Add a migration guide

CHANGES.md

@@ -3,6 +3,42 @@
 This document provides a brief overview of the main changes to `pyrealm` at each of the
 released versions. More detail can be found at the GitHub release page for each version.
 
+## 2.0.0 release candidates
+
+A new major release is planned but will iterate through release candidates in order to
+make functionality available for testing while the new functionality and API changes are
+worked through. The changes below are provisional.
+
+- 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 extentsion 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`.
+
+- The functions `calc_ftemp_kphio` and `calc_ftemp_inst_vcmax` provided narrow use cases
+  with code duplication. They have been replaced with a broader
+  `calc_modified_arrhenius_factor` function.
+
+- The first components in the demography module, providing an integrated set of
+  submodules that provide: plant functional types, size-structured cohorts, plant
+  communities, a community canopy model and an implementation of the T Model for
+  allocation and growth.
+
+- An extension of the Subdaily P Model that allows the initial realised responses to be
+  provided rather than assuming that they are equal to the initial optimal responses.
+
+- The `pyrealm.splash` module has been heavily revised to break out functions within the
+  classes into standalone functions. This adds the `pyrealm.core.solar` module,
+  providing core solar calculations.
+
+- Restructuring of the developer tools for testing code performance to provide a simpler
+  local performance testing routine, and added a CI test to ensure the performance tests
+  are kept up to date with the package API.
+
 ## 1.0.0
 
 - Addition of a more pythonic re-implementation of the SPLASH v1.0 model with a more
@@ -51,11 +87,11 @@ released versions. More detail can be found at the GitHub release page for each
   - Updated typing to use consistent NDArray and remove edge case code to handle scalar
     inputs. Users now expected to provide arrays.
   - Using importlib to single source package version from pyproject.toml
-  - Moved test/ to tests/ and added __init__.py - module paths in testing.
+  - Moved test/ to tests/ and added **init**.py - module paths in testing.
   - Partial restructure of TModel code and extended test suite
   - Extended test suite for hygrometric functions, bug fix in HygroConst.
   - Better definition and handling of class attributes to avoid unnecessary Optional
-    types in __init__ methods.
+    types in **init** methods.
   - Updated docstrings, particularly class attributes now docstringed in place.
   - bounds_checker module merged into utilities module
   - Huge pmodel.py file split into a pmodel module and pmodel, functions, isotopes and
@@ -177,7 +213,7 @@ released versions. More detail can be found at the GitHub release page for each
 - Implementation of the utilities module, currently including some hygrometric
   conversions and shared utility functions.
 - Refactor of PModel and Iabs scaling
-- Better __repr__ and new summarize() functions in pmodel module.
+- Better **repr** and new summarize() functions in pmodel module.
 
 ## 0.4.0
 

docs/source/_toc.yml

@@ -39,7 +39,7 @@ subtrees:
   - file: users/splash.md
   - file: users/constants.md
   - file: users/hygro.md 
-
+  - file: users/versions.md 
 - caption: API
   entries: 
   - glob: api/*

docs/source/users/versions.md

@@ -0,0 +1,69 @@
+---
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.16.4
+kernelspec:
+  display_name: Python 3
+  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
+---
+
+# Versions and migration
+
+The `pyrealm` package is still being actively developed and the functionality in the
+package is being extended and revised. This document is describes the main changes in
+functionality between major versions and provides code migration notes for changes in
+the API of `pyrealm` code.
+
+## Migration from 1.0.0 to version 2.0.0
+
+There are two major API changes to existing code.
+
+1. The signatures for both the {class}`~pyrealm.pmodel.pmodel.PModel` and
+   {class}`~pyrealm.pmodel.subdaily.SubdailyPModel` classes have changed the way in
+   which the quantum yield parameter ($\phi_0$) is set. The classes now require a
+   specific named method for setting $\phi_0$. Each method has an associated default
+   reference value of $\phi_0$, but these can be overridden. This new API makes it
+   possible to extend the set of approaches for calculating quantum yield, and is
+   motivated by the addition of the `sandoval` method for estimating effects of soil
+   moisture stress on $\phi_0$.
+
+    This change replaces the previous `kphio` and `do_ftemp_kphio` arguments.
+
+    ```{code-block} ipython
+    # Old syntax for fixed kphio
+    mod = PModel(env, kphio=0.125, do_ftemp_kphio=False)
+    # New syntax
+    mod = PModel(env, method_kphio='fixed', reference_kphio=0.125)
+
+
+    # Old syntax for temperature variable kphio
+    mod = PModel(env, kphio=0.125, do_ftemp_kphio=True)
+    # New syntax
+    mod = PModel(env, method_kphio='temperature', reference_kphio=0.125)
+    ```
+
+1. The {mod}`pyrealm.pmodel.functions` module used to provide `calc_ftemp_kphio` and
+   `calc_ftemp_inst_vcmax`. These functions overlapped a lot but were tuned to specific
+   enzyme systems. They have been depracated and replaced with the more general function
+   `calc_modified_arrhenius_factor` that can be used more widely across the package.
+
+## Version details
+
+```{include} ../../../CHANGES.md
+    :start-line: 2
+```