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)
generic models (hydromt 0.10.1):
 - grid_model
 - vector_model
 - mesh_model
 - network_model

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 for a subbasin using a point coordinates snapped to
  cells with upstream area >= 50 km2 hydromt build wflow /path/to/model_root
  -i /path/to/wflow_config.yml  -r "{'subbasin': [-7.24, 62.09], 'uparea':
  50}" -d deltares_data -d /path/to/data_catalog.yml -v

  To build a sfincs model based on a bbox hydromt build sfincs
  /path/to/model_root  -i /path/to/sfincs_config.yml  -r "{'bbox':
  [4.6891,52.9750,4.9576,53.1994]}"  -d /path/to/data_catalog.yml -v

Options:
  --opt TEXT               Method specific keyword arguments, see the method
                           documentation of the specific model for more
                           information about the arguments.
  -i, --config PATH        Path to hydroMT configuration file, for the model
                           specific implementation.
  -r, --region TEXT        Set the region for which to build the model, e.g.
                           {'subbasin': [-7.24, 62.09]}
  -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)

global:
  crs: 3857

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

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

setup_maps_from_raster_reclass:
  raster_fn: vito_2015
  reclass_table_fn: vito_mapping
  reclass_variables: ['roughness_manning', 'infiltcap']
  interpolation_method: triangulation

setup_rainfall_from_constant:
  constant_value: 150

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.
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.

NOTE: If you need to use the same function twice, for example you have raster data for elevation and for roughness, you can list the setup_maps_from_rasterdataset as many times as you wish, by adding a repeating the method and adding a number at the end of the function name. Example: setup_maps_from_rasterdataset, setup_maps_from_rasterdataset1, setup_maps_from_rasterdataset2 etc.

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 -vv

2025-05-19 09:45:42,151 - build - log - DEBUG - Writing log messages to new file /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/hydromt.log.
2025-05-19 09:45:42,151 - build - log - INFO - HydroMT version: 0.10.1
2025-05-19 09:45:42,151 - build - main - INFO - Building instance of dflowfm model at /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d.
2025-05-19 09:45:42,151 - build - main - INFO - User settings:
2025-05-19 09:45:42,942 - build - data_catalog - INFO - Reading data catalog artifact_data latest
2025-05-19 09:45:42,942 - build - data_catalog - INFO - Parsing data catalog from /home/runner/.hydromt_data/artifact_data/v0.0.9/data_catalog.yml
2025-05-19 09:45:43,500 - build - model_api - INFO - Initializing dflowfm model from hydromt_delft3dfm (v0.3.1.dev0).
2025-05-19 09:45:43,500 - build - data_catalog - INFO - Parsing data catalog from /usr/share/miniconda/envs/test/lib/python3.12/site-packages/hydromt_delft3dfm/data/parameters_data.yml
2025-05-19 09:45:43,504 - build - dflowfm - INFO - Initialising empty mdu file
2025-05-19 09:45:43,510 - build - dflowfm - INFO - project crs: 3857
2025-05-19 09:45:43,510 - build - model_api - INFO - setup_mesh2d.region: {'bbox': [12.4331, 46.4661, 12.5212, 46.5369]}
2025-05-19 09:45:43,510 - build - model_api - INFO - setup_mesh2d.res: 500
2025-05-19 09:45:43,579 - build - model_api - INFO - setup_maps_from_rasterdataset.raster_fn: merit_hydro
2025-05-19 09:45:43,579 - build - model_api - INFO - setup_maps_from_rasterdataset.variables: ['elevtn']
2025-05-19 09:45:43,579 - build - model_api - INFO - setup_maps_from_rasterdataset.fill_method: nearest
2025-05-19 09:45:43,579 - build - model_api - INFO - setup_maps_from_rasterdataset.reproject_method: nearest
2025-05-19 09:45:43,579 - build - model_api - INFO - setup_maps_from_rasterdataset.interpolation_method: nearestNb
2025-05-19 09:45:43,579 - build - model_api - INFO - setup_maps_from_rasterdataset.locationtype: 2d
2025-05-19 09:45:43,579 - build - model_api - INFO - setup_maps_from_rasterdataset.name: None
2025-05-19 09:45:43,579 - build - model_api - INFO - setup_maps_from_rasterdataset.split_dataset: True
2025-05-19 09:45:43,580 - build - model_api - INFO - Preparing maps data from raster source merit_hydro
2025-05-19 09:45:43,580 - build - rasterdataset - INFO - Reading merit_hydro raster data from /home/runner/.hydromt_data/artifact_data/v0.0.9/data.tar/merit_hydro/{variable}.tif
2025-05-19 09:45:43,611 - build - rasterdataset - DEBUG - Clip to [12.433, 46.467, 12.523, 46.538] (epsg:4326))
2025-05-19 09:45:43,705 - build - model_api - WARNING - Replacing result: elevtn
2025-05-19 09:45:43,706 - build - model_api - INFO - setup_maps_from_raster_reclass.raster_fn: vito_2015
2025-05-19 09:45:43,706 - build - model_api - INFO - setup_maps_from_raster_reclass.reclass_table_fn: vito_mapping
2025-05-19 09:45:43,706 - build - model_api - INFO - setup_maps_from_raster_reclass.reclass_variables: ['roughness_manning', 'infiltcap']
2025-05-19 09:45:43,706 - build - model_api - INFO - setup_maps_from_raster_reclass.fill_method: None
2025-05-19 09:45:43,706 - build - model_api - INFO - setup_maps_from_raster_reclass.reproject_method: nearest
2025-05-19 09:45:43,706 - build - model_api - INFO - setup_maps_from_raster_reclass.interpolation_method: triangulation
2025-05-19 09:45:43,706 - build - model_api - INFO - setup_maps_from_raster_reclass.locationtype: 2d
2025-05-19 09:45:43,706 - build - model_api - INFO - setup_maps_from_raster_reclass.name: None
2025-05-19 09:45:43,707 - build - model_api - INFO - setup_maps_from_raster_reclass.split_dataset: True
2025-05-19 09:45:43,707 - build - model_api - INFO - Preparing map data by reclassifying the data in vito_2015 based on vito_mapping
2025-05-19 09:45:43,707 - build - rasterdataset - INFO - Reading vito_2015 raster data from /home/runner/.hydromt_data/artifact_data/v0.0.9/data.tar/vito.tif
2025-05-19 09:45:43,715 - build - rasterdataset - DEBUG - Clip to [12.433, 46.467, 12.523, 46.538] (epsg:4326))
2025-05-19 09:45:43,716 - build - dataframe - INFO - Reading vito_mapping csv data from /usr/share/miniconda/envs/test/lib/python3.12/site-packages/hydromt_delft3dfm/data/landuse/vito_mapping.csv
The nodata value None is not in the reclass table.None will be used for the params.
2025-05-19 09:45:43,785 - build - model_api - INFO - setup_rainfall_from_constant.constant_value: 150
2025-05-19 09:45:43,785 - build - dflowfm - INFO - Preparing rainfall meteo forcing from uniform timeseries.
2025-05-19 09:45:43,787 - build - boundaries - INFO - Preparing global (spatially uniform) timeseries.
2025-05-19 09:45:43,787 - build - boundaries - WARNING - time unit days is not supported by the current GUI version: 2022.04
2025-05-19 09:45:43,788 - build - dflowfm - INFO - Writing model data to /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d
2025-05-19 09:45:43,788 - build - dflowfm - INFO - Writing maps files to /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/maps
2025-05-19 09:45:43,792 - build - dflowfm - INFO - Writing file /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/maps/bedlevel.tif
2025-05-19 09:45:43,820 - build - dflowfm - INFO - Writing file /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/maps/frictioncoefficient.tif
2025-05-19 09:45:43,834 - build - dflowfm - INFO - Writing file /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/maps/InfiltrationCapacity.tif
2025-05-19 09:45:43,840 - build - model_api - DEBUG - Writing file geoms/region.geojson
2025-05-19 09:45:43,843 - build - model_api - DEBUG - Writing file geoms/mesh2d.geojson
2025-05-19 09:45:43,857 - build - model_api - WARNING - Replacing geom: mesh2d
2025-05-19 09:45:43,858 - build - model_api - WARNING - Replacing geom: region
2025-05-19 09:45:43,858 - build - model_api - WARNING - Replacing geom: mesh2d
2025-05-19 09:45:43,858 - build - model_api - DEBUG - Writing file geoms/region.geojson
2025-05-19 09:45:43,860 - build - model_api - DEBUG - Writing file geoms/mesh2d.geojson
2025-05-19 09:45:43,923 - build - dflowfm - INFO - Writting forcing files.
2025-05-19 09:45:43,951 - build - dflowfm - INFO - Initialising empty dimr file
INFO:build:Initialising empty dimr file
2025-05-19 09:45:43,951 - build - dflowfm - INFO - Adding dflowfm component to dimr config
INFO:build:Adding dflowfm component to dimr config
2025-05-19 09:45:43,952 - build - dflowfm - INFO - Writing model dimr file to /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/dimr_config.xml
INFO:build:Writing model dimr file to /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/build/dflowfm_2d/dimr_config.xml

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.
-vv : give some extra verbosity (2 * v) to display feedback on screen. Now debug and 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/
 - hydromt.log
 - hydromt_data.yml
 - dimr_config.xml
./build/dflowfm_2d/maps
 - bedlevel.tif
 - frictioncoefficient.tif
 - InfiltrationCapacity.tif
./build/dflowfm_2d/geoms
 - region.geojson
 - mesh2d.geojson
./build/dflowfm_2d/dflowfm
 - DFlowFM.mdu
 - fieldFile.ini
 - meteo_boundaryconditions.bc
 - fm_net.nc
 - bnd.ext

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: