ras-commander 0.89.1
A Python library for automating HEC-RAS 6.x operations
Requires Python: >=3.10

# RAS Commander (ras-commander)

<p align="center">
  <img src="ras-commander_logo.svg" width=70%>
</p>

RAS Commander is a Python library for automating HEC-RAS operations, providing a set of tools to interact with HEC-RAS project files, execute simulations, and manage project data. This library was initially conceptualized in the Australian Water School course "AI Tools for Modelling Innovation", and subsequently expanded to cover much of the basic functionality of the HECRASController COM32 interface using open-source python libraries and extent python tooling to the 6.x series of HEC-RAS.  This library uses a Test Driven Development strategy, leveraging the publicly-available HEC-RAS Example projects to create repeatable demonstration examples.  The "Commmander" moniker is inspired by the "Command Line is All You Need" approach to HEC-RAS automation that was first implemented in the HEC-Commander Tools repository.  

**December 2025 Update:** RAS Commander now supports a fully agentic engineering experience using CLI coding agents and agent SDK's to extend library functions and assist H&H engineers with common modeling tasks such as importing external data, performing QAQC reviews, validating project file paths, AEP and historic storm modeling, or any of the other functionality supported by, or imminently extendable from existing functions, in composable long form agentic workflows.  Agents are instructed to work with humans in the loop: demonstrating their steps, maintaining modeling logs, and creating reproducible deliverables that can be externally verified directly in the HEC-RAS GUI.  Long term memory is arranged in a heirarchical knowledge structure with progressive disclosure. Agents, skills, rules and cognitive memory systems are included to assist the user with solidifying LLM-written code into deterministic workflows in a continual learning looop, along with a file-based memory system to assist with long term task planning and execution across many conversations and subagents. 

## LLM Forward Engineering

This library was developed using an **LLM Forward** approach - focusing on Large Language Models to accelerate engineering workflows while maintaining professional responsibility and verifiability. See [LLM Forward Development](https://ras-commander.readthedocs.io/en/latest/development/llm-development/) for philosophy and best practices.

[![Documentation Status](https://readthedocs.org/projects/ras-commander/badge/?version=latest)](https://ras-commander.readthedocs.io/en/latest/?badge=latest)

**[ðŸ“– Full Documentation](https://ras-commander.readthedocs.io/)** | *[ASFPM Presentation](https://drive.google.com/file/d/1kX0twae8NrpLwR0iQ0Dmd8zAXdq-pYXD/view)*

## Repository Author

**[William Katzenmeyer, P.E., C.F.M.](https://engineeringwithllms.info)**
Owner & Vice President, [CLB Engineering Corporation](https://clbengineering.com/)

This library demonstrates the **LLM Forward** approach to engineering software development - a framework emphasizing professional responsibility first while leveraging large language models to accelerate insight and automation.


## Don't Ask Me, Ask a GPT!

This repository has several methods of interaction with Large Language Models and LLM-Assisted Coding built right in:

1. **[Claude Code Agentic Infrastructure](https://github.com/gpt-cmdr/ras-commander/tree/main/.claude)**: A comprehensive cognitive infrastructure built for [Anthropic's Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI tool. The `.claude/` directory contains specialized **agents** (domain experts for HDF analysis, geometry parsing, USGS integration, remote execution), **skills** (workflow templates for common tasks like plan execution and results extraction), **rules** (auto-loaded coding patterns and best practices), and **commands** (slash commands for common operations). The root `CLAUDE.md` provides strategic guidance while `AGENTS.md` files throughout the codebase offer scoped context. This hierarchical knowledge system enables Claude Code to understand ras-commander's static class patterns, HEC-RAS domain concepts, and testing approaches - making it an effective pair programming partner for hydraulic engineering automation. Just open the repository in Claude Code (`claude` in terminal) to leverage the full infrastructure.

2. **[Third-Party AI Framework Support](https://github.com/gpt-cmdr/ras-commander/tree/main/.cursor/rules)**: The repository supports common AI coding frameworks including **Cursor IDE** (`.cursor/rules/`), **AGENTS.md standard** (scoped guidance files throughout codebase), and other LLM-assisted development tools. All framework configurations point to the authoritative `CLAUDE.md` and `.claude/rules/` documentation - no content duplication. Just open the repository in your preferred AI-assisted IDE to leverage the built-in context.

3. **[Full Documentation on ReadTheDocs](https://ras-commander.readthedocs.io/)**: Comprehensive API documentation, user guides, and example notebooks. Includes installation guide, quick start, and detailed class references.

4. **[RAS Commander Library Assistant on ChatGPT](https://chatgpt.com/g/g-TZRPR3oAO-ras-commander-library-assistant)** _(Deprecated - CLI agents preferred)_: This GPT is no longer actively maintained. For the best experience, use Claude Code or other CLI agents with the repository's built-in cognitive infrastructure.


## Background

The ras-commander library emerged from the initial test-bed of LLM Forward engineering represented by the [HEC-Commander tools](https://github.com/gpt-cmdr/HEC-Commander) Python notebooks. These notebooks served as a proof of concept, demonstrating the value proposition of automating HEC-RAS operations through responsible LLM adoption.

In 2024, William Katzenmeyer taught a series of progressively more complex webinars demonstrating how to use simple prompting, example projects, and natural language instruction to effectively code HEC-RAS automation workflows, culminating in a 6-hour course. The library published for utilization in that course, [awsrastools](https://github.com/gpt-cmdr/awsrastools), served as a foundation of examples which were iteratively extended into the full RAS-Commander library using LLM Forward development principles.

Unlike the original notebook by the same name, this library is not focused on parallel execution across multiple machines. Instead, it is focused on providing a general-purpose python API for interacting with HEC-RAS projects, and building an AI-friendly library that will allow new users to quickly scaffold their own workflows into a python script. Example notebooks are provided, but the intention is to empower engineers, software developers, GIS personnel and data analysts to more easily access and interact with HEC-RAS data in a python environment. Also, by publishing these examples publicly, with complete working code examples and LLM optimization, future users can readily rewrite the key functions of the library for inclusion into their own preferred libraries, languages or return formats.

## Features

If you've ever read the book "Breaking the HEC-RAS Code" by Chris Goodell, this library is intended to be an AI-coded, pythonic library that provides a modern alternative to the HECRASController API.  By leveraginging modern python features libraries such as pandas, geopandas and H5Py (favoring HDF data sources wherever practicable) this library builds functionality around HEC-RAS 6.2+ while maintaining as much forward compatibilty as possible with HEC-RAS 2025.  

HEC-RAS Project Management & Execution
- Multi-project handling with parallel and sequential execution
- Command-line execution integration
- **Smart execution skip** (NEW in v0.88.0) - automatic staleness detection, skips re-runs when results are current
- Project folder management and organization
- Multi-core processing optimization
- Progress tracking and logging
- Execution error handling and recovery

Legacy Version Support (NEW in v0.81.0)
- **RasControl class** for HEC-RAS 3.x-4.x via COM interface (HECRASController)
- ras-commander style API - use plan numbers, not file paths
- Extract steady state profiles AND unsteady time series
- Run plans with automatic current plan setting
- Supports versions: 3.1, 4.1, 5.0.x (501-507), 6.0, 6.3, 6.6
- Version migration validation and comparison
- Open-operate-close pattern prevents conflicts with modern workflows
- Seamless integration with ras-commander project management
- See `examples/17_legacy_1d_automation_with_hecrascontroller_and_rascontrol.ipynb` for complete usage

HDF Data Access & Analysis
- 2D mesh results processing (depths, velocities, WSE)
- Cross-section data extraction
- Boundary condition analysis
- Structure data (bridges, culverts, gates)
- Pipe network and pump station analysis
- Fluvial-pluvial boundary calculations
- Infiltration and precipitation data handling
- Infiltration and soil data handling
- Land cover and terrain data integration
- Weighted parameter calculations for hydrologic modeling

RASMapper Data Integration
- RASMapper configuration parsing (.rasmap files)
- Terrain, soil, and land cover HDF paths
- Profile line paths

Model Discovery & Download (NEW - Experimental)
- Unified catalog for discovering HEC-RAS models from 25+ documented public sources
- Federal sources: USGS ScienceBase (implemented), FEMA BLE (planned)
- State sources: Virginia VFRIS, Wisconsin DNR, North Carolina FRIS (planned)
- County sources: Henrico VA, Harris County TX M3 (planned)
- Note: USACE official examples already available via `RasExamples` class
- Advanced filtering: location, type, tags, spatial extent, file size, dates
- Automatic download and extraction with validation
- See `examples/600_discovering_hecras_models_from_usgs.ipynb` for usage
- Requires: `pip install sciencebasepy` for USGS access

Manning's n Coefficient Management
- Base Manning's n table extraction and modification
- Regional overrides for spatially-varied roughness
- Direct editing of geometry file Manning values

Infiltration & Soil Analysis
- Soil statistics calculation and analysis
- Infiltration parameter management and scaling
- Weighted average parameter calculation
- Raster-based soil data processing

RAS ASCII File Operations
- Plan file creation and modification
- Geometry file parsing examples 
- Unsteady flow file management
- Project file updates and validation  

Note about support for Pipe Networks:  As a relatively new feature, only read access to Pipe Network geometry and results data has been included.  Users will need to code their own methods to modify/add pipe network data, and pull requests are always welcome to incorporate this capability.

Note about version support: The modern HDF-based features target HEC-RAS 6.2+ for optimal compatibility. For legacy versions (3.1, 4.1, 5.0.x), use the RasControl class which provides COM-based access to steady state profile extraction and plan execution (see example notebook 17).

## Installation

First, create a virtual environment with conda or venv (ask ChatGPT if you need help).  

#### Install via Pip

In your virtual environment, install ras-commander using pip:
```
pip install --upgrade ras-commander
```
If you have dependency issues with pip (especially if you have errors with numpy), try clearing your local pip packages 'C:\Users\your_username\AppData\Roaming\Python\' and then creating a new virtual environment.  

### Library Dependencies

These are the core dependencies required for ras-commander library functionality:

```bash
# Core library dependencies
pip install h5py numpy pandas requests tqdm scipy xarray geopandas matplotlib shapely rasterstats rtree

# Windows-specific (for RasControl COM interface and GUI automation)
pip install pywin32 psutil
```

### Notebook Dependencies

Additional packages needed to run the example notebooks in the `examples/` folder:

```bash
# For raster visualization (notebooks 15, 21) and coordinate system operations (notebook 14) and external downloads 
pip install rasterio pyproj requests aiohttp

```

### Optional Dependencies

For specific features that aren't required for core functionality:

```bash
# DSS file operations (requires Java JRE/JDK 8+)
pip install pyjnius

# Remote execution backends
pip install paramiko      # SSH remote execution
pip install pywinrm       # WinRM remote execution
pip install docker        # Docker container execution
pip install boto3         # AWS EC2 execution
pip install azure-identity azure-mgmt-compute  # Azure execution

# Or install all remote backends at once:
pip install ras-commander[remote-all]
```

Note: `pathlib` is built into Python 3.4+ and does not need to be installed separately.


#### Work in a Local Copy

If you want to make revisions and work actively in your local version of ras-commander, just skip the pip install rascommander step above and clone a fork of the repo to your local machine using Git (ask ChatGPT if you need help).  Most of the notebooks and examples in this repo have a code segment similar to the one below, that works as long as the script is located in a first-level subfolder of the ras-commander repository:
```
# Flexible imports to allow for development without installation
try:
    # Try to import from the installed package
    from ras_commander import init_ras_project, RasExamples, RasCmdr, RasPlan, RasGeo, RasUnsteady, RasUtils, ras
except ImportError:
    # If the import fails, add the parent directory to the Python path
    current_file = Path(__file__).resolve()
    parent_directory = current_file.parent.parent
    sys.path.append(str(parent_directory))
    # Alternately, you can just define a path sys.path.append(r"c:/path/to/rascommander/rascommander)")
    
    # Now try to import again
    from ras_commander import init_ras_project, RasExamples, RasCmdr, RasPlan, RasGeo, RasUnsteady, RasUtils, ras
```
It is highly suggested to fork this repository before going this route, and using Git to manage your changes!  This allows any revisions to the ras-commander classes and functions to be actively edited and developed by end users. The folders "/workspace/, "/projects/", or "my_projects/" are included in the .gitignore, so users can place you custom scripts there for any project data they don't want to be tracked by git.

## Quick Start Guide

```
from ras_commander import init_ras_project, RasCmdr, RasPlan
```

### Initialize a project (single project)
```python
# Basic initialization using default HEC-RAS location (on C: drive)
init_ras_project(r"/path/to/project", "6.5")

# Specifying a custom path to Ras.exe (useful if HEC-RAS is not installed on C: drive)
init_ras_project(r"/path/to/project", r"D:/Programs/HEC/HEC-RAS/6.5/Ras.exe")
```

### Initialize a project (multiple projects)
```python
your_ras_project = RasPrj()
init_ras_project(r"/path/to/project", "6.5", ras_object=your_ras_project)
```

## Accessing Plan, Unsteady and Boundary Conditions Dataframes
Using the default 'ras" object, othewise substitute your_ras_project for muli-project scripts
```
print("\nPlan Files DataFrame:")
ras.plan_df
```
```
print("\nFlow Files DataFrame:")
ras.flow_df
```
```
print("\nUnsteady Flow Files DataFrame:")
ras.unsteady_df
```
```
print("\nGeometry Files DataFrame:")
ras.geom_df
```
```
print("\nBoundary Conditions DataFrame:")
ras.boundaries_df
```
```
print("\nHDF Entries DataFrame:")
ras.get_hdf_entries()
```



### Execute a single plan
```
RasCmdr.compute_plan("01", dest_folder=r"/path/to/results", overwrite_dest=True)
```

### Execute plans in parallel
```
results = RasCmdr.compute_parallel(
    plan_number=["01", "02"],
    max_workers=2,
    num_cores=2,
    dest_folder=r"/path/to/results",
    overwrite_dest=True
)
```

### Modify a plan
```
RasPlan.set_geom("01", "02")
```

### Execution Modes

RAS Commander provides multiple methods for executing HEC-RAS plans:

#### Modern Command-Line Execution (HEC-RAS 6.0+)

**Single Plan Execution:**
```python
# Execute a single plan
success = RasCmdr.compute_plan("01", dest_folder=r"/path/to/results")
print(f"Plan execution {'successful' if success else 'failed'}")
```

**Sequential Execution of Multiple Plans:**
```python
# Execute multiple plans in sequence in a test folder
results = RasCmdr.compute_test_mode(
    plan_number=["01", "02", "03"],
    dest_folder_suffix="[Test]"
)
for plan, success in results.items():
    print(f"Plan {plan}: {'Successful' if success else 'Failed'}")
```

**Parallel Execution of Multiple Plans:**
```python
# Execute multiple plans concurrently
results = RasCmdr.compute_parallel(
    plan_number=["01", "02", "03"],
    max_workers=3,
    num_cores=2
)
for plan, success in results.items():
    print(f"Plan {plan}: {'Successful' if success else 'Failed'}")
```

**Smart Execution Skip** (NEW in v0.88.0):
```python
# Default: Smart skip - automatically skips if results are current
RasCmdr.compute_plan("01")  # Skips if HDF newer than inputs
# Logs: "Skipping plan 01: Results are current (HDF newer than inputs)"

# Force re-run even if current
RasCmdr.compute_plan("01", force_rerun=True)  # Always executes

# Force complete geometry reprocessing
RasCmdr.compute_plan("01", force_geompre=True)  # Clears .g##.hdf + .c##

# Efficiency: 10 plans, only 2 modified â†’ 80% time savings
RasCmdr.compute_parallel(["01", ..., "10"])  # Runs only modified plans
```

#### Legacy COM Interface Execution (HEC-RAS 3.x-6.x)

**For older HEC-RAS versions**, use the RasControl class:

```python
# Initialize with version
init_ras_project(project_path, "4.1")  # or "41", "5.0.6", "506", "6.6", etc.

# Run a plan (auto-sets as current, blocks until complete)
success, messages = RasControl.run_plan("02")

# Extract steady state results
df_steady = RasControl.get_steady_results("02")
print(f"Extracted {len(df_steady)} rows with {df_steady['profile'].nunique()} profiles")

# Extract unsteady time series (includes "Max WS" special timestep)
df_unsteady = RasControl.get_unsteady_results("01", max_times=20)
times = RasControl.get_output_times("01")
```

**Key RasControl Features:**
- Uses plan numbers, not file paths (ras-commander style)
- Automatically sets current plan before operations
- Supports steady AND unsteady extraction
- Works with versions 3.1, 4.1, 5.0.x, 6.0, 6.3, 6.6
- Open-operate-close pattern (no HEC-RAS window left open)
- Perfect for version migration validation

### Working with Multiple Projects

RAS Commander allows working with multiple HEC-RAS projects simultaneously:

```python
# Initialize multiple projects
project1 = RasPrj()
init_ras_project(path1, "6.6", ras_object=project1)
project2 = RasPrj()
init_ras_project(path2, "6.6", ras_object=project2)

# Perform operations on each project
RasCmdr.compute_plan("01", ras_object=project1, dest_folder=folder1)
RasCmdr.compute_plan("01", ras_object=project2, dest_folder=folder2)

# Compare results between projects
print(f"Project 1: {project1.project_name}")
print(f"Project 2: {project2.project_name}")

# Always specify the ras_object parameter when working with multiple projects
# to avoid confusion with the global 'ras' object
```

This is useful for comparing different river systems, running scenario analyses across multiple watersheds, or managing a suite of related models.

#### Core HEC-RAS Automation Classes

- `RasPrj`: Manages HEC-RAS projects, handling initialization and data loading
- `RasCmdr`: Handles execution of HEC-RAS simulations via command line
- `RasControl`: Legacy version support via COM interface for HEC-RAS 3.x-6.x
- `RasPlan`: Provides functions for modifying and updating plan files
- `RasGeo`: Handles 2D Manning's n land cover operations
- `RasGeometry`: **NEW** Comprehensive 1D geometry parsing (cross sections, storage, connections)
- `RasGeometryUtils`: **NEW** Geometry parsing utilities (FORTRAN fixed-width, count interpretation)
- `RasBreach`: Dam breach parameter modification in plan files
- `RasUnsteady`: Manages unsteady flow file operations
- `RasUtils`: Contains utility functions for file operations and data management
- `RasMap`: Parses RASMapper configuration files and automates floodplain mapping
- `RasExamples`: Manages and loads HEC-RAS example projects

#### HDF Data Access Classes
- `HdfBase`: Core functionality for HDF file operations
- `HdfBndry`: Enhanced boundary condition handling
- `HdfMesh`: Comprehensive mesh data management
- `HdfPlan`: Plan data extraction and analysis
- `HdfResultsMesh`: Advanced mesh results processing
- `HdfResultsPlan`: Plan results analysis
- `HdfResultsXsec`: Cross-section results processing
- `HdfStruc`: Structure data and SA/2D connection management
- `HdfResultsBreach`: **NEW** Dam breach results extraction from HDF files
- `HdfHydraulicTables`: **NEW** Cross section property tables (HTAB) for rating curves
- `HdfPipe`: Pipe network analysis tools
- `HdfPump`: Pump station analysis capabilities
- `HdfFluvialPluvial`: Fluvial-pluvial boundary analysis
- `HdfPlot` & `HdfResultsPlot`: Specialized plotting utilities

### Project Organization Diagram

```
ras_commander
â”œâ”€â”€ .claude/                # Claude Code cognitive infrastructure
â”‚   â”œâ”€â”€ agents/             # Domain specialist definitions
â”‚   â”œâ”€â”€ skills/             # Workflow templates
â”‚   â””â”€â”€ rules/              # Auto-loaded coding patterns
â”œâ”€â”€ examples
â”‚   â””â”€â”€ [Example Notebooks](https://github.com/gpt-cmdr/ras-commander/tree/main/examples)
â”œâ”€â”€ ras_commander
â”‚   â”œâ”€â”€ __init__.py
â”‚   â”œâ”€â”€ _version.py
â”‚   â”œâ”€â”€ Decorators.py
â”‚   â”œâ”€â”€ LoggingConfig.py
â”‚   â”œâ”€â”€ RasCmdr.py
â”‚   â”œâ”€â”€ RasExamples.py
â”‚   â”œâ”€â”€ RasGeo.py
â”‚   â”œâ”€â”€ RasPlan.py
â”‚   â”œâ”€â”€ RasPrj.py
â”‚   â”œâ”€â”€ RasUnsteady.py
â”‚   â”œâ”€â”€ RasUtils.py
â”‚   â”œâ”€â”€ HdfBase.py
â”‚   â”œâ”€â”€ HdfBndry.py
â”‚   â”œâ”€â”€ HdfMesh.py
â”‚   â”œâ”€â”€ HdfPlan.py
â”‚   â”œâ”€â”€ HdfResultsMesh.py
â”‚   â”œâ”€â”€ HdfResultsPlan.py
â”‚   â”œâ”€â”€ HdfResultsXsec.py
â”‚   â”œâ”€â”€ HdfStruc.py
â”‚   â”œâ”€â”€ HdfPipe.py
â”‚   â”œâ”€â”€ HdfPump.py
â”‚   â”œâ”€â”€ HdfFluvialPluvial.py
â”‚   â”œâ”€â”€ HdfPlot.py
â”‚   â””â”€â”€ HdfResultsPlot.py
â”œâ”€â”€ docs/                   # Documentation source (MkDocs)
â”œâ”€â”€ .gitignore
â”œâ”€â”€ LICENSE
â”œâ”€â”€ README.md
â”œâ”€â”€ mkdocs.yml
â”œâ”€â”€ pyproject.toml
â”œâ”€â”€ setup.py
```

### Accessing HEC Examples through RasExamples

The `RasExamples` class provides functionality for quickly loading and managing HEC-RAS example projects. This is particularly useful for testing and development purposes.  All examples in the ras-commander repository currently utilize HEC example projects to provide fully running scripts and notebooks for end user testing, demonstration and adaption. 

Key features:
- Download and extract HEC-RAS example projects
- List available project categories and projects
- Extract specific projects for use
- Manage example project data efficiently

Example usage:
from ras_commander import RasExamples

```
categories = ras_examples.list_categories()
projects = ras_examples.list_projects("Steady Flow")
extracted_paths = ras_examples.extract_project(["Bald Eagle Creek", "Muncie"])
```

The RasExamples class is used to provide an alternative to traditional unit testing, with example notebooks doubling as tests and in-context examples for the end user.  This increases interpretability by LLM's, reducing hallucinations.  

### RasPrj

The `RasPrj` class is central to managing HEC-RAS projects within the ras-commander library. It handles project initialization, data loading, and provides access to project components.

Key features:
- Initialize HEC-RAS projects
- Load and manage project data (plans, geometries, flows, etc.)
- Provide easy access to project files and information

Note: While a global `ras` object is available for convenience, you can create multiple `RasPrj` instances to manage several projects simultaneously.

Example usage:
```
from ras_commander import RasPrj, init_ras_project
```

#### Using the global ras object
```
init_ras_project("/path/to/project", "6.5")
```

#### Creating a custom RasPrj instance
```
custom_project = RasPrj()
init_ras_project("/path/to/another_project", "6.5", ras_instance=custom_project)
```

### RasHdf

The `RasHdf` class provides utilities for working with HDF files in HEC-RAS projects, enabling easy access to simulation results and model data.

Example usage:

```python
from ras_commander import RasHdf, init_ras_project, RasPrj

# Initialize project with a custom ras object
custom_ras = RasPrj()
init_ras_project("/path/to/project", "6.5", ras_instance=custom_ras)

# Get runtime data for a specific plan
plan_number = "01"
runtime_data = RasHdf.get_runtime_data(plan_number, ras_object=custom_ras)
print(runtime_data)
```
This class simplifies the process of extracting and analyzing data from HEC-RAS HDF output files, supporting tasks such as post-processing and result visualization.

#### Infrastructure Analysis
```python
from ras_commander import HdfPipe, HdfPump

# Analyze pipe network
pipe_network = HdfPipe.get_pipe_network(hdf_path)
conduits = HdfPipe.get_pipe_conduits(hdf_path)

# Analyze pump stations
pump_stations = HdfPump.get_pump_stations(hdf_path)
pump_performance = HdfPump.get_pump_station_summary(hdf_path)
```

#### Advanced Results Analysis
```python
from ras_commander import HdfResultsMesh

# Get maximum water surface and velocity
max_ws = HdfResultsMesh.get_mesh_max_ws(hdf_path)
max_vel = HdfResultsMesh.get_mesh_max_face_v(hdf_path)

# Visualize results
from ras_commander import HdfResultsPlot
HdfResultsPlot.plot_results_max_wsel(max_ws)
```

#### Fluvial-Pluvial Analysis
```python
from ras_commander import HdfFluvialPluvial

boundary = HdfFluvialPluvial.calculate_fluvial_pluvial_boundary(
    hdf_path,
    delta_t=12  # Time threshold in hours
)
```

## Examples

Check out the examples in the repository to learn how to use RAS Commander:

### Project Setup
- `00_Using_RasExamples.ipynb`: Download and extract HEC-RAS example projects
- `01_project_initialization.ipynb`: Initialize HEC-RAS projects and explore their components

### File Operations
- `02_plan_and_geometry_operations.ipynb`: Clone and modify plan and geometry files
- `03_unsteady_flow_operations.ipynb`: Extract and modify boundary conditions
- `09_plan_parameter_operations.ipynb`: Retrieve and update plan parameters

### Execution Modes
- `05_single_plan_execution.ipynb`: Execute a single plan with specific options
- `06_executing_plan_sets.ipynb`: Different ways to specify and execute plan sets
- `07_sequential_plan_execution.ipynb`: Run multiple plans in sequence
- `08_parallel_execution.ipynb`: Run multiple plans in parallel

### Legacy Version Support
- `17_legacy_1d_automation_with_hecrascontroller_and_rascontrol.ipynb`: Using RasControl for HEC-RAS 3.x-6.x via COM interface

### Advanced Operations
- `04_multiple_project_operations.ipynb`: Work with multiple HEC-RAS projects simultaneously

These examples demonstrate practical applications of RAS Commander for automating HEC-RAS workflows, from basic operations to advanced scenarios.

## Documentation

For detailed usage instructions and API documentation, visit the **[RAS Commander Documentation](https://ras-commander.readthedocs.io/)**:

- [Installation Guide](https://ras-commander.readthedocs.io/en/latest/getting-started/installation/)
- [Quick Start](https://ras-commander.readthedocs.io/en/latest/getting-started/quickstart/)
- [User Guide](https://ras-commander.readthedocs.io/en/latest/user-guide/overview/)
- [API Reference](https://ras-commander.readthedocs.io/en/latest/api/)

## Future Development

The ras-commander library is an ongoing project embodying LLM Forward engineering principles. Future plans include:

- Integration of more advanced LLM-assisted features while maintaining professional oversight
- Expansion of HMS and DSS functionalities through community-driven development
- Enhanced verifiability and interpretability features for engineering review
- Community-driven development of new modules following LLM Forward best practices

See [LLM Forward Development Philosophy](https://ras-commander.readthedocs.io/en/latest/development/llm-development/) for contribution guidelines.

## Related Resources

- [HEC-Commander Blog](https://github.com/gpt-cmdr/HEC-Commander/tree/main/Blog)
- [GPT-Commander YouTube Channel](https://www.youtube.com/@GPT_Commander)
- [ChatGPT Examples for Water Resources Engineers](https://github.com/gpt-cmdr/HEC-Commander/tree/main/ChatGPT%20Examples)


## Style Guide

This project follows a specific style guide to maintain consistency across the codebase. Please refer to the [Contributing Guide](https://ras-commander.readthedocs.io/en/latest/development/contributing/) for details on coding conventions, documentation standards, and best practices.

## Acknowledgments

RAS Commander is based on the HEC-Commander project's "Command Line is All You Need" approach, leveraging the HEC-RAS command-line interface for automation. The initial development of this library was presented in the HEC-Commander Tools repository. In a 2024 Australian Water School webinar, Bill demonstrated the derivation of basic HEC-RAS automation functions from plain language instructions. Leveraging the previously developed code and AI tools, the library was created. The primary tools used for this initial development were Anthropic's Claude, GPT-4, Google's Gemini Experimental models, and the Cursor AI Coding IDE.

Additionally, we would like to acknowledge the following notable contributions and attributions for open source projects which significantly influenced the development of RAS Commander:

1. Contributions: Sean Micek's [`funkshuns`](https://github.com/openSourcerer9000/funkshuns), [`TXTure`](https://github.com/openSourcerer9000/TXTure), and [`RASmatazz`](https://github.com/openSourcerer9000/RASmatazz) libraries provided inspiration, code examples and utility functions which were adapted with AI for use in RAS Commander. Sean has also contributed heavily to 

- Development of additional HDF functions for detailed analysis and mapping of HEC-RAS results within the RasHdf class.
- Development of the prototype `RasCmdr` class for executing HEC-RAS simulations.

2. Attribution: The [`pyHMT2D`](https://github.com/psu-efd/pyHMT2D/) project by Xiaofeng Liu, which provided insights into HDF file handling methods for HEC-RAS outputs.  Many of the functions in the [Ras_2D_Data.py](https://github.com/psu-efd/pyHMT2D/blob/main/pyHMT2D/Hydraulic_Models_Data/RAS_2D/RAS_2D_Data.py) file were adapted with AI for use in RAS Commander. 

   Xiaofeng Liu, Ph.D., P.E.,    Associate Professor, Department of Civil and Environmental Engineering
   Institute of Computational and Data Sciences, Penn State University

3. Attribution: The [ffrd\rashdf'](https://github.com/fema-ffrd/rashdf) project by FEMA-FFRD (FEMA Future of Flood Risk Data) was incorporated, revised, adapted and extended in rascommander's RasHDF libaries (where noted). 

These acknowledgments recognize the contributions and inspirations that have helped shape RAS Commander, ensuring proper attribution for the ideas and code that have influenced its development.

4. Chris Goodell, "Breaking the HEC-RAS Code" - Studied and used as a reference for understanding the inner workings of HEC-RAS, providing valuable insights into the software's functionality and structure.

5. [HEC-Commander Tools](https://github.com/gpt-cmdr/HEC-Commander) - Inspiration and initial code base for the development of RAS Commander.

## Official RAS Commander AI-Generated Songs:

[No More Wait and See (Bluegrass)](https://suno.com/song/16889f3e-50f1-4afe-b779-a41738d7617a)  
  
  
[No More Wait and See (Cajun Zydeco)](https://suno.com/song/4441c45d-f6cd-47b9-8fbc-1f7b277ee8ed)  
  
## Other Resources

Notebook version of RAS-Commander: [RAS-Commander Notebook in the HEC-Commander Tools Repository](https://github.com/gpt-cmdr/HEC-Commander/tree/main/RAS-Commander)  

Youtube Tutorials for HEC-Commander Tools and RAS-Commander: [GPT-Commander on YouTube](https://www.youtube.com/@GPT_Commander/videos)

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to submit pull requests, report issues, and suggest improvements.

## LICENSE

This software is released under the MIT license.

## Contact

For questions, suggestions, or support, please contact:  
William Katzenmeyer, P.E., C.F.M. - heccommander@gmail.com