Authors: Cian Wilson, Cameron Seebeck, Kidus Teshome, Nathan Sime, Peter van Keken
Welcome to the FEniCS Subduction Zone Jupyter Book, an online resource for modeling subduction zones!
This repository was developed by undergraduate interns Kidus Teshome and Cameron Seebeck at the Carnegie Science Earth & Planets Laboratory. It is based on Wilson & van Keken, PEPS, 2023 (II), which is part II of a three part introductory review of the thermal structure of subduction zones by Peter van Keken and Cian Wilson.
Our goal is both to demonstrate how to build kinematic-slab thermal models of subduction zones using the finite element library FEniCSx and to provide an easily accessible and modifiable source of the global suite of subduction zone models as described in Wilson & van Keken, PEPS, 2023 (II) and van Keken & Wilson, PEPS, 2023 (III). For comparison, the original models used in these papers are also available as open-source repositories on github and zenodo.
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.
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.
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.
Binder limits the amount of computational resources available. Extremely high resolution simulations may therefore not be feasible online.
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.
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-szIf 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:releaseThe 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.
`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`.
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:releaseThis 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-rootagain copying and pasting the resulting URL into a web browser to access the notebooks.
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.
Note that we use [pyvista](https://docs.pyvista.org/) for plotting and, on linux machines, this requires [Xvfb](https://x.org/releases/X11R7.7/doc/man/man1/Xvfb.1.xhtml) to be installed on the system.
Installation instructions for FEniCSx are available on the FEniCS project homepage.
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.txtThis can then be activated using
conda activate fenics-szWe recommend disabling threading by setting
export OMP_NUM_THREADS=1before starting jupyter lab with
jupyter labwhich 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 labNote 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.
Remember that linux machines require Xvfb to be installed independently of the above instructions for plotting to work.
This Jupyter Book is based on the FEniCSx Tutorial by Jørgen S. Dokken, which is an excellent resource for learning how to use FEniCS in a similar interactive Jupyter Book.