Tip
Build an emission model#
This notebook demonstrates how to prepare DELWAQ D-Emissions 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#
In HydroMT, you can interact with DELWAQ models either to be used by D-Emissions (demission) or D-Water Quality (delwaq).
Lets first check if the delwaq and demission models are recognized by hydromt
[1]:
# this should return "delwaq, demission, wflow, wflow_sediment"
!hydromt --models
Model plugins:
- model (hydromt 1.3.0)
- example_model (hydromt 1.3.0)
- wflow_sbm (hydromt_wflow 1.0.1)
- wflow_sediment (hydromt_wflow 1.0.1)
- delwaq (hydromt_delwaq 0.3.2.dev0)
- demission (hydromt_delwaq 0.3.2.dev0)
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.
Setup demission model base layers#
DELWAQ models are quite specific in the sense that they are usually added on top of an already existing hydrologic / hydraulic or hydrodynamic model. In HydroMT, for now, DELWAQ models (demission for D-Emissions and delwaq for D-Water Quality) can only be built on top of Wflow hydrologic models. You can find more information on this coupling in docs(coupling_wflow).
Here is how you can build a D-Emissions model using a model workflow configuration file.
The configuration file (yml) contains the model setup configuration and determines which components are build and in which order and optionally sets non-default arguments for each component. This configuration is passed to hydromt using -i <path_to_configuration_file>. We have prepared several example files which are available in the model repository examples folder and from the
docs(build_configuration).
Each header as shown between [...] (e.g. [setup_basemaps]) corresponds to a model component. All model components are explained in the docs(model_components).
Almost each DELWAQ model is unique depending on which substances and sources are included but also what kind of emission data is available. For these reasons, there is no default build configuration file for a demission/delwaq model and still some manual steps are required to build and run a D-Emissions model with HydroMT. You can learn more about these steps in the docs(hydromt_D-Emissions).
We will load an example demission build configuration file for inspection:
[3]:
fn_yml = 'delwaq_build_EM.yml'
with open(fn_yml, 'r') as f:
txt = f.read()
print(txt)
steps:
- setup_basemaps:
region:
wflow_sbm: wflow_piave
maps:
- rivmsk
- lndslp
- strord
- soil_thickness
- soil_theta_s
- setup_monitoring:
mon_areas: riverland
- setup_emission_raster:
emission_fn: ghs_pop_2015
scale_method: average
fillna_method: zero
area_division: True
- setup_emission_vector:
emission_fn: gdp_world
col2raster: gdp
rasterize_method: value
Some explanations for the sections the ini file above:
setup_basemaps: prepares the first delwaq model layers (grid, segment ID) and for EM also the geometry.
setup_monitoring: prepares no monitoring points and monitoring areas by compartments (emissions only here).
setup_emission_raster: prepares emissions grid from a raster file. You can repeat this section several times for several rasters. Here we will prepare population data from the global ghs_pop_2015 dataset.
setup_emission_vector: prepares emissions grid from a vector file. You can repeat this section several times for several rasters. Here we will prepare GDP data from the global gdp_world data.
For more information on all the options used (resampling method, NaN values handling…), please check the docs(model_components)
Data for model setup#
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 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 are available from the Deltares p-drive. If you have acces to this drive, a pre-configured catalog file can be loaded using
-d deltares_data.
More background how to write a data catalog yml file can be found in the hydromt core docs
Setup complete D-Emissions model#
[4]:
# NOTE: copy this line (without !) to your shell for more direct feedback
!hydromt build demission "./EM_test" -i delwaq_build_EM.yml -d artifact_data --fo -vv
2026-01-19 02:34:36,462 - hydromt - log - INFO - HydroMT version: 1.3.0
2026-01-19 02:34:36,576 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Reading data catalog artifact_data latest
2026-01-19 02:34:36,576 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Parsing data catalog from /home/runner/.hydromt/artifact_data/v1.0.0/data_catalog.yml
2026-01-19 02:34:37,252 - hydromt.model.model - model - INFO - Initializing demission model from hydromt_delwaq (v0.3.2.dev0).
2026-01-19 02:34:37,252 - hydromt - log - INFO - HydroMT version: 1.3.0
2026-01-19 02:34:37,253 - hydromt.model.model - model - INFO - build: setup_basemaps
2026-01-19 02:34:37,253 - hydromt.model.model - model - INFO - setup_basemaps.maps=['rivmsk', 'lndslp', 'strord', 'soil_thickness', 'soil_theta_s']
2026-01-19 02:34:37,253 - hydromt.model.model - model - INFO - setup_basemaps.region={'wflow_sbm': PosixPath('/home/runner/work/hydromt_delwaq/hydromt_delwaq/docs/_examples/wflow_piave')}
2026-01-19 02:34:37,253 - hydromt.model.model - model - INFO - Initializing wflow_sbm model from hydromt_wflow (v1.0.1).
2026-01-19 02:34:37,253 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Parsing data catalog from /home/runner/miniconda3/envs/hydromt_delwaq/lib/python3.11/site-packages/hydromt_wflow/data/parameters_data.yml
2026-01-19 02:34:37,270 - hydromt.hydromt_wflow.wflow_base - wflow_base - INFO - Supported Wflow.jl version v1+
2026-01-19 02:34:37,270 - hydromt.hydromt_wflow.components.config - config - INFO - Reading model config file from /home/runner/work/hydromt_delwaq/hydromt_delwaq/docs/_examples/wflow_piave/wflow_sbm.toml.
2026-01-19 02:34:38,529 - hydromt.model.model - model - INFO - build: setup_monitoring
2026-01-19 02:34:38,529 - hydromt.model.model - model - INFO - setup_monitoring.mon_points=None
2026-01-19 02:34:38,529 - hydromt.model.model - model - INFO - setup_monitoring.mon_areas=riverland
2026-01-19 02:34:38,544 - hydromt.model.model - model - INFO - build: setup_emission_raster
2026-01-19 02:34:38,544 - hydromt.model.model - model - INFO - setup_emission_raster.scale_method=average
2026-01-19 02:34:38,544 - hydromt.model.model - model - INFO - setup_emission_raster.fillna_method=zero
2026-01-19 02:34:38,544 - hydromt.model.model - model - INFO - setup_emission_raster.fillna_value=0.0
2026-01-19 02:34:38,544 - hydromt.model.model - model - INFO - setup_emission_raster.area_division=True
2026-01-19 02:34:38,544 - hydromt.model.model - model - INFO - setup_emission_raster.emission_fn=ghs_pop_2015
2026-01-19 02:34:38,546 - hydromt.data_catalog.sources.data_source - data_source - INFO - Reading ghs_pop_2015 RasterDataset data from /home/runner/.hydromt/artifact_data/latest/ghs_pop_2015.tif
2026-01-19 02:34:38,640 - hydromt.model.model - model - INFO - build: setup_emission_vector
2026-01-19 02:34:38,640 - hydromt.model.model - model - INFO - setup_emission_vector.col2raster=gdp
2026-01-19 02:34:38,640 - hydromt.model.model - model - INFO - setup_emission_vector.rasterize_method=value
2026-01-19 02:34:38,640 - hydromt.model.model - model - INFO - setup_emission_vector.emission_fn=gdp_world
2026-01-19 02:34:38,650 - hydromt.data_catalog.sources.data_source - data_source - INFO - Reading gdp_world GeoDataFrame data from /home/runner/.hydromt/artifact_data/latest/gdp_world.gpkg
2026-01-19 02:34:38,776 - hydromt.hydromt_delwaq.components.staticdata - staticdata - INFO - Writing staticdata files.
2026-01-19 02:34:38,830 - hydromt.model.components.geoms - geoms - INFO - demission.geoms: Writing geoms to /home/runner/work/hydromt_delwaq/hydromt_delwaq/docs/_examples/EM_test/geoms/monareas.geojson.
2026-01-19 02:34:38,834 - hydromt.model.components.geoms - geoms - INFO - demission.geoms: Writing geoms to /home/runner/work/hydromt_delwaq/hydromt_delwaq/docs/_examples/EM_test/geoms/basins.geojson.
2026-01-19 02:34:38,836 - hydromt.hydromt_delwaq.components.config - config - INFO - Writing model config to file.
2026-01-19 02:34:38,837 - hydromt.hydromt_delwaq.components.hydromaps - hydromaps - INFO - Writing hydromap files.
2026-01-19 02:34:38,883 - hydromt.hydromt_delwaq.components.geometry - geometry - INFO - Writing geometry file in root/config
2026-01-19 02:34:38,887 - hydromt.hydromt_delwaq.components.forcing - forcing - INFO - No forcing data found, skip writing.
The example above means the following: run hydromt build with:
demission: i.e. build a demission model./EM_test: output model folder-i delwaq_build_EM.yml: setup configuration file including all components to build and their arguments.-d artifact_data: use artifact_data predefined catalog.-vv: give some extra verbosity (2 * v) to display feedback on screen. Now debug messages are provided.
Next we check which files and folders have been created:
config: basic configuration setups for the Delwaq input file .inp. Names of the ASCII files start with the corresponding block in the .inp file.
dynamicdata: Delwaq time-dependant data (hydrological fluxes) in binary format.
fews: additional files for connection with Delft-FEWS (not implemented yet)
hydromodel: data extracted to connect the hydrological model (wflow) and Delwaq (tif format). These files are not mandatory for DELWAQ but produced extra from HydroMT.
staticdata: static (spatial but non time-dependant) data for Delwaq (typically emission data) in binary format. A copy of the data in NetCDF format is also available for easier visualization.
geoms: related geometry files (geojson format). These files are not mandatory for DELWAQ but produced extra from HydroMT.
[5]:
import os
root = 'EM_test'
for path, _, files in os.walk(root):
print(path)
for name in files:
if name.endswith('.xml'):
continue
print(f' - {name}')
EM_test
- hydromt_data.yml
- hydromt.log
EM_test/staticdata
- ghs_pop_2015.dat
- slope.dat
- river.dat
- streamorder.dat
- ptiddown.dat
- porosity.dat
- soil_thickness.dat
- staticdata.nc
- gdp_world.dat
EM_test/hydromodel
- river.tif
- modelmap.tif
- ptiddown.tif
- elevtn.tif
- ptid.tif
- rivarea.tif
- basins.tif
- resarea.tif
- rivwth.tif
- ldd.tif
- rivlen.tif
EM_test/config
- B7_geometry.inc
- B4_nrofexch.inc
- B2_stations.inc
- B7_geometry.bin
- B5_boundlist.inc
- B2_nrofmon.inc
- B7_geometry-parameters.inc
- B3_nrofseg.inc
- B3_attributes.inc
- B2_monareas.inc
- B7_surf.inc
EM_test/geoms
- monareas.geojson
- basins.geojson
You can see that the dynamicdata folder (hydrological input) does not contain any file yet. We will add them in the update forcing example notebook.
Visualize and/or inspect model schematization#
The delwaq plot example notebook contains scripts to visualize your model (staticdata, dynamicdata, hydromodel and geoms).
In the meantime, feel free to have a look at some configuration files that were prepared by HydroMT. You can change the file name from the example code below.
[6]:
import os
model_path = './EM_test'
fn_config = 'config/B3_nrofseg.inc'
with open(os.path.join(model_path,fn_config), 'r') as f:
txt = f.read()
print(txt)
1653 ; nr of segments
In the config folder, you can also see three geometry files:
B7_geometry-parameters.inc (Headers for the binary version)
B7_geometry.bin (Binary version)
B7_geometry.inc (ASCII version)
These files are specific for the D-Emissions plugin and specifies geometry properties of the D-Emissions segments. These properties are:
Segment area (m2)
Fraction of the segment area that is paved
Fraction of the segment area that is unpaved
Fraction of the segment area that is open water
[7]:
import os
model_path = './EM_test'
fn_config = 'config/B7_geometry-parameters.inc'
with open(os.path.join(model_path,fn_config), 'r') as f:
txt = f.read()
print(txt)
PARAMETERS TotArea fPaved fUnpaved fOpenWater