API documentation for the `configuration` module#

The configuration module provides the core model configuration elements for the Virtual Ecosystem. It defines shared pydantic base classes that are used to define configuration settings for a model.

Each model must define an object model_name.model_config.ModelConfiguration. For the science models, this object must inherit from ModelConfigurationRoot, which provides the common static setting. The core.model_config.ModelConfiguration configuration instead directly uses Configuration since it cannot be run in static mode. The model_name.model_config module can then include other Configuration classes that are used as nested fields within the root configuration class.

Classes:

`CompiledConfiguration`()	Compiled configuration class for Virtual Ecosystem models.
`Configuration`()	Base configuration class for the Virtual Ecosystem.
`DisturbanceConfigurationRoot`(*[, run_at, ...])	Root configuration class for disturbance Virtual Ecosystem models.
`ModelConfigurationRoot`(*[, static])	Root configuration class for individual Virtual Ecosystem models.
`T`	Generic type to support static typing of subconfigurations.

Data:

RST_TO_MD

Tags to replace when converting RST descriptions of fields to Markdown.

Functions:

`model_config_to_html`(model_name, config_object)	Renders the fields in a model configuration class as an HTML Table.
`placeholder_validator`(path, info)	Check for path placeholders and handle path substutition.

class virtual_ecosystem.core.configuration.CompiledConfiguration[source]#

Compiled configuration class for Virtual Ecosystem models.

This class is used as the base for dynamically compiled complete model returned by the generate_configuration() function. It provides a shared method to extract specific model configurations by name. This is needed because the dynamic creation means that model fields are not explicitly declared, so mypy gets does not handle configuration.plants, but we can use configuration.get_subconfiguration(“plants”) instead.

Methods:

`export_toml`(path)	TOML export method for a compiled configuration.
`get_disturbance_config`()	Get the compile configuration for disturbances, if any.
`get_subconfiguration`(name, as_class)	Get a named subconfiguration object from a compiled configuration.

export_toml(path: Path)[source]#

TOML export method for a compiled configuration.

Parameters:: path – The path to be used to export the configuration data.

get_disturbance_config() → CompiledConfiguration | None[source]#: Get the compile configuration for disturbances, if any.

get_subconfiguration(name: str, as_class: Callable[[...], T]) → T[source]#

Get a named subconfiguration object from a compiled configuration.

This method can be used to extract model configurations or the core configuration from a compiled configuration instance. The second argument is used to provide support for static typing in mypy by explicitly providing the type of the returned object. The method should be called as - for example:

subconfig: SubConfigConfiguration = (
    compiled_configuration_instance.get_subconfiguration(
        "subconfig", SubConfigConfiguration
    )
)

Parameters:

name – The required subconfiguration.
as_class – The class of objected returned by the method. This is not used by the method itself but is used to support static typing of the return value.

class virtual_ecosystem.core.configuration.Configuration[source]#

Base configuration class for the Virtual Ecosystem.

This model provides a common Pydantic base class for use in configuring the Virtual Ecosystem. This base class is used to share common configuration settings for all models. It is also used as the root configuration base for the core configuration settings.

virtual_ecosystem.core.configuration.DIRPATH_PLACEHOLDER(*args, **kwargs)#

Custom type for directory paths in configurations. This enforces the DirectoryPath validation to check that paths in configuration data actually point to existing paths. It also provides custom validation to allow a <DIRPATH_PLACEHOLDER> default value. This can be written to file - because the field does not use validate_defaults - but the custom validation specifically rejects incoming values that have been left with that default.

alias of Annotated[Path, PathType(path_type=dir), FieldInfo(annotation=NoneType, required=False, default=PosixPath(‘<DIRPATH_PLACEHOLDER>’)), BeforeValidator(func=placeholder_validator, json_schema_input_type=PydanticUndefined)]

class virtual_ecosystem.core.configuration.DisturbanceConfigurationRoot(*, run_at: int | tuple[int, ...] = (), run_every: tuple[int, ...] = (), priority: int = 0)[source]#

Root configuration class for disturbance Virtual Ecosystem models.

This model provides a common Pydantic base class that must be used to define the root configuration class of a Virtual Ecosystem disturbance model. Each disturbance must define an object model_name.model_config.ModelConfiguration that inherits from DisturbanceConfigurationRoot. The model_name.model_config module can then include other Configuration classes that are used as nested fields within the root configuration but can be only one ModelConfigurationRoot class per model. This base model sets common shared attributes across models: currently just the timing options.

It also validates the timing fields to ensure that at least one of them is set.

Attributes:

`priority`	Priority for the disturbance.
`run_at`	Define time indices to run at specific times.
`run_every`	Define a range of indices to run the disturbance.

Methods:

timing_options_are_not_both_empty()

Validate the timing options of the configuration.

priority: int#

Priority for the disturbance.

Every disturbance model must have a different priority.

run_at: int | tuple[int, ...]#

Define time indices to run at specific times.

Either a single integer or a list of integers indicating the time indices when the disturbance is to run.

run_every: tuple[int, ...]#

Define a range of indices to run the disturbance.

A tuple of integers indicating (start), or (start, step), or (start, step, stop), from where a list of integers indicating the time indices when the disturbance is to run can be constructed. If not provided, ‘step’ defaults to 1 and ‘stop’ defaults to the last time index. ‘start’ must always be provided.

timing_options_are_not_both_empty() → DisturbanceConfigurationRoot[source]#: Validate the timing options of the configuration.

virtual_ecosystem.core.configuration.FILEPATH_PLACEHOLDER(*args, **kwargs)#

Custom type for file paths in configurations. This enforces the FilePath validation to check that paths in configuration data actually point to existing paths. It also provides custom validation to allow a <FILEPATH_PLACEHOLDER> default value. This can be written to file - because the field does not use validate_defaults - but the custom validation specifically rejects incoming values that have been left with that default.

alias of Annotated[Path, PathType(path_type=file), FieldInfo(annotation=NoneType, required=False, default=PosixPath(‘<FILEPATH_PLACEHOLDER>’)), BeforeValidator(func=placeholder_validator, json_schema_input_type=PydanticUndefined)]

class virtual_ecosystem.core.configuration.ModelConfigurationRoot(*, static: bool = False)[source]#

Root configuration class for individual Virtual Ecosystem models.

This model provides a common Pydantic base class that must be used to define the root configuration class of a Virtual Ecosystem model. Each model must define an object model_name.model_config.ModelConfiguration that inherits from ModelConfigurationRoot. The model_name.model_config module can then include other Configuration classes that are used as nested fields within the root configuration but can be only one ModelConfigurationRoot class per model. This base model sets common shared attributes across models: currently just the shared static option.

Attributes:

static

The model static mode setting.

static: bool#: The model static mode setting.

virtual_ecosystem.core.configuration.RST_TO_MD = [(':cite:t:', '{cite:t}'), (':cite:p:', '{cite:p}'), (':attr:', '{attr}')]#: Tags to replace when converting RST descriptions of fields to Markdown.

class virtual_ecosystem.core.configuration.T#

Generic type to support static typing of subconfigurations.

alias of TypeVar(‘T’)

virtual_ecosystem.core.configuration.model_config_to_html(model_name: str, config_object: type[Configuration], rows_only: bool = False)[source]#

Renders the fields in a model configuration class as an HTML Table.

This is a helper function for use in documenting model configurations. It takes a model configuration class and then iterates over model fields, recursing into sub-models within the fields, to generate a simple HTML table showing the config sections and then the description and defaults of each setting. The CSS classes are defined in docs/source/_static/css/custom.css.

Parameters:

model_name – The name of the model as it would appear in a configuration file.
config_object – A ModelConfig instance
rows_only – Should the function wrap the returned rows with HTML table and tbody tags?

virtual_ecosystem.core.configuration.placeholder_validator(path: str, info: ValidationInfo) → str[source]#

Check for path placeholders and handle path substutition.

This custom validator rejects <FILEPATH_PLACEHOLDER> and <DIRPATH_PLACEHOLDER> values when loading file paths. It also looks for file or directory pathways defined using markers (‘$MARKER_NAME’) and substitutes in paths defined through the cli_paths argument to ve_run. When cli_paths are provided, the info.context dictionary passed down to this validator should contain a cli_paths dictionary mapping marker names to paths.

Parameters:

path – A field path value to validate.
info – A ValidationInfo instance providing context.

API documentation for the configuration module#

API documentation for the `configuration` module#