API documentation for the `hydrology_model` module#

The hydrology_model module creates a HydrologyModel class as a child of the BaseModel class.

There are still a number of open TODOs related to process implementation and improvement , time step and model structure, and units and module coordination.

Todo

processes

spin up soil moisture
set boundaries for river discharge
update infiltration process

Todo

time step and model structure

find a way to load daily (precipitation) data and loop over daily time_index
potentially move calculate_drainage_map to core
add abiotic constants from config

Todo

units and module coordination

change temperature to Kelvin

Classes:

HydrologyModel(data, core_components, ...[, ...])

A class describing the hydrology model.

class virtual_ecosystem.models.hydrology.hydrology_model.HydrologyModel(data: Data, core_components: CoreComponents, initial_soil_moisture: float, initial_groundwater_saturation: float, p_wet_wet: float, p_wet_dry: float, rainfall_shape_parameter: float, rainfall_scale_parameter: float, model_constants: HydrologyConstants = HydrologyConstants(), abiotic_constants: AbioticConstants = AbioticConstants(), pyrealm_core_constants: CoreConst = PyrealmCoreConst(), static: bool = False)[source]#

A class describing the hydrology model.

Parameters:

data – The data object to be used in the model.
core_components – The core components used across models.
initial_soil_moisture – The initial volumetric relative water content [unitless] for all layers. This will be converted to soil moisture in mm.
initial_groundwater_saturation – Initial level of groundwater saturation (between 0 and 1) for all layers and grid cells identical. This will be converted to groundwater storage in mm.
model_constants – Set of constants for the hydrology model.
abiotic_constants – Some abiotic constants are required in the hydrology model.
pyrealm_core_constants – Core constants for the pyrealm package.
static – Boolean flag indicating if the model should run in static mode.

Methods:

`check_init_data`()	Check the init data contains the required variables.
`cleanup`()	Placeholder function for hydrology model cleanup.
`from_config`(data, configuration, core_components)	Factory function to initialise the hydrology model from configuration.
`spinup`()	Placeholder function to spin up the hydrology model.
`update`(time_index, **kwargs)	Function to update the model.

Attributes:

`core_constants`	The core constants used in the model.
`data`	A Data instance providing access to the shared simulation data.
`drainage_map`	Upstream neighbours for the calculation of horizontal flow.
`grid`	The Grid details used in the model.
`initial_groundwater_saturation`	Initial level of groundwater saturation for all layers identical.
`initial_soil_moisture`	Initial volumetric relative water content [unitless] for all layers and grid cells identical.
`layer_structure`	The LayerStructure details used in the model.
`model_constants`	Set of constants for the hydrology model
`model_timing`	The ModelTiming details used in the model.
`model_update_bounds`	Bounds on model update frequencies.
`p_wet_dry`	Probability a wet day follows a dry day.
`p_wet_wet`	Probability a wet day follows a wet day.
`pyrealm_core_constants`	Set of core constants for the pyrealm package
`rainfall_scale_parameter`	Scale parameter of Gamma distribution controlling magnitude of rainfall.
`rainfall_shape_parameter`	Shape parameter of Gamma distribution controlling rainfall variability.
`soil_layer_thickness_mm`	Soil layer thickness in mm.
`surface_layer_index`	Surface layer index.
`vars_populated_by_first_update`	Variables that are initialised by the model during the first update.
`vars_populated_by_init`	Variables that are initialised by the model during the setup.
`vars_required_for_init`	Required variables for model initialisation.
`vars_required_for_update`	Variables that are required by the update method of the model.
`vars_updated`	Variables that are updated by the model.

check_init_data() → None#

Check the init data contains the required variables.

This method is used to check that the set of variables defined in the vars_required_for_init class attribute are present in the Data instance used to create a new instance of the class.

Raises:: ValueError – If the Data instance does not contain all the required variables or if those variables do not map onto the required axes.

cleanup() → None[source]#: Placeholder function for hydrology model cleanup.

core_constants: CoreConstants#: The core constants used in the model.

data: Data#: A Data instance providing access to the shared simulation data.

drainage_map: dict#: Upstream neighbours for the calculation of horizontal flow.

classmethod from_config(data: Data, configuration: CompiledConfiguration, core_components: CoreComponents) → HydrologyModel[source]#

Factory function to initialise the hydrology model from configuration.

This function unpacks the relevant information from the configuration file, and then uses it to initialise the model. If any information from the config is invalid rather than returning an initialised model instance an error is raised.

Parameters:

data – A Data instance.
configuration – A validated Virtual Ecosystem model configuration object.
core_components – The core components used across models.

grid: Grid#: The Grid details used in the model.

initial_groundwater_saturation: float#: Initial level of groundwater saturation for all layers identical.

initial_soil_moisture: float#: Initial volumetric relative water content [unitless] for all layers and grid cells identical.

layer_structure: LayerStructure#: The LayerStructure details used in the model.

model_constants: HydrologyConstants#: Set of constants for the hydrology model

model_timing: ModelTiming#: The ModelTiming details used in the model.

model_update_bounds: tuple[Quantity, Quantity] = (<Quantity(1, 'day')>, <Quantity(1, 'month')>)#

Bounds on model update frequencies.

This class attribute defines two time intervals that define a lower and upper bound on the update frequency that can reasonably be used with a model. Models updated more often than the lower bound may fail to capture transient dynamics and models updated more slowly than the upper bound may fail to capture important temporal patterns.

p_wet_dry: float#: Probability a wet day follows a dry day.

p_wet_wet: float#: Probability a wet day follows a wet day.

pyrealm_core_constants: PyrealmCoreConst#: Set of core constants for the pyrealm package

rainfall_scale_parameter: float#: Scale parameter of Gamma distribution controlling magnitude of rainfall.

rainfall_shape_parameter: float#: Shape parameter of Gamma distribution controlling rainfall variability.

soil_layer_thickness_mm: np.ndarray#: Soil layer thickness in mm.

spinup() → None[source]#: Placeholder function to spin up the hydrology model.

surface_layer_index: int#: Surface layer index.

update(time_index: int, **kwargs: Any) → None#

Function to update the model.

If the model is static, the inner update method, self._update will only run once, at most.

Parameters:

time_index – The index representing the current time step in the data object.
**kwargs – Further arguments to the update method.

vars_populated_by_first_update: tuple[str, ...] = ('interception', 'precipitation_surface', 'surface_runoff', 'bypass_flow', 'soil_evaporation', 'vertical_flow', 'subsurface_flow', 'baseflow', 'surface_runoff_routed_plus_local', 'subsurface_runoff_routed_plus_local', 'river_discharge_rate', 'total_runoff', 'canopy_evaporation')#

Variables that are initialised by the model during the first update.

These are the variables that are initialised by the model and stored in the data object when running the update method for the first time. They will be available for other models to use in their update methods but not in the setup methods.

vars_populated_by_init: tuple[str, ...] = ('soil_moisture', 'matric_potential', 'groundwater_storage', 'aerodynamic_resistance_soil', 'aerodynamic_resistance_canopy', 'specific_heat_air', 'stomatal_conductance', 'latent_heat_vapourisation', 'density_air', 'condensation')#

Variables that are initialised by the model during the setup.

These are the variables that are initialised by the model and stored in the data object when running the setup method and that will be available for other models to use in their own setup or update methods.

vars_required_for_init: tuple[str, ...] = ('layer_heights', 'elevation', 'air_temperature_ref', 'atmospheric_pressure_ref')#

Required variables for model initialisation.

This class property defines a set of variable names that must be present in the Data instance used to initialise an instance of this class. It is a tuple containing zero or more tuples, each providing a variable name and then a tuple of zero or more core axes that the variable must map onto.

For example: (('temperature', ('spatial', 'temporal')),)

vars_required_for_update: tuple[str, ...] = ('air_temperature', 'relative_humidity', 'atmospheric_pressure', 'vapour_pressure_deficit', 'precipitation', 'wind_speed', 'leaf_area_index', 'layer_heights', 'soil_moisture', 'transpiration', 'density_air', 'aerodynamic_resistance_canopy', 'specific_heat_air', 'stomatal_conductance', 'net_radiation', 'condensation')#

Variables that are required by the update method of the model.

These variables should have been initialised by another model or loaded from external sources, but in either case they will be available in the data object.

vars_updated: tuple[str, ...] = ('interception', 'canopy_evaporation', 'precipitation_surface', 'soil_moisture', 'surface_runoff', 'vertical_flow', 'soil_evaporation', 'surface_runoff_routed_plus_local', 'subsurface_runoff_routed_plus_local', 'total_runoff', 'river_discharge_rate', 'matric_potential', 'groundwater_storage', 'subsurface_flow', 'baseflow', 'bypass_flow', 'aerodynamic_resistance_soil')#

Variables that are updated by the model.

At the moment, this tuple is used to decide which variables to output from the Data object, i.e. every variable updated by a model used in the specific simulation. It is also be used warn if multiple models will be updating the same variable and to verify that these variables are indeed initialised by another model, and therefore will be available.

API documentation for the hydrology_model module#

API documentation for the `hydrology_model` module#