ADR-0004: RUSLE scenario_sbs Surface-Rock Partition for C
Status: Accepted
Date: 2026-05-27
Review Date: 2027-05-27
Context
The current scenario_sbs pathway uses static severity lookup defaults for RUSLE
C and does not expose an explicit surface-rock partition control. In rocky
settings, this can treat lookup bare fractions as fully exposed erodible soil,
which overstates erosion where surface armor is substantial.
RUSLE2 guidance places surface rock in cover-management (C) logic, while
profile coarse fragments belong in soil erodibility/permeability (K) logic.
For scenario_sbs, this adjustment should not depend on RAP artifacts.
Decision
Add a user-facing scenario_sbs parameter:
rock_fraction_of_sbs_barein[0, 1]
Use it to partition lookup-derived SBS bare fraction:
fg_lookup = clamp(fg_lookup_pct / 100, 0, 1)bare_lookup = 1 - fg_lookupr_sbs_bare = clamp(rock_fraction_of_sbs_bare, 0, 1)bare_exposed = bare_lookup * (1 - r_sbs_bare)fg_effective_pct = 100 * (1 - bare_exposed)C = exp(-0.04 * fg_effective_pct)
Provide auto defaulting with proxy source precedence:
- first from run-scoped SSURGO
cosurffragsproxy columns insoils/soils.parquet - fallback to top-horizon
cfvo - final fallback to
0.0
Convert proxy total-surface cover into SBS control space (fraction of SBS bare):
rock_fraction_of_sbs_bare_default = clamp(surface_rock_cover_proxy_0_1 / bare_lookup_mean_0_1, 0, 1)whenbare_lookup_mean_0_1 > 0rock_fraction_of_sbs_bare_default = 0.0whenbare_lookup_mean_0_1 <= 0
The SBS rock adjustment is explicitly RAP-independent: no RAP raster retrieval
or RAP-year dependency is required for scenario_sbs.
Decision Provenance (Required for Parameterization Changes)
Decision Venue: Codex user request thread, 2026-05-27 PDT
Participants Present: User, Codex
Decision Owner(s): User / WEPPcloud operator request
Implementer(s): Codex
Change Summary
Old behavior:
scenario_sbshad no explicit surface-rock partition control.- Lookup bare implicitly behaved as exposed bare in SBS
Coutcomes.
New behavior:
scenario_sbsincludesrock_fraction_of_sbs_bare.- SBS lookup bare is partitioned into exposed-soil and protective-rock
components before
Ccalculation. autodefault usescosurffragsfirst, thencfvo, then0.0, normalized into SBS bare-fraction control space.
Rationale
- Aligns SBS with canonical RUSLE placement of surface rock in
C. - Improves directional realism on stony post-fire and disturbed landscapes.
- Keeps SBS contract independent from RAP-specific data dependencies.
- Reuses existing proxy hierarchy while preserving explicit user override.
Alternatives Considered
- Leave SBS unchanged and rely only on
Kprofile-rock effects - Rejected. This misses protective surface armor in theCpathway. - Reuse RAP-specific rock control in SBS mode - Rejected. This creates unnecessary RAP coupling for SBS workflows.
- Require field-entered rock fraction only (no
auto) - Rejected for now. Operationally too brittle where field measurements are unavailable.
Consequences
- Positive:
- More defensible SBS
Cbehavior in armored terrain. - Clear RAP-independent scenario contract.
- Provenance can distinguish user-entered versus proxy-derived defaults.
- More defensible SBS
- Risks:
autoremains a proxy prior and can misestimate local true surface rock.- Cross-layer contract updates are required (UI/API/runtime/tests).
Evidence
- Spec update:
wepppy/nodb/mods/rusle/specification.md. - Work package:
docs/work-packages/20260527_rusle_sbs_surface_rock_partition/package.md. - Existing related ADR for observed RAP mode:
docs/adrs/ADR-0003-rusle-observed-rap-surface-rock-partition.md.
Risk and Rollback Notes
- Monitor sensitivity with
rock_fraction_of_sbs_bare = 0.0,auto, and field-informed values. - If proxy defaults are unstable, rollback path is to keep the SBS control but
disable
autoand require explicit numeric entry.
Implementation Notes
- Manifest metadata should record effective SBS rock-fraction value and source
(
user,auto:cosurffrags,auto:cfvo, or fallback marker). - UI should explicitly warn users that
autois an estimate and field/local rock-cover verification is preferred.