{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Jupyter Notebook Setup Guide for MEEN20010\n", "\n", "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.\n", "\n", "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.\n", "\n", "## Minimal approach\n", "\n", "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." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Windows 10\n", "\n", "This is a step by step guide to installing the Jupyter notebook software and required tools on Windows 10.\n", "This was performed on Windows 10 Pro (1903) with Firefox 68.0.1. **This process shouldn't take more than 20 minutes.**\n", "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.\n", "\n", "### Install python 3.x\n", "\n", "Open your web browser (Firefox, Chrome, Edge etc) and go to python.org and download the latest version of python.\n", "(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.**\n", "\n", "**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.\n", "\n", "\"Python.org\"\n", "
Snapshot of the download section of python.org
\n", "\n", "When the installer downloads, run it by double clicking on it. \n", "Be sure to tick the box at the bottom of the setup wizard:\n", "**Add Python 3.7 to PATH**\n", "(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)\n", "\n", "\"python\n", "
Snapshot of the python 3 install wizard. Don't forget to tick the 'Add Python 3 to PATH box!
\n", "\n", "### A brief aside on the command line interface\n", "\n", "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.\n", "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.\n", "\n", "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. \n", "\n", "\"PowerShell\"\n", "
A newly open PowerShell Window
\n", "\n", "Ignoring all this we can focus on the _prompt_ itself \n", "\n", "```PS C:\\Users\\Kevin```\n", "\n", "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. \n", "\n", "So for example if I could change directory to a folder in Documents using the `cd` command \n", "\n", "```\n", "PS C:\\Users\\Kevin> cd C:\\Users\\Kevin\\Documents\\\n", "```\n", "\n", "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.\n", "As above`dir` 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!\n", "\n", "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.\n", "\n", "```\n", "PS C:\\Users\\Kevin\\Documents> del homework\n", "```\n", "\n", "### Testing your python installation\n", "\n", "Now that your somewhat familiar with the command line interface go ahead and type `python` at the prompt.\n", "and then press the enter key. This will open an interactive python session in the PowerShell window. It should look like this:\n", "\n", "```\n", "Python 3.7.4 (tags/v3.7.4:e09359112e, Jul 8 2019, 20:34:20) [MSC v.1916 64 bit (AMD64)] on win32\n", "Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n", ">>>\n", "```\n", "\n", "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.\n", "Fortunately python is easy and very similar to _Matlab_ so lets try a simple example:\n", "\n", "```\n", "a = 3\n", "b = 4\n", "a + b\n", "\n", "```\n", "pressing return gives:\n", "```\n", "7\n", "```\n", "\n", "When you're ready we can exit python by typing\n", "\n", "```\n", "exit()\n", "```\n", "\n", "noting the parenthesis. This will close python and return us to the PowerShell prompt" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Installing jupyter and other packages\n", "\n", "Python comes with a package manager called `pip`. This lets you install various packages.\n", "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!\n", "\n", "First lets see if pip is working and is up to date:\n", "```\n", "python -m pip install --upgrade pip\n", "```\n", "\n", "You'll see some text come up in the PowerShell window and a loading bar as any new version is downloaded.\n", "\n", "For example:\n", "```\n", "Collecting pip\n", " Downloading https://files.pythonhosted.org/packages/62/ca/94d32a6516ed197a491d17d46595ce58a83cbb2fca280414e57cd86b84dc/pip-19.2.1-py2.py3-none-any.whl (1.4MB)\n", " 100% |████████████████████████████████| 1.4MB 7.9MB/s\n", "Installing collected packages: pip\n", " Found existing installation: pip 19.0.3\n", " Uninstalling pip-19.0.3:\n", " Successfully uninstalled pip-19.0.3\n", "Successfully installed pip-19.2.1\n", "```\n", "\n", "As you can see we've upgraded from pip 19.0.3 to 19.2.1.\n", "\n", "Next we will install jupyter \n", "\n", "```\n", "pip install jupyter\n", "```\n", "\n", "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.\n", "\n", "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_.\n", "```\n", "pip install scipy\n", "```\n", "Again you'll see a wall of text and loading bars as packages like `numpy` and are installed.\n", "The package `numpy` allows us to easily perform numerical calculations on arrays just like Matlab.\n", "The `scipy` package allows us to do additional _Matlab_ like things like curve fitting and interpolation.\n", "\n", "Now we will install `matplotlib`, which, as the name suggests allows us to plot data just like in Matlab.\n", "```\n", "pip install matplotlib\n", "\n", "```\n", "We can install any additional python packages directly from our Jupyter notebooks as we need them." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## MacOS\n", "\n", "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`.\n", "\n", "The easiest way to get up and running on MacOS is to install the Homebrew package manager.\n", "https://brew.sh/\n", "\n", "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.\n", "It is very powerful and potentially very dangerous so be careful when using it.\n", "If you would like to learn more about the UNIX command line this guide is excellent:\n", "http://unixmages.com/wp-content/uploads/2018/12/ufbm.pdf\n", "\n", "To open a Terminal window you can search from it from Spotlight or find it in `/Applications/Utilities/Terminal.app`.\n", "(while you're here check out the Grapher app, it's very useful!)\n", "\n", "\"Terminal.app\"\n", "\n", "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.\n", "\n", "```\n", "brew install python3\n", "\n", "```\n", "\n", "Then you can use python's `pip3` to install the required packages.\n", "```\n", "pip3 install jupyter\n", "\n", "pip3 install scipy\n", "\n", "pip3 install matplotlib\n", "\n", "```\n", "\n", "## Linux\n", "\n", "If you're running a Linux system I'm going to assume you know what you're doing!\n", "If you are using an Ubuntu flavoured system the required commands are:\n", "\n", "```\n", "sudo apt-get install python3\n", "\n", "sudo apt-get install jupyter\n", "```\n", "Then you can use `pip3` to install the required packages\n", "\n", "```\n", "pip3 install scipy\n", "\n", "pip3 install matplotlib\n", "```\n", "\n", "If you're having installation issues just email me or call by my office." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Working in Jupyter\n", "\n", "## Getting started\n", "In order to run our notebooks our command prompt has to be in the right directory.\n", "We use the command `cd` for this purpose. On my Windows PC notebooks are stored in a folder:\n", "```\n", "C:\\Users\\Kevin\\UCD\\MEEN20010_Jupyter\n", "```\n", "\n", "So to switch the current directory to this one we do the following\n", "\n", "```\n", "cd 'C:\\Users\\Kevin\\UCD\\MEEN20010_Jupyter'\n", "```\n", "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.\n", "\n", "For Mac and Linux it's much the same except UNIX like systems use a `/` separator instead of a '\\'.\n", "```\n", "cd '/Users/kevinnolan/UCD/MEEN20010_Jupyter'\n", "```\n", "\n", "Let's run Jupyter by typing:\n", "```\n", "jupyter notebook\n", "```\n", "This will fire up your default web browser and you'll see a bunch of .ipynb files in a list. \n", "These are our Jupyter notebooks! Jupyter is based on the **iPy**thon **n**ote**b**ook format which explains the name.\n", "\n", "If you didn't bother to change directory or you made a mistake you can simply browse to the correct directory using this interface.\n", "\n", "## Opening and closing notebooks\n", "\n", "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.\n", "\n", "\"jupyter_menu\"\n", "\n", "\n", "Along the top of an open notebook you will see a familiar looking menu bar.\n", "\"jupyter_menu\"\n", "\n", "To safely close a notebook look under the File menu and select Close and halt.\n", "\"Terminal,app\"\n", "\n", "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.\n", "\n", "## Creating and editing notebooks\n", "\n", "On the left side of the jupyter home page you will see a button called 'new'.\n", "\n", "\"jupyter_menu\"\n", "\n", "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. " ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "I love fluid mechanics!\n" ] } ], "source": [ "# This is a code cell. \n", "# Edit the text inside the quotation marks and press `Shift Enter` to run the code\n", "\n", "print('I love fluid mechanics!')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You can switch a cell from one type to another, split them, merge them etc. \n", "\n", "From the documentation: The Jupyter Notebook has two different keyboard input modes. \n", "\n", "**Edit mode** allows you to type code or text into a cell and is indicated by a **green cell border**. \n", "\n", "**Command mode** binds the keyboard to notebook level commands and is indicated by a **blue cell border**.\n", "\n", "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).\n", "\n", "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.\n", "\n", "\"jupyter_menu\"\n", "\n", "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.\n", "\n", "For example I can make a series of bullet points as follows\n", "\n", "```\n", "- Bananas\n", "- Apples\n", "- Oranges\n", "- Grapes\n", "```\n", "which gets rendered as:\n", "\n", "- Bananas\n", "- Apples\n", "- Oranges\n", "- Grapes\n", "\n", "Double clicking a text cell opens it in edit mode and reveals all the simple markdown code.\n", "In Jupyter we also use a tool called `MathJax` to render equations based on the `LaTeX` document preparation system.\n", "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:\n", "```\n", "\\begin{equation*}\n", "e^{i \\pi} + 1 = 0\n", "\\end{equation*}\n", "```\n", "\n", "\\begin{equation*}\n", "e^{i \\pi} + 1 = 0\n", "\\end{equation*}\n", "\n", "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.\n", "\n", "
\n", "Important equations will be rendered in a blue box like this\n", "\\begin{equation*}\n", "e^{i \\pi} + 1 = 0\n", "\\end{equation*}\n", "
\n", "\n", "\n", "You may find this guide on Markdown for Jupyter maintained by IBM useful:\n", "https://www.ibm.com/support/knowledgecenter/SSQNUZ_current/com.ibm.icpdata.doc/dsx/markd-jupyter.html\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Quiting Jupyter\n", "\n", "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.\n", "\n", "## Jupyter Extensions\n", "\n", "If you want you can install a host of jupyter extensions. These include things like spell checkers etc.\n", "\n", "Shut down your Jupyter server and run these commands from the command line and relauch jupyter.\n", "```\n", "pip install jupyter_contrib_nbextensions \n", "jupyter contrib nbextension install \n", "```\n", "\n", "This will add a new `Nbextensions` tab at the top of the Jupyter home page." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.9" } }, "nbformat": 4, "nbformat_minor": 2 }