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 - DSS Results, Native Records, and Recovery Results extraction, windows, DSS6/DSS7 writes, every curve of a paired-data record, repair and the sync flush policy

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; write WGS84 grids, and the tenk storm on the SHG lattice through HmsAorc and the engine's NetCDF reader
14b - AORC Grid Setup Create grid definitions and cell mappings; check the cells against the grids; move the tenk cells from HRAP to SHG
14c - AORC HMS Execution Run HMS with the shipped Stage III grids and with the new AORC SHG grids, and check PRECIP-INC against the grids

Native DSS and Gridded Precipitation (5-10 minutes)

These notebooks use the optional native DSS engine (ras-commander-fast-dss); see the Native DSS Backend guide and the notebook qualification.

Notebook Description
23 - Native Gridded Import, Zonal Rainfall, and Grid Tools MRMS GRIB2 (1, 6 and 24 hours), AORC NetCDF-4 and SNODAS imported to SHG over the tenk basin; every grid tool; all eight zonal statistics written as subbasin rainfall series
06 - DSS Results, Native Records, and Recovery Native records, repair and sync (also listed above)
14a / 14b / 14c - AORC on the SHG lattice The SHG route, cell remapping, and the HEC-HMS check of the new grids (also listed above)

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