Usage#
Author: Cian Wilson
The notebooks in this Jupyter Book can all be run interactively in a web browser, either online or locally. In addition we provide versions of most notebooks as python scripts that can be run locally from a terminal.
Online#
This website is published as a Jupyter Book. Each page is a Jupyter notebook that can be run interactively in the browser. To start such an interactive session using binder click the 
-symbol in the top right corner of the relevant page. Note that binder may take some time to start.
Interactive Changes
Binder allows users to run notebooks interactively, making changes to the published Jupyter Book. Note that these changes will be lost once the binder session ends unless the changed files are manually downloaded by selecting them in the Jupyter lab file browser and downloading them to the local machine.
Computational Costs
Binder limits the amount of computational resources available. Extremely high resolution simulations may therefore not be feasible online.
Local#
To run the notebooks locally, outside of binder, an installation of the FEniCSx is required. We strongly recommend new users do this using Docker.
Docker#
Docker is software that uses images and containers to supply virtualized installations of software across different kinds of operating systems (Linux, Mac, Windows). The first step is to install docker, following the instructions at their webpage.
Once docker is installed we provide compatible docker images using github packages.
Computational Resources
On non-linux operating systems docker limits the computational resources available to the virtualized docker container, which may limit the size of simulations it is possible to run locally. Modify the docker settings to change these settings and make more resources available.
To use these images with this book on a local machine, first (using a terminal) clone the repository and change into that directory
git clone -b release https://github.com/cianwilson/fenics-sz.git
cd fenics-sz
Browser#
If running the book in a browser then run the following docker command
docker run --init --rm -p 8888:8888 --workdir /root/shared -v "$(pwd)":/root/shared ghcr.io/cianwilson/fenics-sz:release
The first time this is run it will automatically download the docker image and start Jupyter lab in the docker container on the local machine. To view the notebooks and modify them locally, copy and paste the URL printed in the terminal into a web-browser.
Updates
docker run will only download the docker image the first time it is called. To get updates to the images run
docker pull ghcr.io/cianwilson/fenics-sz:release
before calling docker run.
Terminal#
Alternatively, the image can be used through an interactive terminal by running
docker run -it --rm -p 8888:8888 --workdir /root/shared -v "$(pwd)":/root/shared --entrypoint="/bin/bash" ghcr.io/cianwilson/fenics-sz:release
This allows the python scripts based on the notebooks to be run, e.g.
cd notebooks
python3 <script name>.py
where <script name>.py should be substituted for the desired python script.
Jupyter lab can also be started from within the docker container
jupyter lab --ip 0.0.0.0 --port 8888 --no-browser --allow-root
again copying and pasting the resulting URL into a web browser to access the notebooks.
Install#
If not using docker a local installation of FEniCSx is necessary, including all of its components
along with other dependencies, which can be seen in the files docker/pyproject.toml and docker/Dockerfile.
Installation instructions for FEniCSx are available on the FEniCS project homepage.
This Jupyter book was built with and is known to be compatible with
import dolfinx
print(f"DOLFINx version: {dolfinx.__version__} based on GIT commit: {dolfinx.git_commit_hash} of https://github.com/FEniCS/dolfinx/")
DOLFINx version: 0.8.0 based on GIT commit: 5a20e2ba3907c1f108cb0af45931f46e32250351 of https://github.com/FEniCS/dolfinx/
Acknowledgments#
This Jupyter Book is based on the FEniCSx Tutorial by Jørgen S. Dokken.