README.md

---

The pyrealm package provides a toolbox implementing some key models for estimating plant productivity, growth and demography in Python. The outputs of different models can be then easily fed into other models within pyrealm to allow productivity estimates to be fed forward into estimation of net primary productivity, growth and ultimately plant community demography.

The pyrealm package currently includes:

• The P Model for estimating optimal rates of plant photosynthesis given the balance between carbon capture and water loss. This includes recent extensions to incorporate the effects of water stress, slow acclimation processes, models of C3/C4 competition and carbon isotope fractionation.
• The SPLASH model for calculating soil moisture and actual evapotranspiration.
• Initial components of a demography module for modelling plant functional types, cohorts, communities and canopies, including allocation calculations using the T Model.
• A suite of core physics functions and other utilities used to support the modules above.

For more details, see the package website: https://pyrealm.readthedocs.io/.

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, 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 to help update existing code.

Using pyrealm

The pyrealm package requires Python 3 and the currently supported Python versions are: 3.10, 3.11 and 3.12. We make released package versions available via PyPi and also generate DOIs for each release via Zenodo. You can install the most recent release using pip:

pip install pyrealm

You can now get started using pyrealm. For example, to calculate the estimated gross primary productivity of a C3 plant in a location, start a Python interpreter, using python, python3 or ipython depending on your installation, and run:

import numpy as np
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])
)

# 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

This should give the following output:

array([76.42544948])

The package website provides worked examples of using pyrealm, for example to:

• fit the P Model,
• include acclimation in estimating light use efficiency , and
• estimate C3/C4 competition.

These worked examples also show how pyrealm can be used within Python scripts or Jupyter notebooks and how to use pyrealm with large datasets loaded using numpy or xarray with pyrealm classes and functions.

Citing pyrealm

The pyrealm repository can be cited following the information in the citation file. If you are using pyrealm in research, it is better to cite the DOI of the specific release from Zenodo.

Developing pyrealm

If you are interested in contributing to the development of pyrealm, please read the guide for contributors. Please do also read the code of conduct for contributing to this project.

Support and funding

Development of the pyrealm package has been supported by the following grants and institutions:

• The REALM project, funded by an ERC grant to Prof. Colin Prentice (Imperial College London).
• The LEMONTREE project, funded by Schmidt Sciences through the VESRI programme to support an international research team lead by Prof. Sandy Harrison (University of Reading).
• The Virtual Rainforest project, funded by a Distinguished Scientist award from the NOMIS Foundation to Prof. Robert Ewers (Imperial College London)
• Research software engineering support from the Institute of Computing for Climate Science at the University of Cambridge, through the Virtual Institute for Scientific Software program funded by Schmidt Sciences.