ADR-0014: Disturbed openWEPP Route Coefficients
Status: Accepted
Date: 2026-07-07
Context
openWEPP Lane-D active routing requires five static route coefficients in
native ow-lanuse-1 management files. The preceding openWEPP D16 route
coefficient bridge held because selected Disturbed-produced management files
were legacy 98.4 files and carried no authoritative
routing_coefficients extension.
WEPPpy Disturbed owns the disturbed class, burn severity, soil texture, and management-file parameterization harness for the affected workflows. It is therefore the producer boundary for class-specific native openWEPP routing inputs.
Decision
Add explicit openWEPP Lane-D route coefficient defaults to the Disturbed
extended lookup table and use the management-file API to produce native
ow-lanuse-1 files only when the caller explicitly selects native openWEPP
routing output.
The values are operator-calibrated, texture-invariant class defaults. They are not inferred from legacy WEPP row spacing, ridge spacing, random roughness, residue, cover, or other legacy cropland fields.
Decision Provenance
Decision Venue: Codex work-package execution chat, 2026-07-07, America/Los_Angeles
Participants Present: WEPPcloud/openWEPP operator, Codex
Decision Owner(s): WEPPcloud/openWEPP operator
Implementer(s): Codex
Change Summary
Old behavior:
- Disturbed extended lookup rows carried soil, PMET, initial-condition, and plant fields, but no static openWEPP route coefficient fields.
- Disturbed management outputs remained legacy WEPP management files by default.
New additive behavior:
- The extended lookup table carries five route coefficient columns and four
provenance columns:
route_skin_friction_coefficient_koroute_form_drag_coefficientroute_roughness_element_height_mroute_roughness_concentrationroute_vegetation_drag_coefficientroute_coeff_source_refroute_coeff_authority_classroute_coeff_confidenceroute_coeff_notes
route_coeff_authority_classisoperator_calibration.route_coeff_confidenceisbounded_class_calibration.route_coeff_notesrecordstexture_invariantand the effective route class.- Native output uses
Management.as_openwepp_native_cropland(...), which emitsow-lanuse-1,landuse=4native cropland records, and arouting_coefficientsblock after each plant record. - Legacy output is unchanged unless native output is explicitly selected.
Active class values are ordered as k_o, form C_d, D_r in meters,
lambda, vegetation C_d.
| Disturbed class | Values |
|---|---|
| agriculture crops | 480.0, 0.25, 0.010, 0.050, 0.12 |
| bare | 540.0, 0.00, 0.000, 0.000, 0.00 |
| deciduous forest | 420.0, 0.90, 0.050, 0.180, 0.65 |
| forest | 410.0, 0.95, 0.060, 0.200, 0.75 |
| forest high sev fire | 530.0, 0.18, 0.006, 0.018, 0.08 |
| forest low sev fire | 465.0, 0.58, 0.026, 0.085, 0.34 |
| forest moderate sev fire | 490.0, 0.40, 0.016, 0.050, 0.20 |
| forest prescribed fire | 450.0, 0.70, 0.035, 0.110, 0.45 |
| grass high sev fire | 530.0, 0.08, 0.003, 0.010, 0.04 |
| grass low sev fire | 475.0, 0.27, 0.010, 0.045, 0.15 |
| grass moderate sev fire | 500.0, 0.18, 0.007, 0.026, 0.09 |
| grass prescribed fire | 465.0, 0.32, 0.012, 0.055, 0.18 |
| high use skid | 575.0, 0.03, 0.000, 0.000, 0.00 |
| low or treated skid | 545.0, 0.12, 0.006, 0.020, 0.03 |
| mixed forest | 415.0, 0.92, 0.055, 0.190, 0.70 |
| mulch | 420.0, 0.85, 0.040, 0.180, 0.20 |
| short grass | 460.0, 0.34, 0.014, 0.070, 0.24 |
| shrub | 430.0, 0.72, 0.035, 0.120, 0.45 |
| shrub high sev fire | 525.0, 0.14, 0.004, 0.014, 0.06 |
| shrub low sev fire | 465.0, 0.44, 0.020, 0.065, 0.24 |
| shrub moderate sev fire | 490.0, 0.30, 0.012, 0.038, 0.14 |
| shrub prescribed fire | 450.0, 0.55, 0.026, 0.090, 0.32 |
| skid | 560.0, 0.05, 0.000, 0.000, 0.00 |
| tall grass | 440.0, 0.48, 0.020, 0.100, 0.35 |
| thinning | 435.0, 0.90, 0.045, 0.160, 0.50 |
| young forest | 430.0, 0.85, 0.045, 0.160, 0.60 |
Rationale
This creates an explicit source-authorized input surface for openWEPP Lane-D routing without depending on a hidden or mechanical mapping from unrelated legacy management fields. The class ordering follows Disturbed semantics: undisturbed vegetated classes carry stronger roughness and vegetation terms, high-severity burned classes carry reduced vegetation and roughness protection, and bare/skid classes carry no vegetation drag.
The initial values are texture-invariant because no source in this work package authorizes texture-specific gradients for these surface-routing coefficients. Soil texture remains available in the row key for future measured or literature-backed refinement.
Alternatives Considered
- Infer values from legacy WEPP row/ridge/random roughness/cover fields - rejected because openWEPP authority explicitly disallows a hidden bridge.
- Use the H2637 timing recipe
500.0 0.0 0.0 0.0 0.0for every lane - rejected because it is a timing harness value, not a Disturbed cohort production policy. - Hold for measured per-site values - rejected for this source-acquisition increment because the operator accepted an explicit bounded calibration table, and the schema records provenance/confidence for later replacement.
Consequences
Disturbed can now be the canonical producer of native ow-lanuse-1 management
files for the active Disturbed class table at the current mesh. The values are
reviewable and replaceable because they live in a single module and table with
provenance columns.
The main limitation is that these are class defaults, not measured site data. Future packages may replace any class with measured or literature-range values without changing the management-file API.
Evidence
- Work package:
/home/workdir/openWEPP/docs/work-packages/20260707-laned-router-d16-hybrid-disturbed-route-coeff-source-acquisition-001/ - Implementation:
wepppy/nodb/mods/disturbed/route_coefficients.py - Static table:
wepppy/nodb/mods/disturbed/data/extended_land_soil_lookup.csv - Focused tests:
tests/disturbed/test_route_coefficients.pytests/test_managements_module.py
Risk and Rollback Notes
Risks:
- Class defaults may need recalibration after D16 cohort sensitivity evidence.
- Native forest
landuse=3is not implemented in WEPPpy management parsing; current Disturbed native production uses native croplandlanduse=4over the existing cropland-grammar templates.
Rollback:
- Revert the route coefficient module, static CSV columns, and Disturbed extended-table enrichment.
- Native output is opt-in, so legacy WEPP management generation can continue without runtime migration if the new producer is disabled.
Implementation Notes
managements.py is the canonical native management parser/writer surface.
Disturbed supplies lookup-row coefficients and calls
Management.as_openwepp_native_cropland(...) when native openWEPP output is
requested. WEPP prep honors the opt-in
disturbed.openwepp_native_managements_enabled flag and writes native
pN.man files only when that flag is true.