parsing-basin-models
Parses HEC-HMS basin model files (.basin) to extract and modify subbasins, junctions,reaches, loss parameters, transform parameters, baseflow, and routing. Use when readingbasin files, modifying hydrologic parameters, analyzing basin structure, or updatingcurve numbers, lag times, and routing coefficients. Handles clone workflows for QAQC.Trigger keywords: basin file, subbasin, junction, reach, loss method, curve number,transform, lag time, baseflow, routing, Muskingum, parse basin, get parameters.
When & Why to Use This Skill
This Claude skill facilitates the automated parsing, extraction, and modification of HEC-HMS basin model (.basin) files. It streamlines hydrologic engineering workflows by providing programmatic access to subbasins, junctions, and reaches, enabling bulk updates to critical parameters like curve numbers, lag times, and routing coefficients while supporting non-destructive QAQC cloning.
Use Cases
- Automated extraction of basin components and connectivity data into structured DataFrames for rapid hydrologic analysis and reporting.
- Bulk modification of hydrologic parameters, such as updating SCS Curve Numbers or lag times across hundreds of subbasins simultaneously.
- Performing non-destructive QAQC by cloning existing basin models to test different parameter scenarios without altering the original project files.
- Analyzing complex basin structures and downstream relationships to validate model connectivity and routing logic programmatically.
| name | parsing-basin-models |
|---|---|
| description | | |
| Trigger keywords | basin file, subbasin, junction, reach, loss method, curve number, |
Parsing Basin Models
Quick Start
from hms_commander import HmsBasin
# Read basin components
subbasins = HmsBasin.get_subbasins("project.basin")
junctions = HmsBasin.get_junctions("project.basin")
reaches = HmsBasin.get_reaches("project.basin")
# Get/set parameters
loss_params = HmsBasin.get_loss_parameters("project.basin", "Subbasin1")
HmsBasin.set_loss_parameters("project.basin", "Subbasin1", curve_number=85)
Primary Sources
Code: hms_commander/HmsBasin.py - Complete API with docstrings
Examples: examples/03_project_dataframes.ipynb - Basin operations
Rules: .claude/rules/hec-hms/basin-files.md - Basin file patterns
File Format: tests/projects/.../02_Basin_File.md - HMS file structure
When to Use This Skill
- Extracting basin components for analysis
- Modifying loss method parameters (CN, deficit, constant rate)
- Updating transform parameters (lag time, time of concentration)
- Analyzing basin connectivity (downstream relationships)
- Cloning basins for QAQC comparison
Core Capabilities
1. Component Extraction
Returns DataFrames with basin elements:
get_subbasins()- Area, downstream, loss/transform methodsget_junctions()- Connectivity nodesget_reaches()- Channel routing elements
2. Parameter Operations
Get/set hydrologic parameters:
- Loss methods (Deficit & Constant, SCS CN, Green & Ampt, etc.)
- Transform methods (SCS UH, Clark UH, ModClark, etc.)
- Baseflow methods (Recession, Constant Monthly, etc.)
- Routing methods (Muskingum, Lag, ModPuls, etc.)
See: hms_commander/HmsBasin.py for complete method list
3. Clone Workflows
Non-destructive basin cloning:
- Preserves original basin
- Updates description with clone metadata
- Appears in HEC-HMS GUI
- Enables side-by-side QAQC comparison
See: .claude/rules/hec-hms/clone-workflows.md for CLB Engineering pattern
Common Workflows
Workflow 1: Extract All Components
subbasins = HmsBasin.get_subbasins("project.basin")
print(f"Found {len(subbasins)} subbasins")
print(f"Total area: {subbasins['Area'].sum()} sq mi")
Workflow 2: Bulk Parameter Update
# Update all curve numbers
subbasins = HmsBasin.get_subbasins("project.basin")
for name in subbasins.index:
HmsBasin.set_loss_parameters("project.basin", name, curve_number=85)
Workflow 3: Clone for QAQC
from hms_commander import init_hms_project, hms, HmsBasin
init_hms_project("project")
HmsBasin.clone_basin("Baseline", "Updated_Basin", hms_object=hms)
# Now modify Updated_Basin parameters for comparison
Reference Files
reference/get_subbasins.md- DataFrame structure and usagereference/loss_methods.md- All loss method parametersreference/transform_methods.md- All transform method parametersexamples/parameter_sweep.md- Bulk parameter updates
Related Skills
- cloning-hms-components - Complete clone workflow
- executing-hms-runs - Run after modifying parameters