API for the microclimate_simple module#

The models.abiotic_simple.microclimate_simple 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 an exponential curve between the above canopy observation and ground level prediction. The same method is applied to derive a vertical wind profile within the canopy, except that we use a logarithmic interpolation. 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}\) as well as a profile of net radiation.

TODO change temperatures to Kelvin

Functions:

calculate_vapour_pressure_deficit(...)

Calculate vapour pressure and vapour pressure deficit, kPa.

exp_interpolation(reference_data, ...)

LAI regression and exponential interpolation of variables above ground.

interpolate_soil_temperature(layer_heights, ...)

Interpolate soil temperature using logarithmic function.

log_interpolation(reference_data, ...)

LAI regression and logarithmic interpolation of variables above ground.

run_simple_microclimate(data, ...)

Calculate simple microclimate.
virtual_ecosystem.models.abiotic_simple.microclimate_simple.calculate_vapour_pressure_deficit(temperature: DataArray, relative_humidity: DataArray, pyrealm_core_constants: CoreConst) → dict[str, DataArray][source]#

Calculate vapour pressure and vapour pressure deficit, kPa.

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

Parameters:

  • temperature – temperature, [C]

  • relative_humidity – relative humidity, []

  • pyrealm_core_constants – Set of core constants from pyrealm which include factors for saturation vapour pressure calculation

Returns:

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

virtual_ecosystem.models.abiotic_simple.microclimate_simple.exp_interpolation(reference_data: ndarray[tuple[Any, ...], dtype[floating]], leaf_area_index_sum: ndarray[tuple[Any, ...], dtype[floating]], layer_structure: LayerStructure, layer_heights: ndarray[tuple[Any, ...], dtype[floating]], upper_bound: float, lower_bound: float, gradient: float) → DataArray[source]#

LAI regression and exponential interpolation of variables above ground.

Parameters:

  • reference_data – Input variable at reference height

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

  • layer_structure – The LayerStructure instance for the simulation.

  • layer_heights – Vertical layer heights, [m]

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

  • upper_bound – Maximum allowed value, used to constrain exp interpolation.

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

Returns:

vertical exponential profile of provided variable

virtual_ecosystem.models.abiotic_simple.microclimate_simple.interpolate_soil_temperature(layer_heights: DataArray, surface_temperature: DataArray, mean_annual_temperature: DataArray, layer_structure: LayerStructure, upper_bound: float, lower_bound: float) → DataArray[source]#

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]

  • layer_structure – The LayerStructure instance for the simulation.

  • 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_simple.log_interpolation(reference_data: ndarray[tuple[Any, ...], dtype[floating]], leaf_area_index_sum: ndarray[tuple[Any, ...], dtype[floating]], layer_structure: LayerStructure, layer_heights: ndarray[tuple[Any, ...], dtype[floating]], upper_bound: float, lower_bound: float, gradient: float) → DataArray[source]#

LAI regression and logarithmic interpolation of variables above ground.

Parameters:

  • reference_data – Input variable at reference height

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

  • layer_structure – The LayerStructure instance for the simulation.

  • 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 logarithmic profile of provided variable

virtual_ecosystem.models.abiotic_simple.microclimate_simple.run_simple_microclimate(data: Data, layer_structure: LayerStructure, time_index: int, constants: AbioticSimpleConstants | AbioticConstants, core_constants: CoreConstants, pyrealm_core_constants: CoreConst, bounds: AbioticSimpleBounds) → dict[str, DataArray][source]#

Calculate simple microclimate.

This function uses empirical relationships between leaf area index (LAI) and atmospheric temperature, relative humidity, vapour pressure deficit, and wind speed to derive vertical 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 (AbioticSimpleConstants) and \(c\) is the intersect which we set to the external data values. We assume that the gradient remains constant.

The values for all atmospheric layers as defined by ‘layer_heights’ in the Virtual Ecosystem (including canopy layers and surface layer) are calculated by exponential (for atmospheric temperature, relative humidity, vapour pressure deficit) or logarithmic (for wind speed) 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 which approximately equals the mean annual temperature, i.e. can assumed to be constant over the year.

The function also broadcasts the reference values for atmospheric pressure and \(\ce{CO2}\) to all atmospheric levels as they are currently assumed to remain constant during one time step. Net radiation for canopy and topsoil layer is also returned.

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

  • above canopy (canopy height + 2 m)

  • canopy layers

  • surface layer

  • soil layers

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]

  • wind_speed_ref [m s-1]

  • leaf_area_index [m m-1]

  • layer_heights [m]

Parameters:

  • data – Data object

  • layer_structure – The LayerStructure instance for the simulation.

  • time_index – Time index, integer

  • constants – Set of constants for the abiotic simple model

  • core_constants – Set of constants shared across all models

  • pyrealm_core_constants – Set of constants from pyrealm package

  • bounds – Upper and lower allowed values for vertical profiles, used to constrain log/exp 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], atmospheric \(\ce{CO2}\) [ppm], wind speed [m s-1]