Executing HEC-HMS Runs

Quick Start

from hms_commander import init_hms_project, HmsCmdr

# Initialize project
init_hms_project(r"C:\Projects\watershed")

# Execute single run
HmsCmdr.compute_run("Run 1")

# Execute multiple runs in parallel
HmsCmdr.compute_parallel(["Run 1", "Run 2", "Run 3"], max_workers=2)

Primary Sources

Code (Authoritative API):

• hms_commander/HmsCmdr.py - Execution engine with complete docstrings
• hms_commander/HmsJython.py - Script generation and version detection

Examples (Working Demonstrations):

• examples/01_multi_version_execution.ipynb - Complete workflow
• examples/04_hms_workflow.ipynb - End-to-end simulation

Rules (Patterns & Decisions):

• .claude/rules/hec-hms/execution.md - Execution patterns
• .claude/rules/hec-hms/version-support.md - HMS 3.x vs 4.x differences

When to Use This Skill

Trigger Scenarios:

• User says "run HMS simulation"
• User says "execute this model"
• User says "compute all runs in parallel"
• User mentions "Jython script"
• Working with HMS 3.x (requires Python 2 compatibility)
• Need to execute batch simulations
• Setting up automated workflows

Core Capabilities

1. Single Run Execution

Pattern: Initialize → Compute → Verify

See reference/compute_run.md for complete API details.

Key Decision: When to use compute_run() vs compute_test_mode()

• Use compute_run() for actual simulation
• Use compute_test_mode() to validate setup without running

2. Parallel Execution

Pattern: Batch runs across multiple workers

See reference/parallel.md for parallel execution strategies.

Key Decision: How many workers?

• Default: 2 workers (safe for most systems)
• CPU-bound: Use os.cpu_count() - 1
• Memory-constrained: Use 1 worker (sequential)
• Large models: Consider memory per run × workers

3. Jython Script Generation

Pattern: Generate version-appropriate script → Execute via HMS

See reference/jython.md for script generation details.

Critical Decision: HMS 3.x vs 4.x

• HMS 3.x: MUST use python2_compatible=True
• HMS 4.x: Use default (Python 3 syntax)
• Auto-detection: Check install path contains "(x86)" = 3.x

HMS Version Awareness

This skill handles BOTH HMS 3.x and 4.x:

Aspect	HMS 3.x	HMS 4.x
Architecture	32-bit	64-bit
Python Syntax	Python 2 (print "x")	Python 3 (print("x"))
Script Flag	python2_compatible=True	Default
Max Memory	~1.3 GB	32+ GB
Install Path	Program Files (x86)	Program Files

See: .claude/rules/hec-hms/version-support.md for complete differences

Common Workflows

Workflow 1: Basic Execution

from hms_commander import init_hms_project, HmsCmdr

init_hms_project(r"C:\Projects\watershed")
HmsCmdr.compute_run("Run 1")

See: examples/basic-run.md for complete walkthrough

Workflow 2: Batch Execution (Sequential)

runs = ["Baseline", "Alternative_1", "Alternative_2"]
HmsCmdr.compute_batch(runs)

See: examples/batch-runs.md for batch strategies

Workflow 3: Parallel Execution

runs = ["Run_1", "Run_2", "Run_3", "Run_4"]
HmsCmdr.compute_parallel(runs, max_workers=2)

See: reference/parallel.md for worker allocation

Workflow 4: Legacy HMS 3.x Project

from hms_commander import HmsJython

# Generate Python 2 compatible script
script = HmsJython.generate_compute_script(
    project_path=r"C:\Projects\old_project",
    run_name="Run 1",
    python2_compatible=True  # CRITICAL for HMS 3.x!
)

# Execute with HMS 3.x
success, stdout, stderr = HmsJython.execute_script(
    script_content=script,
    hms_exe_path=r"C:\Program Files (x86)\HEC\HEC-HMS\3.5"
)

See: .claude/rules/hec-hms/version-support.md for legacy workflows

Troubleshooting

Common Issues:

1. HMS Not Found: See reference/jython.md#finding-hms
2. Memory Errors: See reference/jython.md#memory-allocation
3. Python 2 Syntax Errors: See .claude/rules/hec-hms/version-support.md
4. Parallel Execution Hangs: See reference/parallel.md#debugging

Integration Points

Before Execution:

• Use HmsBasin to modify parameters (see parsing-basin-models skill)
• Use HmsMet to update precipitation (see updating-met-models skill)
• Use HmsControl to set time window (see .claude/rules/hec-hms/control-files.md)

After Execution:

• Use HmsDss to extract results (see extracting-dss-results skill)
• Use HmsResults for analysis (see .claude/rules/hec-hms/dss-operations.md)

Reference Files

Detailed API Documentation (load on-demand):

• reference/compute_run.md - HmsCmdr.compute_run() complete API
• reference/parallel.md - Parallel execution strategies
• reference/jython.md - Script generation and execution
• reference/troubleshooting.md - Common issues and solutions

Complete Examples (working code):

• examples/basic-run.md - Simple single run
• examples/batch-runs.md - Sequential batch execution
• examples/parallel-runs.md - Parallel execution with worker allocation
• examples/legacy-3x.md - HMS 3.x compatibility

Testing This Skill

Use real HMS projects for testing:

from hms_commander import HmsExamples

# Extract example project
HmsExamples.extract_project("tifton")

# Test execution
init_hms_project("tifton/tifton")
HmsCmdr.compute_run("1970_simulation")

See: .claude/rules/testing/tdd-approach.md for testing philosophy

Key Patterns (Not in Primary Sources)

Pattern 1: Destination Folder Management

HMS creates output in the project folder. For organized results:

# Results go to project_folder/results/RUN_<run_name>.results
# DSS file location specified in .run file

Decision: HMS writes to project folder, not a separate destination folder like RAS.

Pattern 2: Version Auto-Detection

from pathlib import Path

hms_path = Path(r"C:\Program Files (x86)\HEC\HEC-HMS\3.5")
is_3x = "(x86)" in str(hms_path)  # 32-bit = HMS 3.x
python2_compatible = is_3x

Decision: Use install path pattern for version detection, not HMS version file.

Pattern 3: Error Handling

try:
    HmsCmdr.compute_run("Run 1")
except Exception as e:
    # Check HMS log file for details
    log_file = hms.project_folder / f"RUN_Run 1.log"
    if log_file.exists():
        print(log_file.read_text())
    raise

Decision: HMS errors appear in log files, check those for diagnostics.

Related Skills

• parsing-basin-models - Modify parameters before execution
• updating-met-models - Update precipitation before execution
• extracting-dss-results - Process outputs after execution
• cloning-hms-components - Create QAQC comparison runs
• managing-hms-versions - Multi-version testing workflows

---

Navigation: This skill points to primary sources. For complete API details, read the code docstrings in hms_commander/HmsCmdr.py and hms_commander/HmsJython.py.