delftwaves/swan repository overview

⁠SWAN

SWAN is a third-generation wave model that computes random, short-crested wind-generated waves in coastal regions and inland waters.

The source code is available on TU Delft GitLab⁠

⁠how to use this docker image

This docker image provides the ability to run or try SWAN on your own computer without requiring to install or compile its source code. Using this image a container is created that has all the necessary software, including libraries, dependencies and the SWAN executable, installed for running SWAN on any platform (Windows, Linux and macOS).

To create a Docker container, you must first install the Docker Desktop⁠. Download links are provided for Windows⁠, Linux⁠ and macOS⁠.

After installing Docker, you can run SWAN by running the container in the following way.

• Open a terminal and navigate to the folder containing your SWAN input files (command file, grid, bathymetry, etc.).

• Copy and paste the following command in your terminal, replace <SWAN input> by the name of your SWAN command file (without extension!), and hit Enter:

  docker run --rm -v .:/home/swan delftwaves/swan swanrun -input <SWAN input>
  

  Copy

Alternatively, you can log into the container and then run commands from there.

docker run -v .:/home/swan -it delftwaves/swan bash

Notes:

• The option -v .:/home/swan instructs Docker to mount the work directory /home/swan, which resides inside the container, onto your local folder. This way the SWAN output files are saved in that folder after terminating the container.

• The current source code from the main branch of the GitLab repository⁠ is available under the tag latest. If desired, you can use another version of the container by explicitly specifying the tag, as follows

  docker run ... delftwaves/swan:<tag> ...
  

  Copy

  where <tag> indicates a version number of SWAN. You can select this number at the top-right corner.

⁠additional options

# pull the image
docker pull delftwaves/swan

# run the container called checkswan to check swan
docker run --name checkswan delftwaves/swan

# retrieve the SWAN output file from the running container `checkswan`
docker cp checkswan:/tmp/a21sho01.tbl .

⁠use with Apptainer

This docker image can be used with Apptainer, which is especially useful for running SWAN on HPC clusters, either locally or in the cloud.

First, pull the docker image:

apptainer pull docker://delftwaves/swan:latest

This pull creates a singularity image named swan_latest.sif, which can then be run with standard Apptainer commands. For example:

apptainer run swan_latest.sif swanrun -input <SWAN input> -mpi <nprocs> > swanout &

where <SWAN input> is the name of your command file without extension and <nprocs> indicates how many processors need to be launched for a parallel MPI run.

Note that Apptainer is compatible with Singularity, implying that you may use the command singularity instead of apptainer.

⁠running testcases

Various testcases can be found in the GitHub repository⁠.