GEOCEAN — Software Modules

How to find and run the numerical models the group maintains on the SCI-UC cluster. If you just want to run xbeach/swan/sfincs/etc. and don't care how it was built, this page is for you — see Model Development if you need to build a new version or add a model.

Quick start

Every session (or put this in your ~/.bashrc):

module use /nfs/software/geocean/modulefiles

Then:

module avail                # list everything available
module load xbeach          # load the default version
module load xbeach/6157     # or pin an exact version
module list                 # what's currently loaded
module unload xbeach        # unload it
module purge                # unload everything

module avail after the module use line lists every group model in one place:

---------------------- /nfs/software/geocean/modulefiles ----------------------
   delft3d/delft3d     schism/5.11.0       swan/4151
   lisflood/8.1.0      sfincs/2.4.1        swash/12.01
   riskscape/1.14.0    snapwave/b663c81    xbeach/6157

Always pin a version (module load sfincs/2.4.1, not just module load sfincs) for anything you intend to reproduce later or publish results from — the default a bare module load <model> resolves to can change if a newer version is installed and promoted later. Check which version is default any time with module avail <model> (the default is marked, or just check modulefiles/<model>/.version directly).

What's available

Model	Loads as	What it is
`xbeach`	`xbeach/6157`	Coastal morphodynamics (waves, currents, sediment transport, dune erosion)
`delft3d`	`delft3d/delft3d`	Full Delft3D FM suite (D-Flow FM, D-Waves, DIMR coupling)
`swan`	`swan/4151`	Spectral wave model (nearshore wave propagation)
`swash`	`swash/12.01`	Non-hydrostatic wave-flow model (surf zone, wave-structure interaction)
`schism`	`schism/5.11.0`	Unstructured-grid hydrodynamic model (estuaries, coastal circulation)
`sfincs`	`sfincs/2.4.1`	Fast compound-flood model (storm surge + river + rainfall)
`snapwave`	`snapwave/b663c81`	Fast implicit unstructured-grid wave solver
`lisflood`	`lisflood/8.1.0`	Hydraulic flood-inundation model (rivers, pluvial/fluvial flooding)
`riskscape`	`riskscape/1.14.0`	Natural hazard risk/exposure modelling (Java, not a numerical solver)

Each model also has a bin/slurm-<model>.sh sbatch template — see "Submitting a job" below — and a real, runnable example case under /nfs/software/geocean/models/<model>/test/case/ you can copy as a starting point for your own setup.

Running a model

Every model follows the same pattern: module use + module load, cd into a directory with your case's input files, then run the model's binary directly from there.

xbeach

module use /nfs/software/geocean/modulefiles
module load xbeach
cd /path/to/your/case          # params.txt, *.grd, *.dep, ...
mpirun -np <N> xbeach

delft3d

module use /nfs/software/geocean/modulefiles
module load delft3d
cd /path/to/your/case
run_dimr.sh                    # or submit_dimr.sh — see D3D_HOME/bin

swan

module use /nfs/software/geocean/modulefiles
module load swan
cd /path/to/your/case          # INPUT.swn (must be named exactly INPUT.swn)
mpirun -np <N> swan.exe        # or use swanrun, see swan/README.md

swash

module use /nfs/software/geocean/modulefiles
module load swash
cd /path/to/your/case
swashrun -input <name>          # name without the .sws extension

schism

module use /nfs/software/geocean/modulefiles
module load schism
cd /path/to/your/case          # param.nml, hgrid.gr3, vgrid.in, bctides.in, ...
mkdir -p outputs                # SCHISM does not create this for you
mpirun -np <N> pschism_TVD-VL <n_scribes>

<n_scribes> is a dedicated-I/O rank count, not a second -np — see schism/README.md's "The <n_scribes> argument" section before running a real case, the two rules for choosing it are easy to get wrong once.

sfincs

module use /nfs/software/geocean/modulefiles
module load sfincs
cd /path/to/your/case          # sfincs.inp, sfincs.dep, sfincs.msk, ...
OMP_NUM_THREADS=<N> sfincs

snapwave

module use /nfs/software/geocean/modulefiles
module load snapwave
cd /path/to/your/case          # SnapWave.inp, <grid>_net.nc, ...
OMP_NUM_THREADS=<N> snapwave

lisflood

module use /nfs/software/geocean/modulefiles
module load lisflood
cd /path/to/your/case
lisflood -v <name>.par

riskscape

module use /nfs/software/geocean/modulefiles
module load riskscape
cd /path/to/your/project        # project.ini, pipelines, data, ...
riskscape model list
riskscape model run <model-name>

Submitting a job

Each model ships a ready-to-edit sbatch template at /nfs/software/geocean/models/<model>/bin/slurm-<model>.sh. Copy it into your case directory and adjust the resource request, or submit it directly with arguments:

cd /path/to/your/case
sbatch --ntasks=48 /nfs/software/geocean/models/schism/bin/slurm-schism.sh 4

See Intro's Slurm section for partitions and general job etiquette. All these models are single-node-friendly (48 cores on the geocean partition); check the model's own README before assuming multi-node scaling is set up (most aren't tested past one node here).

Where to find real example cases

Every model's test/case/ directory (under /nfs/software/geocean/models/<model>/) is a genuine, previously-verified example — not a toy — good for confirming a module works, or as a starting template for your own case:

cp -r /nfs/software/geocean/models/sfincs/test/case ~/my-first-sfincs-run
cd ~/my-first-sfincs-run
module use /nfs/software/geocean/modulefiles
module load sfincs
OMP_NUM_THREADS=4 sfincs

Something not working?

Wrong version loaded / conflicting output — run module list, confirm you pinned the version you meant (module load model/version), and module purge before loading a different model if you're mixing them in one script.
Library not found at runtime — you likely bypassed the module (ran the binary via an absolute path without module load first, or copied it somewhere else). Always load the module in the same shell/job that runs the binary.
A model behaves differently than documented, or you found a bug in the build — see Model Development and the model's own README.md/VERSIONS.md under /nfs/software/geocean/models/<model>/ before reporting — most non-obvious behavior is already explained there.

Open items

[ ] Add a short worked example per model with real output, not just the bare run command.
[ ] Document any group conventions for naming/organizing case directories under /lustre/geocean/WORK/$USER.