PyFloods

Automate HEC-RAS with Python — drive river-hydraulics models at scale, without touching the GUI.

PyFloods is a collection of working scripts that use the HEC-RAS Controller (COM API) to open existing HEC-RAS projects, run them, and extract results programmatically — plus pipelines that processed thousands of county-scale HEC-RAS models from the FRIS/NFIE datasets into geomorphic metrics (entrenchment ratio, incision ratio), rating curves, and cross-section data.

Deep-dive documentation of the code base: https://deepwiki.com/solomonvimal/PyFloods

---

Why this exists

I built these scripts years ago to save time for anyone getting started with the HEC-RAS Controller in Python. The Controller's documentation is thin, its function IDs are cryptic, and almost nobody publishes working code for it. This repository maps ~30 output-variable IDs (water-surface elevation, depths, velocities, top widths, bank stations, hydraulic radii...) with runnable extraction examples, and shows how to loop that machinery across hundreds of model files unattended.

A taste of what you get — the ID map (full version in HEC_RAS_controller.py):

Variable	ID	Variable	ID
Water surface elevation	2	Top width	62
Energy grade line	3	Left/right bank stations	263 / 264
Max channel depth	4	Channel bank stations	158 / 159
Total flow	9	LOB/ROB elevations	197 / 198
Flow area (XS / LOB / Ch / ROB)	10–13	Hydraulic radius (XS/LOB/Ch/ROB)	208–211
Wetted perimeter	14–17	Min channel elevation station	255
Average velocity	23	Min section elevation	136

Repository map

Script	What it does
HEC_RAS_controller.py	Start here. Guided tour of the Controller: connect, open a project, enumerate nodes/profiles, extract ~20 variables, compute entrenchment/incision ratios, plot long profiles
RatingCurves.py	Batch-extract depth–discharge rating curves for every cross section of every .prj in a folder → pickled dict
EntrenchmentRatio.py	Per-cross-section entrenchment/incision metrics from RAS output
County_ER.py, County_ER_exceptions.py	Full pipeline: unzip NFIE county HEC-RAS bundles → run each project through the Controller → county-wide entrenchment-ratio tables (with exception handling for inconsistent folders)
XS_averaging_by_COMID.py, XS_averaging_by_COMID_TACC.py	Average cross sections grouped by NHD COMID (+ TACC/HPC variant)
merged_XS_to_triangle.py	Convert merged cross sections to triangular/fan geometry
XSPoint.py, extract_XY.py, XY_from_HEC_RAS.py	Pull cross-section cut-line coordinates out of RAS schematics
Plot_XS.py	Cross-section profile plotting
SPRNT.py, SPRNT_connectivity.py	SPRNT river-basin network utilities
HYDRAID_to_HEC-RAS.py, file_zip_names.py, Unzip_From_R.py, extract_subfolder.py	Data-wrangling helpers for HYDRAID/NFIE archives
merge_entrenchment_tables.py, reject_ouliers.py, averaging_parameters.py, hydraulic_parameters.py, CSV_open.py, ArcPy_Sagy.py	Post-processing glue (tables, outlier rejection, ArcGIS interop)

Legacy data artifacts were moved out of the main tree to keep the repository lean; they live in unused_backup/ locally if you cloned an older revision.

Quickstart

Requirements: Windows, an installed HEC-RAS (4.1 or 5.x), Python 3.8+.

git clone https://github.com/solomonvimal/PyFloods.git
cd PyFloods
pip install -r requirements.txt

Then open HEC_RAS_controller.py, point ras_file at any HEC-RAS .prj, and run it — the script walks through connecting to the Controller, opening the project, and pulling results node by node.

import win32com.client

RC = win32com.client.Dispatch("RAS500.HECRASCONTROLLER")
RC.Project_Open(r"C:\path\to\your_model.prj")

n = RC.Schematic_XSCount()                      # number of cross sections
wse = RC.Output_NodeOutput(1, 1, 1, 0, 1, 2)[0] # WSE (ID=2) at node 1, profile 1
print(n, wse)
RC.QuitRAS()

Tip: everything the Controller does behaves like scripted clicks on the HEC-RAS GUI. If a native method is missing, mouse automation via win32api fills the gap (example at the bottom of the original README notes below).

Reference & credits

• The book Breaking the HEC-RAS Code by Chris Goodell (https://tinyurl.com/Chris-HEC-RAS-book) is what I used to learn the Controller. You can get far with the code here plus the key of HEC-RAS function IDs in this sheet.
• Chris Goodell maintains a user forum for the book — post Controller questions there; I sometimes check the Python-related ones. You're also welcome to email me: solomon.vimal@gmail.com

Training & workshops

Want to learn HEC-RAS Controller automation properly instead of reverse-engineering it?

I offer paid, hands-on training for individuals and organizations:

• Intro workshop — connect Python to HEC-RAS, extract results, first automation script in 90 minutes
• Batch-processing masterclass — running and harvesting thousands of models unattended (the full County_ER-style pipeline)
• Custom/on-site training — tailored to your models, your folder structures, your KPIs

📩 Enquiries: solomon.vimal@gmail.com (subject line: PyFloods Training)

Commercial licensing

This repository is free for research, education, and other noncommercial use under the PolyForm Noncommercial 1.0.0 license. Commercial use — including use inside for-profit consultancies, engineering firms, or SaaS products — requires a separate license. Contact solomon.vimal@gmail.com.

License

Code: PolyForm Noncommercial 1.0.0 — free for research/education, paid license required for commercial use.