Modules

Pluggable sub-model strategies that a model can plug in to vary one part of its structure (e.g. the glacier formulation). See glacier modules for usage.

Pluggable sub-model modules for the hydrological models.

Modules are strategy components that a model can plug in to vary a part of its structure without changing the model itself (e.g. the glacier formulation). They are selected by a model option (a registry name) or supplied as an instance.

Module base

class hydrobricks.modules.base.Module

Bases: ABC

Base class for the pluggable sub-model modules.

A module is a swappable strategy a model plugs in to vary one part of its structure without changing the model itself (e.g. the glacier formulation). Each module category is a direct subclass of Module (e.g. GlacierModule) that defines the category’s interface and its own registry of named concrete formulations. Concrete modules register under a name with the register decorator, and a model resolves one with <Category>.get_module(name_or_instance).

This base provides only the shared pluggability machinery (registry, registration and resolution); the category subclasses provide the actual interface.

classmethod get_module(module: str | Module) → Module

Resolve a module of this category from a registry name or an instance.

Parameters:

module – Either a registered module name (e.g. 'gsm') or a module instance of this category (for custom user-defined formulations).

Returns:

The resolved module instance.

Return type:

Module

Raises:

ConfigurationError – If the name is not registered in this category (or an instance of another category is given).

classmethod register(name: str)

Return a class decorator registering a concrete module under name.

Example

>>> @GlacierModule.register("gsm")
... class GSM(GlacierModule):
...     ...

Glacier modules

class hydrobricks.modules.glacier.GSM

Bases: GlacierModule

Glacier Sub-Model (GSM), as in GSM-SOCONT (Schaefli et al., 2005).

The glacierized area sends its rain + snowmelt and its ice melt to two catchment-level linear reservoirs draining directly to the outlet, bypassing the soil routine. Ice melt is suppressed while snow covers the ice (no_melt_when_snow_cover); the ice is treated as an infinite storage by default (glacier_infinite_storage). The two reservoirs are shared by all glacier covers.

ICEMELT_STORAGE = 'glacier_area_icemelt_storage'

RAIN_SNOWMELT_STORAGE = 'glacier_area_rain_snowmelt_storage'

add_bricks(structure: dict[str, Any], glacier_names: list[str], *, melt_process: str, options: dict[str, Any]) → None

Add the glacier bricks for the given glacier covers into structure.

Parameters:

• structure – The model structure dictionary to add the bricks to (modified in place).

• glacier_names – The names of the glacier land covers.

• melt_process – The ice melt process kind (e.g. 'melt:degree_day'), usually the model’s snow melt process.

• options – The model options (a module reads its own configuration from here, e.g. glacier_infinite_storage).

land_cover_keys(glacier_names: list[str]) → set[str]

Return the structure keys that are glacier land covers.

These are excluded from the glacier-free base variant (while any shared, catchment-level bricks the module adds, such as sub-basin reservoirs, stay in the base so the sub-basin owns and shares them).

parameter_aliases(glacier_names: list[str]) → dict[str, list[str]]

Return the glacier-specific parameter aliases (e.g. reservoir factors).

class hydrobricks.modules.glacier.GlacierModule

Bases: Module

Pluggable glacier formulation for the hydrological models.

A glacier module owns everything glacier-specific so that the same formulation can be shared across models (e.g. Socont and HBV) and alternative formulations swapped in. It contributes:

• the glacier-related bricks added to the model structure (add_bricks),

• the structure keys that are glacier land covers, so the model can split a glacier-free base from a with-glacier variant (land_cover_keys),

• the glacier-specific parameter aliases (parameter_aliases).

The melt parameters (e.g. a_ice) and the a_snow < a_ice constraint are derived generically by ParameterSet from the melt process placed on the glacier land cover, so a module only needs to expose its own extra aliases (such as the response factors of its reservoirs).

Resolve a glacier module with GlacierModule.get_module(name_or_instance) and register a new one with the @GlacierModule.register("name") decorator.

abstractmethod add_bricks(structure: dict[str, Any], glacier_names: list[str], *, melt_process: str, options: dict[str, Any]) → None

Add the glacier bricks for the given glacier covers into structure.

Parameters:

• structure – The model structure dictionary to add the bricks to (modified in place).

• glacier_names – The names of the glacier land covers.

• melt_process – The ice melt process kind (e.g. 'melt:degree_day'), usually the model’s snow melt process.

• options – The model options (a module reads its own configuration from here, e.g. glacier_infinite_storage).

abstractmethod land_cover_keys(glacier_names: list[str]) → set[str]

Return the structure keys that are glacier land covers.

These are excluded from the glacier-free base variant (while any shared, catchment-level bricks the module adds, such as sub-basin reservoirs, stay in the base so the sub-basin owns and shares them).

abstractmethod parameter_aliases(glacier_names: list[str]) → dict[str, list[str]]

Return the glacier-specific parameter aliases (e.g. reservoir factors).