From c2c55cc979806f97c03bc43e25b2929554c2baf4 Mon Sep 17 00:00:00 2001 From: David Orme Date: Thu, 12 Dec 2024 13:50:10 +0000 Subject: [PATCH] Updated CHANGES and migration/changes in docs --- CHANGES.md | 42 +++++++++++++++++++-- docs/source/_toc.yml | 2 +- docs/source/users/versions.md | 69 +++++++++++++++++++++++++++++++++++ 3 files changed, 109 insertions(+), 4 deletions(-) create mode 100644 docs/source/users/versions.md diff --git a/CHANGES.md b/CHANGES.md index 32c7e420..5b717fe1 100644 --- a/CHANGES.md +++ b/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 diff --git a/docs/source/_toc.yml b/docs/source/_toc.yml index b91919bc..76efd22e 100644 --- a/docs/source/_toc.yml +++ b/docs/source/_toc.yml @@ -41,7 +41,7 @@ subtrees: - file: users/splash.md - file: users/constants.md - file: users/hygro.md - + - file: users/versions.md - caption: API entries: - glob: api/* diff --git a/docs/source/users/versions.md b/docs/source/users/versions.md new file mode 100644 index 00000000..c98040ee --- /dev/null +++ b/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 +```