It is not necessary to install any software on your computer to explore these interactive course notes, however if you do wish to install the tools (and I would encourage it) this document will also guide you through the necessary steps needed to get Jupyter Notebooks running on your own machine. Guides are provided for Windows, Mac and Linux.
If you do not want to install any software but want to interact with the code you can simply copy the GitHub URL of the notebook to Google CoLab (https://colab.research.google.com) and it'll run a copy right there in the browser for you. This should work on any device from desktop to smartphone.
If you just want to read the notes and not worry about any computer code or software aspects of this module then you can use the HTML versions of the notes. These are available on GitHub and can be found via Brightspace. You can happily ignore the rest of this document.
This is a step by step guide to installing the Jupyter notebook software and required tools on Windows 10. This was performed on Windows 10 Pro (1903) with Firefox 68.0.1. This process shouldn't take more than 20 minutes. Since the Windows is, for better or worse, the most common platform this guide will go into the most detail on setting up the required software for the latest Microsoft operating system. If you're running Windows 7 or 8 the guide should also work.
Open your web browser (Firefox, Chrome, Edge etc) and go to python.org and download the latest version of python. (Currently 3.7.4 at time of writing). Be sure to download python 3.x, while python 2.7 is still available it is obsolete and should not be used.
If you're running a 64bit version of Windows (which is very likely the case nowadays) download the 64 bit version. You can find it here: (https://www.python.org/downloads/windows/. Scroll down to the Windows x86-64 executable installer version.
When the installer downloads, run it by double clicking on it.
Be sure to tick the box at the bottom of the setup wizard:
Add Python 3.7 to PATH
(this allows python to be called easily in a command prompt by simply typing python
otherwise you would have to type out the full file path every time)
Open a command prompt by searching from the start menu or by pressing Windows key and x ($\boxplus$-x) and select 'Windows PowerShell' or 'Command Prompt'. I'll use PowerShell here because it is somewhat closer to the UNIX environment I prefer. This type of tool is often called variously, a command line interface, the terminal or a shell. They allow you to control a computer by typing a wide range of text commands, which may seem archaic when you've got a UI you can easily click your way around, but is in fact an extremely efficient and powerful way you to run complex and automated tasks that would take much longer by clicking with a mouse. It also uses less resources leaving more compute power for actual work instead of rendering fancy transparent windows. All of the world's supercomputers operate in this manner for these reasons. As engineers it is good to be exposed to such tools.
Here is a snapshot of a new PowerShell window. At the top you can see some Microsoft legal text and a link to some new tool of theirs.
Ignoring all this we can focus on the prompt itself
PS C:\Users\Kevin
This tells me that the current directory is C:\Users\Kevin
which is my User folder of the Windows installation on my PC. This called a prompt because this is where we are prompted to enter commands. Entering the dir
command for example will result in the contents of this folder (C:\Users\Kevin
) being listed on the screen. It is important to understand that any actions performed in this windows can affect the files in the current directory (directory is just another word for folder). It is just another way of using your computer.
So for example if I could change directory to a folder in Documents using the cd
command
PS C:\Users\Kevin> cd C:\Users\Kevin\Documents\
Notice that the command is cd
followed by a space followed by a file path C:\Users\Kevin\Documents\
. This the typical way things are done. Sometimes you can specify options to modify how the command behaves.
As abovedir
will list the contents of the folder. There are many commands some of which are dangerous. The command del
will permanently delete any file you tell it. It will not be placed in the Recycle Bin, it will be simply be deleted without any ability to recover it. So don't delete your homework!
We will only be using this command line interface to install some software and launch our jupyter notebooks so you shouldn't have to worry about doing anything dangerous here.
PS C:\Users\Kevin\Documents> del homework
Now that your somewhat familiar with the command line interface go ahead and type python
at the prompt.
and then press the enter key. This will open an interactive python session in the PowerShell window. It should look like this:
Python 3.7.4 (tags/v3.7.4:e09359112e, Jul 8 2019, 20:34:20) [MSC v.1916 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>
As you can see python spits out some text such as the version number some suggestions on getting help etc and then displays a new type of prompt >>>
. This is the python prompt and anything you type here must be python code.
Fortunately python is easy and very similar to Matlab so lets try a simple example:
a = 3
b = 4
a + b
pressing return gives:
7
When you're ready we can exit python by typing
exit()
noting the parenthesis. This will close python and return us to the PowerShell prompt
Python comes with a package manager called pip
. This lets you install various packages.
You can think of pip as a sort of App Store and packages as being much like Matlab toolboxes. A package may include libraries of code that allow you to do all kinds of fun things that would otherwise require you to spend months writing yourself. Unlike Matlab these packages are all free!
First lets see if pip is working and is up to date:
python -m pip install --upgrade pip
You'll see some text come up in the PowerShell window and a loading bar as any new version is downloaded.
For example:
Collecting pip
Downloading https://files.pythonhosted.org/packages/62/ca/94d32a6516ed197a491d17d46595ce58a83cbb2fca280414e57cd86b84dc/pip-19.2.1-py2.py3-none-any.whl (1.4MB)
100% |████████████████████████████████| 1.4MB 7.9MB/s
Installing collected packages: pip
Found existing installation: pip 19.0.3
Uninstalling pip-19.0.3:
Successfully uninstalled pip-19.0.3
Successfully installed pip-19.2.1
As you can see we've upgraded from pip 19.0.3 to 19.2.1.
Next we will install jupyter
pip install jupyter
You'll see a lot of different packages being installed as part of the jupyter project, depending on your Internet speed this might take a couple of minutes.
Next we will install scipy
. Scientific Python (scipy
for short) is a bundle of packages that gives python a lot of numerical computing functionality much like Matlab.
pip install scipy
Again you'll see a wall of text and loading bars as packages like numpy
and are installed.
The package numpy
allows us to easily perform numerical calculations on arrays just like Matlab.
The scipy
package allows us to do additional Matlab like things like curve fitting and interpolation.
Now we will install matplotlib
, which, as the name suggests allows us to plot data just like in Matlab.
pip install matplotlib
We can install any additional python packages directly from our Jupyter notebooks as we need them.
Unlike Windows, MacOS and Linux are based on UNIX and are much easier to work with in this context. Installing the required packages can be done easily from the command line in a few minutes. However both these systems (MacOS < 10.15 Catalina) come with python 2.7 already installed for legacy reasons so you need to install python 3.x and call it python3
.
The easiest way to get up and running on MacOS is to install the Homebrew package manager. https://brew.sh/
This requires you to enter a command into a terminal window on your Mac. The terminal, just like PowerShell on Windows, is a command line interface for working with your computer. Unlike the Window, the MacOS and Linux command lines are standardised and share the majority of their functionality. It is very powerful and potentially very dangerous so be careful when using it. If you would like to learn more about the UNIX command line this guide is excellent: http://unixmages.com/wp-content/uploads/2018/12/ufbm.pdf
To open a Terminal window you can search from it from Spotlight or find it in /Applications/Utilities/Terminal.app
.
(while you're here check out the Grapher app, it's very useful!)
Once homebrew is installed according to the latest instructions on https://brew.sh/ you can install the required tools by entering each command below into the terminal and hitting enter each time.
brew install python3
Then you can use python's pip3
to install the required packages.
pip3 install jupyter
pip3 install scipy
pip3 install matplotlib
If you're running a Linux system I'm going to assume you know what you're doing! If you are using an Ubuntu flavoured system the required commands are:
sudo apt-get install python3
sudo apt-get install jupyter
Then you can use pip3
to install the required packages
pip3 install scipy
pip3 install matplotlib
If you're having installation issues just email me or call by my office.
In order to run our notebooks our command prompt has to be in the right directory.
We use the command cd
for this purpose. On my Windows PC notebooks are stored in a folder:
C:\Users\Kevin\UCD\MEEN20010_Jupyter
So to switch the current directory to this one we do the following
cd 'C:\Users\Kevin\UCD\MEEN20010_Jupyter'
taking note of the quotations at the start and end of the path. These are important because you might have a space in on of your folder names and the quotation marks tell PowerShell that they are part of the input path, otherwise it will get confused and return an error. I tend to use underscores instead of spaces for my file and folder names.
For Mac and Linux it's much the same except UNIX like systems use a /
separator instead of a ''.
cd '/Users/kevinnolan/UCD/MEEN20010_Jupyter'
Let's run Jupyter by typing:
jupyter notebook
This will fire up your default web browser and you'll see a bunch of .ipynb files in a list. These are our Jupyter notebooks! Jupyter is based on the iPython notebook format which explains the name.
If you didn't bother to change directory or you made a mistake you can simply browse to the correct directory using this interface.
Double clicking a ipynb file will open them in a new browser tab. On the jupyter home page open notebooks have a green icon or can be viewed from the running tab.
Along the top of an open notebook you will see a familiar looking menu bar.
To safely close a notebook look under the File menu and select Close and halt.
You can also save and checkpoint your notebooks here. Checkpoints are useful backups of your work should you want to go back to an earlier state. 'The Download as...' option is useful for exporting a notebooks as PDF or HTML.
On the left side of the jupyter home page you will see a button called 'new'.
Here you can select a new Python 3 notebook. A notebook is comprised of a series of cells that can contain Text or Python Code.
# This is a code cell.
# Edit the text inside the quotation marks and press `Shift Enter` to run the code
print('I love fluid mechanics!')
I love fluid mechanics!
You can switch a cell from one type to another, split them, merge them etc.
From the documentation: The Jupyter Notebook has two different keyboard input modes.
Edit mode allows you to type code or text into a cell and is indicated by a green cell border.
Command mode binds the keyboard to notebook level commands and is indicated by a blue cell border.
This means when the left edge of a cell is green you can type in the cell. Hitting Esc
changes the edge to blue and this command mode allows you do perform a lot of useful tasks such as adding a new cell. These commands are often single keystrokes, for example pressing D
twice deletes a cell (This and other behaviours are adopted from the UNIX text editor VIM).
Here is a list of commands that you can obtain by pressing Esc
and then pressing H
, there are a lot of them but don't worry we'll just use a few.
Text in Jupyter is written in the Markdown format. Markdown is a superset of HTML written by John Gruber and Aaron Swartz. Markdown is an extremely syntax to to learn. It is designed to allow one "to write using an easy-to-read and easy-to-write plain text format, optionally convert it to structurally valid XHTML (or HTML)". This means that the code version of Markdown looks as clean and readable as the HTML version.
For example I can make a series of bullet points as follows
- Bananas
- Apples
- Oranges
- Grapes
which gets rendered as:
Double clicking a text cell opens it in edit mode and reveals all the simple markdown code.
In Jupyter we also use a tool called MathJax
to render equations based on the LaTeX
document preparation system.
LaTeX is a popular tool for writing research papers because it lets us generate elegant documents with beautiful equations. This means that it is easy to insert equations in to a Jupyter notebook inline by wrapping them in dollar signs like $F = ma$
which renders as $F = ma$ or as as display equation using this syntax:
\begin{equation*}
e^{i \pi} + 1 = 0
\end{equation*}
\begin{equation*}
e^{i \pi} + 1 = 0
\end{equation*}Notice that the code for the equation is as readable as the rendered result. This is the great advantage of this approach. The result of all this is that these notes become a living breathing document that are constantly updated. You can maintain your own copy which you update and edit to suit your own learning. Hopefully you find the format useful and use it in other modules to organise your work.
You may find this guide on Markdown for Jupyter maintained by IBM useful: https://www.ibm.com/support/knowledgecenter/SSQNUZ_current/com.ibm.icpdata.doc/dsx/markd-jupyter.html
Once you've saved and closed all your notebooks go back to the Jupyter home page and select quit on the top right. Go back to the command line and use the shortcut Ctrl-c
two times or until you're returned to your system prompt.
If you want you can install a host of jupyter extensions. These include things like spell checkers etc.
Shut down your Jupyter server and run these commands from the command line and relauch jupyter.
pip install jupyter_contrib_nbextensions
jupyter contrib nbextension install
This will add a new Nbextensions
tab at the top of the Jupyter home page.