Build a Delft3D FM 2D model from scratch#

This notebook demonstrates how to prepare a 2D Delft3D FM model from scratch using the command line interace (CLI).

All lines in this notebook which start with ! are executed from the command line. Within the notebook environment the logging messages are shown after completion. You can also copy these lines and paste these in your shell to get more direct feedback.

HydroMT CLI build interface#

Lets first check if the Delft3D FM model is recognized by HydroMT:

[1]:

# this should return "dflowfm" to build DFlowFM components of Delft3D FM
# as well as the generic HydroMT models "grid_model, lumped_model, mesh_model, network_model"
!hydromt --models

Model plugins:
        - dflowfm (hydromt_delft3dfm 0.3.1.dev0)
        - model (hydromt 1.3.1)
        - example_model (hydromt 1.3.1)

Using the HydroMT build API we can setup a complete model from scratch. Let’s get an overview of all the available options:

[2]:

!hydromt build --help

Usage: hydromt build [OPTIONS] MODEL MODEL_ROOT

  Build models from scratch.

  Example usage: --------------

  To build a wflow model: hydromt build wflow_sbm /path/to/model_root -i
  /path/to/wflow_config.yml -d deltares_data -d /path/to/data_catalog.yml -v

  To build a sfincs model: hydromt build sfincs /path/to/model_root  -i
  /path/to/sfincs_config.yml -d /path/to/data_catalog.yml -v

Options:
  -i, --config PATH        Path to hydroMT configuration file, for the model
                           specific implementation.  [required]
  -d, --data TEXT          Path to local yaml data catalog file OR name of
                           predefined data catalog.
  --dd, --deltares-data    Flag: Shortcut to add the "deltares_data" catalog
  --fo, --force-overwrite  Flag: If provided overwrite existing model files
  --cache                  Flag: If provided cache tiled rasterdatasets
  -v, --verbose            Increase verbosity.
  -q, --quiet              Decrease verbosity.
  --help                   Show this message and exit.

Data for model setup#

Most of the time, the <...>_fn arguments correspond to a data source from the DataCatalog which is based on a yml-file with references to the data paths/urls and how the data should be read. This file can be provided to HydroMT using -d <path_to_yml_file>.

By default, the pre-defined artifact_data catalog containing some example data for the Piave basin will be downloaded to ~/.hydromt_data/ which is also used for this example. An overview of the available example data is provided here. This example data is a based on the data which is available from the Deltares p-drive. If you have acces to this drive, a pre-configured catalog file can be loaded using the -d deltares_data pre-defined catalog.

More information on how to write a data catalog yml file can be found in the HydroMT core docs

NOTE: In HydroMT-Delft3D FM, an additional data catalog with all default parameters values is always used parameters_data.yml. It contains default values for 1D network elements and structures as well as default 2D landuse parameter mapping tables.

Model setup configuration#

The HydroMT configuration file contains the model setup configuration and determines which methods are used to prepare the different components of a Delft3D FM model and in which order and optionally sets non-default arguments for each method. This configuration is passed to HydroMT using -i <path_to_configuration_file>. We have prepared several example yml-files which are available in the model repository examples folder and from the docs (building a model).

Each section, before indent, (e.g. setup_mesh2d) corresponds to a model method. All model methods are explained in the docs (model components). The global section contains direct model initialisation properties.

We will load the default dflowfm build 2D yaml file for inspection:

[3]:

fn_yml = "dflowfm_build2d.yml"
with open(fn_yml, "r") as f:
    txt = f.read()
print(txt)

modeltype: dflowfm

global:
  crs: 3857

steps:
  - setup_mesh2d:
      region:
        bbox: [12.4331, 46.4661, 12.5212, 46.5369]
      res: 500

  - setup_maps_from_rasterdataset:
      raster_filename: merit_hydro
      variables: ["elevtn"]
      fill_method: nearest
      interpolation_method: nearestNb

  - setup_maps_from_raster_reclass:
      raster_filename: vito_2015
      reclass_table_filename: vito_mapping
      reclass_variables: ['roughness_manning', 'infiltcap']
      interpolation_method: triangulation

  - setup_rainfall_from_constant:
      constant_value: 150

  - setup_config:
      geometry.bedlevuni: -5

Looking at this file, you see that we will prepare the following information for our model:

  • global: our model will be defined in the projected crs WGS84 EPSG 3857.

Then the model building steps are:

  • setup_mesh2d: we will prepare a regular grid for the region bounding box [12.4331, 46.4661, 12.5212, 46.5369] of 500**500* meters resolution.

  • setup_maps_from_rasterdataset: prepares gridded elevation (bedlevel) from merit_hydro. Here elevation is extracted from merit_hydro and any no data is filled using nearest method. When running, the Delft3D FM kernel will interpolate it to the mesh 2D grid using the nearestNb method.

  • setup_maps_from_raster_reclass: prepares gridded Manning roughness and infiltration capacity data from landuse, by reclassifying the landuse categories in vito landuse data, using parameters values defined per landuse category in vito_mapping table. When running, the Delft3D FM kernel will interpolate it to the mesh 2D grid using the triangulation method.

  • setup_rainfall_from_constant: prepares a constant rainfall rate of 150 mm/day as meteo forcing to the model. Feel free to use the links of each components to know more about how each function works and what are all the available settings.

NOTE: In this example, we apply region argument in setup_mesh2d. The region bbox are in WGS 84 as required, but the user should specify the dflowfm model destination CRS in the global section in order to allow to use grid definition data (rivers, pipes) from different data sources or CRS.

Building a 2D Delft3D FM model#

[4]:

# NOTE: copy this line (without !) to your shell for more direct feedback - should take a couple of seconds to run
!hydromt build dflowfm "./build/dflowfm_2d" -i dflowfm_build2d.yml -d artifact_data --fo -v

2026-05-06 06:28:43,460 - hydromt - log - INFO - HydroMT version: 1.3.1
2026-05-06 06:28:44,331 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Reading data catalog artifact_data latest
2026-05-06 06:28:44,331 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Parsing data catalog from /home/runner/.hydromt/artifact_data/v1.0.0/data_catalog.yml
2026-05-06 06:28:45,014 - hydromt.model.model - model - INFO - Initializing dflowfm model from hydromt_delft3dfm (v0.3.1.dev0).
2026-05-06 06:28:45,014 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Parsing data catalog from /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/hydromt_delft3dfm/data/parameters_data.yml
2026-05-06 06:28:45,020 - hydromt.hydromt_delft3dfm.dflowfm - dflowfm - INFO - project crs: 3857
2026-05-06 06:28:45,020 - hydromt - log - INFO - HydroMT version: 1.3.1
2026-05-06 06:28:45,021 - hydromt.model.model - model - INFO - build: setup_mesh2d
2026-05-06 06:28:45,021 - hydromt.model.model - model - INFO - setup_mesh2d.res=500
2026-05-06 06:28:45,021 - hydromt.model.model - model - INFO - setup_mesh2d.region={'bbox': [12.4331, 46.4661, 12.5212, 46.5369]}
2026-05-06 06:28:45,068 - hydromt.model.model - model - INFO - build: setup_maps_from_rasterdataset
2026-05-06 06:28:45,069 - hydromt.model.model - model - INFO - setup_maps_from_rasterdataset.raster_filename=merit_hydro
2026-05-06 06:28:45,069 - hydromt.model.model - model - INFO - setup_maps_from_rasterdataset.variables=['elevtn']
2026-05-06 06:28:45,069 - hydromt.model.model - model - INFO - setup_maps_from_rasterdataset.fill_method=nearest
2026-05-06 06:28:45,069 - hydromt.model.model - model - INFO - setup_maps_from_rasterdataset.interpolation_method=nearestNb
2026-05-06 06:28:45,069 - hydromt.model.components.spatialdatasets - spatialdatasets - INFO - Preparing dataset data from raster source merit_hydro
2026-05-06 06:28:45,071 - hydromt.data_catalog.sources.data_source - data_source - INFO - Reading merit_hydro RasterDataset data from /home/runner/.hydromt/artifact_data/latest/merit_hydro/{variable}.tif
2026-05-06 06:28:45,179 - hydromt.model.components.spatialdatasets - spatialdatasets - WARNING - Replacing xarray: elevtn
2026-05-06 06:28:45,179 - hydromt.model.model - model - INFO - build: setup_maps_from_raster_reclass
2026-05-06 06:28:45,180 - hydromt.model.model - model - INFO - setup_maps_from_raster_reclass.raster_filename=vito_2015
2026-05-06 06:28:45,180 - hydromt.model.model - model - INFO - setup_maps_from_raster_reclass.reclass_table_filename=vito_mapping
2026-05-06 06:28:45,180 - hydromt.model.model - model - INFO - setup_maps_from_raster_reclass.reclass_variables=['roughness_manning', 'infiltcap']
2026-05-06 06:28:45,180 - hydromt.model.model - model - INFO - setup_maps_from_raster_reclass.interpolation_method=triangulation
2026-05-06 06:28:45,180 - hydromt.model.components.spatialdatasets - spatialdatasets - INFO - Preparing map data by reclassifying the data in vito_2015 based on vito_mapping
2026-05-06 06:28:45,182 - hydromt.data_catalog.sources.data_source - data_source - INFO - Reading vito_2015 RasterDataset data from /home/runner/.hydromt/artifact_data/latest/vito.tif
2026-05-06 06:28:45,192 - hydromt.data_catalog.sources.data_source - data_source - INFO - Reading vito_mapping DataFrame data from /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/hydromt_delft3dfm/data/landuse/vito_mapping.csv
2026-05-06 06:28:45,198 - hydromt.gis.raster - raster - WARNING - The nodata value None is not in the reclass table.None will be used for the params.
2026-05-06 06:28:45,261 - hydromt.model.model - model - INFO - build: setup_rainfall_from_constant
2026-05-06 06:28:45,261 - hydromt.model.model - model - INFO - setup_rainfall_from_constant.constant_value=150
2026-05-06 06:28:45,261 - hydromt.hydromt_delft3dfm.dflowfm - dflowfm - INFO - Preparing rainfall meteo forcing from uniform timeseries.
2026-05-06 06:28:45,261 - hydromt.hydromt_delft3dfm.dflowfm - dflowfm - INFO - Initialising empty mdu file
2026-05-06 06:28:45,269 - hydromt.hydromt_delft3dfm.workflows.boundaries - boundaries - INFO - Preparing global (spatially uniform) timeseries.
2026-05-06 06:28:45,269 - hydromt.hydromt_delft3dfm.workflows.boundaries - boundaries - WARNING - time unit days is not supported by the current GUI version: 2022.04
2026-05-06 06:28:45,271 - hydromt.model.model - model - INFO - build: setup_config
2026-05-06 06:28:45,272 - hydromt.model.model - model - INFO - setup_config.geometry.bedlevuni=-5
2026-05-06 06:28:45,272 - hydromt.hydromt_delft3dfm.dflowfm - dflowfm - INFO - Write model data to /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d
2026-05-06 06:28:45,275 - hydromt.hydromt_delft3dfm.components.inifield - inifield - INFO - Writing maps files to /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/maps
2026-05-06 06:28:45,278 - hydromt.hydromt_delft3dfm.components.inifield - inifield - INFO - Writing file /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/maps/bedlevel.tif
2026-05-06 06:28:45,303 - hydromt.hydromt_delft3dfm.components.inifield - inifield - INFO - Writing file /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/maps/frictioncoefficient.tif
2026-05-06 06:28:45,317 - hydromt.hydromt_delft3dfm.components.inifield - inifield - INFO - Writing file /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/maps/InfiltrationCapacity.tif
2026-05-06 06:28:45,323 - hydromt.model.components.geoms - geoms - INFO - dflowfm.geoms: Writing geoms to /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/geoms/mesh2d.geojson.
2026-05-06 06:28:45,337 - hydromt.model.components.geoms - geoms - WARNING - Replacing geom: mesh2d
2026-05-06 06:28:45,337 - hydromt.model.components.geoms - geoms - WARNING - Replacing geom: mesh2d
2026-05-06 06:28:45,337 - hydromt.hydromt_delft3dfm.components.mesh - mesh - INFO - Writing mesh file.
2026-05-06 06:28:45,385 - hydromt.hydromt_delft3dfm.components.forcing - forcing - INFO - Writing forcing files.
2026-05-06 06:28:45,412 - hydromt.hydromt_delft3dfm.components.dimr - dimr - INFO - Initialising empty dimr file
INFO:hydromt.hydromt_delft3dfm.components.dimr:Initialising empty dimr file
2026-05-06 06:28:45,413 - hydromt.hydromt_delft3dfm.components.dimr - dimr - INFO - Adding dflowfm component to dimr config
INFO:hydromt.hydromt_delft3dfm.components.dimr:Adding dflowfm component to dimr config
2026-05-06 06:28:45,413 - hydromt.hydromt_delft3dfm.components.dimr - dimr - INFO - Writing model dimr file to /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/dimr_config.xml
INFO:hydromt.hydromt_delft3dfm.components.dimr:Writing model dimr file to /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/dimr_config.xml
Error in sys.excepthook:

Original exception was:

The example above means the following: run hydromt build with:

  • dflowfm : i.e. build a FM model

  • ./build/dflowfm_2d : output model folder

  • -i dflowfm_build1d.yml: model build configuration file

  • -d artifact_data: data catalog to use. Here the default artifact data catalog with global data for Northern Italy.

  • --fo: force overwritting in case a model already exists in the output folder.

  • -v : give some extra verbosity (1 * v) to display feedback on screen. Now info messages are provided rather than only warnings and errors.

NOTE: You can use as many data catalogs as you need within the same command line, by repeating the -d options and name of the catalog to use several times.

Next we check which files have been created.

[5]:

import os

root = "./build/dflowfm_2d/"
for path, _, files in os.walk(root):
    print(path)
    for name in files:
        print(f" - {name}")

./build/dflowfm_2d/
 - dimr_config.xml
 - hydromt.log
 - hydromt_data.yml
./build/dflowfm_2d/maps
 - frictioncoefficient.tif
 - bedlevel.tif
 - InfiltrationCapacity.tif
./build/dflowfm_2d/geoms
 - mesh2d.geojson
./build/dflowfm_2d/dflowfm
 - bnd.ext
 - fm_net.nc
 - fieldFile.ini
 - DFlowFM.mdu
 - meteo_boundaryconditions.bc

The model root should contain three files and four folders:

  • dimr_config.xml: Configuration file to execute Delft3D FM in Deltares Integrated Model Runner (DIMR).

  • hydromt.log: log saved by HydroMT on model building steps.

  • hydromt_data.yml: information saved by HydroMT on used datasets for reproducibility.

  • dflowfm folder: dflowfm files, here for our 2D model. Contains all necessary information to run a 2D model including the mesh2d, and settings and paths to the mesh2d data files in the maps folder. The configuration MDU file is also created.

  • geoms folder: folder containing a copy of the dflowfm data in an easily readable GIS format rather than the ini or UGRID netcdf file.

  • maps folder: folder containing regular gridded data that Delft3D FM can interpolate to the 2D mesh grid. Here we see our elevation or bedlevel data, as well as the roughness / friction and infiltration capacity maps.

Visualize and/or inspect model schematization#

  • We can now load the dimr_config.xml into Delft3D FM GUI.

  • The dflowfm plot example notebook contains scripts to visualize your model in python: