RAS Agent - Automated 2D HEC-RAS Hydraulic Modeling

Pipeline

Ten stages. One command.

Each stage is independently testable and produces typed result objects. Run the full pipeline or individual stages - with mock mode for testing without live data or a network connection. HEC-RAS is free, open-source software from the U.S. Army Corps of Engineers - no license required.

🗺️

Terrain Ingestion

Illinois ILHMP 1m LiDAR. Mosaic & reproject to EPSG:5070. Hard-fail if coverage absent - no coarse fallbacks.

🌊

Watershed Delineation

pysheds D8 flow direction & accumulation. Delineate contributing basin, extract characteristics.

📈

Peak Flow Estimation

USGS StreamStats API for peak flows. Fallback to IL regression equations (SIR 2008-5176).

〰️

Hydrograph Generation

NRCS dimensionless unit hydrograph (NEH Part 630). Compute Tc via Kirpich method.

🏗️

Model Builder

Clone template project. Generate Cartesian cell centers in HEC-RAS fixed-width format. Write perimeter + cell seeds to .g## files - preprocessor handles Voronoi tessellation automatically.

⚙️

Execution Engine

RasUnsteady via SQLite job queue. Parallel runs, 4hr timeout, headless on Rocky Linux 8.

📦

Results Pipeline

Typed dataclasses, depth/WSE/velocity rasters, flood extent GeoPackage, COG GeoTIFFs per return period.

🌧️

Precipitation

AORC/MRMS rain-on-grid retrieval. Design storm selection by AEP and duration for Illinois watersheds.

🔬

Storm QC

GHCND gauge cross-validation of gridded precipitation. Flags depth-ratio outliers and unclassified storms.

📄

Report

Self-contained HTML run reports + workspace report packaging. Hydrograph plots, basin characteristics, precip QAQC. FEMA-memo ready.

Features

Engineered for the H&H workflow

Built by engineers for engineers. Designed to handle the unglamorous parts of hydraulic modeling - data wrangling, format conversion, and model assembly - so you can focus on review and QA.

⚡

Fully Automated

One command runs the entire 10-stage pipeline from coordinates to flood maps. Human-in-the-loop pauses route scientific decisions to the engineer - never silent autonomy on regulatory choices.

python pipeline/orchestrator.py \
  --lon -88.578 --lat 40.021 \
  --output ./output/test

🔁

Batch Processing

Run hundreds of watersheds in parallel with batch.py. Resume on failure - skip completed runs automatically. Outputs a summary CSV for each batch run.

python batch.py \
  --watersheds watersheds.csv \
  --workers 8 \
  --resume

🗺️

Web Dashboard + Map Viewer

FastAPI backend with React dashboard. MapLibre flood extent viewer with multi-return-period toggle - switch between 10-yr, 50-yr, and 100-yr flood layers interactively.

docker-compose up api

# With web dashboard:
docker-compose \
  --profile dev up

🐳

Docker Ready

Reproducible environment with GDAL, pysheds, and all geospatial dependencies pre-installed. Runs fully headless on Rocky Linux 8 - no Windows required for geometry preprocessing or simulation.

docker build -t ras-agent .
docker run --rm ras-agent \
  python pipeline/orchestrator.py \
  --lon -88.578 --lat 40.021

📄

HTML Run Reports

Self-contained HTML reports generated for every run - hydrograph plots, basin characteristics table, and flood extent preview. Suitable for attaching to FEMA memos or client deliverables.

☁️

Cloud Storage

Cloudflare R2 integration for results storage. Generates presigned download URLs for sharing COG GeoTIFFs, GeoPackages, and HTML reports without exposing storage credentials.

🔬

HITL / Scientific Review

Human-in-the-loop pauses at configurable stages for expert validation. Engineers review and approve before the pipeline advances - critical for regulatory submissions and peer review.

🧪

Mock Mode & CI

Run the complete pipeline without real terrain data or a live StreamStats connection. HEC-RAS is free, open-source software from the U.S. Army Corps of Engineers - no license required. 474 tests pass in CI on every push. Every HTTP call is mocked - no network access required.

python pipeline/orchestrator.py \
  --mock

python -m pytest tests/ -v
# 474 passed

🔔

Webhook Notifications

HMAC-signed webhook payloads on run completion. Email notifications included. Integrate with Slack, Teams, or any CI/CD pipeline to trigger downstream workflows automatically.

Recent Milestones

What's shipping now

Active development - major capability unlocks in the last development cycle.

🌧️

Rain-on-Grid Pipeline (Stages 8–10)

Extended to a full 10-stage pipeline with AORC/MRMS precipitation retrieval, GHCND gauge cross-validation, and workspace-packaged HTML run reports. Design storm AEP selection and depth-ratio QC flags are first-class outputs.

🏔️

Pilot Channel Terrain-Mod Proposals

pilot_channel.py generates conservative LiDAR terrain-mod proposal packages from TauDEM centerlines - STA/ELEV profiles, cut/fill summaries, reviewer flags, and HTML report. Proposal-only: never edits production terrain. Human engineering signoff required before application.

✅

TauDEM QAQC + Signoff Bundle

Real TauDEM delineation writes a reviewer QAQC bundle by default - qaqc_report.html, diagnostics, SVG maps, and a signoff.json. Production promotion is blocked until human approval is recorded.

🧪

474 Tests Passing

Full test suite runs in CI on every push. 474 tests covering all 10 pipeline stages, batch mode, TauDEM QAQC, mesh QA, pilot channel proposals, NWIS retrieval, SLURM, results parsing, cloud-native export, and API endpoints - all with mock mode.

Automated 2D HEC-RAS Hydraulic Modeling - Terrain to Flood Maps

Ten stages. One command.

Engineered for the H&H workflow

What's shipping now

Built by the H&H community