name

managing-hms-versions

description

Manages HEC-HMS version differences (3.x vs 4.x), handles Python 2/3 compatibility, detects HMS installations, and generates version-appropriate Jython scripts. Use when working with legacy HMS 3.x projects, upgrading models from 3.x to 4.x, testing across multiple HMS versions, or troubleshooting version-specific issues. Handles 32-bit vs 64-bit architecture differences, memory limits, and script syntax variations. Trigger keywords: HMS version, HMS 3.x, HMS 4.x, legacy, upgrade, Python 2 compatible, 32-bit, 64-bit, version detection, multi-version testing.

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 - Version detection and script generation

Rules: .claude/rules/hec-hms/version-support.md - Complete differences

Examples: examples/01_multi_version_execution.ipynb - Multi-version workflow

Task Agent: hms_agents/update_3_to_4/ - Automated 3.x → 4.x upgrade

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

Version	Support	Architecture	Python	Notes
HMS 4.4.1+	✅ Full	64-bit	Python 3	Recommended
HMS 3.3-3.5	✅ Full	32-bit	Python 2	Requires `python2_compatible=True`
HMS 4.0-4.3	❌	64-bit	Python 3	Legacy classpath not supported
HMS 3.0-3.2	❓	32-bit	Python 2	Untested

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

Critical Differences

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

Install Path: C:\Program Files (x86)\HEC\HEC-HMS\3.x\ **Max Memory**: ~1.3 GB **Java**: java/bin/java.exe Python: Jython 2.5 (Python 2 syntax)

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\ **Max Memory**: 32+ GB **Java**: jre/bin/java.exe Python: Jython 2.7 (Python 3 syntax)

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 for complete workflow

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 for HMS 3.x

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