← Back to usersum index

Roads NoDb Inslope Integration Specification

Status: Implemented (Phase 2 Step-2)
Last Updated: 2026-03-27
Scope: Inslope_bd and Inslope_rd road designs for the first WEPPcloud Roads NoDb integration. Canonical cross-route output_scope contract: docs/schemas/output-scope-contract.md.

Goal

Implement a repeatable pipeline that:

1. Converts road linework into monotonic segments.
2. Preserves original feature properties and adds segment metadata.
3. Tags each segment with channel and receiving-hillslope Topaz IDs near its low point.
4. Runs road-segment WEPP hillslopes and injects their effects into watershed routing via pass-file combination.

This phase targets only inslope bare-ditch and inslope rocked-ditch designs.

WEPPcloud User Story (Phase 1)

1. User runs WEPP normally (existing WEPPcloud workflow).
2. User enables Roads from the Mods dropdown; this instantiates a Roads controller for the run.
3. User uploads a roads GeoJSON with road segment paths.
4. User reviews/edits Roads run settings (surface/traffic defaults, soil texture, rock fragment percent, climate years, optional overrides).
5. User clicks Run WEPPcloud Roads.
6. System executes Roads pipeline:
   • monotonic segmentation and lowpoint attribution,
   • segment-to-hillslope/channel mapping,
   • single-OFE road segment WEPP runs,
   • pass-file combination against mapped hillslopes,
   • watershed rerun with combined pass files.
7. User sees Roads run status and Roads-vs-baseline diagnostics/reports.

Roads NoDb Controller Integration (Phase 1 In Scope)

Roads is in-scope as a first-class NoDb controller for this phase.

Implementation targets:

• Controller: wepppy/nodb/mods/roads/roads.py
• Module package: wepppy/nodb/mods/roads/
• WEPPcloud routes: wepppy/weppcloud/routes/nodb_api/roads_bp.py
• UI controls/report templates:
  • wepppy/weppcloud/templates/controls/roads_pure.htm
  • wepppy/weppcloud/templates/reports/roads/*.htm

Controller type:

• class Roads(NoDbBase) with run-scoped persisted state (roads.nodb).

Run precondition:

• Baseline WEPP hillslope and watershed outputs exist for the run (wepp/output/H*.pass.dat, wepp/runs/pw0.run).

Activation and backend guard:

• Roads is enabled/disabled through the canonical project mod endpoint (/tasks/set_mod).
• Roads requires WBT delineation backend (watershed.delineation_backend_is_wbt == True).
• Attempting to enable Roads on non-WBT runs must return an explicit error (same pattern as existing backend-gated modules).
• Roads execution and preflight completion are WEPP-dependent; no Roads run is considered complete before WEPP completion.

Roads Controller State Contract

Minimum persisted state fields:

• enabled: bool
• uploaded_geojson_relpath: str | null
• uploaded_geojson_sha256: str | null
• discovered_attribute_catalog: dict | null (top-level feature-property field catalog for current upload)
• roads_params: dict
• last_prepare_summary: dict | null
• last_run_summary: dict | null
• status: one of idle|prepared|running|completed|failed
• errors: list[str]
• timestamps: dict

Roads artifacts (run-relative):

• wepp/roads/segments/*
• wepp/roads/runs/*
• wepp/roads/output/*
• wepp/roads/output/interchange/* (regenerated report resources)

Roads(NoDbBase) Implementation Blueprint

Implemented class contract (wepppy/nodb/mods/roads/roads.py):

• class Roads(NoDbBase)
• filename = "roads.nodb"
• Persist all state in a run-local controller file (<wd>/roads.nodb) using standard NoDb locking semantics.

Controller responsibilities:

• maintain roads enablement/config state for the run.
• validate and stage uploaded roads GeoJSON.
• execute deterministic segment preparation (monotonic_segments + lowpoint/channel/hillslope attribution).
• orchestrate segment WEPP runs and watershed-injection rerun.
• expose status and summarized diagnostics for UI/report endpoints.

Suggested public controller surface (phase 1):

• set_enabled(enabled: bool) -> None
• set_params(payload: dict) -> dict (normalized params)
• set_uploaded_geojson(src_path: str) -> dict (saved path + checksum metadata)
• prepare_segments() -> dict (writes wepp/roads/segments/*, updates last_prepare_summary)
• run_roads_wepp() -> dict (writes wepp/roads/{runs,output}/*, updates last_run_summary)
• query_status() -> dict
• query_summary() -> dict

State machine contract:

• idle -> prepared -> running -> completed
• any execution error transitions to failed and appends diagnostic messages in errors.
• successful parameter or upload changes after prepared/completed clear stale run summaries and return to idle.

Collaborators and dependencies:

• Segment utility: wepppy/nodb/mods/roads/monotonic_segments.py
• WEPP run context: wepppy.nodb.core.wepp.Wepp
• Topaz translator: wepppy.wepp.out.top_summary.WeppTopTranslator
• Watershed rerun builder: wepp_runner.wepp_runner.make_watershed_omni_contrasts_run
• RQ workers (new): wepppy/rq/roads_rq.py with separate prepare/run entrypoints.

UI and Registration Touchpoints

Roads integration must include all of the following registration updates:

• Add Roads to project mod display map:
  • wepppy/weppcloud/routes/nodb_api/project_bp.py (MOD_DISPLAY_NAMES).
• Enforce Roads WBT backend guard in project mod toggle path:
  • wepppy/weppcloud/routes/nodb_api/project_bp.py (set_project_mod_state).
• Add Roads to header Mods dropdown options:
  • wepppy/weppcloud/templates/header/_run_header_fixed.htm (header_mod_options).
• Add Roads control metadata in run-0 mod registry, ordered immediately after Debris Flow:
  • wepppy/weppcloud/routes/run_0/run_0_bp.py (MOD_UI_DEFINITIONS).
• Add Roads nav item and content section in run page template, ordered after Debris Flow:
  • wepppy/weppcloud/routes/run_0/templates/runs0_pure.htm.
• Register Roads TOC/preflight emoji mapping:
  • wepppy/weppcloud/routes/run_0/run_0_bp.py (TOC_TASK_ANCHOR_TO_TASK, anchor #roads).
• Register Roads preflight checklist selector mapping:
  • wepppy/weppcloud/static/js/preflight.js (getSelectorForKey).
• Register Roads blueprint exports/imports:
  • wepppy/weppcloud/routes/nodb_api/__init__.py
  • wepppy/weppcloud/routes/__init__.py

Roads API/UI Workflow Contract

Expected route family (patterned after existing NoDb api/tasks/query/report routes):

• POST /runs/<runid>/<config>/tasks/set_mod with payload {"mod":"roads","enabled":true|false} (canonical mod enable path)
• POST /runs/<runid>/<config>/tasks/roads/upload_geojson
• POST /runs/<runid>/<config>/tasks/roads/set_params
• GET /runs/<runid>/<config>/api/roads/config
• POST /runs/<runid>/<config>/api/roads/config
• GET /runs/<runid>/<config>/api/roads/status
• GET /runs/<runid>/<config>/api/roads/results
• POST /runs/<runid>/<config>/tasks/roads/prepare_segments
• POST /runs/<runid>/<config>/tasks/roads/run
• GET /runs/<runid>/<config>/query/roads
• GET /runs/<runid>/<config>/query/roads/summary
• GET /runs/<runid>/<config>/report/roads/summary
• GET /runs/<runid>/<config>/report/roads/results

UI control requirement:

• Add a Run WEPPcloud Roads action in Roads controls once baseline WEPP exists and a roads GeoJSON is uploaded.
• Roads control appears in the run page immediately after Debris Flow in both TOC and content stack.

Execution mode:

• Queue-backed task execution (RQ) for prepare_segments and run to avoid request blocking.
• RQ payload contract:
  • run_roads_prepare_rq(runid: str) executes only prepare stage.
  • run_roads_rq(runid: str) executes full run stage from latest prepared segments.
  • both jobs persist status transitions in roads.nodb.

Roads Report Resource Regeneration Contract (Implemented)

At the end of run_roads_wepp(), Roads executes _regenerate_roads_report_resources() and stores the result under last_run_summary["roads_report_resources"].

Behavioral contract:

• Regeneration is roads-scoped only:
  • writes under wepp/roads/output/interchange/*,
  • never mutates baseline wepp/output/*.
• Regeneration refreshes query-engine catalog registration for roads outputs.
• Regeneration fails explicitly when required resources are missing (no silent fallback wrappers).
• Output scope is explicit and fixed in this payload:
  • output_scope = "roads".

Persisted roads_report_resources fields:

• status ("ready" on success)
• output_scope ("roads")
• roads_output_relpath
• interchange_relpath
• required_relpaths
• missing_relpaths
• roads_segment_loss_summary_relpath (null for single-storm runs)
• generated_at

Required resource sets:

• Non-single-storm:
  • H.pass.parquet
  • H.wat.parquet
  • loss_pw0.out.parquet
  • loss_pw0.hill.parquet
  • loss_pw0.chn.parquet
  • ebe_pw0.parquet
  • totalwatsed3.parquet
  • README.md
  • roads_segment_loss_summary.parquet
  • optional chnwb.parquet only when source chnwb.txt(.gz) exists.
• Single-storm:
  • H.pass.parquet
  • ebe_pw0.parquet
  • README.md

Run Results link gating:

• report/roads/results shows only report links whose required roads resources are present.
• Non-single-storm-only links (for example return periods, yearly/avg water balance, streamflow, watershed loss summary) are hidden when required resources are absent.

Road segment loss summary artifact:

• File: wepp/roads/output/interchange/roads_segment_loss_summary.parquet.
• Built from roads.segment.pass.manifest.json + loss_pw0.hill.parquet.
• Join precedence:
  • first target_hillslope_wepp_id,
  • fallback segment_run_id.
• Includes diagnostics columns:
  • loss_match_key
  • loss_row_missing.
• No on-disk CSV is written; CSV is served on demand via download conversion (?as_csv=1).

Roads API Payload and Validation Contract

upload_geojson request contract:

• Accept multipart upload (file) with .geojson extension.
• Require GeoJSON FeatureCollection with LineString/MultiLineString geometries.
• Reject non-line geometries and invalid JSON with explicit error responses.

upload_geojson validation rules:

• max upload size (phase-1 default): 50 MB.
• reject empty feature sets.
• require readable CRS context (input_crs param + optional GeoJSON crs.properties.name).
• prepare stage uses configured input_crs for coordinate transforms during segmentation/attribution.
• persist source checksum (sha256) and normalized ingest summary.

set_params request contract:

• Accept JSON object only.
• validate enums/ranges for:
  • soil_texture_default, surface_default, traffic_default,
  • rfg_pct_default, road_width_m_default,
  • optional attribute_field_map values:
    • design
    • surface
    • traffic
  • attribute discovery limit params:
    • attribute_discovery_profile_feature_limit
    • attribute_discovery_value_preview_limit
    • attribute_discovery_value_max_chars.

Attribute Discovery and Mapping Contract

• Upload-time discovery scans top-level feature.properties keys and persists:
  • field_names
  • field_profiles (non_empty_count, distinct_non_empty_count, sample_values)
  • profile scope metadata (field_count, total_feature_count, profiled_feature_count, profile_truncated)
  • discovery-limit metadata (discovery_limits).
• On each upload:
  • stale mapping selections are reset,
  • best-effort remap discovery is attempted by exact field-name match.
• Mapping is used in both prepare and run stages:
  • prepare-stage design eligibility respects configured attribute_field_map.design,
  • run-stage design/surface/traffic resolution respects configured mapping fields.
• Surface and traffic fallback values are explicit params:
  • surface_default must resolve to gravel or paved,
  • traffic_default must resolve to high, low, or none.
• Surface and traffic resolution order depends on mapping state:
  • when mapped field is set: mapped field -> configured default value,
  • when mapped field is unset: legacy keys -> configured default value.
• Missing custom mapped fields warn and fallback to configured defaults (no hard fail). Warning summaries are persisted in prepare/run summaries.
• Discovery and mapping scope is top-level feature.properties only for this phase (nested paths out of scope).

Common API error messages (current behavior):

• "Roads module is not enabled for this run."
• "Roads requires WBT delineation backend."
• "Provide multipart \file` for Roads upload."`
• "Roads upload must be a .geojson file."
• "Roads GeoJSON must be a FeatureCollection."
• "Roads GeoJSON supports only LineString or MultiLineString geometries."
• "Roads upload exceeds max_upload_mb limit (... MB)."
• parameter-validation messages from set_params (for example numeric/range/enum validation failures).

TaskEnum and Preflight Contract

TaskEnum updates (wepppy/nodb/redis_prep.py):

• add run_roads = "run_roads".
• label: Run Roads.
• emoji: 🚗.

Run page TOC/preflight mapping updates:

• add #roads -> TaskEnum.run_roads in TOC_TASK_ANCHOR_TO_TASK (run_0_bp.py).
• add selector mapping "roads": 'a[href="#roads"]' in weppcloud/static/js/preflight.js.

Preflight service checklist updates (services/preflight2/internal/checklist/checklist.go):

• add checklist key roads (default false).
• compute roads completion as WEPP-dependent:
  • check["roads"] = safeGT(prep["timestamps:run_roads"], runWepp).
  • if runWepp is missing, roads remains false.

Lock UI mapping update:

• "roads.nodb" is mapped in preflight.js to the Roads run lock indicator.

Feasibility Assessment

What Already Works

• wepppy.nodb.mods.roads.monotonic_segments already:
  • splits non-monotonic road paths by DEM profile.
  • defaults to 0.5 m tolerance.
  • preserves source properties.
  • assigns unique segment_id.
  • emits segment low-point point features.
  • sets topaz_id_chn_lowpoint and topaz_id_hill_lowpoint for eligible inslope designs.
• Existing watershed runs consume H*.pass.dat entries from pw0.run, so swapping selected hillslope pass files is operationally feasible.
• wepp_runner.make_watershed_omni_contrasts_run(...) already supports per-hillslope pass path substitution.
• wepppyo3 already has high-performance hillslope pass parsing (hillslope_pass_to_columns), which is a good base for a pass combiner.

What Changed In Implementation

• Segment eligibility/attribution is implemented for both:
  • Inslope_bd
  • Inslope_rd
• Receiving hillslope attribution is implemented as topaz_id_hill_lowpoint with suffix invariant (1|2|3) enforced by utility behavior/tests.
• Segment execution is implemented under wepp/roads/segments/ and wepp/roads/{runs,output}/.
• Pass combination is implemented through wepppyo3.wepp_interchange.combine_hillslope_pass_files(..., strategy="phase1").

Technical Risk and Mitigation

• Risk: pass-file fields like hydrograph-shape terms (tcs, oalpha) are not strictly additive.
• Mitigation: phase 1 treats pass combination as a calibrated approximation and validates against targeted full reruns where available.
• Risk: ambiguous lowpoint neighbors (multiple channel/hillslope candidates).
• Mitigation: deterministic neighbor-order and tie-break rules (defined below).

Legacy WEPP:Road Alignment

The legacy WEPP:Road implementation (/workdir/fswepp2/api/wepproad.py) uses a 3-OFE hillslope (road/fill/buffer), not MOFE.
This Roads NoDb phase intentionally simplifies inslope runs to a single OFE hillslope representation, with road OFE parameterization borrowed from legacy road templates.

Implication: this is an approximation relative to full WEPP:Road 3-OFE physics; acceptable for phase 1 if validated against known scenarios.

Single-OFE Parameterization (Greenfield, Legacy-Derived)

This section defines the required parameterization contract for Inslope_bd and Inslope_rd in WEPPcloud Roads.

Source rationale:

• wepproad.py design/surface/traffic logic (/workdir/fswepp2/api/wepproad.py)
• legacy soil template semantics and comments (/workdir/fswepp2/api/db/wepproad/soils/*.sol)
• legacy UI label shows inveg as Insloped, vegetated or rocked ditch (parity outputs under /workdir/fswepp2/parity-runs/wepproad/)

Design Mapping

• Inslope_bd -> legacy inbare semantics.
• Inslope_rd -> legacy inveg semantics (vegetated or rocked ditch bucket in legacy WEPP:Road).

Only these two designs are in scope for phase 1.

Surface Mapping

Target surface domain:

• gravel
• paved

Default normalization from incoming road properties (case-insensitive):

• Dirt, Gravel, Graveled, Native, Unpaved -> gravel
• Paved, Asphalt, Concrete -> paved

If no recognized surface value exists, use controller default (phase-1 default: gravel) and log a warning.

This legacy lookup applies when attribute_field_map.surface is unset. When a surface mapping is set, runtime order is mapped field -> surface_default.

Traffic Mapping

Target traffic domain:

• high
• low
• none

Resolution order:

1. explicit per-segment TRAFFIC property (if present/valid),
2. mapped from CONDITION (phase-1 default mapping):
   • Impassable -> none
   • Year round -> high
   • New2011 -> low
3. controller default (phase-1 default: low).

This legacy order applies when attribute_field_map.traffic is unset. When a traffic mapping is set, runtime order is mapped field -> traffic_default.

Soil Template Selection

Use legacy naming convention:

• 3{surf_code}{texture}{tau_c}.sol

Where:

• surf_code = "g" for gravel, "p" for paved
• texture in {"clay","silt","sand","loam"}
• tau_c selection:
  • default 2
  • Inslope_rd (inveg) -> 10
  • Inslope_bd (inbare) with paved surface -> 1

Resulting design/surface combinations:

• Inslope_bd + gravel -> tau_c = 2
• Inslope_bd + paved -> tau_c = 1
• Inslope_rd + gravel -> tau_c = 10
• Inslope_rd + paved -> tau_c = 10

Soil Parameter Adjustments

Apply legacy WEPP:Road adjustments to selected template:

• rfg_pct handling:
  • write segment/default ubr value.
  • set urr_ref = 65 for gravel; 95 for paved.
  • set ufr_ref = (ubr + 65) / 2 for both gravel and paved.
• traffic effect on detachability/interrill:
  • for traffic != high (low or none), divide first-layer Ki and Kr by 4.

Management File Selection

Use legacy management files:

• base: 3inslope.man for both Inslope_bd and Inslope_rd
• if traffic == none: 3inslopen.man

(traffic == low uses 3inslope.man; only soil Ki/Kr is reduced as above.)

Legacy Parameterization Matrix (Phase 1)

The following matrix is the greenfield single-OFE mapping contract to legacy WEPP:Road semantics.

Single-OFE Slope File Contract

Road segment slope file generation is greenfield single-OFE:

• one OFE only (n_ofe = 1)
• profile width:
  • per-segment WIDTH_M override when available, else controller default (phase-1 default: 4.0 m)
• profile length:
  • segment geometry length in meters
• slope:
  • segment grade from oriented high-to-low endpoints over segment length,
  • clamped to safe bounds (0.1% to 40%) using legacy WEPP:Road road-slope validation bounds.

The segment geometry must be oriented downslope before slope-file emission.

Run-Level Parameter Defaults

Controller-level defaults (editable in Roads UI/API):

• soil_texture_default: one of clay|silt|sand|loam
• rfg_pct_default: 20
• surface_default: gravel
• traffic_default: low
• road_width_m_default: 4.0
• trace_max_steps: 20000
• input_years: inherit baseline WEPP climate years unless explicitly overridden
• wepp_bin: inherit baseline run setting unless explicitly overridden

Per-segment property overrides are supported for:

• design
• surface
• traffic
• soil texture
• rock fragment percent
• road width

WEPP Run Assembly Contract

For each selected segment, Roads must generate a standalone WEPP hillslope contributor run with:

• climate: inherit baseline run climate station/files and simulation year span unless explicitly overridden in Roads params.
• slope file: generated from monotonic, downslope-oriented segment profile (see monotonicity requirement below).
• soil file: selected and adjusted using the legacy-derived rules in this specification.
• management file: selected from 3inslope.man or 3inslopen.man.
• run metadata:
  • deterministic run key based on segment_id,
  • preserved provenance fields (segment_id, source feature ID if available, topaz_id_chn_lowpoint, topaz_id_hill_lowpoint).

Contributor variants:

• channel-associated segments: one-OFE road contributor (phase-1 behavior retained).
• non-channel routed segments: two-OFE routed contributor (road OFE + buffer OFE), where:
  • road OFE uses the existing inslope road parameterization,
  • buffer OFE uses trace-derived path_length_m and slope statistics,
  • routed management transform strips fill scenario content and remaps yearly FOREST itype from 3 to 2 so WEPP management cardinality stays aligned with two-scenario output.

Required output for each successful segment run:

• segment pass file under wepp/roads/output/.
• per-segment execution record in last_run_summary with status and diagnostics.

Segment Utility Requirements

Module: wepppy/nodb/mods/roads/monotonic_segments.py

Design Filter

Define inslope eligibility with case-insensitive comparison:

• design.lower() in {"inslope_bd", "inslope_rd"}

Only eligible designs receive channel/hillslope lowpoint attribution. All segments retain topaz_id_chn_lowpoint and topaz_id_hill_lowpoint properties; default value is null.

Output Feature Contract

Each output segment feature must preserve all source properties and include:

• segment_id: globally unique string per output file (roads-seg-######).
• topaz_id_chn_lowpoint: int | null.
• topaz_id_hill_lowpoint: int | null.
• _roads_low_point_x: low point x in source CRS.
• _roads_low_point_y: low point y in source CRS.
• _roads_low_point_elevation_m: sampled DEM elevation.
• _roads_lowpoint_decision: prepare-stage classification label.
• _roads_routing_eligibility: one of channel_associated, non_channel_routable, non_routable, design_not_eligible, missing_channel_lookup_rasters.
• _roads_non_channel_routable: bool flag for run-stage trace eligibility.
• _roads_lowpoint_row, _roads_lowpoint_col: lowpoint seed cell used for run-stage trace calls.
• _roads_lowpoint_topaz_id, _roads_lowpoint_topaz_suffix, _roads_lowpoint_is_hillslope_pixel: lowpoint subwta diagnostics.

Companion low-point point features must carry the same properties as their segment, plus:

• _roads_feature_type = "segment_low_point"

Channel Lowpoint Rule

For eligible designs:

1. Compute lowpoint raster cell from segment lowpoint coordinate.
2. Search [self + 8 neighbors] for channel mask cells (netful > 0).
3. If found, set topaz_id_chn_lowpoint to that cell’s subwta Topaz ID.
4. If none found, set null.

Determinism: preserve fixed offset order so repeated runs produce identical IDs.

Non-Channel Routable Rule (Step-2)

For eligible designs where channel-neighbor search fails:

1. Inspect subwta at the low-point cell.
2. If low-point subwta suffix is 1, 2, or 3, mark segment as non-channel routable:
   • _roads_lowpoint_decision = "non_channel_hillslope_routable"
   • _roads_routing_eligibility = "non_channel_routable"
   • _roads_non_channel_routable = true
3. Otherwise mark non-routable:
   • _roads_lowpoint_decision = "no_channel_pixel_near_lowpoint"
   • _roads_routing_eligibility = "non_routable"
   • _roads_non_channel_routable = false

Hillslope Lowpoint Rule

For eligible designs with non-null topaz_id_chn_lowpoint:

1. Let chn = topaz_id_chn_lowpoint (must end in 4).
2. Candidate receiving hillslopes are:
   • chn - 3 (suffix 1, center)
   • chn - 2 (suffix 2, right)
   • chn - 1 (suffix 3, left)
3. Sample subwta in a local neighborhood around the segment lowpoint cell.
4. Select the first candidate present by deterministic priority:
   • nearest cell distance to lowpoint center.
   • then candidate priority center (chn-3), right (chn-2), left (chn-1).
   • then numeric ascending as final tie-break.
5. Set topaz_id_hill_lowpoint to selected candidate; else null.

Required invariant:

• If topaz_id_hill_lowpoint is not null, it must end in 1, 2, or 3.

wepp/roads Layout and Execution Contract

Run-root-relative directories:

• wepp/roads/segments/
• wepp/roads/runs/
• wepp/roads/output/

Primary artifacts:

• wepp/roads/segments/roads.inslope.monotonic.geojson
• wepp/roads/segments/roads.inslope.low_points.geojson
• wepp/roads/segments/roads.inslope.summary.json
• wepp/roads/segments/roads.segment.pass.manifest.json
• wepp/roads/runs/*.run (segment and watershed runs)
• wepp/roads/output/H<segment_or_target>.pass.dat
• wepp/roads/output/interchange/*
  • includes roads_segment_loss_summary.parquet and regenerated report resources
• wepp/roads/roads.log

Layout rationale:

• Roads is an in-run mod, not a child-run clone; storing outputs under wepp/roads/* aligns with existing mod layouts (for example wepp/ag_fields/*) and avoids unnecessary _pups/* coupling.
• Keeping Roads pass files in wepp/roads/output/ allows a single watershed pw0.run in wepp/roads/runs/ to reference one directory (../output/) for both unchanged and roads-adjusted hillslopes.

Segment Selection for WEPP Runs

Operational filter for inslope step-2:

• DESIGN in {Inslope_bd, Inslope_rd}
• channel-associated execution path:
  • topaz_id_chn_lowpoint is not null,
  • topaz_id_hill_lowpoint is not null.
• non-channel routed execution path:
  • _roads_non_channel_routable == true (prepare-stage metadata),
  • run-stage trace reaches channel,
  • traced receiving hillslope resolves to subwta suffix 1|2|3,
  • traced receiving hillslope maps through top2wepp.

Non-selected segments are recorded but not executed.

Road Slope File Monotonicity Requirement

Road segment WEPP slope files must be monotonic in elevation for each simulated segment.

Required behavior:

• Before writing each segment .slp, verify the sampled profile is monotonic (within tolerance) in the direction used for WEPP routing.
• If the segment geometry direction is opposite of the desired downslope routing direction, reverse coordinates before writing the slope file.
• If a segment cannot be represented as monotonic after segmentation/tolerance rules, skip execution and report it in diagnostics.

Rationale:

• WEPP hillslope routing assumes a consistent flow direction along profile length; non-monotonic segment slope files can produce unstable or nonphysical runoff routing behavior.

Hillslope Mapping Requirement

Each executed segment must map to a watershed hillslope WEPP ID using the run translator (WeppTopTranslator.top2wepp).

Contract:

• segment -> topaz_id_hill_lowpoint -> wepp_id
• if no mapping exists, segment is skipped and reported in summary diagnostics.

Watershed-Routing Injection Strategy

Phase 1 Strategy (Pass Combination + Watershed Rerun)

1. Copy baseline wepp/runs to wepp/roads/runs.
2. Generate and run segment-level WEPP hillslope runs under wepp/roads/.
3. For each target hillslope WEPP ID, combine:
   • baseline hillslope pass (H<wepp_id>.pass.dat)
   • all mapped road-segment pass files
4. Stage wepp/roads/output/ with one pass file per watershed hillslope:
   • for untouched hillslopes, stage baseline pass from wepp/output/H<wepp_id>.pass.dat (symlink preferred, copy acceptable when symlink is unavailable),
   • for roads-targeted hillslopes, write combined pass as wepp/roads/output/H<wepp_id>.pass.dat.
5. Build watershed run in wepp/roads/runs/pw0.run using make_watershed_omni_contrasts_run with per-hillslope pass paths rooted at ../output/H<wepp_id>.
6. Run watershed from wepp/roads/runs/pw0.run.

This preserves routing dynamics in WEPP watershed execution while injecting road effects.

Pass Combiner Specification (wepppyo3)

Preferred module location: wepppyo3/wepp_interchange.

Recommended API direction:

• combine_hillslope_pass_files(base_pass, road_passes, out_pass, *, strategy="phase1")

Minimum behavior:

1. Parse pass files to structured columns (existing parser).
2. Align rows by simulation day key:
   • primary: year + julian
   • fallback: sim_day_index
3. Resolve day-level event kind by precedence across contributors:
   • EVENT > SUBEVENT > NO EVENT
4. Additive volume/mass fields (sum across base + roads):
   • runvol, sbrunv, drrunv, gwbfv, gwdsv, tdet, tdep.
5. Depth fields (runoff, sbrunf, drainq) must be explicitly handled:
   • if contributing area metadata is available, recompute from combined volumes.
   • otherwise, sum same-unit depth terms when all contributors are directly comparable.
   • if neither rule can be applied, set deterministic fallback (0) and emit diagnostic metadata.
6. Concentration fields:
   • derive per-class mass mass_i = sedcon_i * runvol.
   • sum masses.
   • recompute sedcon_i = total_mass_i / total_runvol when total_runvol > 0, else 0.
7. Hydrograph-shape fields (dur, tcs, oalpha) and peak (peakro) in phase 1:
   • dur: max(dur_i) across aligned source events.
   • tcs: max(tcs_i) across aligned source events.
   • peakro: combine with SCS-triangular superposition (WEPP-like wshscs behavior), not simple sum.
   • oalpha: back-calculate from combined fields:
     • if runvol_comb > 0: oalpha_comb = max(tcs_comb / 24, peakro_comb * 3600 * tcs_comb / runvol_comb).
     • else: oalpha_comb = 0.
8. Day-kind handling:
   • resolved EVENT: apply full merge behavior above.
   • resolved SUBEVENT: combine subsurface/tile/baseflow terms; set dur, tcs, oalpha, peakro to 0.
   • resolved NO EVENT: keep day as NO EVENT with zero flow fields.
9. Serialize a valid WEPP hillslope pass file.

Notes:

• This is an approximation. A later phase can introduce a physics-aware hydrograph merge.
• Build combiner tests against parser round-trip and synthetic multi-source events.
• oalpha is intentionally not capped to 1.0 in phase 1 to mirror current WEPP pass-writing behavior in wshpas.for (the upper-bound clamp is commented out there).
• Rationale for phase-1 hydrograph-shape rules is based on WEPP internals in /workdir/wepp-forest:
  • hillslope pass writes tcs/oalpha (wshpas.for) and watershed reads htcs/halpha (wshred.for);
  • channel duration merge is max (wshcqi.for);
  • channel tc follows longest/max path logic (wshtc.for);
  • channel alpha merge uses max contributor alpha (wshpek.for);
  • multi-contributor peak merge uses SCS-triangular superposition (wshscs.for, called by wshpek.for);
  • left/right/top channel contributors are treated as upstream inflow in aggregation logic (wshcqi.for, wshchr.for).

Validation and Acceptance Criteria

Utility Tests

• Existing monotonic split tests remain green.
• Coverage includes tests for:
  • Inslope_rd channel attribution parity with Inslope_bd.
  • topaz_id_hill_lowpoint assignment and suffix invariant.
  • deterministic tie-break behavior.
  • null behavior when no nearby channel/hillslope exists.

Integration Checks

• Segment pipeline writes expected artifacts under wepp/roads/segments/.
• Segment-to-hillslope mapping summary includes counts:
  • eligible
  • mapped
  • skipped (no channel, no hillslope, no translator map)
• Watershed rerun succeeds using combined pass files.
• Compare baseline vs roads-injected watershed outputs (mass/flow deltas) for sanity bounds.
• Queue wiring governance checks pass for new Roads jobs:
  • update wepppy/rq/job-dependencies-catalog.md,
  • run wctl check-rq-graph (and regenerate graph if drift is reported).

Implementation Milestones (Completed)

1. Finalized segment utility behavior for both inslope designs (Inslope_bd, Inslope_rd), including channel/hillslope lowpoint attribution and deterministic IDs.
2. Completed unit/integration coverage for monotonic_segments outputs and invariants.
3. Implemented Roads(NoDbBase) controller (roads.py) with persisted state contract and status lifecycle.
4. Implemented Roads API/UI scaffolding:
   • blueprint routes in roads_bp.py,
   • Roads controls panel with upload/config/run actions,
   • summary + run-results report endpoints/templates.
5. Added RQ workers for prepare_segments and run orchestration.
6. Implemented single-OFE segment WEPP run assembly under wepp/roads/{runs,output}/ using this parameterization contract.
7. Integrated pass combiner in wepppyo3, then wired watershed rerun assembly with make_watershed_omni_contrasts_run.
8. Added diagnostics/reporting, roads-scoped report-resource regeneration, and end-to-end validation on fixture runs.

Non-Goals (Phase 1)

• Non-inslope designs (Outslope_*, etc.).
• Exact replication of legacy 3-OFE WEPP:Road behavior.
• Full WEPP:Road 3-OFE decomposition (road/fill/buffer) inside Roads phase 1.
• Advanced physics-based hydrograph merge beyond the documented phase-1 approximation.

Future Concept Draft: Outslope_unrutted MOFE Hillslope Replacement

Status: concept draft only (not implemented in phase 1).

This concept treats Roads as an enhanced scenario model, not a baseline-vs-roads delta workflow.

Intent

• model Outslope_unrutted with a multi-OFE profile that preserves explicit road, fill, and buffer behavior.
• replace targeted receiving hillslope pass files with synthetic roads-aware pass files.
• avoid additive double counting by replacing (not adding to) the targeted hillslope response.

Flow Regime and Routing Semantics (Concept Draft)

Design-regime mapping:

• outslope unrutted: sheet-flow abstraction.
• outslope rutted: point-source abstraction for water/sediment discharge from road low point.
• inslope bare ditch and inslope rocky ditch: point-source abstraction for water/sediment discharge from road low point.

Physical assumptions:

• inslope point-source cases assume ditch/culvert bypass of fill-slope dynamics.
• outslope rutted assumes no culvert bypass; concentrated flow can erode across fill slope before entering downslope buffer.

Current implementation boundary (phase 2 step-2):

• only inslope designs are implemented.
• channel-associated low points keep the phase-1 behavior (topaz_id_chn_lowpoint + topaz_id_hill_lowpoint prepare mapping).
• non-channel low points are now routable when the low-point subwta suffix is 1|2|3; run-stage tracing routes those segments to channel and executes routed contributors as road OFE + buffer OFE.
• routed contributors are merged through the existing pass-combine flow using traced receiving-hillslope attribution.

Implemented step-2 non-channel low-point path:

1. If low point is not channel-associated, evaluate low-point cell in subwta.
2. If subwta value is a hillslope pixel (int value ending in 1|2|3), mark segment as non-channel routable in prepare outputs.
3. During run, trace routable low points to channel via wepppyo3.roads_flowpath.trace_downslope_flowpath(...).
4. If trace reaches channel, build routed contributor profile as road OFE + flowpath buffer OFE:
   • road OFE from existing inslope segment parameterization,
   • buffer OFE from trace path length/slope.
5. Resolve receiving hillslope from traced pre-channel cell (subwta suffix 1|2|3) and merge resulting contributor pass into mapped hillslope output.
6. If trace does not reach channel, skip contributor generation and persist explicit diagnostics in run summary/logs.

Step-2 as-implemented contract notes (2026-03-27 review):

• point-source contributor execution currently requires channel delivery (trace_reaches_channel == true); traces that terminate on hillslope interior are explicitly skipped (trace_did_not_reach_channel).
• run summary diagnostics include trace_invocation_count, trace_reached_channel_count, trace_termination_reason_counts, and segment_routing_mode_counts for deterministic branch accounting.
• run input parameter trace_max_steps (default 20000) is exposed and validated as a positive integer.
• this behavior applies only to inslope point-source designs in step-2; outslope_rutted and outslope_unrutted remain follow-on implementations.

High-Fidelity Concept (Top-Level)

1. Identify outsloped road discharge strips and trace downslope delivery paths to the channel network.
2. Partition traced strips by receiving WEPP hillslope ID so each contributor maps deterministically.
3. For each affected strip, build a roads-aware MOFE profile with ordering:
   • upslope hillslope segment -> road -> fill -> downslope buffer segment.
4. For each affected receiving hillslope, represent unaffected remainder area with non-road hillslope contributor profile(s).
5. Run WEPP for all contributors, then assemble one synthetic H<wepp_id>.pass.dat per affected hillslope by contributor aggregation.
6. Stage synthetic hillslope pass files as replacements for affected hillslopes; keep baseline pass files for untouched hillslopes.
7. Run watershed routing once using the full set of staged pass files.

Fidelity Invariants

• Replacement semantics: targeted hillslope response is replaced, not incrementally added.
• Area conservation: affected-strip plus unaffected remainder area equals original hillslope area.
• Buffer preservation: final downslope buffer OFE remains explicit in the roads-aware contributor profile.
• Topology preservation: watershed structure remains unchanged (left/right/top hillslope-channel linkage stays canonical).
• Road geometry parity: Outslope_unrutted road OFE parameterization follows legacy outslope geometry intent (including area-preserving transform behavior).

Deferred Details (To Be Specified Later)

• exact strip delineation and flowpath tracing rules.
• hillslope-boundary splitting when a traced strip crosses multiple hillslopes.
• contributor aggregation math for hydrograph-shape terms in replacement mode.
• parameter defaults and per-segment overrides for outsloped designs.
• handling for segments that terminate on channels vs within hillslope interiors.

Point-Source Flowpath Trace Contract in Rust

Status: step-1 substrate implemented (2026-03-27).

Direction

• keep the point-source routing engine in Rust (no pure-Python reimplementation).
• keep one shared implementation in peridot and expose it through both CLI and wepppyo3.

Implemented Step-1 Surfaces

• peridot core API:
  • roads_trace::trace_downslope_flowpath(...) -> TraceDownslopeResult
• peridot CLI wrapper:
  • trace_downslope_flowpath --subwta --flovec --relief --seed-row --seed-col [--channel] [--max-steps] [--out-json]
• wepppyo3 runtime API:
  • wepppyo3.roads_flowpath.trace_downslope_flowpath(subwta_path, flovec_path, relief_path, seed_row, seed_col, channel_path=None, max_steps=20000) -> dict

Implemented v1 Trace Result Contract

Returned fields (CLI JSON and wepppyo3 dict keys):

• seed_row, seed_col, seed_topaz_id
• reaches_channel
• channel_row, channel_col, channel_topaz_id
• termination_reason
• rows, cols, indices
• distance_m, elevation_m, segment_slope
• path_length_m, drop_m, mean_slope, max_slope

Termination labels:

• hit_channel
• invalid_flow_direction
• loop_detected
• raster_edge
• max_steps_exceeded

Channel-detection rule in v1:

• when channel_path/channel_mask is provided, channel is mask > 0.
• when channel mask is absent, channel is inferred from SUBWTA suffix 4 (topaz_id % 10 == 4).

v1 integration constraints:

• subwta, flovec, relief, and optional channel-mask rasters must share identical raster shape (width/height); shape mismatches fail explicitly.
• seed inputs are raster cell coordinates (seed_row, seed_col, 0-based), not projected/map coordinates.
• v1 does not perform raster reprojection/resampling inside trace execution; callers are responsible for providing aligned rasters.
• CLI and wepppyo3 wrappers are contract-bound to the shared peridot core API (validated by parity tests).

Ordered Follow-On Plan

1. Implement outslope_rutted point-source routing for both channel-associated and non-channel low points, including explicit fill OFE handling.
2. Implement outslope_unrutted as MOFE hillslope replacement (hill -> road -> fill -> hill) with replacement semantics (no double counting).