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 .ini 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 itself does not contain an implementation for a specific model. To actually build a specific model the associated HydroMT plugin needs to be installed.

To check which HydroMT model plugins are installed, do:

hydromt --models

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.ini file and the data sources in the data_catalog.yml file.

hydromt build sfincs /path/to/model_root "{'bbox': [4.6891,52.9750,4.9576,53.1994]}" -i /path/to/sfincs_config.ini -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 REGION

  Build models from scratch.

  Example usage:
  --------------

  To build a wflow model for a subbasin using and point coordinates snapped to cells with stream order >= 4
  hydromt build wflow /path/to/model_root "{'subbasin': [-7.24, 62.09], 'strord': 4}" -i /path/to/wflow_config.ini -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 "{'bbox': [4.6891,52.9750,4.9576,53.1994]}" -i /path/to/sfincs_config.ini -d /path/to/data_catalog.yml -v

Options:
  -r, --res FLOAT             Model resolution in model src.
  --build-base / --build-all  Deprecated!
  --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.
  -d, --data TEXT             Path to local yaml data catalog file OR name of
                              predefined data catalog.
  --dd, --deltares-data       Shortcut to add the "deltares_data" catalog
  -q, --quiet                 Decrease verbosity.
  -v, --verbose               Increase 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.ini')  # parse .ini 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)