API for the soil_energy_balance module

The models.abiotic.soil_energy_balance module calculates the soil energy balance for the Virtual Ecosystem.

The first part of this module determines the energy balance at the surface. calculate_soil_heat_balance() calculates how incoming solar radiation that reaches the surface is partitioned in sensible, latent, and ground heat flux. Further, longwave emission is calculated and the topsoil temperature is updated.

The second part determines the soil temperature profile at different depths. We divide the soil into discrete layers to numerically solve the time-dependent differential equation that describes soil temperature as a function of depth and time (see TODO THIS FUNCTION for details).

Functions:

calculate_ground_heat_flux(...)

Calculate ground heat flux.

calculate_latent_heat_flux_from_soil_evaporation(...)

Calculate latent heat flux from soil evaporation.

calculate_sensible_heat_flux_soil(...)

Calculate sensible heat flux from soil surface.

calculate_soil_absorption(...)

Calculate soil absorption of shortwave radiation.

calculate_soil_heat_balance(data, ...)

Calculate soil heat balance.

update_surface_temperature(...)

Update surface temperature after exchange of radiation.
virtual_ecosystem.models.abiotic.soil_energy_balance.calculate_ground_heat_flux(soil_absorbed_radiation: ndarray[Any, dtype[float32]], topsoil_longwave_emission: ndarray[Any, dtype[float32]], topsoil_sensible_heat_flux: ndarray[Any, dtype[float32]], topsoil_latent_heat_flux: ndarray[Any, dtype[float32]]) → ndarray[Any, dtype[float32]]

Calculate ground heat flux.

The ground heat flux is calculated as the residual of splitting incoming raditaion into emitted longwave radiation, and sensible and latent heat flux. A positive ground heat flux means a warming of the soil, a negative flux indicates a cooling of the soil.

Parameters:

  • soil_absorbed_radiation – Shortwave radiation absorbed by topsoil, [W m-2]

  • topsoil_longwave_emission – Longwave radiation emitted by topsoil, [W m-2]

  • topsoil_sensible_heat_flux – Sensible heat flux from topsoil, [W m-2]

  • topsoil_latent_heat_flux – Latent heat flux from topsoil, [W m-2]

Returns:

ground heat flux, [W m-2]

virtual_ecosystem.models.abiotic.soil_energy_balance.calculate_latent_heat_flux_from_soil_evaporation(soil_evaporation: ndarray[Any, dtype[float32]], latent_heat_vapourisation: ndarray[Any, dtype[float32]]) → ndarray[Any, dtype[float32]]

Calculate latent heat flux from soil evaporation.

We assume that 1 mm of evaporated water is equivalent to 1 kg of water.

Parameters:

  • soil_evaporation – Soil evaporation, [mm]

  • latent_heat_vapourisation – Latent heat of vapourisation, [J kg-1]

Returns:

latent heat flux from topsoil, [W m-2]

virtual_ecosystem.models.abiotic.soil_energy_balance.calculate_sensible_heat_flux_soil(air_temperature_surface: ndarray[Any, dtype[float32]], topsoil_temperature: ndarray[Any, dtype[float32]], molar_density_air: ndarray[Any, dtype[float32]], specific_heat_air: ndarray[Any, dtype[float32]], aerodynamic_resistance: ndarray[Any, dtype[float32]]) → ndarray[Any, dtype[float32]]

Calculate sensible heat flux from soil surface.

The sensible heat flux from the soil surface is given by:

\(H_{S} = \frac {\rho_{air} C_{air} (T_{S} - T_{b}^{A})}{r_{A}}\)

Where \(T_{S}\) is the soil surface temperature, \(T_{b}^{A}\) is the temperature of the bottom air layer and \(r_{A}\) is the aerodynamic resistance of the soil surface, given by

\(r_{A} = \frac {C_{S}}{u_{b}}\)

Where \(u_{b}\) is the wind speed in the bottom air layer and \(C_{S}\) is the soil surface heat transfer coefficient.

Parameters:

  • air_temperature_surface – Air temperature near the surface, [K]

  • topsoil_temperature – Topsoil temperature, [K]

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

  • specific_heat_air – Specific heat of air, [J mol-1 K-1]

  • aerodynamic_resistance – Aerodynamic resistance near the surface

Returns:

Sensible heat flux from topsoil, [W m-2]

virtual_ecosystem.models.abiotic.soil_energy_balance.calculate_soil_absorption(shortwave_radiation_surface: ndarray[Any, dtype[float32]], surface_albedo: float | ndarray[Any, dtype[float32]]) → ndarray[Any, dtype[float32]]

Calculate soil absorption of shortwave radiation.

The amount of shortwave radiation that is absorbed by the topsoil layer is a function of incoming radiation and surface albedo. In reality, surface albedo is modulated by soil moisture. The current implementation of soil absorption assumes a constant albedo within each grid cell because the radiation that reaches the surface below the canopy is typically quite small (<5%).

Parameters:

  • shortwave_radiation_surface – Shortwave radiation that reaches surface, [W m-2]

  • surface_albedo – Surface albedo, dimensionless.

Returns:

shortwave radiation absorbed by soil surface, [W m-2]

virtual_ecosystem.models.abiotic.soil_energy_balance.calculate_soil_heat_balance(data: Data, topsoil_layer_index: int, update_interval: Quantity, abiotic_consts: AbioticConsts, core_consts: CoreConsts) → dict[str, ndarray[Any, dtype[float32]]]

Calculate soil heat balance.

This function performs a series of calculations to solve the energy balance at the surface at the interface between soil and atmoshere:

  • calculate soil absorption (\(R_{N{} * (1-albedo)\))

  • calculate sensible heat flux (convective flux from soil to atmosphere above)

  • calculate latent heat flux (conversion of soil evaporation)

  • calculate ground heat flux (conductive flux)

  • update topsoil temperature

The function takes an instance of data object, AbioticConsts and CoreConsts which must provide the following inputs:

  • soil_temperature: Soil temperature

  • air_temperature: Air temperature

  • shortwave_radiation_surface: Shortwave radiation that reaches surface, [W m-2]

  • soil_evaporation: Soil evaporation, [mm]

  • soil_emissivity: Soil emissivity, dimensionless

  • surface_albedo: Surface albedo, dimensionless

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

  • specific_heat_air: Specific heat of air, [J mol-1 K-1]

  • aerodynamic_resistance_surface: Aerodynamic resistance near the surface

  • stefan_boltzmann: Stefan Boltzmann constant, [W m-2 K-4]

  • latent_heat_vapourisation: Latent heat of vapourisation, [kJ kg-1]

  • surface_layer_depth: Topsoil layer depth, [m]

  • grid_cell_area: Grid cell area, [m2]

  • specific_heat_capacity_soil: Soil specific heat capacity, [J kg-1 K-1]

  • volume_to_weight_conversion: Factor to convert between soil volume and weight [kg]

Parameters:

  • data – instance if a data object

  • update_interval – Update interval, [s]

  • AbioticConsts – set of constants specific to abiotic model

  • CoreConsts – set of constants that are shared across the model

Returns:

dictionnary with soil shortwave absorption, soil longwave emission, sensible and

latent heat flux from the soil, ground heat flux, and updated topsoil temperature

virtual_ecosystem.models.abiotic.soil_energy_balance.update_surface_temperature(topsoil_temperature: ndarray[Any, dtype[float32]], surface_net_radiation: ndarray[Any, dtype[float32]], surface_layer_depth: float | ndarray[Any, dtype[float32]], grid_cell_area: float, update_interval: Quantity, specific_heat_capacity_soil: float | ndarray[Any, dtype[float32]], volume_to_weight_conversion: float | ndarray[Any, dtype[float32]]) → ndarray[Any, dtype[float32]]

Update surface temperature after exchange of radiation.

This function calculates the surface temperature after absorption of shortwave radiation, emission of longwave radiation, and surface fluxes. This process usually happens in the top few centimeters of the soil column, which is much less than the thickness of the upper soil layer of the current layer implementation. In the simulation flow, we therefore set the topsoil layer depth to 0.05, TODO merge this into temperature profile.

Parameters:

  • topsoil_temperature – Topsoil temperature

  • surface_net_radiation – Longwave or shortwave radiation that enters (positive) or leaves (negative) the topsoil, [W m-2]

  • surface_layer_depth – Topsoil layer depth, [m]

  • grid_cell_area – Grid cell area, [m2]

  • update_interval – Update interval to convert between W and J, [s]

  • specific_heat_capacity_soil – Soil specific heat capacity, [J kg-1 K-1]

  • volume_to_weight_conversion – Factor to convert between soil volume and weight in kilograms

Returns:

topsoil temperature