Overview models#

High level functionality#

HydroMT has the following high-level functionality for setting up models from raw data or adjusting models:

building a model: building a model from scratch.
updating a model: adding or changing model components of an existing model.
clipping a model: changing the spatial domain of an existing model (e.g. select subbasins from a larger model).

The building and clipping methods required the user to provide a region of interest. HydroMT provides several options to define a region based on a geospatial or hydrographic region.

The exact process of building or updating a model can be configured in a single configuration .yaml file. This file describes the full pipeline of model methods and their arguments. The methods vary for the different model classes and Plugins, as documented in this documentation or for each plugin documentation website.

Model API#

HydroMT defines any model through the model-agnostic Model API based on several general components and computational unit components. Each component represents a specific model data type and is parsed to a specific Python data object. The general components are maps (raster data), geoms (vector data), forcing, results, states, and config (the model simulation configuration). These are available to all model classes and plugins.

The computational components are different for different types of models: i.e. grid for distributed or grid models, vector for lumped or semi-distributed models, mesh for mesh or unstructured grid models, and network for network models (to be developed).

By default, the model components are returned and read from standard formats, as documented in the API reference. While a generalized model class can readily be used, it can also be tailored to specific model software through so-called Plugins. These plugins have the same model components (i.e. Model API), but with model-specific file readers and writers and workflows.

Note

As of version 0.6.0, the grid model (distributed grid model), vector model (semi-distributed and lumped models), mesh model (unstructured grid(s) models) have been implemented. Other model classes such as network models will follow in future versions.

The table below lists the base model components common to all model classes. All base model attributes and methods can be found the API reference

Component	Explanation	API
maps	Map data (resolution and CRS may vary between maps)	`maps` `set_maps()` `read_maps()` `write_maps()`
geoms	Static vector data	`geoms` `set_geoms()` `read_geoms()` `write_geoms()`
forcing	(Dynamic) forcing data (meteo or hydrological for example)	`forcing` `set_forcing()` `read_forcing()` `write_forcing()`
results	Model output	`results` `set_results()` `read_results()`
states	Initial model conditions	`states` `set_states()` `read_states()` `write_states()`
config	Settings for the model kernel simulation or model class	`config` `set_config()` `read_config()` `write_config()`

For each generalized model class, the respective computational unit components exist:

Component	Model class	Explanation	API
grid	GridModel	Static gridded data with on unified grid	`grid` `set_grid()` `read_grid()` `write_grid()`
vector	VectorModel	Static polygon data over the vector units	`vector` `set_vector()` `read_vector()` `write_vector()`
mesh	MeshModel	Static mesh (unstructured grid(s)) data	`mesh` `set_mesh()` `get_mesh()` `read_mesh()` `write_mesh()`

Note

Prior to v0.6.0, the staticmaps and staticgeoms components were available. staticmaps is replaced with grid in GridModel, whereas staticgeoms is renamed to geoms for consistency but still available in the Model class.