Skip to content

Floodway Check: Experimental Steady-Flow Diagnostics

RasCheck.check_floodways() compares two computed steady profiles and returns CheckResults.messages plus a per-section floodway_summary. It does not establish regulatory compliance or hydraulic acceptance. Supply profiles from the same model with compatible discharge, geometry, units, and boundary assumptions. The current checker assumes feet; it does not convert SI results.

Qualification and coverage

The floodway authoring and check workflow is experimental. Notebook 223 was withdrawn from the example gallery pending qualification. Its historical outputs are not evidence that the complete workflow is correct. The API remains available for development on disposable copies, with these known limitations:

  • RasFloodway.parse_encroachments() preserves blank eight-character fields, including the three Method 4 targets in official Example 6 plan 02. Native opt-in native regression tests cover that record and Method 5 plan 01; malformed numeric fields or methods raise ValueError with the node and line context. This parsing repair does not qualify trial authoring or computed hydraulic behavior.
  • The checker reads paired Encroachment Station Left and Encroachment Station Right arrays under Additional Variables, selecting the exact profile and using result-owned section identifiers. Read-only evidence covers the retained HEC-RAS 6.5 US Customary Example 6 HDF. Missing profiles, incomplete pairs, incompatible shapes, or missing result identifiers produce a logged diagnostic and no station table. NaN stations stay missing; other layouts and versions still require qualification.
  • That accessor does not supply an encr_method column. Method-specific diagnostics listed below are implemented branches, but their detection path is unqualified; they are skipped when the method is unknown. FW_EM_04 reports missing station results without inferring an authored method. Absence of method messages does not confirm method suitability.
  • Station-based width and structure screening now receives the retained HDF's station arrays. FW_WD_05 transition screening is disabled because no qualified longitudinal spacing and coordinate contract is supplied; river-station labels (including river miles and interpolated identifiers) are not used as distances.
  • Missing results, missing profile names, unsupported datasets, and some helper failures can return empty or partial results. There is no complete coverage receipt. Verify the summary is populated and contains every expected section.
  • HEC-RAS writes no steady encroachment or boundary-condition input to the plan HDF. FW_BC_* read the steady flow file (.f##) and the encroachment parameters read the plan file (.p##) through RasSteady and RasFloodway. Both files are found next to the plan HDF from its Plan Information Plan Filename/Flow Filename (file names matched case-insensitively); when either is absent these helpers return nothing. Profiles are matched by exact name against the flow file's Profile Names. No plan-file field for a Method 5 iteration limit is known, so FW_EM_08 does not run.
  • FW_LW_02 reads the steady lateral-structure results (Steady Profiles/Lateral Structures/<River> <Reach> <RS>/Structure Variables, checked on HEC-RAS 6.6 and 7.0.1 Baxter output).
  • Starting-WSE checks infer a downstream section by sorting station identifiers; they are screening heuristics for compatible subcritical reaches, not a general boundary-condition audit. Review station order and hydraulic regime explicitly.

The retained Example 6 HDF was inspected for two profiles and 24 steady result rows during the September 2026 review. No new solver run or successful authoring qualification is claimed by this repair. Restoring the notebook requires independent input-record readback, complete section/profile matching, fresh solver evidence, and review of WSE, energy, flow regime, and structure behavior. Keep source models immutable and retain both diagnostics and the actual executed notebook outputs. Native fixture tests require the retained files (or paths supplied through RAS_COMMANDER_FLOODWAY_EXAMPLES_ZIP and RAS_COMMANDER_FLOODWAY_HDF); they skip explicitly when those files are unavailable. They include public checker calls for the encroached profile and an unencroached missing-station control, plus an idempotent rewrite of native full-width station records. Parser rejection is checked before trial-flow expansion; this is not a general two-file transaction guarantee for other authoring failures.

Separate 2D authoring status

Notebook 311 was also withdrawn. Its RasEncroachments GIS authoring route is separate from the steady-flow parser above. The retained HEC-RAS 6.6 run reported completion booleans, but no native unsteady encroachment result arrays and zero maximum-WSE differences for all 13,093 compared rows. This evidence does not establish that the solver applied the authored regions/zones. The APIs remain available as experimental input-authoring helpers; file/layer readback and a completed base simulation do not qualify the hydraulic encroachment workflow.

HEC-RAS method reference

Method Input / meaning Review context
1 User-specified left and right encroachment stations Used for final refinement in USACE Example 6 after trial methods; use alone is not a warning
2 Fixed top width Review the resulting stations and hydraulic response
3 Specified percentage reduction in conveyance Review conveyance distribution and the resulting hydraulic response
4 Target increase in water surface elevation (WSE) Determines stations using conveyance at the raised WSE; computed rise may differ from the input target, so the user reviews successive trials
5 Target WSE increase plus maximum energy change Iterative search; review both targets, convergence, and computed WSE/energy changes

The method definitions follow the USACE Steady Flow Floodway Encroachment Analysis manual. The trial-to-final Method 1 sequence is demonstrated in USACE Floodway Determination, Example 6. In particular, Method 5 is not a width-reduction target. A Method 4 target is not itself a guaranteed computed surcharge. Method selection, target values, and acceptance criteria remain study-specific engineering decisions.

Configured thresholds

The public wrapper defaults to surcharge=1.0 ft. This is a software default, not a determination of the applicable limit. The legacy get_state_surcharge_limit() helper returns a stored lookup (for example, IL returns 0.1 and TX returns 1.0); those entries have not been audited against current state or local requirements. This page does not prescribe state limits. Obtain the study's governing criterion and record its source before running checks.

Several fields in ValidationThresholds.floodway are not wired into these predicates: surcharge_max_ft, surcharge_warning_percent, discharge_tolerance_percent, min_floodway_width_ft, and acceptable_encroachment_methods. Changing them does not change the corresponding hard-coded screening rules below. Use the explicit surcharge argument for the surcharge comparison. The starting-WSE difference thresholds are used.

Message reference

The following table records the IDs and severities constructed by the public checker's helpers, with predicates summarized from check_floodways.py. It is checked against the code and messages.py by a focused regression test. A listed branch does not imply that its required input was found or the branch ran. SC uses s = floodway WSE - base WSE and the explicitly supplied limit. All length/elevation thresholds in this table are in feet.

ID Severity Implemented condition / meaning
FW_SC_01 ERROR s > limit
FW_SC_02 WARNING s < -0.01; negative surcharge
FW_SC_03 INFO abs(s) < 0.005; near-zero surcharge
FW_SC_04 INFO s > 0 and abs(s - limit) < 0.01; includes either side of limit and can coexist with FW_SC_01
FW_Q_01 WARNING Absolute discharge difference exceeds 1% of a positive base discharge
FW_Q_02 WARNING Floodway discharge exceeds 1.01 times base discharge
FW_Q_03 WARNING Adjacent sorted-section discharge change exceeds both 2% of previous positive flow and 50 cfs; inspect tributaries and losses
FW_EM_01 INFO Method 1 detected; fixed stations are not inherently unsuitable
FW_EM_02 WARNING Method is zero and both encroachment stations are missing at a non-structure section
FW_EM_03 INFO Multiple positive methods detected within a reach
FW_EM_04 WARNING Both station results are missing at a non-structure section with unknown or zero method; does not establish absent authored encroachment
FW_EM_05 INFO Method 5 detected; targets are not verified by this message
FW_EM_06 WARNING Encroachment method detected at a structure; review treatment
FW_EM_07 WARNING Detected Method 4/5 inward encroachment distances beyond positive banks have an asymmetry ratio greater than 5:1
FW_EM_08 WARNING Method 5 is detected and a read iteration limit is below 10; heuristic, not observed nonconvergence
FW_WD_01 ERROR Right minus left encroachment station is zero or negative
FW_WD_02 WARNING Left encroachment is right of a positive left bank station
FW_WD_03 WARNING Right encroachment is left of a positive right bank station
FW_WD_04 WARNING Encroachment width is less than a positive channel width
FW_ST_01 WARNING Structure encroachment differs from adjacent section encroachment
FW_ST_02 ERROR Encroachment lies inside positive bridge abutment stations
FW_ST_03 WARNING Both encroachment stations are missing at a structure
FW_BC_01 INFO Floodway downstream Known WS differs from the base profile's Known WS on the same reach (value = floodway - base); Example 6 differs by design
FW_BC_02 INFO Base and floodway downstream boundaries are Normal Depth with the same slope
FW_BC_03 INFO Floodway downstream boundary is Known WS (value = that WS)
FW_SW_01 INFO Computed WSE reported at the inferred downstream section
FW_SW_02 WARNING Absolute base/floodway WSE difference exceeds starting_wse_diff_threshold_ft (default 0.5)
FW_SW_02M1 WARNING FW_SW_02 with Method 1 detected
FW_SW_02M4 WARNING FW_SW_02 with Method 4 detected; review trial results and boundary assumptions
FW_SW_02M5 WARNING FW_SW_02 with Method 5 detected; review both targets and boundary assumptions
FW_SW_03 ERROR Floodway WSE below the section minimum channel elevation
FW_SW_03M1 ERROR FW_SW_03 with Method 1 detected
FW_SW_03M4 ERROR FW_SW_03 with Method 4 detected
FW_SW_04 INFO Floodway WSE above the higher sampled bank elevation
FW_SW_04M1 INFO FW_SW_04 with Method 1 detected
FW_SW_04M4 INFO FW_SW_04 with Method 4 detected
FW_SW_05 WARNING Other profiles differ from floodway WSE beyond the starting-WSE threshold at the same section
FW_SW_05M1 WARNING FW_SW_05 with Method 1 detected
FW_SW_05M4 INFO FW_SW_05 with Method 4 detected
FW_SW_06 WARNING Computed Froude number is at least 1.0 at the inferred downstream section
FW_SW_07 ERROR Reported depth or WSE minus channel minimum is negative
FW_SW_08 WARNING Difference between base and floodway WSE drops over the first two sorted sections exceeds starting_wse_computed_diff_ft (default 1.0); does not compare against a specified boundary value
FW_LW_01 WARNING Lateral structure present in Geometry/Structures; activity requires result review
FW_LW_02 WARNING Steady Total Flow of a lateral structure exceeds 5% of its upstream river flow (Flow HW US) in the floodway profile

The checker also delegates permanent ineffective-flow screening to the structure checker (ST_IF_05). Additional FW_ST_* templates exist in messages.py, but the separate extended structure helper is not called by this public entry point. FW_DC_* and the formerly described asymmetric-width/discontinuity IDs were incorrect documentation, not emitted messages from this implementation.

Interpreting diagnostics

A negative surcharge can involve changes in losses, flow regime, boundary conditions, or numerical behavior; it is not automatic permission to narrow the floodway. Near-zero surcharge is likewise not a certificate of a conservative or acceptable result. Review the matched profiles and diagnostics together.

A higher floodway downstream WSE can be intentional. USACE Example 6 uses a one-foot higher floodway starting WSE to represent downstream encroachment. Therefore, a starting-WSE difference is a review flag; enforcing identical values would not reproduce that example. Review reach extent, downstream assumptions, structures, transitions, and the computed energy/WSE profiles.

Running the available checks

Python
from pathlib import Path
from ras_commander.check import RasCheck, create_custom_thresholds

# Replace with your HDFs and exact computed profile names.
plan_hdf = Path("working/model.p01.hdf")
geom_hdf = Path("working/model.g01.hdf")
review_limit_ft = 1.0  # Example configuration; establish the study criterion first.
thresholds = create_custom_thresholds({
    "floodway.starting_wse_diff_threshold_ft": 0.5,
})
results = RasCheck.check_floodways(
    plan_hdf, geom_hdf,
    base_profile="PF#1",
    floodway_profile="PF#2",
    surcharge=review_limit_ft,
    thresholds=thresholds,
)
if results.floodway_summary.empty:
    raise RuntimeError("No matched profile evidence; floodway review is incomplete")
print(results.floodway_summary)
for message in results.messages:
    print(message.message_id, message.severity.value, message.message)
# Independently compare expected section identities with the summary.
# Messages and populated rows do not establish complete check coverage.

The public RasCheck wrapper accepts surcharge. The lower-level CheckFloodways.check_floodways() and RasFloodway.check_floodways() accept surcharge_limit; use the keyword belonging to the called API.