1. Toolkit Setup#

1.1. Tools we will rely on#

  • Python 3

    … clear and powerful object-oriented programming language, comparable to Perl, Ruby, Scheme, or Java.

    Python has (relatively) simple and elegant syntax, is free and open-sourse and (relatively) easy to debug (due to being an interpreted programming language).

    Python is largely popular but still, it cannot compete in performance with compiled, statically typed programming languages, such as C++ or Fortran, when addressing certain tasks. Nevertheless, it is been widely used by C++ developers for prototyping.

  • Anaconda

    … free, easy-to-install package manager, environment manager, and Python distribution with a collection of 1,500+ open source packages with free community support.

    Anaconda has been very useful for Python developers. First of all, it comes with a distribution of Python 3 and allows you an easy switch between its versions. Second, by installing Anaconda you get a package manager called conda. Using conda you can install most Python packages with a simple one-liner command.

  • Git

    … is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.

    Git is used by developers to easily track and share their work. Whenever you introduce changes to your project they are tracked by git, and you can revert to any previous state at any moment. Moreover, you can create “branches” - different versions of your project at the same time. Branches are commonly used, so that multiple people can work on the same files at the same time. Besides, usage of branches allows you to keep the main workflow clean by storing your work in progress separately until you’re sure it can be merged into the project.

    In this course we use Git to maintain the repository with the course notes. You will mostly use Git to stay synchronized with the state of the repo. Nevertheless, we encourage you to learn the basic usage of Git to work with your own projects, as it would be an extremely useful skill for you to acquire.

1.2. Installation#

In this course you are expected to run basic commands via ‘the command line’. In case you don’t know how to open a command prompt, read how to do this on MacOS, Linux or Windows.

1.2.1. Install Git#

  • MacOS

    If you are running 10.9 Mavericks or a later version of MacOS, launch the command line and run:

    git --version

    It will start the installation of Git.

    If you are running an earlier version of MacOS, please visit official website for instructions.

  • Windows

    Download Git from the official website and install it via graphical installer.

  • Linux

    Open command line and run:

    apt-get install git

To check that Git was properly installed and its version, run from the command line:

git --version

In case you are interested in learning more about git, here is some further reading:

1.2.2. Get the course notes#

The material of this course is available online and can be alternatively accessed on GitHub or on a dedicated webpage. The second option is recommended for an easy navigation through the different chapters. However, the content is static and not suited to experiment with the various concepts we discuss. For that purpose, each chapter of the course is also distributed as a collection of Jupyter notebooks on GitHub.

The Jupyter Notebook is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations and narrative text.

In a Jupyter Notebook coding is easy and interactive. In a single file you can combine Markdown cells and code cells.

You should download the course notes on your computer by following these few steps:

  1. Create your GitHub account in case you don’t have one.

  2. Go to the GitHub page of the course.

  3. Click the green “Code” button and copy the HTTP address of this repository.

../../../_images/code_copy.png

  1. Open the command line.

  2. Optional: if you want the course notes to reside at a specific location on your computer, change the directory first.

  3. Run from the command line:

     git clone https://github.com/aquaULB/solving_pde_mooc.git

    You will be asked to enter your GitHub credentials.

A directory named solving_pde_mooc will be created in your current folder. Locally, you’ll have access to all of the content that is available on GitHub.

Note that git clone does much more than just copies the files in their current state. It in fact does what it says - clones, creates exact duplicate of the remote repository (that on GitHub). It means that you will have full access to all of the changes that will appear on GitHub. We will guide you through how to download those changes further in the course.

1.2.3. Install Anaconda (or Miniconda)#

In this course we ask you to install Anaconda (or Miniconda) and provide you with a recipe to install all the required packages in one click.

Note that in case you are working on a ULB computer, Anaconda is already installed and you can immediately proceed to the next step.

Both Anaconda and Miniconda come with the latest stable release of Python and the conda package manager - this is all you need to proceed to setting up your work environment.

  • Install Anaconda if you do not mind dedicating several GB of your disk space to the installation, do not mind installing a large set of Python packages at once and want to have access to a graphical interface to launch applications and manage conda environments.

    To install Anaconda we refer you to the Anaconda website.

  • Install Miniconda if you are tight on disk space, if you don’t need access to a graphical interface to manage your environments or if you prefer to only install only the Python packages that you actually need.

    For the Miniconda installation, we refer you to the official installation guide.

1.2.4. Setup an environment#

You will now be quided through the setup of the working environment that you’ll use throughout this course. To isolate it from your other projects that you might use Anaconda for, we’ll use a conda environment -

… a directory that contains a specific collection of conda packages that you have installed… If you change one environment, your other environments are not affected. You can easily activate or deactivate environments, which is how you switch between them.

Open the command line and make sure you are “located” in the root directory of the course (path/to/the/course/directory/solving_pde_mooc). Run the following command:

conda env create -f environment.yml

This will create a conda environment named “course” and launch the installation of multiple packages. This step only has to be done once. After that, you may activate this specific environment by typing in any terminal window,

conda activate course

You might run into the following error:

CommandNotFoundError: Your shell has not been properly configured to use 'conda activate'.

Normally, the Anaconda (or Miniconda) installer should update your shell scripts to initialize conda but if it didn’t, as stated in the error message, you’ll have to do it manually. Run

conda init

and then restart you command line application. Now conda activate command should be recognized.

At any time you can deactivate the environment by typing:

conda deactivate

This will switch you back to the base Anaconda environment but you can return to the “course” environment by activating it again.

For Windows users: In some cases, the Jupyter notebook extensions we use are not properly installed automatically when the environment is created. To finish their installation you should type the following commands in a terminal window:

1) conda activate course (only needed if the course environment is not yet activated in the terminal)
2) jupyter contrib nbextension install --user
3) jupyter nbextension enable varInspector/main

These extra steps have to be performed only once to get a functional installation.

1.3. Working with Jupyter Notebook#

We recommend that you use Jupyter notebooks to work with the course material, as it includes sample codes along with the relevant explanations.

Before trying to view the course notebooks in a Jupyter Notebook window, activate the conda environment course , as the notebooks rely on some of the newly installed packages. Launch the Jupyter Notebook application by running within a terminal window the following command from the solving_pde_mooc/notebooks folder:

jupyter notebook

The course’s notebooks require some Jupyter Notebook extensions to display properly. In the extension menu check out the following boxes:

../../../_images/jupextensions.png

We think that the course notebooks are best displayed using a custom HTML theme. To activate it, you must execute the last cell of each notebook after opening them:

This will immediately apply the preconfigured styling.

1.4. Summary#

In this notebook, you’ve learnt how to set up your work environment for this course. You are now ready to dive into the main subject of the course and learn how to construct numerical solutions of partial differential equations.

from IPython.core.display import HTML
css_file = '../styles/notebookstyle.css'
HTML(open(css_file, 'r').read())