Preparing a model configuration

A user can define a complete pipeline of methods and their options to build a model or updating an existing model in the configuration .yaml file

Steps in brief:

1. Start with a template of the HydroMT model plugin with which you want to build / update a model. Templates can be found in the online documentation of each model plugin.

2. Edit / add / remove sections (i.e. methods) based on which components you want to build or adapt. The arguments of specific methods can be found in the API chapter in the online documentation of each model plugin.

3. Save the configuration file and use it in combination with the HydroMT build and update methods.

Note

The HydroMT configuration file used to be in ini format, this will be deprecated in the future. The new format (supported from version 0.7.1) is a yaml file, which is more flexible and easier to read and write.

Note

The HydroMT model configuration (.yaml) file should not be confused with the simulation configuration file of the model kernel. While the first defines how HydroMT should build or update a model, the latter defines the simulation for the model kernel. The format of the latter differs with each plugin, but can be accessed in HydroMT trough the config() component.

Model configuration (.yaml) file

The .yaml file has a simple syntax with sections and key-value pairs. In HydroMT sections corresponds with model methods and the key-value pair with the arguments of each method. For available methods and their arguments of a specific model, please visit the plugin documentation pages or the API reference. When passed to the build or update CLI methods, HydroMT executes all methods in order as provided in the .yaml file. As such the .yaml file, in combination with a data catalog yaml file define a reproducible model.

HydroMT configuration file specifications and conventions:

• HydroMT will execute each method (i.e. section) in the order it is provided in the .yaml file.

• Methods can be re-used by enumerating the methods by adding a number to the end (without underscore or space!). Although this is not enforced in the code, by convention we start enumerating the second call of each method with a number 2, the third call with a number 3 etc.

• Arguments ending with _fn (short for filename) are typically used to set a data source from the data catalog based on its source name, see Working with data in HydroMT.

An example .yaml file is shown below. Note that this .yaml file does not apply to any supported model plugin.

setup_basemaps:
  topography_fn: merit   # source name of topography data
  crs: 4326              # CRS EPSG code
  res: 100               # resolution [m]

setup_manning_roughness:
  lulc_fn: globcover             # source name of landuse-landcover data
  mapping_fn: globcover_mapping  # source name of mapping table converting lulc classes to N values

setup_infiltration:
  soil_fn:
    source: soil_data             # source name of soil data with specific version
    version: 1.0                  # version of soil data
  mapping_fn: soil_mapping        # source name of mapping table converting soil classes to infiltration parameters

Tip

By default the hydromt build() and update() commands will write all the model files at the end of the workflow using the write() method. This behaviour can be custumized by adding the write method to the workflow with specific arguments, or adding the write method of a specific model component, for instance write_grid() or write_forcing(). If a write method is added to the workflow, the default write method will not be executed at the end and the user needs to take care that all required files are written to disk.