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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

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.
nameparsing-basin-models
description|
Trigger keywordsbasin 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 methods
  • get_junctions() - Connectivity nodes
  • get_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 usage
  • reference/loss_methods.md - All loss method parameters
  • reference/transform_methods.md - All transform method parameters
  • examples/parameter_sweep.md - Bulk parameter updates
  • cloning-hms-components - Complete clone workflow
  • executing-hms-runs - Run after modifying parameters