Building a model

To build a complete model from scratch using available data the build method can be used. The build method is identical for all HydroMT model plugins, but the model methods (i.e. sections and options in the .yaml configuration file) are different for each model.

Steps in brief:

1. Prepare or use a pre-defined data catalog with all the required data sources, see working with data

2. Define your model region, see the overview of region options.

3. Prepare a model configuration which describes the complete pipeline to build your model: see model configuration.

4. Build you model using the CLI or Python interface

From CLI

The hydromt build command line interface (CLI) method can be run from the command line after the right conda environment is activated. The HydroMT core package contain implementation for generalized model classes. Specific model implementation for softwares have to be built from associated HydroMT plugin that needs to be installed to your Python environment.

To check which HydroMT model plugins are installed, do:

hydromt --models

Note

From version 0.7.0 onwards it is required to add a -r (--region) flag before REGION when defining a region with the CLI. Prior to this change the -r flag was reserved for resolution. Resolution for gridded models now have to be set in the .yaml configuration files, e.g., under setup_basemaps for HydroMT-Wflow.

Example usage

The following line of code builds a SFINCS model for a region defined by a bounding box bbox and based on the model methods in the sfincs_config.yaml file and the data sources in the data_catalog.yml file.

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

The following line of code builds a SFINCS model for a region defined by a bounding box bbox and based on the model methods in the grid_model_config.yaml file and the data sources in the data_catalog.yml file.

hydromt build grid_model /path/to/model_root -r "{'bbox': [4.6891,52.9750,4.9576,53.1994]}" -i /path/to/grid_model_config.yaml -d /path/to/data_catalog.yml -v

Tip

The verbosity of the log messages can be increased with -v for info and -vv for debug messages.

Overview of options

To check all options do:

hydromt build --help

Usage: main 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.

From Python

All HydroMT models have a build() method which can be used when building models from Python. The data catalog yaml files and logging have to be set when initializing the model. The configuration file can be parsed using configread() and passed to the build method using the opt argument.

Example usage

To create the same SFINCS model as shown above in the CLI example the following block of Python code is required.

from hydromt_sfincs import SfincsModel
from hydromt.config import configread
data_libs = [r'/path/to/data_catalog.yml']
model_root = r'/path/to/model_root
opt=configread(r'/path/to/sfincs_config.yaml')  # parse .yaml configuration
mod = SfincsModel(model_root, data_libs=data_libs)  # initialize model with default logger
mod.build(region={'bbox': [4.6891,52.9750,4.9576,53.1994]}, opt=opt)

To create the same gridded model:

from hydromt.models.model_grid import GridModel
from hydromt.config import configread
data_libs = [r'/path/to/data_catalog.yml']
model_root = r'/path/to/model_root
opt=configread(r'/path/to/grid_model_config.yaml')  # parse .yaml configuration
mod = GridModel(model_root, data_libs=data_libs)  # initialize model with default logger
mod.build(region={'bbox': [4.6891,52.9750,4.9576,53.1994]}, opt=opt)