Overview

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.

Usage

The notebooks in this repository 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

The 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.

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.

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.

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.

`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.

These can also be run in parallel using, e.g.:

  cd notebooks
  mpirun -np <p> python3 <script name>.py

where <p> should be substituted for the number of processes (see note above about computational resources in docker on non-linux operating systems).

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:

UFL
Basix
FFCx
DOLFINx 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.

Acknowledgments

This Jupyter Book is based on the FEniCSx Tutorial by Jørgen S. Dokken.