Model building using HydroMT Delft3D FM#

Accessing HydroMT through CLI#

Let’s first check if the Delft3D FM model is recognized by HydroMT using the command hydromt --models. This should return dflowfm, as well as the generic HydroMT models: grid_model, lumped_model, mesh_model, network_model.

NOTE: If you have other HydroMT plugins installed in the same environment (Wflow, SFINCS, FIAT, and more), then these models will also appear after this command.

[1]:

!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

We can use the command hydromt --help to get an overview of all the commands that can be accessed through the command line interface. HydroMT is typically used to hydromt build a model using a configuration file. This command sets up the model based on the parameters and data specified in the configuration file.

It is also possible to hydromt update or hydromt clip existing models:

• ``hydromt update``: This command updates an existing model with new data or parameters.

• ``hydromt clip``: This command clips the model to a specified region, which can be useful for focusing on a smaller area within a larger model.

The command hydromt export is not directly related to model building but is used to export data from a data catalog. This can be useful for extracting specific datasets for analysis or use in other applications.

The command hydromt check is used to validate the configuration file and the linked data catalogs and region settings. This can be especially useful to catch mistakes in the model building process without having to pass all the model building steps, which can take a lot of time for large models.

A more detailed description of these commands can be found in the HydroMT API.

[2]:

!hydromt --help

Usage: hydromt [OPTIONS] COMMAND [ARGS]...

  Command line interface for hydromt models.

Options:
  --version  Show the version and exit.
  --models   Print available model plugins and exit.
  --help     Show this message and exit.

Commands:
  build   Build models
  check   Validate config / data catalog / region
  clip    Clip models.
  export  Export data
  update  Update models

NOTE: When inspecting the documentation of HydroMT Core, make sure that you open the documentation for the corresponding HydroMT version. The HydroMT version of your Python environment is listed as a part of the hydromt --models command, or can be found by simply using hydromt --version.

[3]:

!hydromt --version

HydroMT version: 0.10.1

Requirements for building a model in HydroMT Delft3D FM#

Using the HydroMT build API, we can set up a complete model from scratch. This process involves several steps and options that allow you to customize your model according to your specific needs. Let’s get an overview of all the available options to understand how we can effectively use this API for model building.

[4]:

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

We can see that there are two required arguments for building a model: MODEL, which describes the type of model to build, and MODEL_ROOT, which is the root path of the model. Additionally, a HydroMT configuration file can be specified using either -i or --config, a data catalog using either -d or --data, and region settings using -r or --region. Both the configuration file and the data catalog will be explained in greater detail in this notebook.

• ``MODEL``: This argument specifies the type of model you want to build (e.g., dflowfm).

• ``MODEL_ROOT``: This argument defines the root directory where the model will be stored.

• ``-i`` or ``–config``: Use this option to specify the path to the HydroMT configuration file.

• ``-d`` or ``–data``: Use this option to specify the data catalog that contains the datasets required for the model.

• ``-r`` or ``–region``: Use this option to define the geographical region for the model.

These options provide flexibility and control over the model-building process, allowing you to customize your model according to your specific needs.

NOTE: In the current version of HydroMT Delft3D FM, no region settings are required when building a model.

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, 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 YAML files which are available in the model repository examples folder and from the docs (building a model). These example YAML files are also used in this notebook to build the 1D, 2D, and coupled 1D2D models.

Each section, before indent (e.g., setup_rivers_from_dem), corresponds to a model method. A model method is a step inside the model building process. Each method adds a new component to the model, thus building the model step-by-step. All model methods are explained in the docs (model components). The global section contains direct model initialization properties which are required when the empty model is initialized. It typically contains global settings such as the coordinate system of the model.

We will load the default dflowfm build 1D2D yaml file for inspection:

[5]:

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

global:
  crs: 3857
  network_snap_offset: 25
  openwater_computation_node_distance: 40

setup_rivers_from_dem:
  region:
    bbox: [12.4331, 46.4661, 12.5212, 46.5369]
  hydrography_fn: merit_hydro
  river_geom_fn: hydro_rivers_lin
  rivers_defaults_fn: rivers_defaults
  rivdph_method: gvf
  rivwth_method: geom
  river_upa: 25.0
  friction_type: "Manning"
  friction_value: 0.023
  rivbankq: 25

setup_pipes:
  region:
    bbox: [12.4331, 46.4661, 12.5212, 46.5369]
  pipes_fn: grip_roads
  pipes_defaults_fn: pipes_defaults
  pipe_filter: pipe
  spacing: 50
  friction_type: WhiteColeBrook
  friction_value: 0.003
  crosssections_shape: circle
  crosssections_value: 0.5
  dem_fn: merit_hydro # [copdem30, merit]
  pipes_depth: 2.0
  snap_offset: 0.5
  pipes_invlev: 3.

setup_manholes:
  manholes_fn:
  manholes_defaults_fn: manholes_defaults
  dem_fn: merit_hydro
  bedlevel_shift: 0.5

setup_1dboundary:
  boundary_value: -2.0
  branch_type: river
  boundary_type: waterlevel
  boundary_unit: m
  boundary_locs: both

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

setup_link1d2d:
  link_direction: 1d_to_2d

It can be seen that many arguments are required for the methods. Some arguments require data sources, typically indicated using <...>_fn. For example, the setup_pipes method requires a data source for the geometry of the pipes: pipes_fn, and additionally a data source with the default geometry of these pipes: pipes_default_fn. These data sources are obtained either directly by providing a path to the corresponding file, or by using an entry from a given data catalog. The next section explains how to create and use a data catalog.

NOTE: In this example, we apply the region argument in setup_rivers_from_dem, setup_pipes, and setup_mesh2d. They are identical in this example, but you can alter them to have different regions for rivers, pipes, and the 2D mesh. This allows you to customize your model as much as possible, as the extent of the 1D river can differ from the extent of the 1D urban network or the 2D inundation grid. The region bounding boxes (bbox) are in WGS 84 as required, but you should specify the dflowfm model destination Coordinate Reference System (CRS) in the global section. This ensures that you can use grid definition data (rivers, pipes) from different data sources or CRS.

Data for model setup#

Most of the time, the <...>_fn arguments correspond to a data source from the DataCatalog, which is based on a YAML 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>. The functionality of the data catalog is prescribed by HydroMT Core, and therefore, the detailed description on how to create and use a data catalog can be found in the HydroMT core docs. It is possible to use multiple data catalogs by repeating the -d flag.

A data catalog in HydroMT is a structured way to organize and reference various datasets, making it easier to manage and access data for modeling. Its entries describe where data can be found, which adapter to use to read data with which settings, how to modify the data when reading (scaling, offsetting), and metadata.

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

We use the pre-defined artifact_data catalog in this example notebook, which contains some example data for the Piave basin. This data will be downloaded to ~/.hydromt_data/. To give an example of a data catalog, we will use hydromt export to download and export some entries of the artifact_data catalog. This will be done for the same region as the example build models, and the target directory will be the data folder, which should already exist in the same folder as this notebook.

[6]:

!hydromt export ./data -s grip_roads -s merit_hydro -s vito_2015 -r "{'bbox': [12.4331, 46.4661, 12.5212, 46.5369]}" -d artifact_data -vvv

2025-05-19 09:45:56,170 - export - log - DEBUG - Writing log messages to new file /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/data/hydromt.log.
2025-05-19 09:45:56,170 - export - log - INFO - HydroMT version: 0.10.1
2025-05-19 09:45:56,170 - export - main - INFO - Output dir: /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/data

After downloading the data, we can inspect the corresponding data catalog:

[7]:

dc_yml = "./data/data_catalog.yml"
with open(dc_yml, "r") as f:
    txt = f.read()
print(txt)

meta:
  root: /home/runner/work/hydromt_delft3dfm/hydromt_delft3dfm/docs/_examples/data
grip_roads:
  data_type: GeoDataFrame
  version: v4
  path: grip_roads.gpkg
  driver: vector
  filesystem: local
  meta:
    category: road
    paper_doi: 10.1088/1748-9326/aabd42
    paper_ref: Meijer et al, 2018
    source_license: CC0-1.0
    source_url: https://www.globio.info/download-grip-dataset
  crs: 4326
merit_hydro:
  data_type: RasterDataset
  version: '1.0'
  path: merit_hydro/{variable}.tif
  driver: raster
  filesystem: local
  meta:
    category: topography
    paper_doi: 10.1029/2019WR024873
    paper_ref: Yamazaki et al. (2019)
    source_license: CC-BY-NC 4.0 or ODbL 1.0
    source_url: http://hydro.iis.u-tokyo.ac.jp/~yamadai/MERIT_Hydro
  crs: 4326
vito_2015:
  data_type: RasterDataset
  version: 2.0.2
  path: vito_2015.tif
  driver: raster
  filesystem: local
  meta:
    category: landuse & landcover
    paper_doi: 10.5281/zenodo.3939038
    paper_ref: Buchhorn et al (2020)
    source_url: https://land.copernicus.eu/global/products/lc
  crs: 4326

Next steps: Model building notebooks#

In this notebook, you have explored the basic concepts of accessing HydroMT Delft3D FM using the Command Line Interface (CLI). We have explained the contents of a configuration file and a data catalog, and how they are used to build and manage Delft3D FM models.

You can now proceed to the example notebooks where Delft3D FM models will be built using an example configuration file and the artifact data. It is recommended to start with the 1D and 2D models (build_1dmodel.ipynb and build_2dmodel.ipynb) before moving on to the coupled 1D2D model (build_1d2dmodel.ipynb).

Additionally, there are example notebooks that highlight the functionality of grid refinement (update_refine_2dgrid.ipynb) and how to plot the mesh of a model using Python (plot_dflowfm_mesh.ipynb).