API for the microclimate module

The models.abiotic_simple.microclimate module uses linear regressions from Hardwick et al. (2015) and Jucker et al. (2018) to predict atmospheric temperature, relative humidity, and vapour pressure deficit at ground level (1.5 m) given the above canopy conditions and leaf area index of intervening canopy. A within canopy profile is then interpolated using a logarithmic curve between the above canopy observation and ground level prediction. Soil temperature is interpolated between the surface layer and the soil temperature at 1 m depth which equals the mean annual temperature. The module also provides a constant vertical profile of atmospheric pressure and \(\ce{CO2}\).

TODO change tenperatures to Kelvin

Functions:

calculate_saturation_vapour_pressure(...)

Calculate saturation vapour pressure.

calculate_vapour_pressure_deficit(...)

Calculate vapour pressure and vapour pressure deficit.

interpolate_soil_temperature(layer_heights, ...)

Interpolate soil temperature using logarithmic function.

log_interpolation(data, reference_data, ...)

LAI regression and logarithmic interpolation of variables above ground.

run_microclimate(data, layer_roles, ...)

Calculate simple microclimate.
virtual_ecosystem.models.abiotic_simple.microclimate.calculate_saturation_vapour_pressure(temperature: DataArray, saturation_vapour_pressure_factors: list[float]) → DataArray

Calculate saturation vapour pressure.

Saturation vapour pressure \(e_{s} (T)\) is here calculated as

\(e_{s}(T) = 0.61078 exp(\frac{7.5 T}{T + 237.3})\)

where \(T\) is temperature in degree C .

Parameters:

  • temperature – Air temperature, [C]

  • saturation_vapour_pressure_factors – Factors in saturation vapour pressure calculation

Returns:

saturation vapour pressure, [kPa]

virtual_ecosystem.models.abiotic_simple.microclimate.calculate_vapour_pressure_deficit(temperature: DataArray, relative_humidity: DataArray, saturation_vapour_pressure_factors: list[float]) → dict[str, DataArray]

Calculate vapour pressure and vapour pressure deficit.

Vapor pressure deficit is defined as the difference between saturated vapour pressure and actual vapour pressure.

Parameters:

  • temperature – temperature, [C]

  • relative_humidity – relative humidity, []

  • saturation_vapour_pressure_factors – Factors in saturation vapour pressure calculation

Returns:

vapour pressure, [kPa], vapour pressure deficit, [kPa]

virtual_ecosystem.models.abiotic_simple.microclimate.interpolate_soil_temperature(layer_heights: DataArray, surface_temperature: DataArray, mean_annual_temperature: DataArray, upper_bound: float, lower_bound: float) → DataArray

Interpolate soil temperature using logarithmic function.

Parameters:

  • layer_heights – vertical layer heights, [m]

  • layer_roles – list of layer roles (from top to bottom: above, canopy, subcanopy, surface, soil)

  • surface_temperature – surface temperature, [C]

  • mean_annual_temperature – mean annual temperature, [C]

  • upper_bound – maximum allowed value, used to constrain log interpolation. Note that currently no conservation of water and energy!

  • lower_bound – minimum allowed value, used to constrain log interpolation.

Returns:

soil temperature profile, [C]

virtual_ecosystem.models.abiotic_simple.microclimate.log_interpolation(data: Data, reference_data: DataArray, leaf_area_index_sum: DataArray, layer_roles: list[str], layer_heights: DataArray, upper_bound: float, lower_bound: float, gradient: float) → DataArray

LAI regression and logarithmic interpolation of variables above ground.

Parameters:

  • data – Data object

  • reference_data – input variable at reference height

  • leaf_area_index_sum – leaf area index summed over all layers, [m m-1]

  • layer_roles – list of layer roles (soil, surface, subcanopy, canopy, above)

  • layer_heights – vertical layer heights, [m]

  • lower_bound – minimum allowed value, used to constrain log interpolation. Note that currently no conservation of water and energy!

  • upper_bound – maximum allowed value, used to constrain log interpolation.

  • gradient – gradient of regression from Hardwick et al. (2015)

Returns:

vertical profile of provided variable

virtual_ecosystem.models.abiotic_simple.microclimate.run_microclimate(data: Data, layer_roles: list[str], time_index: int, constants: AbioticSimpleConsts, bounds: AbioticSimpleBounds) → dict[str, DataArray]

Calculate simple microclimate.

This function uses empirical relationships between leaf area index (LAI) and atmospheric temperature, relative humidity, and vapour pressure deficit to derive logarithmic profiles of these variables from external climate data such as regional climate models or satellite observations. Note that these sources provide data at different heights and with different underlying assumptions which lead to different biases in the model output. For below canopy values (1.5 m), the implementation is based on Hardwick et al. (2015) as

\(y = m * LAI + c\)

where \(y\) is the variable of interest, \(m\) is the gradient (AbioticSimpleConsts) and \(c\) is the intersect which we set to the external data values. We assume that the gradient remains constant.

The other atmospheric layers are calculated by logarithmic regression and interpolation between the input at the top of the canopy and the 1.5 m values. Soil temperature is interpolated between the surface layer and the temperature at 1 m depth which equals the mean annual temperature. The function also provides constant atmospheric pressure and \(\ce{CO2}\) for all atmospheric levels.

The layer_roles list is composed of the following layers (index 0 above canopy):

  • above canopy (canopy height)

  • canopy layers (maximum of ten layers, minimum one layers)

  • subcanopy (1.5 m)

  • surface layer

  • soil layers (currently one near surface layer and one layer at 1 m below ground)

The function expects a data object with the following variables:

  • air_temperature_ref [C]

  • relative_humidity_ref []

  • vapour_pressure_deficit_ref [kPa]

  • atmospheric_pressure_ref [kPa]

  • atmospheric_co2_ref [ppm]

  • leaf_area_index [m m-1]

  • layer_heights [m]

Parameters:

  • data – Data object

  • layer_roles – list of layer roles (from top to bottom: above, canopy, subcanopy, surface, soil)

  • time_index – time index, integer

  • constants – Set of constants for the abiotic simple model

  • bounds – upper and lower allowed values for vertical profiles, used to constrain log interpolation. Note that currently no conservation of water and energy!

Returns:

Dict of DataArrays for air temperature [C], relative humidity [-], vapour pressure deficit [kPa], soil temperature [C], atmospheric pressure [kPa], and atmospheric \(\ce{CO2}\) [ppm]