Jupyter Notebook Setup Guide for MEEN20010

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.

Minimal approach

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 PDF and 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.

Windows 10

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.

Install python 3.x

Open your web browser (Firefox, Chrome, Edge etc) and go to python.org and download the latest version of python. (Currently 3.7.4). 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.

Python.org

Snapshot of the download section of python.org

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)

python install wizard

Snapshot of the python 3 install wizard. Don't forget to tick the 'Add Python 3 to PATH box!

A brief aside on the command line interface

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.

PowerShell

A newly open PowerShell Window

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

Testing your python installation

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

Installing jupyter and other packages

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

Next lets install a package that lets us view 3D models in our notebooks:

pip install pyGEL3D

We can install any additional python packages directly from our Jupyter notebooks as we need them.

Installing FFmgeg

Finally for now we need to install FFmpeg, a free open source tool that is used to encode some of videos generated in these notebooks. This is a little more advanced so pay close attention to these steps!

Open your web browser again and go to ffmpeg.org and click download and then the link to Windows builds.

Downloaded the statically linked 64bit version (4.1.4 at time of writing) as a zip file to your Downloads folder. Open your downloads folder in Explorer Unzip the ffmpeg-xxxxxxxx-xxxxxxx-win64-static.zip file and copy it somewhere like the root directory of your C:\ drive. I also renamed the folder to ffmpeg so it won't look cluttered.

ffmpeg

The location of the ffmpeg folder in my C:\ root directory

Here are the contents of the ffmpeg folder. ffmpeg

The ffmpeg folder's contents as downloaded

When we installed python we ticked a box to add python to the computer's PATH. This is a list of folders where Windows looks for programs when asked to run a command. If we didn't set this properly we would have to type out the entire file path every time which would be tedious. Unfortunately FFmpeg does not come with a fancy installer so we will have to set the path to it manually.

Press the Windows key + r ($\boxplus$-r) to open the Run dialog. Enter SystemPropertiesAdvanced and press enter.

Run!

This will open the following window. Click on 'Environment Variables...' at the bottom.

Here be dragons!

The next window looks like this:

Here be dragons!

Notice how python 3.x is already there in the user variables. We are going to add FFmpeg to the System variables so that it can be used system wide.

Look for Path under system variables in the bottom panel and highlight it by left clicking on it. Then click Edit... Add C:\ffmpeg\bin to the list and click OK and OK again to close the previous window.

Here be dragons! You should close and reopen your PowerShell window for this change to take effect.

So now instead of having to type C:\ffmpeg\bin\ffmpeg every time we want to use FFmpeg, we just have to type ffmpeg. But more importantly jupyter can now find it easily which is the whole purpose of this exercise.

MacOS

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!)

Terminal.app

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

brew install ffmpeg

Then you can use python's pip3 to install the required packages.

pip3 install jupyter

pip3 install scipy

pip3 install matplotlib

pip3 install pyGEL3D

Linux

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 ffmpeg

sudo apt-get install jupyter

Then you can use pip3 to install the required packages

pip3 install scipy

pip3 install matplotlib

pip3 install pyGEL3D

If you're having installation issues just email me or call by my office.

Working in Jupyter

Getting started

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.

Opening and closing notebooks

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.

jupyter_menu

Along the top of an open notebook you will see a familiar looking menu bar. jupyter_menu

To safely close a notebook look under the File menu and select Close and halt. Terminal,app

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.

Creating and editing notebooks

On the left side of the jupyter home page you will see a button called 'new'.

jupyter_menu

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.

In [2]:
# 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.

jupyter_menu

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:

  • Bananas
  • Apples
  • Oranges
  • Grapes

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.

Important equations will be rendered in a blue box like this \begin{equation*} e^{i \pi} + 1 = 0 \end{equation*}

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

Quiting Jupyter

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.

Jupyter Extensions

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.