Imported from lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation (models/HEC_RAS/SKILL.md). Install upstream with npx skills add lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation --skill HEC_RAS. Copyright stays with the author.

MANDATORY EXECUTION POLICY — READ BEFORE PROCEEDING

You MUST run the actual model binary or package described in this document. If the model fails to import, compile, or execute, you MUST:

1. Check diagnostics/triplets.yaml for a matching error pattern
2. Try the fix suggested in the triplet's remedy section
3. If still failing, report the error to the user with full details

You MUST NOT substitute a simplified Python formula, regression equation, or hand-coded approximation in place of the real model. Doing so produces scientifically invalid results and defeats the purpose of the KI.

Before starting, run: python3 preflight_check.py (in this KI directory) to verify that the model binary/package and required data are available. Use python3 (/usr/bin) for the validated steady tools — h5py + ki_tools_common are on its path; NOT python (~/.local/bin lacks h5py). HOWEVER ras_commander 0.93.0 lives ONLY in the python_env venv site-packages, which is NOT on /usr/bin/python3's path. For ANY new-river / authoring step that imports ras_commander (§10/§11), invoke it with the venv interpreter KISSPATH_PYTHON_ENV/bin/python3 (verified 2026-06-04: it imports h5py 3.15.1 + ras_commander 0.93.0 + ki_tools_common together).

DEBUGGING PROTOCOL — When something goes wrong (model crashes, wrong output, unexpected values), follow this order. Do NOT skip steps or write debug scripts:

1. Check triplets — diagnostics/triplets.yaml may already cover this error
2. Read official docs — Check the model's own documentation (PDF manual, README, official examples) for expected input formats, variable names, and units
3. Find working examples — Look in outputs/ for previous successful runs of this model, or check if the model ships with test/example data
4. Fix the tool — Now that you know what "correct" looks like, make targeted fixes

Resist the urge to write diagnostic/debug Python scripts. The answers are almost always in the official docs and working examples, not in reverse-engineering the binary.

KI map — what to read, and when

Projected 2026-08-17 from the KI's actual contents — 8 components present. Refresh: python3 ki_tools_common/generate_skill_map.py --ki_dir <this KI>.

Executable tool index (projected — complete by construction)

Every public tool in this KI, by exact path. What each is FOR lives in the human-written Tool Inventory above; --help on any of these prints its arguments.

10 public tools; _-prefixed helpers and packaging files excluded.

HEC-RAS (Hydrologic Engineering Center — River Analysis System) — Knowledge Infrastructure

Package: hydrocraft-hec-ras v2.0.0 Model: HEC-RAS 6.7 Beta 5 (USACE Hydrologic Engineering Center) — real Intel-Fortran solvers under WINE Domain: River / open-channel hydraulics (1-D & 2-D) Binary: KISSPATH_HOME/.wine/drive_c/Program Files (x86)/HEC/HEC-RAS/6.7 Beta 5/x64/RasSteady.exe Last updated: 2026-06-03 Stats: 11 tools | 6 docs | 20 diagnostic triplets Validation status: real — computed vs observed water-surface elevations on the Mixed Flow Regime Channel example: NSE 0.9965, RMSE 0.096 ft, KGE 0.977, PBIAS −0.09 % (19 cross sections).

⚠️ This KI was rebuilt 2026-06-03 to drive the ACTUAL HEC-RAS binary. A prior version shipped a GR4J rainfall-runoff Python surrogate — that was both a KDT-philosophy violation (no real binary) and a domain error (HEC-RAS is a hydraulics model, not a rainfall-runoff model). The surrogate has been removed. Every tool here invokes RasSteady.exe.

1. What HEC-RAS is (and is NOT)

HEC-RAS computes water-surface profiles and velocities along a river, given surveyed cross-section geometry, channel roughness, discharge, and boundary conditions. It solves:

• Steady flow — standard-step solution of the 1-D energy (Bernoulli) equation for gradually-varied flow → WS / energy grade / velocity per cross section per profile.
• Unsteady flow — implicit finite-difference solution of the 1-D Saint-Venant equations (and 2-D shallow-water equations) → stage/flow hydrographs in time.
• Add-ons — bridge/culvert/gate hydraulics, sediment transport, water quality.

HEC-RAS is NOT a rainfall-runoff model. Its forcing is discharge (cfs or m³/s) and boundary stage — not precipitation, temperature, or radiation. Do not wire load_daily_forcing (precip/temp) into HEC-RAS. The Layer-1 tie-in is discharge via ObservedQ (see convert_flow_to_hecras.py).

2. Installation / environment

HEC-RAS is proprietary, closed-source USACE Windows software. There is no buildable source. A pre-built install (6.7 Beta 5) is staged under WINE 9.0:

Install:  KISSPATH_HOME/.wine/drive_c/Program Files (x86)/HEC/HEC-RAS/6.7 Beta 5
Solvers:  x64/RasSteady.exe            (steady — VALIDATED here)
          x64/RasUnsteady.exe          (unsteady — loads; needs orchestration)
          x64/RasGeomPreprocess.exe    (geometry property tables)
          x64/RasUnsteadySediment.exe  (sediment)
          x64/RasWaterQuality.exe      (water quality)
          x64/RasQuasiSediment.exe / RasQuasiRVSM.exe

Invoke a solver under wine (the tools do this for you):

env -u LD_PRELOAD WINEPREFIX=KISSPATH_HOME/.wine WINEDEBUG=-all \
  wine ".../6.7 Beta 5/x64/RasSteady.exe" MIXED.r01

Two environment gotchas (both handled in tools/_hecras_env.py):

1. A broken system-wide LD_PRELOAD (32-bit libstdc++) breaks wine — strip it (env -u LD_PRELOAD).
2. RasSteady aborts with HDF_ERROR trying to open HDF output file unless the plan results skeleton <prj>.pNN.tmp.hdf exists — seed it from <prj>.gNN.hdf.

Python helpers used: h5py (read results), numpy, matplotlib, ki_tools_common (metrics, units). ras-commander 0.93.0 is installed but its project auto-detection does not recognise the "6.7 Beta 5" layout, so this KI drives the solvers directly rather than through RasCmdr.compute_plan.

3. Execution architecture (why this works headless)

The Fortran solvers do not read the human-readable .prj/.g/.f/.p files. The .NET orchestrator Ras.exe normally (a) flattens geometry+flow+plan into a run file .rNN, and (b) creates the plan results HDF .pNN.tmp.hdf. Ras.exe needs Wine Mono, which is not installed here.

Verified work-around for steady runs (this is what makes the KI real):

1. Start from a project that already has a .rNN run file (every shipped example does).
2. Seed results skeleton:   cp <prj>.gNN.hdf  <prj>.pNN.tmp.hdf
3. Run:  wine RasSteady.exe <prj>.rNN     (cwd = project dir)
4. Results land in <prj>.pNN.tmp.hdf -> /Results/Steady/Output/.../Cross Sections/

run_hecras.py does all four steps in a temp workspace and collects the output. The trailing HDF5-DIAG lines printed after Finished Steady Flow Simulation are non-fatal (the solver probes an optional group) — success is keyed on the "Finished" banner and a populated (>60 kB) results HDF.

Limitation (documented honestly): brand-new geometry requires a .rNN run file, which only Ras.exe/the GUI/ras-commander can write from scratch. Unsteady/sediment/WQ solvers load and execute (proven) but their full run needs the plan-HDF skeleton Ras.exe builds with boundary conditions baked in — so they are documented but not end-to-end validated in this environment.

4. Capability inventory (Phase 1b) → tools

5. Pipeline (typical steady workflow)

cd knowledge_infrastructure

# 0. environment check
python3 preflight_check.py

# 1. prepare a parameterised project from the template
python3 tools/prepare_steady_run.py --out-dir /tmp/myproj \
        --flows 600,1200 --dn-slope 0.0008

# 2. run the REAL steady solver
python3 tools/run_hecras.py --project /tmp/myproj --prj MIXED --plan 01 \
        --out /tmp/myproj_out

# 3. parse results to CSV/JSON
python3 tools/parse_output_hecras.py --hdf /tmp/myproj_out/MIXED.p01.tmp.hdf \
        --csv /tmp/myproj_out/results.csv

# 4. validate against observed WS (real-tier)
python3 tools/validate_hecras.py --hdf /tmp/myproj_out/MIXED.p01.tmp.hdf \
        --flow examples/MixedFlowSteady/MIXED.f01 --figure figures/s8_validation.png

# (optional) stage-discharge rating curve at cross section #9
python3 tools/rating_curve.py --xs-index 9 --flows 300,500,800,1200,2000 \
        --out /tmp/rating.csv

Every tool returns a JSON status with a validation block and exits non-zero on failure (validate→process→validate contract).

6. Output Description and Input Reference

Source of truth: dag.yaml. The dag is the model identity for observable outputs: variable names, units, media, descriptions, observability, and validation_rank come from the dag. If this section ever disagrees with dag.yaml, the dag wins and this section is the bug.

Headline output (dag validation_rank: 1):

discharge_out — Open-channel surface-water discharge at each cross section / structure / 2-D cell-face. For STEADY flow this is a conserved pass-through of the input forcing, NOT a model product. (cfs or m^3/s)

Other dag outputs currently named by this KI are: water_surface_elevation, energy_grade, velocity_channel, velocity_total, flood_inundation_extent, froude_number, shear_stress_channel, friction_slope, sediment_transport_rate, bed_elevation_change, and water_quality_constituent.

Inputs (per project <PRJ>)

Outputs

Key results HDF path: /Results/Steady/Output/Output Blocks/Base Output/Steady Profiles/Cross Sections/ holds Water Surface, Energy Grade, Flow (shape [n_profiles, n_xs]) and an Additional Variables/ group with velocity, depth, top width, area, Froude, shear, etc.

Unit trap table

The unit system is declared in the .prj (English Units / SI Units); changing discharge units without changing the project unit system silently corrupts results.

7. Unsteady / sediment / water quality (documented, not validated here)

The unsteady, sediment, and water-quality solvers are present and execute under wine (RasUnsteady.exe prints Performing Unsteady Flow Simulation HEC-RAS 6.7 Beta 5). Their full headless run is blocked because the plan results skeleton — which Ras.exe writes with the boundary-condition time series baked in — cannot be produced without Wine Mono (~/.wine/drive_c/windows/mono absent; dl.winehq.org unreachable in this sandbox). To run them you must either install Wine Mono and use Ras.exe -c project.prj plan.pNN, or run on a native Windows / licensed HEC-RAS install. See docs/06_capabilities.md and triplets unsteady_needs_mono, wine_mono_missing.

8. Unit Conversion Table

This table documents the unit conversions used by the HEC-RAS KI pipeline. HEC-RAS projects are either English or SI; the project unit system controls geometry, boundary conditions, and result interpretation.

Do not convert meteorological forcing into HEC-RAS. This KI consumes geometry, roughness, discharge, and boundary stage/slope; precipitation, temperature, radiation, wind, and soil tables are not HEC-RAS inputs.

9. Tool reference

10. Data requirements & sources

✅ NEW-RIVER STEADY NOW WORKS — no Wine Mono, no ras_commander (2026-06-04). The repeated "structurally impossible without Wine Mono" verdict was a FALSE NEGATIVE. The steady Fortran solver reads cross-section station/elevation directly from the .rNN run file — the .gNN.hdf is only the results-skeleton seed. Proven by controlled experiment: bumping every bed elevation in MIXED.r01 by +5 ft and re-running RasSteady.exe under plain wine raised the computed WS by exactly +5 ft (66.00..72.93 → 71.00..77.93). New geometry therefore needs only an edited .rNN, which is now authored by tools/author_steady_geometry.py (DEM + centerline → ki_tools_common.terrain_ops.cut_cross_sections → trapezoidal cross sections injected into the template .rNN, keeping 19 XS / 4 pts so the "Section - Arrays Sizes" header stays valid). Demonstrated end-to-end on Bengbu (china_dem_90m, 19 DEM cross sections, observed Q quantiles 3810/6812 m³/s → WS 69.33..81.22 ft, RasSteady.exe rc=0, real hydraulics in the results HDF). Limitation: this value-swap path inherits the template's longitudinal layout (reach lengths / river stations); fully general XS count/spacing additionally needs regenerating the array-size header (next tool_build). And steady produces stage, consumes discharge — a discharge_m3s validation target is the forcing input, not an output; for discharge-vs-discharge routing fidelity use unsteady (§12, still needs the plan-HDF skeleton — open question whether the unsteady solver is likewise .rNN/.uNN-authoritative).

(superseded note — ras_commander path) CORRECTION (2026-06-04, diagnosis retry): the prior "ras_commander not installed" verdict was a FALSE NEGATIVE — it ran import ras_commander under /usr/bin/python3. ras_commander 0.93.0 IS installed in the python_env venv and imports cleanly from KISSPATH_PYTHON_ENV/bin/python3, exposing the full authoring stack: GeomCrossSection.set_station_elevation, GeomPreprocessor, RasGeo, RasCmdr.compute_plan_linux, HdfResultsXsec. The ONLY remaining gap is that no tool in tools/ yet wraps these into a DEM→cross-section authoring + run pipeline — a tool_build TODO, NOT a missing library. Author new-river steps with the venv interpreter (see §2). Verified-working scope today is steady water-surface profiles on geometry that already ships a .gNN.hdf + .rNN (the bundled MixedFlowSteady example, NSE 0.9965 §11).

The intended (currently non-executable) workflow for a new basin would be:

1. Start from a bundled template (RasExamples.extract_project('MixedFlowSteady') or any project that ships a .gNN.hdf + a .pNN).
2. Replace cross-section geometry using RasGeo / GeomCrossSection — overwrite station-elevation tables with DEM-extracted cross sections (MERIT-Hydro 3-arcsec tiles, river centerline from MERIT-Hydro dir).
3. Set flow / boundary conditions via RasUnsteady for unsteady routing or RasPlan for steady. Upstream BC = observed discharge time series.
4. Run via RasCmdr.compute_plan() — this calls the Fortran solvers (HEC-RAS.exe, RasUnsteady.exe) which work under plain WINE without Wine Mono (verified Tier 3 v1, 2026-06-02). Do NOT invoke Ras.exe (the .NET GUI) — that DOES need Wine Mono.
5. Read modelled output via HdfResultsMesh (cross-section results) or HdfPlot — produces water-surface stage, modelled discharge at downstream nodes, velocity profiles.

What still requires Wine Mono (and is still blocked here): Ras.exe -c compute (the .NET command-line driver), RAS Mapper GIS exports, the GUI itself. Anything that goes through HECRASController COM.

What still requires human engineering: choosing channel/overbank Manning n (use 0.035/0.06 default), picking cross-section spacing (Δx ≈ 50–500 m), calibrating against observed water-surface or downstream Q.

⚠️ ORCHESTRATION TARGET VARIABLE. HEC-RAS consumes discharge and produces water-surface stage. A verifier target of Variable=discharge_m3s is wrong for this domain — discharge is the forcing input, not an output. The comparison variable must be water-surface stage (the observed z column / observed-WS lines), as validated in §11.

• Geometry — surveyed cross sections (station, elevation) in the project unit system. The bundled template (examples/MixedFlowSteady/) is a prismatic trapezoidal reach; for a new river, geometry comes from survey or DEM-extracted cross sections (authored in the HEC-RAS GUI / ras-commander).
• Discharge — design floods or ObservedQ peaks. See data_ki/ObservedQ/SKILL.md for the observed-discharge dataset format; convert_flow_to_hecras.py can read it and convert m³/s → cfs.
• Roughness — Manning n from land cover / channel material (channel 0.025–0.05, overbank 0.04–0.15). Default 0.035 channel / 0.06 overbank if unknown.
• Why this data? HEC-RAS is a hydraulics model: it consumes discharge and geometry, not meteorology. The CMFD/MSWX/NASA-POWER met loaders in ki_tools_common are therefore intentionally not used here.

See docs/ for stage-by-stage procedures and diagnostics/triplets.yaml for the error→remedy catalogue (HDF seeding, LD_PRELOAD, unit traps, Wine Mono, etc.).

11. Validated Results

Test Case: Mixed Flow Regime Channel

The dag's rank-1 output is discharge_out: Open-channel surface-water discharge at each cross section / structure / 2-D cell-face. For STEADY flow this is a conserved pass-through of the input forcing, NOT a model product. The validated body campaign here is therefore reported on water_surface_elevation, the observable steady-flow model product with observed WS lines in the bundled example.

Performance Metrics

The computed profile correctly reproduces the supercritical→subcritical transition (hydraulic jump) of the mixed-flow regime: Froude > 1 in the steep upstream reach, < 1 downstream.

Convention Bars Restated From docs/validation_convention.yaml

These are the convention entries supplied for water_surface_elevation. They must not be copied onto discharge_out; no cited discharge_out pass-band is stated here.

Data Replacement Tracking

12. Routing-test recipe (Wangjiaba → Bengbu, Huai River)

⚠️ STEADY new-river now works (§10); this §12 UNSTEADY Q→Q routing recipe is still blocked. For a steady water-surface profile on a new reach use tools/author_steady_geometry.py (no Wine Mono). The unsteady routing below needs the plan-HDF skeleton with boundary time series baked in — open question whether the unsteady solver is likewise flat-file (.uNN/.rNN) authoritative the way the steady solver proved to be.

⚠️ PARTIALLY EXECUTABLE — library present, wrapper missing (corrected 2026-06-04). This recipe depends on ras_commander (RasExamples, RasGeo, GeomCrossSection, RasUnsteady, RasCmdr.compute_plan_linux) and a DEM→cross-section authoring step. ras_commander 0.93.0 IS installed — import it via KISSPATH_PYTHON_ENV/bin/python3; the only missing piece is a tools/ wrapper that authors geometry from a DEM. Every Bengbu run to date has therefore been structurally blocked at the authoring stage — the Bengbu Q/stage metrics are uncomputable, not poor. The recipe is kept as the design target for when those dependencies are added. Until then HEC-RAS validates only on geometry that already ships a .gNN.hdf + .rNN (dev example, §11).

This is the orchestrator's primary real-case validation for HEC-RAS. It tests hydrodynamic routing fidelity (attenuation + lag) on a real river reach, which is the natural validation for HEC-RAS (the model consumes upstream Q and routes it downstream — it does not produce Q de novo).

Reach. Huai River, China. Upstream gage Wangjiaba (id wangjiaba_51030, 32.43 N, 115.60 E, KISSPATH_OBS/WJB/HUAIH-51030-wangjiaba.txt) → downstream gage Bengbu (id bengbu_51080, 32.93 N, 117.38 E, KISSPATH_OBS/BB/51080_bengbu.txt). ~200 km reach. Both files share period 1952-05-30 to 1997-12-31, daily resolution, columns include discharge_m3s and water_level_m.

Pattern.

1. Authoring (ras-commander HDF-direct, no Wine Mono).
   • Start from a bundled template via RasExamples.extract_project('MixedFlowSteady') (or any project shipping .gNN.hdf + a plan file).
   • Use RasGeo / GeomCrossSection to overwrite station-elevation tables with cross sections sampled from MERIT-Hydro DEM (KISSPATH_DATA/MERIT_Hydro/, 3-arcsec tiles) along the Wangjiaba→Bengbu centerline. Δx ≈ 200-500 m.
   • Use RasUnsteady to set:
     • Upstream BC = Wangjiaba discharge_m3s time series (read with read_obs_q.py or data_ki/ObservedQ/SKILL.md recipe).
     • Downstream BC = normal-depth (friction slope) or stage-Q rating.
     • Plan title, time window matching the obs overlap.
2. Run (plain WINE, no Mono). RasCmdr.compute_plan(prj, plan_id, num_cores=4) invokes the Fortran solvers (HEC-RAS.exe, RasUnsteady.exe) under WINE.
3. Extract modelled Q at Bengbu. HdfResultsMesh (or parse_output_hecras.py for 1D unsteady) — pull discharge time series at the cross-section nearest Bengbu (32.93 N, 117.38 E).
4. Compare modelled Bengbu Q vs observed Bengbu Q over a common 1–3 year window (NSE, KGE, r, PBIAS, peak-lag). Use the standard validators.

Why this is the right test. HEC-RAS is a 1D/2D hydrodynamic solver — its job is to take Q at an upstream boundary and route it downstream with proper wave attenuation and lag. Comparing modelled-discharge-at-a-different-station to observed-discharge-at-that-station directly measures routing fidelity. (A stage-vs-stage test is the other valid choice; see §10 ⚠️ note. We use Q-vs-Q here because both gages have long contiguous daily Q records.)

Pitfalls. (a) Make sure the unsteady time step Δt is small enough for the Courant condition along the reach (Δt ≤ Δx / c with c ≈ √(g h)). (b) The ~200 km reach has tributaries; for a first cut, ignore them — the model will under-predict peaks. To add lateral inflow, use RasUnsteady flow-distributions on internal cross sections. (c) Normal-depth downstream BC induces an error band near the downstream end; place the Bengbu extraction cross section ≥ 5 km upstream of the downstream BC to avoid it.