API documentation for the registry module

The registry module is used to populate the MODULE_REGISTRY.

The registry is a dictionary, keyed using the short names of models, such as core or plants. Each entry provides a ModuleInfo dataclass, which provides the BaseModel subclass for each model and its configuration model. The core model has a configuration model but has no BaseModel subclass.

The module also provides the register_module() function, which is used to populate the registry with the components of a given module.

Data:

DISTURBANCE_REGISTRY	The global disturbance module registry.
MODULE_REGISTRY	The global module registry.

Classes:

ModuleInfo(model, config, is_core)

Dataclass for module information.

Functions:

get_model_configuration_class(module_name, ...)	Get the root configuration class for a model.
register_disturbance(module_name)	Register module components.
register_module(module_name)	Register module components.

virtual_ecosystem.core.registry.DISTURBANCE_REGISTRY: dict[str, ModuleInfo] = {}

The global disturbance module registry.

As each module is registered using register_disturbance(), a ModuleInfo dataclass will be added to this registry using the short name of the module being registered.

virtual_ecosystem.core.registry.MODULE_REGISTRY: dict[str, ModuleInfo] = {}

The global module registry.

As each module is registered using register_module(), a ModuleInfo dataclass will be added to this registry using the short name of the module being registered.

class virtual_ecosystem.core.registry.ModuleInfo(model: Any, config: type[Configuration], is_core: bool)

Dataclass for module information.

This dataclass holds references to Base subclasses and configuration class for a model or disturbance and is used to hold that information with the corresponding registry. Note that the virtual_ecosystem.core module does not have an associated BaseModel subclass and the model attribute for the core module will be None.

Attributes:

config	A Configuration subclass that provides a pydantic model to populate and validate the model configuration.
is_core	Logical flag indicating if an instance contains registration information for the core module.
model	The Base subclass associated with the module.

config: type[Configuration]

A Configuration subclass that provides a pydantic model to populate and validate the model configuration.

is_core: bool

Logical flag indicating if an instance contains registration information for the core module.

model: Any

The Base subclass associated with the module.

virtual_ecosystem.core.registry.get_model_configuration_class(module_name: str, module_name_short: str)

Get the root configuration class for a model.

Discovery is name based, with the function attempting to retrieve a class based on the model short name:

• plants -> PlantsConfiguration,

• abiotic_simple -> AbioticSimpleConfiguration

Parameters:

• module_name – The full module name (e.g. virtual_ecosystem.models.plants)

• module_name_short – The short module name (e.g plants)

virtual_ecosystem.core.registry.register_disturbance(module_name: str) → None

Register module components.

This function loads the BaseDisturbance() subclass for a module and its root configuration object. It then adds a ModuleInfo dataclass instance to the DISTURBANCE_REGISTRY containing references to those classes. The core module does not have an associated module.

This function is primarily used within the generate_configuration() method to register the components required to validate and setup the model configuration for a particular simulation.

Parameters:

module_name – The full name of the module to be registered (e.g. ‘virtual_ecosystem.disturbances.logging’).

Raises:

• RuntimeError – if the requested module cannot be found or where a module does not provide a single subclass of the BaseDisturbance class.

• Exception – other exceptions can occur when loading the JSON schema fails.

virtual_ecosystem.core.registry.register_module(module_name: str) → None

Register module components.

This function loads the main BaseModel() subclass for a module and the root configuration object for a module. It then adds a ModuleInfo dataclass instance to the MODULE_REGISTRY containing references to those classes. The core module does not have an associated module.

This function is primarily used within the generate_configuration() method to register the components required to validate and setup the model configuration for a particular simulation.

Parameters:

module_name – The full name of the module to be registered (e.g. ‘virtual_ecosystem.models.animal’).

Raises:

RuntimeError – if the requested module cannot be found or where a module does not provide a single subclass of the BaseModel class.