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

<WRAP round box info>
**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.
</WRAP>

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''

<WRAP round box info half>
There is a corresponding ''.sh'' script for //each version// of the container image we make available.
</WRAP>

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:

<code lang=bash>
$ 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
$
</code>

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

<code lang=bash>
$ 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
...
$
</code>

   * 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 [[advanced:software:x11|Linux X11 Desktop]] session from our [[advanced:interactive|Open OnDemand]] service.

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

{{:advanced:software:fsl_01_desktop.jpg?500|}} {{:advanced:software:ood_desktop_launch_terminal.png?500|}} {{:advanced:software:ood_desktop_terminal_open.png?500|}}

In the terminal window run the following:

<code lang=bash>
$ source /nobackup/shared/containers/ogs.2026.03.sh
$ container.run ogs-lab-example
</code>

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:

{{:advanced:software:ogs_lab_gui.png?600|}}

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.

<WRAP round box tip>
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.
</WRAP>

   * 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 [[advanced:software:x11|Linux X11 Desktop]] session from our [[advanced:interactive|Open OnDemand]] service.

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

{{:advanced:software:fsl_01_desktop.jpg?500|}} {{:advanced:software:ood_desktop_launch_terminal.png?500|}} {{:advanced:software:ood_desktop_terminal_open.png?500|}}

In the **Terminal** window run the following:

<code lang=bash>
$ source /nobackup/shared/containers/ogs.2026.03.sh
$ container.run ogs-lab
</code>

**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

{{:advanced:software:ogs_lab_start.png?500|}} {{:advanced:software:ogs_lab_start_blank.png?500|}} {{:advanced:software:ogs_lab_start_example.png?500|}}

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

<WRAP round box tip>
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.
</WRAP>

----

===== 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 =====

<WRAP round box important>
**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.
</WRAP>

**Build script**

<code lang=bash title=ogs.build.sh>
#!/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
</code>

**Container definition**

<code lang=bash title=ogs.def>
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
</code>

**Run script**

<code lang=bash title=ogs.sh>
#!/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} $@
}
</code>

----

[[:advanced:software|Back to Software]]