Skip to content
hecras_compute_plans logo

Executing HEC-RAS Plans

hecras_compute_plans

Executes HEC-RAS plans using RasCmdr.compute_plan(), handles parallel execution across multiple plans, manages destination folders, and monitors real-time progress with callbacks. Use when running HEC-RAS simulations, computing plans, executing models, parallel workflows, setting up distributed c...

SKILL.md

Full skill instructions

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:

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

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

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 Guide

Use this decision matrix to select the appropriate execution mode:

ScenarioRecommended ModeRationale
Single plan, need full controlcompute_plan()Direct control, callback monitoring, parameter tuning
Single plan, quick runcompute_plan()Simplest API, minimal overhead
Multiple plans, debugging issuescompute_test_mode()Sequential execution, single folder, easier diagnosis
Multiple plans, production runscompute_parallel()Fastest throughput, worker isolation, parallel HDF writes
Distributed across machinescompute_parallel_remote()Scale-out to multiple computers
HEC-RAS 3.x-5.x legacyRasControlCOM-based automation (see rascontrol documentation)
Resume interrupted batchcompute_parallel(..., skip_existing=True)Skips completed plans
Scenario comparison studycompute_parallel() with dest_folderEach scenario in separate folder

Quick Decision Tree:

  1. How many plans? Single → compute_plan(), Multiple → continue
  2. Debugging? Yes → compute_test_mode(), No → continue
  3. 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:

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

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

# 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

SettingRecommendationWhen
clear_geompre=False2x-10x fasterGeometry unchanged
clear_geompre=TrueRequiredAfter ANY geometry edit
num_cores=2-4Best balanceMost models
num_cores=1-2Highest efficiencyResource-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:

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.

More Productivity & Planning skills

brainstorming logo
Productivity & Planning

brainstorming

Structured design dialogue that validates ideas before implementation begins.

295.4K 385.7K
View
ui-ux-pro-max logo
Productivity & Planning

ui-ux-pro-max

Comprehensive design intelligence for web and mobile UI/UX across 10 technology stacks.

133.1K 383.9K
View
writing-plans logo
Productivity & Planning

writing-plans

Comprehensive implementation plans for multi-step tasks, breaking down specs into bite-sized, testable steps.

295.4K 268K
View
using-superpowers logo
Productivity & Planning

using-superpowers

Introduction to the obra skills system with mandatory skill invocation rules and best practices.

295.4K 259.8K
View
executing-plans logo
Productivity & Planning

executing-plans

Execute a written implementation plan with critical review and task checkpoints.

295.4K 229.1K
View
dispatching-parallel-agents logo
Productivity & Planning

dispatching-parallel-agents

Delegate independent tasks to specialized agents working concurrently with isolated context.

295.4K 206.3K
View
using-git-worktrees logo
Productivity & Planning

using-git-worktrees

Isolated git worktrees with smart directory selection and safety verification.

295.4K 205.2K
View
webapp-testing logo
Productivity & Planning

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

179.7K 170.6K
View
content-strategy logo
Productivity & Planning

content-strategy

Plan searchable and shareable content that drives traffic, builds authority, and generates leads.

53.3K 150.9K
View
repo-intake-and-plan logo
Productivity & Planning

repo-intake-and-plan

README-first repository scanner that extracts commands and classifies reproduction candidates without executing them.

497 139.6K
View
marketing-ideas logo
Productivity & Planning

marketing-ideas

Brainstorm and prioritize marketing strategies tailored to your SaaS stage, budget, and goals.

53.3K 137.2K
View
site-architecture logo
Productivity & Planning

site-architecture

Plan and optimize your website's page hierarchy, navigation, URL structure, and internal linking.

53.3K 112.8K
View

Productivity AI tools

Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View
SaveDay logo
Productivity

SaveDay

Capture, organize, and utilize your knowledge effortlessly.

Free
View
Any Summary logo
Productivity

Any Summary

Instant Summaries of Audio & Video Interviews with AnySummary

Freemium
View
M
Productivity

Map This

Transform PDFs into engaging mind maps.

Freemium
View
ChatPDF logo
Productivity

ChatPDF

Chat with any PDF instantly

Free
View
I
Productivity

intellisay

Create an optimal daily plan using your voice

Paid
View
A
Productivity

Aurora AI

A productivity platform to centralize organizational knowledge and workflows with contextual AI assistance.

Paid
View
AskYourPDF logo
Productivity

AskYourPDF

AskYourPDF Pricing Plans: Tailored to Your Needs

Free
View