Usage#
Author: Cian Wilson
The easiest way to read this Jupyter Book is on the FEniCS-SZ website however all the pages of the book can also be run interactively in a web browser from any jupyter server with the appropriate software packages installed. Below we start by providing instructions for running the notebooks through docker, a containerized software environment, for which we supply pre-built container images. These can be most easily run online (but with limited computational resources) through binder or locally on any machine with docker installed. In addition we provide some guidelines for installing the necessary software packages on any jupyter server using conda.
Online Binder#
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 while it downloads and starts the docker image.
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 Docker#
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 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 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 can be useful, for example to install extra packages in the docker container through the terminal.
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.
Local Installation#
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.
Xvfb
Note that we use pyvista for plotting and, on linux machines, this requires Xvfb to be installed on the system.
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.9.0 based on GIT commit: a1bd6f697e1784c7001caf9ebb32673b1fb22412 of https://github.com/FEniCS/dolfinx/
Conda#
Aside from using the recommended method through docker, conda provides the easiest way of installing the necessary software packages. Below we provide some guidance on setting up a conda environment for running the notebooks.
Assuming a working conda installation, we provide a docker/requirements.txt file that can be used to install a conda environment matching the docker installation
conda create -n fenics-sz python=3.12.3 -c conda-forge --file docker/requirements.txt
This can then be activated using
conda activate fenics-sz
We recommend disabling threading by setting
export OMP_NUM_THREADS=1
before starting jupyter lab with
jupyter lab
which will display a URL to copy and paste to the web browser if it doesn’t automatically open.
docker/requirements.txt contains the strictest list of version requirements to match the docker installation. This sometimes causes conda to fail to resolve the dependencies so we provide an alternative docker/requirements_min.txt file that contains less stringent version restrictions and can be installed and started using
conda create -n fenics-sz-min python=3.12.3 -c conda-forge --file docker/requirements_min.txt
conda activate fenics-sz-min
export OMP_NUM_THREADS=1
jupyter lab
Note that as this doesn’t guarantee the same software versions as used in our docker environment, some changes may occur between the published website output and output produced using this conda environment.
Xvfb
Remember that linux machines require Xvfb to be installed independently of the above instructions for plotting to work.
With a working software environment available, either locally or online through binder, we next discuss some background tutorial problems that motivate our final application. Those already familiar with the finite element method should skip ahead to our implementation of subduction zone problems or to the global suite of subduction zone models.