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 example82.0.WeppPrepService.prep_managements(...)passed that value intomanagement.set_cancov(...), producing generated.manfiles withcancov=82.00000.
New behavior:
RAP_TS.get_cover(...)sums the same percent-scale RAP vegetation bands and returnssum / 100.0, for example0.82.- The generated WEPP management initial condition receives
cancovin the expected0..1fraction 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
- 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.
- 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. - Leave behavior unchanged - rejected because generated
.manfiles can carry impossible canopy-cover fractions such as82.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.00000in thecancovposition. - RAP_TS parquet for the same run stores percent-scale values under
/wc1/runs/pr/praetorian-talcum/rap/rap_ts.parquet. - WEPP source documents
icancoas 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.