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

Key Decision: When to use

compute_run()

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

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

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:

print "x"

print("x")

python2_compatible=True

Program Files (x86)

Program Files

See:

.claude/rules/hec-hms/version-support.md

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

Workflow 2: Batch Execution (Sequential)

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

See:

examples/batch-runs.md

Workflow 3: Parallel Execution

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

See:

reference/parallel.md

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

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

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

hms_commander/HmsJython.py