A research companion to the playground. This document describes what the model actually computes, how its light-response and protection terms relate to established photosynthesis physiology, and where the scalar simplification departs from the standard biochemical models.
The playground treats oxygenic photosynthesis as a controllable landscape. Seventeen physiological parameters and three speculative control nodes feed a deterministic steady-state function, simulate(), that returns a carbon-fixation proxy, a reactive-oxygen-species (ROS) load, a homeostasis score, a bifurcation risk, and a regime label. A second layer runs a 48-step trajectory under five perturbation profiles, accumulating damage memory so that the same nominal conditions can yield different outcomes depending on history. The model is a teaching instrument, not a predictive crop model. Its light response is a genuine rectangular hyperbola and its CO2 response is a genuine Michaelis-Menten saturation, but its single scalar assimilation output deliberately collapses processes that the Farquhar-von Caemmerer-Berry (FvCB) framework keeps separate.
Oxygenic photosynthesis splits the light reactions across two photosystems wired in series. Photosystem II (PSII, reaction-center pigment P680) oxidises water, releasing O2 and feeding electrons into the plastoquinone pool. The cytochrome b6f complex passes those electrons to plastocyanin while pumping protons across the thylakoid membrane, building the proton-motive force that ATP synthase uses to make ATP. Photosystem I (PSI, reaction-center pigment P700) re-excites the electrons and delivers them, via ferredoxin and ferredoxin-NADP reductase, to NADP+, producing NADPH.
Plotting redox potential against the electron's journey produces the characteristic Z shape. The redox span from water (E about +0.82 V) to NADP+ (E about -0.32 V) is roughly 1.14 V. A single 680 nm photon carries about 1.82 eV, which is nominally enough, but each transfer step dissipates free energy, so two serial photon inputs are needed in practice. This two-photosystem requirement is the model's single established structural assumption (Hill and Bendall, 1960; Blankenship, 2021).
The core of the model is the light-use term
lightUse(I) = (I * antenna) / (I * antenna + Ik * (1 + 0.7 * NPQ))
where I is incident irradiance, antenna scales the effective absorption cross-section, Ik is the species half-saturation irradiance, and NPQ is the effective non-photochemical quenching. This is the rectangular hyperbola form of the photosynthesis-irradiance (P-I) curve (Jassby and Platt, 1976; Ye, 2007). It has three textbook diagnostic properties, all of which the calibration suite checks against simulate() directly:
NPQ enters the denominator: raising quenching pushes the half-saturation point to higher irradiance, the model's way of saying that a leaf dissipating more energy as heat needs more light to reach the same relative output. A larger antenna does the opposite, lowering Ik so that dim-light specialists (the Red Algae preset, with a large phycobilisome antenna and low Ik) saturate earlier.
Note that this model does not represent a light compensation point as a negative intercept. Real leaves respire, so net assimilation is slightly negative in darkness and crosses zero at the compensation irradiance. The playground's assimilation is a gross light-use proxy clamped to be non-negative, so its dark value is zero rather than minus the respiration rate. This is one of the deliberate simplifications.
Carbon-dioxide delivery enters through
co2Effective = CO2 * (1 + ccm * ccmStrength)
co2Factor = co2Effective / (co2Effective + kCO2)
another Michaelis-Menten saturation, with kCO2 the half-saturation concentration. The carbon-concentrating-mechanism (CCM) term raises the effective CO2 seen by Rubisco, capturing the qualitative advantage of C4 bundle-sheath cells and cyanobacterial carboxysomes (Sage, 2004; Badger and Price, 2003). In the FvCB framework the CO2 response is more structured: it is the lower envelope of a Rubisco-limited rate and an RuBP-regeneration-limited rate, with a sharp transition between them. The playground uses one smooth saturation instead of that piecewise envelope.
When absorbed light exceeds what carbon fixation can consume, excess excitation drives the formation of reactive oxygen species that damage the D1 protein of PSII. The model represents three defences, each grounded in the literature:
repair and rosBuffer parameters set a repair capacity that is differenced against ROS load to give net damage.ROS load grows with irradiance, excitation mismatch, water stress, and supra-optimal temperature, and is damped by NPQ and the ROS buffer. Damage memory integrates the running excess of ROS over repair.
The trajectory layer is where the state-space framing earns its name. Each of the 48 steps re-runs simulate() under a time-varying irradiance and temperature profile, then updates damage memory by the net of ROS over repair. Because memory feeds back into the next step's penalty, two leaves reaching the same nominal noon conditions can end in different states: one that ramped up gradually may sit in a homeostatic regime, while one hit by a high-light pulse may have accumulated enough damage to tip into the photoinhibition attractor. The regime classifier labels the photoinhibition basin when bifurcation risk or damage index crosses threshold. The calibration suite confirms that combined extreme stress (saturating light, heat, drought, crippled NPQ and repair) reliably lands in that basin.
This bifurcation is a coarse caricature of real photoinhibition dynamics, which are continuous and reversible on the timescale of D1 turnover rather than a true attractor with a separatrix. The model uses a sigmoid threshold to make the regime shift legible, not because photoinhibition is genuinely bistable.
To use the playground honestly, three departures from textbook physiology should be kept in mind.
The calibration panel checks the deterministic core against the diagnostic points listed above: the dark point, light saturation, the half-saturation irradiance, P-I monotonicity, excitation-balance symmetry, and the photoinhibition basin under extreme stress. Every predicted value is computed by simulate() at run time, not stored, so the panel re-verifies the model on each build. The stochastic, history-dependent trajectory layer is intentionally left out of calibration because its output depends on the path, not on a fixed target.