WEPPcloud

← Back to help

ADR-0003: RUSLE observed_rap Surface-Rock Partition for C

Status: Accepted
Date: 2026-05-27
Review Date: 2027-05-27

Context

The current RUSLE observed_rap implementation computes C directly from RAP bare-ground percent:

  • fg = clamp(100 - bare_ground_pct, 0, 100)
  • C = exp(-0.04 * fg)

In rocky landscapes, RAP bare includes both exposed mineral soil and exposed rock. RUSLE2 guidance treats surface rock as protective ground cover in C, while profile coarse fragments are handled in K logic.

Without a separate surface-rock term, observed_rap can overstate exposed-soil fraction on armored hillslopes.

Decision

Add a user-facing observed_rap parameter:

  • rock_fraction_of_rap_bare in [0, 1]

Use it to partition RAP bare into exposed-soil and protective-rock fractions:

  • bare_rap = clamp(bare_ground_pct / 100, 0, 1)
  • r_bare = clamp(rock_fraction_of_rap_bare, 0, 1)
  • bare_exposed = bare_rap * (1 - r_bare)
  • fg = 100 * (1 - bare_exposed)
  • C = exp(-0.04 * fg)

Provide an auto convenience default with source precedence:

  • first from run-scoped SSURGO cosurffrags proxy columns in soils/soils.parquet (cosurffrags_cover_pct, surface_rock_cover_pct, surface_rock_cover_percent, sfragcov) aggregated across the run footprint as a total-surface-rock proxy (surface_rock_cover_proxy_0_1)
  • fallback to top-horizon cfvo (surface_rock_cover_proxy_0_1 = clamp(cfvo_0_5cm_volpct / 100, 0, 1))
  • final fallback to 0.0

Convert proxy total-surface cover into the control domain (fraction of RAP bare interpreted as rock):

  • rock_fraction_of_rap_bare_default = clamp(surface_rock_cover_proxy_0_1 / bare_rap_mean_0_1, 0, 1) when bare_rap_mean_0_1 > 0
  • rock_fraction_of_rap_bare_default = 0.0 when bare_rap_mean_0_1 <= 0
  • Multiplying by bare_rap_mean_0_1 is intentionally rejected because it shifts the parameter into total-area space instead of fraction-of-bare space.

The auto value is explicitly documented as a proxy prior, not canonical surface-rock truth.

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:

  • observed_rap had no explicit surface-rock partition control.
  • RAP bare was treated as exposed bare for fg calculation.

New behavior:

  • observed_rap includes rock_fraction_of_rap_bare user control.
  • fg now reflects overlap-consistent rock partitioning of RAP bare.
  • auto default populates from SSURGO cosurffrags when available, with fallback to top-horizon cfvo.

Rationale

  • Aligns with canonical RUSLE2 guidance: surface rock affects C (cover), not K.
  • Preserves explicit user control where no robust spatial surface-rock raster exists.
  • Keeps profile-fragment effects in K while avoiding double counting.
  • Uses a surface-fragment dataset (cosurffrags) as primary proxy rather than profile volumetric fragments (cfvo) for the C-factor surface-cover path.

Alternatives Considered

  1. Keep RAP bare unchanged and rely only on K profile-fragment adjustment - Rejected. This mis-buckets protective surface armor into the profile-permeability path.
  2. Require field-entered surface-rock cover only, with no default - Rejected. Scientifically strongest but operationally brittle for current run workflows.
  3. Derive hard spatial surface-rock map automatically - Rejected for now. No defensible run-scoped data source is currently available in this stack.

Consequences

  • Positive:
    • Better directional behavior on stony, exposed hillslopes.
    • Clearer separation of surface-rock (C) vs profile-fragment (K) effects.
    • Explicit uncertainty labeling for proxy defaults.
  • Risks:
    • auto defaults are still uncertain proxies; cosurffrags and cfvo can both misestimate true site-observed surface rock cover if not overridden.

Evidence

Risk and Rollback Notes

  • Monitor sensitivity of A to rock_fraction_of_rap_bare (0.0, auto, and field-informed values).
  • If proxy defaults produce unstable or implausible behavior, rollback path is:
    • keep user control,
    • disable auto,
    • require explicit user entry or 0.0 default until better surface data is available.

Implementation Notes

  • This ADR records the specification-level contract and defaulting policy.
  • Runtime/controller implementation must emit manifest provenance for the effective rock-partition value and source (user vs auto).