API for the conductivities module

The models.abiotic.conductivities module calculates the conductivities for the energy balance of the Virtual Ecosystem based on Maclean and Klinges (2021).

Functions:

calculate_air_heat_conductivity_above(...)	Calculate air heat conductivity by turbulent convection above canopy.
calculate_air_heat_conductivity_canopy(...)	Calculate air heat conductivity by turbulent convection in canopy,[mol m-2 s-1].
calculate_current_conductivities(data, ...)	Calculate conductivities based on current reference data.
calculate_leaf_air_heat_conductivity(...)	Calculate forced or free laminer conductance between leaf and air,[mol m-2 s-1].
calculate_leaf_vapour_conductivity(...)	Calculate leaf air conductivity for vapour, [mol m-2 s-1].
initialise_conductivities(layer_heights, ...)	Initialise conductivities for first model time step, [mol m-2 s-1].
interpolate_along_heights(start_height, ...)	Linear interpolation for given start and end values along a height axis.

virtual_ecosystem.models.abiotic.conductivities.calculate_air_heat_conductivity_above(height_above_canopy: ndarray[Any, dtype[float32]], zero_displacement_height: ndarray[Any, dtype[float32]], canopy_height: ndarray[Any, dtype[float32]], friction_velocity: ndarray[Any, dtype[float32]], molar_density_air: ndarray[Any, dtype[float32]], diabatic_correction_heat: ndarray[Any, dtype[float32]], von_karmans_constant: float) → ndarray[Any, dtype[float32]]

Calculate air heat conductivity by turbulent convection above canopy.

Heat conductance, \(g_{t}\) between any two heights \(z_{1}\) and \(z_{0}\) above-canopy is given by

\[g_{t} = \frac {0.4 \hat{\rho} u^{*}}{ln(\frac{z_{1} - d}{z_{0} - d}) + \Psi_{H}}\]

where \(\hat{\rho}\) is the molar density or air, \(u^{*}\) is the friction velocity, \(d\) is the zero displacement height, and \(\Psi_{H}\) is the diabatic correction factor for heat.

Parameters:

• height_above_canopy – Height above canopy, [m]

• zero_displacement_height – Zero displacement height, [m]

• canopy_height – Canopy height, [m]

• friction_velocity – Friction velocity, dimensionless

• molar_density_air – Molar density of air, [mole m-3]

• diabatic_correction_heat – Diabatic correction factor for heat, dimensionless

• von_karmans_constant – Von Karman constant, unitless

Returns:

Air heat conductivity by turbulent convection above canopy, [mol m-2 s-1]

virtual_ecosystem.models.abiotic.conductivities.calculate_air_heat_conductivity_canopy(attenuation_coefficient: ndarray[Any, dtype[float32]], mean_mixing_length: ndarray[Any, dtype[float32]], molar_density_air: ndarray[Any, dtype[float32]], upper_height: ndarray[Any, dtype[float32]], lower_height: ndarray[Any, dtype[float32]], relative_turbulence_intensity: ndarray[Any, dtype[float32]], top_of_canopy_wind_speed: ndarray[Any, dtype[float32]], diabatic_correction_momentum: ndarray[Any, dtype[float32]], canopy_height: ndarray[Any, dtype[float32]]) → ndarray[Any, dtype[float32]]

Calculate air heat conductivity by turbulent convection in canopy,[mol m-2 s-1].

Within-canopy heat conductance (\(g_{t}\)) between any two heights \(z_{1}\) and \(z_{0}\) below-canopy is given by

\[g_{t} = \frac{u_{h}l_{m}i_{w}a} {(exp(\frac{-a_{z_{0}}}{h-1}) - exp(\frac{-a_{z_{1}}}{h-1})) \Phi_{H}}\]

where \(u_{h}\) is wind speed at the top of the canopy at height \(h\), \(a\) is a wind attenuation coefficient, \(i_{w}\) is a coefficient describing relative turbulence intensity, \(l_{m}\) is the mean mixing length, equivalent to the free space between the leaves and stems, and \(\Phi_{H}\) is a within-canopy diabatic correction factor for heat.

TODO better tests for different conditions

Parameters:

• attenuation_coefficient – Wind attenuation coefficient, dimensionless

• mean_mixing_length – Mixing length for canopy air transport, [m]

• molar_density_air – Molar density of air, [mol m-3]

• upper_height – Height of upper layer, [m]

• lower_height – Height of lower layer, [m]

• relative_turbulence_intensity – Relative turbulence intensity, dimensionless

• top_of_canopy_wind_speed – Top of canopy wind speed, [m s-1]

• diabatic_correction_momentum – Diabatic correction factor for momentum, dimensionless

• canopy_height – Canopy height, [m]

Returns:

air heat conductivity by turbulent convection in the canopy, [mol m-2 s-1]

virtual_ecosystem.models.abiotic.conductivities.calculate_current_conductivities(data: Data, characteristic_dimension_leaf: float | ndarray[Any, dtype[float32]], von_karmans_constant: float, abiotic_constants: AbioticConsts) → dict[str, ndarray[Any, dtype[float32]]]

Calculate conductivities based on current reference data.

This function calculates the conductivites for heat and vapour between air layers and the leaf and surrounding atmosphere for the current time step. The first value on the vertical axis is 2m above the canopy, the second value corresponds to the top of the canopy.

The data object must provide the following variables:

• layer_heights: layer heights, [m]

• air_temperature, [C]

• canopy_temperature, [C]

• attenuation_coefficient: Wind attenuation coefficient, dimensionless

• mean_mixing_length: Mixing length for canopy air transport, [m]

• molar_density_air: Molar density of air, [mol m-3]

• relative_turbulence_intensity: Relative turbulence intensity, dimensionless

• wind_speed: wind speed, [m s-1]

• stomatal_conductance: Stomatal conductance, [mmol m-2 s-1]

• zero_displacement_height: Zero displacement height, [m]

• friction_velocity: Friction velocity

• diabatic_correction_heat: Diabatic correction for heat in canopy

Parameters:

• characteristic_dimension_leaf – Chacteristic dimension of leaf, typically around 0.7 * leaf width, [m]. This parameter can be a float, a 2D-array with one value per grid cell, or a 3D-array with one value for each layer.

• von_karmans_constant – Von Karman constant

• abiotic_constants – set of abiotic constants

Returns:

dictionnary of conductivities, [mol m-2 s-1]

virtual_ecosystem.models.abiotic.conductivities.calculate_leaf_air_heat_conductivity(temperature: ndarray[Any, dtype[float32]], wind_speed: ndarray[Any, dtype[float32]], characteristic_dimension_leaf: float | ndarray[Any, dtype[float32]], temperature_difference: ndarray[Any, dtype[float32]], molar_density_air: ndarray[Any, dtype[float32]], kinematic_viscosity_parameters: list[float], thermal_diffusivity_parameters: list[float], grashof_parameter: float, forced_conductance_parameter: float, positive_free_conductance_parameter: float, negative_free_conductance_parameter: float) → ndarray[Any, dtype[float32]]

Calculate forced or free laminer conductance between leaf and air,[mol m-2 s-1].

When wind speeds are moderate to high, conduction between the leaf and air \(g_{Ha}\) is predominantly under laminar forced convection and from e.g. Campbell and Norman (2012) is given by

\[g_{Ha} = \frac {0.664 \hat{\rho} D_{H} R_{e}^{0.5} P_{r}^{0.5}}{x_{d}}\]

where \(D_{H}\) is thermal diffusivity, \(x_{d}\) is the characteristic dimension of the leaf, \(\hat{\rho}\) is the molar density of air, \(R_{e}\) is the Reynolds number, and \(P_{r}\) is the Prandtl number.

When wind speeds are low, an expression that is adequate for leaves is given by (Campbell and Norman, 2012)

\[g_{Ha} = \frac{0.54 \hat{\rho} D_{H} (G_{r}P_{r})^{0.25}}{x_{d}}\]

where \(G_{r}\) is the Grashof number. When the leaf is cooler than the air, the heat transfer is only half as efficient so the constant 0.54 becomes 0.26.

TODO better tests for different conditions

Parameters:

• temperature – Temperature, [C]

• wind_speed – Wind speed, [m s-1]

• characteristic_dimension_leaf – Chacteristic dimension of leaf, typically around 0.7 * leaf width, [m]. This parameter can be a float, a 2D-array with one value per grid cell, or a 3D-array with one value for each layer.

• temperature_difference – Estimate of temperature differences of surface and air, e.g. from previous time step, see notes in Maclean and Klinges (2021)

• molar_density_air – Molar density of air, [mol m-3]

• kinematic_viscosity_parameters – Parameters in calculation of kinematic viscosity

• thermal_diffusivity_parameters – Parameters in calculation of thermal diffusivity

• grashof_parameter – Parameter in calculation of Grashof number

• forced_conductance_parameter – Parameter in calculation of forced conductance

• positive_free_conductance_parameter – Parameter in calculation of free conductance for positive temperature difference

• negative_free_conductance_parameter – Parameter in calculation of free conductance for negative temperature difference

Returns:

Leaf air heat conductance, [mol m-2 s-1]

virtual_ecosystem.models.abiotic.conductivities.calculate_leaf_vapour_conductivity(leaf_air_conductivity: ndarray[Any, dtype[float32]], stomatal_conductance: float | ndarray[Any, dtype[float32]]) → ndarray[Any, dtype[float32]]

Calculate leaf air conductivity for vapour, [mol m-2 s-1].

The conductance for vapour loss from leaves \(g_{v}\) depends on stomatal conductance \(g_{c}\) and heat conductivity between air and leaf \(g_{Ha}\):

\[g_{v} = \frac{1}{(\frac{1}{g_{Ha}} + \frac{1}{g_{c}})\]

(Maclean and Klinges, 2021).

Parameters:

• leaf_air_conductivity – Heat conductivity between air and leaf, [mol m-2 s-1]

• stomatal_conductance – Stomatal conductance, [mol m-2 s-1]

Returns:

Leaf vapour conductivity, [mol m-2 s-1]

virtual_ecosystem.models.abiotic.conductivities.initialise_conductivities(layer_heights: DataArray, initial_air_conductivity: float, top_leaf_vapour_conductivity: float, bottom_leaf_vapour_conductivity: float, top_leaf_air_conductivity: float, bottom_leaf_air_conductivity: float) → dict[str, DataArray]

Initialise conductivities for first model time step, [mol m-2 s-1].

Air heat conductivity by turbulent convection (\(g_{t}\)) is scaled by canopy height and number of canopy layers (and hence distance between nodes). Leaf-air vapour conductivity (\(g_{v}\)) and leaf-air heat conductivity (\(g_{Ha}\)) are linearly interpolated between intial values.

The first value in each output represents conductivity between the air at 2 m above canopy and the highest canopy layer. The last (above ground) value represents conductivity between the ground and the lowest canopy node.

Parameters:

• layer_height – layer heights, [m]

• initial_air_conductivity – Initial value for heat conductivity by turbulent convection in air, [mol m-2 s-1]

• top_leaf_vapour_conductivity – Initial leaf vapour conductivity at the top of the canopy, [mol m-2 s-1]

• bottom_leaf_vapour_conductivity – Initial leaf vapour conductivity at the bottom of the canopy, [mol m-2 s-1]

• top_leaf_air_conductivity – Initial leaf air heat conductivity at the top of the canopy, [mol m-2 s-1]

• bottom_leaf_air_conductivity – Initial leaf air heat conductivity at the surface, [mol m-2 s-1]

Returns:

Heat conductivity in air of each canopy layer node, [mol m-2 s-1], Leaf conductivity to vapour loss for each canopy layer node, [mol m-2 s-1], Heat conductivity between air and leaf for each canopy layer node, [mol m-2 s-1]

virtual_ecosystem.models.abiotic.conductivities.interpolate_along_heights(start_height: ndarray[Any, dtype[float32]], end_height: ndarray[Any, dtype[float32]], target_heights: ndarray[Any, dtype[float32]], start_value: float | ndarray[Any, dtype[float32]], end_value: float | ndarray[Any, dtype[float32]]) → ndarray[Any, dtype[float32]]

Linear interpolation for given start and end values along a height axis.

This function can be used to lineraly interpolate atmospheric or soil variables such as temperature or humidity for a set of user specified heights based on the top and bottom values. Note that the start value has to be the surface and the end value has to be above ground.

Parameters:

• start_height – Starting heights of the interpolation range, [m].

• end_height – Ending heights of the interpolation range, [m]

• target_heights – Array of target heights with the first column representing heights and subsequent columns representing additional dimensions, here cell_id.

• start_value – The value at the starting height.

• end_value – The value at the ending height.

Returns:

Interpolated values corresponding to the target heights