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:
- Follow the repository notebook rules in
examples/AGENTS.md - Use
HmsExamples.extract_project()for reproducibility - Include pip cell + dev environment note
- Execute and save outputs
- Add to
mkdocs.ymlnavigation
See Contributing Guide for details.
Next Steps¶
- New users: Start with 01 - Basic Workflow
- API details: See API Reference
- Concepts: Review User Guide