API documentation for the model_config module

The models.animal.constants module contains a set of dataclasses containing constants” (fitting relationships taken from the literature) required by the broader animal module

Classes:

AnimalConfiguration(*, static, ...[, ...])	Root configuration class for the animal model.
AnimalConstants(*, density_scaling_method, ...)	Dataclass to store all constants related to animals.
AnimalExportConfig(*[, enabled, ...])	Configuration for animal cohort data export.
ResourcePoolExportConfig(*[, enabled, ...])	Configuration for resource pool data export.

Functions:

deserialise_diet_type(diet)	Deserialise string diet terms to DietType.
serialise_diet_type(diet)	Serialise DietType Flag value to string.

class virtual_ecosystem.models.animal.model_config.AnimalConfiguration(*, static: bool = False, functional_group_definitions_path: ~typing.Annotated[~pathlib.Path, ~pydantic.types.PathType(path_type=file), ~pydantic.functional_validators.BeforeValidator(func=~virtual_ecosystem.core.configuration.placeholder_validator, json_schema_input_type=PydanticUndefined)] = PosixPath('<FILEPATH_PLACEHOLDER>'), constants: ~virtual_ecosystem.models.animal.model_config.AnimalConstants = AnimalConstants(density_scaling_method='madingley', total_heterotroph_biomass_density_kg_m2=0.151, damuths_law_terms={<TaxaType.MAMMAL: 'mammal'>: {<DietType.HERBIVORE: 99487>: (-0.75, 4.23), <DietType.CARNIVORE: 31488>: (-0.75, 1.0), <DietType.OMNIVORE: 130975>: (-0.75, 3.0)}, <TaxaType.BIRD: 'bird'>: {<DietType.HERBIVORE: 99487>: (-0.75, 5.0), <DietType.CARNIVORE: 31488>: (-0.75, 2.0), <DietType.OMNIVORE: 130975>: (-0.75, 3.0)}, <TaxaType.INVERTEBRATE: 'invertebrate'>: {<DietType.HERBIVORE: 99487>: (-0.75, 5.0), <DietType.CARNIVORE: 31488>: (-0.75, 2.0), <DietType.OMNIVORE: 130975>: (-0.75, 3.0)}, <TaxaType.AMPHIBIAN: 'amphibian'>: {<DietType.HERBIVORE: 99487>: (-0.75, 5.0), <DietType.CARNIVORE: 31488>: (-0.75, 2.0), <DietType.OMNIVORE: 130975>: (-0.75, 3.0)}, <TaxaType.REPTILE: 'reptile'>: {<DietType.HERBIVORE: 99487>: (-0.75, 5.0), <DietType.CARNIVORE: 31488>: (-0.75, 2.0), <DietType.OMNIVORE: 130975>: (-0.75, 3.0)}}, madingley_biomass_scaling_terms=(0.6, 300000.0), metabolic_scaling_coefficients=(0.037, 0.69), metabolic_rate_terms={<MetabolicType.ENDOTHERMIC: 'endothermic'>: {'basal': (41900000000.0, 0.69), 'field': (908000000000.0, 0.7)}, <MetabolicType.ECTOTHERMIC: 'ectothermic'>: {'basal': (41900000000.0, 0.69), 'field': (149000000000.0, 0.88)}}, energy_density={'meat': 7000.0, 'plant': 18200000.0}, conversion_efficiency={<DietType.HERBIVORE: 99487>: 0.1, <DietType.CARNIVORE: 31488>: 0.25, <DietType.OMNIVORE: 130975>: 0.175}, mechanical_efficiency={<DietType.HERBIVORE: 99487>: 0.9, <DietType.CARNIVORE: 31488>: 0.8, <DietType.OMNIVORE: 130975>: 0.85}, prey_mass_scaling_terms={<MetabolicType.ENDOTHERMIC: 'endothermic'>: {<TaxaType.MAMMAL: 'mammal'>: (1.0, 1.0), <TaxaType.BIRD: 'bird'>: (1.0, 1.0)}, <MetabolicType.ECTOTHERMIC: 'ectothermic'>: {<TaxaType.INVERTEBRATE: 'invertebrate'>: (1.0, 1.0), <TaxaType.AMPHIBIAN: 'amphibian'>: (1.0, 1.0), <TaxaType.REPTILE: 'reptile'>: (1.0, 1.0)}}, cnp_proportion_terms={<TaxaType.MAMMAL: 'mammal'>: {'C': 0.5, 'N': 0.3, 'P': 0.2}, <TaxaType.BIRD: 'bird'>: {'C': 0.4, 'N': 0.3, 'P': 0.3}, <TaxaType.INVERTEBRATE: 'invertebrate'>: {'C': 0.4, 'N': 0.2, 'P': 0.4}, <TaxaType.AMPHIBIAN: 'amphibian'>: {'C': 0.4, 'N': 0.2, 'P': 0.4}, <TaxaType.REPTILE: 'reptile'>: {'C': 0.4, 'N': 0.2, 'P': 0.4}}, birth_mass_threshold=1.5, flow_to_reproductive_mass_threshold=1.0, dispersal_mass_threshold=0.8, energy_percentile_threshold=0.5, tau_f=0.5, alpha_0_herb=1e-07, alpha_0_pred=0.01, b_herb=0.7, b_pred=0.05, M_herb_ref=1.0, h_herb_0=0.7, M_pred_ref=1.0, sigma_opt_pred_prey=0.7, theta_opt_min_f=0.01, theta_opt_f=0.1, sigma_opt_f=0.02, N_sigma_opt_pred_prey=3.0, h_pred_0=0.5, m_tol=1.6, c_tol=6.61, m_tsm=1.53, c_tsm=1.51, placeholder_annual_mean_temp=20.0, placeholder_annual_temp_sd=5.0, M_disp_ref=1.0, V_disp=0.0278, o_disp=0.48, beta_responsive_bodymass=0.8, semelparity_mass_loss=0.5, u_bg=0.001, lambda_se=0.003, lambda_max=1.0, J_st=0.6, zeta_st=0.05, metamorph_mortality=0.1, carbon_excreta_proportion=0.9, nitrogen_excreta_proportion=0.1, decay_rate_excrement=0.25, scavenging_rate_excrement=0.25, decay_rate_carcasses=0.0625, scavenging_rate_carcasses=0.25, migration_mortality=0.1, aquatic_mortality=0.1, aquatic_residence_time=60.0, migration_residence_time=60.0, seasonal_migration_probability=0.083, territory_size_terms={<MetabolicType.ENDOTHERMIC: 'endothermic'>: {<TaxaType.MAMMAL: 'mammal'>: (-6.09, 1.13), <TaxaType.BIRD: 'bird'>: (-6.09, 1.13)}, <MetabolicType.ECTOTHERMIC: 'ectothermic'>: {<TaxaType.INVERTEBRATE: 'invertebrate'>: (-6.09, 1.13), <TaxaType.AMPHIBIAN: 'amphibian'>: (-6.09, 1.13), <TaxaType.REPTILE: 'reptile'>: (-6.09, 1.13)}}), cohort_data_export: ~virtual_ecosystem.models.animal.model_config.AnimalExportConfig = <factory>, resource_pool_export: ~virtual_ecosystem.models.animal.model_config.ResourcePoolExportConfig = <factory>)

Root configuration class for the animal model.

Attributes:

constants	The constants class for the animal model.
functional_group_definitions_path	A file path to a data file of animal functional group definitions

constants: AnimalConstants

The constants class for the animal model.

functional_group_definitions_path: Annotated[Path, PathType(path_type=file), FieldInfo(annotation=NoneType, required=False, default=PosixPath('<FILEPATH_PLACEHOLDER>')), BeforeValidator(func=placeholder_validator, json_schema_input_type=PydanticUndefined)]

A file path to a data file of animal functional group definitions

static: bool

The model static mode setting.

class virtual_ecosystem.models.animal.model_config.AnimalConstants(*, density_scaling_method: ~typing.Literal['damuth', 'madingley'] = 'madingley', total_heterotroph_biomass_density_kg_m2: float = 0.151, damuths_law_terms: dict[~virtual_ecosystem.models.animal.animal_traits.TaxaType, dict[~typing.Annotated[~virtual_ecosystem.models.animal.animal_traits.DietType, ~pydantic.functional_serializers.PlainSerializer(func=~virtual_ecosystem.models.animal.model_config.serialise_diet_type, return_type=PydanticUndefined, when_used=always), ~pydantic.functional_validators.PlainValidator(func=~virtual_ecosystem.models.animal.model_config.deserialise_diet_type, json_schema_input_type=~typing.Any)], tuple[float, float]]] = <factory>, madingley_biomass_scaling_terms: tuple[float, float] = (0.6, 300000.0), metabolic_scaling_coefficients: tuple[float, float] = (0.037, 0.69), metabolic_rate_terms: dict[~virtual_ecosystem.models.animal.animal_traits.MetabolicType, dict[str, tuple[float, float]]] = <factory>, energy_density: dict[str, float] = <factory>, conversion_efficiency: dict[~typing.Annotated[~virtual_ecosystem.models.animal.animal_traits.DietType, ~pydantic.functional_serializers.PlainSerializer(func=~virtual_ecosystem.models.animal.model_config.serialise_diet_type, return_type=PydanticUndefined, when_used=always), ~pydantic.functional_validators.PlainValidator(func=~virtual_ecosystem.models.animal.model_config.deserialise_diet_type, json_schema_input_type=~typing.Any)], float] = <factory>, mechanical_efficiency: dict[~typing.Annotated[~virtual_ecosystem.models.animal.animal_traits.DietType, ~pydantic.functional_serializers.PlainSerializer(func=~virtual_ecosystem.models.animal.model_config.serialise_diet_type, return_type=PydanticUndefined, when_used=always), ~pydantic.functional_validators.PlainValidator(func=~virtual_ecosystem.models.animal.model_config.deserialise_diet_type, json_schema_input_type=~typing.Any)], float] = <factory>, prey_mass_scaling_terms: dict[~virtual_ecosystem.models.animal.animal_traits.MetabolicType, dict[~virtual_ecosystem.models.animal.animal_traits.TaxaType, tuple[float, float]]] = <factory>, cnp_proportion_terms: dict[~virtual_ecosystem.models.animal.animal_traits.TaxaType, dict[str, float]] = <factory>, birth_mass_threshold: float = 1.5, flow_to_reproductive_mass_threshold: float = 1.0, dispersal_mass_threshold: float = 0.8, energy_percentile_threshold: float = 0.5, tau_f: float = 0.5, alpha_0_herb: float = 1e-07, alpha_0_pred: float = 0.01, b_herb: float = 0.7, b_pred: float = 0.05, M_herb_ref: float = 1.0, h_herb_0: float = 0.7, M_pred_ref: float = 1.0, sigma_opt_pred_prey: float = 0.7, theta_opt_min_f: float = 0.01, theta_opt_f: float = 0.1, sigma_opt_f: float = 0.02, N_sigma_opt_pred_prey: float = 3.0, h_pred_0: float = 0.5, m_tol: float = 1.6, c_tol: float = 6.61, m_tsm: float = 1.53, c_tsm: float = 1.51, placeholder_annual_mean_temp: float = 20.0, placeholder_annual_temp_sd: float = 5.0, M_disp_ref: float = 1.0, V_disp: float = 0.0278, o_disp: float = 0.48, beta_responsive_bodymass: float = 0.8, semelparity_mass_loss: float = 0.5, u_bg: float = 0.001, lambda_se: float = 0.003, lambda_max: float = 1.0, J_st: float = 0.6, zeta_st: float = 0.05, metamorph_mortality: float = 0.1, carbon_excreta_proportion: float = 0.9, nitrogen_excreta_proportion: float = 0.1, decay_rate_excrement: float = 0.25, scavenging_rate_excrement: float = 0.25, decay_rate_carcasses: float = 0.0625, scavenging_rate_carcasses: float = 0.25, migration_mortality: float = 0.1, aquatic_mortality: float = 0.1, aquatic_residence_time: float = 60.0, migration_residence_time: float = 60.0, seasonal_migration_probability: float = 0.083, territory_size_terms: dict[~virtual_ecosystem.models.animal.animal_traits.MetabolicType, dict[~virtual_ecosystem.models.animal.animal_traits.TaxaType, tuple[float, float]]] = <factory>)

Dataclass to store all constants related to animals.

TODO: Remove unused constants.

Attributes:

J_st	Determines the inflection point of the logistic function describing ratio of the realised mortality rate to the maximum rate.
M_disp_ref	The reference mass for calculating diffusive juvenile dispersal in grams.
M_herb_ref	Reference mass for herbivore handling time.
M_pred_ref	The reference value for predator mass.
N_sigma_opt_pred_prey	The standard deviations of the realized attack rates around the optimal predator-prey body mass ratio for which to calculate predator specific cumulative prey densities.
V_disp	Diffusive dispersal speed on an individual of body-mass equal to M_disp_ref in km/month.
alpha_0_herb	Effective rate per unit mass at which a herbivore searches its environment.
alpha_0_pred	Effective rate per unit mass at which a predator searches its environment.
aquatic_mortality	Proportion of mortality that occurs on return from aquatic status [unitless].
aquatic_residence_time	Amount of time a new cohort spends living in aquatic environment [days].
b_herb	Herbivore exponent of the power-law function relating the handling time of autotroph matter to herbivore mass.
b_pred	Carnivore exponent of the power-law relationship between the handling time of prey and the ratio of prey to predator body mass.
beta_responsive_bodymass	Ratio of current body-mass to adult body-mass at which starvation-response dispersal is attempted.
birth_mass_threshold	Mass threshold for reproduction
c_tol	Intercept of the relationship between monthly temperature variability and the upper critical temperature limit relative to annual mean temperature, for terrestrial ectothermic functional groups.
c_tsm	Intercept of the relationship between monthly temperature variability and the optimal temperature relative to annual mean temperature, for terrestrial ectothermic functional groups.
carbon_excreta_proportion	The proportion of metabolic wastes that are carbonaceous.
cnp_proportion_terms	Stoichiometric proportions structured by taxon type.
conversion_efficiency	Conversion efficiencies by broad diet categories.
damuths_law_terms	Damuth Law terms, structured by taxonomic type and broad diet category.
decay_rate_carcasses	Rate at which carcasses decay due to microbial activity [day^-1].
decay_rate_excrement	Rate at which excrement decays due to microbial activity [day^-1].
density_scaling_method	The density scaling method to use within a simulation.
dispersal_mass_threshold	Mass threshold for dispersal.
energy_density	Energy densities of different food sources [J/g]
energy_percentile_threshold	Energy threshold for initiating migration.
flow_to_reproductive_mass_threshold	Threshold of trophic flow to reproductive mass.
h_herb_0	Time that it would take a herbivore of body mass equal to the reference mass, to handle one gram of autotroph biomass
h_pred_0	Time that it would take a predator of body mass equal to the reference mass, to handle a prey individual of body mass equal to one gram.
lambda_max	The maximum possible instantaneous fractional starvation mortality rate.
lambda_se	The instantaneous rate of senescence mortality at the point of maturity.
m_tol	Slope of the relationship between monthly temperature variability and the upper critical temperature limit relative to annual mean temperature, for terrestrial ectothermic functional groups.
m_tsm	Slope of the relationship between monthly temperature variability and the optimal temperature relative to annual mean temperature, for terrestrial ectothermic functional groups.
madingley_biomass_scaling_terms	Biomass scaling terms from the Madingley model.
mechanical_efficiency	Mechanical efficiencies by broad diet categories.
metabolic_rate_terms	Parameters from Madingley, mass-based metabolic rates
metabolic_scaling_coefficients	Metabolic rate scaling coefficients.
metamorph_mortality	The mortality proportion inflicted on a larval cohort undergoing metamorphosis.
migration_mortality	Proportion of mortality that occurs on return from a migration [unitless].
migration_residence_time	Amount of time a migrated cohort spends away [days].
nitrogen_excreta_proportion	The proportion of metabolic wastes that are nitrogenous.
o_disp	Power law exponent for the scaling relationship between body-mass and dispersal distance as mediated by a reference mass, M_disp_ref.
placeholder_annual_mean_temp	Annual mean temperature used as a toy stand-in for $T_{Annual}^C$ [°C].
placeholder_annual_temp_sd	Standard deviation of monthly temperatures across the climatological year, used as a toy stand-in for $sigma_{T_{Annual}^C}$ [°C].
prey_mass_scaling_terms	Prey mass scaling terms by metabolic type.
scavenging_rate_carcasses	Rate at which carcasses are scavenged by animals [day^-1].
scavenging_rate_excrement	Rate at which excrement is scavenged by animals [day^-1].
seasonal_migration_probability	The probability a seasonal migration event occurs per time step (month).
semelparity_mass_loss	The proportion of non-reproductive mass lost in semelparous reproduction.
sigma_opt_f	The standard deviation of optimal predator-prey mass ratios among cohorts.
sigma_opt_pred_prey	Standard deviation of the normal distribution describing realized attack rates around the optimal predator-prey body mass ratio.
tau_f	Proportion of time for which functional group is active.
territory_size_terms	Territory size scaling terms (intercept, exponent) by metabolic and taxa type.
theta_opt_f	The mean optimal prey-predator body mass ratio, from which actual cohort optima are drawn.
theta_opt_min_f	The minimum optimal prey-predator body mass ratio.
total_heterotroph_biomass_density_kg_m2	Total heterotroph biomass density in the system, used for normalizing density.
u_bg	The constant background mortality faced by all animal.
zeta_st	The scaling parameter of the logistic function describing the ratio of the realised starvation mortality rate to the maximum starvation mortality rate.

Methods:

get_population_density_terms(taxa, diet)	Return scaling terms for the specified density scaling method.
model_post_init(context, /)	This function is meant to behave like a BaseModel method to initialize private attributes.

J_st: float

Determines the inflection point of the logistic function describing ratio of the realised mortality rate to the maximum rate.

M_disp_ref: float

The reference mass for calculating diffusive juvenile dispersal in grams.

M_herb_ref: float

Reference mass for herbivore handling time.

M_pred_ref: float

The reference value for predator mass.

N_sigma_opt_pred_prey: float

The standard deviations of the realized attack rates around the optimal predator-prey body mass ratio for which to calculate predator specific cumulative prey densities.

V_disp: float

Diffusive dispersal speed on an individual of body-mass equal to M_disp_ref in km/month.

alpha_0_herb: float

Effective rate per unit mass at which a herbivore searches its environment.

alpha_0_pred: float

Effective rate per unit mass at which a predator searches its environment.

aquatic_mortality: float

Proportion of mortality that occurs on return from aquatic status [unitless].

aquatic_residence_time: float

Amount of time a new cohort spends living in aquatic environment [days].

b_herb: float

Herbivore exponent of the power-law function relating the handling time of autotroph matter to herbivore mass.

b_pred: float

Carnivore exponent of the power-law relationship between the handling time of prey and the ratio of prey to predator body mass.

beta_responsive_bodymass: float

Ratio of current body-mass to adult body-mass at which starvation-response dispersal is attempted.

birth_mass_threshold: float

Mass threshold for reproduction

c_tol: float

Intercept of the relationship between monthly temperature variability and the upper critical temperature limit relative to annual mean temperature, for terrestrial ectothermic functional groups.

c_tsm: float

Intercept of the relationship between monthly temperature variability and the optimal temperature relative to annual mean temperature, for terrestrial ectothermic functional groups.

carbon_excreta_proportion: float

The proportion of metabolic wastes that are carbonaceous. This is a temporary fix to facilitate building the machinery and will be updated with stoichiometry.

cnp_proportion_terms: dict[TaxaType, dict[str, float]]

Stoichiometric proportions structured by taxon type.

conversion_efficiency: dict[Annotated[DietType, PlainSerializer(func=serialise_diet_type, return_type=PydanticUndefined, when_used=always), PlainValidator(func=deserialise_diet_type, json_schema_input_type=Any)], float]

Conversion efficiencies by broad diet categories.

damuths_law_terms: dict[TaxaType, dict[Annotated[DietType, PlainSerializer(func=serialise_diet_type, return_type=PydanticUndefined, when_used=always), PlainValidator(func=deserialise_diet_type, json_schema_input_type=Any)], tuple[float, float]]]

Damuth Law terms, structured by taxonomic type and broad diet category.

decay_rate_carcasses: float

Rate at which carcasses decay due to microbial activity [day^-1].

In reality this should not be constant, but as a simplifying assumption it is.

decay_rate_excrement: float

Rate at which excrement decays due to microbial activity [day^-1].

In reality this should not be constant, but as a simplifying assumption it is.

density_scaling_method: Literal['damuth', 'madingley']

The density scaling method to use within a simulation.

dispersal_mass_threshold: float

Mass threshold for dispersal.

energy_density: dict[str, float]

Energy densities of different food sources [J/g]

energy_percentile_threshold: float

Energy threshold for initiating migration.

flow_to_reproductive_mass_threshold: float

Threshold of trophic flow to reproductive mass.

get_population_density_terms(taxa: TaxaType, diet: DietType) → tuple[float, ...]

Return scaling terms for the specified density scaling method.

Parameters:

• taxa – The TaxaType of the functional group (used for damuth).

• diet – The DietType of the functional group (used for damuth).

Returns:

A tuple (exponent, scalar) for the scaling law.

h_herb_0: float

Time that it would take a herbivore of body mass equal to the reference mass, to handle one gram of autotroph biomass

h_pred_0: float

Time that it would take a predator of body mass equal to the reference mass, to handle a prey individual of body mass equal to one gram.

lambda_max: float

The maximum possible instantaneous fractional starvation mortality rate.

lambda_se: float

The instantaneous rate of senescence mortality at the point of maturity.

m_tol: float

Slope of the relationship between monthly temperature variability and the upper critical temperature limit relative to annual mean temperature, for terrestrial ectothermic functional groups.

m_tsm: float

Slope of the relationship between monthly temperature variability and the optimal temperature relative to annual mean temperature, for terrestrial ectothermic functional groups.

madingley_biomass_scaling_terms: tuple[float, float]

Biomass scaling terms from the Madingley model.

mechanical_efficiency: dict[Annotated[DietType, PlainSerializer(func=serialise_diet_type, return_type=PydanticUndefined, when_used=always), PlainValidator(func=deserialise_diet_type, json_schema_input_type=Any)], float]

Mechanical efficiencies by broad diet categories.

metabolic_rate_terms: dict[MetabolicType, dict[str, tuple[float, float]]]

Parameters from Madingley, mass-based metabolic rates

metabolic_scaling_coefficients: tuple[float, float]

Metabolic rate scaling coefficients.

These are the coefficients of Madingley style scaling of metabolic rate with mass and temperature, assuming a power-law relationship with mass and an exponential relationship with temperature. The three values are:

• \(E_s\) - energy to mass conversion constant (g/kJ)

• \(E_a\) - aggregate activation energy of metabolic reactions

metamorph_mortality: float

The mortality proportion inflicted on a larval cohort undergoing metamorphosis.

migration_mortality: float

Proportion of mortality that occurs on return from a migration [unitless].

migration_residence_time: float

Amount of time a migrated cohort spends away [days].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

• self – The BaseModel instance.

• context – The context.

nitrogen_excreta_proportion: float

The proportion of metabolic wastes that are nitrogenous. This is a temporary fix to facilitate building the machinery and will be updated with stoichiometry.

o_disp: float

Power law exponent for the scaling relationship between body-mass and dispersal distance as mediated by a reference mass, M_disp_ref.

placeholder_annual_mean_temp: float

Annual mean temperature used as a toy stand-in for $T_{Annual}^C$ [°C]. Replace once abiotic model exposes this.

placeholder_annual_temp_sd: float

Standard deviation of monthly temperatures across the climatological year, used as a toy stand-in for $sigma_{T_{Annual}^C}$ [°C]. Replace once abiotic model exposes this.

prey_mass_scaling_terms: dict[MetabolicType, dict[TaxaType, tuple[float, float]]]

Prey mass scaling terms by metabolic type.

scavenging_rate_carcasses: float

Rate at which carcasses are scavenged by animals [day^-1].

Used along with AnimalConstants.decay_rate_carcasses to calculate the split of carcass biomass between scavengable carcass biomass and flow into the soil. In reality this should be a constant, but as a simplifying assumption it is.

scavenging_rate_excrement: float

Rate at which excrement is scavenged by animals [day^-1].

Used along with AnimalConstants.decay_rate_excrement to calculate the split of excrement between scavengable excrement and flow into the soil. In reality this should be a constant, but as a simplifying assumption it is.

seasonal_migration_probability: float

The probability a seasonal migration event occurs per time step (month).

semelparity_mass_loss: float

The proportion of non-reproductive mass lost in semelparous reproduction.

sigma_opt_f: float

The standard deviation of optimal predator-prey mass ratios among cohorts.

sigma_opt_pred_prey: float

Standard deviation of the normal distribution describing realized attack rates around the optimal predator-prey body mass ratio.

tau_f: float

Proportion of time for which functional group is active.

territory_size_terms: dict[MetabolicType, dict[TaxaType, tuple[float, float]]]

Territory size scaling terms (intercept, exponent) by metabolic and taxa type.

Tuple entries are (intercept, exponent) for the log-log relationship:

ln(territory_ha) = intercept + exponent * ln(BM_g)

All entries currently use the Ofstad et al. (2016) closed-habitat ungulate parameters as a placeholder. The data team should replace these with taxon-specific fits as they become available.

Reference:

Ofstad EG et al. 2016 Proc. R. Soc. B 283: 20161234. https://doi.org/10.1098/rspb.2016.1234

theta_opt_f: float

The mean optimal prey-predator body mass ratio, from which actual cohort optima are drawn.

theta_opt_min_f: float

The minimum optimal prey-predator body mass ratio.

total_heterotroph_biomass_density_kg_m2: float

Total heterotroph biomass density in the system, used for normalizing density.

u_bg: float

The constant background mortality faced by all animal.

zeta_st: float

The scaling parameter of the logistic function describing the ratio of the realised starvation mortality rate to the maximum starvation mortality rate.

class virtual_ecosystem.models.animal.model_config.AnimalExportConfig(*, enabled: bool = False, cohort_attributes: tuple[str, ...] = (), float_format: str = '%0.5f')

Configuration for animal cohort data export.

This lightweight configuration is intended to be embedded inside AnimalConfiguration and mirrors the pattern used for the plants exporter configuration.

Variables:

• enabled (bool) – Whether animal cohort export is active.

• cohort_attributes (tuple[str, ...]) – Optional subset of cohort attributes to export. If empty, all available attributes are written.

• float_format (str) – Float format string used when writing numeric data.

virtual_ecosystem.models.animal.model_config.DietTypeSer(*args, **kwargs)

Custom data type to serialise and deserialise DietType Flag values.

alias of Annotated[DietType, PlainSerializer(func=serialise_diet_type, return_type=PydanticUndefined, when_used=always), PlainValidator(func=deserialise_diet_type, json_schema_input_type=Any)]

class virtual_ecosystem.models.animal.model_config.ResourcePoolExportConfig(*, enabled: bool = False, float_format: str = '%0.5f')

Configuration for resource pool data export.

Variables:

• enabled (bool) – Whether resource pool export is active.

• float_format (str) – Float format string used when writing numeric data.

virtual_ecosystem.models.animal.model_config.deserialise_diet_type(diet: str) → DietType

Deserialise string diet terms to DietType.

For standard Enum types, pydantic correctly serialises and deserialise a string representation, but DietType is a Flag, which has underlying numeric values. If these are seriliased and deserialised as with an Enum, then users would need to use numeric diet codes in the configuration.

This function takes a string such as “CARNIVORE” or “FRUIT|SEEDS” and returns the appropriate DietType.

virtual_ecosystem.models.animal.model_config.serialise_diet_type(diet: DietType) → str

Serialise DietType Flag value to string.

This shim simply exports the DietType._name_ attribute, which is a string representation of the Flag value.