Table of Contents

XBeach

XBeach is a two-dimensional model for wave propagation, long waves and mean flow, sediment transport and morphological changes of the nearshore area, beaches, dunes and backbarrier during storms.

Running XBeach on Comet

The XBeach software is stored within a dedicated container 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:

We normally recommend using the latest (date) version of the container unless you have a specific need for an earlier version of software.

Container Image Versions

We may reference a specific container file, such as xbeach.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, and access your $HOME, /scratch and /nobackup directories to just two simple commands.

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 xbeach and check the version: 

$ source /nobackup/shared/containers/xbeach.sh
$ container.run xbeach -V
**********************************************************
 You are using XBeach version 1.23.6165M XBeachX release
**********************************************************
$

You can continue to use the container.run command as many times as you need in the same script or same bash session.

We strongly recommend that you use this helper script and the container.run command to run software from inside the container as it will always ensure that you have correctly set up the bind directories for you and you are using the correct container version.

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.

Sample Slurm script

Here is a very simple example of calling XBeach from the container within a Slurm batch job that assumes you are a member of the comet_abc123 HPC project group: 

#!/bin/bash

#SBATCH --partition=default_free
#SBATCH --account=comet_abc123
#SBATCH -c 8
#SBATCH --mem=16G

source /nobackup/shared/containers/xbeach.sh
container.run xbeach

Submit as normal with sbatch xbeach_job.sh.

Note that we run on the default_free partition with 8 CPU cores and 16GB of RAM.

Building XBeach for Comet

Important!

This section is only relevant for RSE HPC staff or those who want to understand how the XBeach container runtime has been built. If you are only interested in running the software, stop reading here!

Container definition file: 

#!/bin/bash

echo "Loading modules..."
module load apptainer

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

echo ""
echo "Starting build of container ..."
apptainer build \
	--bind $SOURCE_DIR:/mnt \
	xbeach.sif xbeach.def 2>&1 | tee xbeach.log

chgrp comet_rsehpc xbeach.sif
chmod 664 xbeach.sif
(OSS 2410.0) [njps3@cometlogin02(comet) build]$ cat xbeach.def 
Bootstrap: docker
From: ubuntu:noble

%post
	# Prevent interactive prompts
	export DEBIAN_FRONTEND=noninteractive

	# Update & install only necessary packages
	apt-get update
    
	# Base stuff everything will need
	apt-get install -y aptitude wget zip less vim subversion

	# Add all of the Ubuntu/Debian packages needed to run XBeach here
	apt-get install -y \
		build-essential \
		cmake \
		gcc-14 \
		g++-14 \
		gfortran-14 \
		netcdf-bin \
		libnetcdf-dev \
		libnetcdff-dev \
		openmpi-bin \
		libopenmpi-dev \
		python3 \
		python3-pip
	
	# XBeach just tries to run 'python' not 'python3'
	ln -s /usr/bin/python3 /usr/bin/python

	# XBeach also wants the 'mako' Python module
	pip3 install mako --break-system-packages

	# Remove any downloaded package files - so they dont remain in the built image	
	apt-get clean

	##############################################################################
	# Set Compiler flags to optimise for Comet CPU hardware
	##############################################################################
	export BASE_CFLAGS="-O3 -march=znver5 -pipe"
	export CPPFLAGS=""
	export CFLAGS="$BASE_CFLAGS -I/usr/include"
	export CXXFLAGS="$CFLAGS"
	export CC=gcc-14
	export CXX=g++-14
	export FC=gfortran-14
	export F90FLAGS="-I/usr/include"
	export FFLAGS="-I/usr/include"

	###############################################################################
	# Download and compile XBeach
	###############################################################################

	mkdir -p /src
	cd /src
	svn co https://svn.oss.deltares.nl/repos/xbeach/trunk xbeach
	cd xbeach
	export FCFLAGS="-I/usr/include -I/usr/include"
	./autogen.sh && \
		FC=gfortran-14 MPIFC=mpif90 ./configure --with-netcdf --with-mpi && \
		make && \
		make install

	# Add /usr/local/lib to ldconfig
	echo "/usr/local/lib" > /etc/ld.so.conf.d/xbeach.conf
	rm /etc/ld.so.cache
	ldconfig

	# Remove downloaded source
	rm -rf /src

%environment

%runscript

Container build script: 

#!/bin/bash

echo "Loading modules..."
module load apptainer

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

echo ""
echo "Starting build of container ..."
apptainer build \
	--bind $SOURCE_DIR:/mnt \
	xbeach.sif xbeach.def 2>&1 | tee xbeach.log

chgrp comet_rsehpc xbeach.sif
chmod 664 xbeach.sif

Container runtime helper script: 

#!/bin/bash

module load apptainer

IMAGE_NAME=/nobackup/shared/containers/xbeach.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 --nv \
		--bind /run/user/$UID:/run/user/$UID \
		--bind /scratch:/scratch \
		--bind /nobackup:/nobackup \
		${IMAGE_NAME} $@
}

Back to software