Opt model

Description

OptModel is built on eco-evolutionary optimality principles to simulate how vegetation gross primary productivity (GPP) responds to climate and atmospheric CO₂. It integrates optimal stomatal conductance theory, optimal Ci/Ca theory, and the coordination theory, treating stomatal conductance (gs), intercellular CO₂ ratio, and maximum rate of Ribulose-1,5-bisphosphate carboxylase/ oxygenase (Rubisco) carboxylation (Vcmax) as outcomes of a carbon gain versus water cost trade-off, which enables analytical solutions for key variables. Driven by LAI and climate forcings (temperature, precipitation, potential evapotranspiration, VPD, radiation, elevation, and CO₂), the model requires only a small number of parameters (i.e., b). It can compute GPP, gs, Vcmax, and marginal water-use efficiency, among others. Compared with empirical formulations, OptModel is parsimonious and physically interpretable, better capturing responses to climate variability and elevated CO₂, and it scales well across sites and regions (Hu et al., 2025).

Examples

using Junimo
using CairoMakie
using CSV, DataFrames

# root_dir = "."
data_path = joinpath(root_dir, "data", "BE-Vie_8day")
df = CSV.read(data_path, DataFrame)

begin
  Ta = df.Tavg              # [°C]
  Precip = df.Prcp          # [mm]
  PET = df.PET              # [mm]
  PAR = (df.Rs * 0.4) * 4.6 # [W m-2] -> [umol m-2 s-1]
  LAI = df.LAI              # [m2 m-2]
  VPD = df.VPD              # [kPa]
  elv = df.elv              # [m]
  Ca = df.co2               # [ppm]
  b = df.b                  # [-]

  res = OptModel.(Ta, Precip, PET, PAR, LAI, VPD, elv, Ca, b)
  GPP_Opt = getindex.(res, 1)
end

begin
  yobs, ysim = df.GPP_obs, GPP_Opt
  fig = Figure(; size=(300, 300))
  ax = Axis(
    fig[1, 1], titlefont = :regular,
    xlabel = "Observed GPP (gC/m2/day)", ylabel = "OptModel GPP (gC/m2/day)",
    rightspinevisible = false, topspinevisible = false,
     xgridvisible = false, ygridvisible = false
  )
  scatter!(ax, yobs, ysim; markersize=10, color=:lightblue)
  lines!(ax, [0, 15], [0, 15]; color=:red, linestyle=:dash, linewidth=2)
  show_gof!(
    ax, 0.1, 14.9, yobs, ysim; metrics=["R2", "RMSE", "PBIAS"],
    n=3, align=(:left, :top), color=:black
  )
  xlims!(ax, 0, 15)
  ylims!(ax, 0, 15)
  fig
end

APIs

Junimo.OptModel — Function

OptModel(Ta, Precip, PET, PAR, LAI, VPD, elv, Ca, b)

Inputs

Ta: air temperature [°C]
Precip: precipitation [mm]
PET: potential evapotranspiration [mm]
PAR: photosynthetically active radiation [umol m-2 s-1]
LAI: leaf area index [m2 m-2]
VPD: vapor pressure deficit [kPa]
elv: elevation [m]
Ca: ambient CO2 concentration [umol mol-1 or ppm]
b: calibrated scalar parameter [-]

Outputs

GPP: gross primary production [gC m-2 day-1]
Gc: canopy conductance [mol m-2 s-1]
Vcmax: maximum carboxylation capacity [umol m-2 s-1]

Parameters

b: calibrated scalar parameter [-]
LightExtCoef: 0.5

Formula

\[GPP = f_c = \frac{ V_{cmax} \times (C_a - \sqrt{1.6 \times \lambda \times VPD \times C_a}) }{ K + \chi \times C_a } \\ Gc_{water} = 1.6 \times Gc_{carbon} = 1.6 \times \frac{ V_{cmax} }{ K + \chi \times C_a } \times (-1 + (\frac{ C_a }{ 1.6 \times \lambda \times VPD }) ^ \frac{1}{2}) \\ V_{cmax} = \phi_0 \times I_{abs} \times \frac{m'}{m_c}\]

Notes

fPAR is computed from LAI using a Beer-Lambert canopy extinction model.
Soil moisture limitation uses the aridity index (AI = Precip / PET).

References

Zhongmin Hu et al. (2025) Simulating climatic responses of vegetation production with ecological optimality theories. The Innovation Geoscience. 3, 100153–11.
Stocker et al. (2020, GMD)
Wang et al. (2017, Nature Plants)
Prentice et al. (2014, Ecology Letters)
Katul et al. (2010)

source

Junimo.fraction_of_photosynthetically_active_radiation — Function

fraction_of_photosynthetically_active_radiation(LAI; LightExtCoef = 0.5)

Compute the fraction of absorbed PAR (fPAR) using a Beer-Lambert canopy extinction model.

Inputs

LAI: leaf area index [m2 m-2], scalar or array
LightExtCoef: canopy light extinction coefficient k [-]

Outputs

fPAR: fraction of absorbed PAR [-], bounded in [0, 1]

Rules for stability:

If LAI is missing, return missing.
If LAI <= 0, return 0.
Output is clamped to [0, 1].

Formula

\[fPAR = 1 - e^{-k \times LAI}\]

References

Beer-Lambert law for canopy radiation transfer.
Monsi, M., and Saeki, T. (1953). On the factor light in plant communities and its importance for matter production.
Sellers, P. J. (1985). Canopy reflectance, photosynthesis and transpiration.

source

Junimo.soil_moisture_constraint_factor — Function

soil_moisture_constraint_factor(Precip, PET; f_AI_min = 0.01)

Soil moisture constraint factor based on aridity index (AI).

Inputs

Precip: precipitation [mm], scalar or array
PET: potential evapotranspiration [mm], scalar or array
fAImin: lower bound for AI, default is 0.01 [-]

Outputs

fAI: soil moisture constraint factor [-], bounded in [fAI_min, 1]

Rules for stability:

If Precip or PET is missing, return 1 (no soil moisture constraint).
If PET <= 0, return f_AI_min to avoid division by zero or negative PET.

Formula

\[f_{AI} = \mathrm{clamp}(\frac{P}{PET}, 0.01, 1)\]

References

Budyko (1974)

source

Junimo.surface_pressure — Function

surface_pressure(elv)

Surface pressure estimated from elevation using a standard atmosphere formulation.

Inputs

elv: elevation [m]

Outputs

Pa: surface pressure [Pa]

Formula

\[Pa = P_0 \left(1 - \frac{k_L z}{T_0}\right)^{\frac{g M_a}{R k_L}}\]

Notes

Uses constants PA0 [Pa], TAOPTK [K], and kR [J mol-1 K-1].

References

Stocker et al. (2020, GMD)
Allen (1973)
Tsilingiris (2008)

source

Junimo.photorespiratory_compensation_point — Function

photorespiratory_compensation_point(Ta, Pa)

Photorespiratory compensation point (Γ*).

Inputs

Ta: air temperature [°C], scalar or array
Pa: air pressure [Pa], scalar or array

Outputs

Γ*: photorespiratory compensation point [umol mol-1]

Rules for stability:

Units follow the constant definitions in this file; use Ta in °C and Pa in Pa.

Notes

Uses constants ?*_25 and ?H_{?*} defined above, and scales by Pa/PA0.
The factor 10 converts from Pa to umol mol-1.

References

Stocker et al. (2020, GMD)

source

Junimo.effective_michaelis_menten_coefficient_of_rubisco — Function

effective_michaelis_menten_coefficient_of_rubisco(Ta, Pa)

Effective Michaelis-Menten coefficient of Rubisco.

Inputs

Ta: air temperature [°C]
Pa: air pressure [Pa]

Outputs

K: effective Michaelis-Menten coefficient [Pa]

Rules for stability:

Units follow the constant definitions in this file; use Ta in °C and Pa in Pa.

Notes

kco uses the US Standard Atmosphere for O2.

References

Stocker et al. (2020, GMD)

source

Junimo.marginal_water_use_efficiency — Function

marginal_water_use_efficiency(Ta, Precip, PET, VPD, Pa, Ca)

Compute marginal water use efficiency and related intermediate terms.

Inputs

Ta: air temperature [°C]
Precip: precipitation [mm]
PET: potential evapotranspiration [mm]
VPD: vapor pressure deficit [kPa]
Pa: air pressure [Pa]
Ca: ambient CO2 concentration [umol mol-1]

Outputs

Γ_star: photorespiratory compensation point [umol mol-1]
K: effective Michaelis-Menten coefficient [Pa]
ξ: intermediate term (Prentice et al., 2014)
λ: marginal water use efficiency [-]
Dvpr: dimensionless VPD [Pa Pa-1]

Rules for stability:

Units follow the constant definitions in this file; use Ta in °C, VPD in kPa, Pa in Pa.

Notes

Uses the Prentice et al. (2014) formulation with viscosity correction (Wang et al., 2017).

References

Prentice et al. (2014, Ecology Letters)
Katul et al. (2010)
Wang et al. (2017, Nature Plants)

source