Versions Compared

Old Version 10

changes.mady.by.user Yvonne Olij - Kenyon

Saved on

compared with

New Version Current

changes.mady.by.user Yvonne Olij - Kenyon

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This page contains information about using our container images to run Delft3D computations on your local machine or on HPC clusters and cloud platforms.

A container image is a lightweight, portable package that includes an application and everything it needs to run such as code, libraries, and settings.

Container images are often 'pulled' over the internet from container image repositories.

Contents of this page

Table of Contents
maxLevel1
excludeContents

For Windows Users

If you want to run our Delft3D containers on Windows, follow these instructions: WSL2 (Windows Subsystem for Linux).

After you have followed the instructions, you can start the 'AlmaLinux 8' application anytime you want to use our Delft3D Docker container images on your system. 

Obtaining our container images

Instructions for manually loading Delft3D images from image files can be found below in the Sections "Docker container usage" and "Apptainer container usage".  

Additionally, Delft3D images are stored in Harbor - the image registry that is used within Deltares. A container image registry makes images available from the network.


Accessing Harbor (for authorised users)

Warning

Pulling images from Harbor has beta status. As such, we do not (yet) offer support for workflows and pipelines that make use of Harbor.


Follow the steps below in order to obtain images from Harbor.  
 

1. Login to the Harbor web-interface: https://containers.deltares.nl/




  • For Deltares employees: Click on 'Deltares Login' using your Deltares email address and Windows password.
  • Other authorised users: Log in with your MyDeltares username/email and password. 

2. Request access to the Delft3D project in the container registry by sending an email to software@deltares.nl. Include the following in your email:

  • Your name;
  • Your email address;
  • Your Company / Educational Institution / Organisation;
  • The type of account required: for personal use or for automation (pipelines);
  • The reason for requesting access to Delft3D containers.

After you have been granted access to the Delft3D repository project, 'delft3d' will appear in the Projects list:

3. Copy your CLI secret. 

Warning
For security purposes, when pulling container images, 'CLI secrets' (command line interface secrets) are used instead of your MyDeltares or Windows password.


Click on your name in the top-right corner and click on 'User Profile'.




Click on the copy-icon to copy your CLI secret to your clipboard.


Image versions and tags

The Delft3D images can be found here. A new container image is available on a regular basis.

Panel
borderColorblue
titleColorblack
titleBGColor#E9F2FF
borderStylesolid
titleTags
  • An image with the development tag is the most recent version of the software.

  • An image with the <version>-development tag is an specific (earlier) image. 

  • An image with the <version>-release tag is a official release version. 
    • Delft3D Docker images with a release tag have the status Beta.
    • Delft3D Apptainer images with a release tag have the status GA.


Prepared examples 

The examples.zip file below contains a set of examples that can be used to test your installation of the container. Instructions for running these examples are provided below in the sections 'Docker container usage' and 'Apptainer container usage'.

View file
nameexamples.zip
height150


Docker container usage

Docker containers are very flexible and there are many ways to use them. We recommended them for Delft3D computations on a local machine, or on a single node of a (cloud) computational cluster.

Expand

Make sure to clean up and remove your Docker containers once in a while!

Obtaining a Docker image

There are two ways to install a Delft3D image:

  1. Manually install the image from a docker_delft3dfm_<version>-<id>.zip file.
    • The file contains a .tar of the Docker image.
    • For employees of Deltares, the .zip file can be found here: P:\d-hydro\delft3dfm_containers\docker
  2. Install the image from Harbor.

Install the image from a file

Unzip the docker_delft3dfm_<version>-<id>.zip file. It contains the Docker image .tar file: delft3dfm_<version>-<id>.tar.

Load the image by executing the following on the command line:

Code Block
languagetext
$ docker load -i delft3dfm_<version>-<id>.tar


The image should appear listed in your local Docker container image registry.

Code Block
languagetext
$ docker image ls

    REPOSITORY                                  TAG
    containers.deltares.nl/delft3d/delft3dfm    <tag>

The tag should have the format <version>-<release/development>, for example:

  • 2026.01-release
  • 2.30.02-development

Install the image from Harbor

Login to Harbor via the CLI. 

Code Block
languagetext
$ docker login containers.deltares.nl
(Type your MyDeltares email address and paste your CLI secret.)


Pull the Docker image.

Code Block
languagetext
$ docker pull containers.deltares.nl/delft3d/delft3dfm:<tag>


The image should appear listed in your local Docker container image registry.

Code Block
languagetext
$ docker image ls

    REPOSITORY                                  TAG
    containers.deltares.nl/delft3d/delft3dfm    <tag>

The tag should have the format <version>-<release/development>, for example:

  • 2026.01-release
  • 2.30.02-development

Using Delft3D Docker images to run models

This section describes the steps to perform a single node Delft3D FM computation in Docker. Note, these instructions are for running on Linux or within WSL2 (Windows Subsystem for Linux). 

First Delft3D run (inside the container)

The image contains a simple test case. To run it, execute this on the command line:

Code Block
languagetext
 $ docker run -t --workdir /example containers.deltares.nl/delft3d/delft3dfm:<tag> ./run_example.sh

   

Run an example test case (outside the container) using a prepared script 

Download the set of prepared examples (see examples.zip, above). Follow the instructions below.

Code Block
languagetext
Note: This solution with the run_docker.sh script is for running on Linux or within WSL2 (Windows Subsystem for Linux).
      Non-WSL2 Windows users can use the run_docker.sh script as a template for their own solution.

Preparation:
  - Copy a run_docker.sh and run_example.sh file from an example folder into your own model directory.
      The intended locations:
        run_docker.sh   Root of your model folder; i.e. the directory containing ALL files and subfolders that are necessary for running your model.
        run_example.sh  Folder that contains the DIMR config XML.
  - Change the variable values inside your run_docker.sh where necessary; alternative example values are commented out:
        image:          Is already set for the specific release.
        docker_options: e.g. Add '--shm-size 4G' (or more for heavy models) to reserve shared memory for parallel and coupled runs.
        model_dir:      The directory containing ALL files and subfolders that are necessary for running your model.
        work_dir:       The directory that contains your DIMR config XML, relative to your ${model_dir}.
        command:        The shell command (e.g. a run script) to run inside your container from within ${work_dir}.

Starting the computation:
  - Run:
    $ <path_to_your_model>/run_docker.sh

Commonly encountered problem (and workaround)

When using Docker on Windows, the Windows filesystem sometimes is 'lost' between runs due to a Microsoft bug.

Error (for example, testcase 02_dflowfm_parallel):

Code Block
languagetext
realpath: examples/02_dflowfm_parallel/run_docker.sh: No such file or directory
docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: exec: "./run_example.sh": stat ./run_example.sh: no such file or directory: unknown

Workaround:

Type these commands on the command line and then re-run:

Code Block
languagetext
  cd .. (to get out of the current folder)
  cd -  (to get back to the previous folder)

Or add these commands to the run_docker.sh script (above the 'docker run' line).

Apptainer container usage

We recommend using the Delft3D Apptainer container on High Performance Computing (HPC) clusters. The container can be used to run Delft3D computations on single or multiple nodes.

Expand

Obtaining an Apptainer image

There are two ways to install a Delft3D image:

  1. Manually install from an apptainer_delft3dfm_20xx.0x-<id>.tar.gz file.
    • This file contains an Apptainer image .sif file.
    • For Employees of Deltares, the tar.gz file is available here: P:\d-hydro\delft3dfm_containers
  2. Pull the Docker image from Harbor and convert it to an Apptainer image .sif file.

Install the image from a file

Unpack the apptainer_delft3dfm_20xx.0x-<id>.tar.gz file. It contains an Apptainer image .sif file: delft3d_<tag>.sif

Install the image from Harbor

Login to Harbor via the CLI. 

Code Block
languagetext
$ apptainer registry login --username <email-address> docker://containers.deltares.nl
(Where <email-address> is your MyDeltares email address. Paste your CLI secret)

* For older versions (1.2.X and older) of Apptainer, use: apptainer remote login --username <email-address> docker://containers.deltares.nl


Pull the Docker image and convert it directly to an Apptainer image .sif file: 

Code Block
languagetext
$ apptainer pull docker://containers.deltares.nl/delft3d/delft3dfm:<tag>


This will result in a .sif file in the current working directory.


Using Delft3D Apptainer images to run models on High Performance Computing clusters


Follow the instructions below to run single or multi-node computations on Deltares' HPC cluster, HYDRAX. The instructions and run scripts are appropriate for HPC clusters that use Slurm with Intel MPI.

For employees of Deltares: the run scripts for HYDRAX, Snellius (SURF) and DelftBlue (TU Delft) can be found here: P:\d-hydro\delft3dfm_containers

Other users: Please contact software@deltares.nl if you wish to run computations on DelftBlue, Snellius and other HPC clusters.


Info
titleUsers of other HPC clusters
  • We recommend that the platform's system administrator installs the Apptainer container. 
  • You will need to modify the run scripts according to the needs of the platform.

1. Prepare the computation

  1. Download and unzip the examples.zip file (see 'Prepared examples'). The file includes several example test cases and the run scripts: run_singularity_h7.sh and execute_singularity_h7.sh.
  2. Place the Apptainer .sif file and the script execute_singularity_h7.sh in the same directory. Do not place multiple .sif files in the same directory.
  3. Copy submit_singularity_h7.sh into your working folder (the location of your dimr configuration file). This is an example script for submitting Apptainer computations to a Slurm cluster. You'll need to modify it for your own needs. Refer to the comments in the script.
  4. Edit execute_singularity_h7.sh. This is an example script for executing Apptainer computations on a Slurm cluster. It must refer to an existing Intel MPI installation on your system. Refer to the comments in the script.

For more information: see User manual and Installation manual, see https://download.deltares.nl/en/download/delft3d-fm/


Warning
titleAPPTAINER CONTAINERS CAN BE EXECUTED ON LINUX SYSTEMS ONLY!

You should ensure that: 

  • Folder paths in the submit script and in the model input files are in Linux format, therefore you need to use forward slashes ( / ).
  • Linux is case-sensitive (unlike Windows).
  • Save the submit script with Linux line endings and use Spaces instead of Tabs.

2. Submit the computation

Your computation can be submitted to the Slurm queue by logging into HYDRAX and running the following command in a terminal:

Code Block
languagexml
$ sbatch ./submit_singularity_h7.sh


The simulation will be placed in a queue and will be given a Slurm job ID, e.g.: 

3. Examine the output

Slurm will generate a text output file that you can examine in order to monitor the progress of your simulation. This file has a name with format slurm-<ID>.out