Merge pull request #593 from ImperialCollegeLondon/513-litter-model-d…

…ocumentation

Litter model theory and implementation docs

docs/source/_toc.yaml

@@ -12,8 +12,14 @@ subtrees:
               - file: virtual_ecosystem/theory/microclimate_theory
               - file: virtual_ecosystem/theory/hydrology_theory
           - file: virtual_ecosystem/theory/plant_theory
-          - file: virtual_ecosystem/theory/soil_theory
-          - file: virtual_ecosystem/theory/animal_theory
+          - file: virtual_ecosystem/theory/soil/summary
+            entries:
+              - file: virtual_ecosystem/theory/soil/soil_theory
+              - file: virtual_ecosystem/theory/soil/litter_theory
+              - file: virtual_ecosystem/theory/soil/environmental_links
+          - file: virtual_ecosystem/theory/animals/animal_theory
+            entries:
+              - file: virtual_ecosystem/theory/animals/carcasses_and_excrement
       - file: virtual_ecosystem/implementation/implementation
         title: Implementation
         entries:

docs/source/using_the_ve/example_data.md

@@ -273,7 +273,7 @@ The `example_soil_data.nc` file provides:
 This code creates a set of plausible values for which the
 {mod}`~virtual_ecosystem.models.soil.soil_model` absolutely has to function sensibly
 for. Descriptions of the soil pools can be found
-[here](../virtual_ecosystem/theory/soil_theory.md).
+[here](../virtual_ecosystem/theory/soil/summary.md).
 
 ````{admonition} soil_example_data.py
 :class: dropdown
@@ -324,9 +324,10 @@ The `example_litter_data.nc` file provides:
   - XY
 ```
 
-The generation script creates a set of plausible values for which the {mod}`~virtual_ecosystem.models.litter.litter_model`
-absolutely has to function sensibly for.
-Descriptions of the litter pools can be found [here](../virtual_ecosystem/theory/soil_theory.md).
+The generation script creates a set of plausible values for which the
+{mod}`~virtual_ecosystem.models.litter.litter_model` absolutely has to function sensibly
+for. Descriptions of the litter pools can be found
+[here](../virtual_ecosystem/theory/soil/litter_theory.md).
 
 ````{admonition} litter_example_data.py
 :class: dropdown

docs/source/virtual_ecosystem/implementation/litter_implementation.md

@@ -24,3 +24,109 @@ language_info:
 ---
 
 # The Litter Model implementation
+
+## Model overview
+
+The litter model uses the following sequence:
+
+1. The amount of litter consumed by animals is subtracted from the relevant pools and
+   diverted into animal digestion processes.
+
+2. Decay rates are calculated for the remaining litter in the pools. These rates vary
+   based on environmental conditions (see the [environmental factors
+   submodule](virtual_ecosystem.models.litter.env_factors)) and the lignin proportion of
+   each pool. The decay rates across pools are calculated using the
+   [calculate_decay_rates
+   function](virtual_ecosystem.models.litter.carbon.calculate_decay_rates).
+
+3. Plant inputs are considered from two sources, which have different stoichiometric
+   properties.
+
+    * Inputs from tissue senescence and turnover directly from plant communities
+      typically have reduced nutrient concentrations through translocation.
+
+    * Plant inputs generated during herbivory, where animals drop unconsumed biomass,
+      are not depleted in nutrients and herbivores may be actively selecting plant
+      matter rich in limiting nutrients.
+
+    The [LitterInputs class](virtual_ecosystem.models.litter.inputs.LitterInputs)
+    therefore handles multiple different tissue types and pathways to keep information
+    on the total input mass and chemistry of these different input routes, along with
+    flows into the different litter pools.
+
+4. Given the litter loss to consumption and decay and the new inputs, updated litter
+   pool sizes are calculated using the [calculate_updated_pools
+   function](virtual_ecosystem.models.litter.carbon.calculate_updated_pools).
+
+5. The chemistry of these new pools is then found using the
+   [calculate_new_pool_chemistries
+   method](virtual_ecosystem.models.litter.chemistry.LitterChemistry.calculate_new_pool_chemistries)
+   of the [LitterChemistry
+   class](virtual_ecosystem.models.litter.chemistry.LitterChemistry).
+
+6. The mineralisation rates at which nutrients enter the soil are then found. We track
+   carbon (using the [calculate_total_C_mineralised
+   function](virtual_ecosystem.models.litter.carbon.calculate_total_C_mineralised)) and
+   also nitrogen and phosphorus (using `LitterChemistry` class methods).
+
+:::{admonition} Future directions 🔭
+
+However, there is an issue with this approach in that it gives animals preferential
+access to litter over microbes (which drive the decay processes). This is something we
+may have to address in future, potentially by only making a limited portion of the
+litter available for animal consumption.
+
+:::
+
+## Model variables
+
+## Initialisation and update
+
+The tables below show the variables that are required to initialise the litter model and
+then update it at each time step.
+
+```{code-cell} ipython3
+---
+mystnb:
+  markdown_format: myst
+tags: [remove-input]
+---
+from IPython.display import display_markdown
+from var_generator import generate_variable_table
+
+display_markdown(
+    generate_variable_table(
+        "LitterModel", ["vars_required_for_init", "vars_required_for_update"]
+    ),
+    raw=True,
+)
+```
+
+## Generated variables
+
+The first update of the litter model adds the following variables to the data
+environment of the Virtual Ecosystem:
+
+```{code-cell} ipython3
+---
+mystnb:
+  markdown_format: myst
+tags: [remove-input]
+---
+display_markdown(
+    generate_variable_table("LitterModel", ["vars_populated_by_first_update"]), raw=True
+)
+```
+
+## Updated variables
+
+At each model step, the following variables are then updated.
+
+```{code-cell} ipython3
+---
+mystnb:
+  markdown_format: myst
+tags: [remove-input]
+---
+display_markdown(generate_variable_table("LitterModel", ["vars_updated"]), raw=True)
+```

docs/source/virtual_ecosystem/implementation/science_model_overview.md

@@ -209,7 +209,7 @@ occluded phosphorus which is irrecoverably bound within a mineral structure.
 ### Further details
 
 Further theoretical background for the Soil Model can be found
-[here](../theory/soil_theory.md).
+[here](../theory/soil/summary.md).
 
 ## Animal Model
 

docs/source/virtual_ecosystem/theory/animal_theory.md → docs/source/virtual_ecosystem/theory/animals/animal_theory.md

@@ -24,3 +24,14 @@ language_info:
 ---
 
 # Theory of the animals
+
+:::{admonition} In progress 🛠️
+
+This is a high level landing page from animal theory, that will be filled out at a later
+date.
+
+:::
+
+Both animal carcasses and excrement are important resources for animals to scavenge
+from, as such their decay is tracked as part of the animal model. How they are tracked
+is explained [here](./carcasses_and_excrement.md).

docs/source/virtual_ecosystem/theory/animals/carcasses_and_excrement.md

@@ -0,0 +1,61 @@
+---
+jupytext:
+  formats: md:myst
+  main_language: python
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.16.4
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+language_info:
+  codemirror_mode:
+    name: ipython
+    version: 3
+  file_extension: .py
+  mimetype: text/x-python
+  name: python
+  nbconvert_exporter: python
+  pygments_lexer: ipython3
+  version: 3.11.9
+---
+
+# Carcasses and excrement
+
+Carcasses and excrement are critical components of litter, soil and animal models but
+the fastest processes using these resources are carrion feeding and coprophagy by
+animals. If carcasses and excrement are handled within the soil or litter model, new
+inputs would only become available to animals at the end of each model update step. To
+avoid the resulting lags in feeding responses to new carcass and excrement inputs, these
+resources pools are handled within the animal model.
+
+Each grid cell contains two pools recording carcass and excrement mass along with the
+nitrogen and phosphorus stoichiometry of each resource. The total mass in each pool is
+divided into two fractions:
+
+* _scavengable_ mass that can be consumed by animals, and
+* _decayed_ mass that will be added to the soil model at the next time step.
+
+When biomass is added to either pool, the relative allocation to the scavengable
+fraction is determined by the following equation
+
+$$f_c = d / (s + d),$$
+
+where $d$ is the rate at which the resource decays due to microbial activity and $s$ is
+the rate at which animals discover and remove the resource.
+
+:::{admonition} Future directions 🔭
+
+* We currently only have one class of carcasses, but this may well be split into
+  separate size classes at some point in the future.
+
+* Both rates $d$ and $s$ are currently empirically derived constants. Scavenging rate
+  ($s$) could be determined dynamically from the animal model but this would introduce
+  parameterisation complexities that we don't want to tackle at present. Future
+  extensions could allow the microbial decay rate ($d$) to vary environmentally (e.g.
+  with temperature).
+
+:::

docs/source/virtual_ecosystem/theory/soil/environmental_links.md

@@ -0,0 +1,82 @@
+---
+jupytext:
+  formats: md:myst
+  main_language: python
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.16.4
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+language_info:
+  codemirror_mode:
+    name: ipython
+    version: 3
+  file_extension: .py
+  mimetype: text/x-python
+  name: python
+  nbconvert_exporter: python
+  pygments_lexer: ipython3
+  version: 3.11.9
+---
+
+# Environmental impacts on soil processes
+
+Litter decay and soil nutrient transformations are both affected by temperature. As the
+soil model explicitly includes microbes, temperature effects many different processes in
+the model, e.g. enzymatic rates and the carbon use efficiency of microbial growth.
+Temperature is more straightforward in the litter model and just effects the decay rate
+of each litter pool. Processes that take place underground are also affected by soil
+moisture. For the soil moisture response, an empirical relationship is used for both
+litter decay and soil organic matter breakdown.
+
+:::{admonition} In progress 🛠️
+
+The representation of soil microbial communities has still not been finalised. Once this
+has happened this section of the documentation will be extended to detail the relevant
+thermal responses.
+
+:::
+
+## Soil moisture response
+
+Breakdown rates for soil organic matter and breakdown rates for the below-ground litter
+pools are both impacted by how wet the soil is. In very dry soils rates are extremely
+slow, this is because microbial movement is restricted so microbes struggle to reach
+the substrate to break it down. As soils get wetter, microbial motility increases
+resulting in faster breakdown rates. However, increasing soil moisture makes it harder
+for oxygen to permeate the soil, so at a certain point breakdown rates begin to
+decrease with increasing soil moisture as oxygen availability has become limiting. The
+"intrinsic" process rates are altered to capture the effect of soil moisture by
+multiplying them with a factor that takes the following form
+
+$$
+A(\psi) = 1 - \left(
+\frac{\log_{10}|\psi| - \log_{10}|\psi_{o}|}
+{\log_{10}|\psi_{h}| - \log_{10}|\psi_{o}|}
+\right)^\alpha,
+$$
+
+where $\psi$ is the soil water potential, $\psi_{o}$ is the "optimal" water potential at
+which substrate breakdown is maximised, $\psi_{h}$ is the water potential at which
+substrate breakdown stops entirely, and $\alpha$ is an empirically determined parameter
+which sets the curvature of the response to changing soil water potential.
+
+## Litter decay temperature response
+
+The decay rates of all classes of litter are effected by temperature. For the
+above-ground pools, this temperature is simply the air temperature just above the soil
+surface. For the below ground pools, the temperature is an average of the temperatures
+for the biologically active soil layers. The "intrinsic" litter decay rates are altered
+to capture the effect of temperature by multiplying them with a factor that takes the
+following form
+
+$$f(T) = \exp{\left(\gamma \frac{T - T_{\mathrm{ref}}}{T + T_{\mathrm{off}}}\right)},$$
+
+where $T$ is the litter temperature, $T_\mathrm{ref}$ is reference temperature used to
+establish "intrinsic" litter decay rates, $T_\mathrm{off}$ is an offset temperature, and
+$\gamma$ is a parameter capturing how responsive litter decay rates are to temperature
+changes.