Slab canopy Stage A: photosynthesis-coupled canopy conductance

[xkykai]

Summary

First cut of the slab-canopy (Stage A) vegetation model from LAND_TRAINING_AND_CANOPY_PLAN.md (Part II) — a single-source, resistance-only big-leaf canopy exposed as a new specific-humidity formulation, CanopyConductanceHumidity. It is the vegetation analogue of SkinHumidity: a canopy stomatal conductance g_c = LAI·gₛ in series with the aerodynamic conductance, solving the same surface vapor-flux balance for qˢ inside the Monin–Obukhov fixed point.

This targets the dominant lever on the Bowen ratio — the quantity an atmosphere-coupled LES most needs from the land.

Per the plan's §10.3 decision, this ships the A1 scientific default: Medlyn (2011) optimality conductance coupled to Farquhar (1980) C3 photosynthesis (not the Jarvis bootstrap).

What's here

• FarquharPhotosynthesis — C3 assimilation with Arrhenius temperature scaling and a smooth (θ-quadratic) min(A_c, A_j) co-limitation.
• MedlynConductance — molar optimality conductance gₛ = g₀ + 1.6(1 + g₁/√VPD)·Aₙ/cₐ.
• stomatal_conductance(...) — coupled Farquhar–Medlyn solve via a short, damped, allocation-free fixed point on intercellular CO₂ (GPU- and AD-safe; guarded √/divisions).
• CanopyConductanceHumidity — slots into the existing humidity formulation seam and runs the solve live inside the coupled flux solver, driven by per-cell leaf-to-air VPD, leaf temperature (= skin temperature, single-source), and the moisture-stress factor β(𝒮) pulled from the ground hydrology exactly as CriticalSaturation does.
• beer_lambert_absorbed_fraction — helper to derive absorbed PAR from a downwelling PAR flux.

Defaults and equations are grounded in ClimaLand (Deck et al. 2026, JAMES, App. C–E): the r_stomata + r_ae series network, Farquhar co-limitation, and the molar Medlyn form with US-Var grass values (g₁ = 166 √Pa, Vcmax25 = 5e-5).

Design notes / scope

• No changes to shared ocean/ice flux code and no exchanger changes. Absorbed PAR and CO₂ are prescribed scalars because the radiation state is not carried to the humidity call site.
• Transpiration is handled by the existing plumbing: the canopy vapor flux is transpiration, so the existing flux → evaporation → water-storage path routes it as a sink on the ground water store.
• Deferred to Stage B (documented in the source header): per-cell absorbed-PAR fields, a prognostic canopy temperature (CanopySkinTemperature R_n = H + LE solve), and canopy-height roughness + displacement.

Testing

test/test_canopy_conductance.jl (auto-discovered by the runner):

• Farquhar–Medlyn physics (Float32/Float64): assimilation rises and saturates with light, rises with CO₂; conductance falls with VPD and moisture stress and floors at g₀; intercellular CO₂ stays in (Γ*, cₐ); type stability.
• Coupled single-column: the canopy resistance lowers latent heat vs a saturated bare surface, latent flux scales with LAI, and moisture stress throttles it.

All 30 assertions pass; test/test_slab_land.jl still passes (no regression).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 84.14634% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...Models/InterfaceComputations/canopy_conductance.jl	84.14%	13 Missing ⚠️

📢 Thoughts on this report? Let us know!