Stomatal Conductance, Gas Diffusion, Equilibrium & Oxygen
Gas-exchange components separate stomatal target laws (BallBerry, Medlyn) and time-evolution semantics (SteadyStateStomata, PrognosticStomata, NoStomatalDynamics) from boundary+stomatal series diffusion (SeriesDiffusion, WaterVaporDiffusion), safeguarded scalar Bisection, SafeguardedNewton, EquilibriumSolver), analytic fixed-temperature gas-exchange sensitivities, and explicit gross/net O₂ budgets (CoreOxygenExchange, NoOxygenExchange).
Walkthroughs: Core exchange, Equilibrium & sensitivities, Oxygen response.
Stomatal Conductance Targets & Dynamics
LeafPhotosynthesis.AbstractStomatalTarget Type
AbstractStomatalTargetSupertype for instantaneous stomatal conductance target laws, kept separate from prognostic time evolution.
sourceLeafPhotosynthesis.BallBerry Type
BallBerry{FT}(; minimum_conductance, slope, micromole_to_mole)
BallBerry(minimum_conductance, slope, micromole_to_mole)Parameterize the Ball–Berry stomatal H₂O conductance target surface_co2 / pressure in StomatalDrivers), with minimum_conductance (g₀ [mol H₂O m⁻² leaf s⁻¹]), dimensionless slope (g₁), and micromole_to_mole [mol μmol⁻¹] converting A_n.
Throws ArgumentError unless minimum_conductance ≥ 0, slope ≥ 0 and micromole_to_mole > 0 are finite; minimum_conductance = 0 is valid (see equilibrium_gas_exchange for the closed-stomata limit it allows). These are fixed parameters, set once on the host, so an invalid value is reported where it is entered rather than as NaN results later.
LeafPhotosynthesis.Medlyn Type
Medlyn{FT}(; minimum_conductance, slope, micromole_to_mole, vpd_floor)
Medlyn(minimum_conductance, slope, micromole_to_mole, vpd_floor)Parameterize the Medlyn stomatal H₂O conductance target surface_co2 / pressure in StomatalDrivers), with minimum_conductance (g₀), slope (g₁ [Pa¹ᐟ²]), micromole_to_mole [mol μmol⁻¹] converting A_n, and positive regularization vpd_floor (D_min [Pa]).
The H₂O/CO₂ diffusivity ratio diffusivity_ratio of the leaf's SeriesDiffusion, passed to target_conductance and read by equilibrium_gas_exchange and leaf_tendencies, so the stomatal law and the CO₂ diffusion path use one value.
Throws ArgumentError unless minimum_conductance ≥ 0, slope ≥ 0, micromole_to_mole > 0 and vpd_floor > 0 are finite. These are fixed parameters, set once on the host, so an invalid value is reported where it is entered rather than as NaN results later.
LeafPhotosynthesis.AbstractStomatalModel Type
AbstractStomatalModelSupertype for equilibrium, prognostic, or disabled stomatal conductance models.
sourceLeafPhotosynthesis.SteadyStateStomata Type
SteadyStateStomata(target)
SteadyStateStomata(; target)Wrap an AbstractStomatalTarget for steady-state stomatal target evaluation and coupled equilibrium_gas_exchange solves.
LeafPhotosynthesis.PrognosticStomata Type
PrognosticStomata(; target, opening_timescale, closing_timescale)
PrognosticStomata(target, opening_timescale, closing_timescale)Parameterize first-order prognostic stomatal conductance relaxation (Liu et al. 2024, Eq. 3) with independent positive finite opening_timescale and closing_timescale [s].
Parameters are immutable; the caller owns StomatalState and time stepping.
LeafPhotosynthesis.NoStomatalDynamics Type
NoStomatalDynamics()Disable stomatal conductance evolution and retain the caller's prescribed conductance.
sourceLeafPhotosynthesis.StomatalState Type
StomatalState(conductance)
StomatalState{FT}(conductance)
StomatalState(; conductance)Hold leaf stomatal H₂O conductance [mol H₂O m⁻² leaf s⁻¹] separately from immutable model parameters. Any value is stored without throwing; entry points treat a negative or non-finite conductance as invalid input.
LeafPhotosynthesis.StomatalDrivers Type
StomatalDrivers{FT}(; assimilation, surface_co2, pressure, relative_humidity, vpd)
StomatalDrivers(assimilation, surface_co2, pressure, relative_humidity, vpd)Bundle leaf-surface drivers for stomatal target evaluation: net assimilation [μmol CO₂ m⁻² leaf s⁻¹], surface_co2 [Pa], total pressure [Pa], relative_humidity (∈ [0, 1]), and leaf-surface vpd [Pa]. Each target law reads one humidity driver (BallBerry relative_humidity, Medlyn vpd); the other is not used and may be NaN.
LeafPhotosynthesis.target_conductance Function
target_conductance(target, drivers::StomatalDrivers, diffusion::SeriesDiffusion)
target_conductance(stomatal_model, drivers::StomatalDrivers, diffusion::SeriesDiffusion)
target_conductance(leaf, drivers::StomatalDrivers, diffusion::SeriesDiffusion)Evaluate the steady-state stomatal H₂O conductance target [mol H₂O m⁻² leaf s⁻¹] of a BallBerry or Medlyn target (directly, in a SteadyStateStomata or PrognosticStomata, or in a LeafModel) for drivers, or return nothing for NoStomatalDynamics.
diffusion is the leaf's CO₂ diffusion path; its diffusivity_ratio is the H₂O/CO₂ ratio
Drivers outside their domain give NaN, never the minimum conductance: non-finite assimilation, negative or non-finite surface CO₂ (zero only without net uptake), non-positive or non-finite pressure, and an invalid humidity driver of the law: relative humidity outside [0, 1] for Ball–Berry, a non-finite VPD for Medlyn. Each law checks only the driver it uses; the other may be NaN. Net assimilation ≤ 0 gives the minimum conductance g₀.
LeafPhotosynthesis.stomatal_tendency Function
stomatal_tendency(model_or_leaf, state::StomatalState, drivers::StomatalDrivers,
diffusion::SeriesDiffusion)Compute the stomatal H₂O conductance rate of change state (0 for NoStomatalDynamics). diffusion supplies the diffusivity ratio of the target, as in target_conductance. Invalid drivers (see target_conductance) or a negative or non-finite state conductance give NaN; a closed state (conductance = 0) is valid.
Gas Diffusion & Coupled Leaf Tendencies
LeafPhotosynthesis.AbstractLeafDiffusion Type
AbstractLeafDiffusionSupertype for leaf gas-diffusion parameterizations, kept separate from biochemical demand and stomatal conductance state.
sourceLeafPhotosynthesis.SeriesDiffusion Type
SeriesDiffusion{FT}(; boundary_co2, mesophyll_co2, diffusivity_ratio, mole_to_micromole)
SeriesDiffusion(boundary_co2, mesophyll_co2, diffusivity_ratio, mole_to_micromole)Parameterize series CO₂ transport across boundary-layer conductance boundary_co2 [mol CO₂ m⁻² leaf s⁻¹], stomatal H₂O conductance (via StomatalState divided by H₂O/CO₂ diffusivity_ratio), and mesophyll conductance mesophyll_co2 [mol CO₂ m⁻² leaf s⁻¹], with unit factor mole_to_micromole [μmol mol⁻¹].
diffusivity_ratio is the only place the package stores the H₂O/CO₂ ratio of stomatal conductances (1.6 for molecular diffusion in air; there is no default): the Medlyn target reads it from the diffusion passed to target_conductance, leaf_tendencies and equilibrium_gas_exchange.
Passing Inf for boundary_co2 or mesophyll_co2 removes that resistance. The conductances may vary from leaf to leaf (wind, leaf size), so any value is stored without throwing; gas_exchange, assimilation_sensitivity and equilibrium_gas_exchange share one domain: boundary_co2 > 0 and mesophyll_co2 > 0 (Inf allowed), and finite positive diffusivity_ratio and mole_to_micromole. Outside it they return NaN (EquilibriumInvalidInput).
LeafPhotosynthesis.WaterVaporDiffusion Type
WaterVaporDiffusion(boundary_water)
WaterVaporDiffusion{FT}(boundary_water)
WaterVaporDiffusion(; boundary_water)Specify leaf boundary-layer H₂O conductance boundary_water [mol H₂O m⁻² leaf s⁻¹] (> 0; Inf removes boundary resistance), kept distinct from CO₂ boundary conductance. Like the other diffusion conductances it may vary from leaf to leaf, so any value is stored without throwing; transpiration_sensitivity returns NaN for an invalid one.
LeafPhotosynthesis.gas_exchange Function
gas_exchange(photosynthesis, environment, state, diffusion,
excitation=BroadbandExcitation())
gas_exchange(leaf, environment, state, diffusion, excitation=BroadbandExcitation())Solve analytical steady-state CO₂ diffusion and C3 assimilation at prescribed nonnegative stomatal conductance state (Liu et al. 2024, Eqs. 1–2).
Supports MinimumLimitation with SignedAssimilation (for both C3Photosynthesis and CytochromePhotosynthesis) without A–Ci iteration: each limiting branch photosynthesize (the carbon fluxes of carbon_assimilation, electron_transport and the model's extra electron diagnostics) at the solved biochemical_co2, followed by surface_co2, intercellular_co2, biochemical_co2 [Pa], total CO₂ conductance [mol m⁻² leaf s⁻¹] and diffusion_residual [μmol CO₂ m⁻² leaf s⁻¹]. Invalid excitation or forcing gives NaN in every field (see is_valid).
Closed stomata (state.conductance = 0): the total conductance g is zero and each branch's quadratic reduces to biochemical_co2 is the CO₂ compensation point of the model, respiration included, diffusion_residual reports it), intercellular_co2 equals biochemical_co2 and surface_co2 equals ambient CO₂. When a branch has NaN.
LeafPhotosynthesis.leaf_tendencies Function
leaf_tendencies(leaf, environment, stomatal_state, diffusion,
excitation=BroadbandExcitation())Evaluate prescribed-conductance gas_exchange, the stomatal target and tendency, and the oxygen_exchange budget at stomatal_state without mutating state.
leaf.stomata is a PrognosticStomata or NoStomatalDynamics; a SteadyStateStomata leaf has no tendency (solve it with equilibrium_gas_exchange) and is a MethodError.
Return (; gas_exchange, conductance_target, conductance_tendency, oxygen):
gas_exchange: thegas_exchangeresult atstomatal_state;conductance_target[mol H₂O m⁻² leaf s⁻¹] andconductance_tendency[mol H₂O m⁻² leaf s⁻²] oftarget_conductanceandstomatal_tendency, with drivers from the gas exchange (net assimilation, surface CO₂) andenvironment(pressure, relative humidity, VPD) and the diffusivity ratio ofdiffusion; forNoStomatalDynamicsthe target is the state conductance and the tendency zero;oxygen: the coupledoxygen_exchangeat the solvedbiochemical_co2, ornothingforNoOxygenExchange.
Each part follows its own domain: inputs outside the gas-exchange domain give NaN in every field of gas_exchange and oxygen and, through the drivers, in the outputs of PrognosticStomata; invalid stomatal drivers alone (for example relative humidity outside [0, 1] with a Ball–Berry target, or a NaN VPD with a Medlyn target) give NaN stomatal outputs only. The humidity driver the target does not read may be NaN.
Coupled A–Ci–gsw Equilibrium Solver
LeafPhotosynthesis.AbstractEquilibriumMethod Type
AbstractEquilibriumMethodSupertype for numerical root-finding methods used by EquilibriumSolver, kept independent of stomatal target physics.
LeafPhotosynthesis.Bisection Type
Bisection()Select bracketed bisection for independent reference equilibrium solves.
sourceLeafPhotosynthesis.SafeguardedNewton Type
SafeguardedNewton(; bisection_interval)
SafeguardedNewton(bisection_interval)Select analytic Newton iteration safeguarded within a physical CO₂ bracket, forcing a bisection step every bisection_interval (an integer > 0) iterations and whenever a Newton trial step leaves the bracket.
LeafPhotosynthesis.EquilibriumSolver Type
EquilibriumSolver(; method, co2_atol, co2_rtol, flux_atol, flux_rtol, max_iterations)
EquilibriumSolver(method, co2_atol, co2_rtol, flux_atol, flux_rtol, max_iterations)Configure numerical tolerances and iteration limits for equilibrium_gas_exchange.
co2_atol [Pa], co2_rtol [-], flux_atol [μmol CO₂ m⁻² leaf s⁻¹], and flux_rtol [-] must be finite and nonnegative with at least one positive CO₂ tolerance and one positive flux tolerance; max_iterations must be a positive integer.
LeafPhotosynthesis.EquilibriumSolution Type
EquilibriumSolution{FT,X}
EquilibriumSolution(exchange, stomatal_conductance, co2_residual, bracket_width,
iterations, status)Store the result of equilibrium_gas_exchange without allocation.
exchange::X: the gas exchange at the solution, a NamedTuple with the fields of agas_exchangeresult (carbon fluxes,electron_transportand the model's extra electron diagnostics,surface_co2,intercellular_co2,biochemical_co2[Pa], total CO₂conductance[mol CO₂ m⁻² leaf s⁻¹] anddiffusion_residual[μmol CO₂ m⁻² leaf s⁻¹]).stomatal_conductance: the solved stomatal H₂O conductance [mol H₂O m⁻² leaf s⁻¹].co2_residual[Pa]: the pressure residual of the CO₂ balance; for the closed-stomata limit, the Newton estimate of the distance to the exact compensation point.bracket_width[Pa],iterationsandstatus(EquilibriumStatus).
is_valid is true for EquilibriumConverged and EquilibriumStomataClosed; for any other status every scalar of exchange is NaN (EquilibriumInvalidInput, EquilibriumInvalidBracket) or the result is the best point found (EquilibriumIterationLimit, EquilibriumPrecisionLimit).
LeafPhotosynthesis.EquilibriumStatus Type
EquilibriumStatusEnumerate non-throwing outcome codes returned by equilibrium_gas_exchange:
EquilibriumConverged: both pressure and flux residuals satisfyEquilibriumSolvertolerances.EquilibriumIterationLimit:max_iterationsreached before meeting tolerances.EquilibriumPrecisionLimit: floating-point bracket width exhausted before meeting tolerances.EquilibriumInvalidInput: non-finite or out-of-domain parameters or environment inputs.EquilibriumInvalidBracket: physical CO₂ bracket failed to straddle a finite root, or no steady state exists (net respiration with zero minimum conductance).EquilibriumStomataClosed: zero minimum conductance and no open-stomata root; the solution is the closed-stomata limit at the CO₂ compensation point.
LeafPhotosynthesis.EquilibriumConverged Constant
EquilibriumConvergedEquilibriumStatus value indicating that both CO₂ pressure and flux residuals converged within solver tolerances.
LeafPhotosynthesis.EquilibriumIterationLimit Constant
EquilibriumIterationLimitEquilibriumStatus value indicating that max_iterations was exhausted prior to meeting solver tolerances.
LeafPhotosynthesis.EquilibriumPrecisionLimit Constant
EquilibriumPrecisionLimitEquilibriumStatus value indicating that floating-point roundoff prevented further bracket contraction before tolerances were satisfied.
LeafPhotosynthesis.EquilibriumInvalidInput Constant
EquilibriumInvalidInputEquilibriumStatus value indicating invalid parameters, conductances, or environmental forcing inputs.
LeafPhotosynthesis.EquilibriumInvalidBracket Constant
EquilibriumInvalidBracketEquilibriumStatus value indicating that the physical CO₂ bracket did not straddle a valid sign change, or that no steady state exists: with zero minimum conductance, net respiration (darkness, or light below the light compensation point) leaves no CO₂ at which assimilation balances a closed leaf.
LeafPhotosynthesis.EquilibriumStomataClosed Constant
EquilibriumStomataClosedEquilibriumStatus value of a converged closed-stomata limit: the minimum conductance is zero and no root with open stomata exists, so stomatal conductance is zero, net assimilation is zero (to the flux tolerance) and biochemical_co2 is the CO₂ compensation point of the model, respiration included. is_valid is true.
LeafPhotosynthesis.equilibrium_gas_exchange Function
equilibrium_gas_exchange(photosynthesis, SteadyStateStomata(target), environment,
diffusion, solver, excitation=BroadbandExcitation(), initial_co2=nothing)
equilibrium_gas_exchange(leaf, environment, diffusion, solver,
excitation=BroadbandExcitation(), initial_co2=nothing)Solve coupled steady-state C3 assimilation (C3Photosynthesis or CytochromePhotosynthesis), series CO₂ diffusion, and Ball–Berry or Medlyn stomatal conductance at prescribed leaf temperature and humidity.
biochemical_co2 (Cc) is solved inside a physics-derived bracket while intercellular_co2 (Ci) and surface_co2 (Cs) are reconstructed from mesophyll and boundary-layer conductances. Thermal kinetic rates and available electron supply are evaluated once per solve, darkness uses an exact analytic branch, and invalid inputs or non-convergence return explicit EquilibriumStatus codes without throwing.
The target law g₀ (common in Medlyn fits). With g₀ approaches zero:
if net assimilation is negative at every CO₂ (darkness, or light below the light compensation point), no steady state exists:
EquilibriumInvalidBracket,NaNfields;otherwise the model's CO₂ compensation point Γ (respiration included) exists. If
, stomata are open at the solution, which is the root infound as for (EquilibriumConverged);otherwise the solution is the closed-stomata limit: stomatal and total conductance zero, net assimilation zero to the flux tolerance and
biochemical_co2 = Γ(EquilibriumStomataClosed, valid). This includes ambient CO₂ at or below Γ.
initial_co2 [Pa] warm-starts the iteration, typically from the previous time step's biochemical_co2. It is nothing (start at the midpoint of the CO₂ bracket) or a scalar of the model's binary precision (a dual number over it counts by its value); another number type, including an integer, is a MethodError, as for every other argument. A warm start that is not finite or lies outside the open bracket falls back to the midpoint. It is not used when equilibrium_gas_exchange.(leaf, environments, diffusion, solver, BroadbandExcitation(), previous_co2) warm-starts every leaf from its own value. Return an EquilibriumSolution.
The humidity driver of the environment is checked per law: Ball–Berry needs a relative humidity in [0, 1] and ignores the VPD, Medlyn needs a finite VPD and ignores the relative humidity (the unused one may be NaN). The H₂O/CO₂ ratio of Medlyn is diffusion.diffusivity_ratio, the same value that converts stomatal H₂O conductance to CO₂ conductance in the diffusion path.
Fixed-Temperature Gas-Exchange Sensitivities
LeafPhotosynthesis.carbon_assimilation_derivative Function
carbon_assimilation_derivative(rates, co2, oxygen, electrons, stoichiometry, limitation, assimilation_sign)Compute the partial derivative
At MinimumLimitation or NonnegativeAssimilation kinks, return a consistent one-sided derivative.
LeafPhotosynthesis.assimilation_sensitivity Function
assimilation_sensitivity(photosynthesis, environment, state, diffusion,
excitation=BroadbandExcitation(), exchange=gas_exchange(...))Compute analytic partial derivatives of steady-state CO₂ exchange with respect to stomatal H₂O conductance state.conductance (g_sw) at fixed leaf temperature, ambient CO₂ and O₂, absorbed light, and boundary/mesophyll conductances.
Return (; dco2_dgs, dnet_assimilation_dgs) in units of Pa (mol H₂O m⁻² s⁻¹)⁻¹ and μmol CO₂ (mol H₂O)⁻¹. Without exchange, a fresh gas_exchange solve for excitation supplies biochemical_co2 and conductance; a precomputed exchange (a gas_exchange result or an EquilibriumSolution, whose exchange is used) is reused and must come from the same inputs and excitation: an exchange whose net assimilation differs from the biochemistry evaluated with excitation at its biochemical_co2, or whose total conductance is not that of state (for an EquilibriumSolution, state must hold its stomatal_conductance), gives NaN in every field. With gas_exchange gives NaN in every field. At closed stomata (state.conductance = 0, Cc the compensation point) the result is the one-sided limit, with
LeafPhotosynthesis.transpiration_sensitivity Function
transpiration_sensitivity(diffusion::WaterVaporDiffusion, state::StomatalState,
leaf_to_air_vpd, pressure)Compute leaf transpiration E = g_total * Δe / P [mol H₂O m⁻² leaf s⁻¹] and its partial derivative ∂E / ∂g_sw [mol H₂O (mol H₂O)⁻¹] at fixed temperature, leaf_to_air_vpd [Pa], total pressure [Pa], and boundary conductance.
The domain is that of the other entry points: finite nonnegative stomatal conductance, positive boundary conductance (Inf allowed), positive finite pressure and finite VPD (negative for condensation); outside it both fields are NaN. At closed stomata (g_sw = 0) E = 0 and ∂E/∂g_sw = Δe / P, the one-sided limit.
Leaf Oxygen Budget
LeafPhotosynthesis.AbstractOxygenExchange Type
AbstractOxygenExchangeSupertype for leaf oxygen-exchange components; positive net flux denotes O₂ release.
sourceLeafPhotosynthesis.CoreOxygenExchange Type
CoreOxygenExchange{FT}(; oxygen_per_oxygenation, co2_per_oxygenation, respiratory_quotient)
CoreOxygenExchange(oxygen_per_oxygenation, co2_per_oxygenation, respiratory_quotient)Specify dimensionless stoichiometric coefficients of the leaf O₂ budget: O₂ taken up (oxygen_per_oxygenation) and CO₂ released (co2_per_oxygenation) by the photorespiratory cycle per Rubisco oxygenation, and the mitochondrial respiratory_quotient (CO₂ released per O₂ consumed). Throws ArgumentError unless co2_per_oxygenation and respiratory_quotient are finite and positive and oxygen_per_oxygenation is finite and nonnegative.
Examples
julia> using LeafPhotosynthesis: OxygenFluxInputs
julia> ox = CoreOxygenExchange(1.5, 0.5, 1.0);
julia> res = oxygen_exchange(ox, OxygenFluxInputs(16.0, 4.0, 1.0));
julia> res.net_release
13.0LeafPhotosynthesis.NoOxygenExchange Type
NoOxygenExchange()Disable oxygen-budget calculations explicitly; oxygen_exchange returns nothing.
LeafPhotosynthesis.OxygenFluxInputs Type
OxygenFluxInputs{FT}(; carboxylation, rubisco_oxygenation, respiration)
OxygenFluxInputs(carboxylation, rubisco_oxygenation, respiration)Bundle realized Rubisco carboxylation and rubisco_oxygenation [μmol reactions m⁻² leaf s⁻¹] and mitochondrial CO₂ respiration [μmol CO₂ m⁻² leaf s⁻¹] for oxygen_exchange, the turnover the coupled form takes from biochemical_turnover.
LeafPhotosynthesis.oxygen_exchange Function
oxygen_exchange(oxygen_model, inputs::OxygenFluxInputs)
oxygen_exchange(oxygen_model, photosynthesis, environment,
excitation=BroadbandExcitation())
oxygen_exchange(leaf, environment, excitation=BroadbandExcitation())Return (; gross_production, photorespiratory_uptake, respiratory_uptake, net_release) [μmol O₂ m⁻² leaf s⁻¹]: gross O₂ evolution, photorespiratory and mitochondrial respiratory O₂ uptake, and net O₂ release (nothing for NoOxygenExchange). The coupled forms append the realized carboxylation and rubisco_oxygenation [μmol m⁻² leaf s⁻¹] and the realized linear_electron_flow [μmol e⁻ m⁻² leaf s⁻¹]; CytochromePhotosynthesis adds psi_electron_flow and cyclic_electron_flow. Input outside the physical domain gives NaN in every field.
Both forms compute the budget from carboxylation OxygenFluxInputs the caller gives them; when coupled to a signed C3Photosynthesis or CytochromePhotosynthesis model they are the realized turnover (co2_per_oxygenation), evaluated prior to net carbon cancellation so the compensation point causes no 0/0 singularity. The same fluxes give the same budget, bit for bit, in both forms. Gross O₂ evolution is the O₂ whose reductant the carbon cycles consume: oxygen_per_oxygenation, co2_per_oxygenation, respiratory_quotient is one. The coupled forms still report the realized linear_electron_flow.