Models

Base model

class hydrobricks.models.model.Model(name: str | None = None, **kwargs: Any)

Bases: ABC

Base abstract class for hydrological models

add_action(action: Action) → bool

Add an action to the model.

Parameters:

action – The action object. The dates must be sorted.

create_config_file(directory: str, name: str, file_type: str = 'both') → None

Create a configuration file describing the model structure.

Such a file can be used when using the command-line version of hydrobricks. It contains the options to generate the corresponding model structure.

Parameters:

• directory – The directory to write the file.

• name – The name of the generated file.

• file_type – The type of file to generate: ‘json’, ‘yaml’, or ‘both’.

dump_outputs(path: str) → None

Write the model outputs to a netcdf file.

Parameters:

path – Path to the target file.

eval(metric: str, observations: numpy.ndarray, warmup: int = 0) → float

Evaluate the simulation using the provided metric (goodness of fit).

Parameters:

• metric – The abbreviation of the function as defined in HydroErr (https://hydroerr.readthedocs.io/en/stable/list_of_metrics.html) Examples: nse, kge_2012, …

• observations – The time series of the observations with dates matching the simulated series.

• warmup – The number of days of warmup period. This option is used to discard the warmup period from the evaluation. It is useful when conducting a run with a specific parameter set and comparing its score with those from the calibration. By setting the ‘warmup’ value, you can ensure fair assessments by discarding outputs from the specified warmup period (as is done automatically during calibration).

Return type:

The value of the selected metric.

generate_parameters() → ParameterSet

Generate a ParameterSet for the model based on its structure.

Automatically creates parameter definitions based on the model structure, applies any defined aliases, and applies any defined constraints.

Returns:

A ParameterSet object with all model parameters defined.

Return type:

ParameterSet

get_action_count() → int

Get the number of actions (types of actions) registered in the model.

get_outlet_discharge() → numpy.ndarray

Get the computed outlet discharge.

get_sporadic_action_item_count() → int

Get the number of sporadic (non-recursive) action items (individual triggers) registered in the model.

get_total_et() → float

Get the total amount of water lost by evapotranspiration.

get_total_outlet_discharge() → float

Get the outlet discharge total.

get_total_snow_storage_changes() → float

Get the total change in snow storage.

get_total_water_storage_changes() → float

Get the total change in water storage.

initialize_state_variables(parameters: ParameterSet, forcing: Forcing | None = None) → None

Run the model and save the state variables as initial values.

Parameters:

• parameters – The parameters for the given model.

• forcing – The forcing data.

property name: str | None

Get the model name.

run(parameters: ParameterSet, forcing: Forcing | None = None) → None

Setup and run the model.

Parameters:

• parameters – The parameters for the given model.

• forcing – The forcing data.

set_forcing(forcing: Forcing) → None

Set the forcing data.

Parameters:

forcing – The forcing data.

setup(spatial_structure: HydroUnits, output_path: str | Path, start_date: str, end_date: str | None = None) → None

Setup and initialize the model for simulation.

Parameters:

• spatial_structure – The spatial structure of the catchment (hydro units).

• output_path – Path to directory where results will be saved.

• start_date – Starting date of the computation (format: ‘YYYY-MM-DD’).

• end_date – Ending date of the computation (format: ‘YYYY-MM-DD’). If None, uses last date in time series. Default: None

Raises:

• RuntimeError – If the model has already been initialized.

• TypeError – If arguments have incorrect types.

• FileNotFoundError – If the output path cannot be created.

Examples

>>> model = SomeModel()
>>> model.setup(hydro_units, './output', '2020-01-01', '2020-12-31')

Model settings

class hydrobricks.models.model_settings.ModelSettings(solver: str = 'heun_explicit', record_all: bool = False, **kwargs: Any)

Bases: object

Base class for the model settings

add_brick_parameter(name: str, value: int | float | bool, kind: str = 'constant') → None

Add a brick parameter

Parameters:

• name – Name of the brick parameter

• value – Value of the brick parameter

• kind – Type of the brick parameter (for now has to be ‘constant’)

add_brick_process(name: str, kind: str, target: str = '', log: bool = False, instantaneous: bool = False) → None

Add a brick process

Parameters:

• name – Name of the brick process

• kind – Type of the brick process

• target – Target of the process output

• log – Log the brick process

• instantaneous – Process outputs are instantaneous

add_hydro_unit_brick(name: str, kind: str) → None

Add a hydro unit brick

Parameters:

• name – Name of the hydro unit brick

• kind – Type of the hydro unit brick

add_land_cover_brick(name: str, kind: str) → None

Add a land cover brick

Parameters:

• name – Name of the land cover brick

• kind – Type of the land cover brick

add_logging_to(item: str) → None

Add logging to an item

Parameters:

item – Name of the item

add_process_output(target: str) → None

Add an extra output target to the most recently added process.

Parameters:

target – Target brick of the additional output.

add_process_parameter(name: str, value: int | float | bool, kind: str = 'constant') → None

Add a process parameter

Parameters:

• name – Name of the process parameter

• value – Value of the process parameter

• kind – Type of the process parameter (for now has to be ‘constant’)

add_structure() → int

Add a new (empty) model-structure variant and select it.

Subsequent structure-building calls populate the newly selected structure. Units are auto-assigned (in the core) to the variant matching their land covers.

Return type:

The id of the newly created structure.

add_sub_basin_brick(name: str, kind: str) → None

Add a sub basin brick

Parameters:

• name – Name of the sub basin brick

• kind – Type of the sub basin brick

generate_base_structure(land_cover_names: list[str], land_cover_types: list[str], with_snow: bool = True, snow_melt_process: str = 'melt:degree_day', snow_rain_process: str | None = None, snow_ice_transformation: str | None = None, snow_redistribution: str | None = None, snow_water_retention_process: str | None = None, snow_refreezing_process: str | None = None, rain_to_snowpack: bool = False) → None

Generate basic elements

Parameters:

• land_cover_names – List of land cover names

• land_cover_types – List of land cover types

• with_snow – Account for snow

• snow_melt_process – Snow melt process

• snow_rain_process – Rain/snow partitioning method (overrides the default derived from snow_melt_process)

• snow_ice_transformation – Snow and ice transformation method (optional)

• snow_redistribution – Snow redistribution method (optional)

• snow_water_retention_process – Outflow process of the snowpack liquid water storage (optional). When provided, the snowpacks are generated with liquid water retention: the melt water is kept in the snowpack water container and released by the given process (e.g. ‘outflow:snow_holding’).

• snow_refreezing_process – Refreezing process of the retained liquid water (optional; requires snow_water_retention_process). E.g. ‘refreeze:degree_day’.

• rain_to_snowpack – Route the rain to the snowpack liquid water storage instead of the land cover (requires snow_water_retention_process). The rain is retained in the snowpack (up to the holding capacity) and exposed to refreezing; without snow, it reaches the land cover within the same time step.

select_hydro_unit_brick(name: str) → None

Select a hydro unit brick

Parameters:

name – Name of the hydro unit brick

set_current_brick_computed_directly() → None

Mark the selected brick as computed directly (explicitly, without the ODE solver). Used for fully explicit formulations such as the GR4J production store and routing, where processes apply an exact discrete update each step.

set_parameter_value(component: str, name: str, value: float) → bool

Set a parameter value

Parameters:

• component – Name of the component

• name – Name of the parameter

• value – Value of the parameter

Return type:

True if the parameter was set successfully, False otherwise.

set_process_outputs_as_instantaneous() → None

Set all process outputs as instantaneous

set_process_outputs_as_static() → None

Set all process outputs as static

set_timer(start_date: str, end_date: str, time_step: int = 1, time_step_unit: str = 'day') → None

Set the timer

Parameters:

• start_date – Start date of the simulation

• end_date – End date of the simulation

• time_step – Time step

• time_step_unit – Time step unit

GSM-Socont

class hydrobricks.models.socont.Socont(name: str = 'socont', **kwargs: Any)

Bases: Model

SOCONT glacio-hydrological model (Schaefli et al., 2005).

SOCONT (SOil CONTribution) is a conceptual model for high-mountain catchments. Each hydro unit splits precipitation into rain and snow; snow and glacier ice melt by a degree-day routine. On the ground land cover the incoming water is split by the Socont infiltration function between a slow (baseflow) reservoir and the quick surface runoff:

• slow reservoir (capacity A): linear baseflow outflow, LP-free Socont evapotranspiration and a capacity overflow to the outlet; an optional second soil layer (soil_storage_nb=2) is fed by a constant percolation,

• surface runoff: the infiltration excess, transformed either by a kinematic-wave overland flow (socont_runoff) or a linear storage.

On glacierized areas, rain + snowmelt and ice melt are collected in two sub-basin linear storages that drain directly to the outlet (the glacier ice is treated as an infinite storage by default).

The model is integrated by the ODE solver, so the results are a continuous approximation of the original discrete SOCONT formulation.

Parameters (literature names as aliases)

a_snowfloat

Snow melt degree-day factor [mm/d/°C].

a_icefloat

Glacier ice melt degree-day factor [mm/d/°C] (must be > a_snow).

Afloat

Slow (soil) reservoir storage capacity [mm].

k_slow (k_slow_1)float

Slow reservoir baseflow response factor [1/d].

k_slow_2float

Second soil-layer response factor [1/d] (only with soil_storage_nb=2; must be < k_slow_1 and < k_quick).

betafloat

Quick-flow (surface runoff) coefficient [m^(4/3)/s] of the kinematic-wave overland flow (surface_runoff=’socont_runoff’).

k_quickfloat

Surface runoff response factor [1/d] when a linear storage is used instead (surface_runoff=’linear_storage’); must be > k_slow_1.

k_snowfloat

Response factor of the glacierized-area rain + snowmelt storage [1/d].

k_icefloat

Response factor of the glacierized-area ice melt storage [1/d].

Options

soil_storage_nbint

Number of slow soil reservoirs, 1 (default) or 2. With 2, a constant percolation feeds a second linear soil layer.

surface_runoffstr

Quick-flow method: ‘socont_runoff’ (default, kinematic-wave overland flow) or ‘linear_storage’.

snow_melt_processstr

Snowmelt method (default: ‘melt:degree_day’).

snow_ice_transformationstr or None

Snow-to-ice transformation on the glacier (default: None).

snow_redistributionstr or None

Optional snow redistribution process (e.g. ‘transport:snow_slide’).

glacier_infinite_storagebool

Treat the glacier ice as an infinite storage (default: True).

glacier_modulestr

Glacier formulation to plug in (default: ‘gsm’, the Glacier Sub-Model of GSM-SOCONT: two linear reservoirs for the glacierized-area rain + snowmelt and ice melt).

GR4J

class hydrobricks.models.gr4j.GR4J(name: str = 'gr4j', **kwargs: Any)

Bases: Model

GR4J daily rainfall-runoff model (Perrin et al., 2003).

Parameters:

• X1 (float) – Production store capacity [mm].

• X2 (float) – Groundwater exchange coefficient [mm/d]. Negative = loss, positive = gain.

• X3 (float) – Routing store maximum capacity [mm].

• X4 (float) – Unit hydrograph time base [d]. Must be > 0.5.

• Options

• -------

• discrete (bool) – Build method for the production store and routing. True (default) computes them directly, reproducing the exact discrete GR4J equations. False integrates them with the ODE solver; provided for comparison, it differs from the reference GR4J (continuous integration is not the exact discrete map).

• snow_melt_process (str or None) – Snowmelt method: None (no snow), ‘melt:degree_day’, ‘melt:degree_day_aspect’, ‘melt:temperature_index’, or ‘melt:cemaneige’. ‘melt:temperature_index’ requires a ‘solar_radiation’ forcing, and ‘melt:degree_day_aspect’ an ‘aspect_class’ hydro unit property.

• snow_redistribution (str or None) – Optional snow redistribution process (e.g. ‘transport:snow_slide’).

GR6J

class hydrobricks.models.gr6j.GR6J(name: str = 'gr6j', **kwargs: Any)

Bases: GR4J

GR6J daily rainfall-runoff model (Pushpalatha et al., 2011).

GR6J extends GR4J with two changes aimed at improving low-flow simulation, while keeping the production store, interception, throughfall and ET identical to GR4J:

• a threshold-based groundwater exchange F = X2 (R/X3 - X5) (the GR5J formulation), and

• an additional exponential routing store (coefficient X6) placed in parallel to the power routing store. The UH1 output is split 60% to the power store and 40% to the exponential store.

Parameters:

• X1 (float) – Production store capacity [mm].

• X2 (float) – Groundwater exchange coefficient [mm/d]. Negative = loss, positive = gain.

• X3 (float) – Routing store maximum capacity [mm].

• X4 (float) – Unit hydrograph time base [d]. Must be > 0.5.

• X5 (float) – Groundwater exchange threshold [-]. Sets the routing-store filling ratio at which the exchange changes sign.

• X6 (float) – Exponential store coefficient [mm]. Must be > 0.

• Options

• -------

• discrete (bool) – Build method for the production store and routing. True (default) computes them directly, reproducing the exact discrete equations. False integrates them with the ODE solver (provided for comparison).

• snow_melt_process (str or None) – Snowmelt method: None (no snow), ‘melt:degree_day’, ‘melt:degree_day_aspect’, ‘melt:temperature_index’, or ‘melt:cemaneige’. ‘melt:temperature_index’ requires a ‘solar_radiation’ forcing, and ‘melt:degree_day_aspect’ an ‘aspect_class’ hydro unit property.

• snow_redistribution (str or None) – Optional snow redistribution process (e.g. ‘transport:snow_slide’).

HBV (base class)

class hydrobricks.models.hbv.HBV(name: str = 'hbv', **kwargs: Any)

Bases: Model

Base class for the HBV model family (Bergström, 1976, and successors).

This class holds the structure elements shared by the HBV versions: the snow routine (degree-day melt with liquid water retention and refreezing), the soil moisture routine (beta-function recharge, LP-limited evapotranspiration) and the transformation function (triangular unit hydrograph, MAXBAS). The response routine differs between versions and must be provided by the subclasses through _define_response_structure() (e.g. the non-linear upper zone of HBV-96).

Precipitation undercatch can be corrected with the rainfall and snowfall correction factors rfcf and sfcf (both default 1.0), applied to the rain and snow components at the snow/rain splitter.

The model is integrated by the ODE solver (as Socont), so the results are a continuous approximation of the original discrete HBV formulations.

Options

snow_melt_processstr

Snowmelt method (default: ‘melt:degree_day’). Must be ‘melt:degree_day’ when snow refreezing is enabled.

snow_water_retention_processstr or None

Outflow process of the snowpack liquid water storage (default: ‘outflow:snow_holding’, the HBV holding capacity CWH). None disables the liquid water retention (melt water leaves the snowpack directly).

snow_refreezing_processstr or None

Refreezing process of the retained liquid water (default: ‘refreeze:degree_day’, the HBV refreezing coefficient CFR). None disables refreezing. Requires a snow water retention process.

rain_to_snowpackbool

Route the rain to the snowpack liquid water storage instead of the ground (default: True, as in the original HBV snow routine). The rain is retained in the snowpack (up to the holding capacity CWH) and exposed to refreezing; without snow, it reaches the ground within the same time step. Requires a snow water retention process.

snow_rain_processstr or None

Rain/snow partitioning method (default: None, i.e. ‘snow_rain:linear’, which matches the HBV-96 linear transition over TT ± TTI/2).

snow_redistributionstr or None

Optional snow redistribution process (e.g. ‘transport:snow_slide’).

share_soilbool

Share a single soil moisture storage across all land covers (default: False, i.e. each land cover has its own soil moisture store, as in the original HBV land-use formulation). With several land covers and per-class soils, the soil/recharge parameters (fc, lp, beta) become cover-specific and are exposed with a per-cover suffix (e.g. fc_forest); with a single land cover (or when sharing) the bare aliases (fc, lp, beta) are kept.

glacier_infinite_storagebool

Treat the glacier ice as an infinite storage (default: True), as in Socont.

glacier_modulestr

Glacier formulation to plug in (default: ‘gsm’, the Glacier Sub-Model of GSM-SOCONT: two linear reservoirs for the glacierized-area rain + snowmelt and ice melt).

Land-use classes

Besides the default soil-bearing ground cover, HBV supports the HBV land-use classes as land covers: forest (canopy interception on the rain path), lake (exclusive open-water cover: all precipitation direct, open-water evaporation, linear outflow — its own no-snow structure variant) and glacier (Socont-style: glacier-area rain + snowmelt and ice melt feed two linear sub-basin reservoirs draining to the outlet, with a glacier-free base variant).

HBV-96

class hydrobricks.models.hbv_96.HBV96(name: str = 'hbv96', **kwargs: Any)

Bases: HBV

HBV-96 model (Lindström et al., 1997).

HBV-96 implements the response routine as an upper, non-linear reservoir and a lower, linear reservoir:

• recharge enters the upper zone (UZ),

• a constant-rate percolation (PERC) feeds the lower zone (LZ),

• an optional capillary transport (CFLUX) returns water from the upper zone to the soil moisture storage,

• upper zone runoff: Q0 = k_uz × UZ^(1 + alpha),

• lower zone runoff: Q1 = k_lz × LZ,

• Q0 + Q1 are routed through the MAXBAS triangular unit hydrograph.

Parameters (literature names as aliases)

ttfloat

Threshold/melting temperature [°C].

rfcffloat

Rainfall correction factor [-] (default 1.0; corrects rain gauge undercatch).

sfcffloat

Snowfall correction factor [-] (default 1.0; corrects snow gauge undercatch).

cfmaxfloat

Snow melt degree-day factor [mm/d/°C].

cfrfloat

Refreezing coefficient [-] (typically 0.05).

cwhfloat

Snowpack liquid water holding capacity, fraction of SWE [-] (typically 0.1).

fcfloat

Soil moisture storage capacity (FC) [mm].

lpfloat

Soil moisture fraction above which ET reaches the potential rate [-].

betafloat

Shape coefficient of the recharge function [-].

cfluxfloat

Maximum capillary flux from the upper zone to the soil moisture [mm/d].

k_uzfloat

Upper zone response factor [mm^(-alpha)/d].

alphafloat

Non-linearity coefficient of the upper zone [-].

percfloat

Constant percolation rate to the lower zone [mm/d].

k_lzfloat

Lower zone (linear) response factor [1/d].

maxbasfloat

Base of the triangular unit hydrograph [d].