delftwaves/swash repository overview

⁠SWASH

SWASH is a general-purpose numerical tool for simulating unsteady, non-hydrostatic, free-surface, rotational flow and transport phenomena in coastal waters as driven by waves, tides, buoyancy and wind forces. It provides a general framework for describing wave transformations from deep water to a beach, port or harbour, complex changes to rapidly varied flows, and density driven flows in coastal seas, estuaries, lakes and rivers.

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 SWASH 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 SWASH executable, installed for running SWASH 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 SWASH by running the container in the following way.

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

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

  docker run --rm -v .:/home/swash delftwaves/swash swashrun -input <SWASH input>
  

  Copy

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

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

Notes:

• The option -v .:/home/swash instructs Docker to mount the work directory /home/swash, which resides inside the container, onto your local folder. This way the SWASH 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/swash:<tag> ...
  

  Copy

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

⁠additional options

# pull the image
docker pull delftwaves/swash

# run the container called checkswash to check swash
docker run --name checkswash delftwaves/swash

# retrieve the SWASH output file from the running container `checkswash`
docker cp checkswash:/tmp/a11stw01.tbl .

⁠use with Apptainer

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

First, pull the docker image:

apptainer pull docker://delftwaves/swash:latest

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

apptainer run swash_latest.sif swashrun -input <SWASH input> -mpi <nprocs> > swashout &

where <SWASH 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⁠.