Array resources implementation

[davidorme]

Description

This PR introduces the animal_model.array_resources module. It provides:

• ArrayResourceDefinition - an information class used to define array resources. This underlies a global list of array resources available for foraging.
• ArrayResource - the actual runtime instance of an array resource, which hooks the definition up to the Data and does setup.
• ResourcePool - arrays can provide more than one pool (e.g. PFTs) so these are generated from ArrayResources and can then be used to generate...
• CellResource - which provides a per-cell class implementing the Resource protocol.

The PR includes a single test that shows the intended workflow.

The basic idea here is unchanged from the plant_resources_v3.py proposal in #1015 - which @TaranRallings and @dalonsoa looked at before. That branch was badly out of date and this new branch and PR cherry pick the best bits and retool it all for current state of develop, notably the rewiring of stochiometry into the CNP element axes in data arrays.

Fixes #1316

Type of change

• New feature (non-breaking change which adds functionality)
• Optimization (back-end change that speeds up the code)
• Bug fix (non-breaking change which fixes an issue)

Key checklist

• Make sure you've run the pre-commit checks: $ pre-commit run -a
• All tests pass: $ poetry run pytest

Further checks

• Code is commented, particularly in hard-to-understand areas
• Tests added that prove fix is effective or that feature works
• Relevant documentation reviewed and updated

[davidorme]

@TaranRallings - this isn't plumbed into the model yet. Could you give it a check over for clarity and that I've understood what you need it to do.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 94.06780% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.95%. Comparing base (177aaaf) to head (b92a703).

Files with missing lines	Patch %	Lines
virtual_ecosystem/models/animal/array_resources.py	92.85%	7 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1318      +/-   ##
===========================================
- Coverage    94.99%   94.95%   -0.04%     
===========================================
  Files           71       71              
  Lines         7366     7431      +65     
===========================================
+ Hits          6997     7056      +59     
- Misses         369      375       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[TaranRallings]

I think this is quite an elegant solution! I like the three part structure, it could make a good template for a later alignment of all the resource pools. I'm happy to move forward with this.

[nickwctan]

Sorry for popping in this PR, so is it safe to assume that now plant (or array) resource is now available based on cell id, vertical occupancy but not yet specific diet type (e.g. seeds/foliage etc)?

Do you think each time there are changes to the codes in the animal module, you can tag me (and Bai)? - not necessary to review but to notify. I know Taran does it now. I do have notifications turned on for the ve repo but sometimes it gets quickly drowned out by other ones. Would be super helpful to me to get the latest update, many thanks!

[dalonsoa]

Now it might be a good time to implement Code Owners, so certain people is automatically tagged in PRs that relate to the files the are Code Owners for. They do not need to approve the PR (although it can be configured to work like that), but made aware of it.

[TaranRallings]

Sorry for popping in this PR, so is it safe to assume that now plant (or array) resource is now available based on cell id, vertical occupancy but not yet specific diet type (e.g. seeds/foliage etc)?

If you got into array_resources.py down to line 185, you will find the two currently implemented plant resources that are available. There is one foliage and one seeds, both ground level.

[davidorme]

The commented out line above is intended to expose all array resources to all cohorts - so as we expand the usage of the array resources to e.g. litter - we don't have to tinker with the diet type filtering here. That does of course mean that forage_cohort then will need to filter array resources internally.

So, I think swapping out plant_resources works right now but ultimately it does need to be handled differently? I guess the issue then is tracking where waste pools go but we could build that into the array resource definition.

[TaranRallings]

How we want to handle that exactly would make for a good in-person chat.

[davidorme]

Agreed!

[dalonsoa]

This looks good to me! I have the feeling I've already revised this PR, but it might have been the original ideal you linked in the description.

[davidorme]

This looks good to me! I have the feeling I've already revised this PR, but it might have been the original ideal you linked in the description.

Yup - we changed the data structure so I cannibalised the old PR that you looked at. Thanks for looking again.

[davidorme]

@TaranRallings - we know there's more to implement, but I think we've agreed this is good to merge down and then work on improvements in subsequent PRs.