shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

executing-hms-runs

使用HmsCmdr.compute_run()执行HEC-HMS模拟，处理多个运行之间的并行执行，并管理Jython脚本生成。当运行HMS模拟、执行运行、计算模型或设置并行计算工作流时，请使用此功能。处理HMS 3.x和4.x版本差异、Python 2/3兼容性、目标文件夹管理和多运行协调。触发关键词：运行模拟、执行HMS、计算运行、并行执行、批量运行、Jython脚本、HMS 3.x、HMS 4.x、Python 2兼容。

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

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.