API for the hydrology_tools module#

Functions to set up hydrology model and select data for current time step.

Functions:

calculate_effective_saturation(...)

Calculate the effective soil saturation based on the soil moisture.

calculate_psychrometric_constant(...)

Calculate the psychrometric constant.

check_monthly_mass_balance(drainage_map, ...)

Check that total monthly streamflow at outlet(s) does not exceed total precip.

check_precipitation_surface(...)

Check that precipitation at the surface is not negative.

initialise_atmosphere_for_hydrology(data, ...)

Initialise atmospheric variables required for hydrology model.

initialise_soil_moisture_mm(layer_structure, ...)

Initialise soil moisture in mm.

setup_hydrology_input_current_timestep(data, ...)

Select and pre-process inputs for hydrology.update() for current time step.
virtual_ecosystem.models.hydrology.hydrology_tools.calculate_effective_saturation(soil_moisture: ndarray[tuple[Any, ...], dtype[floating]], soil_moisture_saturation: float | ndarray[tuple[Any, ...], dtype[floating]], soil_moisture_residual: float | ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[floating]][source]#

Calculate the effective soil saturation based on the soil moisture.

This is kept as a separate function because the soil model also needs to use this quantity.

Parameters:

  • soil_moisture – Volumetric relative water content in top soil, [unitless]

  • soil_moisture_saturation – Soil moisture saturation, [unitless]

  • soil_moisture_residual – Residual soil moisture, [unitless]

Returns:

The effective saturation of the soil [unitless]

virtual_ecosystem.models.hydrology.hydrology_tools.calculate_psychrometric_constant(atmospheric_pressure: ndarray[tuple[Any, ...], dtype[floating]], latent_heat_vapourization: ndarray[tuple[Any, ...], dtype[floating]], specific_heat_air: ndarray[tuple[Any, ...], dtype[floating]], molecular_weight_ratio_water_to_dry_air: float)[source]#

Calculate the psychrometric constant.

NOTE this might be replaced with pyrealm implementation

Parameters:

  • atmospheric_pressure – Atmospheric pressure, [KPa].

  • latent_heat_vapourization – Latent heat of vaporization, [kJ kg-1]

  • specific_heat_air – Specific heat of air at constant pressure, [kJ kg-1 K-1]

  • molecular_weight_ratio_water_to_dry_air – Ratio of molecular weights of water to dry air

Returns:

Psychrometric constant in [kPa K-1]

virtual_ecosystem.models.hydrology.hydrology_tools.check_monthly_mass_balance(drainage_map: dict[int, list[int]], surface_channel_inflow_mm: ndarray[tuple[Any, ...], dtype[floating]], monthly_precipitation_mm: ndarray[tuple[Any, ...], dtype[floating]], monthly_evaporation_mm: ndarray[tuple[Any, ...], dtype[floating]]) → None[source]#

Check that total monthly streamflow at outlet(s) does not exceed total precip.

The function identifies the outlet cells (cells with no downstream connections) from the drainage map. It then sums the surface channel inflow at these outlet cells and compares it to the total catchment precipitation minus total evaporation. If the streamflow exceeds the available water, an AssertionError is raised.

If no true outlet cells exist, the flow from the lowest cells (cells with fewest upstream connections) is used for the check.

Parameters:

  • drainage_map – Dict mapping each cell ID -> list of upstream cell IDs

  • surface_channel_inflow_mm – Monthly total surface channel inflow per cell, [mm]

  • monthly_precipitation_mm – Monthly total precipitation per cell, [mm]

  • monthly_evaporation_mm – Monthly total evaporation per cell, [mm]

Raises:

AssertionError – if monthly streamflow exceeds total catchment precipitation.

virtual_ecosystem.models.hydrology.hydrology_tools.check_precipitation_surface(precipitation_surface: ndarray[tuple[Any, ...], dtype[floating]]) → None[source]#

Check that precipitation at the surface is not negative.

Parameters:

precipitation_surface – Precipitation at the surface

Returns:

error if precipitation is negative in any grid cell

virtual_ecosystem.models.hydrology.hydrology_tools.initialise_atmosphere_for_hydrology(data: Data, model_constants: HydrologyConstants, abiotic_constants: AbioticConstants, core_constants: CoreConstants, layer_structure: LayerStructure)[source]#

Initialise atmospheric variables required for hydrology model.

Parameters:

  • data – Data object

  • model_constants – Set of constants for hydrology model

  • abiotic_constants – Set of constants for abiotic model

  • core_constants – Set of constants shared across all models

  • layer_structure – The LayerStructure instance for a simulation

Returns:

aerodynamic_resistance_soil, aerodynamic_resistance_canopy,

stomatal_conductance, density_air, specific_heat_air, latent_heat_vapourisation

virtual_ecosystem.models.hydrology.hydrology_tools.initialise_soil_moisture_mm(layer_structure: LayerStructure, initial_soil_moisture: float, soil_layer_thickness: ndarray[tuple[Any, ...], dtype[floating]]) → DataArray[source]#

Initialise soil moisture in mm.

Parameters:

  • layer_structure – LayerStructure object that contains information about the number and identities of vertical layers

  • initial_soil_moisture – Initial relative soil moisture, dimensionless

  • soil_layer_thickness – The soil layer thickness in mm.

Returns:

soil moisture, [mm]

virtual_ecosystem.models.hydrology.hydrology_tools.setup_hydrology_input_current_timestep(data: Data, time_index: int, days: int, seed: None | int, layer_structure: LayerStructure, soil_layer_thickness_mm: ndarray[tuple[Any, ...], dtype[floating]], soil_moisture_saturation: float | ndarray[tuple[Any, ...], dtype[floating]], soil_moisture_residual: float | ndarray[tuple[Any, ...], dtype[floating]], p_wet_wet: float, p_wet_dry: float, shape_parameter: float, scale_parameter: float) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Select and pre-process inputs for hydrology.update() for current time step.

The hydrology model currently loops over 30 days per month. Atmospheric variables in the canopy and near the surface are selected here and kept constant for the whole month. Daily timeseries of precipitation and canopy transpiration are generated from monthly values in data to be used in the daily loop. States of other hydrology variables are selected and updated in the daily loop.

The function returns a dictionary with the following variables:

  • surface_temperature (TODO switch to subcanopy_temperature)

  • surface_humidity (TODO switch to subcanopy_humidity)

  • surface_pressure (TODO switch to subcanopy_pressure)

  • surface_wind_speed (TODO switch to subcanopy_wind_speed)

  • atmospheric_pressure_canopy

  • air_temperature_canopy

  • vapour_pressure_deficit_canopy

  • leaf_area_index_sum

  • current_precipitation

  • current_transpiration

  • current_soil_moisture

  • top_soil_moisture_saturation

  • top_soil_moisture_residual

  • groundwater_storage

  • condensation

Parameters:

  • data – Data object that contains inputs from the microclimate model, the plant model, and the hydrology model that are required for current update

  • time_index – Time index of current time step

  • days – Number of days in core time step

  • seed – Seed for random rainfall generator

  • layer_structure – The LayerStructure instance for a simulation.

  • soil_layer_thickness_mm – The thickness of the soil layer, [mm]

  • soil_moisture_saturation – Soil moisture saturation, unitless

  • soil_moisture_residual – Soil moisture residual, unitless

  • p_wet_wet – Probability a wet day follows a wet day.

  • p_wet_dry – Probability a wet day follows a dry day.

  • shape_parameter – Shape parameter of the Gamma distribution controlling rainfall variability.

  • scale_parameter – Scale parameter of the Gamma distribution controlling absolute magnitude of rainfall.

Returns:

dictionary with all variables that are required to run one hydrology update() daily loop