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.
`deserialise_vertical_occupancy`(occupancy)	Deserialise string vertical occupancy terms to VerticalOccupancy.
`serialise_diet_type`(diet)	Serialise DietType Flag value to string.
`serialise_vertical_occupancy`(occupancy)	Serialise VerticalOccupancy 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-11, alpha_0_pred=1e-06, b_herb=0.7, b_pred=0.7, 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_temp_terms={<VerticalOccupancy.CANOPY: 4>: {'mean_temp': 23.0, 'temp_sd': 1.0}, <VerticalOccupancy.GROUND: 2>: {'mean_temp': 20.0, 'temp_sd': 1.0}, <VerticalOccupancy.SOIL: 1>: {'mean_temp': 16.5, 'temp_sd': 1.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>)[source]#

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-11, alpha_0_pred: float = 1e-06, b_herb: float = 0.7, b_pred: float = 0.7, 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_temp_terms: dict[~typing.Annotated[~virtual_ecosystem.models.animal.animal_traits.VerticalOccupancy, ~pydantic.functional_serializers.PlainSerializer(func=~virtual_ecosystem.models.animal.model_config.serialise_vertical_occupancy, return_type=PydanticUndefined, when_used=always), ~pydantic.functional_validators.PlainValidator(func=~virtual_ecosystem.models.animal.model_config.deserialise_vertical_occupancy, json_schema_input_type=~typing.Any)], dict[str, float]] = <factory>, 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>)[source]#

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 [d] 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 [d] 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_temp_terms`	Placeholder per-stratum annual reference temperature terms for the ectotherm activity window, keyed by vertical occupancy.
`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, ...][source]#

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 [d] 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 [d] 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_temp_terms: dict[Annotated[VerticalOccupancy, PlainSerializer(func=serialise_vertical_occupancy, return_type=PydanticUndefined, when_used=always), PlainValidator(func=deserialise_vertical_occupancy, json_schema_input_type=Any)], dict[str, float]]#

Placeholder per-stratum annual reference temperature terms for the ectotherm activity window, keyed by vertical occupancy.

Each stratum provides two terms in degrees Celsius: mean_temp, the annual mean temperature the functional group is adapted to, and temp_sd, the standard deviation of monthly temperatures across the climatological year. They are consumed by activity_window() to derive a group’s thermal tolerance window (T_opt, T_min_crit, T_max_crit), against which each cohort’s experienced microclimate is compared to set sigma_f_t. For multi-stratum groups the terms are averaged across occupied strata at FunctionalGroup construction.

These are toy placeholders anchored to an observed microclimate and should be replaced once the abiotic model supplies real per-stratum annual statistics. See the inline comment above for the derivation and the reasoning behind the per-stratum offsets.

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')[source]#

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')[source]#

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.VerticalOccupancySer(*args, **kwargs)#

Custom data type to serialise and deserialise VerticalOccupancy Flag values.

alias of Annotated[VerticalOccupancy, PlainSerializer(func=serialise_vertical_occupancy, return_type=PydanticUndefined, when_used=always), PlainValidator(func=deserialise_vertical_occupancy, json_schema_input_type=Any)]

virtual_ecosystem.models.animal.model_config.deserialise_diet_type(diet: str) → DietType[source]#

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.deserialise_vertical_occupancy(occupancy: str) → VerticalOccupancy[source]#

Deserialise string vertical occupancy terms to VerticalOccupancy.

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

This function takes a string such as “SOIL” or “SOIL|GROUND” and returns the appropriate VerticalOccupancy.

virtual_ecosystem.models.animal.model_config.serialise_diet_type(diet: DietType) → str[source]#

Serialise DietType Flag value to string.

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

virtual_ecosystem.models.animal.model_config.serialise_vertical_occupancy(occupancy: VerticalOccupancy) → str[source]#

Serialise VerticalOccupancy Flag value to string.

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

API documentation for the model_config module#

API documentation for the `model_config` module#