---

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 overview

The pyrealm package uses semantic versioning and the list below summarise the major changes:

• Version 1.0.0: initial implementation of the P Model and associated functionality
• Version 2.0.0: wide refactor of P Model code to a new API, extension of the package functionality to include the SPLASH v1 model and experimental modules developing functionality for plant demography and phenology.

We strongly recommend that you update to version 2.0.0. The documentation includes a migration guide to help update existing code using version 1.0.0.

Using pyrealm

The pyrealm package requires Python 3.11 or greater and we currently test all pyrealm code using Python 3.11, 3.12 and 3.13. 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],
    fapar=1, ppfd=300)
)

# Calculate the predictions of the P Model for a C3 plant
pmodel_c3 = PModel(env)

# 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.