API for the below_ground module#
The models.hydrology.below_ground module simulates the below-ground hydrological
processes for the Virtual Ecosystem. This includes vertical flow, soil moisture and
matric potential, groundwater storage, and subsurface horizontal flow.
Functions:
Convert soil moisture into an estimate of water potential. |
|
|
Calculate vertical water flow through soil column, [mm d-1]. |
Update groundwater storage and calculate below ground horizontal flow. |
|
|
Update soil moisture profile. |
- virtual_ecosystem.models.hydrology.below_ground.calculate_matric_potential(effective_saturation: ndarray[tuple[Any, ...], dtype[floating]], air_entry_potential_inverse: float, van_genuchten_nonlinearily_parameter: float) ndarray[tuple[Any, ...], dtype[floating]][source]#
Convert soil moisture into an estimate of water potential.
This function estimates soil water potential \(\Psi_{m}\) as using the van Genuchten - Mualem model (Van Genuchten (1980), Mualem (1976)):
\[\Psi_{m} = -\frac{1}{\alpha} (S_{e}^{-\frac{1}{m}} - 1)^{(\frac{1}{n})}\]where \(\alpha\) is the inverse of the air-entry , \(S_{e}\) is the effective saturation, n and m are van Genuchten parameters.
- Parameters:
effective_saturation – Effective saturation
air_entry_potential_inverse – Inverse of air entry potential (parameter alpha in van Genuchten), [m-1]
van_genuchten_nonlinearily_parameter – Dimensionless parameter in van Genuchten model that describes the degree of nonlinearity of the relationship between the volumetric water content and the soil matric potential.
- Returns:
An estimate of the water potential of the soil, [m]
- virtual_ecosystem.models.hydrology.below_ground.calculate_vertical_flow(soil_moisture: ndarray[tuple[Any, ...], dtype[floating]], soil_layer_thickness: ndarray[tuple[Any, ...], dtype[floating]], soil_layer_depth: ndarray[tuple[Any, ...], dtype[floating]], soil_moisture_saturation: float | ndarray[tuple[Any, ...], dtype[floating]], soil_moisture_residual: float | ndarray[tuple[Any, ...], dtype[floating]], saturated_hydraulic_conductivity: float | ndarray[tuple[Any, ...], dtype[floating]], air_entry_potential_inverse: float, van_genuchten_nonlinearily_parameter: float, pore_connectivity_parameter: float, groundwater_capacity: float | ndarray[tuple[Any, ...], dtype[floating]], seconds_to_day: float) dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#
Calculate vertical water flow through soil column, [mm d-1].
To calculate the flow of water through unsaturated soil, this function combines Richards’ equation and Darcy’s law for unsaturated flow. It calculates the effective saturation \(S_{e}\) and effective unsaturated hydraulic conductivity \(K(\Theta)\) based on the moisture content \(\Theta\) using the van Genuchten - Mualem model (Van Genuchten (1980), Mualem (1976)).
First, the effective saturation is calculated as:
\[S_{e} = \frac{\Theta - \Theta_{r}}{\Theta_{s} - \Theta_{r}}\]where \(\Theta_{r}\) is the soil moisture residual and \(\Theta_{s}\) is the soil moisture saturation.
Then, the effective unsaturated hydraulic conductivity is computed as:
\[K(\Theta) = K_{s} S_{e}^{L} (1-(1-S_{e}^{\frac{1}{m}})^{m})^{2}\]where \(K_{s}\) is the saturated hydraulic conductivity, \(L\) is the pore connectivity parameter, and \(m=1-1/n\) is a shape parameter derived from the non-linearity parameter \(n\).
The soil matric potential \(\Psi_{m}\) is calculated as follows:
\[\Psi_{m} = \frac{1}{\alpha} (S_{e}^{-\frac{1}{m}}-1)^\frac{1}{n}\]where \(\alpha\) is the inverse of air entry value.
Then, the function applies Darcy’s law to calculate the water flow rate \(q\) in \(\frac{m}{s-1}\) considering the effective unsaturated hydraulic conductivity:
\[q = - K(\Theta) (\frac{d \Psi_{m}}{dz} + 1)\]where \(\frac{d \Psi_{m}}{dz}\) is the matric potential gradient with \(z\) the elevation (gravitational potential) or gravitational head. The result is converted to mm per day.
Note that there are severe limitations to this approach on the temporal and spatial scale of this model and this can only be treated as a very rough approximation!
- Parameters:
soil_moisture – Volumetric relative water content in top soil, [unitless]
soil_layer_thickness – Thickness of all soil layers, [m]
soil_layer_depth – Soil layer depth, [m]
soil_moisture_saturation – Soil moisture saturation, [unitless]
soil_moisture_residual – Residual soil moisture, [unitless]
saturated_hydraulic_conductivity – Hydraulic conductivity of soil, [m/s]
air_entry_potential_inverse – Inverse of air entry water potential (parameter alpha in van Genuchten model), [m-1]
van_genuchten_nonlinearily_parameter – Dimensionless parameter in van Genuchten model that describes the degree of nonlinearity of the relationship between the volumetric water content and the soil matric potential.
pore_connectivity_parameter – Pore connectivity parameter, dimensionless
groundwater_capacity – Storage capacity of groundwater, [m]
seconds_to_day – Factor to convert between second and day
- Returns:
matric potential,[m] volumetric flow rate of water, [mm d-1]
- virtual_ecosystem.models.hydrology.below_ground.update_groundwater_storage(groundwater_storage: ndarray[tuple[Any, ...], dtype[floating]], vertical_flow_to_groundwater: ndarray[tuple[Any, ...], dtype[floating]], bypass_flow: ndarray[tuple[Any, ...], dtype[floating]], max_percolation_rate_uzlz: float | ndarray[tuple[Any, ...], dtype[floating]], groundwater_loss: float | ndarray[tuple[Any, ...], dtype[floating]], reservoir_const_upper_groundwater: float | ndarray[tuple[Any, ...], dtype[floating]], reservoir_const_lower_groundwater: float | ndarray[tuple[Any, ...], dtype[floating]]) dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#
Update groundwater storage and calculate below ground horizontal flow.
Groundwater storage and transport are modelled using two parallel linear reservoirs, similar to the approach used in the HBV-96 model (Lindström et al., 1997) and the LISFLOOD (Van Der Knijff et al., 2010).
The upper zone represents a quick runoff component, which includes fast groundwater and subsurface flow through macro-pores in the soil. The lower zone represents the slow groundwater component that generates the base flow.
The outflow from the upper zone to the channel, \(Q_{uz}\), [mm], equals:
\(Q_{uz} = \frac{1}{T_{uz}} * UZ * \Delta t\)
where \(T_{uz}\) is the reservoir constant for the upper groundwater layer [days], and \(UZ\) is the amount of water that is stored in the upper zone [mm]. The amount of water stored in the upper zone is computed as follows:
\(UZ = D_{ls,gw} + D_{pref,gw} - D{uz,lz}\)
where \(D_{ls,gw}\) is the flow from the lower soil layer to groundwater, \(D_{pref,gw}\) is the amount of preferential flow or bypass flow per time step, \(D_{uz,lz}\) is the amount of water that percolates from the upper to the lower zone, all in [mm].
The water percolates from the upper to the lower zone is the inflow to the lower groundwater zone. This amount of water is provided by the upper groundwater zone. \(D_{uz,lz}\) is a fixed amount per computational time step and it is defined as follows:
\(D_{uz,lz} = min(GW_{perc} * \Delta t, UZ)\)
where \(GW_{perc}\), [mm day], is the maximum percolation rate from the upper to the lower groundwater zone. The outflow from the lower zone to the channel is then computed by:
\(Q_{lz} = \frac{1}{T_{lz}} * LZ * \Delta t\)
\(T_{lz}\) is the reservoir constant for the lower groundwater layer, [days], and \(LZ\) is the amount of water that is stored in the lower zone, [mm]. \(LZ\) is computed as follows:
\(LZ = D_{uz,lz} - (GW_{loss} * \Delta t)\)
where \(D_{uz,lz}\) is the percolation from the upper groundwater zone,[mm], and \(GW_{loss}\) is the maximum percolation rate from the lower groundwater zone, [mm day].
The amount of water defined by \(GW_{loss}\) never rejoins the river channel and is lost beyond the catchment boundaries or to deep groundwater systems. The larger the value of ath:GW_{loss}, the larger the amount of water that leaves the system.
- Parameters:
groundwater_storage – Amount of water that is stored in the groundwater reservoir , [mm]
vertical_flow_to_groundwater – Flow from the lower soil layer to groundwater for this timestep, [mm]
bypass_flow – Flow that bypasses the soil matrix and drains directly to the groundwater, [mm]
max_percolation_rate_uzlz – Maximum percolation rate between upper and lower groundwater zone, [mm d-1]
groundwater_loss – Constant amount of water that never rejoins the river channel and is lost beyond the catchment boundaries or to deep groundwater systems, [mm]
reservoir_const_upper_groundwater – Reservoir constant for the upper groundwater layer, [days]
reservoir_const_lower_groundwater – Reservoir constant for the lower groundwater layer, [days]
- Returns:
updated amount of water stored in upper and lower zone, outflow from the upper zone to the channel, and outflow from the lower zone to the channel
- virtual_ecosystem.models.hydrology.below_ground.update_soil_moisture(soil_moisture: ndarray[tuple[Any, ...], dtype[floating]], vertical_flow: ndarray[tuple[Any, ...], dtype[floating]], transpiration: ndarray[tuple[Any, ...], dtype[floating]], soil_moisture_saturation: ndarray[tuple[Any, ...], dtype[floating]], soil_moisture_residual: ndarray[tuple[Any, ...], dtype[floating]]) ndarray[tuple[Any, ...], dtype[floating]][source]#
Update soil moisture profile.
This function calculates soil moisture for each layer by removing the vertical flow of the current layer and adding it to the layer below. The implementation is based on Van Der Knijff et al. (2010). Additionally, the canopy transpiration is removed from the second soil layer.
- Parameters:
soil_moisture – Soil moisture after infiltration and surface evaporation, [mm]
vertical_flow – Vertical flow between all layers, [mm]
transpiration – Canopy transpiration, [mm]
soil_moisture_saturation – Soil moisture saturation for each layer, [mm]
soil_moisture_residual – Residual soil moisture for each layer, [mm]
- Returns:
updated soil moisture profile, relative volumetric water content, dimensionless