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_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_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) → 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)

select_hydro_unit_brick(name: str) → None

Select a hydro unit brick

Parameters:

name – Name of the hydro unit brick

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 model implementation