Leaf-to-air VPD, and Sperry's ProfitMax

[dfalster]

Fick's law divided by the AIR deficit however hot the leaf got (#7,
PLAN 13.1). Off the energy balance the leaf is at air temperature and
vpd_leaf_ == atm_vpd_ exactly, so the prescribed-temperature path and
the golden file are untouched. On it the deficit is 3-4x the air's over
Tair 25-45, so gs and A were overstated by that factor.

Also adds optimise_psi_stem_ProfitMax() (Sperry 2017, both terms
normalised, reporting the lambda that makes the existing entry point
agree), an optional instantaneous thermal cost default off, and four
fixes on the single-layer optimisers. Blast radius in the first comment.

[dfalster]

What moved, and what did not

The golden file is bit-identical across all five commits, and that is a
property of the grid rather than evidence the changes are inert:

• the grid runs with use_energy_balance_ off, so vpd_leaf_ == atm_vpd_ by
  construction;
• its minimum assim_max_ is 3.71 (the figure this repo's guide records for that
  grid), so it never reaches the branch that zeroed transpiration.

C++ suite 486 → 534 checks, 0 failures. The baseline was built from a
detached worktree at origin/master rather than remembered — an earlier draft of
this comment said 532, which was an intermediate count from partway through this
branch's own work.

what	measured
leaf-to-air deficit vs air deficit, package defaults	3.4x / 3.2x / 4.0x at Tair 25 / 35 / 45 °C
the same in test_leaf_to_air_vpd's setting (Rn_ 400, ra_ 12, atm_vpd 1.5)	1.52x at Tair 25 °C
decoupling acceptance test	the signature moves from conductance to transpiration: E ×1.034 against D_leaf ×1.089 over the window, so gs ×0.950
ProfitMax solver	Brent returned 1.643 MPa at Tair 50 °C where the objective's maximum is full closure (−1.5314 at psi_soil, −1.5459 at the interior local max)
normalised HC invariance to kmax	worst difference 1.1e-16 across a 3x change

The four fixes on the single-layer optimisers

1. optimise_psi_stem_Sperry searched a NaN objective silently. lambda_ is an
   input with no default, cleared by setup_clean_leaf and never set by
   set_physiology, so a caller who drove the leaf and called this got a
   plausible-looking potential (2.551266 MPa at the defaults) beside
   profit_ = NaN. It now refuses.
2. opt_root_psi_, E_up_ and soil_consumption_ survived from an earlier
   collar solve, so the object reported E = 9.216e-5 beside E_up = 2.626e-5.
   Hazard 8, live on this path.
3. set_leaf_states_rates_from_psi_stem zeroed transpiration wherever
   assim_max_ < 0. Transpiration there is the hydraulic supply and does not
   depend on photosynthesis; the branch made two leaves at the same operating
   point disagree about whether water was moving, purely because one had
   respiration switched on. The shut-down state it reached for is unchanged —
   the ci root-find has no root in [gamma*, ca] and takes its
   compensation-point fallback, which is what the branch set by hand. That
   fallback did not exist when the branch was written.
4. optimise_psi_stem_ProfitMax now scans a grid before refining. See the
   measurement above.

Two things a reviewer should push back on if they disagree

The dgc_dT algebra was re-derived, not sign-flipped.
dprofit_energy_balance_term carried a named const double dgc_dT = 0.0 with a
note promising that PLAN 13.1 would make it "a one-line change instead of a
re-derivation". It would not have been: the damping factor it multiplied puts the
new term under A_T where the derivation puts it under A_prime. The two agree
only at dgc_dT = 0, which is why nothing caught it. The derivation is at the
function.

plant is unaffected by fix 3, and this is provable rather than likely.
prepare_collar_solve has its own assim_max_ < 0 exit and returns false before
any candidate potential is evaluated, so the branch is unreachable from
find_root_collar_psi — the only entry point plant uses.

Where this came from

leaf_calibration_test/sicangco-2026, a replication of Sicangco et al. (2026),
which needed Sperry's ProfitMax on the same footing as TF24. Fix 4 was found by
comparing against their Figure 4: their model closed at 48–56 °C and ours did
not, and the whole difference was the search.

[dfalster]

The docs job, and the two explanations that were wrong

The failure was leaf_model.hpp:3470: error: unexpected command endverbatim, at a line that is code in both the original and the filtered stream. Doxygen 1.17 (Homebrew) renders the same input in silence; 1.9.8 is what the runner installs, so CI was the only oracle. Bisected on a throwaway branch by workflow_dispatch, then settled with a probe header of eight isolated constructs in one render:

construct	1.9.8
one indented run	clean
=== / --- banner rules above a run	clean
| in prose, escaped by the filter	clean
| inside the run's content	clean
emoji in prose	clean
two runs in one /// block	errors, at the SECOND \endverbatim

So Doxygen 1.9 handles the first \verbatim in a /// block and drops the second one's OPEN. The reported line is in the filtered stream and lands wherever the parser next gets confused — 120 lines past the comment responsible, here.

Two things I asserted before measuring, both wrong, both now removed from the tree:

• A setext heading swallowing the block. The banner's --------- rule is directly above the prose. Probe 3 says it is clean.
• A bare \| opening a Markdown table, with \verbatim illegal in a cell. I had committed a \|-escaping change to tools/doxygen_filter.awk on this reasoning and written it into the filter's header as fact. Probes 4 and 5 say pipes are irrelevant either way, and origin/master renders green with unescaped | throughout its prose. That commit is reverted.

The fix is the banner carrying one display instead of two. docs.yml gains a step that counts \verbatim opens per block and names the offending block, so the next occurrence fails legibly instead of pointing at unrelated code.

⚠️ The /*! \file */ block is exempt from that count, and deliberately: closed_form.hpp's file block has carried two runs across a long green master, so counting it would fail the build on code Doxygen renders happily.

[dfalster]

Merged master (#99, #100, #101, #102, #103). MERGEABLE / CLEAN, all six CI jobs green.

The four conflicts, all in leaf_model.hpp

Every one was the same shape — this branch and master changed the same expression for different reasons — so three of them wanted both changes, not a choice:

Three conductance conversions. This branch replaced atm_vpd_ with vpd_leaf_; master (#103) made H2O_CO2_stom_diff_ratio a settable member. Resolved as vpd_leaf_ and H2O_CO2_stom_diff_ratio_:

stom_cond_CO2_ = atm_kpa_ * transpiration_ * kg_to_mol_h2o / vpd_leaf_
                 / H2O_CO2_stom_diff_ratio_;

dprofit's early-return dE_dpsi. Master still derives it as the two gc partials divided back by their shared gc_c. This branch rewrote it to state dE/dpsi directly, because "that cancelled a coefficient that is no longer a single number now that the deficit moves with Tleaf". This branch's version is kept — it is the substantive fix, and it references neither the VPD nor the ratio, so there was nothing of master's to fold in.

Audited afterwards rather than assumed: every ratio site in leaf_model.hpp now pairs the member with vpd_leaf_, and the only surviving bare H2O_CO2_stom_diff_ratio is the constexpr in constants.hpp that the member initialises from.

Two things the merge did not fix, both worth a look

closed_form.hpp is still on atm_vpd_. This branch introduced vpd_leaf_ as the operative VPD for the main path but did not touch the closed-form solver, so the fast approximate path and the exact path now use different VPDs wherever Tleaf != Tair. That is this branch's own scope decision rather than something the merge broke — closed_form.hpp is default-off and "not wired in" — but it is a latent inconsistency now that the two VPDs can differ, and it did not exist before this branch. Worth either updating it or saying in the header why it stays on air VPD.

man/ and NAMESPACE were stale after the merge and I regenerated them. Same gap I flagged on #103: CI regenerates the RcppR6 glue and diffs it, but nothing does that for roxygen, so man/ drifts silently. This merge would have landed with man pages describing the pre-#103 API.

Verification

• make -C tests/cpp — 566 checks, 0 failures, and the golden file is bit-identical
• gradient_golden.tsv unchanged; leaf_behaviour_fingerprint() unchanged at 3e36d9b94fd0
• devtools::test() — 1137 pass, 0 fail, 0 skip
• R CMD check --as-cran with CI's own arguments — Status: OK (0 errors, 0 warnings, 0 notes)
• ctest 2/2; both bench targets build
• The CI consumer program, extracted from this branch's own workflow heredocs and built against an installed prefix — exit 0, against master's updated pinned profit and dA/dvcmax

The bit-identical golden file is the load-bearing result: it says this branch's features are genuinely opt-in and that #101's molar-mass change and #102's gas-constant change did not disturb them. vpd_leaf_ reduces to atm_vpd_ when Tleaf == Tair, which is the default path.

[itowers1]

Looks good to me, though there is a lot of new content, so still having to get used to it. Question about optimise_psi_stem_ProfitMax vs optimise_psi_stem_sperry. For conceptual simplicity woud like to streamline number of optimisers.

[itowers1]

Still need optimise_psi_stem_Sperry, if we also now have optimise_psi_stem_ProfitMax?

[dfalster]

Merging master (#104, #106, #107, #108) in — what the conflicts were, and the blast radius

Blast radius: none. operating_points.tsv 576 points and primitives.tsv 544 values both bit-identical; 605 checks, 0 failures; bench builds. So this catch-up merge is behaviour-preserving on the golden grid, and the branch is now 0 behind master.

Two conflicts, both in set_leaf_states_rates_from_psi_stem, and both had content rather than being textual:

1. Report the leaf's own temperature #106 wrote Tleaf_ on all three branches of that function; this branch had already deleted one of them. The assim_max_ < 0 early exit is gone here (56450b4, "water moves whether or not there is carbon to be had"), so Report the leaf's own temperature #106's note — "the two shut-down branches transpire nothing" — now describes one. Reworded to two paths, keeping Report the leaf's own temperature #106's reasoning for why the shut-down branch must write its own Tleaf_: on the PM path a leaf that transpires nothing is the hottest one, so leaving it to the transpiring branch reports the previous candidate's temperature exactly where the answer is most extreme.

2. Report the leaf's own temperature #106 stores Tleaf_ before the temperature update; this branch was recomputing leaf_temp_from_E for its own set_leaf_vpd call. Both now read the stored Tleaf_, so the temperature the Farquhar parameters were derived at, the temperature the leaf-to-air deficit was derived at, and the temperature reported to the caller cannot be three different numbers. Same value by construction (identical expression, identical order), hence bit-identical — and it drops a redundant leaf_temp_from_E from a path that runs ~10³ times per solve, which is what Report the leaf's own temperature #106's own comment asks for.

R/RcppR6.R conflicted only on its generated hash line. Regenerated with RcppR6::RcppR6() rather than hand-merged; src/RcppR6.cpp and the three support headers came out unchanged.

One thing found and deliberately not fixed here

The remaining shut-down branch (psi_upstream >= psi_stem) writes Tleaf_ but not vpd_leaf_, so a reported leaf-to-air deficit there is the previous candidate's. That is hazard 8 applied to one output over from the one #106 fixed, and it is pre-existing on both sides of this merge. It may move golden rows, so it wants its own change with its own before/after rather than being folded into a conflict resolution. Filing separately.