Skip to content

verification.md

Latest commit

 

History

History
70 lines (54 loc) · 5.48 KB

verification.md

File metadata and controls

70 lines (54 loc) · 5.48 KB
Raw

Verification evidence

What was actually run, on which machine, with which outputs — and where the honest boundary is.

Environment

Item Value
HEC-RAS 7.0.1 (June 2026), HEC-RAS_701_with_Linux_Setup.exe from the official GitHub mirror HydrologicEngineeringCenter/hec-downloads (release 1.0.46), installed to a private folder (.local/HEC-RAS/7.0.1, git-ignored); the Linux engines (Linux/Linux/RasUnsteady, RasSteady, RasGeomPreprocess, run_helper.sh) are present but not used
Windows Windows 10 Pro 10.0.19045, x64
Python 3.13.1 venv, ras-commander 0.99.1, mcp 2.0.0, h5py 3.16, pandas 3.0.5, matplotlib 3.11.1, geopandas 1.1.4
Example data HEC's official Example_Projects_7_0.zip (release 1.0.45): 2D Unsteady Flow Hydraulics/Muncie (51.7 MB) and 1D Unsteady Flow Hydraulics/Balde Eagle Creek (6.8 MB)
Date 2026-08-16

1. Muncie: baseline vs +20 % upstream inflow (scripts/e2e_muncie.py)

Muncie = White River 1D reach (61 cross sections) + one 2D flow area ("2D Interior Area", 5765 cells), US customary units. Plan 03 "Unsteady Run with 2D 50ft Grid": 02JAN1900 00:00 - 03JAN1900 00:00, 10 s computation step, 5 min output.

Every step went through the MCP tool handlers (same code the server calls); numbers below are copied from the tool returns recorded in runs/muncie_demo/report.json.

Step Tool Result
inspect ras_project_info(project, plan="03") plans 01/03/04, upstream BC White/Muncie/15696.24 Flow Hydrograph, 65 values @ 1HOUR, peak 21 000 cfs; downstream 237.6455 Normal Depth
copy ras_project_copy x2 runs/muncie_demo/00_baseline, 00_scenario_q120
edit ras_flow_set_hydrograph(project=copy, plan="03", boundary_index=0, multiplier=1.2) peak 21 000 -> 25 200 cfs, 65 values, count line rewritten
run baseline ras_run(plan="03", num_cores=4) status=completed, max WSEL error 0.0099 ft, volume error 0.0055 %, unsteady compute 0.0133 h, elapsed 61-119 s*
run scenario ras_run(plan="03", num_cores=4) status=completed, max WSEL error 0.0110 ft, volume error 0.0055 %, unsteady compute 0.0135 h
summary ras_results_summary(hdf) 61 XS in White/Muncie; downstream max Q 20 999 cfs, max WSE 938.73 ft; mesh: 4905 / 5765 wet cells, max depth 20.25 ft at cell 537 (t = 19.55 h)
timeseries ras_results_timeseries(kind="xsec", location=downstream, variable="flow") scenario peak 25 200 cfs at 02JAN1900 20:05, 289 points @ 300 s
compare (ranked) ras_results_compare(kind="xsec", variable="flow") 61 shared XS: 61 increased, 0 decreased; largest change at 237.6455: +4 201 cfs (+20.0 %)
compare (stage) ras_results_compare(location=downstream, variable="water_surface") max WSE 938.73 -> 940.75 ft (+2.03 ft), peak 10 min earlier, aligned=exact, RMSE 2.24 ft, NSE 0.52
plots ras_plot x3 03_plots/downstream_flow.png, max_wse_profile.png, max_depth_map.png (scenario: 4997 wet cells, max depth 20.43 ft, cell polygons)
manifest ras_manifest_write runs/muncie_demo/manifest.json, 7 files hashed, missing_files: []

* Elapsed wall time varies with what else the machine is doing (61 s alone, 119 s with the test suite running); the scenario run once took 1267 s because HEC-RAS's Terms and Conditions for Use dialog blocked it — see the boundary note below.

Figures (from docs/figs/):

Downstream flow Max WSE profile Max depth map

2. Bald Eagle Creek 1D: unsteady plan 01 through ras_run

ras_run(project=BaldEagle1D, plan="01", run_dir=runs/baldeagle1d_p01, num_cores=2) -> status=completed, max WSEL error 0.0100, volume error 0.014 %, 178 cross sections, HDF BaldEagle.p01.hdf; ras_results_summary reads it (steady plan 02 of the same project also runs and is read as "steady").

3. RAS-free checks (CI)

pytest (43 tests, ~4 s): boundary-table parser / writer (touching fixed-width fields, count line, CRLF, QMult, insert without table), QA classifier, comparison metrics, manifest, Ras.exe discovery, tool registry, server failure shape, TCU watchdog no-op safety. scripts/smoke_test.py: tool discovery + a real stdio MCP round-trip (initialize, tools/list, tools/call ras_manifest_write) with mcp 2.0.0.

Honest boundaries

  • TCU dialog. HEC-RAS 7.0.1 showed its VB6 Terms and Conditions for Use (TCU) form on some (not all) headless Ras.exe -c launches on this machine; ras-commander's watchdog only sees standard #32770 dialogs. ras_run now runs its own watchdog (accept_tcu, default true) that pages through the form and presses "I agree" / OK, and terminates the run after timeout_s. With accept_tcu=false a blocked run is terminated and reported as failed.
  • Scope. Existing projects only; no terrain / mesh / cross-section / structure editing (RAS Mapper work).
  • Linux engines are installed but not wired in (they need Windows-side preprocessing to .tmp.hdf/.b##/.x##).
  • Reference lines / points, boundary time series are read when the geometry defines them; Muncie's example plans define none, so those code paths are exercised only by unit-level structure, not by a live model yet.
  • Steady flow (.f##) plans run and are read (WSE per profile via ras-commander) but their profiles are not editable.
  • Precipitation tables (Precipitation Hydrograph=) are editable by the same writer; gridded DSS precipitation is not.