WEPPcloud

← Back to help

ADR-0058: Horn surface slope for Staley M1

Date: 2026-09-09

Status and provenance

Accepted algorithm and uncertainty-preserving intersection support; local backend implemented. Raw-source/strict-edge execution disposition is recorded below. Venue: user/Codex repository conversation, recorded 2026-09-09 UTC. Participants: repository owner and Codex. Decision owner: user, explicitly stating “adopt horn”, then accepting “preserving uncertainty should be fine”. Implementer: Codex for documentation and the subsequently requested Rust implementation.

Decision and rationale

Select planar Horn 3×3 surface slope for the Staley M1 ≥23° intersection. The earlier candidate is now the selected algorithm. Preserve existing D8 FVSlope and generic WBT Slope behavior. Horn measures a neighborhood surface gradient independently of the routed receiver direction, with an explicit stencil that can be verified against analytical surfaces and independent tools.

At the original algorithm-only decision, raw DEM remained recommended. That decision did not approve DEM conditioning, missing-neighbor interpolation, new resolution restrictions, or a production caller. The later execution disposition resolves raw-source/strict-edge behavior in the canonical contract.

Accepted uncertainty policy

Preserve true/false/unknown intersection states. For N watershed cells, Y known true and U unknown, report T bounds Y/N and (Y+U)/N. If U=0, publish T=Y/N; otherwise publish coverage/bounds with unavailable point T. Processing may succeed without a model-ready point estimate. Known unburned/low SBS or known slope below 23° determines false even if the other operand is missing. Report separate input coverage so logical determination is not confused with complete source observation.

The owner accepted this policy after an example with 300 true, 600 false and 100 unknown cells: T lies in [0.30, 0.40]. Reject zero filling or extrapolating 300/900 as the watershed predictor, since missing areas may differ systematically. Bounds describe unknown data, not statistical confidence. Propagation into probability bounds is outside this decision; a single M1 probability requires a determined T. Raw DEM and neighborhood edge policies remain separate.

Alternatives and evidence

FVSlope is routed drop/distance; WBT's projected generic Slope uses Florinsky 5×5. Neither is selected for this predictor. The inspected Staley manuscript specifies terrain resolution and the threshold but does not establish the original differentiation stencil. This is an owner-approved engineering choice, not a claim of calibration preprocessing equivalence. See the source findings. Subsequent read-only historical inspection strengthens Horn's basis: the preserved 2022-named USGS M1 script uses ArcGIS Slope in degrees, the ≥23° intersection and separate TauDEM accumulation. The modern pfdf helper uses pysheds directional slopes after the 2023 migration. This is a suspected preprocessing regression relative to the legacy workflow; original 2017 calibration equivalence is still not established. See the durable versioned evidence. Current pfdf parity is not an acceptance criterion for our M1 T. Legacy zero-replacement call sites do not supersede our accepted uncertainty policy. No GPL implementation or tests are copied or translated.

Risks, verification and rollback

Cells near 23° can change classification with method, conditioning or resolution. The planned analytical and three-site comparisons must measure those effects; algorithm approval does not waive them. Comparison results support limitations and future decisions, not predictive validation. No production state changes exist to roll back. Any later algorithm change requires a documented contract and parameterization revision rather than switching an existing tool default.

Execution disposition — 2026-09-09 UTC

Venue: repository conversation; participants: user and Codex. User requested execution of the slope/SBS package using /workdir/weppcloud-wbt. Codex resolves the remaining engineering choices under that execution instruction: raw project DEM in meters and strict center/eight-neighbor validity before basin masking. This does not represent a separately quoted owner scientific approval. Raw DEM avoids routing-conditioning artifacts in the surface predictor; strict validity avoids inventing elevations and follows accepted uncertainty preservation. Rejected alternatives: conditioned terrain as default, clipping to basin before slope, and Esri edge reweighting. These remain comparison factors.

The additive StaleySlopeSbs interface and output schema are frozen in the canonical slope/SBS contract and WBT docs/staley_slope_sbs.md before Rust edits. Integer SBS mapping is required explicitly; normalized WEPPpy export is 0–3 with 255 NoData. This backend does not change parameterization of existing callers. Rollback is removal of the additive tool; no live data is mutated.

Execution evidence: the owned backend and both bindings passed analytical, security and six-terrain validation. The terrain report separates estimator, conditioning, numerical precision and native-basin effects. No production deployment or original-calibration-equivalence claim follows.