This page describes how to run OGS with the help of a Linux container (for users) with Apptainer, formerly Singularity.
On the EVE cluster system (UFZ) you can use prebuilt images which can be used for PETSc-based cluster jobs.
Simply download an image from the releases page.
Simply download an image from the latest master-branch build:
# Linux only:
apptainer exec ogs-6.x.x-serial.squashfs ogs some/path/project.prj
This starts the container, mounts your home directory inside the container, passes the current working directory and runs the ogs
executable (in your home directory which is mounted inside the container) with the passed project file. When using
containers, everything stays transparent to the user. When OGS finishes the container stops and returns to the host system.
You can also specify the full executable path in the container:
# Works on macOS too:
apptainer exec ogs-6.x.x-serial.squashfs /usr/local/ogs/bin/ogs ...
Running a benchmark:
# Create output directories
mkdir -p _out _out_mpi
# Run serial benchmark
apptainer exec ogs-6.x.x-serial.squashfs ogs -o _out [ogs-sources]/Tests/Data/Mechanics/Linear/disc_with_hole.prj
# Run serial benchmark with output validation (via vtkdiff)
apptainer exec ogs-6.x.x-serial.squashfs ogs -o _out -r [ogs-sources]/Tests/Data/Mechanics/Linear [ogs-sources]/Tests/Data/Mechanics/Linear/disc_with_hole.prj
# Run parallel benchmark with MPI
mpirun -np 4 apptainer ogs ogs-6.x.x-openmpi-2.1.2.squashfs ogs -o _out_mpi [ogs-sources]/Tests/Data/Mechanics/Linear/disc_with_hole.prj
You can run other contained executables as well, e.g. vtkdiff
:
apptainer exec ogs-6.x.x-serial.squashfs vtkdiff --help
You can interactively explore the container with apptainer shell
(you can see that you are in the container because of the Apptainer>
prefix of the shell):
# Shell into container
apptainer shell ogs-6.x.x-serial.squashfs
# List binaries in the container
Apptainer> ls $PATH
... ogs vtkdiff
# Exit the container and get back to your hosts shell
Apptainer> exit
For certain benchmarks or tutorials you may need additional Python packages. You can create a Python virtual environment inside the container (stored on your host) and install packages via pip
(inside the container):
mkdir my-working-directory && cd my-working-directory
apptainer shell my-container.squashfs
# Now in the container
virtualenv .venv
source .venv/bin/activate
pip install numpy # or whatever you need
# run ogs
exit
# Now outside the container
# The virtualenv-directory .venv still persists
# If you want to run something in the container with exec, source the venv before:
apptainer exec my-container.squashfs bash -c 'source .venv/bin/activate && ogs ...'
This article was written by Lars Bilke. If you are missing something or you find an error please let us know.
Generated with Hugo 0.147.9
in CI job 577984
|
Last revision: June 16, 2025
Commit: [web] rm singularity for developer page. 4e47e2f3
| Edit this page on