Design doc: multi-patch water redistribution

[dfalster]

Adds notes/427-multipatch-water.md, a design doc with no implementation, for
the water-flow arm of the multi-patch epic.

It separates three water processes — event-time surface redistribution,
within-patch vertical buckets, donor-controlled subsurface flux — toggled by
climate and soil rather than by a hand switch; puts N patches and their
topographic and soil attributes in a Landscape container that leaves Patch
and Environment largely untouched; and uses donor control to make the
cross-patch Jacobian triangular, so a single downslope sweep replaces a stiff
coupled ODE. It also records the soil-vs-redistribution identifiability hazard
and a sequencing that covers the Mulga target in its first two steps.

Refs #427. Draft, for circulation rather than merge.

[dfalster]

Closing — keeping this as a planning doc on the branch feature/multipatch-water-proposal, no PR for now.

[dfalster]

Hi @itowers1 @yangsophieee -- some initial thoughts on a multipatch setup capturing upslope-downslope dynamics in semi-arid, but in a way that also generalises to wet environments.

Also identifies/link to some dependencies that need to be sorted first.

No immediate need to do anything. Just wanted to document things rumbling around in my head, so you can start thinking about it whenever suits

[itowers1]

Looking at this now!

[dfalster]

Working detail, moved off the PR description so it does not land in git log. Under squash merge the description becomes the commit message verbatim; this comment is just as permanent and is linked from the squashed subject. See the family guideline.

Original description, unchanged:

---

Adds notes/427-multipatch-water.md — a design/planning doc (no implementation) for the water-flow arm of the multi-patch epic #427, following the existing notes/ convention (517-nsc-seed.md, plan-tf24-scenario-framework.md).

What it covers

• Three separable water processes: event-time surface redistribution (drylands), within-patch vertical N-layer bucket (always on), donor-controlled subsurface flux (wet systems) — toggled by climate/soil, not a hand switch.
• Landscape/MetaPatch container holding N patches + topographic/soil static attributes, leaving Patch/Environment largely untouched.
• Donor-control → triangular Jacobian → single downslope sweep, avoiding a stiff coupled cross-patch ODE (consistent with the "design out stiffness" philosophy, [speed] [acclimation] Tame TF24f fast-relaxation stiffness locally (IMEX / operator-split / exponential-Newton substep) — not a global implicit solver #529).
• Two-level stepper mirroring the existing outer (node refinement) / inner (adaptive time-stepping) SCM loops at the landscape level.
• Topographically covarying soil (catena) + the soil-vs-redistribution identifiability hazard.
• Sequencing (semi-arid steps 1–2 are cheap and cover the Mulga target; wet-region 3–4 can wait), validation ladder, and open questions.

Issue wiring

• Parent: [patch variations] Multi-patch dynamics #427 (realises its "connected by water flow" criterion + graph formulation — to be linked under its Issues list)
• Depends on: [TF24 hydraulics] [Env drivers] Enable event-driven hydraulics #522 (events queue), [TF24 hydraulics] new growth model with hydraulics and competition for water #424 (TF24 hydraulics), [speed] [acclimation] Tame TF24f fast-relaxation stiffness locally (IMEX / operator-split / exponential-Newton substep) — not a global implicit solver #529 (per-patch stiffness)
• Interacts with: [Env drivers] Drive model (individuals or patches) with variable environments #425, [simplify interface] scope user interface for running individuals, patches, multiple patches #428, [AutoDiff] Enable automatic differentiation (AD) across plant for gradient-based calibration #472/[AutoDiff] Inventory of numerical (finite-difference) derivatives and AD replacement opportunities #537, [Env drivers] AWRA-R Confirm that water is conserved in the system (i.e. prec + soil water + bottom layer drainage) #454, [other] Rename NodeSchedule → Schedule #505; siblings [patch variations] Continuous patch #519/[patch variations] LSM mode #520

Open for discussion

Includes the newly-raised design question extend existing SCM vs build a separate multi-patch SCM (doc leans toward a composition layer), plus patch-graph construction from a DEM, where the rainfall schedule lives, and the fitness/asymmetry interaction.

Draft — opening to capture and circulate the architecture; not for merge until the direction is agreed.

🤖 Generated with Claude Code