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, 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
✓ Loaded: c:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\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 6.3+ (optional for viewing projects, not required for initialization)
  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.

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 (6.3, 6.5, 6.6, 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

RAS Commander: Core 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-01-14 11:31:21 - ras_commander.RasExamples - INFO - Found zip file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\Example_Projects_6_6.zip
2026-01-14 11:31:21 - ras_commander.RasExamples - INFO - Loading project data from CSV...
2026-01-14 11:31:21 - ras_commander.RasExamples - INFO - Loaded 68 projects from CSV.
2026-01-14 11:31:21 - ras_commander.RasExamples - INFO - ----- RasExamples Extracting Project -----
2026-01-14 11:31:21 - ras_commander.RasExamples - INFO - Extracting project 'Balde Eagle Creek' as 'Balde Eagle Creek_101'
2026-01-14 11:31:21 - ras_commander.RasExamples - INFO - Successfully extracted project 'Balde Eagle Creek' to C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Balde Eagle Creek_101
2026-01-14 11:31:21 - ras_commander.RasExamples - INFO - ----- RasExamples Extracting Project -----
2026-01-14 11:31:21 - ras_commander.RasExamples - INFO - Extracting project 'BaldEagleCrkMulti2D' as 'BaldEagleCrkMulti2D_101'
2026-01-14 11:31:22 - ras_commander.RasExamples - INFO - Successfully extracted project 'BaldEagleCrkMulti2D' to C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\BaldEagleCrkMulti2D_101
2026-01-14 11:31:22 - ras_commander.RasExamples - INFO - ----- RasExamples Extracting Project -----
2026-01-14 11:31:22 - ras_commander.RasExamples - INFO - Extracting project 'Muncie' as 'Muncie_101'
2026-01-14 11:31:23 - ras_commander.RasExamples - INFO - Successfully extracted project 'Muncie' to C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie_101


[WindowsPath('C:/Users/billk_clb/anaconda3/envs/rascmdr_piptest/Lib/site-packages/examples/example_projects/Balde Eagle Creek_101'), WindowsPath('C:/Users/billk_clb/anaconda3/envs/rascmdr_piptest/Lib/site-packages/examples/example_projects/BaldEagleCrkMulti2D_101'), WindowsPath('C:/Users/billk_clb/anaconda3/envs/rascmdr_piptest/Lib/site-packages/examples/example_projects/Muncie_101')]

Get Paths for Extracted Example Projects

Python
# Get the parent directory of the first extracted path as our examples directory
examples_dir = extracted_paths[0].parent
print(f"Examples directory: {examples_dir}")


# Define paths to the extracted projects
bald_eagle_path = examples_dir / "Balde Eagle Creek"
multi_2d_path = examples_dir / "BaldEagleCrkMulti2D"
muncie_path = examples_dir / "Muncie"

# 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: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects
Path C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Balde Eagle Creek exists: True
Path C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\BaldEagleCrkMulti2D exists: True
Path C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie 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-01-14 11:31:23 - ras_commander.RasMap - INFO - Successfully parsed RASMapper file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Balde Eagle Creek\BaldEagle.rasmap
2026-01-14 11:31:23 - ras_commander.RasPrj - INFO - Updated results_df with 2 plan(s)


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

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-01-14 11:31:23 - ras_commander.RasMap - INFO - Successfully parsed RASMapper file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Balde Eagle Creek\BaldEagle.rasmap
2026-01-14 11:31:23 - ras_commander.RasPrj - INFO - Updated results_df with 2 plan(s)


Found .prj file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Balde Eagle Creek\BaldEagle.prj
File name: BaldEagle.prj

Successfully initialized project using .prj file path!
Project name: BaldEagle
Project folder: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Balde Eagle Creek
PRJ file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Balde Eagle Creek\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: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Balde Eagle Creek
PRJ File: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Balde Eagle Creek\BaldEagle.prj
HEC-RAS Executable Path: C:\Program Files (x86)\HEC\HEC-RAS\6.6\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 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 None dss 2 None 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 02 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... Unsteady
1 02 None 01 Steady Flow Run NaN SteadyRun 02/18/1999,0000,02/24/1999,0500 2MIN NaN 1 1 NaN 1 NaN NaN NaN NaN None dss 1 None 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 02 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... Steady
Text Only
Steady Flow Files DataFrame:
flow_number full_path unsteady_number
0 02 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... None
1 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... None
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
0 02 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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
0 g01 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
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 × 27 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 bc_type hydrograph_type Interval DSS 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
0 02 1 Bald Eagle Loc Hav 138154.4 Flow Hydrograph Flow Hydrograph 1HOUR ... Flow Hydrograph 2 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS
1 02 2 Bald Eagle Loc Hav 81500 Gate Opening None NaN NaN ... Flow Hydrograph 2 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS
2 02 3 Bald Eagle Loc Hav 659.942 Rating Curve None NaN ... Flow Hydrograph 2 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS

3 rows × 28 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}")

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: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Balde Eagle Creek\BaldEagle.p01
Geometry file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Balde Eagle Creek\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 bc_type hydrograph_type Interval DSS 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
0 02 1 Bald Eagle Loc Hav 138154.4 Flow Hydrograph Flow Hydrograph 1HOUR ... Flow Hydrograph 2 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS
1 02 2 Bald Eagle Loc Hav 81500 Gate Opening None NaN NaN ... Flow Hydrograph 2 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS
2 02 3 Bald Eagle Loc Hav 659.942 Rating Curve None NaN ... Flow Hydrograph 2 6.30 0 Disable No Wind Forces None None 0 mm/hr DSS

3 rows × 28 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-01-14 11:31:23 - ras_commander.RasMap - INFO - Successfully parsed RASMapper file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\BaldEagleCrkMulti2D\BaldEagleDamBrk.rasmap
2026-01-14 11:31:23 - ras_commander.RasPrj - INFO - Updated results_df with 11 plan(s)
2026-01-14 11:31:23 - ras_commander.RasMap - INFO - Successfully parsed RASMapper file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.rasmap



Multi2D project initialized with its own RAS object


2026-01-14 11:31:23 - ras_commander.RasPrj - INFO - Updated results_df with 3 plan(s)



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']}")

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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 07 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 12 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 09 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 10 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 11 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 13 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 02 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 03 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... Unsteady

11 rows × 30 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: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\BaldEagleCrkMulti2D
PRJ File: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\BaldEagleCrkMulti2D\BaldEagleDamBrk.prj
HEC-RAS Executable Path: C:\Program Files (x86)\HEC\HEC-RAS\6.6\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 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 8 None dss 1 Pardiso (Direct) 193 None 06 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 07 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 6 None dss 1 NaN BaldEagleCr None 08 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 12 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 None dss 1 NaN Upstream2D None 10 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 09 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 8 None dss 1 NaN BaldEagleCr None 11 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 10 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 None dss 1 NaN BaldEagleCr None 12 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 11 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 10 None dss 1 NaN BaldEagleCr None 09 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 13 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 6 None dss 1 NaN BaldEagleCr None 13 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 0 0 None dss 1 Pardiso (Direct) BaldEagleCr None 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 None dss 1 NaN BaldEagleCr None 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 10 None dss 1 PARDISO (Direct) BaldEagleCr None 03 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 02 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 None dss 1 Pardiso (Direct) BaldEagleCr None 09 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 03 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 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 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... PMF with Multi 2D Areas 5.00 0 NaN NaN NaN NaN NaN NaN NaN
1 08 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... PMF for Upstream 2D 4.20 0 NaN NaN NaN NaN NaN NaN NaN
2 09 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... Upstream 2D 5.00 0 NaN NaN NaN NaN NaN NaN NaN
3 10 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 1972 Flood Event - 2D to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
4 11 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 1972 Flood Event - SA to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
5 12 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... PMF for 1D - 2D 5.00 0 NaN NaN NaN NaN NaN NaN NaN
6 13 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... Single 2D Area 5.00 0 NaN NaN NaN NaN NaN NaN NaN
7 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 1972 Flood Event - 2D Leve Structure 5.10 0 NaN NaN NaN NaN NaN NaN NaN
8 02 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... Single 2D Area with Bridges 5.10 0 NaN NaN NaN NaN NaN NaN NaN
9 03 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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
0 g06 06 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
1 g08 08 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
2 g10 10 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
3 g11 11 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
4 g12 12 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
5 g09 09 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
6 g13 13 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
7 g01 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
8 g03 03 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
9 g02 02 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
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 × 30 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 bc_type hydrograph_type Interval DSS File ... 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
0 07 1 Bald Eagle Cr. Lock Haven 137520 Flow Hydrograph Flow Hydrograph 1HOUR Bald_Eagle_Creek.dss ... PMF with Multi 2D Areas 5.00 0 NaN NaN NaN NaN NaN NaN NaN
1 07 2 Bald Eagle Cr. Lock Haven 81454 Gate Opening None NaN NaN ... PMF with Multi 2D Areas 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 1HOUR Bald_Eagle_Creek.dss ... PMF with Multi 2D Areas 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 1HOUR NaN ... PMF with Multi 2D Areas 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 1HOUR Bald_Eagle_Creek.dss ... PMF with Multi 2D Areas 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 1HOUR Bald_Eagle_Creek.dss ... PMF with Multi 2D Areas 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 1HOUR Bald_Eagle_Creek.dss ... PMF with Multi 2D Areas 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 1HOUR Bald_Eagle_Creek.dss ... PMF with Multi 2D Areas 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 1HOUR Bald_Eagle_Creek.dss ... PMF with Multi 2D Areas 5.00 0 NaN NaN NaN NaN NaN NaN NaN
9 07 10 Bald Eagle Cr. Lock Haven -1867 Normal Depth None NaN NaN ... PMF with Multi 2D Areas 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 1HOUR Bald_Eagle_Creek.dss ... PMF for Upstream 2D 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 1HOUR NaN ... PMF for Upstream 2D 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 1HOUR Bald_Eagle_Creek.dss ... PMF for Upstream 2D 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 1HOUR Bald_Eagle_Creek.dss ... PMF for Upstream 2D 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 1HOUR Bald_Eagle_Creek.dss ... PMF for Upstream 2D 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 1HOUR Bald_Eagle_Creek.dss ... PMF for Upstream 2D 4.20 0 NaN NaN NaN NaN NaN NaN NaN
16 08 7 Bald Eagle Cr. Lock Haven -1867 Normal Depth None NaN NaN ... PMF for Upstream 2D 4.20 0 NaN NaN NaN NaN NaN NaN NaN
17 08 8 Flow Hydrograph Flow Hydrograph 1HOUR NaN ... PMF for Upstream 2D 4.20 0 NaN NaN NaN NaN NaN NaN NaN
18 08 9 Bald Eagle Cr. Lock Haven 81454 Gate Opening None NaN NaN ... PMF for Upstream 2D 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 1HOUR Bald_Eagle_Creek.dss ... Upstream 2D 5.00 0 NaN NaN NaN NaN NaN NaN NaN
20 09 2 Bald Eagle Cr. Lock Haven -1867 Normal Depth None NaN NaN ... Upstream 2D 5.00 0 NaN NaN NaN NaN NaN NaN NaN
21 09 3 Flow Hydrograph Flow Hydrograph 1HOUR NaN ... Upstream 2D 5.00 0 NaN NaN NaN NaN NaN NaN NaN
22 10 1 Normal Depth None NaN NaN ... 1972 Flood Event - 2D to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
23 10 2 Normal Depth None NaN NaN ... 1972 Flood Event - 2D to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
24 10 3 Gate Opening None NaN NaN ... 1972 Flood Event - 2D to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
25 10 4 Flow Hydrograph Flow Hydrograph 1HOUR NaN ... 1972 Flood Event - 2D to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
26 11 1 Gate Opening None NaN NaN ... 1972 Flood Event - SA to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
27 11 2 Lateral Inflow Hydrograph Lateral Inflow Hydrograph 1HOUR NaN ... 1972 Flood Event - SA to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
28 11 3 Normal Depth None NaN NaN ... 1972 Flood Event - SA to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
29 11 4 Normal Depth None NaN NaN ... 1972 Flood Event - SA to 2D Run 5.00 0 NaN NaN NaN NaN NaN NaN NaN
30 12 1 Bald Eagle Cr. Lock Haven 137520 Flow Hydrograph Flow Hydrograph 15MIN Bald_Eagle_Creek.dss ... PMF for 1D - 2D 5.00 0 NaN NaN NaN NaN NaN NaN NaN
31 12 2 Bald Eagle Cr. Lock Haven 81454 Gate Opening None NaN NaN ... PMF for 1D - 2D 5.00 0 NaN NaN NaN NaN NaN NaN NaN
32 12 3 Normal Depth None NaN NaN ... PMF for 1D - 2D 5.00 0 NaN NaN NaN NaN NaN NaN NaN
33 12 4 Normal Depth None NaN NaN ... PMF for 1D - 2D 5.00 0 NaN NaN NaN NaN NaN NaN NaN
34 13 1 Normal Depth None NaN NaN ... Single 2D Area 5.00 0 NaN NaN NaN NaN NaN NaN NaN
35 13 2 Normal Depth None NaN NaN ... Single 2D Area 5.00 0 NaN NaN NaN NaN NaN NaN NaN
36 13 3 Flow Hydrograph Flow Hydrograph 1HOUR NaN ... Single 2D Area 5.00 0 NaN NaN NaN NaN NaN NaN NaN
37 13 4 Gate Opening None NaN NaN ... Single 2D Area 5.00 0 NaN NaN NaN NaN NaN NaN NaN
38 01 1 Gate Opening None NaN NaN ... 1972 Flood Event - 2D Leve Structure 5.10 0 NaN NaN NaN NaN NaN NaN NaN
39 01 2 Lateral Inflow Hydrograph Lateral Inflow Hydrograph 1HOUR NaN ... 1972 Flood Event - 2D Leve Structure 5.10 0 NaN NaN NaN NaN NaN NaN NaN
40 01 3 Normal Depth None NaN NaN ... 1972 Flood Event - 2D Leve Structure 5.10 0 NaN NaN NaN NaN NaN NaN NaN
41 01 4 Normal Depth None NaN NaN ... 1972 Flood Event - 2D Leve Structure 5.10 0 NaN NaN NaN NaN NaN NaN NaN
42 02 1 Normal Depth None NaN NaN ... Single 2D Area with Bridges 5.10 0 NaN NaN NaN NaN NaN NaN NaN
43 02 2 Normal Depth None NaN NaN ... Single 2D Area with Bridges 5.10 0 NaN NaN NaN NaN NaN NaN NaN
44 02 3 Flow Hydrograph Flow Hydrograph 1HOUR NaN ... Single 2D Area with Bridges 5.10 0 NaN NaN NaN NaN NaN NaN NaN
45 02 4 Gate Opening None NaN NaN ... Single 2D Area with Bridges 5.10 0 NaN NaN NaN NaN NaN NaN NaN
46 02 5 Normal Depth None NaN NaN ... Single 2D Area with Bridges 5.10 0 NaN NaN NaN NaN NaN NaN NaN
47 03 1 Normal Depth None NaN NaN ... Gridded Precipitation 6.00 0 Enable No Wind Forces Gridded None -1 mm/hr DSS
48 03 2 Flow Hydrograph Flow Hydrograph 1HOUR NaN ... Gridded Precipitation 6.00 0 Enable No Wind Forces Gridded None -1 mm/hr DSS
49 03 3 Normal Depth None NaN NaN ... Gridded Precipitation 6.00 0 Enable No Wind Forces Gridded None -1 mm/hr DSS
50 03 4 Gate Opening None NaN NaN ... Gridded Precipitation 6.00 0 Enable No Wind Forces Gridded None -1 mm/hr DSS

51 rows × 29 columns

Python
# Examine the Muncie project
print_ras_object_data(muncie_project, "Muncie Project")
Text Only
Muncie Project Data:
==================================================
Project Name: Muncie
Project Folder: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie
PRJ File: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.prj
HEC-RAS Executable Path: C:\Program Files (x86)\HEC\HEC-RAS\6.6\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 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 None dss 1 NaN NaN None 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 4 None dss 1 Pardiso (Direct) 2D Interior Area None 02 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 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 6 None dss 1 Pardiso (Direct) 2D Interior Area None 04 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... Unsteady
Text Only
Steady Flow Files DataFrame:
flow_number full_path unsteady_number
0 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... None
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|Expanded View Met BC=Precipitation|Gridded Source
0 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... Flow Boundary Conditions 6.30 0 Disable No Wind Forces 0 DSS
Text Only
Geometry Files DataFrame (ras.geom_df):
geom_file geom_number full_path hdf_path
0 g01 01 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
1 g02 02 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
2 g04 04 C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt...
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 × 30 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 bc_type hydrograph_type Interval DSS Path ... hydrograph_num_values hydrograph_values full_path Flow Title Program Version Use Restart Precipitation Mode Wind Mode Met BC=Precipitation|Expanded View Met BC=Precipitation|Gridded Source
0 01 1 White Muncie 15696.24 Flow Hydrograph Flow Hydrograph 1HOUR ... 65 [13500, 14000, 14500, 15000, 15500, 16000, 165... C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... Flow Boundary Conditions 6.30 0 Disable No Wind Forces 0 DSS
1 01 2 White Muncie 237.6455 Normal Depth None NaN NaN ... 0 NaN C:\Users\billk_clb\anaconda3\envs\rascmdr_pipt... Flow Boundary Conditions 6.30 0 Disable No Wind Forces 0 DSS

2 rows × 25 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

RAS Commander: 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 is a free and open-source project maintained by CLB Engineering Corporation. For agencies and firms seeking to modernize H&H workflows with LLM Forward approaches, contact CLB to partner with the engineers who wrote the automation.