Skip to content

Project Initialization

Python
# =============================================================================
# DEVELOPMENT MODE TOGGLE
# =============================================================================
# Set USE_LOCAL_SOURCE based on your setup:
#   True  = Use local source code (for developers editing ras-commander)
#   False = Use pip-installed package (for users)
# =============================================================================

USE_LOCAL_SOURCE = False  # <-- TOGGLE THIS

# -----------------------------------------------------------------------------
if USE_LOCAL_SOURCE:
    import sys
    from pathlib import Path
    local_path = str(Path.cwd().parent)  # Parent of examples/ = repo root
    if local_path not in sys.path:
        sys.path.insert(0, local_path)  # Insert at position 0 = highest priority
    print(f"📁 LOCAL SOURCE MODE: Loading from {local_path}/ras_commander")
else:
    print("📦 PIP PACKAGE MODE: Loading installed ras-commander")

# Import ras-commander
from ras_commander import RasExamples, RasPrj, RasTcu, init_ras_project, ras

# Verify which version loaded
import ras_commander
print(f"✓ Loaded: {ras_commander.__file__}")
Text Only
📦 PIP PACKAGE MODE: Loading installed ras-commander


2026-06-11 15:50:39 - numexpr.utils - INFO - NumExpr defaulting to 8 threads.


✓ Loaded: <repo>\ras_commander\__init__.py

Prerequisites

Before running this notebook, ensure you have:

  1. ras-commander installed: pip install ras-commander
  2. Python 3.10+: Check with python --version
  3. HEC-RAS (optional for inspecting project files; an installed release is required to execute a plan)
  4. Disk Space: ~500 MB for example projects

What You'll Learn

This notebook demonstrates the core project initialization workflow in ras-commander:

  • Global vs Custom Objects: When to use the global ras object vs creating RasPrj() instances
  • Project Structure: Understanding plan_df, geom_df, boundaries_df DataFrames
  • File Path Management: How ras-commander tracks project files
  • Multiple Projects: Managing several HEC-RAS projects simultaneously
  • 100_using_ras_examples.ipynb - Extract example projects first
  • 102_multiple_project_operations.ipynb - Advanced multi-project patterns
  • 110_single_plan_execution.ipynb - Execute initialized projects

Key Concept: The RAS Object

The ras object (or custom RasPrj() instances) is the central data structure in ras-commander: - Stores project metadata (plans, geometries, boundaries) - Tracks file paths and relationships - Provides DataFrame-based API for data access

Design Philosophy: Use the global ras object for single-project workflows. Create custom RasPrj() instances for multi-project scenarios.

Terms and Conditions preflight

On Windows, execution requires the Terms and Conditions of Use (TCU) to be accepted for the exact installed HEC-RAS release and current user. Initialization checks that state without changing it:

Python
init_ras_project(project_folder, RAS_VERSION)
tcu = RasTcu.status(ras_object=ras)
print(tcu.accepted, tcu.reason)

If the status is unaccepted, accept the TCU in that release's GUI. As an explicit opt-in, init_ras_project(project_folder, RAS_VERSION, accept_tcu=True) can replicate an already accepted local settings subtree and write the exact release sentinel. It cannot create acceptance when no accepted donor settings exist.

Parameters

Configure these values to customize the notebook for your project.

Python
# =============================================================================
# PARAMETERS - Edit these to customize the notebook
# =============================================================================
from pathlib import Path

# Project Configuration
PROJECT_NAME = "Muncie"           # Example project to extract
RAS_VERSION = "7.0"               # HEC-RAS version (5.0.5, 6.0, 6.6, 7.0, etc.)
Optional Code Cell For Development/Testing Mode (Local Copy)
Uncomment and run this cell instead of the pip cell above
Python
# For Development Mode, add the parent directory to the Python path
import os
import sys
from pathlib import Path

current_file = Path(os.getcwd()).resolve()
rascmdr_directory = current_file.parent

# Use insert(0) instead of append() to give highest priority to local version
if str(rascmdr_directory) not in sys.path:
    sys.path.insert(0, str(rascmdr_directory))

print("Loading ras-commander from local dev copy")
from ras_commander import *
Python
import os
from pathlib import Path
import pandas as pd
from IPython import display

Core Project Concepts

RAS Commander is a Python library that provides tools for automating HEC-RAS tasks. It's built with several key design principles:

  1. Project-Centric Architecture: Everything revolves around HEC-RAS projects
  2. Two RAS Object Approaches:
  3. Global ras Object: A singleton for simple scripts
  4. Custom RAS Objects: Multiple ras project instances for complex workflows
  5. Comprehensive Project Representation: Each RAS object includes DataFrames for plans, geometries, flows, and boundaries
  6. Logging: Built-in logging to track operations and debug issues
  7. HDF Support: Specialized functions for HDF file access (plan results, geometry, etc.)

Let's explore these concepts in practice.

Downloading Example HEC-RAS Projects

RAS Commander includes a utility to download and extract example HEC-RAS projects. These are useful for learning and testing:

Python
# Extract specific projects we'll use in this tutorial
# This will download them if not present and extract them to the example_projects folder
extracted_paths = RasExamples.extract_project(["Balde Eagle Creek", "BaldEagleCrkMulti2D", "Muncie"], suffix="101")
print(extracted_paths)
Text Only
2026-06-11 15:50:41 - ras_commander.RasExamples - INFO - Successfully extracted project 'Balde Eagle Creek' to <repo>\examples\example_projects\Balde Eagle Creek_101


2026-06-11 15:50:42 - ras_commander.RasExamples - INFO - Successfully extracted project 'BaldEagleCrkMulti2D' to <repo>\examples\example_projects\BaldEagleCrkMulti2D_101


2026-06-11 15:50:43 - ras_commander.RasExamples - INFO - Successfully extracted project 'Muncie' to <repo>\examples\example_projects\Muncie_101


[WindowsPath('<repo>/examples/example_projects/Balde Eagle Creek_101'), WindowsPath('<repo>/examples/example_projects/BaldEagleCrkMulti2D_101'), WindowsPath('<repo>/examples/example_projects/Muncie_101')]

Get Paths for Extracted Example Projects

Python
# Use the exact directories returned by RasExamples.extract_project()
examples_dir = extracted_paths[0].parent
print(f"Examples directory: {examples_dir}")

# Define paths to the extracted projects
bald_eagle_path, multi_2d_path, muncie_path = extracted_paths

# Verify the paths exist
for path in [bald_eagle_path, multi_2d_path, muncie_path]:
    print(f"Path {path} exists: {path.exists()}")
Text Only
Examples directory: <repo>\examples\example_projects
Path <repo>\examples\example_projects\Balde Eagle Creek_101 exists: True
Path <repo>\examples\example_projects\BaldEagleCrkMulti2D_101 exists: True
Path <repo>\examples\example_projects\Muncie_101 exists: True

Utility Function to Print RAS Object Data

Let's create a utility function to help us explore the contents of RAS objects:

Python
def print_ras_object_data(ras_obj, project_name):
    """Prints comprehensive information about a RAS object"""
    print(f"\n{project_name} Data:")
    print("=" * 50)
    print(f"Project Name: {ras_obj.get_project_name()}")
    print(f"Project Folder: {ras_obj.project_folder}")
    print(f"PRJ File: {ras_obj.prj_file}")
    print(f"HEC-RAS Executable Path: {ras_obj.ras_exe_path}")

    print("\nPlan Files DataFrame (ras.plan_df):")
    with pd.option_context('display.max_columns', None):
        display.display(ras_obj.plan_df)

    print("\nSteady Flow Files DataFrame:")
    display.display(ras_obj.flow_df)

    print("\nUnsteady Flow Files DataFrame (ras.unsteady_df):")
    display.display(ras_obj.unsteady_df)

    print("\nGeometry Files DataFrame (ras.geom_df):")
    display.display(ras_obj.geom_df)

    print("\nHDF Entries DataFrame (ras.get_hdf_entries()):")
    display.display(ras_obj.get_hdf_entries())

    print("\nBoundary Conditions DataFrame (ras.boundaries_df):")
    display.display(ras_obj.boundaries_df)

Approach 1: Using the Global ras Object

The global ras object is a singleton instance that persists throughout your script. It's ideal for simple scripts working with a single project.

Key characteristics: - It's available as ras immediately after import - It's initialized via init_ras_project() without saving the return value - It provides access to all project data through the global ras variable - It's simple to use but can be problematic in complex scenarios

Let's initialize it with the Bald Eagle Creek project:

Python
# Initialize the global ras object with Bald Eagle Creek project
# Note: This updates the global 'ras' object visible throughout the script
# Parameters:
#   - project_folder: Path to the HEC-RAS project folder (required)
#   - ras_version: HEC-RAS version (e.g. "6.5") or path to Ras.exe (required first time)

init_ras_project(bald_eagle_path, RAS_VERSION)
print(f"The global 'ras' object is now initialized with the {ras.project_name} project")
Text Only
2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 7.0 at C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.7 Beta 5 at C:\Program Files (x86)\HEC\HEC-RAS\6.7 Beta 5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.7 Beta 4 at C:\Program Files (x86)\HEC\HEC-RAS\6.7 Beta 4\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.6 at C:\Program Files (x86)\HEC\HEC-RAS\6.6\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.5 at C:\Program Files (x86)\HEC\HEC-RAS\6.5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.4.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.4.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.3.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.3.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.3 at C:\Program Files (x86)\HEC\HEC-RAS\6.3\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.2 at C:\Program Files (x86)\HEC\HEC-RAS\6.2\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.0 at C:\Program Files (x86)\HEC\HEC-RAS\6.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.7 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.7\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.6 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.6\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.5 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.4 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.4\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.3 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.3\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.1 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0 at C:\Program Files (x86)\HEC\HEC-RAS\5.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 4.1.0 at C:\Program Files (x86)\HEC\HEC-RAS\4.1.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 4.0 at C:\Program Files (x86)\HEC\HEC-RAS\4.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered 20 installed HEC-RAS version(s)


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - HEC-RAS 7.0 found via version discovery: C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe


2026-06-11 15:50:43 - ras_commander.RasMap - INFO - Successfully parsed RASMapper file: <repo>\examples\example_projects\Balde Eagle Creek_101\BaldEagle.rasmap


2026-06-11 15:50:43 - ras_commander.RasPrj - WARNING - Could not resolve project CRS for <repo>\examples\example_projects\Balde Eagle Creek_101


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - ras-commander v0.98.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - Project initialized: BaldEagle | Folder: <repo>\examples\example_projects\Balde Eagle Creek_101


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - Using HEC-RAS executable: C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - 
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/
Repo: https://github.com/gpt-cmdr/ras-commander
═══════════════════════════════════════════════════════════════════════

PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
  ras.plan_df        Plans, HDF paths, geometry/flow associations
  ras.geom_df        Geometry files and HDF preprocessor paths
  ras.flow_df        Steady flow files
  ras.unsteady_df    Unsteady flow files and configurations
  ras.boundaries_df  Boundary conditions (type, name, location)
  ras.results_df     Lightweight HDF results summaries
  ras.rasmap_df      RASMapper layers, terrain, land cover paths

KEY APIS (static classes — call directly, never instantiate):
  Execution:    RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
  Plan Files:   RasPlan.clone_plan() / clone_geom() / set_geom()
  Unsteady:     RasUnsteady — IC/BC management, gate openings, precipitation
  Geometry:     GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
  HDF Results:  HdfResultsPlan.get_wse() / get_compute_messages()
                HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
                HdfMesh.get_mesh_cell_points()
  QA/QC:        RasCheck.run_check() / RasFixit (geometry repair)
  DSS:          RasDss.get_timeseries() / check_pathname()
  USGS:         UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
  Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
  Terrain:      RasTerrain.create_terrain_hdf() / RasTerrainMod

MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.

EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
  400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
  Review relevant notebooks before assembling new workflows.

PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
  headless execution, data access, geometry modification, and preprocessing
  is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
  Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════


The global 'ras' object is now initialized with the BaldEagle project

Legacy Version String Normalization

get_ras_exe() normalizes legacy dotted version strings like "5.03" to "5.0.3" before looking up the HEC-RAS executable path. This handles older plan files that store the version in a two-part dotted format (e.g., "5.03", "6.31") rather than the standard three-part format.

Python
from ras_commander.RasPrj import RasPrj
import re

# Demonstrate the legacy dotted version normalization
legacy_versions = ["5.03", "6.31", "5.07"]
for v in legacy_versions:
    m = re.fullmatch(r'(\d)\.(\d{2})', v)
    if m:
        normalized = f"{m.group(1)}.{m.group(2)[0]}.{m.group(2)[1]}"
        print(f"  {v!r:>8}  ->  {normalized!r}")

# Show that get_ras_exe resolves these correctly
print("\nVersion alias resolution:")
print(f"  '5.03' normalizes to '5.0.3' which maps to HEC-RAS 5.0.3")
print(f"  '6.31' normalizes to '6.3.1' which maps to HEC-RAS 6.3.1")
Text Only
    '5.03'  ->  '5.0.3'
    '6.31'  ->  '6.3.1'
    '5.07'  ->  '5.0.7'

Version alias resolution:
  '5.03' normalizes to '5.0.3' which maps to HEC-RAS 5.0.3
  '6.31' normalizes to '6.3.1' which maps to HEC-RAS 6.3.1

Verification: Project Initialization

Success Criteria: - ✓ ras object populated (no errors during initialization) - ✓ ras.plan_df contains plan metadata (at least 1 row) - ✓ ras.geom_df contains geometry files (at least 1 row) - ✓ ras.prj_file points to valid .prj file

What to Check:

Python
# Verify initialization succeeded
assert ras.prj_file is not None, "Project file not found"
assert len(ras.plan_df) > 0, "No plans detected"
assert len(ras.geom_df) > 0, "No geometry files detected"

Visual Inspection: - Open ras.prj_file in HEC-RAS GUI - Confirm project loads without errors - Check that plan titles match ras.plan_df['plan_title']

Audit Trail: The initialization process logs: - Project folder scanned - .prj file parsed - Plans/geometries discovered - File paths validated

Understanding the DataFrames

The ras object provides three key DataFrames:

plan_df: Plan metadata - plan_number: Plan ID (e.g., "01", "02") - plan_title: Descriptive name - geom_file: Associated geometry file - flow_file: Flow file (.f##) - hdf_path: Results file location (.p##.hdf)

geom_df: Geometry file metadata - file_path: Full path to .g## file - river_reach: River/reach names parsed from file

boundaries_df: Boundary condition metadata (when applicable) - Upstream/downstream boundary types - DSS file associations - Time series references

Python
# Find the .prj file in the Bald Eagle Creek folder
prj_file = list(bald_eagle_path.glob("*.prj"))[0]
print(f"Found .prj file: {prj_file}")
print(f"File name: {prj_file.name}\n")

# Initialize using the .prj file path directly (NEW FEATURE!)
# This works exactly the same as passing the folder path
init_ras_project(prj_file, RAS_VERSION)
print(f"Successfully initialized project using .prj file path!")
print(f"Project name: {ras.project_name}")
print(f"Project folder: {ras.project_folder}")
print(f"PRJ file: {ras.prj_file}")

# Verify both methods produce identical results
print(f"\n✓ Both folder path and .prj file path initialization methods produce the same result!")
print(f"✓ The project folder is automatically extracted from the .prj file's parent directory")
Text Only
2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 7.0 at C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.7 Beta 5 at C:\Program Files (x86)\HEC\HEC-RAS\6.7 Beta 5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.7 Beta 4 at C:\Program Files (x86)\HEC\HEC-RAS\6.7 Beta 4\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.6 at C:\Program Files (x86)\HEC\HEC-RAS\6.6\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.5 at C:\Program Files (x86)\HEC\HEC-RAS\6.5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.4.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.4.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.3.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.3.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.3 at C:\Program Files (x86)\HEC\HEC-RAS\6.3\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.2 at C:\Program Files (x86)\HEC\HEC-RAS\6.2\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.0 at C:\Program Files (x86)\HEC\HEC-RAS\6.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.7 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.7\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.6 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.6\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.5 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.4 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.4\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.3 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.3\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.1 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0 at C:\Program Files (x86)\HEC\HEC-RAS\5.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 4.1.0 at C:\Program Files (x86)\HEC\HEC-RAS\4.1.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 4.0 at C:\Program Files (x86)\HEC\HEC-RAS\4.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered 20 installed HEC-RAS version(s)


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - HEC-RAS 7.0 found via version discovery: C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe


2026-06-11 15:50:43 - ras_commander.RasMap - INFO - Successfully parsed RASMapper file: <repo>\examples\example_projects\Balde Eagle Creek_101\BaldEagle.rasmap


Found .prj file: <repo>\examples\example_projects\Balde Eagle Creek_101\BaldEagle.prj
File name: BaldEagle.prj



2026-06-11 15:50:43 - ras_commander.RasPrj - WARNING - Could not resolve project CRS for <repo>\examples\example_projects\Balde Eagle Creek_101


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - ras-commander v0.98.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - Project initialized: BaldEagle | Folder: <repo>\examples\example_projects\Balde Eagle Creek_101


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - Using HEC-RAS executable: C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - 
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/
Repo: https://github.com/gpt-cmdr/ras-commander
═══════════════════════════════════════════════════════════════════════

PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
  ras.plan_df        Plans, HDF paths, geometry/flow associations
  ras.geom_df        Geometry files and HDF preprocessor paths
  ras.flow_df        Steady flow files
  ras.unsteady_df    Unsteady flow files and configurations
  ras.boundaries_df  Boundary conditions (type, name, location)
  ras.results_df     Lightweight HDF results summaries
  ras.rasmap_df      RASMapper layers, terrain, land cover paths

KEY APIS (static classes — call directly, never instantiate):
  Execution:    RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
  Plan Files:   RasPlan.clone_plan() / clone_geom() / set_geom()
  Unsteady:     RasUnsteady — IC/BC management, gate openings, precipitation
  Geometry:     GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
  HDF Results:  HdfResultsPlan.get_wse() / get_compute_messages()
                HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
                HdfMesh.get_mesh_cell_points()
  QA/QC:        RasCheck.run_check() / RasFixit (geometry repair)
  DSS:          RasDss.get_timeseries() / check_pathname()
  USGS:         UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
  Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
  Terrain:      RasTerrain.create_terrain_hdf() / RasTerrainMod

MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.

EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
  400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
  Review relevant notebooks before assembling new workflows.

PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
  headless execution, data access, geometry modification, and preprocessing
  is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
  Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════


Successfully initialized project using .prj file path!
Project name: BaldEagle
Project folder: <repo>\examples\example_projects\Balde Eagle Creek_101
PRJ file: <repo>\examples\example_projects\Balde Eagle Creek_101\BaldEagle.prj

✓ Both folder path and .prj file path initialization methods produce the same result!
✓ The project folder is automatically extracted from the .prj file's parent directory

Alternative: Initialize Using .prj File Path

New Feature: You can now initialize a project by providing the direct path to a .prj file instead of the project folder. This is especially useful when: - Working with file selection dialogs (which return file paths) - Using configuration files that store specific .prj file paths - Working with folders that contain multiple projects - Building command-line tools that accept file paths

The function automatically: 1. Validates that the file has a .prj extension 2. Verifies the file contains "Proj Title=" to confirm it's a HEC-RAS project file (not a plan file) 3. Extracts the parent folder and uses it as the project folder 4. Optimizes initialization by passing the .prj file directly (avoids re-searching)

Let's see this in action:

Python
# Explore the global ras object with our utility function
print_ras_object_data(ras, "Global RAS Object (Bald Eagle Creek)")
Text Only
Global RAS Object (Bald Eagle Creek) Data:
==================================================
Project Name: BaldEagle
Project Folder: <repo>\examples\example_projects\Balde Eagle Creek_101
PRJ File: <repo>\examples\example_projects\Balde Eagle Creek_101\BaldEagle.prj
HEC-RAS Executable Path: C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe

Plan Files DataFrame (ras.plan_df):
plan_number unsteady_number geometry_number Plan Title Program Version Short Identifier Simulation Date Computation Interval Mapping Interval Run HTab Run UNet Run Sediment Run PostProcess Run WQNet UNET Use Existing IB Tables Write IC File Write IC File at Fixed DateTime IC Time Write IC File Reoccurance Write IC File at Sim End UNET D1 Cores UNET D2 Cores PS Cores DSS File Friction Slope Method HDF_Results_Path Geom File Geom Path Flow File Flow Path full_path flow_type
0 01 02 01 Unsteady with Bridges and Dam 5.00 UnsteadyFlow 18FEB1999,0000,24FEB1999,0500 2MIN 1HOUR 1 1 0 1 0 -1 0 0 ,, 0 0.0 0.0 None dss 2 None 01 ... 02 ... ... Unsteady
1 02 NaN 01 Steady Flow Run NaN SteadyRun 02/18/1999,0000,02/24/1999,0500 2MIN NaN 1 1 NaN 1 NaN NaN 0 NaN NaN NaN NaN NaN None dss 1 None 01 ... 02 ... ... Steady
Text Only
Steady Flow Files DataFrame:
flow_number full_path unsteady_number Flow Title description
0 02 ... None Steady Flow Data
1 01 ... None Debug Mode - PostProcess Steady Flow
Text Only
Unsteady Flow Files DataFrame (ras.unsteady_df):
unsteady_number full_path Flow Title Program Version Use Restart Precipitation Mode Wind Mode Met BC=Precipitation|Mode Met BC=Evapotranspiration|Mode Met BC=Precipitation|Expanded View Met BC=Precipitation|Constant Units Met BC=Precipitation|Gridded Source description
0 02 ... Flow Hydrograph 2 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS
Text Only
Geometry Files DataFrame (ras.geom_df):
geom_file geom_number full_path hdf_path has_1d_xs has_2d_mesh num_cross_sections num_inline_structures num_bridges num_culverts num_weirs num_gates num_lateral_structures num_sa_2d_connections mesh_cell_count mesh_area_names geom_title description
0 g01 01 ... ... True False 178 0 0 0 0 1 0 0 0 [] Existing Conditions - GIS Data Foster Joseph Sayers Dam and Reservoir
Text Only
HDF Entries DataFrame (ras.get_hdf_entries()):
plan_number unsteady_number geometry_number Plan Title Program Version Short Identifier Simulation Date Computation Interval Mapping Interval Run HTab ... PS Cores DSS File Friction Slope Method HDF_Results_Path Geom File Geom Path Flow File Flow Path full_path flow_type

0 rows × 32 columns

Text Only
Boundary Conditions DataFrame (ras.boundaries_df):
unsteady_number boundary_condition_number river_reach_name river_station storage_area_name pump_station_name area_2d bc_line_name bc_type hydrograph_type ... Program Version Use Restart Precipitation Mode Wind Mode Met BC=Precipitation|Mode Met BC=Evapotranspiration|Mode Met BC=Precipitation|Expanded View Met BC=Precipitation|Constant Units Met BC=Precipitation|Gridded Source description
0 02 1 Bald Eagle Loc Hav 138154.4 Flow Hydrograph Flow Hydrograph ... 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS
1 02 2 Bald Eagle Loc Hav 81500 Gate Opening NaN ... 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS
2 02 3 Bald Eagle Loc Hav 659.942 Rating Curve NaN ... 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS

3 rows × 32 columns

Geometry Metadata Columns (New in v0.88+)

Starting with ras-commander v0.88, geom_df automatically includes 12 metadata columns that provide an instant overview of geometry contents:

Boolean Flags: - has_1d_xs - Contains 1D cross sections - has_2d_mesh - Contains 2D mesh areas

Element Counts: - num_cross_sections - Count of 1D cross sections - num_inline_structures - Total bridges + culverts + weirs - num_bridges - Bridge count - num_culverts - Culvert count - num_weirs - Inline weir count - num_gates - Gate count - num_lateral_structures - Lateral structure count - num_sa_2d_connections - Storage Area to 2D connections

2D Mesh Info: - mesh_cell_count - Total 2D mesh cells - mesh_area_names - List of 2D flow area names

Performance: These counts are extracted efficiently from HDF files (10-50ms per geometry) when .g##.hdf files exist, with automatic fallback to plain text parsing.

Let's examine these metadata columns:

Python
# View geometry metadata columns
print("Geometry Metadata for Bald Eagle Creek:")
print("=" * 60)

# Display all metadata columns
metadata_cols = [
    'geom_number', 'has_1d_xs', 'has_2d_mesh', 'num_cross_sections',
    'num_inline_structures', 'num_bridges', 'num_culverts',
    'num_weirs', 'num_gates', 'mesh_cell_count', 'mesh_area_names'
]

print(ras.geom_df[metadata_cols])

# Show detailed info for first geometry
print(f"\nDetailed view of geometry {ras.geom_df.iloc[0]['geom_number']}:")
for col in metadata_cols:
    value = ras.geom_df.iloc[0][col]
    print(f"  {col}: {value}")
Text Only
Geometry Metadata for Bald Eagle Creek:
============================================================
  geom_number  has_1d_xs  has_2d_mesh  num_cross_sections  \
0          01       True        False                 178

   num_inline_structures  num_bridges  num_culverts  num_weirs  num_gates  \
0                      0            0             0          0          1

   mesh_cell_count mesh_area_names  
0                0              []

Detailed view of geometry 01:
  geom_number: 01
  has_1d_xs: True
  has_2d_mesh: False
  num_cross_sections: 178
  num_inline_structures: 0
  num_bridges: 0
  num_culverts: 0
  num_weirs: 0
  num_gates: 1
  mesh_cell_count: 0
  mesh_area_names: []

Understanding the RAS Object Structure

Each RAS object contains several important components:

  1. Project Metadata:
  2. project_name: Name of the HEC-RAS project
  3. project_folder: Directory containing project files
  4. prj_file: Path to the main .prj file

  5. ras_exe_path: Path to the HEC-RAS executable

  6. Project DataFrames:

  7. plan_df: Information about all plan files (.p*)
  8. flow_df: Information about all steady flow files (.f*)
  9. unsteady_df: Information about all unsteady flow files (.u*)
  10. geom_df: Information about all geometry files (.g*)

  11. boundaries_df: Information about all boundary conditions

  12. Methods for Data Access:

  13. get_plan_entries(): Get plan file information
  14. get_flow_entries(): Get flow file information
  15. get_unsteady_entries(): Get unsteady flow file information
  16. get_geom_entries(): Get geometry file information
  17. get_hdf_entries(): Get HDF file paths for result files
  18. get_boundary_conditions(): Get boundary condition details

Let's see how to access specific information from these components:

Python
# Get the first plan's details
if not ras.plan_df.empty:
    first_plan = ras.plan_df.iloc[0]
    print(f"First plan number: {first_plan['plan_number']}")
    print(f"Plan path: {first_plan['full_path']}")

    # Get the geometry file for this plan
    geom_id = first_plan.get('Geom File', '').replace('g', '')
    if geom_id:
        geom_info = ras.geom_df[ras.geom_df['geom_number'] == geom_id]
        if not geom_info.empty:
            print(f"Geometry file: {geom_info.iloc[0]['full_path']}")

    # Get the HDF results file for this plan (if exists)
    if 'HDF_Results_Path' in first_plan and first_plan['HDF_Results_Path']:
        print(f"Results file: {first_plan['HDF_Results_Path']}")
else:
    print("No plans found in the project.")
Text Only
First plan number: 01
Plan path: <repo>\examples\example_projects\Balde Eagle Creek_101\BaldEagle.p01
Geometry file: <repo>\examples\example_projects\Balde Eagle Creek_101\BaldEagle.g01

Working with Boundary Conditions

Boundary conditions define the inputs and outputs of your model. Let's see how to access boundary condition information:

Python
# View the boundary conditions DataFrame
ras.boundaries_df
unsteady_number boundary_condition_number river_reach_name river_station storage_area_name pump_station_name area_2d bc_line_name bc_type hydrograph_type ... Program Version Use Restart Precipitation Mode Wind Mode Met BC=Precipitation|Mode Met BC=Evapotranspiration|Mode Met BC=Precipitation|Expanded View Met BC=Precipitation|Constant Units Met BC=Precipitation|Gridded Source description
0 02 1 Bald Eagle Loc Hav 138154.4 Flow Hydrograph Flow Hydrograph ... 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS
1 02 2 Bald Eagle Loc Hav 81500 Gate Opening NaN ... 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS
2 02 3 Bald Eagle Loc Hav 659.942 Rating Curve NaN ... 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS

3 rows × 32 columns

Approach 2: Using Custom RAS Objects

For more complex scripts or when working with multiple projects, it's better to create and use separate RAS objects. This approach:

  • Creates independent RAS objects for each project
  • Avoids overwriting the global ras object
  • Provides clearer separation between projects
  • Allows working with multiple projects simultaneously
  • Requires saving the return value from init_ras_project()

Let's initialize multiple projects with custom RAS objects:

Python
# Initialize multiple project instances with custom RAS objects
# Note: This also updates the global 'ras' object each time, but we'll use the custom instances
# Parameters remain the same as before
multi_2d_project = RasPrj()
init_ras_project(multi_2d_path, RAS_VERSION, ras_object=multi_2d_project)
print(f"\nMulti2D project initialized with its own RAS object")

muncie_project = RasPrj()
init_ras_project(muncie_path, RAS_VERSION, ras_object=muncie_project)
print(f"\nMuncie project initialized with its own RAS object")

# Note that the global 'ras' object now points to the Muncie project
# The global 'ras' object gets overwritten every time a project is initialized ,
print(f"\nGlobal 'ras' object now points to: {ras.project_name} since it was the last one initialized.  Avoid the global object when using multiple projects.")
Text Only
2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 7.0 at C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.7 Beta 5 at C:\Program Files (x86)\HEC\HEC-RAS\6.7 Beta 5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.7 Beta 4 at C:\Program Files (x86)\HEC\HEC-RAS\6.7 Beta 4\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.6 at C:\Program Files (x86)\HEC\HEC-RAS\6.6\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.5 at C:\Program Files (x86)\HEC\HEC-RAS\6.5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.4.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.4.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.3.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.3.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.3 at C:\Program Files (x86)\HEC\HEC-RAS\6.3\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.2 at C:\Program Files (x86)\HEC\HEC-RAS\6.2\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.0 at C:\Program Files (x86)\HEC\HEC-RAS\6.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.7 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.7\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.6 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.6\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.5 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.4 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.4\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.3 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.3\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.1 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0 at C:\Program Files (x86)\HEC\HEC-RAS\5.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 4.1.0 at C:\Program Files (x86)\HEC\HEC-RAS\4.1.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 4.0 at C:\Program Files (x86)\HEC\HEC-RAS\4.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered 20 installed HEC-RAS version(s)


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - HEC-RAS 7.0 found via version discovery: C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe


2026-06-11 15:50:43 - ras_commander.RasMap - INFO - Successfully parsed RASMapper file: <repo>\examples\example_projects\BaldEagleCrkMulti2D_101\BaldEagleDamBrk.rasmap


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - ras-commander v0.98.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - Project initialized: BaldEagleDamBrk | Folder: <repo>\examples\example_projects\BaldEagleCrkMulti2D_101


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - Using HEC-RAS executable: C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - 
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/
Repo: https://github.com/gpt-cmdr/ras-commander
═══════════════════════════════════════════════════════════════════════

PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
  ras_object.plan_df        Plans, HDF paths, geometry/flow associations
  ras_object.geom_df        Geometry files and HDF preprocessor paths
  ras_object.flow_df        Steady flow files
  ras_object.unsteady_df    Unsteady flow files and configurations
  ras_object.boundaries_df  Boundary conditions (type, name, location)
  ras_object.results_df     Lightweight HDF results summaries
  ras_object.rasmap_df      RASMapper layers, terrain, land cover paths

KEY APIS (static classes — call directly, never instantiate):
  Execution:    RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
  Plan Files:   RasPlan.clone_plan() / clone_geom() / set_geom()
  Unsteady:     RasUnsteady — IC/BC management, gate openings, precipitation
  Geometry:     GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
  HDF Results:  HdfResultsPlan.get_wse() / get_compute_messages()
                HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
                HdfMesh.get_mesh_cell_points()
  QA/QC:        RasCheck.run_check() / RasFixit (geometry repair)
  DSS:          RasDss.get_timeseries() / check_pathname()
  USGS:         UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
  Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
  Terrain:      RasTerrain.create_terrain_hdf() / RasTerrainMod

MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.

EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
  400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
  Review relevant notebooks before assembling new workflows.

PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
  headless execution, data access, geometry modification, and preprocessing
  is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
  Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 7.0 at C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.7 Beta 5 at C:\Program Files (x86)\HEC\HEC-RAS\6.7 Beta 5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.7 Beta 4 at C:\Program Files (x86)\HEC\HEC-RAS\6.7 Beta 4\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.6 at C:\Program Files (x86)\HEC\HEC-RAS\6.6\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.5 at C:\Program Files (x86)\HEC\HEC-RAS\6.5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.4.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.4.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.3.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.3.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.3 at C:\Program Files (x86)\HEC\HEC-RAS\6.3\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.2 at C:\Program Files (x86)\HEC\HEC-RAS\6.2\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.1 at C:\Program Files (x86)\HEC\HEC-RAS\6.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 6.0 at C:\Program Files (x86)\HEC\HEC-RAS\6.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.7 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.7\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.6 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.6\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.5 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.5\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.4 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.4\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.3 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.3\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0.1 at C:\Program Files (x86)\HEC\HEC-RAS\5.0.1\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 5.0 at C:\Program Files (x86)\HEC\HEC-RAS\5.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 4.1.0 at C:\Program Files (x86)\HEC\HEC-RAS\4.1.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered HEC-RAS 4.0 at C:\Program Files (x86)\HEC\HEC-RAS\4.0\Ras.exe via filesystem (x86)


2026-06-11 15:50:43 - ras_commander.RasUtils - INFO - Discovered 20 installed HEC-RAS version(s)


2026-06-11 15:50:43 - ras_commander.RasPrj - INFO - HEC-RAS 7.0 found via version discovery: C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe


2026-06-11 15:50:44 - ras_commander.RasMap - INFO - Successfully parsed RASMapper file: <repo>\examples\example_projects\Muncie_101\Muncie.rasmap


2026-06-11 15:50:44 - ras_commander.RasPrj - INFO - ras-commander v0.98.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander


2026-06-11 15:50:44 - ras_commander.RasPrj - INFO - Project initialized: Muncie | Folder: <repo>\examples\example_projects\Muncie_101


2026-06-11 15:50:44 - ras_commander.RasPrj - INFO - Using HEC-RAS executable: C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe


2026-06-11 15:50:44 - ras_commander.RasPrj - INFO - 
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/
Repo: https://github.com/gpt-cmdr/ras-commander
═══════════════════════════════════════════════════════════════════════

PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
  ras_object.plan_df        Plans, HDF paths, geometry/flow associations
  ras_object.geom_df        Geometry files and HDF preprocessor paths
  ras_object.flow_df        Steady flow files
  ras_object.unsteady_df    Unsteady flow files and configurations
  ras_object.boundaries_df  Boundary conditions (type, name, location)
  ras_object.results_df     Lightweight HDF results summaries
  ras_object.rasmap_df      RASMapper layers, terrain, land cover paths

KEY APIS (static classes — call directly, never instantiate):
  Execution:    RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
  Plan Files:   RasPlan.clone_plan() / clone_geom() / set_geom()
  Unsteady:     RasUnsteady — IC/BC management, gate openings, precipitation
  Geometry:     GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
  HDF Results:  HdfResultsPlan.get_wse() / get_compute_messages()
                HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
                HdfMesh.get_mesh_cell_points()
  QA/QC:        RasCheck.run_check() / RasFixit (geometry repair)
  DSS:          RasDss.get_timeseries() / check_pathname()
  USGS:         UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
  Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
  Terrain:      RasTerrain.create_terrain_hdf() / RasTerrainMod

MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.

EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
  400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
  Review relevant notebooks before assembling new workflows.

PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
  headless execution, data access, geometry modification, and preprocessing
  is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
  Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════



Multi2D project initialized with its own RAS object

Muncie project initialized with its own RAS object

Global 'ras' object now points to: BaldEagle since it was the last one initialized.  Avoid the global object when using multiple projects.
Python
# Compare geometry types across Muncie project (has both 1D and 2D geometries)
print("Muncie Geometry Comparison:")
print("=" * 60)

# Display metadata for all geometries in Muncie
display.display(muncie_project.geom_df[metadata_cols])

# Filter geometries by type
pure_1d = muncie_project.geom_df[muncie_project.geom_df['has_1d_xs'] & ~muncie_project.geom_df['has_2d_mesh']]
mixed_1d_2d = muncie_project.geom_df[muncie_project.geom_df['has_1d_xs'] & muncie_project.geom_df['has_2d_mesh']]
pure_2d = muncie_project.geom_df[~muncie_project.geom_df['has_1d_xs'] & muncie_project.geom_df['has_2d_mesh']]

print(f"\nGeometry Type Summary:")
print(f"  Pure 1D geometries: {len(pure_1d)} (geom_numbers: {pure_1d['geom_number'].tolist()})")
print(f"  Mixed 1D/2D geometries: {len(mixed_1d_2d)} (geom_numbers: {mixed_1d_2d['geom_number'].tolist()})")
print(f"  Pure 2D geometries: {len(pure_2d)} (geom_numbers: {pure_2d['geom_number'].tolist()})")

# Show details for a mixed geometry
if len(mixed_1d_2d) > 0:
    mixed_geom = mixed_1d_2d.iloc[0]
    print(f"\nMixed 1D/2D Geometry Details (g{mixed_geom['geom_number']}):")
    print(f"  Cross sections: {mixed_geom['num_cross_sections']}")
    print(f"  Mesh areas: {mixed_geom['mesh_area_names']}")
    print(f"  Total mesh cells: {mixed_geom['mesh_cell_count']}")
Text Only
Muncie Geometry Comparison:
============================================================
geom_number has_1d_xs has_2d_mesh num_cross_sections num_inline_structures num_bridges num_culverts num_weirs num_gates mesh_cell_count mesh_area_names
0 01 True False 61 0 0 0 0 0 0 []
1 02 True True 61 0 0 0 0 0 5391 [2D Interior Area]
2 04 True True 61 0 0 0 0 0 5391 [2D Interior Area]
Text Only
Geometry Type Summary:
  Pure 1D geometries: 1 (geom_numbers: ['01'])
  Mixed 1D/2D geometries: 2 (geom_numbers: ['02', '04'])
  Pure 2D geometries: 0 (geom_numbers: [])

Mixed 1D/2D Geometry Details (g02):
  Cross sections: 61
  Mesh areas: ['2D Interior Area']
  Total mesh cells: 5391

Exploring Multiple Projects

Now we have three RAS objects: - multi_2d_project: Our custom object for the Multi2D project - muncie_project: Our custom object for the Muncie project - ras: The global object (which now points to Muncie)

Let's examine the Multi2D project:

Python
display.display(multi_2d_project.plan_df)
plan_number unsteady_number geometry_number Plan Title Program Version Short Identifier Simulation Date Computation Interval Mapping Interval Run HTab ... Friction Slope Method UNET D2 SolverType UNET D2 Name HDF_Results_Path Geom File Geom Path Flow File Flow Path full_path flow_type
0 13 07 06 PMF with Multi 2D Areas 5.10 PMF Multi 2D 01JAN1999,1200,04JAN1999,1200 30SEC 30MIN 1 ... 1 Pardiso (Direct) 193 None 06 ... 07 ... ... Unsteady
1 15 12 08 1d-2D Dambreak Refined Grid 5.10 1D-2D Refined Grid 01JAN1999,1200,04JAN1999,1200 20SEC 5MIN 1 ... 1 NaN BaldEagleCr None 08 ... 12 ... ... Unsteady
2 17 09 10 2D to 1D No Dam 5.00 2D to 1D No Dam 01JAN1999,1200,06JAN1999,1200 1MIN 5MIN 1 ... 1 NaN Upstream2D None 10 ... 09 ... ... Unsteady
3 18 10 11 2D to 2D Run 5.00 2D to 2D Run 01JAN1999,1200,04JAN1999,1200 20SEC 5MIN 1 ... 1 NaN BaldEagleCr None 11 ... 10 ... ... Unsteady
4 19 11 12 SA to 2D Dam Break Run 5.00 SA to 2D Dam Break 01JAN1999,1200,04JAN1999,1200 20SEC 10MIN 1 ... 1 NaN BaldEagleCr None 12 ... 11 ... ... Unsteady
5 03 13 09 Single 2D Area - Internal Dam Structure 5.04 Single 2D 01JAN1999,1200,04JAN1999,1200 30SEC 10MIN 1 ... 1 NaN BaldEagleCr None 09 ... 13 ... ... Unsteady
6 04 01 13 SA to 2D Area Conn - 2D Levee Structure 5.00 2D Levee Struc 01JAN1999,1200,04JAN1999,1200 20SEC 5MIN 1 ... 1 NaN BaldEagleCr None 13 ... 01 ... ... Unsteady
7 02 01 01 SA to Detailed 2D Breach 5.10 SA-2D Det Brch 01JAN1999,1200,04JAN1999,1200 10SEC 5MIN 1 ... 1 Pardiso (Direct) BaldEagleCr None 01 ... 01 ... ... Unsteady
8 01 01 01 SA to Detailed 2D Breach FEQ 5.03 SA-2D Det FEQ 01JAN1999,1200,04JAN1999,1200 5SEC 5MIN 1 ... 1 NaN BaldEagleCr None 01 ... 01 ... ... Unsteady
9 05 02 03 Single 2D area with Bridges FEQ 5.10 Single 2D Bridges FEQ 01JAN1999,1200,04JAN1999,1200 5SEC 10MIN -1 ... 1 PARDISO (Direct) BaldEagleCr None 03 ... 02 ... ... Unsteady
10 06 03 09 Gridded Precip - Infiltration 6.00 Grid Precip Infiltration 09SEP2018,0000,14SEP2018,0000 20SEC 10MIN -1 ... 1 Pardiso (Direct) BaldEagleCr None 09 ... 03 ... ... Unsteady

11 rows × 36 columns

Python
# Examine the Multi2D project
print_ras_object_data(multi_2d_project, "Multi2D Project")
Text Only
Multi2D Project Data:
==================================================
Project Name: BaldEagleDamBrk
Project Folder: <repo>\examples\example_projects\BaldEagleCrkMulti2D_101
PRJ File: <repo>\examples\example_projects\BaldEagleCrkMulti2D_101\BaldEagleDamBrk.prj
HEC-RAS Executable Path: C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe

Plan Files DataFrame (ras.plan_df):
plan_number unsteady_number geometry_number Plan Title Program Version Short Identifier Simulation Date Computation Interval Mapping Interval Run HTab Run UNet Run Sediment Run PostProcess Run WQNet UNET Use Existing IB Tables UNET 1D Methodology Write IC File Write IC File at Fixed DateTime IC Time Write IC File Reoccurance Write IC File at Sim End description UNET D1 Cores UNET D2 Cores PS Cores DSS File Friction Slope Method UNET D2 SolverType UNET D2 Name HDF_Results_Path Geom File Geom Path Flow File Flow Path full_path flow_type
0 13 07 06 PMF with Multi 2D Areas 5.10 PMF Multi 2D 01JAN1999,1200,04JAN1999,1200 30SEC 30MIN 1 1 0 1 0 -1 Finite Difference 0 0 ,, 0 Predominatntly a 1D model with multiple 2D are... 0 8 None dss 1 Pardiso (Direct) 193 None 06 ... 07 ... ... Unsteady
1 15 12 08 1d-2D Dambreak Refined Grid 5.10 1D-2D Refined Grid 01JAN1999,1200,04JAN1999,1200 20SEC 5MIN 1 1 0 1 0 -1 Finite Difference 0 0 ,, 0 This is an example of connecting an upstream 1... 0 6 None dss 1 NaN BaldEagleCr None 08 ... 12 ... ... Unsteady
2 17 09 10 2D to 1D No Dam 5.00 2D to 1D No Dam 01JAN1999,1200,06JAN1999,1200 1MIN 5MIN 1 1 0 1 0 -1 NaN 0 0 ,, 0 This is an example of how to connect an upstre... 0 0 None dss 1 NaN Upstream2D None 10 ... 09 ... ... Unsteady
3 18 10 11 2D to 2D Run 5.00 2D to 2D Run 01JAN1999,1200,04JAN1999,1200 20SEC 5MIN 1 1 0 1 0 -1 NaN 0 0 ,, 0 This is an example of how to connect one 2D fl... 0 8 None dss 1 NaN BaldEagleCr None 11 ... 10 ... ... Unsteady
4 19 11 12 SA to 2D Dam Break Run 5.00 SA to 2D Dam Break 01JAN1999,1200,04JAN1999,1200 20SEC 10MIN 1 1 0 1 0 -1 NaN 0 0 ,, 0 This is an example of how to connect a Storage... 0 0 None dss 1 NaN BaldEagleCr None 12 ... 11 ... ... Unsteady
5 03 13 09 Single 2D Area - Internal Dam Structure 5.04 Single 2D 01JAN1999,1200,04JAN1999,1200 30SEC 10MIN 1 1 0 1 0 -1 Finite Difference 0 0 ,, 0 In this example a single 2D flow area is used ... 0 10 None dss 1 NaN BaldEagleCr None 09 ... 13 ... ... Unsteady
6 04 01 13 SA to 2D Area Conn - 2D Levee Structure 5.00 2D Levee Struc 01JAN1999,1200,04JAN1999,1200 20SEC 5MIN 1 1 0 1 0 -1 NaN 0 0 ,, 0 This is an example of how to modify the 2D Mes... 0 6 None dss 1 NaN BaldEagleCr None 13 ... 01 ... ... Unsteady
7 02 01 01 SA to Detailed 2D Breach 5.10 SA-2D Det Brch 01JAN1999,1200,04JAN1999,1200 10SEC 5MIN 1 1 0 1 0 -1 Finite Difference 1 -1 ,03JAN1999,1200 0 This is an example of how to modify the 2D Mes... 0 0 None dss 1 Pardiso (Direct) BaldEagleCr None 01 ... 01 ... ... Unsteady
8 01 01 01 SA to Detailed 2D Breach FEQ 5.03 SA-2D Det FEQ 01JAN1999,1200,04JAN1999,1200 5SEC 5MIN 1 1 0 1 0 -1 NaN 0 0 ,, 0 This is an example of how to modify the 2D Mes... 0 0 None dss 1 NaN BaldEagleCr None 01 ... 01 ... ... Unsteady
9 05 02 03 Single 2D area with Bridges FEQ 5.10 Single 2D Bridges FEQ 01JAN1999,1200,04JAN1999,1200 5SEC 10MIN -1 -1 0 -1 0 -1 Finite Difference 0 0 ,, 0 In this example a single 2D flow area is used ... 0 10 None dss 1 PARDISO (Direct) BaldEagleCr None 03 ... 02 ... ... Unsteady
10 06 03 09 Gridded Precip - Infiltration 6.00 Grid Precip Infiltration 09SEP2018,0000,14SEP2018,0000 20SEC 10MIN -1 -1 0 -1 0 -1 Finite Difference 0 0 ,, 0 NaN 0 0 None dss 1 Pardiso (Direct) BaldEagleCr None 09 ... 03 ... ... Unsteady
Text Only
Steady Flow Files DataFrame:
Text Only
Unsteady Flow Files DataFrame (ras.unsteady_df):
unsteady_number full_path Flow Title Program Version Use Restart description Precipitation Mode Wind Mode Met BC=Precipitation|Mode Met BC=Evapotranspiration|Mode Met BC=Precipitation|Expanded View Met BC=Precipitation|Constant Units Met BC=Precipitation|Gridded Source
0 07 ... PMF with Multi 2D Areas 5.00 0 NaN NaN NaN NaN NaN NaN NaN
1 08 ... PMF for Upstream 2D 4.20 0 NaN NaN NaN NaN NaN NaN NaN
2 09 ... Upstream 2D 5.00 0 NaN NaN NaN NaN NaN NaN NaN
3 10 ... 1972 Flood Event - 2D to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
4 11 ... 1972 Flood Event - SA to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
5 12 ... PMF for 1D - 2D 5.00 0 NaN NaN NaN NaN NaN NaN NaN
6 13 ... Single 2D Area 5.00 0 NaN NaN NaN NaN NaN NaN NaN
7 01 ... 1972 Flood Event - 2D Leve Structure 5.10 0 NaN NaN NaN NaN NaN NaN NaN
8 02 ... Single 2D Area with Bridges 5.10 0 NaN NaN NaN NaN NaN NaN NaN
9 03 ... Gridded Precipitation 6.00 0 Enable No Wind Forces Gridded None -1 mm/hr DSS
Text Only
Geometry Files DataFrame (ras.geom_df):
geom_file geom_number full_path hdf_path has_1d_xs has_2d_mesh num_cross_sections num_inline_structures num_bridges num_culverts num_weirs num_gates num_lateral_structures num_sa_2d_connections mesh_cell_count mesh_area_names geom_title description
0 g06 06 ... ... True True 192 0 0 0 0 1 0 1 4120 [193, 194, LockHaven] Bald Eagle Multi 2D Areas Foster Joseph Sayers Dam and Reservoir
1 g08 08 ... ... True True 89 0 0 0 0 1 0 0 14206 [BaldEagleCr] 1D-2D Dam Break Model Refined Grid Foster Joseph Sayers Dam and Reservoir
2 g10 10 ... ... True True 69 0 0 0 0 0 0 0 5330 [Upstream2D] U.S 2D - D.S 1D No Dam None
3 g11 11 ... ... False True 0 0 0 0 0 1 0 1 4425 [BaldEagleCr, Upper 2D Area] 2D to 2D Connection None
4 g12 12 ... ... False True 0 0 0 0 0 1 0 1 3439 [BaldEagleCr] SA to 2D Connection None
5 g09 09 ... ... False True 0 0 0 0 0 1 0 1 18066 [BaldEagleCr] Single 2D Area - Internal Dam Structure None
6 g13 13 ... ... False True 0 0 0 0 0 1 0 4 14364 [BaldEagleCr] SA to 2D Flow Area None
7 g01 01 ... ... False True 0 0 0 0 0 1 0 4 87039 [BaldEagleCr] SA to 2D Flow Area - Detailed None
8 g03 03 ... ... False True 0 0 0 0 0 1 0 11 24718 [BaldEagleCr] Single 2D Area with Bridges and Breaklin None
9 g02 02 ... ... False True 0 0 0 0 0 1 0 2 28449 [BaldEagleCr] Single 2D Area -With Infiltration None
Text Only
HDF Entries DataFrame (ras.get_hdf_entries()):
plan_number unsteady_number geometry_number Plan Title Program Version Short Identifier Simulation Date Computation Interval Mapping Interval Run HTab ... Friction Slope Method UNET D2 SolverType UNET D2 Name HDF_Results_Path Geom File Geom Path Flow File Flow Path full_path flow_type

0 rows × 36 columns

Text Only
Boundary Conditions DataFrame (ras.boundaries_df):
unsteady_number boundary_condition_number river_reach_name river_station storage_area_name pump_station_name area_2d bc_line_name bc_type hydrograph_type ... Program Version Use Restart description Precipitation Mode Wind Mode Met BC=Precipitation|Mode Met BC=Evapotranspiration|Mode Met BC=Precipitation|Expanded View Met BC=Precipitation|Constant Units Met BC=Precipitation|Gridded Source
0 07 1 Bald Eagle Cr. Lock Haven 137520 Flow Hydrograph Flow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
1 07 2 Bald Eagle Cr. Lock Haven 81454 Gate Opening NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
2 07 3 Bald Eagle Cr. Lock Haven 28519 Lateral Inflow Hydrograph Lateral Inflow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
3 07 4 Bald Eagle Cr. Lock Haven 1 Lateral Inflow Hydrograph Lateral Inflow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
4 07 5 Bald Eagle Cr. Lock Haven 136948 82303 Uniform Lateral Inflow Hydrograph Uniform Lateral Inflow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
5 07 6 Bald Eagle Cr. Lock Haven 80720 67130 Uniform Lateral Inflow Hydrograph Uniform Lateral Inflow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
6 07 7 Bald Eagle Cr. Lock Haven 76865 Lateral Inflow Hydrograph Lateral Inflow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
7 07 8 Bald Eagle Cr. Lock Haven 67130 Lateral Inflow Hydrograph Lateral Inflow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
8 07 9 Bald Eagle Cr. Lock Haven 66041 1 Uniform Lateral Inflow Hydrograph Uniform Lateral Inflow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
9 07 10 Bald Eagle Cr. Lock Haven -1867 Normal Depth NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
10 08 1 Bald Eagle Cr. Lock Haven 28519 Lateral Inflow Hydrograph Lateral Inflow Hydrograph ... 4.20 0 NaN NaN NaN NaN NaN NaN NaN
11 08 2 Bald Eagle Cr. Lock Haven 1 Lateral Inflow Hydrograph Lateral Inflow Hydrograph ... 4.20 0 NaN NaN NaN NaN NaN NaN NaN
12 08 3 Bald Eagle Cr. Lock Haven 80720 67130 Uniform Lateral Inflow Hydrograph Uniform Lateral Inflow Hydrograph ... 4.20 0 NaN NaN NaN NaN NaN NaN NaN
13 08 4 Bald Eagle Cr. Lock Haven 76865 Lateral Inflow Hydrograph Lateral Inflow Hydrograph ... 4.20 0 NaN NaN NaN NaN NaN NaN NaN
14 08 5 Bald Eagle Cr. Lock Haven 67130 Lateral Inflow Hydrograph Lateral Inflow Hydrograph ... 4.20 0 NaN NaN NaN NaN NaN NaN NaN
15 08 6 Bald Eagle Cr. Lock Haven 66041 1 Uniform Lateral Inflow Hydrograph Uniform Lateral Inflow Hydrograph ... 4.20 0 NaN NaN NaN NaN NaN NaN NaN
16 08 7 Bald Eagle Cr. Lock Haven -1867 Normal Depth NaN ... 4.20 0 NaN NaN NaN NaN NaN NaN NaN
17 08 8 Upper 2D Area Upstream Q Flow Hydrograph Flow Hydrograph ... 4.20 0 NaN NaN NaN NaN NaN NaN NaN
18 08 9 Bald Eagle Cr. Lock Haven 81454 Gate Opening NaN ... 4.20 0 NaN NaN NaN NaN NaN NaN NaN
19 09 1 Bald Eagle Cr. Lock Haven 28519 Lateral Inflow Hydrograph Lateral Inflow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
20 09 2 Bald Eagle Cr. Lock Haven -1867 Normal Depth NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
21 09 3 Upstream2D USFlow Flow Hydrograph Flow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
22 10 1 BaldEagleCr DSNormalDepth Normal Depth NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
23 10 2 BaldEagleCr DS2NormalD Normal Depth NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
24 10 3 Gate Opening NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
25 10 4 Upper 2D Area Upstream Q Flow Hydrograph Flow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
26 11 1 Gate Opening NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
27 11 2 Reservoir Pool Upstream Q Lateral Inflow Hydrograph Lateral Inflow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
28 11 3 BaldEagleCr DS2NormalD Normal Depth NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
29 11 4 BaldEagleCr DSNormalDepth Normal Depth NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
30 12 1 Bald Eagle Cr. Lock Haven 137520 Flow Hydrograph Flow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
31 12 2 Bald Eagle Cr. Lock Haven 81454 Gate Opening NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
32 12 3 BaldEagleCr DSNormalDepth Normal Depth NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
33 12 4 BaldEagleCr DS2NormalD Normal Depth NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
34 13 1 BaldEagleCr DSNormalDepth Normal Depth NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
35 13 2 BaldEagleCr DS2NormalD Normal Depth NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
36 13 3 BaldEagleCr Upstream Inflow Flow Hydrograph Flow Hydrograph ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
37 13 4 Gate Opening NaN ... 5.00 0 NaN NaN NaN NaN NaN NaN NaN
38 01 1 Gate Opening NaN ... 5.10 0 NaN NaN NaN NaN NaN NaN NaN
39 01 2 Reservoir Pool Upstream Q Lateral Inflow Hydrograph Lateral Inflow Hydrograph ... 5.10 0 NaN NaN NaN NaN NaN NaN NaN
40 01 3 BaldEagleCr DSNormalDepth1 Normal Depth NaN ... 5.10 0 NaN NaN NaN NaN NaN NaN NaN
41 01 4 BaldEagleCr DSNormalDepth2 Normal Depth NaN ... 5.10 0 NaN NaN NaN NaN NaN NaN NaN
42 02 1 BaldEagleCr DSNormalDepth Normal Depth NaN ... 5.10 0 NaN NaN NaN NaN NaN NaN NaN
43 02 2 BaldEagleCr DS2NormalD Normal Depth NaN ... 5.10 0 NaN NaN NaN NaN NaN NaN NaN
44 02 3 BaldEagleCr Upstream Inflow Flow Hydrograph Flow Hydrograph ... 5.10 0 NaN NaN NaN NaN NaN NaN NaN
45 02 4 Gate Opening NaN ... 5.10 0 NaN NaN NaN NaN NaN NaN NaN
46 02 5 BaldEagleCr DS2NormalDepth Normal Depth NaN ... 5.10 0 NaN NaN NaN NaN NaN NaN NaN
47 03 1 BaldEagleCr DSNormalDepth Normal Depth NaN ... 6.00 0 Enable No Wind Forces Gridded None -1 mm/hr DSS
48 03 2 BaldEagleCr Upstream Inflow Flow Hydrograph Flow Hydrograph ... 6.00 0 Enable No Wind Forces Gridded None -1 mm/hr DSS
49 03 3 BaldEagleCr DS2NormalD Normal Depth NaN ... 6.00 0 Enable No Wind Forces Gridded None -1 mm/hr DSS
50 03 4 Gate Opening NaN ... 6.00 0 Enable No Wind Forces Gridded None -1 mm/hr DSS

51 rows × 44 columns

Python
# Examine the Muncie project
print_ras_object_data(muncie_project, "Muncie Project")
Text Only
Muncie Project Data:
==================================================
Project Name: Muncie
Project Folder: <repo>\examples\example_projects\Muncie_101
PRJ File: <repo>\examples\example_projects\Muncie_101\Muncie.prj
HEC-RAS Executable Path: C:\Program Files (x86)\HEC\HEC-RAS\7.0\Ras.exe

Plan Files DataFrame (ras.plan_df):
plan_number unsteady_number geometry_number Plan Title Program Version Short Identifier Simulation Date Computation Interval Mapping Interval Run HTab Run UNet Run Sediment Run PostProcess Run WQNet UNET Use Existing IB Tables UNET 1D Methodology Write IC File Write IC File at Fixed DateTime IC Time Write IC File Reoccurance Write IC File at Sim End UNET D1 Cores UNET D2 Cores PS Cores DSS File Friction Slope Method UNET D2 SolverType UNET D2 Name HDF_Results_Path Geom File Geom Path Flow File Flow Path full_path flow_type
0 01 01 01 Unsteady Multi  9-SA run 5.00 9-SAs 02JAN1900,0000,02JAN1900,2400 15SEC 5MIN 1 1 0 1 0 -1 NaN 0 0 ,, 0 0 0 None dss 1 NaN NaN None 01 ... 01 ... ... Unsteady
1 03 01 02 Unsteady Run with 2D 50ft Grid 5.10 2D 50ft Grid 02JAN1900,0000,02JAN1900,2400 10SEC 5MIN -1 -1 0 -1 0 -1 Finite Difference 0 0 ,, 0 0 4 None dss 1 Pardiso (Direct) 2D Interior Area None 02 ... 01 ... ... Unsteady
2 04 01 04 Unsteady Run with 2D 50ft User n Value R 5.10 50ft User n Regions 02JAN1900,0000,02JAN1900,2400 10SEC 5MIN 1 1 0 1 0 -1 Finite Difference 0 0 ,, 0 0 6 None dss 1 Pardiso (Direct) 2D Interior Area None 04 ... 01 ... ... Unsteady
Text Only
Steady Flow Files DataFrame:
flow_number full_path unsteady_number Flow Title Program Version description
0 01 ... None Steady Flow Profile 5.00
Text Only
Unsteady Flow Files DataFrame (ras.unsteady_df):
unsteady_number full_path Flow Title Program Version Use Restart Restart Filename Precipitation Mode Wind Mode Met BC=Precipitation|Expanded View Met BC=Precipitation|Gridded Source description
0 01 ... Flow Boundary Conditions 6.30 0 Muncie.p05.02JAN1900 1200.rst Disable No Wind Forces 0 DSS
Text Only
Geometry Files DataFrame (ras.geom_df):
geom_file geom_number full_path hdf_path has_1d_xs has_2d_mesh num_cross_sections num_inline_structures num_bridges num_culverts num_weirs num_gates num_lateral_structures num_sa_2d_connections mesh_cell_count mesh_area_names geom_title description
0 g01 01 ... ... True False 61 0 0 0 0 0 0 10 0 [] Muncie Base Geometry - 9 SAs None
1 g02 02 ... ... True True 61 0 0 0 0 0 0 0 5391 [2D Interior Area] Muncie Geometry - 2D 50ft Grid None
2 g04 04 ... ... True True 61 0 0 0 0 0 0 0 5391 [2D Interior Area] Muncie Geometry - 50ft User n Value Regi None
Text Only
HDF Entries DataFrame (ras.get_hdf_entries()):
plan_number unsteady_number geometry_number Plan Title Program Version Short Identifier Simulation Date Computation Interval Mapping Interval Run HTab ... Friction Slope Method UNET D2 SolverType UNET D2 Name HDF_Results_Path Geom File Geom Path Flow File Flow Path full_path flow_type

0 rows × 35 columns

Text Only
Boundary Conditions DataFrame (ras.boundaries_df):
unsteady_number boundary_condition_number river_reach_name river_station storage_area_name pump_station_name area_2d bc_line_name bc_type hydrograph_type ... full_path Flow Title Program Version Use Restart Restart Filename Precipitation Mode Wind Mode Met BC=Precipitation|Expanded View Met BC=Precipitation|Gridded Source description
0 01 1 White Muncie 15696.24 Flow Hydrograph Flow Hydrograph ... ... Flow Boundary Conditions 6.30 0 Muncie.p05.02JAN1900 1200.rst Disable No Wind Forces 0 DSS
1 01 2 White Muncie 237.6455 Normal Depth NaN ... ... Flow Boundary Conditions 6.30 0 Muncie.p05.02JAN1900 1200.rst Disable No Wind Forces 0 DSS

2 rows × 33 columns

Comparing Projects

Let's compare some key metrics of the two projects:

Python
# Create a comparison table of the two projects
comparison_data = {
    'Project Name': [multi_2d_project.project_name, muncie_project.project_name],
    'Number of Plans': [len(multi_2d_project.plan_df), len(muncie_project.plan_df)],
    'Number of Geometries': [len(multi_2d_project.geom_df), len(muncie_project.geom_df)],
    'Number of Flow Files': [len(multi_2d_project.flow_df), len(muncie_project.flow_df)],
    'Number of Unsteady Files': [len(multi_2d_project.unsteady_df), len(muncie_project.unsteady_df)],
    'Number of Boundary Conditions': [len(multi_2d_project.boundaries_df) if hasattr(multi_2d_project, 'boundaries_df') else 0, 
                                     len(muncie_project.boundaries_df) if hasattr(muncie_project, 'boundaries_df') else 0],
    'HDF Results Available': [len(multi_2d_project.get_hdf_entries()) > 0, len(muncie_project.get_hdf_entries()) > 0]
}

comparison_df = pd.DataFrame(comparison_data)
display.display(comparison_df)
Project Name Number of Plans Number of Geometries Number of Flow Files Number of Unsteady Files Number of Boundary Conditions HDF Results Available
0 BaldEagleDamBrk 11 10 0 10 51 False
1 Muncie 3 3 1 1 2 False

Project Initialization Best Practices

After exploring both approaches, here are some best practices for using RAS Commander:

  1. Choose Your Approach Based on Complexity:
  2. Simple Scripts (one project): Use the global ras object

  3. Complex Scripts (multiple projects): Use custom RAS objects

  4. Be Consistent:

  5. Don't mix global and custom approaches in the same script

  6. Use descriptive names for custom RAS objects

  7. Working with Project Files:

  8. Access project files through the RAS object's DataFrames

  9. Use helper functions like get_plan_path() to resolve paths

  10. Error Handling:

  11. Always check for empty DataFrames before accessing their contents

  12. Use the built-in logging to track operations

  13. Performance Considerations:

  14. For large projects, consider using the HDF classes directly
  15. Cache results of expensive operations when possible

Summary of Key Functions

  • init_ras_project(project_folder, ras_version): Initialize a RAS project
  • RasExamples().extract_project(project_name): Extract example projects
  • RasPrj.get_project_name(): Get the name of the project
  • RasPrj.get_plan_entries(): Get plan file information
  • RasPrj.get_flow_entries(): Get flow file information
  • RasPrj.get_unsteady_entries(): Get unsteady flow file information
  • RasPrj.get_geom_entries(): Get geometry file information
  • RasPrj.get_hdf_entries(): Get HDF result file information
  • RasPrj.get_boundary_conditions(): Get boundary condition details
  • RasPlan.get_plan_path(plan_number): Get the path to a plan file
  • RasPlan.get_geom_path(geom_number): Get the path to a geometry file
  • RasPlan.get_flow_path(flow_number): Get the path to a flow file
  • RasPlan.get_unsteady_path(unsteady_number): Get the path to an unsteady flow file

Discovering Plan Outputs

After running HEC-RAS plans, you can discover what results are available:

HDF Result Files

Python
# Get HDF results info from plan_df
ras.plan_df[['plan_number', 'Plan Title', 'HDF_Results_Path']]

# Or use get_hdf_entries() for detailed HDF information
ras.get_hdf_entries()

Available Output Discovery Methods

  • HdfBase.get_dataset_info(plan_number, group_path) - Explore HDF structure
  • HdfResultsPlan.list_steady_variables(plan_number) - List available steady state outputs
  • RasMap.get_results_folder(plan_number) - Find raster outputs folder
  • RasMap.get_results_raster(plan_number, variable_name) - Get specific raster path

These discovery methods help you understand what outputs are available before extracting data.

HEC-RAS Project Structure Reference

Understanding HEC-RAS file organization helps interpret ras object structure:

Core Files

Extension Purpose Example
.prj Project master file Muncie.prj
.g## Geometry file Muncie.g01
.p## Plan file Muncie.p01
.f## Flow file Muncie.f01
.u## Unsteady flow file Muncie.u01
.p##.hdf Results (HEC-RAS 5+) Muncie.p01.hdf

HEC Documentation

  • HEC-RAS User's Manual: https://www.hec.usace.army.mil/software/hec-ras/documentation.aspx
  • Chapter 3: Project Window and File Management
  • Chapter 4: Geometry Data
  • File Format Specifications: Available in Technical Reference Manual

LLM Forward: Reviewable Initialization

The ras object structure enables multi-level review:

  1. Code Review: Inspect ras.plan_df to verify correct plans loaded
  2. Visual Review: Open project in HEC-RAS GUI
  3. Data Review: Export ras.plan_df.to_csv() for audit trail

Example audit trail:

Python
# Save project structure for documentation
import pandas as pd

audit_data = {
    'project_file': str(ras.prj_file),
    'num_plans': len(ras.plan_df),
    'num_geometries': len(ras.geom_df),
    'plans': ras.plan_df[['plan_number', 'plan_title', 'geom_file']].to_dict('records')
}

# Export to JSON for audit trail
import json
with open('project_initialization_audit.json', 'w') as f:
    json.dump(audit_data, f, indent=2, default=str)

This audit trail enables: - Reproducibility: Exact project state documented - Traceability: Know what was initialized when - Review: Non-programmers can verify correct project loaded

Next Steps

Now that you understand the basics of project initialization in RAS Commander, you can explore more advanced topics:

  1. Working with HDF files for result analysis
  2. Modifying plan, geometry, and flow files
  3. Running HEC-RAS simulations
  4. Extracting and visualizing results
  5. Automating model calibration

These topics are covered in other examples and notebooks in the RAS Commander documentation.

CLB Engineering Corporation  ·  LLM Forward Engineering
RAS Commander Documentation is a free and open-source project maintained by CLB Engineering Corporation. For agencies and firms modernizing H&H workflows with LLM Forward approaches, contact CLB to partner with the engineers who wrote the automation.