API documentation for the model_config module#
The models.abiotic.constants module contains a set of dataclasses which contain
parameters required by the broader
abiotic_model model.
These parameters are constants in that they should not be changed during a particular
simulation.
Classes:
|
The abiotic model configuration. |
|
Dataclass to store all constants for the abiotic model. |
- class virtual_ecosystem.models.abiotic.model_config.AbioticConfiguration(*, static: bool = False, constants: AbioticConstants = AbioticConstants(leaf_emissivity=0.98, soil_emissivity=0.95, leaf_albedo=0.15, bulk_density_soil=1175.0, wind_reference_height=10.0, latent_heat_vap_equ_factors=(1918460.0, 33.91), zero_plane_scaling_parameter=7.5, substrate_surface_roughness_length=0.003, roughness_element_drag_coefficient=0.3, roughness_sublayer_depth_parameter=0.193, max_ratio_wind_to_friction_velocity=0.3, min_windspeed_below_canopy=0.1, min_roughness_length=0.01, soil_thermal_conductivity=1.206, specific_heat_capacity_soil=881, surface_albedo=0.125, saturated_pressure_slope_parameters=(4098.0, 0.6108, 17.27, 237.3), dry_air_factor=0.378, initial_flux_value=0.001, aerodynamic_resistance_canopy_night=50.0, aerodynamic_resistance_soil_night=50.0, aerodynamic_resistance_canopy_day=20.0, max_mixing_coefficient=1.0, fraction_par_used_for_photosynthesis=0.5, leaf_absorptance_non_par=0.5, par_fraction_of_shortwave_radiation=0.46, maxiter_secant_solver=8, convergence_tolerance_secant_solver=0.01, small_perturbation_second_guess_secant_solver=1e-06, denominator_tolerance=1e-12, min_specific_humidity=0.001, understorey_ventilation_rate=0.1, extinction_coefficient_longwave=0.5, minimum_mixing_depth=1.5, min_leaf_area_index_for_mixing=0.5), bounds: AbioticSimpleBounds = AbioticSimpleBounds(air_temperature=(-20.0, 80.0, -1.27), relative_humidity=(0.001, 99.999, 5.4), vapour_pressure_deficit=(0.001, 10.0, -252.24), wind_speed=(0.001, 100.0, -0.1), soil_temperature=(-10.0, 50.0)), simple_constants: AbioticSimpleConstants = AbioticSimpleConstants(leaf_emissivity=0.98, soil_emissivity=0.95, placeholder=10.0), latitude: float = 0.0)[source]#
The abiotic model configuration.
Attributes:
Bounds for abiotic variables.
Constants for the abiotic model
Latitude in degrees.
Constants used for the simple abiotic model, used to set up initial conditions.
- bounds: AbioticSimpleBounds#
Bounds for abiotic variables.
- constants: AbioticConstants#
Constants for the abiotic model
- simple_constants: AbioticSimpleConstants#
Constants used for the simple abiotic model, used to set up initial conditions.
- class virtual_ecosystem.models.abiotic.model_config.AbioticConstants(*, leaf_emissivity: float = 0.98, soil_emissivity: float = 0.95, leaf_albedo: float = 0.15, bulk_density_soil: float = 1175.0, wind_reference_height: float = 10.0, latent_heat_vap_equ_factors: tuple[float, float] = (1918460.0, 33.91), zero_plane_scaling_parameter: float = 7.5, substrate_surface_roughness_length: float = 0.003, roughness_element_drag_coefficient: float = 0.3, roughness_sublayer_depth_parameter: float = 0.193, max_ratio_wind_to_friction_velocity: float = 0.3, min_windspeed_below_canopy: float = 0.1, min_roughness_length: float = 0.01, soil_thermal_conductivity: float = 1.206, specific_heat_capacity_soil: float = 881, surface_albedo: float = 0.125, saturated_pressure_slope_parameters: tuple[float, float, float, float] = (4098.0, 0.6108, 17.27, 237.3), dry_air_factor: float = 0.378, initial_flux_value: float = 0.001, aerodynamic_resistance_canopy_night: float = 50.0, aerodynamic_resistance_soil_night: float = 50.0, aerodynamic_resistance_canopy_day: float = 20.0, max_mixing_coefficient: float = 1.0, fraction_par_used_for_photosynthesis: float = 0.5, leaf_absorptance_non_par: float = 0.5, par_fraction_of_shortwave_radiation: float = 0.46, maxiter_secant_solver: int = 8, convergence_tolerance_secant_solver: float = 0.01, small_perturbation_second_guess_secant_solver: float = 1e-06, denominator_tolerance: float = 1e-12, min_specific_humidity: float = 0.001, understorey_ventilation_rate: float = 0.1, extinction_coefficient_longwave: float = 0.5, minimum_mixing_depth: float = 1.5, min_leaf_area_index_for_mixing: float = 0.5)[source]#
Dataclass to store all constants for the abiotic model.
Attributes:
Aerodynamic resistance of the canopy during the day, [s m-1].
Aerodynamic resistance of the canopy at night, [s m-1].
Aerodynamic resistance of the soil at night, [s m-1].
Bulk density of soil, [kg m-3].
Convergence tolerance for secant solver, in max absolute update.
Small value to prevent division by zero.
Dry air factor, dimensionless.
Extinction coefficient for longwave radiation, dimensionless.
Fraction of photosynthetically active radiation used for photosynthesis, dimensionless.
Initial non-zero fill value for energy fluxes, [W m-2].
Factors in calculation of latent heat of vapourisation.
Leaf absorptance for non-photosynthetically active radiation, dimensionless.
Leaf albedo, unitless.
Maximum turbulent mixing coefficients, [m2 s-1].
Maximum ratio of wind velocity to friction velocity, dimensionless.
Maximum number of secant iterations to solve for canopy temperature.
Minimum leaf area index required for turbulent mixing to occur, [m m-1].
Minimum roughness length, [m].
Minimum value for specific humidity to avoid dividion by zero, [kg kg-1].
Minimum wind speed below the canopy or in absence of vegetation, [m s-1].
Minimum mixing depth for lowest canopy layer, [m].
Fraction of shortwave radiation that is photosynthetically active, dimensionless.
Roughness-element drag coefficient, dimensionless.
Parameter characterizes the roughness sublayer depth.
List of parameters to calculate the slope of saturated vapour pressure curve.
Small perturbation for second initial guess in secant solver.
Soil thermal conductivity, [W m-1 K-1].
Specific heat capacity of soil, [J kg-1 K-1].
Substrate-surface roughness length, m.
Mean surface albedo of a tropical rainforest in South East Asia, dimensionless.
Understorey ventilation rate, comes into place when there is no canopy, [s-1].
Reference height for wind speed above the canopy, [m].
Control parameter for scaling zero displacement to height, dimensionless.
- aerodynamic_resistance_canopy_day: float#
Aerodynamic resistance of the canopy during the day, [s m-1].
- bulk_density_soil: float#
Bulk density of soil, [kg m-3].
Bulk density describes the mass of dry soil per unit volume, including both the solid soil particles and the pore spaces between them. Value for average rainforest soil is taken from Gupta et al. (2021).
- convergence_tolerance_secant_solver: float#
Convergence tolerance for secant solver, in max absolute update.
- dry_air_factor: float#
Dry air factor, dimensionless.
This term accounts for the proportion of dry air when computing the partitioning of total air pressure. It is the complement of the molecular_weight_ratio_water_to_dry_air in core.constants.
- extinction_coefficient_longwave: float#
Extinction coefficient for longwave radiation, dimensionless.
- fraction_par_used_for_photosynthesis: float#
Fraction of photosynthetically active radiation used for photosynthesis, dimensionless.
- latent_heat_vap_equ_factors: tuple[float, float]#
Factors in calculation of latent heat of vapourisation.
Implementation after Maclean and Klinges (2021), value is taken from Henderson-Sellers (1984).
- leaf_absorptance_non_par: float#
Leaf absorptance for non-photosynthetically active radiation, dimensionless.
- leaf_albedo: float#
Leaf albedo, unitless.
Leaf albedo is the fraction of incoming solar radiation that a leaf reflects, typically ranging from 0.12 to 0.18 in tropical forests due to their dark, broadleaf surfaces. Value here is taken from Su et al. (2021).
- leaf_emissivity: float#
Leaf emissivity, unitless.
Leaf emissivity is a measure of how efficiently a leaf emits thermal radiation compared to a perfect blackbody, typically ranging from 0.95 to 0.99. Value for tropical vegetation is taken from Ma et al. (2019).
- max_ratio_wind_to_friction_velocity: float#
Maximum ratio of wind velocity to friction velocity, dimensionless.
The maximum ratio of wind velocity to friction velocity refers to the highest observed or theoretical value of the ratio between the wind speed at a given height and the surface friction velocity (u*), indicating the efficiency of momentum transfer from the atmosphere to the surface. Implementation and value from Maclean and Klinges (2021).
- min_leaf_area_index_for_mixing: float#
Minimum leaf area index required for turbulent mixing to occur, [m m-1].
- min_roughness_length: float#
Minimum roughness length, [m].
The minimum roughness length represents the lowest height at which the surface roughness significantly affects the wind flow over a particular terrain or surface. Implementation and value from Maclean and Klinges (2021).
- min_specific_humidity: float#
Minimum value for specific humidity to avoid dividion by zero, [kg kg-1].
- min_windspeed_below_canopy: float#
Minimum wind speed below the canopy or in absence of vegetation, [m s-1].
- minimum_mixing_depth: float#
Minimum mixing depth for lowest canopy layer, [m].
This is to prevent unrealistically low mixing depths and therefore high temperatures in the lowest canopy layer when the layer height is very low. Note that this is an artificial inflation of the mixing depth.
- par_fraction_of_shortwave_radiation: float#
Fraction of shortwave radiation that is photosynthetically active, dimensionless.
Value is taken from the P-Model:
Convert from downward shortwave radiation [W m-2] to photosynthetic photon flux density (PPFD)[µmol m-2 s-1]. 1 W m-2 of sunlight is roughly 4.57 µmol m-2 s-1 of full spectrum sunlight, of which about 4.57 * 46% = 2.04 µmol m-2 s-1 is PPFD.
- roughness_element_drag_coefficient: float#
Roughness-element drag coefficient, dimensionless.
The roughness-element drag coefficient refers to the dimensionless coefficient used to quantify the drag force exerted by individual roughness elements (such as buildings, trees, or surface irregularities) on airflow, influencing the overall aerodynamic characteristics of a surface within the atmospheric boundary layer. Implementation and value from Maclean and Klinges (2021).
- roughness_sublayer_depth_parameter: float#
Parameter characterizes the roughness sublayer depth.
The roughness sublayer depth refers to the layer near the surface where the effects of surface roughness significantly influence airflow, turbulence, momentum transfer, typically extending up to about 10% of the height of the roughness elements or features on the surface. This layer is characterized by intense turbulence and rapid velocity changes due to surface irregularities. Implementation and value taken from (Maclean and Klinges, 2021).
- saturated_pressure_slope_parameters: tuple[float, float, float, float]#
List of parameters to calculate the slope of saturated vapour pressure curve.
- small_perturbation_second_guess_secant_solver: float#
Small perturbation for second initial guess in secant solver.
- soil_emissivity: float#
Soil emissivity, dimensionless.
Soil emissivity is a measure of how efficiently the soil surface emits thermal radiation compared to a perfect blackbody, with values typically ranging from 0.90 to 0.98 depending on soil texture, moisture, and surface roughness. Value taken from Mölders (2005).
- soil_thermal_conductivity: float#
Soil thermal conductivity, [W m-1 K-1].
Soil thermal conductivity is a measure of the soil’s ability to conduct heat, influenced by factors such as moisture content, texture, and density. Value is taken from Rasimeng (2020).
- specific_heat_capacity_soil: float#
Specific heat capacity of soil, [J kg-1 K-1].
Specific heat capacity of soil is the amount of heat required to raise the temperature of a unit mass of soil by one degree Celsius (or Kelvin), and depends on soil composition, moisture content, and organic matter. Value taken from Mölders (2005).
- substrate_surface_roughness_length: float#
Substrate-surface roughness length, m.
The substrate-surface roughness length is the “baseline roughness” of the ground itself before adding vegetation on top. Implementation and value from Maclean and Klinges (2021).
- surface_albedo: float#
Mean surface albedo of a tropical rainforest in South East Asia, dimensionless.
The value is takes from a study that compares changes in surface albedo before and after deforestation in South East Asia (Wilson, 2020).
- understorey_ventilation_rate: float#
Understorey ventilation rate, comes into place when there is no canopy, [s-1].
- wind_reference_height: float#
Reference height for wind speed above the canopy, [m].
The reference height for horizontal wind is typically 10m above ground compared to 2m for other atmospheric variables such as temperature and relative humidity. We assume here that the reference height is above the canopy, please check the input data carefully and be aware of limitations.