API for the array_resources module

This module provides the ArrayResources class and API used to communicate between animal foraging at a grid cell level (using the Resource protocol) and data saved in the main Data object as spatially structured arrays.

The module defines four classes:

• The ArrayResourceDefinition is a simple dataclass that is used to define the array resources that should be created when the model runs. An array resource is a Virtual Ecosystem data array that is structured by at least cell id and element, providing available biomasses of each element (CNP) by cell. We currently support array resources that are further structured by plant functional type (PFT).

• An ArrayResource instance is created a runtime from an ArrayResourceDefinition and the Data object. It creates a new array in the Data object to record consumption from the array resource. It is also used to generate a list of ResourcePools: an ArrayResource has a one to many mapping to resource pools because of structuring by PFT.

• A ResourcePool instance manages consumption from single resource pool. This is an explicitly two dimensional slice through the resource array providing elemental masses by cell id. Each resource pool instance defines a consumed_mass attribute that tracks the total biomass consumed within each cell in the pool. An instance can be indexed to generate cell specific resources using the CellResource class.

  • The reset_resources method is used to refresh the available mass for consumption and reset the consumed mass to zero.

  • The write_consumption method can then be used to write actual consumed masses across cells back to the Data object.

• The CellResource class is used to manage actual consumption at the grid cell level within the simulation. It implements the Resource protocol, providing the cell_id, vertical_occupancy and current_mass attributes and the get_eaten method. The instance also contains a reference to the consumed_mass array in the parent ResourcePool and adds consumed mass to the cell_id specific entry in that array when the get_eaten method is called.

The workflow for the model is:

• The model code provides a globally defined list of ArrayResourceDefinition instances that should be used within the model.

• At runtime, these are converted into a list of ArrayResource instances:

• Those can then be expanded into a flat list of ResourcePools:

• At the start of the model update, the set_resources method must be called each resource pool to populate the available masses with the current values from the Data instance.

• Individual pools can then be used to extract CellResource instances for grid cells that can be used as part of the foraging environment within each cells alongside other resources.

• At the end of a model update step, the write_consumption method should be called for each resource pool to write the consumed masses back to the Data object.

Data:

ARRAY_RESOURCES

Definition of the set of ArrayResources available to the AnimalModel.

Classes:

ArrayResource(definition, data)	Manager class for consumption from array resources.
ArrayResourceDefinition(pool_array, ...[, ...])	Dataclass to define array resources.
CellResource(resource, ...)	A per-cell resource for consumption.
ResourcePool(resource, data, density[, pft])	Interface between spatially structured resource pools and per-cell resources.

virtual_ecosystem.models.animal.array_resources.ARRAY_RESOURCES = [ArrayResourceDefinition(pool_array='subcanopy_vegetation_cnp', consumed_array='subcanopy_vegetation_cnp_consumed', vertical_occupancy=<VerticalOccupancy.GROUND: 2>, diet_type=<DietType.FOLIAGE: 8>, partition_by_pft=False, density=False), ArrayResourceDefinition(pool_array='subcanopy_seedbank_cnp', consumed_array='subcanopy_seedbank_cnp_consumed', vertical_occupancy=<VerticalOccupancy.GROUND: 2>, diet_type=<DietType.SEEDS: 128>, partition_by_pft=False, density=False), ArrayResourceDefinition(pool_array='canopy_foliage_cnp', consumed_array='canopy_foliage_cnp_consumed', vertical_occupancy=<VerticalOccupancy.CANOPY: 4>, diet_type=<DietType.FOLIAGE: 8>, partition_by_pft=True, density=False), ArrayResourceDefinition(pool_array='canopy_seed_cnp', consumed_array='canopy_seed_cnp_consumed', vertical_occupancy=<VerticalOccupancy.CANOPY: 4>, diet_type=<DietType.SEEDS: 128>, partition_by_pft=True, density=False), ArrayResourceDefinition(pool_array='canopy_fruit_cnp', consumed_array='canopy_fruit_cnp_consumed', vertical_occupancy=<VerticalOccupancy.CANOPY: 4>, diet_type=<DietType.FRUIT: 16>, partition_by_pft=True, density=False), ArrayResourceDefinition(pool_array='foliage_turnover_cnp', consumed_array='foliage_turnover_cnp_consumed', vertical_occupancy=<VerticalOccupancy.GROUND: 2>, diet_type=<DietType.FOLIAGE: 8>, partition_by_pft=True, density=False), ArrayResourceDefinition(pool_array='seed_turnover_cnp', consumed_array='seed_turnover_cnp_consumed', vertical_occupancy=<VerticalOccupancy.GROUND: 2>, diet_type=<DietType.SEEDS: 128>, partition_by_pft=True, density=False), ArrayResourceDefinition(pool_array='fruit_turnover_cnp', consumed_array='fruit_turnover_cnp_consumed', vertical_occupancy=<VerticalOccupancy.GROUND: 2>, diet_type=<DietType.FRUIT: 16>, partition_by_pft=True, density=False), ArrayResourceDefinition(pool_array='litter_pool_above_metabolic_cnp', consumed_array='litter_consumed_above_metabolic_cnp', vertical_occupancy=<VerticalOccupancy.GROUND: 2>, diet_type=<DietType.DETRITUS: 2>, partition_by_pft=False, density=True), ArrayResourceDefinition(pool_array='litter_pool_above_structural_cnp', consumed_array='litter_consumed_above_structural_cnp', vertical_occupancy=<VerticalOccupancy.GROUND: 2>, diet_type=<DietType.DETRITUS: 2>, partition_by_pft=False, density=True), ArrayResourceDefinition(pool_array='litter_pool_woody_cnp', consumed_array='litter_consumed_woody_cnp', vertical_occupancy=<VerticalOccupancy.GROUND: 2>, diet_type=<DietType.DETRITUS: 2>, partition_by_pft=False, density=True), ArrayResourceDefinition(pool_array='litter_pool_below_metabolic_cnp', consumed_array='litter_consumed_below_metabolic_cnp', vertical_occupancy=<VerticalOccupancy.SOIL: 1>, diet_type=<DietType.DETRITUS: 2>, partition_by_pft=False, density=True), ArrayResourceDefinition(pool_array='litter_pool_below_structural_cnp', consumed_array='litter_consumed_below_structural_cnp', vertical_occupancy=<VerticalOccupancy.SOIL: 1>, diet_type=<DietType.DETRITUS: 2>, partition_by_pft=False, density=True)]

Definition of the set of ArrayResources available to the AnimalModel.

class virtual_ecosystem.models.animal.array_resources.ArrayResource(definition: ArrayResourceDefinition, data: Data)

Manager class for consumption from array resources.

An ArrayResource instance identifies a single array in the Data object that can provide one or more resource pools for animal consumption. The get_pools method is used to return a list of ResourcePool instances available from the ArrayResource and then those pools can be used to provide per-cell CellResources. The internals of those classes are used to propagate consumption at the cell level back up to recording consumption within the Data object.

Attributes:

consumed_array	The name of an array that will be used to record consumed biomass from the resource pool.
data	The data instance containing array resources.
density	Is the pool being accessed a density (per m^2) rather than a mass.
diet_type	A DietType enum value indicating the dietary availability of the resource to consumers.
partition_by_pft	Should this resource array be partitioned into separate resource pools by PFT.
pool_array	The name of an array in the Data object that will be used as the biomass pool for feeding in this resource.
vertical_occupancy	A VerticalOccupancy enum value indicating the vertical availability of the resource to consumers.

Methods:

get_pools(data)

Return a list of resource pools from an ArrayResource.

consumed_array: str

The name of an array that will be used to record consumed biomass from the resource pool. This will have the same dimensional structure as the pool array.

data: Data

The data instance containing array resources.

density: bool

Is the pool being accessed a density (per m^2) rather than a mass.

diet_type: DietType

A DietType enum value indicating the dietary availability of the resource to consumers.

get_pools(data: Data) → list[ResourcePool]

Return a list of resource pools from an ArrayResource.

A single defined ArrayResource can contain multiple pools - currently only through partitioning by PFT but this could expand - so this method returns a list of the pools defined for the resource.

Parameters:

data – A data object containing resource arrays.

partition_by_pft: bool

Should this resource array be partitioned into separate resource pools by PFT.

pool_array: str

The name of an array in the Data object that will be used as the biomass pool for feeding in this resource.

vertical_occupancy: VerticalOccupancy

A VerticalOccupancy enum value indicating the vertical availability of the resource to consumers.

class virtual_ecosystem.models.animal.array_resources.ArrayResourceDefinition(pool_array: str, consumed_array: str, vertical_occupancy: VerticalOccupancy, diet_type: DietType, partition_by_pft: bool = False, density: bool = False)

Dataclass to define array resources.

Attributes:

consumed_array	The name of an array that will be used to record consumed biomass from the resource pool.
density	Is the input pool density (per m^2) rather than just a mass.
diet_type	A definition of the diet type that can forage from this resource.
partition_by_pft	Is the pool array partitioned along the plant functional type axis.
pool_array	The name of an existing array in the Data object that can be used as an array resource.
vertical_occupancy	A VerticalOccupancy enum value indicating the vertical availability of the resource to consumers.

consumed_array: str

The name of an array that will be used to record consumed biomass from the resource pool. This will have the same dimensional structure as the pool array.

density: bool = False

Is the input pool density (per m^2) rather than just a mass.

diet_type: DietType

A definition of the diet type that can forage from this resource.

partition_by_pft: bool = False

Is the pool array partitioned along the plant functional type axis.

pool_array: str

The name of an existing array in the Data object that can be used as an array resource.

vertical_occupancy: VerticalOccupancy

A VerticalOccupancy enum value indicating the vertical availability of the resource to consumers.

class virtual_ecosystem.models.animal.array_resources.CellResource(resource: ArrayResource, available_elemental_masses: ndarray[tuple[Any, ...], dtype[floating]], consumed_total_mass: ndarray[tuple[Any, ...], dtype[floating]], vertical_occupancy: VerticalOccupancy, cell_id: int)

A per-cell resource for consumption.

This class implements the Resource protocol for the AnimalModel but also provides data collection from individual cell consumption back up to spatially structured pools managed in ResourcePool instances.

Parameters:

• resource – The array resource being targeted by the instance.

• available_elemental_masses – An array of the elemental masses available for consumption.

• vertical_occupancy – A VerticalOccupancy enum value indicating the vertical availability of the resource to consumers.

• cell_id – The cell_id being targeted by this resource.

• consumed_total_mass – A reference to the spatially structured array of consumed total biomass in the parent ResourcePool.

Methods:

get_eaten(consumed_mass, consumer)

The get_eaten method for the PlantResource.

Attributes:

mass_current	The current available mass in the resource.
resource	The array resource being targeted by a CellResource instance.

get_eaten(consumed_mass, consumer)

The get_eaten method for the PlantResource.

property mass_current

The current available mass in the resource.

resource

The array resource being targeted by a CellResource instance.

class virtual_ecosystem.models.animal.array_resources.ResourcePool(resource: ArrayResource, data: Data, density: bool, pft: str | None = None)

Interface between spatially structured resource pools and per-cell resources.

The ResourcePool class is used to coordinate consumption within the AnimalModel from spatially structured biomass pool arrays within the Data object. An instance tracks a two-dimensional slice through a biomass array, that should be structured by cell_id and then elemental masses of Carbon, Nitrogen and Phosphorous.

A cell-specific CellResource object, implementing the Resource protocol, can be obtained by indexing a ResourcePool by cell_id. This CellResource instance will be populated with the available elemental biomasses from the pool available for the specific cell.

The CellResource is also passed a reference to the consumed_total_mass attribute, to allow foraging in different cells to update consumption in a single location. Consumed total mass is used within this class to make it easier to track individual total masses removed by foraging - when the write_consumption method is called, these total masses are partitioned back into individual elemental masses in consumed mass array in the Data object.

Attributes:

consumed_mass	An array of total consumed biomass by cell_id.
elemental_masses	An array of biomasses of individual elements by cell_id.

Methods:

is_forageable(diet, vertical_occupancy)	Utility function to test if a consumer can access the resource pool.
set_resources()	Resets the resource from the data object.
write_consumption()	Write accumulated consumption from the pool back into the data object.

consumed_mass: ndarray[tuple[Any, ...], dtype[floating]]

An array of total consumed biomass by cell_id.

elemental_masses: ndarray[tuple[Any, ...], dtype[floating]]

An array of biomasses of individual elements by cell_id.

is_forageable(diet: DietType, vertical_occupancy: VerticalOccupancy) → bool

Utility function to test if a consumer can access the resource pool.

Parameters:

• diet – The diet type of the potential consumer

• vertical_occupancy – The vertical occupancy of the potential consumer.

Returns:

True if the resource pool is within both the diet and vertical occupancy of the functional group, otherwise False.

set_resources()

Resets the resource from the data object.

This method updates the available elemental masses from the resource and resets the local array tracking consumed total biomass.

write_consumption()

Write accumulated consumption from the pool back into the data object.