OpenGeoSys

OpenGeoSys

OpenGeoSys (OGS) is a scientific open source project for the development of numerical methods for the simulation of thermo-hydro-mechanical-chemical (THMC) processes in porous and fractured media. Current version is OpenGeoSys-6 which is documented on this page. For information about OpenGeoSys-5, see its dedicated section. OGS has been successfully applied in the fields of regional, contaminant and coastal hydrology, fundamental and geothermal energy systems, geotechnical engineering, energy storage, CO2 sequestration/storage and nuclear waste management and disposal.

For more information: https://www.opengeosys.org/

Running OpenGeoSys on Comet

OpenGeoSys installs a lot of Python modules and dependencies which may conflict with system-installed packages or those you may already have. Rather than ask everyone to install their own OGS environment we have installed OGS on Comet as a container image.

The OGS container is stored in the /nobackup/shared/containers directory and is accessible to all users of Comet. You do not need to take a copy of the container file; it should be left in its original location.

You can find the container files here:

/nobackup/shared/containers/ogs.2025.03.sif

We normally recommend using the latest version of the container, in the case of OGS, the version numbers represent the date the container was created.

Container Image Versions

We may reference a specific container file, such as ogs.2026.03.sif, but you should always check whether this is the most recent version of the container available. Simply ls the /nobackup/shared/containers directory and you will be able to see if there are any newer versions listed.

We have provided a convenience script that will automate all of steps needed to run applications inside the container, pass through runtime folders, as well as access your $HOME, /scratch and /nobackup directories to just two simple commands.

/nobackup/shared/containers/ogs.2026.03.sh

There is a corresponding .sh script for each version of the container image we make available.

Just source this file and it will take care of loading apptainer, setting up your bind directories and calling the exec command for you - and give you a single command called container.run (instead of the really long apptainer exec command) to then run anything you want inside the container, for example - to run the main ogs command:

$ source /nobackup/shared/containers/ogs.2026.03.sh
$ container.run ogs -h
 info: Parsing the OGS commandline ...

USAGE: 

   ogs  [-h] [--config-warnings-nonfatal] [--enable-fpe] [--log-parallel]
        [--unbuffered-std-out] [--version] [--write-prj] [-l <none|error|
        warn|info|debug|all>] [-m <MESH_DIR_PATH>] [-o <OUTPUT_PATH>] [-p
        <XML_PATCH_FILE> ...] [-r <REF_PATH>] [-s <SCRIPT_DIR_PATH>]
        project-file
$

OGS

You can run the ogs command by using the container.run helper we provide. This can be used interactively, or in your sbatch jobs.

$ source /nobackup/shared/containers/ogs.2026.03.sh
$ container.run ogs -h
info: Parsing the OGS commandline ...

USAGE: 

   ogs  [-h] [--config-warnings-nonfatal] [--enable-fpe] [--log-parallel]
        [--unbuffered-std-out] [--version] [--write-prj] [-l <none|error|
        warn|info|debug|all>] [-m <MESH_DIR_PATH>] [-o <OUTPUT_PATH>] [-p
        <XML_PATCH_FILE> ...] [-r <REF_PATH>] [-s <SCRIPT_DIR_PATH>]
        project-file
...
$

More information on ogs options: https://www.opengeosys.org/6.5.7/docs/userguide/basics/cli-arguments/

OGS Example Jupyter Notebook

To follow the the “OGS 5 minute run” example, we have provided a guide which you can follow by starting a Linux X11 Desktop session from our Open OnDemand service.

Start the Linux Desktop session
Find the Terminal icon
Open the Terminal application

In the terminal window run the following:

$ source /nobackup/shared/containers/ogs.2026.03.sh
$ container.run ogs-lab-example

Within a few seconds the Jupyter Lab server will start and then automatically launch Firefox installed inside the container. It will load to the 5 minute OGS example as below:

To exit, close Firefox, then either Control+C in the Terminal window, or close it. If finished with the Linux Desktop session, then use the “Applications” menu to exit and log out.

You can use any of the interactive partitions to launch the OGS Jupyter Lab interface - you do not need the GPU-specific nodes, as OGS does not have any intensive GPU requirements.

See: https://www.opengeosys.org/6.5.7/docs/userguide/basics/5-mins-ogs/

OGS new or custom Jupyter Notebooks

There are many examples on the OSGTools website - the guide below shows how to get started creating a new Jupyter notebook from scratch, for your own projects. First start a Linux X11 Desktop session from our Open OnDemand service.

Start the Linux Desktop session
Find the Terminal icon
Open the Terminal application

In the Terminal window run the following:

$ source /nobackup/shared/containers/ogs.2026.03.sh
$ container.run ogs-lab

Firefox will start from inside the container with a new, empty, Jupyter Lab instance, then:

Select the Notebook, and Python3 (ipykernel) option
You can now start writing your own code, in this example we ran the first section from https://ogstools.opengeosys.org/0.8.0/auto_examples/howto_quickstart/plot_framework.html

To exit, close Firefox, then either Control+C in the Terminal window, or close it. If finished with the Linux Desktop session, then use the “Applications” menu to exit and log out.

OSGTools documentation: https://ogstools.opengeosys.org/0.8.0/auto_examples/index.html
See the OSGTools quickstart examples: https://ogstools.opengeosys.org/0.8.0/auto_examples/howto_quickstart/plot_framework.html

You can use any of the interactive partitions to launch the OGS Jupyter Lab interface - you do not need the GPU-specific nodes, as OGS does not have any intensive GPU requirements.

Accessing Data

As long as you use the container.run method to launch the applications, you will automatically be able to read and write to files in your $HOME, /scratch and /nobackup directories.

If you run any of the applications inside the container manually, without using the container.run helper you will need to use the –bind argument to apptainer to ensure that all relevant directories are exposed within the container.

Do remember that the container filesystem itself cannot be changed - so you won't be able to write or update to /usr/local, /opt, /etc or any other internal folders - keep output directories restricted to the three areas listed above.

Building OpenGeoSys on Comet

Important!

This section contains information that is only relevant to RSE HPC administrators or users who are curious how OGS is built. If you only need to know how to use OGS, then stop reading here.

Build script

#!/bin/bash
IMAGE_DATE=`date +%Y.%m`

echo "Loading modules..."
module load apptainer

echo ""
echo "Building container..."
export APPTAINER_TMPDIR=/scratch

echo ""
echo "Container will have date suffix $IMAGE_DATE"

# You must supply a copy of bc-convert*.rpm in this
# folder below. If it is not present then the install
# of this tool will be skipped.
SOURCE_DIR=`pwd`

apptainer build --bind $SOURCE_DIR:/mnt ogs.$IMAGE_DATE.sif ogs.def 2>&1 | tee ogs.log

Container definition

Bootstrap: docker
From: ubuntu:noble

####################################################################
#
# Open Geo Sys Container
# ==================
# This is a runtime environment for OGS: https://www.opengeosys.org/stable/
# Please see: 
#	https://hpc.researchcomputing.ncl.ac.uk/dokuwiki/dokuwiki/doku.php?id=advanced:software:ogs
#
####################################################################

%post
    # Prevent interactive prompts
    export DEBIAN_FRONTEND=noninteractive

####################################################################
#
# Basic system packages
#
####################################################################

    # Update & install only necessary packages
    apt-get update
	apt-get install -y apt-utils wget autoconf cmake build-essential man-db tar unzip git aptitude python3-pip gcc-14 g++-14 gfortran-14 openmpi-bin openmpi-common libopenmpi-dev libgomp1 autoconf vim
	ln -s /usr/bin/python3 /usr/bin/python
	
	# Needed for firefox
	apt-get install -y \
		libgtk-3-0 \
		libasound2t64 \
		libx11-xcb1 \
		nodejs \
		libglu1 \
		libgl1 \
		libxft2
	
    # Clean up APT cache to save space
    apt-get clean 

	# Any Python modules installed via pip go here
	# pip install NAME --break-system-packages
	
	pip install ogs==6.5.7 --break-system-packages
	pip install ogstools --break-system-packages
	pip install jupyterlab --break-system-packages
	
	# Remove any Python cache files after pip
	pip3 cache purge

#################################################################################
#
# This is all the custom stuff needed to build the various bioinformatics tools
#
#################################################################################

	# This flag needs to be set to indicate which CPU architecture we
	# are optimising for.
	AMD_ARCH=0

	if [ "$AMD_ARCH" = "1" ]
	then
		# Compiling on AMD Epyc
		export CFLAGS="-O3 -march=znver5 -pipe"
		export MAKE_JOBS=4
	else
		# Compiling on generic system
		export CFLAGS="-O"
		export MAKE_JOBS=2
	fi
	
	export CPPFLAGS=""
	export CXXFLAGS="$CFLAGS"
	export CC=gcc-14
	export CXX=g++-14
	export FC=gfortran-14
	export PATH=/opt/bin:$PATH

	# Src and opt 
	mkdir -p /src/zipped
	mkdir -p /opt/bin
	
	# Firefox
	echo ""
	echo "INSTALL FIREFOX"
	echo "==============="
	echo ""
	cd /src
	wget -q "https://download.mozilla.org/?product=firefox-latest-ssl&os=linux64&lang=en-GB" -O /src/zipped/firefox.tar.xz
	cd /opt
	tar -xf /src/zipped/firefox.tar.xz
	
	# OGS examples
	echo ""
	echo "INSTALL OGS EXAMPLES"
	echo "===================="
	echo ""
	mkdir -p /opt/ogs
	cd /src
	
	# Sample data files
	wget -q https://gitlab.opengeosys.org/ogs/ogs/-/archive/6.5.7/ogs-6.5.7.zip?path=Tests/Data/Mechanics/Linear/DiscWithHole -O /src/zipped/DiscWithHole.zip
	unzip /src/zipped/DiscWithHole.zip
	mv -v ogs-6.5.7-Tests-Data-Mechanics-Linear-DiscWithHole/Tests/Data/Mechanics/Linear/DiscWithHole /opt/ogs/
	
	# Sample notebook
	wget -q https://www.opengeosys.org/docs/benchmarks/small-deformations/linear_disc_with_hole/Linear_Disc_with_hole.ipynb -O /opt/ogs/DiscWithHole/Linear_Disc_with_hole.ipynb
	
	# A script to start ogs with the example notebook
	# https://www.opengeosys.org/6.5.7/docs/userguide/basics/5-mins-ogs/
	echo "#!/bin/bash" > /opt/bin/ogs-lab-example
	echo 'export OGS_TESTRUNNER_OUT_DIR=$HOME/ogs_examples' >> /opt/bin/ogs-lab-example
	echo "jupyter-lab /opt/ogs/DiscWithHole/Linear_Disc_with_hole.ipynb" >> /opt/bin/ogs-lab-example
	chmod +x /opt/bin/ogs-lab-example
	
	# A script to start ogs jupyter lab with a blank notebook
	echo "#!/bin/bash" > /opt/bin/ogs-lab
	echo "jupyter-lab" >> /opt/bin/ogs-lab
	chmod +x /opt/bin/ogs-lab
	
	# Remove all src packages
	echo ""
	echo "FINAL CLEAN UP"
	echo "=============="
	echo ""
	cd
	rm -rf /src
	pip3 cache purge
	
	echo ""
	echo "7. All done"

%environment
	export PATH=/opt/bin:/opt/firefox:$PATH
	export CFLAGS="-O3 -march=native -pipe"
	export CXXFLAGS="$CFLAGS"
	export CC=gcc-14
	export CXX=g++-14
	export FC=gfortran-14
	export OMPI_CC=gcc-14

%runscript

Run script

#!/bin/bash

module load apptainer

IMAGE_NAME=/nobackup/shared/containers/ogs.2026.03.sif

container.run() {
	# Run a command inside the container...
	# automatically bind the /scratch and /nobackup dirs
	# pass through any additional parameters given on the command line
	apptainer exec --bind /run:/run --bind /scratch:/scratch --bind /nobackup:/nobackup ${IMAGE_NAME} $@
}

Back to Software

Table of Contents