Skip to content

Example Notebooks

HMS Commander provides a growing set of Jupyter notebook examples demonstrating real-world workflows, organized by learning progression.

The canonical notebook source is the repository-level examples/ directory. MkDocs currently renders only selected benchmark notebooks under docs/notebooks/; the catalog below links to the source notebooks on GitHub when a rendered docs copy is not intentionally published.

Running the Examples

Setup

# Install with all dependencies
pip install hms-commander[all]

# Clone repository
git clone https://github.com/gpt-cmdr/hms-commander.git
cd hms-commander/examples

# Start Jupyter
jupyter notebook

Using HMS Example Projects

Most notebooks use HEC-HMS example projects that are automatically extracted:

from hms_commander import HmsExamples

# Extract an example project
project_path = HmsExamples.extract_project("castro")

# Or see available projects
projects = HmsExamples.list_projects()

Learning Path

New to hms-commander? Start with 00 - Overview for environment verification and learning path guidance.

Beginner Track (30-45 minutes)

Notebook Description
00 - Overview Environment verification, HMS glossary, learning path
01 - Basic Workflow Initialize, execute, extract results (start here!)
02 - Project DataFrames Explore project structure via DataFrames

Intermediate Track (60-90 minutes)

Notebook Description
03 - File Operations HmsBasin, HmsMet, HmsControl, HmsGage file operations
04 - Run Management Configure and validate simulation runs
05 - Clone Workflow Non-destructive model modifications for QAQC
06 - Results and DSS DSS operations and results extraction

Advanced Track (45-90 minutes)

Notebook Description
07 - Jython Execution Version detection, script generation, batch execution
08 - M3 Models HCFCD M3 model discovery and extraction
09 - M3 Conversion HMS 3.x to 4.x project conversion workflow

Storm Generation (30-45 minutes)

Notebook Description
10 - Atlas 14 Hyetograph Generate design storms from NOAA Atlas 14
11 - Frequency Storm Variable duration storms using TP-40/Hydro-35 patterns

Official HEC-HMS Guide Mirrors (45-90 minutes)

These notebooks cite the official HEC-HMS Tutorials and Guides category pages and show the hms-commander equivalent for workflows that are already supported by the public API.

Notebook Official guide category
101 - Basic Model Setup Basic model setup, simulation execution, and DSS hydrograph review
102 - Meteorologic Methods Historical gage hyetographs, gridded met assets, frequency storms, Atlas 14, and SCS temporal patterns
103 - GIS and Terrain Data GIS tools, model-type detection, subbasin/stream maps, and GeoJSON extraction
104 - Basin Methods, Loss, Transform, and Routing Parameter estimation, CN sensitivity, unit hydrographs, baseflow, and reach routing attenuation
105 - Calibration and Validation Observed-vs-modeled hydrographs, residuals, calibration scaffolding, and Manning roughness sensitivity
106 - Advanced Analysis Batch-run scaffolding, computed parameter ensembles, fan charts, and objective convergence

TauDEM to HMS Assembly (30-60 minutes)

Notebook Description
21 - TauDEM to HMS Atlas 14 Bootstrap Build a TauDEM-derived HMS basin, validate import, and run a Spring Creek Atlas 14 frequency storm

Status note:

  • the notebook is a live Spring Creek benchmark and now proves the path is import-valid and compute-valid
  • the resulting scaffold still carries modeling residuals that must be handled before production use: missing ET/canopy methods, Muskingum stability warnings, lag-vs-time-step warnings, and negative inflow clipping
  • future roadmap work adds the readiness gate, TauDEM parameter tuning/comparison support, and human-review QAQC bundle around this notebook-driven workflow

Validation & Equivalence Proofs (20-30 minutes)

These notebooks demonstrate hms-commander storm-generation equivalence against reference data and HEC-HMS output:

Notebook Description
12 - SCS Type Validation SCS Type I, IA, II, III equivalence proof
13 - Atlas 14 Multi-Duration Multi-duration Atlas 14 validation (6h, 12h, 24h, 96h)
22 - Ground Truth Validation HEC-HMS 4.13 PRECIP-INC fixtures for SCS Type I/II/III and TP-40 frequency storms

AORC Integration (30-60 minutes)

Notebook Description
14a - AORC Download Download AORC precipitation from NOAA AWS
14b - AORC Grid Setup Create grid definitions and HRAP cell mappings
14c - AORC HMS Execution Run HMS with gridded precipitation

All Notebooks Have

✅ Executed outputs - See expected results before running ✅ Visualizations - Charts and plots embedded ✅ Validation - Assertions and quality checks ✅ Prerequisites - Clear requirements documented ✅ Troubleshooting - Common issues and solutions

Development Pattern

All notebooks use the standard two-cell import pattern:

# Cell 1: pip install
# pip install hms-commander

# Cell 2: Development note
# For source development, use the active repo development environment
# and make sure this checkout is on PYTHONPATH or installed editable.

Testing with Real Projects

Examples use actual HEC-HMS projects for real-world applicability: - castro - Simple watershed model - tifton - Time series demonstration - tenk - Gridded precipitation example - M3 models - FEMA-effective H&H models (HCFCD)

Contributing Examples

We welcome example contributions! To add a notebook:

  1. Follow the repository notebook rules in examples/AGENTS.md
  2. Use HmsExamples.extract_project() for reproducibility
  3. Include pip cell + dev environment note
  4. Execute and save outputs
  5. Add to mkdocs.yml navigation

See Contributing Guide for details.

Next Steps

CLB Engineering Corporation  ·  LLM Forward Engineering
HMS Commander is a free and open-source project maintained by CLB Engineering Corporation. For agencies and firms seeking to modernize H&H workflows with LLM Forward approaches, contact CLB to partner with the engineers who wrote the automation.