API documentation for the model_config module#
The model_config defines configuration
dataclasses containing parameters required by the
hydrology_model. These parameters are
constants in that they should not be changed during a particular simulation.
Note that soil parameters vary strongly with soil type and can change over time. The current default values are average best estimates within reasonable bounds.
Classes:
|
Root configuration class for the hydrology model. |
|
Dataclass to store all constants for the hydrology model. |
- class virtual_ecosystem.models.hydrology.model_config.HydrologyConfiguration(*, static: bool = False, initial_soil_moisture: Annotated[float, Ge(ge=0), Le(le=1)] = 0.5, initial_groundwater_saturation: Annotated[float, Ge(ge=0), Le(le=1)] = 0.9, p_wet_wet: float = 0.6, p_wet_dry: float = 0.3, rainfall_shape_parameter: float = 1.5, rainfall_scale_parameter: float = 1.0, constants: HydrologyConstants = HydrologyConstants(soil_moisture_residual=0.175, soil_moisture_saturation=0.51, saturated_hydraulic_conductivity=3.5e-05, van_genuchten_nonlinearily_parameter=1.598, intercept_parameters=(0.935, 0.498, 0.00575), veg_density_param=0.046, groundwater_capacity=500, bypass_flow_coefficient=1.0, extinction_coefficient_global_radiation=0.74, max_percolation_rate_uzlz=2.7, groundwater_loss=1, reservoir_const_upper_groundwater=20, reservoir_const_lower_groundwater=20, initial_aerodynamic_resistance_soil=12.5, drag_coefficient_evaporation=0.2, initial_stomatal_conductance=1000.0, pore_connectivity_parameter=0.5, air_entry_potential_inverse=0.042, m_to_kpa=9.804))[source]#
Root configuration class for the hydrology model.
Attributes:
Constants values for hydrology model.
Initial ground water saturation for all layers, unitless
Initial soil moisture for all layers
Probability a wet day follows a dry day
Probability a wet day follows a wet day
Scale parameter of the Gamma distribution controlling magnitude of rainfall
Shape parameter of the Gamma distribution controlling rainfall variability
- constants: HydrologyConstants#
Constants values for hydrology model.
- rainfall_scale_parameter: float#
Scale parameter of the Gamma distribution controlling magnitude of rainfall
- class virtual_ecosystem.models.hydrology.model_config.HydrologyConstants(*, soil_moisture_residual: float = 0.175, soil_moisture_saturation: float = 0.51, saturated_hydraulic_conductivity: float = 3.5e-05, van_genuchten_nonlinearily_parameter: float = 1.598, intercept_parameters: tuple[float, float, float] = (0.935, 0.498, 0.00575), veg_density_param: float = 0.046, groundwater_capacity: float = 500, bypass_flow_coefficient: float = 1.0, extinction_coefficient_global_radiation: float = 0.74, max_percolation_rate_uzlz: float = 2.7, groundwater_loss: float = 1, reservoir_const_upper_groundwater: float = 20, reservoir_const_lower_groundwater: float = 20, initial_aerodynamic_resistance_soil: float = 12.5, drag_coefficient_evaporation: float = 0.2, initial_stomatal_conductance: float = 1000.0, pore_connectivity_parameter: float = 0.5, air_entry_potential_inverse: float = 0.042, m_to_kpa: float = 9.804)[source]#
Dataclass to store all constants for the hydrology model.
Attributes:
Inverse of air entry potential (parameter alpha in van Genuchten), [m-1].
Empirical bypass flow coefficient, unitless.
Drag coefficient for evaporation, dimensionless.
Extinction coefficient for global radiation, [unitless].
Ground water storage capacity, [mm].
Constant ground water loss, [mm].
Initial aerodynamic resistance at the soil surface, [s m-1].
Initial stomatal conductance, [mmol m-2 s-1].
Interception parameters, unitless.
Factor to convert matric potential from m to kPa.
Maximum percolation rate between upper and lower groundwater zone, [mm d-1].
Pore connectivity parameter, dimensionless.
Reservoir constant for the lower groundwater layer, [days].
Reservoir constant for the upper groundwater layer, [days].
Saturated hydraulic conductivity, [m s-1].
Residual soil moisture, unitless.
Soil moisture saturation, unitless.
Nonlinearity parameter n (dimensionless) in Mualem-van Genuchten model.
Parameter to estimate vegetation density for maximum interception, unitless.
- air_entry_potential_inverse: float#
Inverse of air entry potential (parameter alpha in van Genuchten), [m-1].
The inverse of air entry potential describes how quickly soil water retention decreases with increasing soil suction, with higher values indicating coarser soils that drain more readily. Average value of different soil textures across tropical regions (Hodnett and Tomasella, 2002).
- bypass_flow_coefficient: float#
Empirical bypass flow coefficient, unitless.
This parameter affects how much of the water available for infiltration goes directly to groundwater via preferential bypass flow. A value of 0 means all surface water goes directly to groundwater, a value of 1 gives a linear relation between soil moisture and bypass flow.
- drag_coefficient_evaporation: float#
Drag coefficient for evaporation, dimensionless.
Represents the efficiency of turbulent transport of water vapour from a surface to the atmosphere.
- extinction_coefficient_global_radiation: float#
Extinction coefficient for global radiation, [unitless].
This constant is used to reduce potential evaporation for bare soil to maximum shaded evaporation. Typical values are 0.4 to 0.7 for monocotyledons and 0.65 to 1.1 for broad leaved dicotyledons Monteith (1969). The value for tropical forest is taken from Saldarriaga and Luxmoore (1991). The extinction coefficient can be estimated from measurements of PAR above and below a canopy with a known LAI.
- groundwater_capacity: float#
Ground water storage capacity, [mm].
This parameter indicates how much water can be stored in the ground water reservoir which affects the vertical flow of water and the horizontal sub-surface flow. This parameter is currently set to an arbitrary value; we are working on getting a best estimate.
- groundwater_loss: float#
Constant ground water loss, [mm].
This parameter defines the constant amount of water that never rejoins the river channel and is lost beyond the catchment boundaries or to deep groundwater systems.
- initial_aerodynamic_resistance_soil: float#
Initial aerodynamic resistance at the soil surface, [s m-1].
This parameter is an initial estimate of the resistance to the transfer of momentum, heat, and water vapour between the soil surface and the atmosphere. The value is based on Australian evergreen forest, taken from Su et al. (2021); note that this assumes a dense canopy.
- initial_stomatal_conductance: float#
Initial stomatal conductance, [mmol m-2 s-1].
Initial estimate of the rate at which water vapor and carbon dioxide pass through the stomata of plant leaves, reflecting how open the stomata are and regulating both transpiration and gas exchange.
- intercept_parameters: tuple[float, float, float]#
Interception parameters, unitless.
Parameters in equation that estimates maximum canopy interception capacity after Von Hoyningen-Huene (1981).
- max_percolation_rate_uzlz: float#
Maximum percolation rate between upper and lower groundwater zone, [mm d-1].
Values for tropical rainforest are taken from van den Brink (2009).
- pore_connectivity_parameter: float#
Pore connectivity parameter, dimensionless.
Dimensionless parameter used in van Genuchten-Mualem model to calculate unsaturated hydraulic conductivity.
- reservoir_const_lower_groundwater: float#
Reservoir constant for the lower groundwater layer, [days].
This reservoir constant, measured in days, determines the residence time of water in the lower groundwater zone. It influences how quickly water exits the lower zone as baseflow. Typical values range from 10 to 5000 depending on catchment characteristics. This parameter is currently set to an arbitrary value; we are working on getting a better estimate.
- reservoir_const_upper_groundwater: float#
Reservoir constant for the upper groundwater layer, [days].
This parameter defines the residence time (in days) of water in the upper groundwater zone before contributing to streamflow, with typical values for tropical catchments ranging from 5 to 30 days depending on soil permeability and slope. This parameter is currently set to an arbitrary value; we are working on getting a better estimate.
- saturated_hydraulic_conductivity: float#
Saturated hydraulic conductivity, [m s-1].
The saturated hydraulic conductivity is the measure of a soil’s ability to transmit water through its pores. More specifically, is defined as the volumetric flow rate of water passing through a unit cross-sectional area of soil under a unit hydraulic gradient (pressure difference). Value for average tropical rainforest taken from Gupta et al. (2022).
- soil_moisture_residual: float#
Residual soil moisture, unitless.
The residual soil moisture refers to the water that remains in the soil after prolonged drainage due to the force of gravity. It is the water that is tightly held by soil particles and is not easily available for plant roots to extract. The value is soil specific, the format here is volumentic relative water content (unitless, between 0 and 1). Average value of different soil textures across tropical regions (Hodnett and Tomasella, 2002).
- soil_moisture_saturation: float#
Soil moisture saturation, unitless.
Maximum amount of water a soil can hold when all its pores are completely filled with water — that is, the soil is fully saturated and contains no air in the pore spaces. Average value of different soil textures across tropical regions (Hodnett and Tomasella, 2002) .
- van_genuchten_nonlinearily_parameter: float#
Nonlinearity parameter n (dimensionless) in Mualem-van Genuchten model.
This parameter is a fitting shape parameters of soil water retention curve, see (Van Genuchten, 1980). Average value of different soil textures across tropical regions is taken from Hodnett and Tomasella (2002).