Executing HEC-RAS Plans

This skill helps you execute HEC-RAS plans using ras-commander. It serves as a navigator to primary sources containing comprehensive documentation and working examples.

Primary Sources

1. Execution Patterns (CLAUDE.md)

Location: C:\GH\ras-commander\ras_commander\CLAUDE.md

See 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:

python

# 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: C:\GH\ras-commander\ras_commander\RasCmdr.py

Read docstrings for:

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

Callback protocol: C:\GH\ras-commander\ras_commander\callbacks.py

ExecutionCallback - Protocol definition
ConsoleCallback, FileLoggerCallback, ProgressBarCallback - Implementations

Quick Reference

Single Plan Execution

Basic pattern:

python

from ras_commander import init_ras_project, RasCmdr

# Initialize
init_ras_project(r"C:\Models\MyProject", "6.6")

# Execute
RasCmdr.compute_plan("01")

With destination folder (preserves original):

python

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

With monitoring:

python

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:

python

# 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:

python

# 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 Guide

Use this decision matrix to select the appropriate execution mode:

Scenario	Recommended Mode	Rationale
Single plan, need full control	`compute_plan()`	Direct control, callback monitoring, parameter tuning
Single plan, quick run	`compute_plan()`	Simplest API, minimal overhead
Multiple plans, debugging issues	`compute_test_mode()`	Sequential execution, single folder, easier diagnosis
Multiple plans, production runs	`compute_parallel()`	Fastest throughput, worker isolation, parallel HDF writes
Distributed across machines	`compute_parallel_remote()`	Scale-out to multiple computers
HEC-RAS 3.x-5.x legacy	`RasControl`	COM-based automation (see rascontrol documentation)
Resume interrupted batch	`compute_parallel(..., skip_existing=True)`	Skips completed plans
Scenario comparison study	`compute_parallel()` with dest_folder	Each scenario in separate folder

Quick Decision Tree:

How many plans? Single → compute_plan(), Multiple → continue
Debugging? Yes → compute_test_mode(), No → continue
Multiple machines? Yes → compute_parallel_remote(), No → compute_parallel()

See: .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:

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:

python

# 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

Execution typically follows these upstream skills:

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

Execution typically precedes these downstream skills:

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:

python

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"C:/Models/{project_name}",
        "6.6",
        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

python

# 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

python

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

python

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

python

# 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

python

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

python

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

python

from ras_commander.callbacks import ProgressBarCallback

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

Custom Callback

python

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

python

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

Parse Compute Messages

python

from ras_commander.hdf import HdfResultsPlan

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

Validate Results

python

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

See: .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:

python

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

Remember: This skill is a navigator. For detailed documentation, comprehensive examples, and complete API reference, always consult the Primary Sources section above.

Search AI Tools

hecras_compute_plans

Install this agent skill to your Project

SKILL.md

Executing HEC-RAS Plans

Primary Sources

1. Execution Patterns (CLAUDE.md)

2. Working Examples (Jupyter Notebooks)

3. Code Documentation (Docstrings)

Quick Reference

Single Plan Execution

Parallel Execution

Sequential Test Mode

Mode Selection Guide

Orchestrator Integration

Workflow: Inspector → Execute → Analyze

Integration with Project Inspector

Chaining with Other Skills

Multi-Project Orchestration

Common Patterns

Pattern: Preserve Original Project

Pattern: Geometry Modification Workflow

Pattern: Batch Scenario Processing

Pattern: Skip Already Completed

Real-Time Monitoring

Console Output

File Logging

Progress Bar

Custom Callback

Verification

Return Value Check

Parse Compute Messages

Validate Results

Performance Optimization

Troubleshooting