Managing HMS Versions

Quick Start

from hms_commander import HmsJython

# Auto-detect HMS installations
hms_exe = HmsJython.find_hms_executable()
print(f"Found: {hms_exe}")

# Generate version-appropriate script
is_3x = "(x86)" in str(hms_exe)  # 32-bit = HMS 3.x
script = HmsJython.generate_compute_script(
    project_path="project",
    run_name="Run 1",
    python2_compatible=is_3x  # Critical for 3.x!
)

# Execute with detected version
success, stdout, stderr = HmsJython.execute_script(script, hms_exe)

Primary Sources

Code:

hms_commander/HmsJython.py

Rules:

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

Examples:

examples/01_multi_version_execution.ipynb

Task Agent:

hms_agents/update_3_to_4/

When to Use This Skill

• Working with legacy HMS 3.x projects
• Upgrading models from 3.x to 4.x
• Testing across multiple HMS versions
• Troubleshooting version-specific script errors
• Setting up multi-version test environments
• Understanding memory and architecture limitations

Supported Versions

python2_compatible=True

See:

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

Critical Differences

HMS 3.x (32-bit, Python 2)

Install Path:

C:\Program Files (x86)\HEC\HEC-HMS\3.x\

java/bin/java.exe

Script Generation:

script = HmsJython.generate_compute_script(
    project_path=path,
    run_name=run,
    python2_compatible=True  # MUST be True for 3.x!
)

Python 2 Syntax:

print "Computing run"  # No parentheses

HMS 4.x (64-bit, Python 3)

Install Path:

C:\Program Files\HEC\HEC-HMS\4.x\

jre/bin/java.exe

Script Generation:

script = HmsJython.generate_compute_script(
    project_path=path,
    run_name=run
    # python2_compatible=False (default)
)

Python 3 Syntax:

print(f"Computing {run_name}")  # Parentheses required

Core Capabilities

1. Version Detection

# Auto-detect from common install locations
hms_exe = HmsJython.find_hms_executable()

# Check if 3.x or 4.x
if "(x86)" in str(hms_exe):
    print("HMS 3.x detected (32-bit)")
    python2_compatible = True
else:
    print("HMS 4.x detected (64-bit)")
    python2_compatible = False

2. Version-Appropriate Script Generation

script = HmsJython.generate_compute_script(
    project_path=project_path,
    run_name=run_name,
    python2_compatible=python2_compatible
)

HmsJython handles syntax differences automatically.

3. Multi-Version Testing

from hms_commander import HmsExamples

# List installed versions
versions = HmsExamples.list_versions()
print(f"Found HMS versions: {versions}")

# Test across all versions
for version in versions:
    HmsExamples.extract_project("tifton", version=version)
    # Run tests for this version

See:

examples/01_multi_version_execution.ipynb

4. Version Upgrade

Automated approach (Recommended):

# Use update_3_to_4 task agent
# See: hms_agents/update_3_to_4/README.md

Manual approach: Open in HMS 4.x GUI, save (converts file format)

Common Workflows

Workflow 1: Legacy 3.x Project

# 1. Detect HMS 3.x
hms_3x_path = r"C:\Program Files (x86)\HEC\HEC-HMS\3.5"

# 2. Generate Python 2 script
script = HmsJython.generate_compute_script(
    project_path=r"C:\Projects\old_project",
    run_name="Run 1",
    python2_compatible=True
)

# 3. Execute
success, stdout, stderr = HmsJython.execute_script(
    script_content=script,
    hms_exe_path=hms_3x_path
)

# 4. Check for Python 2 syntax errors
if "SyntaxError" in stderr:
    print("Forgot python2_compatible=True!")

Workflow 2: Multi-Version Testing

for version in ["3.5", "4.11", "4.13"]:
    # Extract version-specific example
    HmsExamples.extract_project("tifton", version=version)

    # Detect Python 2 vs 3
    python2 = version.startswith("3.")

    # Generate script
    script = HmsJython.generate_compute_script(
        f"tifton_{version}/tifton",
        "1970_simulation",
        python2_compatible=python2
    )

    # Execute
    hms_exe = HmsExamples.get_hms_exe(version)
    success, stdout, stderr = HmsJython.execute_script(script, hms_exe)

    print(f"HMS {version}: {'✅' if success else '❌'}")

Workflow 3: Upgrade 3.x to 4.x

Use the update_3_to_4 task agent:

# See: hms_agents/update_3_to_4/AGENT.md
from hms_agents.update_3_to_4 import VersionUpgrader

upgrader = VersionUpgrader(
    project_3x="path/to/hms3x/project",
    project_4x="path/to/hms4x/project"
)

verdict = upgrader.execute()
upgrader.export_modeling_log("UPGRADE_LOG.md")

Troubleshooting

Issue: Python 2 Syntax Error

Error:

SyntaxError: invalid syntax

Cause: Forgot

python2_compatible=True

Fix:

script = HmsJython.generate_compute_script(
    project_path=path,
    run_name=run,
    python2_compatible=True  # Add this!
)

Issue: Memory Error (HMS 3.x)

Error:

OutOfMemoryError

Cause: HMS 3.x limited to ~1.3 GB (32-bit)

Fix: Upgrade to HMS 4.x (64-bit) for large models

Issue: HMS Not Found

Error:

FileNotFoundError: HMS executable not found

Fix:

# Specify path manually
hms_exe = r"C:\Program Files\HEC\HEC-HMS\4.11\HEC-HMS.cmd"
HmsJython.execute_script(script, hms_exe_path=hms_exe)

Reference Files

• reference/hms-3x-vs-4x.md

  - Complete differences table

• reference/python2-compatibility.md

  - Script syntax differences

• examples/legacy-projects.md

  - HMS 3.x workflow examples

Related Skills

• executing-hms-runs - Uses version detection for execution
• cloning-hms-components - Clone before upgrading