The constants module

The constants module implements the base ConstantsClass class and then implements the following constants classes for different modules:

class C3C4Const(adv_to_frac_k: float = 6.63, adv_to_frac_q: float = 0.16, gpp_to_tc_a: float = 15.6, gpp_to_tc_b: float = 1.41, gpp_to_tc_c: float = -7.72, c3_forest_closure_gpp: float = 2.8)

Model constants for the C3C4Competition class.

This data class holds statistically estimated coefficients used to calculate the fraction of C4 plants based on the relative GPP of C3 and C4 plants for given conditions and estimated treecover (Lavergne et al., 2020).

adv_to_frac_k: float = 6.63

Coefficient k of C4 fraction estimation

adv_to_frac_q: float = 0.16

Coefficient 1 of C4 fraction estimation

c3_forest_closure_gpp: float = 2.8

GPP at which forest canopy closure occurs

gpp_to_tc_a: float = 15.6

Coefficient a of tree cover estimation

gpp_to_tc_b: float = 1.41

Coefficient b of tree cover estimation

gpp_to_tc_c: float = -7.72

Coefficient c of tree cover estimation

class ConstantsClass

Base class for model constants.

This base class provides a consistent interface for creating and exporting data from model constant classes. It defines methods to create instances from a dictionary of values and from a JSON file of values. It also defines methods to export an existing instance of a constants class to a dictionary or a JSON file.

All model constant classes use the dataclass() decorator as the basic structure. All fields in these classes are defined with default values, so instances can be defined using partial dictionaries of alternative values.

classmethod from_dict(data: dict) → ConstantsClass

Create a ConstantsClass subclass instance from a dictionary.

Generates a ConstantsClass subclass instance using the data provided in a dictionary to override default values

Parameters:

data – A dictionary, keyed by parameter class attribute names, providing values to use in a new instance.

Returns:

An instance of the subclass.

classmethod from_json(filename: str) → ConstantsClass

Create a ParamClass instance from a JSON file.

Generates a ConstantsClass subclass instance using the data provided in a JSON file.

Parameters:

filename – The path to a JSON formatted file containing a set of values keyed by parameter class attribute names to use in a new instance.

Returns:

An instance of the parameter class.

to_dict() → dict

Return a parameter dictionary.

This method returns the attributes and values used in an instance of a parameter class object as a dictionary.

Returns:

A dictionary

to_json(filename: str) → None

Export a parameter set to JSON.

This method writes the attributes and values used in an instance of a parameter class object to a JSON file.

Parameters:

filename – A path to the JSON file to be created.

Returns:

None

class CoreConst(k_R: float = 8.3145, k_co: float = 209476.0, k_c_molmass: float = 12.0107, k_water_molmass: float = 18.01258, k_Po: float = 101325.0, k_To: float = 298.15, k_L: float = 0.0065, k_G: float = 9.80665, k_Ma: float = 0.028963, k_Mv: float = 0.01802, k_CtoK: float = 273.15, visible_light_albedo: float = 0.03, swdown_to_ppfd_factor: float = 2.04, transmissivity_coef: tuple[float, float, float] = (0.25, 0.5, 2.67e-05), net_longwave_radiation_coef: tuple[float, float] = (0.2, 107.0), shortwave_albedo: float = 0.17, solar_constant: float = 1360.8, day_seconds: float = 86400, equation_of_time_coef: tuple[float, ...] = (7.5e-05, 0.001868, -0.032077, -0.014615, -0.04089, 229.18), solar_eccentricity: float = 0.0167, solar_obliquity: float = 23.44, solar_perihelion: float = 283.0, magnus_coef: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, mwr: float = 0.622, magnus_option: str | None = None, water_density_method: str = 'jones_harris_eq6', fisher_dial_lambda: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, fisher_dial_Po: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, fisher_dial_Vinf: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, chen_po: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, chen_ko: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, chen_ca: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, chen_cb: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, density_kell: tuple[tuple[float, ...], float] = ((999.83952, 16.945176, -0.0079870401, -4.6170461e-05, 1.0556302e-07, -2.8054253e-10), 0.01689785), density_jones_harris_rho: tuple[float, ...] = (999.84847, 0.06337563, -0.008523829, 6.943248e-05, -3.821216e-07), density_jones_harris_kappa: tuple[float, ...] = (5.083101e-07, -3.68293e-09, 7.263725e-11, -6.597702e-13, 2.87767e-15), water_viscosity_method: str = 'vogel', huber_tk_ast: float = 647.096, huber_rho_ast: float = 322.0, huber_mu_ast: float = 1e-06, huber_H_i: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, huber_H_ij: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>)

Constants for the core module.

This data class provides constants used in core, including hygrometric conversions, the calculation of water density and viscosity and the calculation of atmospheric pressure.

Sources for some sets of parameters are shown below:

  • Density of water using Fisher. Values for the Tumlirz equation taken from Table 5 of Fisher and Dial Jr (1975):

    \[V_p = V_\infty + \dfrac{\lambda}{P_o + P},\]

    where \(\lambda\) (fisher_dial_lambda), \(P_o\) (fisher_dial_Po) and \(V_\infty\) (fisher_dial_Vinf) are all temperature dependent polynomial functions.

  • Density of water using Chen. Values taken from Chen et al. (2008) and calculated as the inverse of their equation for the specific volume of water (\(V\)):

    \[V = V^0 - V^0 P/(K^0 +AP+BP^2),\]

    where \(V^0\) (chen_po), \(K^0\) (chen_ko), \(A\) (chen_ca, and \(B\) (chen_cb) are all temperature dependent polynomial functions.

  • Viscosity of water. Values for the parameterisation taken from Table 2 and 3 of Huber et al. (2009): (huber_tk_ast, huber_rho_ast, huber_mu_ast, huber_H_i, huber_H_ij)

chen_ca: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the polynomial temperature dependent coefficient \(A\) from Chen et al. (2008).

chen_cb: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the polynomial temperature dependent coefficient \(B\) from Chen et al. (2008).

chen_ko: ndarray[tuple[Any, ...], dtype[floating]]

Polynomial relationship of bulk modulus of water with temperature at 1 atm (\(K^0\), kg/m^3) from Chen et al. (2008).

chen_po: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the polynomial relationship of water density with temperature at 1 atm (\(P^0\), kg/m^3) from Chen et al. (2008).

day_seconds: float = 86400

The number of seconds in one solar day.

density_jones_harris_kappa: tuple[float, ...] = (5.083101e-07, -3.68293e-09, 7.263725e-11, -6.597702e-13, 2.87767e-15)

Coefficients for calculating water compressibility from (Jones and Harris, 1992), provided as a tuple of polynomial coefficients \(a,b,c,d,e\).`

density_jones_harris_rho: tuple[float, ...] = (999.84847, 0.06337563, -0.008523829, 6.943248e-05, -3.821216e-07)

Coefficients for calculating water density from (Jones and Harris, 1992), provided as a tuple of polynomial coefficients \(a,b,c,d,e\).`

density_kell: tuple[tuple[float, ...], float] = ((999.83952, 16.945176, -0.0079870401, -4.6170461e-05, 1.0556302e-07, -2.8054253e-10), 0.01689785)

Coefficients for calculating water density from (Kell, 1975), provided as a tuple of polynomial coefficients \(a,b,c,d,e,f\) and the denominator coefficient \(g\).

equation_of_time_coef: tuple[float, ...] = (7.5e-05, 0.001868, -0.032077, -0.014615, -0.04089, 229.18)

Coefficients of the equation of time Iqbal (1983)

fisher_dial_Po: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the temperature dependent polynomial for \(P_0\) in the Tumlirz equation.

fisher_dial_Vinf: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the temperature dependent polynomial for \(V_{\infty}\) in the Tumlirz equation.

fisher_dial_lambda: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the temperature dependent polynomial for \(\lambda\) in the Tumlirz equation.

huber_H_i: ndarray[tuple[Any, ...], dtype[floating]]

Temperature dependent parameterisation of Hi in Huber.

huber_H_ij: ndarray[tuple[Any, ...], dtype[floating]]

Temperature and mass density dependent parameterisation of Hij in Huber.

huber_mu_ast: float = 1e-06

Huber reference pressure (\(\mu_{ast}\) 1.0e-6, Pa s)

huber_rho_ast: float = 322.0

Huber reference density (\(\rho_{ast}\), 322.0, kg/m^3)

huber_tk_ast: float = 647.096

Huber reference temperature (\(tk_{ast}\), 647.096, Kelvin)

k_CtoK: float = 273.15

Conversion from °C to K (\(CtoK\) , 273.15, -)

k_Cw = 1.05

Supply constant, mm/hr (Federer, 1982)

k_G: float = 9.80665

Gravitational acceleration (\(G\) , 9.80665, m/s^2)

k_L: float = 0.0065

Adiabiatic temperature lapse rate (Allen, 1973) (\(L\) , 0.0065, K/m)

k_Ma: float = 0.028963

Molecular weight of dry air (Tsilingiris, 2008) (\(M_a\), 0.028963, kg/mol)

k_Mv: float = 0.01802

Molecular weight of water vapour (Tsilingiris, 2008) (\(M_v\),0.01802, kg/mol)

k_Po: float = 101325.0

Standard reference atmosphere (Allen, 1973) (\(P_o\) , 101325.0, Pa)

k_R: float = 8.3145

Universal gas constant (\(R\) , 8.3145, J/mol/K)

k_To: float = 298.15

Standard reference temperature (\(T_o\) , 298.15, K)

k_c_molmass: float = 12.0107

Molecular mass of carbon (\(c_molmass\) , 12.0107, g)

k_co: float = 209476.0

O2 partial pressure, Standard Atmosphere (\(co\) , 209476.0, ppm)

k_pir = 0.017453292519943295

Conversion factor from radians to degrees (pir , ~0.01745, -)

k_w = 0.26

Entrainment factor (Lhomme, 1997; Priestley & Taylor, 1972)

k_water_molmass: float = 18.01258

Molecular mass of water (\(h2o_molmass\) , 18.01258, g)

magnus_coef: ndarray[tuple[Any, ...], dtype[floating]]

Three coefficients of the Magnus equation for saturated vapour pressure, defaulting to those of Sonntag1990.

magnus_option: str | None = None

Pre-defined Magnus equation parameterisations. Use one of Allen1998, Alduchov1996 or Sonntag1990 to set values for magnus_coef.

mwr: float = 0.622

The ratio molecular weight of water vapour to dry air (\(MW_r\), -)

net_longwave_radiation_coef: tuple[float, float] = (0.2, 107.0)

Coefficients (\(b, A\)) of net longwave radiation function, Eqn. 11 and Table 1 of Prentice et al. (1993)

shortwave_albedo: float = 0.17

The shortwave albedo (\(A_{sw}\), unitless, Federer, 1968).

solar_constant: float = 1360.8

The solar constant (\(G_{sc}\), W/m^2, Kopp & Lean, 2011) - the long term mean total solar irradiance.

solar_eccentricity: float = 0.0167

Solar eccentricity (\(e\)), using default value for 2000 CE Berger (1978).

solar_obliquity: float = 23.44

Solar obliquity in degrees (\(\epsilon\)), using default value for 2000 CE Berger (1978).

solar_perihelion: float = 283.0

Solar longitude of perihelion in degrees (\(\omega\)), using default value for 2000 CE Berger (1978).

swdown_to_ppfd_factor: float = 2.04

Conversion factor from shortwave downwelling radiation (W m-2) to photosynthetic photon flux density (PPFD, µmol m-2 s-1): one W m-2 of sunlight is roughly 4.57 µmol m-2 s-1 of full spectrum sunlight, of which about 46% (2.04 / 4.57) is PPFD. (Meek et al., 1984).

transmissivity_coef: tuple[float, float, float] = (0.25, 0.5, 2.67e-05)

cloudy transmissivity (\(c=0.25\)), angular coefficient of transmittivity (\(d=0.5\)) and elevation factor (\(f`=2.67e-5\)).

Type:

Coefficients for calculating transmissivity from Linacre (1968)

viscosity_daubert_danner = (-51.964, 3670.6, 5.7331, -5.349e-29)

Coefficients for calculating water viscosity using the Daubert and Danner form, taken from Table 4.20 of (Viswanath, 2007).

viscosity_girifalco = (-0.3908, -689.92, 236110)

Coefficients for calculating water viscosity using the Girifalco form, taken from Table 4.12 of (Viswanath, 2007).

viscosity_reid = (-24.71, 4209.0, 0.04527, -3.376e-05)

Coefficients for calculating water viscosity using a polynomial form, taken from Table 4.18 of (Viswanath, 2007).

viscosity_viswanath_natarajan = (-4.5318, -220.57, 149.39)

Coefficients for calculating water viscosity using the Viswanath and Natarajan form, taken from Table 4.9 of (Viswanath, 2007).

viscosity_vogel = (0.02939, 507.88, 149.3)

Coefficients for calculating water viscosity using the Vogel-Fulcher-Tammann equation taken from (Viswanath and Natavajan, 1988).

visible_light_albedo: float = 0.03

The visible light albedo (\(A_{vis}\), unitless, Sellers, 1985).

water_density_method: str = 'jones_harris_eq6'

Set the method used for calculating water density.

water_viscosity_method: str = 'vogel'

Set the method used for calculating water viscosity.

class IsotopesConst(farquhar_a: float = 4.4, farquhar_b: float = 29, farquhar_b2: float = 28, farquhar_f: float = 12, vonCaemmerer_b4: float = -7.4, vonCaemmerer_s: float = 1.8, vonCaemmerer_phi: float = 0.5, frank_postfrac: float = 2.1, badeck_postfrac: float = 1.9)

Settings for calculate carbon isotope discrimination.

This data class provides values for underlying constants used in the calculation of carbon isotope discrimination from P Model instances.

  • For C4 plants, the coefficients for calculating isotopic discrimination are taken from Lavergne et al. (2022). The class also provides an alternative, but currently implemented, parameterisation using coefficients taken from von Caemmerer et al. (2014).

  • For C3 plants, the coefficients for calculating isotopic discrimination are taken from Farquhar et al. (1982).

  • Post-photosynthetic fractionation values are also provided between leaf organic matter and alpha-cellulose (Frank et al., 2015) and bulk wood (Badeck et al., 2005).

badeck_postfrac: float = 1.9

Post-photosynthetic fractionation between leaf organic matter and bulk wood (permil)

farquhar_a: float = 4.4

Intercept for isotopic discrimination for C3 plants

farquhar_b: float = 29

Coefficient for simple isotopic discrimination for C3 plants

farquhar_b2: float = 28

Coefficient for isotopic discrimination with photorespiration for C3 plants

farquhar_f: float = 12

Coefficient for isotopic discrimination with photorespiration for C3 plants

frank_postfrac: float = 2.1

Post-photosynthetic fractionation between leaf organic matter and alpha-cellulose (permil)

lavergne_delta13_a = 13.95

Intercept for isotopic discrimination for C4 plants

lavergne_delta13_b = -17.04

Slope for C4 isotopic discrimination for C4 plants

vonCaemmerer_b4: float = -7.4

Alternative coefficient for isotopic discrimination for C4 plants

vonCaemmerer_phi: float = 0.5

Alternative coefficient for isotopic discrimination for C4 plants

vonCaemmerer_s: float = 1.8

Alternative coefficient for isotopic discrimination for C4 plants

class PModelConst(sandoval_peak_phio: tuple[float, float] = (6.8681, 0.07956432), sandoval_kinetics: dict[str, float] = <factory>, tc_ref: float = 25.0, tk_ref: float = 298.15, heskel_rd: tuple[float, float] = (0.1012, 0.0005), arrhenius_vcmax: dict = <factory>, arrhenius_jmax: dict = <factory>, kphio_C4: tuple[float, float, float] = (-0.064, 0.03, -0.000464), kphio_C3: tuple[float, float, float] = (0.352, 0.022, -0.00034), bernacchi_kmm: dict[str, float] = <factory>, maximum_phi0: float = 0.125, bernacchi_gs: dict[str, float] = <factory>, soilmstress_stocker: dict[str, float] = <factory>, soilmstress_mengoli: dict[str, float] = <factory>, beta_cost_ratio_c3: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, beta_cost_ratio_c4: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, lavergne_2020_c3: tuple[float, float] = (4.55, 1.73), lavergne_2020_c4: tuple[float, float] = (np.float64(2.3527754226637803), 1.73), wang17_c: float = 0.41, smith19_coef: tuple[float, float] = (0.85, 0.05336251))

Constants for the P Model module.

This dataclass provides constants used in calculating the predictions of the P Model and associated methods.

arrhenius_jmax: dict

Coefficients of Arrhenius factor scaling for \(J_{max}\). The simple method provides an estimate of the activation energy (\(H_a\), J/mol). The kattge_knorr method provides the parameterisation from Kattge and Knorr (2007), providing the intercept and slope of activation entropy as a function of the mean growth temperature (J/mol/K), the deactivation energy constant (\(H_d\), J/mol) and the activation energy (\(H_a\), J/mol).

arrhenius_vcmax: dict

Coefficients of Arrhenius factor scaling for \(V_{cmax}\). The simple method provides an estimate of the activation energy (\(H_a\), J/mol). The kattge_knorr method provides the parameterisation from Kattge and Knorr (2007), providing the intercept and slope of activation entropy as a function of the mean growth temperature (J/mol/K), the deactivation energy constant (\(H_d\), J/mol) and the activation energy (\(H_a\), J/mol).

bernacchi_gs: dict[str, float]

Coefficients for the estimation of the photorespiratory CO2 compensation point. Values are taken from Table 1 of Bernacchi et al. (2001) and provide a dictionary of:

  • The reference value of \(\Gamma^{*}\) at standard temperature and pressure (\(\Gamma^{*}_{0}\), gs25_0, Pa), converted from the tabulated value of 42.75 µmol mol-1, , assuming a measurement at an elevation of 227.076 metres and standard atmospheric pressure for that elevation (98716.403 Pa).

  • The activation energy (\(\Delta H_a\), dha, J/mol)

The values for kc_25 and ko_25 are converted from the original tabulated values of 404.9 µmol mol-1 and 278.4 mmol mol-1 respectively to Pa, assuming a measurement at an elevation of 227.076 metres and standard atmospheric pressure for that elevation (98716.403 Pa).

bernacchi_kmm: dict[str, float]

Coefficients for the estimation of the Michaelis Menten coefficient of Rubisco-limited assimilation. Values are taken from Table 1 of Bernacchi et al. (2001) and provide a dictionary of:

  • The activation energy for \(\ce{CO2}\) (\(\Delta H_{kc}\), dhac, J/mol)

  • The activation energy for \(\ce{O2}\) (\(\Delta H_{ko}\), dhao`, J/mol))

  • The Michelis constant for \(\ce{CO2}\) at standard temperature (\(K_{c25}\), kc25, Pa)

  • The Michelis constant for \(\ce{O2}\) at standard temperature (\(K_{o25}\), ko25, Pa)

The values for kc_25 and ko_25 are converted from the original tabulated values of 404.9 µmol mol-1 and 278.4 mmol mol-1 respectively to Pa, assuming a measurement at an elevation of 227.076 metres and standard atmospheric pressure for that elevation (98716.403 Pa).

beta_cost_ratio_c3: ndarray[tuple[Any, ...], dtype[floating]]

Unit cost ratio for C3 plants (\(\beta\), 146.0) taken from Stocker et al. (2020).

beta_cost_ratio_c4: ndarray[tuple[Any, ...], dtype[floating]]

Unit cost ratio for C4 plants (\(\beta\), 16.222).

For C4 plants, we follow the estimates of the \(g_1\) parameter for C3 and C4 plants in Lin et al. (2015) and De Kauwe et al. (2015), which have a C3/C4 ratio of around 3. Given that \(g_1 \equiv \xi \propto \surd\beta\), a reasonable default for C4 plants is that \(\beta_{C4} \approx \beta_{C3} / 9 \approx 146 / 9 \approx 16.222\).

heskel_rd: tuple[float, float] = (0.1012, 0.0005)

Linear (\(b\), 0.1012) and quadratic (\(c\), 0.0005) coefficients of the temperature scaling of dark respiration. Values taken from Heskel et al. (2016):.

kphio_C3: tuple[float, float, float] = (0.352, 0.022, -0.00034)

Coefficients of the quadratic scaling of the quantum yield of photosynthesis (phi_0, \(\phi_0\)) with temperature for C3 plants, taken from Table 2 of Bernacchi et al. (2003)

kphio_C4: tuple[float, float, float] = (-0.064, 0.03, -0.000464)

Coefficients of the quadratic scaling of the quantum yield of photosynthesis (phi_0, \(\phi_0\)) with temperature for C4 plants, taken from Eqn 5 of Cai and Prentice (2020), and adjusted from the original values (-0.008, 0.00375, -0.58e-4) to account for an unintentional double scaling to account for the fraction of light reaching PS2.

lavergne_2020_c3: tuple[float, float] = (4.55, 1.73)

Intercept and slope coefficients for the effects of soil moisture on optimal chi estimates for C3 plants, following (Lavergne et al., 2020).

lavergne_2020_c4: tuple[float, float] = (np.float64(2.3527754226637803), 1.73)

Intercept and slope coefficients for the effects of soil moisture on optimal chi estimates for C4 plants, following (Lavergne et al., 2020).

maximum_phi0: float = 0.125

The theoretical maximum intrinsic quantum yield efficiency of photosynthesis (\(\phi_0\), unitless). This value defaults to 1/8 but could be set to 1/9 to capture the absence of a Q cycle (Long et al., 1993).

sandoval_kinetics: dict[str, float]

Enzyme kinetics parameters for estimation of kphio from mean growth temperature in the Sandoval method Sandoval (in_prep) for estimation of quantum yield efficiency. Values are: the intercept and slope of activation entropy as a function of the mean growth temperature (J/mol/K), the deactivation energy constant (J/mol) and the activation energy (J/mol).

sandoval_peak_phio: tuple[float, float] = (6.8681, 0.07956432)

Curvature parameters for calculation of peak phio in the Sandoval method for estimation of quantum yield efficiency.

smith19_coef: tuple[float, float] = (0.85, 0.05336251)

Scaling factors theta (\(\theta\), 0.85) and c (\(c\), 0.05336251) used in the calculation of J_max limitation using the method of Smith et al. (2019).

soilmstress_mengoli: dict[str, float]

Parameterisation of the soil moisture stress function of Mengoli et al. (2023) as a dictionary providing values for the:

  • coefficient of the maximal level function (y_a),

  • exponent of the maximal level function (y_b),

  • coefficient of the threshold function (psi_a), and

  • exponent of the threshold function (psi_b).

soilmstress_stocker: dict[str, float]

Parameterisation of the soil moisture stress function of Stocker et al. (2020) as a dictionary providing values for the:

  • intercept of the aridity sensitivity function (theta0),

  • slope of the aridity sensitivity function (thetastar),

  • lower bound in relative soil moisture (a), and

  • upper bound in relative soil moisture (b).

tc_ref: float = 25.0

Standard baseline reference temperature of photosynthetic processes in °C (\(T_o\) , 25.0, °C)

tk_ref: float = 298.15

Standard baseline reference temperature of photosynthetic processes in Kelvin (298.15, K)

wang17_c: float = 0.41

Unit carbon cost for the maintenance of electron transport capacity, value taken from Wang et al. (2017) (\(c\), 0.41, ).

class PhenologyConst(z: float = 12.227, k: float = 0.5, f0_coefficients: tuple[float, float, float] = (0.65, 0.604169, 1.9), sigma: float = 0.771)

Model constants for the phenology module class.

This data class defines constants used in the phenology module.

calculate_f0(aridity_index: ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[floating]]

Calculate the \(f_0\) parameter.

The value \(f_0\) is the ratio of annual total transpiration of annual total precipitation. It is calculated from site specific estimates of the climatological aridity index, calculated as the long term (typically 20 years) total PET over total precipitation (\(AI\), unitless) as:

\[f_0 = a \exp{\left(-b \left(\frac{AI}{c}\right)^2\right)}\]

where \(a,b,c\) are defined in the f0_coefficients attribute.

f0_coefficients: tuple[float, float, float] = (0.65, 0.604169, 1.9)

Coefficients \(a,b,c\) to calculate \(f_0\) from the local aridity index (AI), where \(a\) is the maximum value, \(b\) is the slope of the relationship with AI and \(c\) is the AI value at which the maximum value \(a\) is reached.

k: float = 0.5

The canopy light extinction coefficient (unitless)

sigma: float = 0.771

The \(\sigma\) parameter captures the ability of plants to maintain maximum LAI throughout the growing season. If a canopy with maximum LAI grows instantaneously and is present until the end of the growing season, then the potential LAI profile forms a square wave (\(\sigma = 1\)). However real plants require time to deploy a canopy at the start of the growing season, through bud formation, budburst and leaf growth. Time is also needed at the end of the season for processes such as nutrient resorption and leaf sensescence. These processes round off that square wave and this is captured by values of \(\sigma < 1\).

z: float = 12.227

The constant \(z\) (mol C m^{-2} year^{-1}) accounts for the carbon costs of building and maintaining leaves and the total below-ground allocation required to support the nutrient demand of those leaves. The default is an empirical estimate from global data.

class TModelTraits(a_hd: float = 116.0, ca_ratio: float = 390.43, h_max: float = 25.33, rho_s: float = 200.0, lai: float = 1.8, sla: float = 14.0, tau_f: float = 4.0, tau_r: float = 1.04, par_ext: float = 0.5, yld: float = 0.6, zeta: float = 0.17, resp_r: float = 0.913, resp_s: float = 0.044, resp_f: float = 0.1)

Trait data settings for a TTree instance.

This data class provides the value of the key traits used in the T model. The default values are taken from Table 1 of Li et al. (2014). Note that the foliage maintenance respiration fraction is not named in the T Model description, but has been included as a modifiable trait in this implementation. The traits are shown below with mathematical notation, default value and units shown in brackets:

a_hd: float = 116.0

Initial slope of height-diameter relationship (\(a\), 116.0, -)

ca_ratio: float = 390.43

Initial ratio of crown area to stem cross-sectional area (\(c\), 390.43, -)

h_max: float = 25.33

Maximum tree height (\(H_m\), 25.33, m)

lai: float = 1.8

Leaf area index within the crown (\(L\), 1.8, -)

par_ext: float = 0.5

PAR extinction coefficient (\(k\), 0.5, -)

resp_f: float = 0.1

Foliage maintenance respiration fraction (\(r_f\), 0.1, -)

resp_r: float = 0.913

Fine-root specific respiration rate (\(r_r\), 0.913, year-1)

resp_s: float = 0.044

Sapwood-specific respiration rate (\(r_s\), 0.044, year-1)

rho_s: float = 200.0

Sapwood density (\(\rho_s\), 200.0, kg Cm-3)

sla: float = 14.0

Specific leaf area (\(\sigma\), 14.0, m2 kg-1 C)

tau_f: float = 4.0

Foliage turnover time (\(\tau_f\), 4.0, years)

tau_r: float = 1.04

Fine-root turnover time (\(\tau_r\), 1.04, years)

yld: float = 0.6

Yield_factor (\(y\), 0.17, -)

zeta: float = 0.17

Ratio of fine-root mass to foliage area (\(\zeta\), 0.17, kg C m-2)

The ConstantsClass base class

class ConstantsClass

Base class for model constants.

This base class provides a consistent interface for creating and exporting data from model constant classes. It defines methods to create instances from a dictionary of values and from a JSON file of values. It also defines methods to export an existing instance of a constants class to a dictionary or a JSON file.

All model constant classes use the dataclass() decorator as the basic structure. All fields in these classes are defined with default values, so instances can be defined using partial dictionaries of alternative values.

classmethod from_dict(data: dict) → ConstantsClass

Create a ConstantsClass subclass instance from a dictionary.

Generates a ConstantsClass subclass instance using the data provided in a dictionary to override default values

Parameters:

data – A dictionary, keyed by parameter class attribute names, providing values to use in a new instance.

Returns:

An instance of the subclass.

classmethod from_json(filename: str) → ConstantsClass

Create a ParamClass instance from a JSON file.

Generates a ConstantsClass subclass instance using the data provided in a JSON file.

Parameters:

filename – The path to a JSON formatted file containing a set of values keyed by parameter class attribute names to use in a new instance.

Returns:

An instance of the parameter class.

to_dict() → dict

Return a parameter dictionary.

This method returns the attributes and values used in an instance of a parameter class object as a dictionary.

Returns:

A dictionary

to_json(filename: str) → None

Export a parameter set to JSON.

This method writes the attributes and values used in an instance of a parameter class object to a JSON file.

Parameters:

filename – A path to the JSON file to be created.

Returns:

None

Core constants

class CoreConst(k_R: float = 8.3145, k_co: float = 209476.0, k_c_molmass: float = 12.0107, k_water_molmass: float = 18.01258, k_Po: float = 101325.0, k_To: float = 298.15, k_L: float = 0.0065, k_G: float = 9.80665, k_Ma: float = 0.028963, k_Mv: float = 0.01802, k_CtoK: float = 273.15, visible_light_albedo: float = 0.03, swdown_to_ppfd_factor: float = 2.04, transmissivity_coef: tuple[float, float, float] = (0.25, 0.5, 2.67e-05), net_longwave_radiation_coef: tuple[float, float] = (0.2, 107.0), shortwave_albedo: float = 0.17, solar_constant: float = 1360.8, day_seconds: float = 86400, equation_of_time_coef: tuple[float, ...] = (7.5e-05, 0.001868, -0.032077, -0.014615, -0.04089, 229.18), solar_eccentricity: float = 0.0167, solar_obliquity: float = 23.44, solar_perihelion: float = 283.0, magnus_coef: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, mwr: float = 0.622, magnus_option: str | None = None, water_density_method: str = 'jones_harris_eq6', fisher_dial_lambda: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, fisher_dial_Po: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, fisher_dial_Vinf: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, chen_po: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, chen_ko: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, chen_ca: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, chen_cb: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, density_kell: tuple[tuple[float, ...], float] = ((999.83952, 16.945176, -0.0079870401, -4.6170461e-05, 1.0556302e-07, -2.8054253e-10), 0.01689785), density_jones_harris_rho: tuple[float, ...] = (999.84847, 0.06337563, -0.008523829, 6.943248e-05, -3.821216e-07), density_jones_harris_kappa: tuple[float, ...] = (5.083101e-07, -3.68293e-09, 7.263725e-11, -6.597702e-13, 2.87767e-15), water_viscosity_method: str = 'vogel', huber_tk_ast: float = 647.096, huber_rho_ast: float = 322.0, huber_mu_ast: float = 1e-06, huber_H_i: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, huber_H_ij: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>)

Constants for the core module.

This data class provides constants used in core, including hygrometric conversions, the calculation of water density and viscosity and the calculation of atmospheric pressure.

Sources for some sets of parameters are shown below:

  • Density of water using Fisher. Values for the Tumlirz equation taken from Table 5 of Fisher and Dial Jr (1975):

    \[V_p = V_\infty + \dfrac{\lambda}{P_o + P},\]

    where \(\lambda\) (fisher_dial_lambda), \(P_o\) (fisher_dial_Po) and \(V_\infty\) (fisher_dial_Vinf) are all temperature dependent polynomial functions.

  • Density of water using Chen. Values taken from Chen et al. (2008) and calculated as the inverse of their equation for the specific volume of water (\(V\)):

    \[V = V^0 - V^0 P/(K^0 +AP+BP^2),\]

    where \(V^0\) (chen_po), \(K^0\) (chen_ko), \(A\) (chen_ca, and \(B\) (chen_cb) are all temperature dependent polynomial functions.

  • Viscosity of water. Values for the parameterisation taken from Table 2 and 3 of Huber et al. (2009): (huber_tk_ast, huber_rho_ast, huber_mu_ast, huber_H_i, huber_H_ij)

chen_ca: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the polynomial temperature dependent coefficient \(A\) from Chen et al. (2008).

chen_cb: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the polynomial temperature dependent coefficient \(B\) from Chen et al. (2008).

chen_ko: ndarray[tuple[Any, ...], dtype[floating]]

Polynomial relationship of bulk modulus of water with temperature at 1 atm (\(K^0\), kg/m^3) from Chen et al. (2008).

chen_po: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the polynomial relationship of water density with temperature at 1 atm (\(P^0\), kg/m^3) from Chen et al. (2008).

day_seconds: float = 86400

The number of seconds in one solar day.

density_jones_harris_kappa: tuple[float, ...] = (5.083101e-07, -3.68293e-09, 7.263725e-11, -6.597702e-13, 2.87767e-15)

Coefficients for calculating water compressibility from (Jones and Harris, 1992), provided as a tuple of polynomial coefficients \(a,b,c,d,e\).`

density_jones_harris_rho: tuple[float, ...] = (999.84847, 0.06337563, -0.008523829, 6.943248e-05, -3.821216e-07)

Coefficients for calculating water density from (Jones and Harris, 1992), provided as a tuple of polynomial coefficients \(a,b,c,d,e\).`

density_kell: tuple[tuple[float, ...], float] = ((999.83952, 16.945176, -0.0079870401, -4.6170461e-05, 1.0556302e-07, -2.8054253e-10), 0.01689785)

Coefficients for calculating water density from (Kell, 1975), provided as a tuple of polynomial coefficients \(a,b,c,d,e,f\) and the denominator coefficient \(g\).

equation_of_time_coef: tuple[float, ...] = (7.5e-05, 0.001868, -0.032077, -0.014615, -0.04089, 229.18)

Coefficients of the equation of time Iqbal (1983)

fisher_dial_Po: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the temperature dependent polynomial for \(P_0\) in the Tumlirz equation.

fisher_dial_Vinf: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the temperature dependent polynomial for \(V_{\infty}\) in the Tumlirz equation.

fisher_dial_lambda: ndarray[tuple[Any, ...], dtype[floating]]

Coefficients of the temperature dependent polynomial for \(\lambda\) in the Tumlirz equation.

huber_H_i: ndarray[tuple[Any, ...], dtype[floating]]

Temperature dependent parameterisation of Hi in Huber.

huber_H_ij: ndarray[tuple[Any, ...], dtype[floating]]

Temperature and mass density dependent parameterisation of Hij in Huber.

huber_mu_ast: float = 1e-06

Huber reference pressure (\(\mu_{ast}\) 1.0e-6, Pa s)

huber_rho_ast: float = 322.0

Huber reference density (\(\rho_{ast}\), 322.0, kg/m^3)

huber_tk_ast: float = 647.096

Huber reference temperature (\(tk_{ast}\), 647.096, Kelvin)

k_CtoK: float = 273.15

Conversion from °C to K (\(CtoK\) , 273.15, -)

k_Cw = 1.05

Supply constant, mm/hr (Federer, 1982)

k_G: float = 9.80665

Gravitational acceleration (\(G\) , 9.80665, m/s^2)

k_L: float = 0.0065

Adiabiatic temperature lapse rate (Allen, 1973) (\(L\) , 0.0065, K/m)

k_Ma: float = 0.028963

Molecular weight of dry air (Tsilingiris, 2008) (\(M_a\), 0.028963, kg/mol)

k_Mv: float = 0.01802

Molecular weight of water vapour (Tsilingiris, 2008) (\(M_v\),0.01802, kg/mol)

k_Po: float = 101325.0

Standard reference atmosphere (Allen, 1973) (\(P_o\) , 101325.0, Pa)

k_R: float = 8.3145

Universal gas constant (\(R\) , 8.3145, J/mol/K)

k_To: float = 298.15

Standard reference temperature (\(T_o\) , 298.15, K)

k_c_molmass: float = 12.0107

Molecular mass of carbon (\(c_molmass\) , 12.0107, g)

k_co: float = 209476.0

O2 partial pressure, Standard Atmosphere (\(co\) , 209476.0, ppm)

k_pir = 0.017453292519943295

Conversion factor from radians to degrees (pir , ~0.01745, -)

k_w = 0.26

Entrainment factor (Lhomme, 1997; Priestley & Taylor, 1972)

k_water_molmass: float = 18.01258

Molecular mass of water (\(h2o_molmass\) , 18.01258, g)

magnus_coef: ndarray[tuple[Any, ...], dtype[floating]]

Three coefficients of the Magnus equation for saturated vapour pressure, defaulting to those of Sonntag1990.

magnus_option: str | None = None

Pre-defined Magnus equation parameterisations. Use one of Allen1998, Alduchov1996 or Sonntag1990 to set values for magnus_coef.

mwr: float = 0.622

The ratio molecular weight of water vapour to dry air (\(MW_r\), -)

net_longwave_radiation_coef: tuple[float, float] = (0.2, 107.0)

Coefficients (\(b, A\)) of net longwave radiation function, Eqn. 11 and Table 1 of Prentice et al. (1993)

shortwave_albedo: float = 0.17

The shortwave albedo (\(A_{sw}\), unitless, Federer, 1968).

solar_constant: float = 1360.8

The solar constant (\(G_{sc}\), W/m^2, Kopp & Lean, 2011) - the long term mean total solar irradiance.

solar_eccentricity: float = 0.0167

Solar eccentricity (\(e\)), using default value for 2000 CE Berger (1978).

solar_obliquity: float = 23.44

Solar obliquity in degrees (\(\epsilon\)), using default value for 2000 CE Berger (1978).

solar_perihelion: float = 283.0

Solar longitude of perihelion in degrees (\(\omega\)), using default value for 2000 CE Berger (1978).

swdown_to_ppfd_factor: float = 2.04

Conversion factor from shortwave downwelling radiation (W m-2) to photosynthetic photon flux density (PPFD, µmol m-2 s-1): one W m-2 of sunlight is roughly 4.57 µmol m-2 s-1 of full spectrum sunlight, of which about 46% (2.04 / 4.57) is PPFD. (Meek et al., 1984).

transmissivity_coef: tuple[float, float, float] = (0.25, 0.5, 2.67e-05)

cloudy transmissivity (\(c=0.25\)), angular coefficient of transmittivity (\(d=0.5\)) and elevation factor (\(f`=2.67e-5\)).

Type:

Coefficients for calculating transmissivity from Linacre (1968)

viscosity_daubert_danner = (-51.964, 3670.6, 5.7331, -5.349e-29)

Coefficients for calculating water viscosity using the Daubert and Danner form, taken from Table 4.20 of (Viswanath, 2007).

viscosity_girifalco = (-0.3908, -689.92, 236110)

Coefficients for calculating water viscosity using the Girifalco form, taken from Table 4.12 of (Viswanath, 2007).

viscosity_reid = (-24.71, 4209.0, 0.04527, -3.376e-05)

Coefficients for calculating water viscosity using a polynomial form, taken from Table 4.18 of (Viswanath, 2007).

viscosity_viswanath_natarajan = (-4.5318, -220.57, 149.39)

Coefficients for calculating water viscosity using the Viswanath and Natarajan form, taken from Table 4.9 of (Viswanath, 2007).

viscosity_vogel = (0.02939, 507.88, 149.3)

Coefficients for calculating water viscosity using the Vogel-Fulcher-Tammann equation taken from (Viswanath and Natavajan, 1988).

visible_light_albedo: float = 0.03

The visible light albedo (\(A_{vis}\), unitless, Sellers, 1985).

water_density_method: str = 'jones_harris_eq6'

Set the method used for calculating water density.

water_viscosity_method: str = 'vogel'

Set the method used for calculating water viscosity.

P Model constants

class PModelConst(sandoval_peak_phio: tuple[float, float] = (6.8681, 0.07956432), sandoval_kinetics: dict[str, float] = <factory>, tc_ref: float = 25.0, tk_ref: float = 298.15, heskel_rd: tuple[float, float] = (0.1012, 0.0005), arrhenius_vcmax: dict = <factory>, arrhenius_jmax: dict = <factory>, kphio_C4: tuple[float, float, float] = (-0.064, 0.03, -0.000464), kphio_C3: tuple[float, float, float] = (0.352, 0.022, -0.00034), bernacchi_kmm: dict[str, float] = <factory>, maximum_phi0: float = 0.125, bernacchi_gs: dict[str, float] = <factory>, soilmstress_stocker: dict[str, float] = <factory>, soilmstress_mengoli: dict[str, float] = <factory>, beta_cost_ratio_c3: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, beta_cost_ratio_c4: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]] = <factory>, lavergne_2020_c3: tuple[float, float] = (4.55, 1.73), lavergne_2020_c4: tuple[float, float] = (np.float64(2.3527754226637803), 1.73), wang17_c: float = 0.41, smith19_coef: tuple[float, float] = (0.85, 0.05336251))

Constants for the P Model module.

This dataclass provides constants used in calculating the predictions of the P Model and associated methods.

arrhenius_jmax: dict

Coefficients of Arrhenius factor scaling for \(J_{max}\). The simple method provides an estimate of the activation energy (\(H_a\), J/mol). The kattge_knorr method provides the parameterisation from Kattge and Knorr (2007), providing the intercept and slope of activation entropy as a function of the mean growth temperature (J/mol/K), the deactivation energy constant (\(H_d\), J/mol) and the activation energy (\(H_a\), J/mol).

arrhenius_vcmax: dict

Coefficients of Arrhenius factor scaling for \(V_{cmax}\). The simple method provides an estimate of the activation energy (\(H_a\), J/mol). The kattge_knorr method provides the parameterisation from Kattge and Knorr (2007), providing the intercept and slope of activation entropy as a function of the mean growth temperature (J/mol/K), the deactivation energy constant (\(H_d\), J/mol) and the activation energy (\(H_a\), J/mol).

bernacchi_gs: dict[str, float]

Coefficients for the estimation of the photorespiratory CO2 compensation point. Values are taken from Table 1 of Bernacchi et al. (2001) and provide a dictionary of:

  • The reference value of \(\Gamma^{*}\) at standard temperature and pressure (\(\Gamma^{*}_{0}\), gs25_0, Pa), converted from the tabulated value of 42.75 µmol mol-1, , assuming a measurement at an elevation of 227.076 metres and standard atmospheric pressure for that elevation (98716.403 Pa).

  • The activation energy (\(\Delta H_a\), dha, J/mol)

The values for kc_25 and ko_25 are converted from the original tabulated values of 404.9 µmol mol-1 and 278.4 mmol mol-1 respectively to Pa, assuming a measurement at an elevation of 227.076 metres and standard atmospheric pressure for that elevation (98716.403 Pa).

bernacchi_kmm: dict[str, float]

Coefficients for the estimation of the Michaelis Menten coefficient of Rubisco-limited assimilation. Values are taken from Table 1 of Bernacchi et al. (2001) and provide a dictionary of:

  • The activation energy for \(\ce{CO2}\) (\(\Delta H_{kc}\), dhac, J/mol)

  • The activation energy for \(\ce{O2}\) (\(\Delta H_{ko}\), dhao`, J/mol))

  • The Michelis constant for \(\ce{CO2}\) at standard temperature (\(K_{c25}\), kc25, Pa)

  • The Michelis constant for \(\ce{O2}\) at standard temperature (\(K_{o25}\), ko25, Pa)

The values for kc_25 and ko_25 are converted from the original tabulated values of 404.9 µmol mol-1 and 278.4 mmol mol-1 respectively to Pa, assuming a measurement at an elevation of 227.076 metres and standard atmospheric pressure for that elevation (98716.403 Pa).

beta_cost_ratio_c3: ndarray[tuple[Any, ...], dtype[floating]]

Unit cost ratio for C3 plants (\(\beta\), 146.0) taken from Stocker et al. (2020).

beta_cost_ratio_c4: ndarray[tuple[Any, ...], dtype[floating]]

Unit cost ratio for C4 plants (\(\beta\), 16.222).

For C4 plants, we follow the estimates of the \(g_1\) parameter for C3 and C4 plants in Lin et al. (2015) and De Kauwe et al. (2015), which have a C3/C4 ratio of around 3. Given that \(g_1 \equiv \xi \propto \surd\beta\), a reasonable default for C4 plants is that \(\beta_{C4} \approx \beta_{C3} / 9 \approx 146 / 9 \approx 16.222\).

heskel_rd: tuple[float, float] = (0.1012, 0.0005)

Linear (\(b\), 0.1012) and quadratic (\(c\), 0.0005) coefficients of the temperature scaling of dark respiration. Values taken from Heskel et al. (2016):.

kphio_C3: tuple[float, float, float] = (0.352, 0.022, -0.00034)

Coefficients of the quadratic scaling of the quantum yield of photosynthesis (phi_0, \(\phi_0\)) with temperature for C3 plants, taken from Table 2 of Bernacchi et al. (2003)

kphio_C4: tuple[float, float, float] = (-0.064, 0.03, -0.000464)

Coefficients of the quadratic scaling of the quantum yield of photosynthesis (phi_0, \(\phi_0\)) with temperature for C4 plants, taken from Eqn 5 of Cai and Prentice (2020), and adjusted from the original values (-0.008, 0.00375, -0.58e-4) to account for an unintentional double scaling to account for the fraction of light reaching PS2.

lavergne_2020_c3: tuple[float, float] = (4.55, 1.73)

Intercept and slope coefficients for the effects of soil moisture on optimal chi estimates for C3 plants, following (Lavergne et al., 2020).

lavergne_2020_c4: tuple[float, float] = (np.float64(2.3527754226637803), 1.73)

Intercept and slope coefficients for the effects of soil moisture on optimal chi estimates for C4 plants, following (Lavergne et al., 2020).

maximum_phi0: float = 0.125

The theoretical maximum intrinsic quantum yield efficiency of photosynthesis (\(\phi_0\), unitless). This value defaults to 1/8 but could be set to 1/9 to capture the absence of a Q cycle (Long et al., 1993).

sandoval_kinetics: dict[str, float]

Enzyme kinetics parameters for estimation of kphio from mean growth temperature in the Sandoval method Sandoval (in_prep) for estimation of quantum yield efficiency. Values are: the intercept and slope of activation entropy as a function of the mean growth temperature (J/mol/K), the deactivation energy constant (J/mol) and the activation energy (J/mol).

sandoval_peak_phio: tuple[float, float] = (6.8681, 0.07956432)

Curvature parameters for calculation of peak phio in the Sandoval method for estimation of quantum yield efficiency.

smith19_coef: tuple[float, float] = (0.85, 0.05336251)

Scaling factors theta (\(\theta\), 0.85) and c (\(c\), 0.05336251) used in the calculation of J_max limitation using the method of Smith et al. (2019).

soilmstress_mengoli: dict[str, float]

Parameterisation of the soil moisture stress function of Mengoli et al. (2023) as a dictionary providing values for the:

  • coefficient of the maximal level function (y_a),

  • exponent of the maximal level function (y_b),

  • coefficient of the threshold function (psi_a), and

  • exponent of the threshold function (psi_b).

soilmstress_stocker: dict[str, float]

Parameterisation of the soil moisture stress function of Stocker et al. (2020) as a dictionary providing values for the:

  • intercept of the aridity sensitivity function (theta0),

  • slope of the aridity sensitivity function (thetastar),

  • lower bound in relative soil moisture (a), and

  • upper bound in relative soil moisture (b).

tc_ref: float = 25.0

Standard baseline reference temperature of photosynthetic processes in °C (\(T_o\) , 25.0, °C)

tk_ref: float = 298.15

Standard baseline reference temperature of photosynthetic processes in Kelvin (298.15, K)

wang17_c: float = 0.41

Unit carbon cost for the maintenance of electron transport capacity, value taken from Wang et al. (2017) (\(c\), 0.41, ).

T Model traits

class TModelTraits(a_hd: float = 116.0, ca_ratio: float = 390.43, h_max: float = 25.33, rho_s: float = 200.0, lai: float = 1.8, sla: float = 14.0, tau_f: float = 4.0, tau_r: float = 1.04, par_ext: float = 0.5, yld: float = 0.6, zeta: float = 0.17, resp_r: float = 0.913, resp_s: float = 0.044, resp_f: float = 0.1)

Trait data settings for a TTree instance.

This data class provides the value of the key traits used in the T model. The default values are taken from Table 1 of Li et al. (2014). Note that the foliage maintenance respiration fraction is not named in the T Model description, but has been included as a modifiable trait in this implementation. The traits are shown below with mathematical notation, default value and units shown in brackets:

a_hd: float = 116.0

Initial slope of height-diameter relationship (\(a\), 116.0, -)

ca_ratio: float = 390.43

Initial ratio of crown area to stem cross-sectional area (\(c\), 390.43, -)

h_max: float = 25.33

Maximum tree height (\(H_m\), 25.33, m)

lai: float = 1.8

Leaf area index within the crown (\(L\), 1.8, -)

par_ext: float = 0.5

PAR extinction coefficient (\(k\), 0.5, -)

resp_f: float = 0.1

Foliage maintenance respiration fraction (\(r_f\), 0.1, -)

resp_r: float = 0.913

Fine-root specific respiration rate (\(r_r\), 0.913, year-1)

resp_s: float = 0.044

Sapwood-specific respiration rate (\(r_s\), 0.044, year-1)

rho_s: float = 200.0

Sapwood density (\(\rho_s\), 200.0, kg Cm-3)

sla: float = 14.0

Specific leaf area (\(\sigma\), 14.0, m2 kg-1 C)

tau_f: float = 4.0

Foliage turnover time (\(\tau_f\), 4.0, years)

tau_r: float = 1.04

Fine-root turnover time (\(\tau_r\), 1.04, years)

yld: float = 0.6

Yield_factor (\(y\), 0.17, -)

zeta: float = 0.17

Ratio of fine-root mass to foliage area (\(\zeta\), 0.17, kg C m-2)

Isotopic discrimination constants

class IsotopesConst(farquhar_a: float = 4.4, farquhar_b: float = 29, farquhar_b2: float = 28, farquhar_f: float = 12, vonCaemmerer_b4: float = -7.4, vonCaemmerer_s: float = 1.8, vonCaemmerer_phi: float = 0.5, frank_postfrac: float = 2.1, badeck_postfrac: float = 1.9)

Settings for calculate carbon isotope discrimination.

This data class provides values for underlying constants used in the calculation of carbon isotope discrimination from P Model instances.

  • For C4 plants, the coefficients for calculating isotopic discrimination are taken from Lavergne et al. (2022). The class also provides an alternative, but currently implemented, parameterisation using coefficients taken from von Caemmerer et al. (2014).

  • For C3 plants, the coefficients for calculating isotopic discrimination are taken from Farquhar et al. (1982).

  • Post-photosynthetic fractionation values are also provided between leaf organic matter and alpha-cellulose (Frank et al., 2015) and bulk wood (Badeck et al., 2005).

badeck_postfrac: float = 1.9

Post-photosynthetic fractionation between leaf organic matter and bulk wood (permil)

farquhar_a: float = 4.4

Intercept for isotopic discrimination for C3 plants

farquhar_b: float = 29

Coefficient for simple isotopic discrimination for C3 plants

farquhar_b2: float = 28

Coefficient for isotopic discrimination with photorespiration for C3 plants

farquhar_f: float = 12

Coefficient for isotopic discrimination with photorespiration for C3 plants

frank_postfrac: float = 2.1

Post-photosynthetic fractionation between leaf organic matter and alpha-cellulose (permil)

lavergne_delta13_a = 13.95

Intercept for isotopic discrimination for C4 plants

lavergne_delta13_b = -17.04

Slope for C4 isotopic discrimination for C4 plants

vonCaemmerer_b4: float = -7.4

Alternative coefficient for isotopic discrimination for C4 plants

vonCaemmerer_phi: float = 0.5

Alternative coefficient for isotopic discrimination for C4 plants

vonCaemmerer_s: float = 1.8

Alternative coefficient for isotopic discrimination for C4 plants

C3/C4 competition constants

class C3C4Const(adv_to_frac_k: float = 6.63, adv_to_frac_q: float = 0.16, gpp_to_tc_a: float = 15.6, gpp_to_tc_b: float = 1.41, gpp_to_tc_c: float = -7.72, c3_forest_closure_gpp: float = 2.8)

Model constants for the C3C4Competition class.

This data class holds statistically estimated coefficients used to calculate the fraction of C4 plants based on the relative GPP of C3 and C4 plants for given conditions and estimated treecover (Lavergne et al., 2020).

adv_to_frac_k: float = 6.63

Coefficient k of C4 fraction estimation

adv_to_frac_q: float = 0.16

Coefficient 1 of C4 fraction estimation

c3_forest_closure_gpp: float = 2.8

GPP at which forest canopy closure occurs

gpp_to_tc_a: float = 15.6

Coefficient a of tree cover estimation

gpp_to_tc_b: float = 1.41

Coefficient b of tree cover estimation

gpp_to_tc_c: float = -7.72

Coefficient c of tree cover estimation

Two leaf model constants

class TwoLeafConst(atmospheric_scattering_coef: float = 0.426, leaf_scattering_coef: float = 0.15, diffuse_reflectance: float = 0.036, diffuse_extinction_coef: float = 0.719, solar_obscurity_angle: float = 0.017453292519943295, direct_beam_extinction_numerator: float = 0.5, scattered_beam_extinction_numerator: float = 0.46, atmos_transmission_par: float = 0.72, vcmax_lloyd_coef: tuple[float, float] = (0.00963, 2.43), jmax25_wullschleger_coef: tuple[float, float] = (29.1, 1.64))

Constants for the two leaf, two stream model.

The derived constant for the reflectance of horizontal leaves (\(\rho_h\)) is calculated automatically from the leaf scattering coefficient (\(\sigma\)), following equation A20 of De Pury and Farquhar (1997).

\[\rho_h = \frac{1 - \sqrt{1 - \sigma}}{1 + \sqrt{1 - \sigma}}\]
atmos_transmission_par: float = 0.72

The atmospheric transmission coefficient of photosynthetically active radiation, used in the calculation of fraction of diffuse light reaching the canopy (\(a\), Table 5. of De Pury and Farquhar (1997)).

atmospheric_scattering_coef: float = 0.426

Scattering coefficient of PAR in the atmosphere (\(f_a\), dimensionless)

diffuse_extinction_coef: float = 0.719

Diffuse and scattered diffuse PAR extinction coefficient (\(k_d'\), dimensionless).

diffuse_reflectance: float = 0.036

Canopy reflection coefficient for diffuse PAR,(\(\rho_{cd}\), dimensionless).

direct_beam_extinction_numerator: float = 0.5

Numerator of the extinction beam coefficient calculation (\(n\)) for direct light.

horizontal_leaf_reflectance: float

The reflectance coefficient for horizontal leaves (\(\rho_h\)).

jmax25_wullschleger_coef: tuple[float, float] = (29.1, 1.64)

Coefficients of the empirical relationship between the maximum rate of electron transport (\(J_{max25}\)) and the carboxylation rate (\(V_{cmax25}\)), values taken from (Wullschleger, 1993).

leaf_scattering_coef: float = 0.15

Scattering coefficient of PAR by leaves by reflection and transmission (\(\sigma\), dimensionless, Table 2. of De Pury and Farquhar (1997))

scattered_beam_extinction_numerator: float = 0.46

Numerator of the extinction beam coefficient calculation (\(n\)) for scattered light.

solar_obscurity_angle: float = 0.017453292519943295

Solar obscurity angle (\(\beta_{ob}\) radians)

vcmax_lloyd_coef: tuple[float, float] = (0.00963, 2.43)

Coefficients of the canopy extinction coefficient (\(k_v\)) function, taken from Figure 10 of (Lloyd et al., 2010)

Phenology constants

class PhenologyConst(z: float = 12.227, k: float = 0.5, f0_coefficients: tuple[float, float, float] = (0.65, 0.604169, 1.9), sigma: float = 0.771)

Model constants for the phenology module class.

This data class defines constants used in the phenology module.

calculate_f0(aridity_index: ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[floating]]

Calculate the \(f_0\) parameter.

The value \(f_0\) is the ratio of annual total transpiration of annual total precipitation. It is calculated from site specific estimates of the climatological aridity index, calculated as the long term (typically 20 years) total PET over total precipitation (\(AI\), unitless) as:

\[f_0 = a \exp{\left(-b \left(\frac{AI}{c}\right)^2\right)}\]

where \(a,b,c\) are defined in the f0_coefficients attribute.

f0_coefficients: tuple[float, float, float] = (0.65, 0.604169, 1.9)

Coefficients \(a,b,c\) to calculate \(f_0\) from the local aridity index (AI), where \(a\) is the maximum value, \(b\) is the slope of the relationship with AI and \(c\) is the AI value at which the maximum value \(a\) is reached.

k: float = 0.5

The canopy light extinction coefficient (unitless)

sigma: float = 0.771

The \(\sigma\) parameter captures the ability of plants to maintain maximum LAI throughout the growing season. If a canopy with maximum LAI grows instantaneously and is present until the end of the growing season, then the potential LAI profile forms a square wave (\(\sigma = 1\)). However real plants require time to deploy a canopy at the start of the growing season, through bud formation, budburst and leaf growth. Time is also needed at the end of the season for processes such as nutrient resorption and leaf sensescence. These processes round off that square wave and this is captured by values of \(\sigma < 1\).

z: float = 12.227

The constant \(z\) (mol C m^{-2} year^{-1}) accounts for the carbon costs of building and maintaining leaves and the total below-ground allocation required to support the nutrient demand of those leaves. The default is an empirical estimate from global data.

class PhenologyConstNew(k: float = 0.5, cai_z: float = 12.227, cai_f0_coefficients: tuple[float, float, float] = (0.65, 0.604169, 1.9), cai_sigma: float = 0.771, zhou_alpha: float = 0.06666666666666667, zhu_f0: float = 0.5, zhu_z: float = 17, zhu_budyko: float = 4)

Model constants for the phenology module class.

This data class defines constants used in the phenology module. The different methods for calculating maximum fAPAR and the phenology use different settings, so these constants define some method specific settings.

Two critical values used in calculating maximum fAPAR are:

  • The value \(z\) (mol C m^{-2} year^{-1}) accounts for the carbon costs of building and maintaining leaves and the total below-ground allocation required to support the nutrient demand of those leaves. It is used to calculate an energy-limited estimate of maximum fAPAR.

  • The value \(f_0\) (-) accounts for water limitation on annual assimilation and hence sets the water-limited estimate of maximum fAPAR.

Different methods use different default values for these two parameters and they are not necessarily fixed: the method of (Cai et al., 2025) calculates \(f_0\) as a function of the aridity index for a site. These method specific differences in parameterisation are explained in the descriptions of the method implementations.

cai_f0_coefficients: tuple[float, float, float] = (0.65, 0.604169, 1.9)

The method of (Cai et al., 2025) calculates \(f_0\) as a function of a site specific climatological aridity index (AI). This attribute provides the coefficients \(a,b,c\), where \(a\) is the maximum value, \(b\) is the slope of the relationship with AI and \(c\) is the AI value at which the maximum value \(a\) is reached.

cai_sigma: float = 0.771

In the method of (Cai et al., 2025), \(\sigma\) captures the ability of plants to maintain maximum LAI throughout the growing season. If a canopy with maximum LAI grows instantaneously and is present until the end of the growing season, then the potential LAI profile forms a square wave (\(\sigma = 1\)). However real plants require time to deploy a canopy at the start of the growing season, through bud formation, budburst and leaf growth. Time is also needed at the end of the season for processes such as nutrient resorption and leaf sensescence. These processes round off that square wave and this is captured by values of \(\sigma < 1\).

cai_z: float = 12.227

A value for \(z\) used by (Cai et al., 2025), calculated as an empirical estimate from global data.

k: float = 0.5

The canopy light extinction coefficient (unitless)

zhou_alpha: float = 0.06666666666666667

In the method of (Zhou et al., 2025), this is alpha value used with the exponential weighted average to set the magnitude of the lagging between realised LAI and the steady state values.

zhu_A0_quantile = 0.95

A quantile of the daily assimilation distribution within a year used to calculate the allocation of potential GPP to LAI (\(m\)), used by (Zhu et al., 2026).

zhu_budyko: float = 4

The value of \(\bar\omega\) used to estimate maximum fAPAR in the method of (Zhu et al., 2026).

zhu_f0: float = 0.5

The value of \(f_0\) used to estimate water limited fAPAR in the method of (Zhu et al., 2026).

zhu_lagcoef = 64.6

A coefficient used in (Zhu et al., 2026) to estimate the effect of the climatological AET/PET ratio for a site on the lag length used to estimate realised LAI from steady state.

zhu_lagmax = 365

An upper bound on the lag length for estimating realised LAI used in (Zhu et al., 2026).

zhu_min_a0 = 1e-06

A lower bound on daily assimilation when calculating leaf area index, used by (Zhu et al., 2026).

zhu_z: float = 17

The value of \(z\) used to estimate energy limited fAPAR in the method of (Zhu et al., 2026).