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. 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.
Check out the ASFPM Presentation on RAS-Commander Here
This repository has several methods of interaction with Large Language Models and LLM-Assisted Coding built right in:
-
Purpose-Built Knowledge Base Summaries: Up-to-date compilations of the documentation and codebase for use with large language models like Claude, ChatGPT, Gemini or Grok. Look in 'ai_tools/assistant_knowledge_bases/' in the repo. The repo's codebase (without documentation and examples) has been curated to stay within the current ~200k context window limitations of frontier models, and for tasks that do not need an understanding of the underlying code, the Comprehensive Library Guide and any relevant examples from the example folder should be adequate context for leveraging the ras-commander API to complete tasks.
-
Cursor IDE Integration: Custom rules(.cursor/rules) for the Cursor IDE to provide context-aware suggestions and documentation. Just open the repository folder in Cursor to recognize these instructions. You can create your own folders "/workspace/, "/projects/", or "my_projects/" as these are already in the .gitignore, and place your custom scripts there for your projects. This will allow easy referencing of the ras-commander documents and individual repo files, the automatic loading of the .cursorrules file. Alternatvely, download the github repo into your projects folder to easily load documents and use cursor rules files.
-
RAS-Commander library as indexed by Deepwiki An LLM-generated summary of the repostiory with diagrams and analysis of the library, as well as an integrated chat assistant with deep research.
The RAS-Commander library Assistant is a full-featured interface for multi-turn conversations, using your own API keys and the ras-commander library for context. The library assistant allows you to load your own scripts and chat with specific examples and/or function classes in the RAS-Commander library to effectively utilize the library's functions in your workflow. To reduce hallucinations, a file browser is included which adds full files to the conversation to ensure grounded responses. A dashboard shows you the total context and estimated cost of each request. Now with support for Claude 3.7 with extended thinking, OpenAI's o1, o3 and o4-mini, and Deepseek V3 and R1 models using US-based Together.ai
- RAS Commander Library Assistant on ChatGPT: A specialized ChatGPT "GPT" with access to the ras-commander codebase and library, available for answering queries and providing code suggestions. You can even upload your own plan, unsteady and HDF files to inspect and help determine how to automate your workflows or visualize your results. NOTE: GPT's are still quite limited by OpenAI's GPT frameworks and may not be useful for long conversations. Code interpreter cannot run HEC-RAS but can open and view smaller HDF files and projects for demonstration purposes
The ras-commander library emerged from the initial test-bed of AI-driven coding represented by the HEC-Commander tools Python notebooks. These notebooks served as a proof of concept, demonstrating the value proposition of automating HEC-RAS operations. In 2024, I 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 served as a foundation of examples which were iteratively extended into the full RAS-Commander library. 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 they key functions of the library for inclusion in into their own preferred libraries, languages or return formats.
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
- Project folder management and organization
- Multi-core processing optimization
- Progress tracking and logging
- Execution error handling and recovery
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
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. Please note that the library has not been tested with versions prior to HEC-RAS 6.2.
First, create a virtual environment with conda or venv (ask ChatGPT if you need help).
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.
Dependencies can also be manually installed:
pip install h5py numpy pandas requests tqdm scipy xarray geopandas matplotlib shapely pathlib rasterstats rtree
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.
from ras_commander import init_ras_project, RasCmdr, RasPlan
# 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")your_ras_project = RasPrj()
init_ras_project(r"/path/to/project", "6.5", ras_object=your_ras_project)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()
RasCmdr.compute_plan("01", dest_folder=r"/path/to/results", overwrite_dest=True)
results = RasCmdr.compute_parallel(
plan_number=["01", "02"],
max_workers=2,
num_cores=2,
dest_folder=r"/path/to/results",
overwrite_dest=True
)
RasPlan.set_geom("01", "02")
RAS Commander provides three methods for executing HEC-RAS plans:
# Execute a single plan
success = RasCmdr.compute_plan("01", dest_folder=r"/path/to/results")
print(f"Plan execution {'successful' if success else 'failed'}")# 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'}")# 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'}")RAS Commander allows working with multiple HEC-RAS projects simultaneously:
# 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' objectThis is useful for comparing different river systems, running scenario analyses across multiple watersheds, or managing a suite of related models.
RasPrj: Manages HEC-RAS projects, handling initialization and data loadingRasCmdr: Handles execution of HEC-RAS simulationsRasPlan: Provides functions for modifying and updating plan filesRasGeo: Handles operations related to geometry filesRasUnsteady: Manages unsteady flow file operationsRasUtils: Contains utility functions for file operations and data managementRasMap: Parses and manages RASMapper configuration dataRasExamples: Manages and loads HEC-RAS example projects
HdfBase: Core functionality for HDF file operationsHdfBndry: Enhanced boundary condition handlingHdfMesh: Comprehensive mesh data managementHdfPlan: Plan data extraction and analysisHdfResultsMesh: Advanced mesh results processingHdfResultsPlan: Plan results analysisHdfResultsXsec: Cross-section results processingHdfStruc: Structure data managementHdfPipe: Pipe network analysis toolsHdfPump: Pump station analysis capabilitiesHdfFluvialPluvial: Fluvial-pluvial boundary analysisHdfPlot&HdfResultsPlot: Specialized plotting utilities
ras_commander
├── ai_tools
│ ├── [AI Knowledge Bases](https://github.com/gpt-cmdr/ras-commander/tree/main/ai_tools/llm_knowledge_bases)
│ └── [Library Assistant](https://github.com/gpt-cmdr/ras-commander/tree/main/ai_tools/library_asssistant)
├── examples
│ └── [Examples Notebooks](https://github.com/gpt-cmdr/ras-commander/tree/main/ras_commander)
├── 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
├── .gitignore
├── LICENSE
├── README.md
├── STYLE_GUIDE.md
├── Comprehensive_Library_Guide.md
├── pyproject.toml
├── setup.py
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.
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
init_ras_project("/path/to/project", "6.5")
custom_project = RasPrj()
init_ras_project("/path/to/another_project", "6.5", ras_instance=custom_project)
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:
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.
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)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)from ras_commander import HdfFluvialPluvial
boundary = HdfFluvialPluvial.calculate_fluvial_pluvial_boundary(
hdf_path,
delta_t=12 # Time threshold in hours
)Check out the examples in the repository to learn how to use RAS Commander:
00_Using_RasExamples.ipynb: Download and extract HEC-RAS example projects01_project_initialization.ipynb: Initialize HEC-RAS projects and explore their components
02_plan_and_geometry_operations.ipynb: Clone and modify plan and geometry files03_unsteady_flow_operations.ipynb: Extract and modify boundary conditions09_plan_parameter_operations.ipynb: Retrieve and update plan parameters
05_single_plan_execution.ipynb: Execute a single plan with specific options06_executing_plan_sets.ipynb: Different ways to specify and execute plan sets07_sequential_plan_execution.ipynb: Run multiple plans in sequence08_parallel_execution.ipynb: Run multiple plans in parallel
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.
For detailed usage instructions and API documentation, please refer to the Comprehensive Library Guide.
The ras-commander library is an ongoing project. Future plans include:
- Integration of more advanced AI-driven features
- Expansion of HMS and DSS functionalities
- Community-driven development of new modules and features
This project follows a specific style guide to maintain consistency across the codebase. Please refer to the Style Guide for details on coding conventions, documentation standards, and best practices.
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:
- Contributions: Sean Micek's
funkshuns,TXTure, andRASmatazzlibraries 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
RasCmdrclass for executing HEC-RAS simulations. - Optimization examples and methods from (INSERT REFERENCE) for use in the Ras-Commander library examples
-
Attribution: The
pyHMT2Dproject 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 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
-
Attribution: The 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.
-
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.
-
HEC-Commander Tools - Inspiration and initial code base for the development of RAS Commander.
No More Wait and See (Bluegrass)
No More Wait and See (Cajun Zydeco)
Notebook version of RAS-Commander: RAS-Commander Notebook in the HEC-Commander Tools Repository
Youtube Tutorials for HEC-Commander Tools and RAS-Commander: GPT-Commander on YouTube
We welcome contributions! Please see our Contributing Guide for details on how to submit pull requests, report issues, and suggest improvements.
This software is released under the MIT license.
For questions, suggestions, or support, please contact:
William Katzenmeyer, P.E., C.F.M. - [email protected]