feat: consumption-basis water supply with AWARE scarcity and groundwater

[koen-vg]

Stacked on #32 (basin-aware regions), which is stacked on #31 (multi-cropping baseline). Review the last commit only. This is the final structural PR of the water-aware extraction series, and it carries the single recalibration for all three — #31 and #32 must not merge without it.

Rebuilds the model's water system on a consumption basis, replacing the single per-region growing-season store sized from Huang et al. withdrawals.

What changes

Three quantities, no longer conflated. Crops need a net irrigation requirement E (GAEZ). The resource that is scarce is consumption C. What gets reported in the literature is withdrawal W. The model now separates them: crop links draw E from per-region field buses, a delivery link draws C = E / eta_c from the regional pool with eta_c calibrated at build time against observed WaterGAP consumption, and W is reported via the consumed fraction.

Availability and scarcity from AWARE 2.0 on WaterGAP 2.2e volumes. The regional pool, its monthly timing and its within-region basin allocation come from WaterGAP's irrigation surface field; AWARE supplies the convex scarcity curve. The Water Footprint Network "sustainable" branch and the water.supply_scenario key are gone; the source is now water.data.availability (aware | current_use).

Optional intra-year resolution. water.temporal_resolution (a divisor of 12) splits the year into periods that each balance their own surface availability against the demand landing in them, so a season whose surface falls short draws groundwater endogenously rather than being rescued by annual averaging. Demand is placed into periods by the observed MIRCA-OS irrigated crop calendar, retimed by iterative proportional fitting to WaterGAP's monthly requirement.

Groundwater as an annual resource. Renewable and non-renewable bands (annual, per region — an aquifer can be pumped in any period) sit additively on top of the period-bound surface supply, so mining emerges endogenously wherever surface plus recharge fall short, instead of being capped at renewable availability.

Two new solve-time levers, both off by default: water_scarcity (price and/or cap accumulated AWARE scarcity) and groundwater_depletion (price and/or cap accumulated mining). Analysis gains a water_metrics output: per-region withdrawal, scarcity, renewable groundwater and depletion.

Defaults chosen for main (deliberately cheaper than the study branch)

The water-aware branch runs quarterly resolution with the full scarcity curve. That is the right setting for a water study and the wrong default for everyone else, so main ships:

water:
  temporal_resolution: 1      # annual
  supply:
    scarcity_tiers: false     # one flat availability cap per region-period
    groundwater: true         # surface/groundwater split retained

I retired the supply.mode ladder (single → scarcity → groundwater) in favour of two independent switches. The ladder welded two orthogonal decisions to one enum and had no rung for "collapsed tiers with the groundwater split" — the combination main wants. All four combinations are now valid and primary_resources was always mode-agnostic, so this costs nothing downstream. One subtlety this exposed: the groundwater bands must be derived from the pre-collapse curve, since renewable groundwater borrows the region's scarcest surface CF, and with collapsed tiers every surface CF is zero — passing the collapsed table would have silently made renewable groundwater free.

Two honest caveats about the default, both stated in the docs and changelog:

1. At temporal_resolution: 1 a region's whole annual pool is available to every season — exactly the averaging the seasonal design exists to remove. The groundwater bands consequently go nearly inert and reported depletion falls to near zero. That near-zero is an artefact of the resolution, not a finding. Any study about water should raise it.
2. data.availability: aware is a looser water system than main's current binding present-day withdrawal cap, so results will move. It is still the right default — better dataset, and eta_c anchors the baseline draw to observed consumption regardless of pool size — but it deserves a sanity check on the first recalibrated solve.

tests/config/test.yaml pins temporal_resolution: 4 with tiers and groundwater on, so CI keeps exercising the full-fidelity path that the shipped default does not.

Also

• Scarcity pricing/capping now raises if scarcity_tiers is off, rather than silently pricing a signal that is identically zero.
• Fixed a GAEZ artefact where a few cells carry a negative net irrigation requirement, which flipped those crop links into spurious water producers.
• Removed the dead WFN availability script and the now-unused blue_water_availability / growing_season_water build inputs, which went dead when the per-region water store was replaced.
• New chapter docs/water.rst; crop_production.rst's water section now points at it.

Verification

Full pipeline builds, solves and analyzes on the test config at T=4 with tiers and groundwater on. Global totals are plausible for the test config's 9-crop subset: 863 km³/yr irrigation consumption (1488 km³ reported withdrawal), 227 km³ renewable groundwater, 27 km³ depletion, draw-weighted mean CF 25 on AWARE's 0.1–100 scale. The objective-breakdown reconciliation — which is a hard identity check — passes with the new water carriers. 42 water unit tests plus the full suite pass.

Calibration

This PR carries the single tools/calibrate regeneration for the whole structural series (multi-cropping anchoring → basin-aware regions → this), for both tracked artefact sets. See the final commit.

Review follow-up

An independent model review validated the water chain empirically against the built and solved test network: every water, water_field and groundwater bus balances (max imbalance 2.6e-3 Mm³), water is an input on every crop port, per-period shares sum to the annual requirement, sum_p(CF_p × draw_p) reproduces the scarcity store to 8 digits, delivery draw matches tier draw to 1e-3 Mm³, and eta_c stays in range with no division blow-up. All four scarcity_tiers × groundwater combinations were exercised at T ∈ {1,2,3,4,6,12}: collapsed surface conserves capacity to 1.5e-11 Mm³, and the CF fix is confirmed necessary — bands built from the collapsed table give renewable-groundwater CF = 0 for every region, bands built from the pre-collapse curve give the real CF.

It found two real bugs, both now fixed in the last commit:

• solve_and_analyze_model was missing all the water params, so any config with solving.inline_analysis — both GSA configs — would have died with AttributeError the moment run_solve read them. There is now a static cross-check that every water param run_solve reads is defined in both solve rules and in the cluster manifest.
• The rice-CH₄ sensitivity dial was silently inert. It hardcoded bus4; rice CH₄ now sits at bus(3 + T), and over half of it moved to crop_production_multi, which the carrier filter never covered at any resolution. On the quarterly test build the old mask matched zero links, so GSA sweeps of the CH₄ factor left rice cultivation — about a fifth of the CH₄ budget — unscaled. Fixed and verified at exactly 2.00× under a 2× dial.

Two open questions for a maintainer, deliberately not decided here

1. Renewable groundwater borrows the region's maximum surface CF, which saturates: 86% of regions land exactly at CF_MAX = 100, and the statistic drifts with resolution (mean 95.5 at T=1, 99.98 at T=12). In the solved network renewable groundwater is 26% of volume but 70% of reported scarcity, so scarcity_mm3_eq — and anything a scarcity price or cap acts on — is dominated by a saturated constant rather than AWARE's spatial signal. A volume-weighted or high-percentile CF would be more defensible and stable in T. I left it alone because the water study computes its headline numbers with this exact definition, and changing it here would silently diverge main from the study.
2. The eta_c feasibility floor is annual while the binding constraint is per-period. At T=4, 259 of 703 region-periods with baseline demand exceed that period's surface cap; groundwater currently rescues all of them, so the default solve is clean, but with supply.groundwater: false that baseline quietly lands on slack instead of being flagged. I corrected the docstring, which claimed a property the code does not deliver; making the floor and warning per-region-period is the right follow-up.