Skip to content

CS-028 advanced roadway overtopping handoff

Date: 2026-09-14

This branch implements the code-facing scope of GitHub issues #4 and #14 without claiming broader engineering validation or release readiness beyond the supported roadway methods.

Implemented

  • Added typed irregular roadway crest geometry using station/elevation points and a piecewise-linear profile.
  • Added a roadway profile weir that retains the existing explicit SI discharge coefficient contract instead of silently selecting a coefficient.
  • Integrated irregular profiles with four-point Gaussian quadrature between adjacent station/elevation coordinates, following the FHWA HY8 roadway-profile procedure.
  • Added paved and gravel downstream-submergence correction using source-traceable digital ordinates identified by EPA SWMM as derived from FHWA/RD-86/108 Figure 10.
  • Pinned the EPA SWMM roadway digitisation reference to release commit 65e8435e094bc7c10b83d230dc2829cd5031938b rather than a mutable branch URL.
  • Bounded the implemented submergence relationship to a local downstream/upstream head ratio of 0.99. Ratios between 0.99 and equal stage fail closed rather than extrapolating or using the nonzero digitised equal-stage ordinate; exactly equal water levels return zero roadway flow.
  • Bounded crossing headwater bracketing to the same supported roadway-submergence domain. A requested crossing discharge below the minimum evaluable submerged-roadway capacity fails with an explicit applicability error rather than entering the unsupported gap.
  • Kept submerged cases fail-closed when no supported roadway surface is supplied, and rejected reverse roadway flow rather than extrapolating the correction.
  • Preserved per-integration-segment geometry, local heads, flow contribution, effective coefficient, correction factor, and source provenance in public result objects.
  • Added downstream-consumable roadway segment state for issue #14: local unit discharge, machine-readable inactive/free/submerged state, direct submergence ratio/factor access, and an explicit physical interval length distinct from Gaussian effective length.
  • Deliberately omitted critical depth, critical velocity, specific energy, Froude number, shear, momentum, and protection-design values where their applicability is not established.
  • Updated crossing configuration and common-headwater solving so irregular and supported submerged roadway flow participates in the same culvert/roadway conservation equation.
  • Added focused regression tests for constant/profile equivalence, sag-profile segment summation, paved submergence, equal-stage zero flow, unsupported near-equal submergence, submerged crossing bracketing, fixed-tailwater crossing conservation, a discharge-dependent tailwater forward/inverse round trip, and the issue #14 public roadway-state properties.
  • Updated public input/result/built-in API documentation, hydraulic-basis documentation, MkDocs navigation, and exports.

Deliberate limits

  • The existing explicit user-supplied SI discharge coefficient remains authoritative. This increment does not digitise or automate HDS-5 roadway discharge-coefficient selection.
  • Only paved and gravel roadway submergence relationships are supported.
  • The digitised ratio-1.00 submergence ordinates are retained as source evidence but are not used by the solver because they imply nonzero static capacity at equal water levels.
  • The range 0.99 < downstream_head / upstream_head < 1.00 is unsupported and fails closed.
  • Reverse roadway flow is not implemented.
  • No extrapolation is permitted beyond the supported submergence-ratio endpoint.
  • HY-8 executable comparison has not been run for the new roadway cases. Such comparison is optional validation evidence and must not be used to tune the FHWA method to an executable.

Verification evidence

GitHub Actions Python CI run #64 passed on the post-main branch head used to establish acceptance evidence. The run completed:

  • Ruff lint and Ruff format check;
  • strict Pyright with zero errors;
  • the full pytest suite: 398 passed;
  • Markdown lint;
  • mkdocs build --strict, including this handoff page in nav;
  • patch-whitespace checks;
  • wheel build/verification; and
  • installed-wheel and vendored-wheel smoke tests on Windows, macOS, and Ubuntu with Python 3.14.

The final documentation-only handoff commit must also retain a green CI result before merge.

Status

The implementation and acceptance criteria for GitHub issues #4 and #14 are complete on this branch, subject to the final documentation-only CI confirmation noted above. GitHub issues remain the authoritative live task records; merge of PR #13 should close those issues after the final branch checks remain green.