Executing HEC-RAS Plans

When the user asks to run HEC-RAS plans, use RasCmdr.compute_plan() for single plans or RasCmdr.compute_parallel() 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/110_single_plan_execution.ipynb - Complete single plan workflow
• examples/111_executing_plan_sets.ipynb - Plan sets and batch processing
• examples/112_sequential_plan_execution.ipynb - Test mode execution
• examples/113_parallel_execution.ipynb - Parallel execution with performance analysis

Advanced workflows:

• examples/500_remote_execution_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.compute_test_mode() - 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 = max_workers × num_cores
• 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 hecras_plan_execution 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:

• hecras_parse_geometry -- After geometry modifications
• dss_read_boundary-data -- After validating boundary conditions
• usgs_integrate_gauges -- After setting up gauge-based boundaries

Invoke these downstream skills after execution:

• hecras_extract_results -- 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):

• on_prep_start() - Before geometry preprocessing
• on_prep_complete() - After preprocessing
• on_exec_start() - HEC-RAS subprocess starts
• on_exec_message() - Each .bco file message (real-time)
• on_exec_complete() - Execution finishes
• on_verify_result() - 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

Setting	Recommendation	When
clear_geompre=False	2x-10x faster	Geometry unchanged
clear_geompre=True	Required	After ANY geometry edit
num_cores=2-4	Best balance	Most models
num_cores=1-2	Highest efficiency	Resource-limited

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

Troubleshooting

Plan doesn't execute - Check: init_ras_project() 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 -- @log_call and @standardize_input 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):

• hecras_plan_execution -- Use upstream for execution mode selection and parameter tuning
• hecras_compute_remote -- Use for distributed remote execution
• hecras_compute_rascontrol -- Use for legacy COM-based execution
• hecras_extract_results -- Use downstream to extract results after execution
• hecras_parse_compute-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/110_single_plan_execution.ipynb -- Single plan workflow
• examples/113_parallel_execution.ipynb -- Parallel execution workflow