API documentation for the soil_model
module
The soil_model
module creates a
SoilModel
class as a child of the
BaseModel
class. At present a lot of the
abstract methods of the parent class (e.g.
setup()
and
spinup()
) are overwritten using
placeholder functions that don’t do anything. This will change as the Virtual Ecosystem
model develops. The factory method
from_config()
exists in a
more complete state, and unpacks a small number of parameters from our currently pretty
minimal configuration dictionary. These parameters are then used to generate a class
instance. If errors crop here when converting the information from the config dictionary
to the required types (e.g. timedelta64
) they are caught and then
logged, and at the end of the unpacking an error is thrown. This error should be caught
and handled by downstream functions so that all model configuration failures can be
reported as one.
Exceptions:
Custom exception class for cases when model integration cannot be completed. |
Classes:
|
A class defining the soil model. |
Functions:
|
Function that constructs the full soil model in a solve_ivp friendly form. |
|
Constructs a list of slices based on the number of grid cells and pools. |
- exception virtual_ecosystem.models.soil.soil_model.IntegrationError
Custom exception class for cases when model integration cannot be completed.
- class virtual_ecosystem.models.soil.soil_model.SoilModel(data: Data, core_components: CoreComponents, model_constants: SoilConsts, **kwargs: Any)
A class defining the soil model.
This model can be configured based on the data object and a config dictionary. It can be updated by numerical integration. At present the underlying model this class wraps is quite simple (i.e. four soil carbon pools), but this will get more complex as the Virtual Ecosystem develops.
- Parameters:
data – The data object to be used in the model.
update_interval – Time to wait between updates of the model state.
soil_layers – A list giving the number and depth of soil layers to be modelled.
canopy_layers – The number of canopy layers to be modelled.
constants – Set of constants for the soil model.
Methods:
cleanup
()Placeholder function for soil model cleanup.
from_config
(data, core_components, config)Factory function to initialise the soil model from configuration.
Integrate the soil model.
setup
()Placeholder function to setup up the soil model.
spinup
()Placeholder function to spin up the soil model.
update
(time_index, **kwargs)Update the soil model by integrating.
Attributes:
Set of constants for the soil model.
The layer in the data object representing the first soil layer.
- core_constants: CoreConsts
The core constants used in the model.
- classmethod from_config(data: Data, core_components: CoreComponents, config: Config) SoilModel
Factory function to initialise the soil 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.
- integrate() dict[str, DataArray]
Integrate the soil model.
For now a single integration will be used to advance the entire soil module. However, this might get split into several separate integrations in future (if that is feasible).
This function unpacks the variables that are to be integrated into a single numpy array suitable for integration.
- Returns:
A data array containing the new pool values (i.e. the values at the final time point)
- Raises:
IntegrationError – When the integration cannot be successfully completed.
- layer_structure: LayerStructure
The LayerStructure details used in the model.
- model_constants
Set of constants for the soil model.
- model_timing: ModelTiming
The ModelTiming details used in the model.
- model_update_bounds: tuple[pint.Quantity, pint.Quantity] = (<Quantity(30, 'minute')>, <Quantity(3, '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, ...]], ...] = (('soil_c_pool_maom', ('spatial',)), ('soil_c_pool_lmwc', ('spatial',)), ('soil_c_pool_microbe', ('spatial',)), ('soil_c_pool_pom', ('spatial',)), ('pH', ('spatial',)), ('bulk_density', ('spatial',)), ('clay_fraction', ('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')),)
- top_soil_layer_index
The layer in the data object representing the first soil layer.
- update(time_index: int, **kwargs: Any) None
Update the soil model by integrating.
- Parameters:
time_index – The index representing the current time step in the data object.
- vars_updated: tuple[str, ...] = ('soil_c_pool_maom', 'soil_c_pool_lmwc', 'soil_c_pool_microbe', 'soil_c_pool_pom', 'soil_enzyme_pom', 'soil_enzyme_maom')
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.
- virtual_ecosystem.models.soil.soil_model.construct_full_soil_model(t: float, pools: ndarray[Any, dtype[float32]], data: Data, no_cells: int, top_soil_layer_index: int, delta_pools_ordered: dict[str, ndarray[Any, dtype[float32]]], model_constants: SoilConsts, core_constants: CoreConsts) ndarray[Any, dtype[float32]]
Function that constructs the full soil model in a solve_ivp friendly form.
- Parameters:
t – Current time [days]. At present the model has no explicit time dependence, but the function must still be accept a time value to allow it to be integrated.
pools – An array containing all soil pools in a single vector
data – The data object, used to populate the arguments i.e. pH and bulk density
no_cells – Number of grid cells the integration is being performed over
top_soil_layer_index – Index for layer in data object representing top soil layer
delta_pools_ordered – Dictionary to store pool changes in the order that pools are stored in the initial condition vector.
model_constants – Set of constants for the soil model.
core_constants – Set of constants shared between models.
- Returns:
The rate of change for each soil pool
- virtual_ecosystem.models.soil.soil_model.make_slices(no_cells: int, no_pools: int) list[slice]
Constructs a list of slices based on the number of grid cells and pools.
- Parameters:
no_cells – Number of grid cells the pools are defined for
no_pools – Number of soil pools being integrated
- Returns:
A list of containing the correct number of correctly spaced slices