Executing HEC-RAS Plans

When the user asks to run HEC-RAS plans, use RasCmdr.computeplan() for single plans or RasCmdr.computeparallel() for multiple. Read the primary sources below for complete parameter details.

Primary Sources

1. Execution Patterns (AGENTS.md)

Location: ras_commander/AGENTS.md

Read these sections:

• "Plan Execution" - Core execution methods and parameters
• "Execution Modes" - Four modes: single, parallel, sequential, remote
• "Plan Execution Parameters" - Complete parameter reference
• "Common Workflow Pattern" - Initialize, Execute, Extract

Key execution modes:

# Single plan
RasCmdr.compute_plan("01", dest_folder="run1", num_cores=4)

# Parallel local
RasCmdr.compute_parallel(["01", "02", "03"], max_workers=3)

# Sequential test
RasCmdr.compute_test_mode(["01", "02"])

2. Working Examples (Jupyter Notebooks)

Core execution notebooks:

• examples/110singleplan_execution.ipynb - Complete single plan workflow
• examples/111executingplan_sets.ipynb - Plan sets and batch processing
• examples/112sequentialplan_execution.ipynb - Test mode execution
• examples/113parallelexecution.ipynb - Parallel execution with performance analysis

Advanced workflows:

• examples/500remoteexecution_psexec.ipynb - Distributed execution
• Real-time monitoring examples (search for stream_callback usage)

3. Code Documentation (Docstrings)

Location: ras_commander/RasCmdr.py

Read these docstrings:

• RasCmdr.compute_plan() - Lines 139-250+ (comprehensive parameter docs)
• RasCmdr.compute_parallel() - Parallel execution details
• RasCmdr.computetestmode() - Sequential debugging mode

Callback protocol: ras_commander/callbacks.py

• ExecutionCallback - Protocol definition
• ConsoleCallback, FileLoggerCallback, ProgressBarCallback - Implementations

Quick Reference

Single Plan Execution

Basic pattern:

from ras_commander import init_ras_project, RasCmdr

# Initialize
init_ras_project("path/to/project", "7.0")

# Execute
RasCmdr.compute_plan("01")

With destination folder (preserves original):

RasCmdr.compute_plan("01", dest_folder="computation_folder")

With monitoring:

from ras_commander.callbacks import ConsoleCallback

RasCmdr.compute_plan(
    "01",
    stream_callback=ConsoleCallback(verbose=True)
)

Key parameters:

• plan_number - "01", "02", etc. (use strings)
• dest_folder - None = in-place, path = separate folder
• num_cores - CPU cores to use (None = plan default)
• clear_geompre - True after geometry changes
• verify - True to check completion
• skip_existing - True to resume interrupted runs
• stream_callback - Real-time monitoring object

Parallel Execution

Execute multiple plans:

# All plans with 3 workers
RasCmdr.compute_parallel(max_workers=3, num_cores=2)

# Specific plans
RasCmdr.compute_parallel(
    plans_to_run=["01", "02", "03"],
    max_workers=3,
    num_cores=2
)

Worker allocation:

• max_workers - Parallel plan executions
• num_cores - Cores per plan
• Total cores used = maxworkers × numcores
• Optimal: 2-4 cores per worker, workers ≤ physical cores / num_cores

Sequential Test Mode

For debugging:

# Run plans one at a time in test folder
RasCmdr.compute_test_mode(["01", "02", "03"])

Difference from parallel:

• ONE plan at a time (not simultaneous)
• Single test folder (not multiple workers)
• Easier to debug issues

Mode Selection

To choose between execution modes (single, parallel, sequential, remote, legacy), invoke the hecrasplanexecution skill for decision trees, mode selection matrices, and parameter recommendations.

Read .claude/rules/hec-ras/execution.md for complete mode documentation.

Orchestrator Integration

Workflow: Inspector → Execute → Analyze

For complex projects, chain execution with inspection and analysis in this order:

1. Project Inspector → Understand project structure
2. Mode Selection   → Choose execution approach
3. Execute          → Run plans
4. Results Analyst  → Interpret outputs

Integration with Project Inspector

Before executing unfamiliar projects, gather intelligence first:

# Step 1: Inspect project (via hecras-project-inspector agent or manual)
# - Get plan count and types
# - Identify dependencies between plans
# - Check geometry complexity (1D vs 2D vs mixed)
# - Review execution recommendations

# Step 2: Based on inspection, select mode
# Example: Inspector finds 5 independent 2D plans
plans = ["01", "02", "03", "04", "05"]
mode = "compute_parallel"  # Independent plans → parallel

# Step 3: Execute with appropriate parameters
RasCmdr.compute_parallel(
    plans_to_run=plans,
    max_workers=3,      # Based on system resources
    num_cores=4,        # 2D models benefit from multiple cores
    verify=True
)

# Step 4: Dispatch to results analysis
# - Extract WSE, velocity, depth from HDF files
# - Generate comparison plots
# - Create summary report

Chaining with Other Skills

Invoke these upstream skills before execution:

• hecrasparsegeometry -- After geometry modifications
• dssreadboundary-data -- After validating boundary conditions
• usgsintegrategauges -- After setting up gauge-based boundaries

Invoke these downstream skills after execution:

• hecrasextractresults -- Parse HDF outputs
• Results visualization -- Generate plots and maps
• Validation workflows -- Compare to observed data

Multi-Project Orchestration

For workflows spanning multiple HEC-RAS projects:

from ras_commander import RasPrj, init_ras_project, RasCmdr

# Create separate project contexts
projects = {}
for project_name in ["upstream", "downstream", "tributary"]:
    projects[project_name] = RasPrj()
    init_ras_project(
        f"path/to/{project_name}",
        "7.0",
        ras_object=projects[project_name]
    )

# Execute in dependency order
RasCmdr.compute_plan("01", ras_object=projects["upstream"])
RasCmdr.compute_plan("01", ras_object=projects["tributary"])
RasCmdr.compute_plan("01", ras_object=projects["downstream"])

Critical: Pass ras_object when working with multiple projects. See .claude/rules/python/ras-commander-patterns.md for context object discipline.

Common Patterns

Pattern: Preserve Original Project

# Run in separate folder, leave original untouched
RasCmdr.compute_plan(
    "01",
    dest_folder="results/run_2024_12_11",
    overwrite_dest=True,
    verify=True
)

Pattern: Geometry Modification Workflow

from ras_commander.RasGeo import RasGeo

# Modify geometry
RasGeo.update_mannings_n(geom_file="g01", landcover_map={...})

# Run with forced reprocessing
RasCmdr.compute_plan("01", clear_geompre=True)  # CRITICAL

Pattern: Batch Scenario Processing

scenarios = {
    "baseline": {"plan": "01", "dest": "output/baseline"},
    "mitigation": {"plan": "02", "dest": "output/mitigation"},
}

for name, config in scenarios.items():
    RasCmdr.compute_plan(
        config["plan"],
        dest_folder=config["dest"],
        verify=True
    )

Pattern: Skip Already Completed

# Resume interrupted batch run
for plan in ["01", "02", "03"]:
    RasCmdr.compute_plan(
        plan,
        skip_existing=True,  # Skip if already complete
        verify=True
    )

Real-Time Monitoring

Console Output

from ras_commander.callbacks import ConsoleCallback

callback = ConsoleCallback(verbose=True)
RasCmdr.compute_plan("01", stream_callback=callback)

Output example:

[Plan 01] Starting execution...
[Plan 01] Geometry Preprocessor Version 6.6
[Plan 01] Computing Plan: 01
[Plan 01] SUCCESS in 45.2s

File Logging

from ras_commander.callbacks import FileLoggerCallback
from pathlib import Path

callback = FileLoggerCallback(output_dir=Path("logs"))
RasCmdr.compute_plan("01", stream_callback=callback)
# Creates: logs/plan_01_execution.log

Progress Bar

from ras_commander.callbacks import ProgressBarCallback

# Requires: pip install tqdm
callback = ProgressBarCallback()
RasCmdr.compute_plan("01", stream_callback=callback)

Custom Callback

from ras_commander.callbacks import ExecutionCallback

class AlertCallback(ExecutionCallback):
    def on_exec_complete(self, plan_number: str, success: bool, duration: float):
        send_email(subject=f"Plan {plan_number} {'SUCCESS' if success else 'FAILED'}")

RasCmdr.compute_plan("01", stream_callback=AlertCallback())

Available callback methods (all optional):

• onprepstart() - Before geometry preprocessing
• onprepcomplete() - After preprocessing
• onexecstart() - HEC-RAS subprocess starts
• onexecmessage() - Each .bco file message (real-time)
• onexeccomplete() - Execution finishes
• onverifyresult() - After verification (if verify=True)

Thread safety: Use SynchronizedCallback wrapper for parallel execution

Verification

Return Value Check

success = RasCmdr.compute_plan("01", verify=True)
if not success:
    print("Execution failed or incomplete")

Parse Compute Messages

from ras_commander.hdf import HdfResultsPlan

messages = HdfResultsPlan.get_compute_messages("01")
if "Complete Process" in messages:
    print("Success!")

Validate Results

wse = HdfResultsPlan.get_wse("01", time_index=-1)
if wse is not None:
    print(f"WSE range: {wse.min():.2f} to {wse.max():.2f} ft")

Performance Optimization

Read .claude/rules/hec-ras/execution.md for detailed performance guidance.

Troubleshooting

Plan doesn't execute - Check: initrasproject() called? Plan in ras.plan_df? HEC-RAS installed? Write permissions?

HDF not created - Enable ConsoleCallback(verbose=True), check compute messages, try HEC-RAS GUI manually.

Debug command:

from ras_commander import ras
print(f"Project: {ras.project_folder}")
print(f"RAS: {ras.ras_exe_path}")
print(ras.plan_df)

Cross-References

Rules (follow these):

• .claude/rules/hec-ras/execution.md -- Execution mode parameters and performance tuning
• .claude/rules/python/static-classes.md -- RasCmdr static method pattern
• .claude/rules/python/decorators.md -- @logcall and @standardizeinput usage

Agents (delegate when needed):

• hecras-general-agent -- Delegate for full inspect-plan-execute-analyze workflows
• hecras-project-inspector -- Delegate for project analysis before execution

Skills (related workflows):

• hecrasplanexecution -- Use upstream for execution mode selection and parameter tuning
• hecrascomputeremote -- Use for distributed remote execution
• hecrascomputerascontrol -- Use for legacy COM-based execution
• hecrasextractresults -- Use downstream to extract results after execution
• hecrasparsecompute-messages -- Use downstream to verify execution status

Primary sources:

• ras_commander/AGENTS.md -- Plan execution section with complete parameter reference
• ras_commander/RasCmdr.py -- Source code with comprehensive docstrings
• examples/110singleplan_execution.ipynb -- Single plan workflow
• examples/113parallelexecution.ipynb -- Parallel execution workflow