Jupyter Notebooks

Jupyter Notebooks are documents which can contain live (Python) code, equations, visualizations and narrative text and can be used as an intuitive interface for OGS projects. The following video gives an introduction to using OpenGeoSys with Jupyter Notebooks:

Jupyter Notebooks container environments

You can use a pre-defined container environment which currently contains:

The Jupyter Notebook / Lab application
The latest OpenGeoSys application (with MFront support) and tools
A set of Python packages:
- ogs6py — OGS model manipulation
- VTUInterface — VTU / PVD IO
- h5py — HDF5 IO
- MFront python bindings – Material model manipulation
- matplotlib — Plotting
- numpy — Scientific computing
- pandas — Data analysis
- scipy — Scientific computing
- vtk — Visualization
- PyVista — Visualization
Jupyter-related tools:
- nbconvert — Format conversion
- nbdime — Diffs for notebooks
- nb2hugo — Notebook to www.opengeosys.org markdown

Usage

With Docker:

docker run --rm -p 8888:8888 -v $PWD:/home/jovyan/work --user `id -u $USER` \
    --group-add users registry.opengeosys.org/ogs/ogs/ogs-serial-jupyter

This mounts your current directory into ~/work inside the container.

Windows notes

The above command only works when you run Docker from within a WSL2 Linux shell!

Install Docker Desktop on Windows, it automatically configures WSL2.
Install a Linux distribution from the Microsoft App Store. We recommend Ubuntu 20.04.
In the Docker Desktop application under Settings / Resources / WSL integration add your Linux distribution.
Open a command prompt in your Linux distribution (At the start menu type the name of the distribution) and run the container.
- If your current working contains spaces write out $PWD, e.g.:
```
... -v /c/Users/My\ Name/working/directory:/home/jovyan/work ...
```

With Singularity:

singularity run docker://registry.opengeosys.org/ogs/ogs/ogs-serial-jupyter

Open the specified URL shown in the command output in your browser, e.g.

http://127.0.0.1:8888/lab?token=xxx

You may have to modify the IP address if this is running on a remote machine.

Adding additional Python packages

In a running container you can install additional Python packages with the Jupyter magic command %pip:

%pip install [package name]

Please note that this is a temporary installation. If you stop the container the environment is destroyed.

Rendering with PyVista

When using PyVista the container uses the (interactive) pythreejs rendering backend per default. If you want to output static images there are a couple of ways to configure the ‘static’ rendering backend:

Globally as an environment variable: PYVISTA_JUPYTER_BACKEND=static. This can be defined when starting the container:
```
docker run ... -e PYVISTA_JUPYTER_BACKEND=static ...
```

Globally as a pyvista setting:

import pyvista as pv
pv.set_jupyter_backend('static')

Locally on each plot:

import pyvista as pv
...
pv.show(jupyter_backend='static')