New version of the P Model architecture

CHANGES.md

@@ -9,15 +9,59 @@ A new major release is planned but will iterate through release candidates in or
 make functionality available for testing while the new functionality and API changes are
 worked through. The changes below are provisional.
 
+- The `PModel` and `SubdailyPModel` classes have been extensively restructured to align
+  the attributes and methods and to remove repeated code. Many of these changes are
+  internal but the model signatures have changed and several of the attributes have been
+  renamed.
+
+  **Breaking changes**:
+
+  - The `SubdailyPModel` attributes giving actual predicted estimates of $V_{cmax}$ and
+    $J_{max}$ for observations (`subdaily_vcmax`, `subdaily_vcmax25`, `subdaily_jmax`
+    and `subdaily_jmax25`) have been renamed to simply `vcmax`, `vcmax25`, `jmax` and
+    `jmax25` to align with the observation estimates in `PModel`.
+  - The `SubdailyPModel` attributes giving the daily optimum and realised values for
+    $V_{cmax25}$, $J_{max25}$ and $\xi$ have been renamed for more clarity: `vcmax25_opt`,
+    `vcmax25_real`, `jmax25_opt`, `jmax25_real`, `xi_opt` and `xi_real` have changed to
+    `vcmax25_daily_optimal`,  `vcmax25_daily_realised`, `jmax25_daily_optimal`,
+    `jmax25_daily_realised`, `xi_daily_optimal` and `xi_daily_realised`.
+  - The `PModel.estimate_productivity` method was required to pass in FAPAR and PPFD to
+    scale up LUE predictions to GPP and to estimate other predictions. This has been
+    deprecated with addition of FAPAR and PPFD to the `PModelEnvironment` and GPP is now
+    calculated automatically.
+  - The `convert_pmodel_to_subdaily` function has been deprecated in favour of the new
+    `PModel.to_subdaily` method.
+
+- The `PModelEnvironment` class has been updated. It now requires that the user also
+  provides `fapar` and `ppfd` data, currently with no default values. The provision of
+  additional variables has also been made more flexible, allowing users to provide
+  arbitary extra variables to the environment. This makes it easier to adopt new PModel
+  methods implementations with new required variables.
+
+  **Breaking change**: Need to specify `fapar` and `ppfd` in `PModelEnvironment`.
+
+- The `bounds_checker` function has been retired and replaced with the `BoundsChecker`
+  class, which provides more flexible and user-configurable bounds checking. This
+  functionality is used within other classes and does not introduce breaking changes.
+
 - A new system for providing alternative calculations of quantum yield ($\phi_0$) in the
   P Model, using the new `pyrealm.pmodel.quantum_yield` module. This module now provides
   an expandable set of implementations of the quantum yield calculation, and currently
   supports the previous fixed and temperature dependent $\phi_0$ approaches but also
   David Sandoval's extension for estimating the impact of water stress on $\phi_0$.
 
-  **Breaking change** The signatures of the `PModel` and `SubdailyPModel` classes have
-  changed: the arguments `kphio` and `do_ftemp_kphio` have been replaced by
-  `method_kphio` and `reference_kphio`.
+  **Breaking changes**:
+
+  - The signatures of the `PModel` and `SubdailyPModel` classes have
+    changed: the arguments `kphio` and `do_ftemp_kphio` have been replaced by
+    `method_kphio` and `reference_kphio`.
+  - In addition to changing the implementation, the **default values** of $\phi_0$ have
+    changed. In `1.0.0`, the `PModel` followed {cite:t}`Stocker:2020dh` in using default
+    values of either 0.081785 or 0.049977, depending on whether the model applied
+    temperature correction to $\phi_0$. These values were tuned to the particular model
+    setup and the application of a water stress penalty. The `PModel` and
+    `SubdailyPModel` now both default to the theoretical maximum quantum yield of
+    photosynthesis ($\phi_0 = 1/8$).
 
 - The implementation of $J_{max}$ and $V_{cmax}$ limitation has been updated to provide
   a more flexible and expandable system. The changes are mostly internal, but there are
@@ -43,10 +87,30 @@ worked through. The changes below are provisional.
   change between v1 and v2, with the shift from `kattge_knorr` to `simple` as the
   default factors.
 
+- Many of the arguments to `SubdailyPModel` have been brought together into a new
+  `AcclimationModel` class. This replaces `SubdailyScaler` and bundles all of the
+  settings for acclimation into a single class. The following is therefore a **breaking
+  change**:
+
+  - `SubdailyScaler` has been replaced with `AcclimationModel`, and the following
+    arguments to `SubdailyPModel` are now arguments to `AcclimationModel`: `alpha`,
+    `allow_holdover`, `allow_partial_data`, `update_point`, `fill_kind` (as
+    `fill_method`).
+
+- The legacy implementation `SubdailyPModel_JAMES` has been deprecated. This
+  implementation duplicated the original Mengoli et al JAMES code. This was largely a
+  proof of concept implementation, misses some key parts of the acclimation model and
+  the internal calculations are sufficiently different that there is a high maintenance
+  cost to updating it to the new API in version 2.0.0.
+
+  - The `fill_from` argument to `fill_daily_to_subdaily` was only required for
+    `SubdailyPModel_JAMES` and so this has also been deprecated.
+
 - The functions `calc_ftemp_kphio` and `calc_ftemp_inst_vcmax` provided narrow use cases
   with code duplication. They have been replaced by two broader Arrhenius functions:
-  `calculate_simple_arrhenius_factor` and `calculate_kattge_knorr_arrhenius_factor` (see
-  also the point above).
+  `calculate_simple_arrhenius_factor` and `calculate_kattge_knorr_arrhenius_factor` .
+  The functions in {mod}`pyrealm.pmodel.functions` have been updated to take specific
+  arguments rather than just taking `PModelConsts` and `CoreConsts` objects.
 
 - The `pyrealm.core.water` module now provides `convert_water_mm_to_moles`,
   `convert_water_moles_to_mm` and `calculate_water_molar_volume`.

README.md

@@ -79,15 +79,13 @@ from pyrealm.pmodel import PModelEnvironment, PModel
 # Calculate the photosynthetic environment given the conditions
 env = PModelEnvironment(
     tc=np.array([20]), vpd=np.array([1000]),
-    co2=np.array([400]), patm=np.array([101325.0])
+    co2=np.array([400]), patm=np.array([101325.0],
+    fapar=1, ppfd=300)
 )
 
 # Calculate the predictions of the P Model for a C3 plant
 pmodel_c3 = PModel(env)
 
-# Estimate the GPP from the model given the absorbed photosynthetically active light
-pmodel_c3.estimate_productivity(fapar=1, ppfd=300)
-
 # Report the GPP in micrograms of carbon per m2 per second.
 pmodel_c3.gpp
 ```

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/api/pmodel_api.md

@@ -27,14 +27,6 @@ language_info:
 .. automodule:: pyrealm.pmodel
 ```
 
-## The {mod}`~pyrealm.pmodel.pmodel` submodule
-
-```{eval-rst}
-.. automodule:: pyrealm.pmodel.pmodel
-    :autosummary:
-    :members:
-```
-
 ## The {mod}`~pyrealm.pmodel.pmodel_environment` submodule
 
 ```{eval-rst}
@@ -59,6 +51,16 @@ language_info:
 .. automodule:: pyrealm.pmodel.optimal_chi
     :autosummary:
     :members:
+    :inherited-members:
+```
+
+## The {mod}`~pyrealm.pmodel.arrhenius` submodule
+
+```{eval-rst}
+.. automodule:: pyrealm.pmodel.arrhenius
+    :autosummary:
+    :members:
+    :inherited-members:
 ```
 
 ## The {mod}`~pyrealm.pmodel.quantum_yield` submodule
@@ -67,6 +69,7 @@ language_info:
 .. automodule:: pyrealm.pmodel.quantum_yield
     :autosummary:
     :members:
+    :inherited-members:
 ```
 
 ## The {mod}`~pyrealm.pmodel.functions` submodule
@@ -93,19 +96,19 @@ language_info:
     :members:
 ```
 
-## The {mod}`~pyrealm.pmodel.scaler` submodule
+## The {mod}`~pyrealm.pmodel.acclimation` submodule
 
 ```{eval-rst}
-.. automodule:: pyrealm.pmodel.scaler
+.. automodule:: pyrealm.pmodel.acclimation
     :autosummary:
     :members:
-    :private-members:
 ```
 
-## The {mod}`~pyrealm.pmodel.subdaily` submodule
+## The {mod}`~pyrealm.pmodel.pmodel` submodule
 
 ```{eval-rst}
-.. automodule:: pyrealm.pmodel.subdaily
+.. automodule:: pyrealm.pmodel.pmodel
     :autosummary:
     :members:
+    :inherited-members:
 ```

docs/source/conf.py

@@ -9,6 +9,7 @@
 
 import os
 import sys
+import warnings
 from dataclasses import dataclass, field
 from datetime import datetime
 
@@ -21,11 +22,14 @@
 
 from pyrealm import __version__ as pyrealm_version
 
-# +
 sys.path.insert(0, os.path.abspath("../"))
-# -
 
 
+# Suppress the 2.0.0 user warnings in the documentation
+warnings.filterwarnings(
+    "ignore", category=UserWarning, message="Pyrealm 2.0.0 uses a uses default value"
+)
+
 # -- Project information -----------------------------------------------------
 
 project = "pyrealm: Ecosystem Models in Python"
@@ -55,6 +59,7 @@
     "sphinxcontrib.bibtex",
     "myst_nb",
     "sphinx_rtd_theme",
+    "sphinx_design",
     "sphinx_external_toc",
 ]
 
@@ -64,7 +69,6 @@
 
 # + [markdown]
 # Citation styling
-# -
 
 
 def bracket_style() -> BracketStyle:
@@ -156,7 +160,6 @@ class MyReferenceStyle(AuthorYearReferenceStyle):
     ("py:class", "pandas.core.frame.DataFrame"),
 ]
 
-# +
 intersphinx_mapping = {
     "pytest": ("https://docs.pytest.org/en/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
@@ -166,7 +169,6 @@ class MyReferenceStyle(AuthorYearReferenceStyle):
     "shapely": ("https://shapely.readthedocs.io/en/stable/", None),
     "marshmallow": ("https://marshmallow.readthedocs.io/en/stable/", None),
 }
-# -
 
 
 autodoc_default_flags = ["members"]
@@ -213,7 +215,6 @@ class MyReferenceStyle(AuthorYearReferenceStyle):
 # html_theme = 'sphinx_material'
 html_theme = "sphinx_rtd_theme"
 
-# +
 html_theme_options = {
     "logo_only": True,
     "version_selector": True,
@@ -227,7 +228,6 @@ class MyReferenceStyle(AuthorYearReferenceStyle):
     "includehidden": True,
     "titles_only": False,
 }
-# -
 
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/source/index.md

@@ -29,11 +29,21 @@ 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
 
-The package is in active development and currently provides the following modules:
+:::{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 package currently provides the following modules:
 
 The `core` module
 : Contains fundamental utilities and physics functionality shared across the
@@ -57,23 +67,6 @@ The `demography` module
   and respiration {cite:p}`Li:2014bc`. This module is still in active development but a
   lot of initial functionality is present.
 
-## Version 2.0.0 development
-
-New functionality being implemented after version 1.0.0 has lead to some immediate
-breaking changes in the API, for example in the handling of quantum yield settings in
-the class signatures for the `PModel` and `SubdailyPModel`. As the package uses
-[semantic versioning](https://semver.org/), these changes to the API require that new
-releases be made under a new major version.
-
-We will be publishing a series of "release candidates" of the 2.0.0 package. These will
-be used to identify issues with the current API and try to stabilise a new API. The
-content of version 2.0.0 is not yet finalised, so these release candidates may also add
-new functionality.
-
-We recommend that you update to the most recent release candidate of version 2.0.0. The
-documentation now includes a [migration guide](users/versions.md) to help update
-existing code.
-
 ## Indices and tables
 
 * {ref}`genindex`