Allow animal consumption of soil pools

[jacobcook1995]

Description

This PR adds SoilPool objects which animals can consume from. These follow the basic structure of the LitterPools which are already used for animal consumption of litter. They mainly serve to convert from the quantities used in the soil model into those used by the animal. They also serve to group the pools available for animal consumption into ones that animals could feasibly specialise in eating (i.e. particulate organic matter, bacteria, fungi), rather than allowing them to feed from every single pool as a discrete resource or to feed from nonsensical pools (e.g. soil enzymes)

As part of the PR I've had to modify the animal model code, so feedback on whether the changes seem sensible/in keeping with the overall code style would be useful.

Fixes #904

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

[codecov-commenter]

Codecov Report

❌ Patch coverage is 99.08257% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 94.08%. Comparing base (9b941e2) to head (6989f27).
⚠️ Report is 1679 commits behind head on develop.

Files with missing lines	Patch %	Lines
virtual_ecosystem/models/animal/decay.py	98.30%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #917      +/-   ##
===========================================
+ Coverage    94.00%   94.08%   +0.08%     
===========================================
  Files           78       78              
  Lines         6067     6172     +105     
===========================================
+ Hits          5703     5807     +104     
- Misses         364      365       +1     

☔ 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]

Am I following the logic correctly?

We keep the decay classes, the new one mirrors the litter pool.
I forage from the soil pool objects directly.
The new soil code auto-calculates the loss to animals and feeds that back into your new data variables?

[jacobcook1995]

Am I following the logic correctly?

We keep the decay classes, the new one mirrors the litter pool. I forage from the soil pool objects directly. The new soil code auto-calculates the loss to animals and feeds that back into your new data variables?

Yep exactly! With the idea being that the foraging code does not touch the soil model variables in the data object at all (the possibility for bugs going that route feels limitless)

[dalonsoa]

I've a couple of suggestions here and there, and a few comments, but nothing major. All looks good!

[dalonsoa]

I think I ask this every time I see CNP somewhere. Were not a dataclass to handle this specific data structure consistently across the codebase?

[jacobcook1995]

Yeah that could be useful. It would be somewhat tricky as the representation varies between models.

For the microbial groups, the soil model does not track the stoichiometry explicitly it just assumes that each group has a fixed stoichiometry (which is an input parameter). This is basically to keep the amount of pools that the integration has to track lower (there's a huge number anyway).

I guess it probably does make sense to think about a unified approach to this at some point, but I think it probably has to wait until plant stoichiometry is implemented so that we know what all models require the general system to do

[dalonsoa]

Is there any risk of this ever becoming negative? If so, what should happen?

[jacobcook1995]

There shouldn't be any processes in the animal model that can increase the size of the SoilPool pools. These are designed to just track the consumption within one animal model evaluation step, so there shouldn't be any changes from any other models to the pool within the relevant time frame. So, pom_final_stock can only ever be equal to or smaller than pom_initial_stock

[dalonsoa]

Here we have a collection of subtractions. I guess you are on top of them and it is not possible, but just checking that they cannot lead to negative numbers, ever.

[jacobcook1995]

The changes in pools that are being calculated here can be negative. In terms of preventing the pools from going negative, I haven't been able to think of a reasonable way to stop this from happening. As the animal and soil model run in sequence the total consumption is calculated based on old soil pool sizes and then subtracted from the soil pools at the next simulation step, so if the abundance of the pool suddenly drops the consumption rate won't allowing the pool to potentially go negative.

This happening would be an indication that something is wrong in how animal consumption has been parameterised, but I'm not really sure what makes sense to do in response. Pools that are negative could be replaced with zero values, but I feel like that just masks the problem, as well as breaking stoichiometric conservation (because the animals receive more CNP from the soil than they remove)