Chlorophyll Fluorescence, State Transitions & PAM
Internal photosystem fluorescence yields and emitted photon fluxes are computed from the same photosystem excitations and realized electron flows used by carbon assimilation, either through empirical PSII rate competition with replaceable non-photochemical quenching (RateCompetitionFluorescence, ConstantQuenching, SaturationQuenching) or through coupled PSII/PSI + Cytochrome CytochromeFluorescence), or through the PSII lake-model relations of Gu et al. (2019), which take the open reaction-center fraction as an input and also return the linear electron flow from an observed fluorescence flux (LakeModelFluorescence). Closed-form LHCII state transitions (qT, StateTransitionRule) and apparent Pulse-Amplitude-Modulated fluorometry with PSI detector leakage (PAMFluorescenceObserver) compose directly on top of the steady-state photosystem states.
Walkthroughs: PSII fluorescence, Cytochrome b6f stress fluorescence, Flexas (2002) water-stress SIF, Lake-model fluorescence.
Fluorescence Models & Quenching Laws
LeafPhotosynthesis.AbstractFluorescence Type
AbstractFluorescenceSupertype for replaceable leaf chlorophyll fluorescence source models.
sourceLeafPhotosynthesis.NoFluorescence Type
NoFluorescence()Disable fluorescence calculations explicitly; fluorescence returns nothing.
LeafPhotosynthesis.RateCompetitionFluorescence Type
RateCompetitionFluorescence(; fluorescence_rate, constitutive_heat_rate,
maximum_photochemical_rate, quenching, yield_tolerance)
RateCompetitionFluorescence(fluorescence_rate, constitutive_heat_rate,
maximum_photochemical_rate, quenching, yield_tolerance)Parameterize steady-state PSII excitation rate competition with dimensionless rates fluorescence_rate (K_F > 0), constitutive_heat_rate (K_D ≥ 0), maximum_photochemical_rate (K_P,max > 0), quenching (AbstractQuenching), and roundoff allowance yield_tolerance (≥ 0).
Consumes realized linear electron flow and PSII excitation; PSI emission and within-leaf spectral escape are modeled separately.
sourceLeafPhotosynthesis.CytochromeFluorescence Type
CytochromeFluorescence(; psii, psi, yield_tolerance)
CytochromeFluorescence(psii, psi, yield_tolerance)Parameterize the mechanistic steady-state PSII + PSI fluorescence model coupled through Cytochrome b₆f redox poise and energy-dependent feedback quenching K_N (Johnson & Berry 2021, Eqs. 7–30).
LeafPhotosynthesis.LakeModelFluorescence Type
LakeModelFluorescence(; maximum_photochemical_yield, heat_to_fluorescence_ratio, yield_tolerance)
LakeModelFluorescence(maximum_photochemical_yield, heat_to_fluorescence_ratio, yield_tolerance)Parameterize the PSII lake-model relations between fluorescence, photochemistry and non-photochemical quenching of Gu et al. (2019, Eqs. 9–21) with
maximum_photochemical_yield( , the dark-adapted PSII yield with every reaction center open and no regulated quenching),heat_to_fluorescence_ratio( , constitutive heat dissipation relative to fluorescence), androundoff allowance
yield_tolerance(≥ 0) on the largest photochemical yield.
In the lake model all PSII antennae share one exciton pool, so photochemistry competes with the rate NPQ: fluorescence takes PSIIOpenFractionInputs, or the CoupledPhotosystemInputs of CytochromePhotosynthesis) and returns the NPQ they imply; lake_model_yields evaluates the yields from NPQ; electron_flow_from_fluorescence inverts an observed fluorescence flux for the linear electron flow. Only PSII is described: PSI emission and within-leaf or canopy escape are outside the model.
LeafPhotosynthesis.AbstractQuenching Type
AbstractQuenching{FT}Supertype for relative-rate non-photochemical quenching laws implementing quenching_rate.
LeafPhotosynthesis.ConstantQuenching Type
ConstantQuenching(rate)
ConstantQuenching(; rate)Represent a constant, nonnegative, dimensionless regulated heat-dissipation rate rate (K_N ≥ 0) sharing the normalization of K_F and K_D.
LeafPhotosynthesis.SaturationQuenching Type
SaturationQuenching(maximum_rate, exponent, half_saturation)
SaturationQuenching(; maximum_rate, exponent, half_saturation)Parameterize instantaneous empirical feedback quenching (van der Tol et al. 2014, Eq. 19): maximum_rate ≥ 0, exponent (α > 0), and half_saturation (β > 0).
LeafPhotosynthesis.quenching_rate Function
quenching_rate(law, saturation)Evaluate the dimensionless regulated non-photochemical quenching rate constant K_N at excitation saturation (∈ [0, 1]); a saturation outside [0, 1] (or NaN) gives NaN.
Photosystem Rate Parameters & Flux Inputs
LeafPhotosynthesis.PSIIRateParameters Type
PSIIRateParameters(; fluorescence_rate, constitutive_heat_rate,
maximum_photochemical_rate, exciton_transfer_rate, sustained_quenching_rate)
PSIIRateParameters(fluorescence_rate, constitutive_heat_rate,
maximum_photochemical_rate, exciton_transfer_rate, sustained_quenching_rate)Specify first-order PSII excitation decay and inter-unit transfer rate constants sharing a common normalization (conventionally ns⁻¹, Johnson & Berry 2021, Table 1):
fluorescence_rate(K_F2 > 0).constitutive_heat_rate(K_D2 ≥ 0).maximum_photochemical_rate(K_P2 > 0).exciton_transfer_rate(K_U2 ≥ 0;0selects the separate-units puddle limit,> 0selects connected-units exciton sharing).sustained_quenching_rate(K_N,sus ≥ 0; dark-sustained thermal dissipation).
LeafPhotosynthesis.PSIRateParameters Type
PSIRateParameters(; fluorescence_rate, constitutive_heat_rate,
maximum_photochemical_rate, closed_quenching_rate)
PSIRateParameters(fluorescence_rate, constitutive_heat_rate,
maximum_photochemical_rate, closed_quenching_rate)Specify first-order PSI excitation decay rate constants sharing one normalization (conventionally ns⁻¹, Johnson & Berry 2021, Table 1):
fluorescence_rate(K_F1 > 0).constitutive_heat_rate(K_D1 ≥ 0).maximum_photochemical_rate(K_P1 > 0in open P700 centers).closed_quenching_rate(K_X1 > 0radiationless decay in oxidized P700⁺ centers).
LeafPhotosynthesis.PSIIFluxInputs Type
PSIIFluxInputs(psii_excitation, linear_electron_flow)
PSIIFluxInputs(; psii_excitation, linear_electron_flow)Store PSII-delivered photon flux psii_excitation and realized linear_electron_flow [μmol m⁻² one-sided leaf s⁻¹] for RateCompetitionFluorescence.
LeafPhotosynthesis.CoupledPhotosystemInputs Type
CoupledPhotosystemInputs{FT}(psii_excitation, psi_excitation,
linear_electron_flow, psi_electron_flow, psii_open_fraction)
CoupledPhotosystemInputs(psii_excitation, psi_excitation,
linear_electron_flow, psi_electron_flow, psii_open_fraction)
CoupledPhotosystemInputs(; psii_excitation, psi_excitation,
linear_electron_flow, psi_electron_flow, psii_open_fraction)Bundle scalar inputs for CytochromeFluorescence:
psii_excitation,psi_excitation: absorbed photon fluxes delivered to PSII and PSI [μmol photons m⁻² one-sided leaf s⁻¹].linear_electron_flow: realized PSII linear electron fluxJ_P680[μmol e⁻ m⁻² leaf s⁻¹].psi_electron_flow: realized PSI electron fluxJ_P700 = J_P680 + J_CEF[μmol e⁻ m⁻² leaf s⁻¹].psii_open_fraction: open PSII reaction-center fractionq₂ ∈ [0, 1].
LeafPhotosynthesis.PSIIOpenFractionInputs Type
PSIIOpenFractionInputs(psii_excitation, linear_electron_flow, psii_open_fraction)
PSIIOpenFractionInputs(; psii_excitation, linear_electron_flow, psii_open_fraction)
PSIIOpenFractionInputs(flux::PSIIFluxInputs, psii_open_fraction)Store PSII-delivered photon flux psii_excitation, realized linear_electron_flow [μmol m⁻² one-sided leaf s⁻¹] and the open PSII reaction-center fraction psii_open_fraction (LakeModelFluorescence.
LeafPhotosynthesis.ObservedFluorescenceInputs Type
ObservedFluorescenceInputs(photon_flux, escape_probability, psii_fraction, psii_open_fraction)
ObservedFluorescenceInputs(; photon_flux, escape_probability, psii_fraction, psii_open_fraction)Store an observed fluorescence photon_flux [μmol photons m⁻² s⁻¹] with what electron_flow_from_fluorescence needs to relate it to PSII:
escape_probability( ): fraction of the PSII photons emitted inside the leaf that reachesphoton_flux, supplied by the optical model;psii_fraction(∈ [0, 1]): share ofphoton_fluxemitted by PSII (1when PSI emission has been removed, as Gu et al. 2019, Eq. 2, assume);psii_open_fraction( ).
photon_flux is a hemispheric photon flux integrated over the emission spectrum, on the area basis of the electron flow (one-sided leaf area for a leaf). escape_probability and psii_fraction must refer to that same flux: both depend on wavelength (red fluorescence is reabsorbed far more than far-red, and PSI emits mostly in the far-red), so a narrow-band or directional radiance has to be converted by the optical model first.
LeafPhotosynthesis.fluorescence_inputs Function
fluorescence_inputs(photosynthesis, site::LeafEnvironment, excitation=BroadbandExcitation())
fluorescence_inputs(leaf, site::LeafEnvironment, excitation=BroadbandExcitation())Return the inputs of fluorescence from the signed turnover of photosynthesis at the biochemical site site: a PSIIFluxInputs (PSII excitation and realized linear electron flow) for C3Photosynthesis, a CoupledPhotosystemInputs (PSII and PSI excitations, realized linear J_P680 and PSI J_P700 electron flows, open PSII fraction q₂) for CytochromePhotosynthesis.
Both require SignedAssimilation (the turnover contract); another sign treatment is a MethodError. An invalid site or excitation gives NaN in every field; an invalid rate domain gives NaN electron flows. After solving gas exchange, check the result with is_valid and pass a LeafEnvironment built with its biochemical_co2, never ambient CO₂.
LeafPhotosynthesis.maximum_photochemical_yield Function
maximum_photochemical_yield(model::RateCompetitionFluorescence)Compute the unquenched maximum PSII photochemical yield
LeafPhotosynthesis.psii_maximum_photochemical_yield Function
psii_maximum_photochemical_yield(psii_or_model[, psii_open_fraction = 1])Compute the PSII photochemical quantum yield at zero dynamic feedback quenching (K_N = 0) and open reaction-center fraction psii_open_fraction (∈ [0, 1]), accounting for connected-units exciton sharing (K_U2) and sustained quenching (K_N,sus).
LeafPhotosynthesis.psi_maximum_photochemical_yield Function
psi_maximum_photochemical_yield(psi_or_model)Compute the open-center PSI maximum photochemical quantum yield
LeafPhotosynthesis.minimum_psii_partition Function
minimum_psii_partition(fluorescence_model::CytochromeFluorescence,
stoichiometry::CytochromeStoichiometry;
linear_atp_per_electron, cyclic_atp_per_electron)Compute the minimum broadband PSII photon fraction β_min ensuring Φ_P2 ≤ Φ_P2,max(q₂) (K_N ≥ 0) across all positive irradiances, Cytochrome capacities, and CO₂ partial pressures under SerialLimitation (Johnson & Berry 2021, Eq. 20).
LeafPhotosynthesis.fluorescence_low_light_yield Function
fluorescence_low_light_yield(model::RateCompetitionFluorescence)Return the low-light (Q₂ → 0) PSII photochemical yield implied by model and its selected AbstractQuenching law.
LeafPhotosynthesis.validate_fluorescence_coupling Function
validate_fluorescence_coupling(fluorescence_model, electron_transport)
validate_fluorescence_coupling(fl::CytochromeFluorescence, et::CytochromeElectronParameters,
stoichiometry::CytochromeStoichiometry; linear_atp_per_electron, cyclic_atp_per_electron)
validate_fluorescence_coupling(fl::CytochromeFluorescence,
photosynthesis::CytochromePhotosynthesis, temperature, oxygen)Verify on the host that low-light photochemical yields and photosystem partition parameters of electron_transport (or photosynthesis) are consistent with fluorescence_model within yield_tolerance, throwing ArgumentError on mismatch.
Steady-State Fluorescence Evaluation & Status Codes
LeafPhotosynthesis.RateCompetitionResult Type
RateCompetitionResult{FT}Store scalar PSII rate-competition diagnostics for RateCompetitionFluorescence.
photon_flux is internal PSII fluorescence emission [μmol photons m⁻² one-sided leaf s⁻¹] prior to within-leaf optical escape. Check is_valid before consuming outputs; boundary_roundoff flags tolerated roundoff above the maximum photochemical yield.
LeafPhotosynthesis.CytochromeFluorescenceResult Type
CytochromeFluorescenceResult{FT}Store scalar PSII and PSI fluorescence fluxes, quantum yields, open-center fractions and dynamic quenching psii_quenching_rate (K_N) for CytochromeFluorescence, with two Stern–Volmer quenching indices of PSII:
npq: the PAM index of an ideal PSII-only observer with equal dark and light cross-sections, referenced to the dark-adapted, which includes the sustained quenching (the same reference as pam_fluorescence'sapparent_npq).total_quenching_ratio: , all regulated and sustained heat dissipation relative to PSII without any non-photochemical quenching.
The two agree when
psii_photon_flux, psi_photon_flux, and total_photon_flux represent internal leaf emission rates [μmol photons m⁻² one-sided leaf s⁻¹] prior to within-leaf optical escape and reabsorption. Check is_valid before consuming fluxes or yields.
LeafPhotosynthesis.LakeModelResult Type
LakeModelResult{FT}Store scalar PSII lake-model diagnostics for LakeModelFluorescence: the four yields of absorbed PSII excitation (they sum to one), the input psii_open_fraction (npq (
photon_flux is internal PSII fluorescence emission [μmol photons m⁻² one-sided leaf s⁻¹] prior to within-leaf optical escape. Check is_valid before consuming outputs; boundary_roundoff flags tolerated roundoff above the largest photochemical yield of the open fraction, where npq is set to zero.
LeafPhotosynthesis.FluorescenceStatus Type
FluorescenceStatusEnumerate non-throwing outcome codes returned by fluorescence and pam_fluorescence on CPU and GPU devices:
FluorescenceLit: positive photosystem excitation within the steady-state domain.FluorescenceDark: zero excitation and zero realized electron flow (0photon flux,NaNyields).FluorescenceInvalidInput: non-finite, negative, or out-of-domain input values.FluorescenceIncompatibleRates: realized electron flow outside the model's photochemical domain.
LeafPhotosynthesis.FluorescenceLit Constant
FluorescenceLitFluorescenceStatus value indicating valid illuminated fluorescence evaluation.
LeafPhotosynthesis.FluorescenceDark Constant
FluorescenceDarkFluorescenceStatus value indicating exact darkness (0 excitation and 0 electron flow), with zero emitted photon flux and NaN flux-ratio yields.
LeafPhotosynthesis.FluorescenceInvalidInput Constant
FluorescenceInvalidInputFluorescenceStatus value indicating non-finite, negative, or out-of-range inputs.
LeafPhotosynthesis.FluorescenceIncompatibleRates Constant
FluorescenceIncompatibleRatesFluorescenceStatus value indicating that realized electron transport exceeds the fluorescence model's maximum photochemical yield or Z-scheme domain.
LeafPhotosynthesis.fluorescence Function
fluorescence(model, inputs)Evaluate internal chlorophyll fluorescence yields, rate constants and photon emission flux for the inputs of fluorescence_inputs: a RateCompetitionResult for RateCompetitionFluorescence with PSIIFluxInputs, a CytochromeFluorescenceResult for CytochromeFluorescence with CoupledPhotosystemInputs, and nothing for NoFluorescence.
Out-of-domain values do not throw: they give a result whose status (FluorescenceStatus) says why and whose yields are NaN; check it with is_valid. A model and inputs of different binary precisions are a MethodError.
LeafPhotosynthesis.lake_model_yields Function
lake_model_yields(model::LakeModelFluorescence, psii_open_fraction, npq)Evaluate the lake-model yields of absorbed PSII excitation from the open reaction-center fraction psii_open_fraction (npq (≥ 0), with
photochemical_yield (Eq. 16),fluorescence_yield (Eq. 14),constitutive_heat_yieldand regulated_heat_yield .
Return (; photochemical_yield, fluorescence_yield, constitutive_heat_yield, regulated_heat_yield), which sum to one; every field is NaN outside the domain. Multiplying photochemical_yield by the PSII excitation gives the linear electron flow (Eq. 17). (1, 0) gives the dark-adapted minimum level (0, 0) the maximum (0, npq) the light-adapted maximum
LeafPhotosynthesis.electron_flow_from_fluorescence Function
electron_flow_from_fluorescence(model::LakeModelFluorescence, observation)Compute the realized linear electron flow [μmol electrons m⁻² s⁻¹] from an observed fluorescence flux (ObservedFluorescenceInputs) with Gu et al. (2019, Eq. 21):
where NPQ nor the absorbed light enters. The result is NaN outside the input domain. For fluorescence inverted: passing it back with the same
Closed-Form LHCII State Transitions (qT)
LeafPhotosynthesis.StateTransitionRule Type
StateTransitionRule{FT}(; minimum_psii_fraction=zero(FT), maximum_psii_fraction=one(FT))
StateTransitionRule(; minimum_psii_fraction, maximum_psii_fraction)
StateTransitionRule(minimum_psii_fraction, maximum_psii_fraction)Configure closed-form state-transition antenna partitioning (qT; Johnson & Berry 2021, Eqs. 25a, 28, 30a, Cases 10–12) with optional LHCII mobility bounds 0 ≤ minimum_psii_fraction < maximum_psii_fraction ≤ 1.
Under Cytochrome b₆f limitation (J_P700,j ≤ J_P700,c), solves analytically for the PSII absorbed-photon fraction β = Q₂ / Q_abs that balances linear and cyclic electron transport at K_N = 0, freezing β at its light-saturation crossover value β_sat above J_P700,j ≥ J_P700,c.
LeafPhotosynthesis.dark_balanced_psii_partition Function
dark_balanced_psii_partition(fluorescence_model::CytochromeFluorescence,
photosynthesis::CytochromePhotosynthesis, temperature, co2, oxygen)
dark_balanced_psii_partition(fluorescence_model::CytochromeFluorescence,
photosynthesis::CytochromePhotosynthesis, site::LeafEnvironment)Compute the low-light (Q_abs → 0, q₂ → 1, K_N = 0) PSII absorbed-photon fraction NaN on invalid inputs without throwing. The closed form holds for SerialLimitation in photosynthesis.electron_transport; another co-limitation is a MethodError.
LeafPhotosynthesis.state_transition_partition Function
state_transition_partition(rule::StateTransitionRule,
fluorescence_model::CytochromeFluorescence,
photosynthesis_or_leaf, site::LeafEnvironment)Evaluate the pointwise, closed-form PSII absorbed-photon fraction β ∈ (0, 1) under rule at site (Johnson & Berry 2021, Cases 10–12), returning NaN on invalid or incompatible inputs without throwing. As for dark_balanced_psii_partition, the model must use SerialLimitation in its electron transport; another co-limitation is a MethodError.
LeafPhotosynthesis.state_transition_excitation Function
state_transition_excitation(rule::StateTransitionRule,
fluorescence_model::CytochromeFluorescence,
photosynthesis_or_leaf, site::LeafEnvironment)Return a PrescribedDualExcitation (Q₂, Q₁) implementing Johnson & Berry (2021) dynamic state transitions (qT) at site via a Sterbenz-exact split of site.absorbed_par so Q₂ + Q₁ == site.absorbed_par holds identically across all IEEE-754 binades.
Pulse-Amplitude-Modulated (PAM) Fluorometry
LeafPhotosynthesis.PAMFluorescenceObserver Type
PAMFluorescenceObserver(; psii_sensitivity, psi_sensitivity)
PAMFluorescenceObserver(psii_sensitivity, psi_sensitivity)Specify pulse-amplitude modulated (PAM) fluorometer detector weights (psii_sensitivity, psi_sensitivity) (ε_F2 > 0, ε_F1 ≥ 0) mapping internal PSII and PSI fluorescence yields to apparent detector levels F / S (Johnson & Berry 2021, Eqs. 38–42).
LeafPhotosynthesis.PAMFluorescenceResult Type
PAMFluorescenceResult{FT}Store apparent PAM fluorometer levels (fs, fm_dark, fo_dark, fm_prime, fo_prime in F / S units; Johnson & Berry 2021, Eqs. 38–42) and derived pulse-ratio indices (apparent_photochemical_yield, apparent_regulated_heat_yield, apparent_residual_yield, apparent_npq, qp, ql).
Check is_valid before consuming fields; non-lit states carry NaN fields without throwing on GPU devices.
LeafPhotosynthesis.pam_fluorescence Function
pam_fluorescence(observer::PAMFluorescenceObserver,
fluorescence_model::CytochromeFluorescence,
result::CytochromeFluorescenceResult,
alpha_psii, alpha_psi[, alpha_psii_dark, alpha_psi_dark])Evaluate apparent PAM fluorometer observables (Johnson & Berry 2021, Eqs. 38–42) from coupled internal fluorescence result, light-adapted absorption cross-sections (alpha_psii, alpha_psi), and dark-reference cross-sections (alpha_psii_dark, alpha_psi_dark) (defaulting to (alpha_psii, alpha_psi)).
LeafPhotosynthesis.dark_pam_levels Function
dark_pam_levels(observer::PAMFluorescenceObserver,
fluorescence_model::CytochromeFluorescence,
alpha_psii_dark, alpha_psi_dark)Compute dark-adapted (K_N = 0) PAM reference levels (; fo, fm, fv_fm) (F_o / S, F_m / S, and (F_m - F_o) / F_m; Johnson & Berry 2021, Eqs. 39, 41), returning NaN fields on invalid cross-sections without throwing.
LeafPhotosynthesis.detector_level Function
detector_level(observer::PAMFluorescenceObserver,
alpha_psii, psii_fluorescence_yield, alpha_psi, psi_fluorescence_yield)Compute the apparent detector level F / S of a fluorometer from the fluorescence yields of the two photosystems (Johnson & Berry 2021, Eq. 38): alpha_psii > 0, alpha_psi ≥ 0) and the weights of observer.
The yields may come from any fluorescence model, so a PSII-only formulation (RateCompetitionFluorescence, LakeModelFluorescence) can be compared with a measured signal by adding a PSI yield. For a CytochromeFluorescenceResult the value equals the fs of pam_fluorescence. Ratios of two levels (for example NaN for a negative or non-finite yield, alpha_psii ≤ 0 or alpha_psi < 0); that the two fractions belong to one measuring beam is the caller's concern.