Models

Base model

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

Bases: ABC

Base abstract class for hydrological models

add_action(action: Action) → bool[source]

Add an action to the model.

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

add_recordings(request: RecordingRequest) → None[source]

Enable the recording of specific stores/fluxes.

A targeted alternative to record_all=True: records only the items needed (e.g. by an auxiliary calibration observation). Must be called before setup() (the recordings are part of the model settings used to build the model).

Parameters:: request – The stores/fluxes to record (see RecordingRequest).
Raises:: ModelError – If the model has already been initialized.

create_config_file(directory: str, name: str, file_type: str = 'both') → None[source]

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 | Path | None = None) → str[source]

Write the model outputs to a netCDF file.

Parameters:: path – Path to the output directory in which the results.nc file is written. If None, the output path given to setup() is used.
Returns:: The full path to the written netCDF file (<path>/results.nc), ready to pass to Results.
Return type:: str
Raises:: ModelError – If no path is given and the model has no output path (setup not called).

eval(metric: str, observations: np.ndarray | Any, warmup: int = 0, period: Period | tuple | None = None) → float[source]

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 observations: an array with dates matching the simulated series, or a DischargeObservations (sliced by its own dates when a period is given).
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). Not needed when the model was set up with a spin-up.
period – Evaluate on this date slice of the simulation only (a Period or (start, end) pair). The period must be covered by the modelling period. Mutually exclusive with warmup.

Return type:

The value of the selected metric.

generate_parameters() → ParameterSet[source]

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[source]: Get the number of actions (types of actions) registered in the model.

get_outlet_discharge() → numpy.ndarray[source]: Get the computed outlet discharge.

get_recorded_hydro_unit_areas() → numpy.ndarray[source]: Get the hydro unit areas [m2], in the order of the recorded series.

get_recorded_hydro_unit_fractions(label: str) → numpy.ndarray[source]

Get a recorded land-cover fraction series directly from memory.

Fractions are recorded only when record_all is enabled. With a glacier evolution action the fraction evolves over time; otherwise it is constant.

Parameters:

label – The land cover name (e.g. ‘glacier’).

Returns:

The fraction series as a 2D array of shape (n_hydro_units, n_timesteps),
matching the convention of Results.get_hydro_units_values.

get_recorded_hydro_unit_ids() → numpy.ndarray[source]: Get the hydro unit ids, in the order of the recorded series.

get_recorded_hydro_unit_values(label: str) → numpy.ndarray[source]

Get a recorded hydro-unit component series directly from memory.

Reads the in-memory logger (no netCDF dump), which makes it suitable for use inside a calibration loop. The component must have been recorded (see record_all).

Parameters:

label – The recorded component label (e.g. ‘glacier_snowpack:snow_content’).

Returns:

The recorded series as a 2D array of shape (n_hydro_units, n_timesteps),
matching the convention of Results.get_hydro_units_values. Values are
NaN for hydro units to which the component does not apply.

get_recorded_labels() → list[str][source]

Get the labels of the recorded hydro-unit components (in-memory).

These are the components that can be retrieved with get_recorded_hydro_unit_values() without dumping the outputs to a netCDF file. The set depends on what was recorded (use record_all=True to record everything).

Returns:: The list of recorded component labels (e.g. ‘glacier
Return type:: melt:output’).

get_recorded_time() → pandas.DatetimeIndex[source]

Reconstruct the daily date axis of the recorded series.

The model runs on a daily time step, so the axis is rebuilt from the modelling period rather than read from the engine.

Return type:: A daily DatetimeIndex spanning the modelling period.

get_results(output_path: str | Path | None = None) → Results[source]

Dump the outputs and return a Results reader.

Convenience wrapper around dump_outputs() and Results that removes the need to know the results.nc filename convention: it writes the outputs and returns a ready-to-use reader.

Parameters:: output_path – Output directory to write results.nc into. If None, the output path given to setup() is used.
Returns:: A reader opened on the freshly written results file.
Return type:: Results

get_sporadic_action_item_count() → int[source]: Get the number of sporadic (non-recursive) action items (individual triggers) registered in the model.

get_structure_graph(structure_id: int = 1, with_forcing: bool = True) → StructureGraph[source]

Build the model structure graph (bricks, processes, fluxes, splitters).

The graph reflects the complete structure (including the snow routine, the precipitation splitters, the forest canopy and the glacier reservoirs), is available right after model construction (no setup/run needed), and can be serialized, summarized and plotted.

Parameters:

structure_id – The structure variant to inspect (default 1, the primary). Models with glacier/lake covers define several variants.
with_forcing – Include the meteorological forcing inputs (precipitation, temperature, pet) as source nodes. Set to False for a less cluttered graph.

Returns:

The structure graph object.

Return type:

StructureGraph

get_total_et() → float[source]: Get the total amount of water lost by evapotranspiration.

get_total_outlet_discharge() → float[source]: Get the outlet discharge total.

get_total_snow_storage_changes() → float[source]: Get the total change in snow storage.

get_total_water_storage_changes() → float[source]: Get the total change in water storage.

initialize_state_variables(parameters: ParameterSet, forcing: Forcing | None = None) → None[source]

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.

plot_structure(path: str | None = None, fmt: str = 'png', view: bool = False, legend: bool = True, with_forcing: bool = True, nodesep: float = 0.5, ranksep: float = 0.7, dpi: int = 200, structure_id: int = 1)[source]

Plot the model structure as a directed graph (requires graphviz).

Parameters:

path – Output file path without extension; if None, the graph object is returned without writing a file.
fmt – Output format (e.g. ‘png’, ‘pdf’, ‘svg’). Vector formats (‘pdf’, ‘svg’) are resolution-independent and give the sharpest result.
view – Open the rendered file with the default viewer.
legend – Add a legend describing the node and flux styles (default True).
with_forcing – Include the meteorological forcing inputs (precipitation, temperature, pet). Set to False for a less cluttered diagram.
nodesep – Graphviz spacing (inches) between nodes in a rank and between ranks; larger values give the diagram more breathing room.
ranksep – Graphviz spacing (inches) between nodes in a rank and between ranks; larger values give the diagram more breathing room.
dpi – Raster (e.g. PNG) resolution in dots per inch; raise it for a crisper image. Ignored for vector formats.
structure_id – The structure variant to plot (default 1, the primary).

Return type:

The graphviz.Digraph object.

print_structure(structure_id: int = 1) → None[source]: Print a compact textual summary of the model structure.

run(parameters: ParameterSet, forcing: Forcing | None = None) → None[source]

Setup and run the model.

Parameters:

parameters – The parameters for the given model.
forcing – The forcing data.

set_forcing(forcing: Forcing) → None[source]

Set the forcing data.

Parameters:: forcing – The forcing data.

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
period – The modelling period, as a Period or a (start, end) pair (e.g. periods.calibration from a Periods). Mutually exclusive with start_date/end_date.
spinup – The spin-up duration: the first days/years of the modelling period are replayed (unlogged) on every run to initialize the states, then the run restarts at the period start with the warmed-up states. Either a number of days (int) or a string like '4y' (calendar years). A spin-up longer than the period is clamped to it. Default: 0 (no spin-up)

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.setup(hydro_units, './output', period=periods.calibration,
...             spinup='4y')

summary(structure_id: int = 1) → str[source]: Return a compact textual summary of the model structure.

Model settings

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

Bases: object

Base class for the model settings

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

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[source]

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[source]

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[source]

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[source]

Add logging to an item

Parameters:: item – Name of the item

add_process_output(target: str) → None[source]

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[source]

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[source]

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[source]

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, snow_sublimation_process: str | None = None, rain_to_snowpack: bool = False, forest_interception: bool = False) → None[source]

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’.
snow_sublimation_process – Sublimation process removing snow water equivalent directly to the atmosphere (optional). One of ‘sublimation:constant’ or ‘sublimation:pet’.
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.
forest_interception – Add a canopy interception store on each forest land cover (default False). When False, forest covers behave like a generic soil cover.

get_structure() → list[source]

Export the model structure (bricks, processes, fluxes, splitters).

Returns:

A list of structure-variant dicts (see SettingsModel.get_structure in the C++
bindings); used to build the model structure graph.

record_brick_state(brick: str, item: str) → None[source]

Record a state (e.g. a content) of a hydro-unit brick.

Parameters:

brick – Name of the brick (e.g. 'glacier_snowpack').
item – Name of the item to log (e.g. 'snow_content'). The recorded label is '{brick}:{item}'.

record_fractions(record: bool = True) → None[source]

Record the time-varying land-cover fractions.

Enabled automatically with record_all; can be enabled on its own for selective recording (e.g. when an auxiliary observation needs the land-cover areas without logging every component).

Parameters:: record – True to record the fractions.

record_process_output(brick: str, process: str, item: str = 'output') → None[source]

Record an output of a process of a hydro-unit brick.

Parameters:

brick – Name of the brick holding the process (e.g. 'glacier').
process – Name of the process (e.g. 'melt').
item – Name of the item to log (default 'output'). The recorded label is '{brick}:{process}:{item}'.

select_hydro_unit_brick(name: str) → None[source]

Select a hydro unit brick

Parameters:: name – Name of the hydro unit brick

set_current_brick_computed_directly() → None[source]: 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[source]

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[source]: Set all process outputs as instantaneous

set_process_outputs_as_static() → None[source]: Set all process outputs as static

set_spinup_days(days: int) → None[source]

Set the spin-up duration.

The first days of the modelling period are replayed (unlogged) on every run to initialize the states, then the run restarts at the period start.

Parameters:: days – Number of days of the modelling period replayed as spin-up.

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

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

Custom structures

A model whose full structure is declared as data (a YAML file or a dict).

CustomModel builds the same kind of structure the pre-built model classes define in code — bricks (stores and land covers), their processes, and the fluxes routing the water between bricks or to the outlet — from a declarative structure definition. The parameters are derived from the declared process kinds exactly as for the pre-built models (generate_parameters()), so a custom structure is calibratable out of the box.

Example structure file (a simplified SOCONT-like model):

name: my_model

options:
  snow_melt_process: melt:degree_day

bricks:
  open:                       # a land cover (must match land_cover_names)
    kind: land_cover
    processes:
      infiltration: {kind: infiltration:socont, target: slow_reservoir}
      runoff: {kind: outflow:rest, target: surface_runoff}
  slow_reservoir:
    kind: storage             # attached to each hydro unit by default
    parameters: {capacity: 200}
    processes:
      et: {kind: et:socont}   # ET needs no target (to the atmosphere)
      outflow: {kind: outflow:linear, target: outlet}
      overflow: {kind: overflow, target: outlet}
  surface_runoff:
    kind: storage
    processes:
      runoff: {kind: outflow:linear, target: outlet}

aliases:
  slow_reservoir:capacity: A
  slow_reservoir:response_factor: k_slow
  surface_runoff:response_factor: k_quick

constraints:
  - [k_slow, "<", k_quick]

The precipitation splitters (rain/snow) and the per-cover snowpacks are generated from the options (the same snow options every model supports: with_snow, snow_melt_process, snow_redistribution, …), so the declared bricks start where the snow routine ends. A process routes its output with target (a declared brick, a generated one such as <cover>_snowpack, or outlet) or fans out with targets (a list); log: true records the process output, and instantaneous: true makes the flux instantaneous. Bricks attach to each hydro unit by default; use attach_to: sub_basin for catchment-level stores.

class hydrobricks.models.custom.CustomModel(structure: str | Path | dict, name: str | None = None, **kwargs: Any)[source]

Bases: Model

A model whose structure is declared as data (YAML file or dict).

See the module docstring for the structure definition schema. The snow routine and the precipitation splitters are generated from the declared options (overridable as keyword arguments, like for any model), and the parameters are derived from the declared process kinds — so generate_parameters(), calibration and project files work as for the pre-built models.

Parameters:

structure – Path to a YAML structure file, or an equivalent (already parsed) dict.
name – Optional model name (defaults to the structure’s name, else 'custom').
**kwargs – The usual model keyword arguments (solver, record_all, land_cover_types, land_cover_names) plus any snow option declared in the structure’s options.

GSM-Socont

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

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’).
snow_sublimation_processstr or None: Optional snow sublimation process removing snow directly to the atmosphere (default: None). One of ‘sublimation:constant’ or ‘sublimation:pet’.
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)[source]

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’).
snow_sublimation_process (str or None) – Optional snow sublimation process removing snow directly to the atmosphere (default: None). One of ‘sublimation:constant’ or ‘sublimation:pet’.

GR6J

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

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’).
snow_sublimation_process (str or None) – Optional snow sublimation process removing snow directly to the atmosphere (default: None). One of ‘sublimation:constant’ or ‘sublimation:pet’.

HBV (base class)

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

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’).
snow_sublimation_processstr or None: Optional snow sublimation process removing snow directly to the atmosphere (default: None). One of ‘sublimation:constant’ or ‘sublimation:pet’.
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.
forest_interceptionbool: Add a canopy interception store on each forest land cover (default: False). When enabled, the canopy intercepts rain (capacity ic), evaporates at the potential rate and passes the excess as throughfall; when disabled, a forest cover behaves like a generic soil cover.
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 open cover, HBV supports the HBV land-use classes as land covers: forest (an optional canopy interception on the rain path, enabled with forest_interception=True), 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)[source]

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].