WEPPcloud

← Back to help

ADR-0010: RAP_TS Management Cover Fraction Normalization

Status: Accepted Date: 2026-06-26

Context

RAP band summaries are stored in RAP's native percent scale (0..100). The RAP_TS management-prep path used RAP_TS.get_cover(...) to sum annual grass, perennial grass, shrub, and tree cover, then passed that value directly to Management.set_cancov(...).

Generated WEPP management files require canopy cover (cancov) as a fraction (0..1). The run /wc1/runs/pr/praetorian-talcum/wepp/runs/p6.man exposed the bug: its initial condition line contained 82.00000 for cancov, where the intended canopy cover was 0.82.

The existing single-year RAP landuse path already divides RAP band summaries by 100.0 before assigning cancov. RAP_TS management preparation needs the same unit boundary.

Decision

RAP_TS.get_cover(topaz_id, year, fallback=True) will return a WEPP management canopy-cover fraction by dividing the percent-scale vegetation-band sum by 100.0.

Raw RAP_TS data, including RAP_TS.data and <wd>/rap/rap_ts.parquet, remains percent-scale. This preserves source-product provenance, existing analytics, and compatibility with callers that inspect raw RAP band summaries.

This ADR covers the RAP_TS management-file cancov path. It does not change the separate RAP_TS.prep_cover(...) .cov time-series export contract.

Decision Provenance (Required for Parameterization Changes)

Decision Venue: Codex task from operator report, 2026-06-26 America/Los_Angeles Participants Present: WEPPcloud operator/user, Codex coding agent Decision Owner(s): WEPPcloud operator/user Implementer(s): Codex coding agent

Change Summary

Old behavior:

  • RAP_TS.get_cover(...) summed percent-scale RAP vegetation bands and returned the raw sum, for example 82.0.
  • WeppPrepService.prep_managements(...) passed that value into management.set_cancov(...), producing generated .man files with cancov=82.00000.

New behavior:

  • RAP_TS.get_cover(...) sums the same percent-scale RAP vegetation bands and returns sum / 100.0, for example 0.82.
  • The generated WEPP management initial condition receives cancov in the expected 0..1 fraction range.

Rationale

WEPP documents canopy cover as a fraction (0..1) in both initial-condition state and output headers. Passing percent-scale RAP values into cancov overstates cover by a factor of 100 and can make unburned RAP_TS runs behave like fully covered hillslopes regardless of the actual vegetation state.

Normalizing in RAP_TS.get_cover(...) puts the conversion at the boundary where RAP_TS changes from raw RAP data access to management-cover parameterization. It also keeps RAP_TS consistent with the single-year RAP landuse path.

Alternatives Considered

  1. Normalize RAP_TS parquet/data during analysis - rejected because the parquet is a raw RAP summary artifact and downstream analytics expect percent-scale band values.
  2. Normalize inside WeppPrepService.prep_managements(...) - rejected because the service only needs a WEPP-ready canopy-cover value; putting the unit conversion in the RAP_TS accessor keeps the unit contract local to RAP_TS.
  3. Leave behavior unchanged - rejected because generated .man files can carry impossible canopy-cover fractions such as 82.00000.

Consequences

RAP_TS scenarios that rebuild management files after this change will have lower, physically valid canopy-cover inputs wherever RAP_TS cover overrides are applied to undisturbed forest, deciduous forest, mixed forest, shrub, or tall grass hillslopes.

Previously generated runs are unchanged until their management files are rebuilt.

Evidence

  • Reported run artifact: /wc1/runs/pr/praetorian-talcum/wepp/runs/p6.man
  • In the reported artifact, the initial-condition line includes 82.00000 in the cancov position.
  • RAP_TS parquet for the same run stores percent-scale values under /wc1/runs/pr/praetorian-talcum/rap/rap_ts.parquet.
  • WEPP source documents icanco as canopy cover at end of simulation (0-1) in /workdir/wepp-forest/src/cincon.inc.
  • WEPP output headers document Canopy cover (0-1) in /workdir/wepp-forest/src/bighdr.for.
  • Regression tests: tests/nodb/mods/test_rap_ts_cover_transform.py::test_get_cover_returns_wepp_fraction_from_percent_scale_rap_bands. tests/wepp/test_wepp_prep_managements_rap_ts.py::test_prep_managements_rap_ts_only_updates_undisturbed_classes.

Risk and Rollback Notes

Risk: RAP_TS runs rebuilt after this change can produce different runoff and sediment because canopy cover is no longer inflated by percent-scale values. That is the intended correction.

Rollback: revert the RAP_TS.get_cover(...) division by 100.0 and this ADR. Use rollback only if follow-up validation shows the management-file writer expects percent-scale cancov, which would contradict WEPP's documented 0..1 contract.

Implementation Notes

The implementation deliberately leaves raw RAP_TS storage untouched. The unit conversion happens only in RAP_TS.get_cover(...), which is the accessor used by the management-generation path that writes .man cancov.