Usage

Usage#

There are two ways to use FEniCS-SZ:

non-interactively by reading the FEniCS-SZ website
interactively in a web browser from any jupyter server with the appropriate software packages installed

1. Website#

To use the website non-interactively please open https://cianwilson.github.io/fenics-sz in a web browser and use the panel on the left-hand side to navigate the contents. Each page corresponds to a jupyter notebook, converted to html in a jupyter book.

2. Jupyter#

FEniCS-SZ is a jupyter book made up of a set of jupyter notebook (.ipynb) files, each one of which can be run interactively in a web browser on a jupyter server. On the website these are converted into html webpages. When viewing through a jupyter server these are contained in the notebooks directory of the repository that will be visible in the left hand file directory. Files are numbered corresponding to the order in which they appear on the website to make navigation as easy as possible.

Once opened the notebooks are made up of cells that can contain annotations in a markdown format or executable python code. Files will typically open with the first cell highlighted. To run that cell click the play button at the top of the frame and the highlighted cell will progress to the next cell. A useful keyboard shortcut for this is Shift + Enter. Repeatedly click play or Shift + Enter to progress through the notebook.

Not all cells will produce output (e.g., markdown cells won’t) but python cells that do will show their results inline below the cell. Python cells performing a lot of calculations will take some time to run and may temporarily stall progression to the next cell. Once a cell has finished executing it will display any output and progress the active cell down the page.

Many excellent tutorials for jupyter exist (e.g. for jupyter lab). If you’re new to interacting with jupyter notebooks we recommend checking some of them out.

Here we discuss how to launch jupyter using

[fastest but limited resources] binder, an online interactive jupyter server
[fast, requires a local docker installation] docker, a containerized software environment
[fast, sometimes compatibility issues] conda, a python package manager
[complicated, developers only] an installation from source

2.1 Online Binder#

Starting on the website, navigate to whichever page you want to run interactively, then simply click the Binder symbol -symbol in the top right corner of the page. This will launch an online interactive jupyter session using binder and a containerized docker development environment for FEniCS-SZ. Note that binder may take some time to start while it downloads and starts the docker image.

Any page can be opened this way but once a binder session is running it will likely be easier to navigate the pages from within the jupyter session using the left hand file directory rather than returning to the FEniCS-SZ website and repeatedly opening new binder sessions.

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 file browser and downloading them to the local machine.

Computational Costs

Binder limits the amount of computational resources available. High resolution simulations may therefore not be feasible online.

If this method works and provides sufficient computational resources to explore the notebooks then there’s no need to read any further! The instructions after this refer to running FEniCS-SZ on a local machine rather than online.

2.2 Local Docker#

To run the notebooks locally, outside of binder, an installation of FEniCSx is required. We strongly recommend new users do this using a local installation of docker and our pre-packaged docker development image.

Docker is software that uses images and containers to supply virtualized installations of software across different kinds of operating systems (Linux, Mac, Windows). Start by making sure a working installation of docker is available, following the instructions on their webpage.

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 make more resources available.

Once docker is installed we provide compatible docker images using github packages. To use these images on a local machine open a terminal window, navigate to an appropriate location on the file system, and use git to clone the FEniCS-SZ repository into that directory

  git clone -b release https://github.com/cianwilson/fenics-sz.git
  cd fenics-sz

After this step there are two options for launching the FEniCS-SZ development container:

[likely for most users] automatically starting the jupyter server and opening it in a browser
[useful for developers] starting the container in a terminal and then manually launching the jupyter server
[also primarily for developers] starting a development container in an integrated development environment (IDE)

2.2.1 Browser#

To start the jupyter server automatically 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 in the docker container on the local machine. To view and interact with the notebooks, copy and paste the URL printed in the terminal into a web browser. Look for output similar to, e.g.:

    To access the server, open this file in a browser:
        file:///root/.local/share/jupyter/runtime/jpserver-6-open.html
    Or copy and paste one of these URLs:
        http://e7ba9ed551e1:8888/lab?token=35522c8f002cc75803ccd1f5764a6e480e5dd8569d8f82bf
        http://127.0.0.1:8888/lab?token=35522c8f002cc75803ccd1f5764a6e480e5dd8569d8f82bf

and copy the full URL starting with http://127.0.0.1:8888 into a browser window.

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.

If this method works and provides sufficient access to the repository and its notebooks then there’s no need to read any further! The instructions after this refer to running FEniCS-SZ while maintaining terminal access.

2.2.2 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. Again, the first time this is run, it will automatically download the docker image on the local machine. To get any subsequent updates it is necessary to run docker pull (see above).

Jupyter can then be started from within the terminal running the docker container using

  jupyter lab --ip 0.0.0.0 --port 8888 --no-browser --allow-root

and again copying and pasting the resulting URL into a web browser to access the notebooks. Look for output similar to, e.g.:

    To access the server, open this file in a browser:
        file:///root/.local/share/jupyter/runtime/jpserver-6-open.html
    Or copy and paste one of these URLs:
        http://e7ba9ed551e1:8888/lab?token=35522c8f002cc75803ccd1f5764a6e480e5dd8569d8f82bf
        http://127.0.0.1:8888/lab?token=35522c8f002cc75803ccd1f5764a6e480e5dd8569d8f82bf

and copy the full URL starting with http://127.0.0.1:8888 into a browser window.

Alternatively, to run notebooks non-interactively from the terminal navigate to the desired notebook and run

  jupyter execute <notebook name>.ipynb

replacing <notbook name>.ipynb with the filename of the notebook.

If this method works and provides sufficient access to the repository and its notebooks then there’s no need to read any further! The instructions immediately after this refer to running FEniCS-SZ in an integrated development environment.

2.2.3 IDE#

Some integrated development environments (IDEs), e.g. Visual Studio Code (VSCode), support development containers that can load a docker image and run jupyter notebooks inside the container from within the IDE (no browser required). .devcontainer/devcontainer.json describes a development container for FEniCS-SZ that has been used and tested in VSCode. Simply select the option to “Reopen in container” after opening the clone of the repository in the IDE. When first running a notebook select the dolfinx-env python environment if prompted.

If this method works and provides sufficient access to the repository and its notebooks then there’s no need to read any further! The instructions immediately after this refer to installing the dependencies of FEniCS-SZ using conda.

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

Xvfb

Note that we use pyvista for plotting and, on linux machines, this requires Xvfb to be installed on the system.

Assuming a working conda installation, we provide a conda/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 conda/requirements.txt

This can then be activated using

  conda activate fenics-sz

We recommend disabling threading by setting (only required once per environment)

  conda env config vars set OMP_NUM_THREADS=1
  conda deactivate fenics-sz
  conda activate fenics-sz

before starting jupyter lab with

  jupyter lab

which will display a URL to copy and paste to the web browser (as above) if it doesn’t automatically open.

conda/requirements.txt contains the strictest list of version requirements to match the docker installation. This sometimes causes conda to fail to resolve package dependencies so we provide an alternative conda/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 conda/requirements_min.txt
  conda activate fenics-sz-min
  conda env config vars set OMP_NUM_THREADS=1
  conda deactivate fenics-sz
  conda activate fenics-sz
  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 the output produced using this conda environment.

If this method works and provides sufficient access to the repository and its notebooks then there’s no need to read any further! The instructions immediately after this refer to installing the dependencies of FEniCS-SZ from source.

2.4 Source Installation#

If not using docker or conda, a local installation of FEniCSx and its dependencies is necessary, including all of its components

along with other dependencies, which can be seen in the files docker/pyproject.toml and docker/Dockerfile.