API documentation for the env_factors module#
The models.soil.env_factors module contains functions that are used to
capture the impact that environmental factors have on microbial rates. These include
temperature, soil water potential, pH and soil texture.
Classes:
|
The various factors through which the environment effects soil cycling rates. |
Functions:
|
Calculate the (temperature dependent) carbon use efficiency. |
Calculate the impact that the soil clay fraction has on enzyme saturation. |
|
Calculate factor that captures the effect of temperature on denitrification rate. |
|
Calculate the effects that the environment has on relevant biogeochemical rates. |
|
Calculate factor that captures the effect of soil moisture on nitrification rate. |
|
Calculate factor that captures the effect of temperature on nitrification rate. |
|
|
Calculate the suitability of the soil pH for microbial activity. |
Calculate rate at which water removes a given solute based on flow rate. |
|
Calculate the cost of symbiotic nitrogen fixation in carbon terms. |
|
Calculate the effect that temperature has on microbial metabolic rates. |
|
Calculate the effect that soil water potential has on microbial rates. |
|
Find total soil moisture for the microbially active depth. |
|
|
Find the rate at which water leaves the microbially active soil region. |
- class virtual_ecosystem.models.soil.env_factors.EnvironmentalEffectFactors(water: ndarray[tuple[Any, ...], dtype[floating]], pH: ndarray[tuple[Any, ...], dtype[floating]], clay_saturation: ndarray[tuple[Any, ...], dtype[floating]])[source]#
The various factors through which the environment effects soil cycling rates.
Attributes:
Impact of soil clay fraction on enzyme saturation constants [unitless].
Impact of soil pH on enzymatic rates [unitless].
Impact of soil water potential on enzymatic rates [unitless].
- virtual_ecosystem.models.soil.env_factors.calculate_carbon_use_efficiency(soil_temp: ndarray[tuple[Any, ...], dtype[floating]], reference_cue_logit: float, cue_reference_temp: float, logit_cue_with_temp: float) ndarray[tuple[Any, ...], dtype[floating]][source]#
Calculate the (temperature dependent) carbon use efficiency.
We model the carbon use efficiency using a logistic function. This is to ensure that carbon use efficiency values remain bounded between zero and one.
TODO - This should be adapted to use an Arrhenius function at some point.
- Parameters:
soil_temp – soil temperature for each soil grid cell [Celsius]
reference_cue_logit – Logit of the carbon use efficiency at reference temp [unitless]
cue_reference_temp – Reference temperature [Celsius]
logit_cue_with_temp – Rate of change in the logit of carbon use efficiency with increasing temperature [Celsius^-1]
- Returns:
The carbon use efficiency (CUE) of the microbial community
- virtual_ecosystem.models.soil.env_factors.calculate_clay_impact_on_enzyme_saturation(clay_fraction: ndarray[tuple[Any, ...], dtype[floating]], base_protection: float, protection_with_clay: float) ndarray[tuple[Any, ...], dtype[floating]][source]#
Calculate the impact that the soil clay fraction has on enzyme saturation.
This factor impacts enzyme saturation constants, based on the assumption that finely textured soils will restrict enzyme access to available C substrates (which protects them). Its form is taken from Fatichi et al. (2019).
- Parameters:
clay_fraction – The fraction of the soil which is clay [unitless]
base_protection – The protection that a soil with no clay provides [unitless]
protection_with_clay – The rate at which protection increases with increasing clay [unitless]
- Returns:
A multiplicative factor capturing how much the protection due to soil structure changes the effective saturation constant by [unitless]
- virtual_ecosystem.models.soil.env_factors.calculate_denitrification_temperature_factor(soil_temp: ndarray[tuple[Any, ...], dtype[floating]], factor_at_infinity: float, minimum_temp: float, thermal_sensitivity: float)[source]#
Calculate factor that captures the effect of temperature on denitrification rate.
Form of this function is a slight rearranged of one provided in Xu-Ri and Prentice (2008).
- Parameters:
soil_temp – Temperature of the relevant segment of soil [Celsius]
factor_at_infinity – Value of temperature factor at infinite temperature [unitless]
minimum_temp – Minimum temperature at which denitrification can still happen [Kelvin]
thermal_sensitivity – Sensitivity of the factor to changes in temperature [Kelvin]
- Returns:
A factor capturing the impact of soil temperature on the denitrification rate [unitless].
- virtual_ecosystem.models.soil.env_factors.calculate_environmental_effect_factors(soil_water_potential: ndarray[tuple[Any, ...], dtype[floating]], pH: ndarray[tuple[Any, ...], dtype[floating]], clay_fraction: ndarray[tuple[Any, ...], dtype[floating]], constants: SoilConstants) EnvironmentalEffectFactors[source]#
Calculate the effects that the environment has on relevant biogeochemical rates.
For each environmental effect a multiplicative factor is calculated, and all of them are returned in a single object for use elsewhere in the soil model.
- Parameters:
soil_water_potential – Soil water potential for each grid cell [kPa]
pH – pH values for each soil grid cell [unitless]
clay_fraction – The clay fraction for each soil grid cell [unitless]
constants – Set of constants for the soil model
- Returns:
An object containing four environmental factors, one for the effect of water potential on enzyme rates, one for the effect of pH on enzyme rates, one for the effect of clay fraction on enzyme saturation, and one for the effect of clay on necromass decay destination.
- virtual_ecosystem.models.soil.env_factors.calculate_nitrification_moisture_factor(effective_saturation: ndarray[tuple[Any, ...], dtype[floating]])[source]#
Calculate factor that captures the effect of soil moisture on nitrification rate.
Form of this function is taken from Fatichi et al. (2019), where it is provided with basically no justification.
- Parameters:
effective_saturation – Effective saturation of the soil with water [unitless]
- Returns:
A factor capturing the impact of soil moisture on the nitrification rate [unitless].
- virtual_ecosystem.models.soil.env_factors.calculate_nitrification_temperature_factor(soil_temp: ndarray[tuple[Any, ...], dtype[floating]], optimum_temp: float, max_temp: float, thermal_sensitivity: int) ndarray[tuple[Any, ...], dtype[floating]][source]#
Calculate factor that captures the effect of temperature on nitrification rate.
Form of this function is taken from Xu-Ri and Prentice (2008).
- Parameters:
soil_temp – Temperature of the relevant segment of soil [Celsius]
optimum_temp – Temperature at which nitrification is maximised [Kelvin]
max_temp – Maximum temperature for which this expression still gives a meaningful result [Kelvin]
thermal_sensitivity – Sensitivity of the factor to changes in temperature [unitless]
- Returns:
A factor capturing the impact of soil temperature on the nitrification rate [unitless].
- virtual_ecosystem.models.soil.env_factors.calculate_pH_suitability(soil_pH: ndarray[tuple[Any, ...], dtype[floating]], maximum_pH: float, minimum_pH: float, upper_optimum_pH: float, lower_optimum_pH: float) ndarray[tuple[Any, ...], dtype[floating]][source]#
Calculate the suitability of the soil pH for microbial activity.
This function is taken from Orwin et al. (2011). pH values within the optimal range are assumed to cause no microbial inhibition, and pH values above a certain value or below a certain value are assumed to cause total inhibition. Linear declines then occur between the edges of the optimal range and the zone of total inhibition.
- Parameters:
soil_pH – The pH of the soil [unitless]
maximum_pH – pH above which microbial rates are completely inhibited [unitless]
minimum_pH – pH below which microbial rates are completely inhibited [unitless]
upper_optimum_pH – pH above which suitability declines [unitless]
lower_optimum_pH – pH below which suitability declines [unitless]
- Returns:
A multiplicative factor capturing the effect of pH on microbial rates
- virtual_ecosystem.models.soil.env_factors.calculate_solute_removal_by_soil_water(solute_density: ndarray[tuple[Any, ...], dtype[floating]], exit_rate: ndarray[tuple[Any, ...], dtype[floating]], soil_moisture: ndarray[tuple[Any, ...], dtype[floating]], solubility_coefficient: float) ndarray[tuple[Any, ...], dtype[floating]][source]#
Calculate rate at which water removes a given solute based on flow rate.
This functional form is adapted from Porporato et al. (2003). The amount of solute that is expected to be found in dissolved form is calculated by multiplying the solute density by its solubility coefficient. This is then multiplied by the frequency with which the water column in the microbially active depth is completely replaced. This replacement can happen through downwards flow (leaching) or through horizontal flow. The replacement frequency can be found as the ratio the total rate at which water exits the microbially active portion of the soil to soil moisture in mm.
- Parameters:
solute_density – The density of the solute in the soil [kg{solute} m^-3]
exit_rate – Rate at which water exits the microbially active portion of the soil [mm day^-1]
soil_moisture – Volume of water contained in topsoil layer [mm]
solubility_coefficient – The solubility coefficient of the solute in question [unitless]
- Returns:
The rate at which the solute in question is removed from the soil by the flow of water [kg{solute} m^-3 day^-1]
- virtual_ecosystem.models.soil.env_factors.calculate_symbiotic_nitrogen_fixation_carbon_cost(soil_temp: ndarray[tuple[Any, ...], dtype[floating]], cost_at_zero_celsius: float, infinite_temp_cost_offset: float, thermal_sensitivity: float, cost_equality_temp: float)[source]#
Calculate the cost of symbiotic nitrogen fixation in carbon terms.
The function used here is adapted from an empirical function provided in Brzostek et al. (2014). As the function is not defined below zero degrees celsius if a negative temperature is input an infinite cost is returned.
I could not sensibly convert this empirically derived function from Celsius to Kelvin units so this is the only function in the soil model to use Celsius units.
- Parameters:
soil_temp – Temperature of the relevant soil zone [Celsius]
cost_at_zero_celsius – The cost nitrogen fixation at zero Celsius [kg{C} kg{N}^-1]
infinite_temp_cost_offset – The difference between the nitrogen fixation cost at zero Celsius and the cost that it tends towards at very high temperatures [kg{C} kg{N}^-1]
thermal_sensitivity – Sensitivity of nitrogen fixation cost to changes in temperature [Celsius^-1]
cost_equality_temp – Temperature (positive) at which the nitrogen fixation cost is the same as it is at zero Celsius [Celsius]
- Returns:
The carbon cost that plants have to pay their microbial symbionts to fix per unit of nitrogen fixed [kg{C} kg{N}^-1]
- virtual_ecosystem.models.soil.env_factors.calculate_temperature_effect_on_microbes(soil_temperature: ndarray[tuple[Any, ...], dtype[floating]], activation_energy: float, reference_temperature: float) ndarray[tuple[Any, ...], dtype[floating]][source]#
Calculate the effect that temperature has on microbial metabolic rates.
This uses a standard Arrhenius equation to calculate the impact of temperature.
This function takes temperatures in Celsius as inputs and converts them into Kelvin for use in the Arrhenius equation. TODO - review this after we have decided how to handle these conversions in general.
- Parameters:
soil_temperature – The temperature of the soil [Celsius]
activation_energy – Energy of activation [J mol^-1]
reference_temperature – The reference temperature of the Arrhenius equation [Celsius]
- Returns:
A multiplicative factor capturing the effect of temperature on microbial rates
- virtual_ecosystem.models.soil.env_factors.calculate_water_potential_impact_on_microbes(water_potential: ndarray[tuple[Any, ...], dtype[floating]], water_potential_halt: float, water_potential_opt: float, response_curvature: float) ndarray[tuple[Any, ...], dtype[floating]][source]#
Calculate the effect that soil water potential has on microbial rates.
This function produces values of one (i.e. no suppression due to soil water) when soil water potentials that are greater than the optimal water potential. Below the water potential at which microbial activity ceases suppression is (by definition) total, so values of zero are produced.
- Parameters:
water_potential – Soil water potential [kPa]
water_potential_halt – Water potential at which all microbial activity stops [kPa]
water_potential_opt – Optimal water potential for microbial activity [kPa]
response_curvature – Parameter controlling the curvature of function that captures the response of microbial rates to water potential [unitless]
- Returns:
A multiplicative factor capturing the impact of moisture on soil microbe rates decomposition [unitless]
- virtual_ecosystem.models.soil.env_factors.find_total_soil_moisture_for_microbially_active_depth(soil_moistures: DataArray, layer_structure: LayerStructure) ndarray[tuple[Any, ...], dtype[floating]][source]#
Find total soil moisture for the microbially active depth.
The proportion of each soil layer that lies within the microbially active zone is first found. The soil moisture for each layer is then multiplied by this proportion and summed, to find the total soil moisture in the microbially active zone.
- Parameters:
soil_moistures – Soil moistures across all soil layers [mm]
layer_structure – The LayerStructure instance for the simulation. From this we use the thickness of each layer, as well as soil_layer_active_thickness which is how much of each layer lies within the microbially active zone
- Returns:
The total soil moisture in the microbially active depth [mm]
- virtual_ecosystem.models.soil.env_factors.find_water_outflow_rates(vertical_flow: ndarray[tuple[Any, ...], dtype[floating]], layer_structure: LayerStructure) ndarray[tuple[Any, ...], dtype[floating]][source]#
Find the rate at which water leaves the microbially active soil region.
This functions calculates the rate at which soil water in the microbially active region is refreshed with “new” water from rainfall. The reason to specifically care about “new” water is that it does not carry any significant amount of nutrients with it (in contrast to water moving from a different part of the soil), meaning that the soil nutrients will dissolve from the soil without impediment (which is the assumption underlying the
calculate_solute_removal_by_soil_water()function). The rate of “new” water refreshing the microbially active column will be equivalent to the rate at which water escapes from this region. For the upper soil layers, all water flows are vertical rather than horizontal, so this function only considers vertical flows. If the implementation of the hydrology model changes so that the upper layers also have horizontal water movements this function will need to change to ensure that nutrient flows properly track the water flows.The water column that the soil model is interested in (i.e. the amount of water down to the maximum depth of microbial activity) generally spans a fractional number of soil hydrology layers, meaning that water exits the microbially active region within a specific soil hydrology layer rather than at the boundary of two layers. This complicates things as the vertical flow rates are defined for passing between hydrology layers. We therefore calculate two separate exit rates which we then sum to find the combined rate. Firstly, we calculate the rate at which water flows into the microbially inactive portion of the partially microbially active layer. This is found by multiplying the vertical flow into the layer by the fraction of the layer that is microbially inactive. Secondly, we calculate the rate at which water flows from the microbially active portion of this layer to the microbially inactive layer below. This flow is found by multiplying the vertical flow to the lower layer by the fraction of the upper layer that is microbially active.
- Parameters:
vertical_flow – The flow rate between each soil layer [mm day^-1]
layer_structure – The LayerStructure instance for the simulation. From this we use the thickness of each layer, as well as soil_layer_active_thickness which is how much of each layer lies within the microbially active zone
- Returns:
The rate at which water leaves the microbially active region of the soil [mm day^-1]