Merge pull request #441 from ImperialCollegeLondon/438-revise-the-p-m…

…odel-documentation

Revise the P Model documentation

docs/source/_toc.yml

@@ -6,20 +6,23 @@ subtrees:
   entries: 
   - file: users/pmodel/module_overview.md
     subtrees:
+      - entries:
+        - file: users/pmodel/shared_components/overview.md
+          subtrees:
+            - entries:
+              - file: users/pmodel/shared_components/photosynthetic_environment.md
+              - file: users/pmodel/shared_components/optimal_chi.md
+              - file: users/pmodel/shared_components/quantum_yield.md
+              - file: users/pmodel/shared_components/jmax_limitation.md
+              - file: users/pmodel/shared_components/arrhenius.md
+              - file: users/pmodel/shared_components/soil_moisture.md
+              - file: users/pmodel/shared_components/extreme_values.md
       - entries:
         - file: users/pmodel/pmodel_details/pmodel_overview.md
           subtrees:
             - entries:
               - file: users/pmodel/pmodel_details/worked_examples.md
-              - file: users/pmodel/pmodel_details/photosynthetic_environment.md
-              - file: users/pmodel/pmodel_details/optimal_chi.md
-              - file: users/pmodel/pmodel_details/quantum_yield.md
-              - file: users/pmodel/pmodel_details/jmax_limitation.md
-              - file: users/pmodel/pmodel_details/arrhenius.md
               - file: users/pmodel/pmodel_details/envt_variation_outputs.md
-              - file: users/pmodel/pmodel_details/soil_moisture.md
-              - file: users/pmodel/pmodel_details/extreme_values.md
-              - file: users/pmodel/pmodel_details/rpmodel.md
         - file: users/pmodel/subdaily_details/subdaily_overview.md
           subtrees:
             - entries:

docs/source/index.md

@@ -29,14 +29,18 @@ language_info:
 ```
 
 The `pyrealm` package provides Python implementations of models of plant productivity
-and demography.
+and demography. All of the functionality within the package is built to accept arrays of
+data and uses the {mod}`numpy` package to efficiently calculate values across datasets
+with multiple dimensions, up to analyses of global spatial datasets of long-running time
+series.
 
 # The `pyrealm` package
 
 :::{admonition} Version 2.0.0
-The `pyrealm` package has just been updated to version 2.0.0. There are a quite a few breaking
-changes to the previous version, documented in the [migration guide](users/versions.md)
-to help update existing code. We strongly recommend upgrading to the new version.
+The `pyrealm` package has just been updated to version 2.0.0. There are a quite a few
+breaking changes to the previous version, documented in the [migration
+guide](users/versions.md) to help update existing code. We strongly recommend upgrading
+to the new version.
 :::
 
 The package currently provides the following modules:

docs/source/users/pmodel/module_overview.md

@@ -23,41 +23,32 @@ language_info:
 
 # The P Model module
 
-The {mod}`~pyrealm.pmodel` module implements the P Model and extensions. The main
-components are:
-
-The [P Model](pmodel_details/pmodel_overview)
-: This is an implementation of the standard implementation of the P Model, which  is a
-ecophysiological model of optimal carbon dioxide uptake by plants
-{cite:p}`Prentice:2014bc,Wang:2017go,Stocker:2020dh`.
-
-* An [overview](pmodel_details/pmodel_overview) of the model.
-* Two [worked examples](pmodel_details/worked_examples) of fitting the model.
-* Details of calculations of:
-  * the [photosynthetic_environment](pmodel_details/photosynthetic_environment),
-  * [optimal chi](pmodel_details/optimal_chi) values,
-  * estimation of quantum yield efficiency (pmodel_details/quantum_yield),
-  * estimation of [electron transfer rate limitation](pmodel_details/jmax_limitation),
-    and
-  * the estimation of [gross primary
-    productivity](pmodel_details/envt_variation_outputs.md#productivity-outputs).
-
-* Approaches to the impacts of [soil moisture stress](pmodel_details/soil_moisture).
-* The behaviour of P Model equations with [extreme forcing
-  values](pmodel_details/extreme_values.md).
-
-The [subdaily P Model](subdaily_details/subdaily_overview)
-: This is an extension to the P Model that incorporates acclimation of the
-  photosynthetic pathway to changing environmental conditions {cite}`mengoli:2022a`.
-  This extension allows slow responses to changing conditions and gives better
-  predictions from the P Model at fine temporal resolutions, particularly when the P
-  Model is applied to datasets with subdaily observations.
-
-[Isotopic discrimination](isotopic_discrimination)
-: The process of photosynthesis discriminates between the carbon isotopes occuring in
-  air, leaving characteristic isotopic signatures, which can be estimated.
-
-[C3 / C4 plant competition](c3c4model)
-: The relative advantages of the C3 and C4 pathways differ with environmental conditions
-  and this extension uses the relative advantage to estimates the expected fraction of
-  C4 plants in a community.
+The {mod}`~pyrealm.pmodel` module implements the P Model and extensions. The P Model
+implements an eco-evolutionary optimality (EEO) theory  of plant productivity: that
+plants optimise their behaviour to balance the costs and gains of photosynthesis.
+
+The module provides implementations of the standard and subdaily forms of the P Model.
+Much of the code and theory is shared between these implementations and is described in
+the documentation for the [shared components](./shared_components/overview.md).
+
+The two specific model implementations are then:
+
+* The ['standard' P Model](pmodel_details/pmodel_overview)
+  {cite:p}`Prentice:2014bc,Wang:2017go,Stocker:2020dh`.
+
+* The [subdaily P Model](subdaily_details/subdaily_overview), extends the P Model to
+  incorporate acclimation of photosynthetic pathways to changing environmental
+  conditions {cite}`mengoli:2022a`. This improves the performance of the P Model at fine
+  temporal resolutions, by accounting for lags in the adoption of optimal behaviour.
+
+In addition to the two P Model forms, this module also provides two extensions that
+build on the P Model:
+
+* The process of photosynthesis discriminates between the carbon isotopes occuring in
+  air, leaving characteristic isotopic signatures. The [Isotopic
+  discrimination](isotopic_discrimination) module estimates the isotopic signatures from
+  different P Models.
+
+* The relative advantages of the C3 and C4 photosynthetic pathways differ with
+  environmental conditions. The [C3 / C4 plant competition](c3c4model) model uses the
+  relative advantage to estimate the expected fraction of C4 plants in a community.