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.

Image registry.opengeosys.org/ogs/ogs/ogs-serial-jupyter 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
  • ogstools — OGS-related helper scripts, e.g. msh2vtu: Gmsh to VTU conversion
  • h5py — HDF5 IO
  • MFront python bindings – Material model manipulation
  • Matplotlib — Plotting
  • NumPy — Scientific computing
  • pandas — Data analysis
  • SciPy — Scientific computing
  • VTK — Visualization
  • PyVista — Visualization
  • Snakemake — Workflow management
  • meshio — Mesh conversions between many formats. Pulled in via ogstools.
• Jupyter-related tools:
  • nbconvert — Format conversion
  • nbdime — Diffs for notebooks
  • nb2hugo — Notebook to website markdown conversion
• Gmsh — Mesh generator (incl. Python bindings)

Image registry.opengeosys.org/ogs/ogs/ogs-petsc-jupyter additionally contains:

• PETSc-support

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. Use image registry.opengeosys.org/ogs/ogs/ogs-petsc-jupyter for PETSc-support!

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.

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

Browsing notebooks on GitLab

In the file browser on the left-hand side of the Jupyter Lab interface there is a GitLab-tab which allows for browsing and opening notebooks from the ogs/ogs-repository. You can directly modify and execute a notebook, but the notebook is not saved back to GitLab. You can change the browsed repository by typing into the top text field.

If you would like to us this with private repositories you have to supply an access token at container start-up:

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 \
    --GitLabConfig.access_token="< YOUR_ACCESS_TOKEN >"

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) rendering backend ipyvtklink per default. Other backends are currently not supported.

The backend can be set via:

import pyvista as pv

pv.set_jupyter_backend('ipyvtklink') # default
pv.set_jupyter_backend('pythreejs')  # see https://docs.pyvista.org/user-guide/jupyter/pythreejs.html
pv.set_jupyter_backend('static')     # static images