API documentation for the abiotic_model module

The abiotic_model module creates a AbioticModel class as a child of the BaseModel class. This implements the full complexity abiotic model.

TODO There are currently a number of unresolved/not implemented processes which require further advancement in other models of the Virtual Ecosystem or potentially some changes to the vertical layer structure:

  • add process based calculation of soil temperature

  • change temperatures to Kelvin

  • adjust for soil moisture default in mm (once updated in hydrology model)

  • coordinate latent heat flux/evapotranspiration processes between plants and abiotic

  • add soil fluxes to lower atmosphere (might need to drop ‘subcanopy’ layer)

  • introducte ‘metaconstants’ to support sharing of constants between models

  • add self.model_timing.update_interval in seconds as input to soil balance

  • expand tests to cover different atmospheric conditions

  • expand use of LayerStructure and shape for more compact concatenating

The AbioticModel class

class virtual_ecosystem.models.abiotic.abiotic_model.AbioticModel(data: Data, core_components: CoreComponents, model_constants: AbioticConsts = AbioticConsts(), **kwargs: Any)

A class describing the abiotic model.

Parameters:

  • data – The data object to be used in the model.

  • core_components – The core components used across models.

  • model_constants – Set of constants for the abiotic model.

Methods:

cleanup()

Placeholder function for abiotic model cleanup.

from_config(data, core_components, config)

Factory function to initialise the abiotic model from configuration.

setup()

Function to set up the abiotic model.

spinup()

Placeholder function to spin up the abiotic model.

update(time_index, **kwargs)

Function to update the abiotic model.

Attributes:

model_constants

Set of constants for the abiotic model.

simple_constants

Set of constants for simple abiotic model.
cleanup() → None

Placeholder function for abiotic model cleanup.

core_constants: CoreConsts

The core constants used in the model.

data: Data

A Data instance providing access to the shared simulation data.

classmethod from_config(data: Data, core_components: CoreComponents, config: Config) → AbioticModel

Factory function to initialise the abiotic model from configuration.

This function unpacks the relevant information from the configuration file, and then uses it to initialise the model. If any information from the config is invalid rather than returning an initialised model instance an error is raised.

Parameters:

  • data – A Data instance.

  • core_components – The core components used across models.

  • config – A validated Virtual Ecosystem model configuration object.

layer_structure: LayerStructure

The LayerStructure details used in the model.

model_constants

Set of constants for the abiotic model.

model_timing: ModelTiming

The ModelTiming details used in the model.

model_update_bounds: tuple[pint.Quantity, pint.Quantity] = (<Quantity(1, 'hour')>, <Quantity(1, 'month')>)

Bounds on model update frequencies.

This class attribute defines two time intervals that define a lower and upper bound on the update frequency that can reasonably be used with a model. Models updated more often than the lower bound may fail to capture transient dynamics and models updated more slowly than the upper bound may fail to capture important temporal patterns.

required_init_vars: tuple[tuple[str, tuple[str, ...]], ...] = (('air_temperature_ref', ('spatial',)), ('relative_humidity_ref', ('spatial',)), ('topofcanopy_radiation', ('spatial',)))

Required variables for model initialisation.

This class property defines a set of variable names that must be present in the Data instance used to initialise an instance of this class. It is a tuple containing zero or more tuples, each providing a variable name and then a tuple of zero or more core axes that the variable must map onto.

For example: (('temperature', ('spatial', 'temporal')),)

setup() → None

Function to set up the abiotic model.

This function initializes soil temperature and canopy temperature for all corresponding layers and calculates the reference vapour pressure deficit for all time steps of the simulation. All variables are added directly to the self.data object.

simple_constants

Set of constants for simple abiotic model.

spinup() → None

Placeholder function to spin up the abiotic model.

update(time_index: int, **kwargs: Any) → None

Function to update the abiotic model.

The function updates the microclimate in the following order:

  • wind profiles

  • soil energy balance

  • conductivities

  • canopy energy balance for each layer

  • TODO representation of turbulent fluxes is inconsistent

  • TODO add all soil fluxes to atmosphere

  • TODO update soil temperatures

Parameters:

time_index – The index of the current time step in the data object.

vars_updated: tuple[str, ...] = ('air_temperature', 'canopy_temperature', 'soil_temperature', 'vapour_pressure', 'vapour_pressure_deficit', 'air_heat_conductivity', 'conductivity_from_ref_height', 'leaf_air_heat_conductivity', 'leaf_vapour_conductivity', 'wind_speed', 'friction_velocity', 'diabatic_correction_heat_above', 'diabatic_correction_momentum_above', 'diabatic_correction_heat_canopy', 'diabatic_correction_momentum_canopy', 'sensible_heat_flux', 'latent_heat_flux', 'ground_heat_flux', 'soil_absorption', 'longwave_emission_soil')

Variables that are updated by the model.

At the moment, this tuple is used to decide which variables to output from the Data object, i.e. every variable updated by a model used in the specific simulation. In future, this could also be used to prevent multiple models from updating the same variable and similar problems.