[taddyb]

Adds a gridded routing path to DDR: build a river network from the ISIMIP DDM30 0.5° drainage-direction grid, aggregate the attributes it needs from native rasters, regrid the forcing onto it, and train the KAN on it at Juniata and CONUS scale.

The routing engine, mmc.py, merit.py and the MERIT/Lynker paths are untouched. Everything here is additive.

What's in it

Engine (ddr_engine.gridded)

• attributes.py — 0.5° cell polygons, extractrs coverage-weighted zonal means onto cells (reprojecting cells into each raster's CRS), in-memory extraction for derived rasters, cell areas, and a cell-table → lat/lon grid scatter
• terrain.py, climate.py — slope from a DEM using its own pixel size, FAO-56 extraterrestrial radiation, Hargreaves PET, Walsh & Lawler seasonality, snowfall fraction, aridity with a precipitation floor
• forcing.py — catchment→cell area weights and mass-conserving redistribution of per-catchment Q′
• subdivide.py — split cells into sub-reaches so Muskingum-Cunge runs near Courant 1
• validate.py — flow-direction, unit-range, coverage and consistency checks

Scripts — acquisition (acquire_merit_hydro.py, acquire_gee_attributes.py), builders (build_gridded_attributes.py, build_gridded_qprime.py, build_subdivided_adjacency.py), and validate_gridded.py

Examples — examples/juniata_gridded/, a self-contained sample mirroring examples/juniata. Ships a 1.6 MB bundle, so the whole thing runs with no external stores:

uv run python examples/juniata_gridded/train_gridded.py --epochs 30
uv run python examples/juniata_gridded/eval_plots.py --run examples/juniata_gridded/runs/latest

CONUS training and eval-plot scripts alongside it, mirroring the ddrs eval-plot families.

Docs — docs/gridded_data.md walks from nothing to a built store: Earth Engine setup, DDM30 download, the raster acquisition script, direct downloads (SoilGrids, WorldClim, GLHYMPS, MERIT catchments), building the attribute and forcing stores, gauge snapping, validation, and the data gotchas. This previously lived only in wiki/, which is gitignored and so never reached users.

Data products (on /mnt/ssd1, not in git)

Product	Contents
ddm30_conus_attributes.{nc,ic} + _grid.nc	25 attributes × 5,198 CONUS cells; NetCDF keyed on COMID (the merit_global_attributes_v2 layout, so ddr and ddrs read it unchanged), icechunk keyed on divide_id, plus the 280×720 ISIMIP grid
ddm30_global_attributes.*	the same for all 67,424 cells of the ISIMIP grid
ddm30_conus_uh_retrospective_regridded.ic	dHBV2 UH Q′ area-weighted onto cells, 4,085 cells × 14,976 days
ddm30_subreach_adjacency.zarr	91,867 Courant-1 sub-reaches

Attributes come from native rasters only. Q′ is volumetric per catchment, so moving it to cells is mass-conserving aggregation, verified to 8e-8; ~40% of catchments straddle a cell edge, which the previous flowline-midpoint assignment mishandled.

Results

Fixed-parameter benchmark, 321 gauges, WY1996: routed median NSE 0.587 against 0.437 for the summed-Q′ baseline.

Trained, Juniata (27 sub-reaches, 30 epochs): routed NSE 0.795 / KGE 0.737 against summed 0.594 / 0.671, zero negative solves.

Trained, CONUS (620 gauges, 45 epochs): median NSE 0.542 against summed 0.390, beating the baseline at 81% of gauges, NSE > 0.5 at 336.

Validation suite: 67 checks passing on the CONUS store.

Findings worth review

Sub-reach splitting fixes conditioning but not daily skill. At 0.5° with dt = 3600 s the Cunge X saturates at its 0.5 cap, so c₁ is negative in ~88% of states. Splitting to Courant ≈ 1 drops negative solves 10× but leaves paired ΔNSE at −0.0002 across 321 gauges. The implicit solve was already absorbing them, and mass conservation is guaranteed by c₁+c₂+c₃ = 1 and c₄ = c₁+c₂. Courant 1 is nonetheless the default, on the argument that a well-conditioned operator should give cleaner gradients for training; that specific claim is not yet measured.

Three quarters of gages_3000 cannot be represented at 0.5°. 2,416 of 3,211 gauges drain less than one cell (~2,350 km²). Training uses the 620 above 2,000 km² that snap within drainage-area tolerance.

Parameter medians converge, but their spreads saturate against the bounds. An untrained KAN emits sigmoid ≈ 0.5, which denormalizes to the midpoint of n's [0.02, 0.2] bounds, i.e. 0.111 — a floodplain roughness, not a channel one. Over 45 epochs the median rises to 0.145 by epoch 17 then settles at 0.127, but the 10–90 spread grows the entire run to 0.05–0.19, pressing the ceiling; q reaches 0.93 against a maximum of 1.0. The extra 33 epochs bought 0.017 NSE for 3.2 hours. Worth deciding whether to narrow the bounds or bias the output layer so training starts somewhere physical.

Channel geometry is not sensible and longer training makes it worse. Downstream exponents are width b = −0.09 (Leopold & Maddock ≈ 0.5) and depth f = 0.75 (≈ 0.4) at 45 epochs, against b = 0.08 at 12 — so larger rivers are now made slightly narrower, which is backwards. Width-to-depth falls below 10 above roughly 4,000 km². Nothing in an L1-on-daily-flow objective rewards physical channel shape, so p and q drift wherever they help the hydrograph. p_spatial's log-space range of [1, 200] is the first suspect.

Notes

• 35 commits, merged up to master (Juniata single-catchment sample: self-contained bundle, train/test module, physics notebook #193); 809 tests pass, 2 skipped
• MERIT Hydro cannot serve the global grid (17,238 cells sit north of 60°N), so elevation and slope come from GMTED2010, matching the paper's USGS-DEM lineage
• The plan this follows is in wiki/plan-gridded-juniata.md (wiki is gitignored). Its open question about the juniata-sample branch is resolved: Juniata single-catchment sample: self-contained bundle, train/test module, physics notebook #193 merged it, and examples/juniata_gridded/ now sits alongside examples/juniata/ rather than duplicating its scaffolding