API for the `microclimate` module#

The microclimate module contains the equations to solve the radiation and energy balance in the Virtual Ecosystem.

Functions:

`build_output_from_record`(data_record, ...)	Build model output from hourly record and static/state variables.
`calculate_soil_fluxes`(state, static, ...)	Calculate soil fluxes for microclimate model.
`calculate_thermodynamics`(state, static, ...)	Calculate thermodynamic variables for microclimate model.
`calculate_vegetation_fluxes`(state, static, ...)	Calculate vegetation fluxes for microclimate model.
`calculate_vegetation_temperature`(state, ...)	Calculate canopy and understorey temperature for microclimate model.
`calculate_wind_profiles`(static, data, ...)	Calculate wind profiles for microclimate model.
`generate_hourly_forcing`(data, static, ...)	Generate hourly profiles for atmospheric forcing variables.
`initialize_hourly_record`(data, vars_updated, ...)	Initialize hourly record arrays for microclimate model.
`initialize_state`(data)	Initialize state variables for microclimate model.
`prepare_static_inputs`(data, idx, time_index, ...)	Prepare static inputs for microclimate model.
`run_hour_step`(state, static, hourly_forcing, ...)	Run one hour step of the microclimate model.
`run_microclimate`(data, vars_updated, ...)	Run the microclimate model for one day, iterating through hourly time steps.
`update_air_temperature`(state, static, ...)	Update air temperature profiles based on calculated fluxes and turbulent mixing.
`update_atmospheric_humidity`(state, static, ...)	Update atmospheric humidity profiles based on fluxes and turbulent mixing.
`update_forcing_boundary_conditions`(state, ...)	Update forcing boundary conditions for microclimate model.

virtual_ecosystem.models.abiotic.microclimate.build_output_from_record(data_record: dict[str, Any], static: dict[str, Any], layer_structure: LayerStructure, vars_updated: tuple[str, ...]) → dict[str, DataArray][source]#

Build model output from hourly record and static/state variables.

This function also checks if variables are missing from var updated list.

Parameters:

data_record – Hourly data record
static – Static inputs
layer_structure – LayerStructure object
vars_updated – Tuple containing strings of all variables that are updated by the abiotic model

Returns:

Dictionary of DataArray outputs. Raises ValueError when unsupported variable: dimensions are provided and when requested variables could not be produced

virtual_ecosystem.models.abiotic.microclimate.calculate_soil_fluxes(state: dict[str, Any], static: dict[str, Any], abiotic_constants: AbioticConstants, core_constants: CoreConstants, time_interval: float, idx: SimpleNamespace) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Calculate soil fluxes for microclimate model.

This function calculates the components of the soil energy balance, including net radiation, longwave emission, sensible and latent heat flux, and ground heat flux.

Parameters:

state – Current state variables for microclimate model
static – Prepared static inputs for microclimate model
hourly_forcing – Generated hourly profiles for atmospheric forcing variables
abiotic_constants – Set of constants for abiotic model
core_constants – Set of constants that are shared across all models
time_interval – Time interval for flux calculations, [s]
idx – SimpleNamespace with layer indices

Returns:

Dictionary with soil fluxes

virtual_ecosystem.models.abiotic.microclimate.calculate_thermodynamics(state: dict[str, Any], static: dict[str, Any], hourly_forcing: dict[str, Any], hour: int, n_cells: int, idx: SimpleNamespace, abiotic_constants: AbioticConstants, core_constants: CoreConstants) → dict[str, Any][source]#

Calculate thermodynamic variables for microclimate model.

This includes the density of air, specific heat capacity of air, latent heat of vapourisation, aerodynamic resistances for day and nighttime, and ventilation rate above the canopy.

Parameters:

state – Current state variables for microclimate model
static – Prepared static inputs for microclimate model
hourly_forcing – Generated hourly profiles for atmospheric forcing variables
hour – Current hour index
n_cells – Number of grid cells in the model
idx – SimpleNamespace with layer indices
abiotic_constants – Set of constants for abiotic model
core_constants – Set of constants that are shared across all models

Returns:

Dictionary with calculated thermodynamic variables for microclimate model

virtual_ecosystem.models.abiotic.microclimate.calculate_vegetation_fluxes(state: dict[str, Any], static: dict[str, Any], abiotic_constants: AbioticConstants, core_constants: CoreConstants, idx: SimpleNamespace) → dict[str, Any][source]#

Calculate vegetation fluxes for microclimate model.

This function calculates the components of the vegetation energy balance, including net radiation, longwave emission, and sensible and latent heat flux.

Parameters:

state – Current state variables for microclimate model
static – Prepared static inputs for microclimate model
hourly_forcing – Generated hourly profiles for atmospheric forcing variables
abiotic_constants – Set of constants for abiotic model
core_constants – Set of constants that are shared across all models
idx – SimpleNamespace with layer indices

Returns:

Dictionary with vegetation fluxes

virtual_ecosystem.models.abiotic.microclimate.calculate_vegetation_temperature(state: dict[str, Any], static: dict[str, Any], abiotic_constants: AbioticConstants, core_constants: CoreConstants, idx: SimpleNamespace) → ndarray[tuple[Any, ...], dtype[floating]][source]#

Calculate canopy and understorey temperature for microclimate model.

This uses the energy balance equation to solve for canopy and understorey temperature based on absorbed radiation, evapotranspiration, aerodynamic resistance, and other thermodynamic variables.

Parameters:

state – Current state variables for microclimate model
static – Prepared static inputs for microclimate model
abiotic_constants – Set of constants for abiotic model
core_constants – Set of constants that are shared across all models
idx – SimpleNamespace with layer indices

Returns:

new vegetation temperature

virtual_ecosystem.models.abiotic.microclimate.calculate_wind_profiles(static: dict[str, Any], data: Data, time_index: int, abiotic_constants: AbioticConstants, core_constants: CoreConstants, layer_structure: LayerStructure) → dict[str, Any][source]#

Calculate wind profiles for microclimate model.

This function calculates the zero plane displacement height, roughness length for momentum, wind speed profile, friction velocity, and turbulent mixing coefficient above the canopy. These variables currently remain constant over the course of one day.

If there is no canopy, zero plane displacement and roughness length are set to zero, and the wind speed profile is constant with height and equal to the reference wind speed.

Parameters:

static – Dictionary with prepared static inputs for microclimate model
data – Data object
time_index – Time index
abiotic_constants – Set of constants for abiotic model
core_constants – Set of constants that are shared across all models
layer_structure – Layer structure

Returns:

Dictionary with calculated wind profiles for microclimate model

virtual_ecosystem.models.abiotic.microclimate.generate_hourly_forcing(data: Data, static: dict[str, Any], time_index: int, month: int, days: int, latitude: float, abiotic_constants: AbioticConstants) → dict[str, Any][source]#

Generate hourly profiles for atmospheric forcing variables.

This function generates a diurnal cycle of air temperature, shortwave absorption, relative humidity, evapotranspiration, and soil evaporation. This diurnal cycle is generated from monthly data using a sinusoidal function.

Parameters:

data – Data object
static – Dictionary with prepared static inputs for microclimate model
time_index – Time index
month – Current month (1-12)
days – Number of days per month
latitude – Latitude of the location, [degrees]
abiotic_constants – Set of constants for abiotic model

Returns:

Dictionary with generated hourly profiles for atmospheric forcing variables

virtual_ecosystem.models.abiotic.microclimate.initialize_hourly_record(data: Data, vars_updated: tuple[str, ...], time_dim: int, layer_structure: LayerStructure) → dict[str, Any][source]#

Initialize hourly record arrays for microclimate model.

This function initialised a dictionary of data arrays for all variables that are updated by the abiotic model. These arrays collect the hourly data which is later averaged and returned to the data object.

Parameters:

data – Data object
vars_updated – Tuple containing strings of all variables that are updated by the abiotic model
time_dim – Number of time steps in the hourly record (e.g., 24 for a full day)
layer_structure – Layer structure object with information on the number of layers and their indices

Returns:

Dictionary with initialized hourly record arrays for microclimate model

virtual_ecosystem.models.abiotic.microclimate.initialize_state(data: Data) → dict[str, Any][source]#

Initialize state variables for microclimate model.

This function initialises state variables that are updated during the diurnal cycle.

Parameters:: data – Data object
Returns:: Dictionary with initialized state variables

virtual_ecosystem.models.abiotic.microclimate.prepare_static_inputs(data: Data, idx: SimpleNamespace, time_index: int, layer_structure: LayerStructure, abiotic_constants: AbioticConstants) → dict[str, Any][source]#

Prepare static inputs for microclimate model.

These are inputs that do not change during the hourly loop, but can vary in space and between VE time steps. They include canopy height, sum over canopy leaf area index, atmospheric pressure and CO2 profiles, absorbed longwave radiation, and cell area.

If there is no canopy, canopy height and leaf area index sum are set to zero.

Parameters:

data – Data object
idx – SimpleNamespace with indices for different layers and variables
time_index – Time index
layer_structure – Layer structure object
abiotic_constants – Set of constants for abiotic model

Returns:

Dictionary with prepared static inputs for microclimate model

virtual_ecosystem.models.abiotic.microclimate.run_hour_step(state: dict[str, Any], static: dict[str, Any], hourly_forcing: dict[str, Any], hour: int, idx: SimpleNamespace, layer_structure: LayerStructure, abiotic_constants: AbioticConstants, core_constants: CoreConstants, pyrealm_core_constants: CoreConst, abiotic_bounds: AbioticSimpleBounds, time_interval: float)[source]#

Run one hour step of the microclimate model.

This function will be called iteratively for each hour in the day, updating the state variables based on the calculated fluxes and thermodynamics.

Parameters:

state – Current state variables for microclimate model
static – Prepared static inputs for microclimate model
hourly_forcing – Generated hourly profiles for atmospheric forcing variables
hour – Current hour index
idx – SimpleNamespace with layer indices
layer_structure – LayerStructure
abiotic_constants – Set of constants for abiotic model
core_constants – Set of constants that are shared across all models
pyrealm_core_constants – Set of constants from pyrealm core that are used in calculations
abiotic_bounds – Set of bounds for abiotic values
time_interval – Time interval for flux calculations, [s]

Returns:

Updated state variables for the current hour

virtual_ecosystem.models.abiotic.microclimate.run_microclimate(data: Data, vars_updated: tuple[str, ...], time_index: int, time_dim: int, time_interval: float, month: int, days: int, latitude: float, layer_structure: LayerStructure, abiotic_constants: AbioticConstants, core_constants: CoreConstants, pyrealm_core_constants: CoreConst, abiotic_bounds: AbioticSimpleBounds) → dict[str, Any][source]#

Run the microclimate model for one day, iterating through hourly time steps.

This function prepares static inputs, calculates wind profiles, generates hourly forcing, initializes state and record variables, and then iteratively updates the state variables based on calculated fluxes and thermodynamics for each hour.

Parameters:

data – Data object containing all model variables and grid information
vars_updated – Tuple containing strings of all variables that are updated by abiotic model
time_index – Time index for the current day in the data
time_dim – Number of time steps in the hourly record (e.g., 24 for a full day)
time_interval – Time interval for flux calculations, [s]
month – Current month (1-12) for generating diurnal cycle
days – Number of days per month
latitude – Latitude of the location, [degrees]
layer_structure – Layer structure object with information on number of layers and their indices
abiotic_constants – Set of constants for abiotic model
core_constants – Set of constants that are shared across all models
pyrealm_core_constants – Set of constants from pyrealm
abiotic_bounds – Bounds for air temperature to ensure physical realism

Returns:

Dictionary with updated state variables and hourly record for the day

virtual_ecosystem.models.abiotic.microclimate.update_air_temperature(state: dict[str, Any], static: dict[str, Any], abiotic_bounds: AbioticSimpleBounds, idx: SimpleNamespace, denominator_tolerance: float, min_leaf_area_index_for_mixing: float) → ndarray[tuple[Any, ...], dtype[floating]][source]#

Update air temperature profiles based on calculated fluxes and turbulent mixing.

Parameters:

state – Current state variables for microclimate model
static – Prepared static inputs for microclimate model
abiotic_bounds – Bounds for air temperature to ensure physical realism
idx – Indices for different layer types
denominator_tolerance – Small value to prevent division by zero in calculations
min_leaf_area_index_for_mixing – Minimum leaf area index required for turbulent mixing to occur.

Returns:

Updated air temperature profiles for microclimate model

virtual_ecosystem.models.abiotic.microclimate.update_atmospheric_humidity(state: dict[str, Any], static: dict[str, Any], pyrealm_core_constants: CoreConst, core_constants: CoreConstants, abiotic_constants: AbioticConstants, abiotic_bounds: AbioticSimpleBounds, idx: SimpleNamespace, time_interval: float) → dict[str, Any][source]#

Update atmospheric humidity profiles based on fluxes and turbulent mixing.

Parameters:

state – Current state variables for microclimate model
static – Prepared static inputs for microclimate model
pyrealm_core_constants – Set of constants from pyrealm core that are used
core_constants – Set of constants that are shared across all models
abiotic_constants – Set of constants for abiotic model
abiotic_bounds – Bounds for atmospheric humidity variables
idx – SimpleNamespace with layer indices
time_interval – Time interval for flux calculations, [s]

Returns:

dict with atmospheric humidity, vapour pressure, vapour pressure deficit,: specific humidity

virtual_ecosystem.models.abiotic.microclimate.update_forcing_boundary_conditions(state: dict[str, Any], hourly_forcing: dict[str, Any], hour: int) → dict[str, Any][source]#

Update forcing boundary conditions for microclimate model.

This function updates boundary conditions and forcing for atmospheric air temperature, relative humidity, shortwave absorption, evapotranspiration, and soil evaporation for the current hour.

Parameters:

state – Current state variables for microclimate model
hourly_forcing – Generated hourly profiles for atmospheric forcing variables
hour – Current hour index

Returns:

Updated state variables with new boundary conditions

API for the microclimate module#

API for the `microclimate` module#