[taddyb]

Follow-up to #194: the documentation that work needed, plus two bug fixes it exposed.

#194 landed the gridded routing path but left a gap — every acquisition instruction lived in wiki/, which is gitignored, so none of it reached a user. This PR closes that and fixes two defects found while writing it up.

Documentation

docs/gridded_methods.md — a methods section written for a collaborator who knows hydrology but has not seen the code. Nine sections take a reader from the DDM30 network to the limitations, with six figures from the shipped runs. It covers the three undocumented deviations in the ISIMIP product, the Courant-band derivation behind sub-reach sizing, an attribute table with the reason each source deviates from Song et al. (2025) where it does, why moving lateral inflow onto cells is mass-conserving aggregation rather than interpolation, and why the negative-coefficient regime cannot bias the water balance.

docs/gridded_data.md gains a full gauge-selection section, and the README gains a gridded section with the same in brief.

Two skills, .claude/skills/ddr-training and .claude/skills/ddr-gridded, covering the standard CLI path and the gridded path. .claude/ was ignored wholesale, so the skills library could not be committed as the project instructions require; narrowed to .claude/* with an exception for skills/.

Dataset credit — the README now names Song, Bindas et al. (2025) as the source of both the lateral inflow and the attribute set, with the Zenodo archive alongside the paper DOI.

How the gauges are selected

Documented in both the README and the data guide, because grid resolution decides the answer rather than preference. A 0.5° cell is about 2,350 km², so a basin smaller than one routing element cannot be represented.

Step	Gauges
In gages_3000.csv	3,211
Drainage area > 2,000 km²	890
Snap within area tolerance	667
Observation coverage > 90%	620

Snapping searches the 3×3 neighbourhood and keeps the cell minimising |log(cell_upstream_area / gauge_drainage_area)|, with DA_TOLERANCE = (0.7, 1.4) rejecting the match if even the closest is too far off. Those bounds are asymmetric in linear terms but symmetric in log terms, which is the right symmetry for a multiplicative quantity. Nearest-centre snapping was tried first and rejected: it misplaced about half of the large gauges, by up to a factor of 201 in drainage area, because a gauge near a cell edge is often closest to a cell its river never enters.

Bug fixes

Both are instances of one failure mode: zarr answers an out-of-range read with fill values rather than raising, so a mismatched reader produces an all-NaN lateral inflow and a silently zero baseline instead of an error.

The Q′ store was written transposed. build_gridded_qprime.py emitted Qr(time, divide_id), the transpose of the contract the dHBV2 UH source follows. Regenerated the CONUS store and the shipped bundle in contract order. Values are unchanged: volume on a sample day matches the source exactly, the Juniata four-cell mean is 163.0 m³/s as before, and the example still trains to NSE 0.795 against the summed baseline's 0.594.

The benchmark read Qr positionally. _aggregate_qprime used shape[1] as the time length, correct only because the source store happens to be in contract order. Reading now goes through qprime_matrix, which selects and transposes by dimension name and refuses a variable whose dimensions match neither layout. Two tests cover it. Also removed a _t0 parameter threaded into _route_and_score that was never read.

Verified behaviour-preserving by re-running the CONUS benchmark end to end: median NSE 0.5872 against the baseline's 0.4375, beating it at 84.7% of 321 gauges, negative solves 0.0488% — identical to the numbers in #194.

Not changed, worth a decision

• scripts/summed_q_prime.py reads Qr positionally in two places. It is the production MERIT path rather than gridded work, and it is correct for contract-order stores, but it would hit the same trap on a transposed one.
• The gridded benchmark still builds forcing by flowline-midpoint assignment while training uses the area-weighted store, so the two measure with different inflow. About 40% of catchments straddle a cell edge.
• The methods doc's limitations section records the two open modelling problems from Gridded (ISIMIP DDM30) routing: network, attributes, forcing, and training #194: roughness initialising at the midpoint of its bounds and pressing the ceiling after 45 epochs, and downstream hydraulic-geometry exponents that come out backwards. Neither is addressed here.

811 tests pass, 2 skipped.