Skip to content

Using results_df for Plan Results Summary

This notebook demonstrates the results_df DataFrame, which provides lightweight HDF-based results summaries for all plans. This enables quick access to execution status, volumetric errors, compute messages, and runtime data without opening heavy geospatial results.

Setup and Imports

Python
from pathlib import Path
import sys

# Flexible imports for development vs installed package
try:
    from ras_commander import init_ras_project, RasCmdr, RasExamples, ras
    from ras_commander.results import ResultsParser
except ImportError:
    current_file = Path(__file__).resolve()
    parent_directory = current_file.parent.parent
    sys.path.append(str(parent_directory))
    from ras_commander import init_ras_project, RasCmdr, RasExamples, ras
    from ras_commander.results import ResultsParser

Extract Example Project

Python
# Extract Muncie example project
project_path = RasExamples.extract_project("Muncie")
print(f"Project extracted to: {project_path}")
Text Only
2026-01-11 23:57:09 - 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-11 23:57:09 - ras_commander.RasExamples - INFO - Loading project data from CSV...
2026-01-11 23:57:09 - ras_commander.RasExamples - INFO - Loaded 68 projects from CSV.
2026-01-11 23:57:09 - ras_commander.RasExamples - INFO - ----- RasExamples Extracting Project -----
2026-01-11 23:57:09 - ras_commander.RasExamples - INFO - Extracting project 'Muncie'
2026-01-11 23:57:09 - ras_commander.RasExamples - INFO - Folder 'Muncie' already exists. Deleting existing folder...
2026-01-11 23:57:09 - ras_commander.RasExamples - INFO - Existing folder 'Muncie' has been deleted.
2026-01-11 23:57:10 - ras_commander.RasExamples - INFO - Successfully extracted project 'Muncie' to C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie


Project extracted to: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie

Initialize Project with results_df

When initializing a project, results_df is automatically populated by default (load_results_summary=True).

Python
# Initialize project - results_df is automatically loaded
init_ras_project(project_path, "6.6")

print(f"Plans in project: {len(ras.plan_df)}")
print(f"Results summaries loaded: {len(ras.results_df)}")
Text Only
2026-01-11 23:57:10 - 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
2026-01-11 23:57:10 - ras_commander.RasPrj - INFO - Updated results_df with 3 plan(s)


Plans in project: 3
Results summaries loaded: 3

View Initial results_df

Before execution, results_df shows plans with HDF files already present (if any).

Python
# View initial results_df
print("\n=== Initial results_df ===")
cols = ['plan_number', 'plan_title', 'hdf_exists', 'completed', 'has_errors']
print(ras.results_df[cols].to_string())
Text Only
=== Initial results_df ===
  plan_number                                plan_title  hdf_exists  completed  has_errors
0          01                  Unsteady Multi  9-SA run       False      False       False
1          03            Unsteady Run with 2D 50ft Grid       False      False       False
2          04  Unsteady Run with 2D 50ft User n Value R       False      False       False

Execute a Plan

After execution, results_df is automatically updated with fresh results.

Python
# Execute plan 01
print("Executing plan 01...")
RasCmdr.compute_plan("01", num_cores=2)
print("Execution complete!")
Text Only
2026-01-11 23:57:10 - ras_commander.RasCmdr - INFO - Using ras_object with project folder: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie
2026-01-11 23:57:10 - ras_commander.RasUtils - INFO - Using provided plan file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01
2026-01-11 23:57:10 - ras_commander.RasUtils - INFO - Successfully updated file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01
2026-01-11 23:57:10 - ras_commander.RasCmdr - INFO - Set number of cores to 2 for plan: 01
2026-01-11 23:57:10 - ras_commander.RasCmdr - INFO - Running HEC-RAS from the Command Line:
2026-01-11 23:57:10 - ras_commander.RasCmdr - INFO - Running command: "C:\Program Files (x86)\HEC\HEC-RAS\6.6\Ras.exe" -c "C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.prj" "C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01"


Executing plan 01...


2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - HEC-RAS execution completed for plan: 01
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Total run time for plan 01: 13.37 seconds
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2577 characters from HDF
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: Unsteady Multi  9-SA run
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 24.0
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
c:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\ras_commander\RasPrj.py:1514: FutureWarning: The behavior of DataFrame concatenation with empty or all-NA entries is deprecated. In a future version, this will no longer exclude empty or all-NA columns when determining the result dtypes. To retain the old behavior, exclude the relevant entries before the concat operation.
  self.results_df = pd.concat([self.results_df, new_results], ignore_index=True)
2026-01-11 23:57:23 - ras_commander.RasPrj - INFO - Updated results_df with 1 plan(s)


Execution complete!

View Updated results_df

The results_df is automatically refreshed after execution.

Python
# View updated results_df
print("\n=== After Execution ===")
cols = ['plan_number', 'hdf_exists', 'completed', 'has_errors', 'has_warnings']
print(ras.results_df[cols].to_string())
Text Only
=== After Execution ===
  plan_number  hdf_exists  completed  has_errors  has_warnings
0          03       False      False       False         False
1          04       False      False       False         False
2          01        True       True       False         False

Inspect Plan 01 Details

Python
# Get plan 01 results
plan_01 = ras.results_df[ras.results_df['plan_number'] == '01'].iloc[0]

print("=== Plan 01 Summary ===")
print(f"Plan Title: {plan_01['plan_title']}")
print(f"Flow Type: {plan_01['flow_type']}")
print(f"HDF File: {Path(plan_01['hdf_path']).name}")
print(f"HDF Modified: {plan_01['hdf_file_modified']}")
print(f"RAS Version: {plan_01['ras_version']}")
print(f"\nExecution Status:")
print(f"  Completed: {plan_01['completed']}")
print(f"  Has Errors: {plan_01['has_errors']}")
print(f"  Error Count: {plan_01['error_count']}")
print(f"  Has Warnings: {plan_01['has_warnings']}")
print(f"  Warning Count: {plan_01['warning_count']}")
Text Only
=== Plan 01 Summary ===
Plan Title: Unsteady Multi  9-SA run
Flow Type: Unsteady
HDF File: Muncie.p01.hdf
HDF Modified: 2026-01-11 23:57:23.216435
RAS Version: 5.00

Execution Status:
  Completed: True
  Has Errors: False
  Error Count: 0
  Has Warnings: False
  Warning Count: 0

Runtime Performance Data

Python
# Runtime data
print("=== Runtime Performance ===")
print(f"Simulation Start: {plan_01.get('runtime_simulation_start', 'N/A')}")
print(f"Simulation End: {plan_01.get('runtime_simulation_end', 'N/A')}")
print(f"Simulation Hours: {plan_01.get('runtime_simulation_hours', 'N/A')}")
print(f"Complete Process Hours: {plan_01.get('runtime_complete_process_hours', 'N/A')}")
print(f"Unsteady Compute Hours: {plan_01.get('runtime_unsteady_compute_hours', 'N/A')}")
print(f"Complete Process Speed: {plan_01.get('runtime_complete_process_speed', 'N/A'):.1f} hr/hr")
Text Only
=== Runtime Performance ===
Simulation Start: 1900-01-02 00:00:00
Simulation End: 1900-01-03 00:00:00
Simulation Hours: 24.0
Complete Process Hours: 0.003298611111111111
Unsteady Compute Hours: 0.0025
Complete Process Speed: 7275.8 hr/hr

Volume Accounting (Unsteady Only)

Python
# Volume accounting data
vol_cols = [c for c in ras.results_df.columns if c.startswith('vol_')]

if vol_cols and plan_01['flow_type'] == 'Unsteady':
    print("=== Volume Accounting ===")
    for col in vol_cols:
        value = plan_01.get(col, 'N/A')
        # Format numbers nicely
        if isinstance(value, (int, float)):
            print(f"{col.replace('vol_', '')}: {value:,.4f}")
        else:
            print(f"{col.replace('vol_', '')}: {value}")
else:
    print("No volume accounting data (steady flow or data not available)")
Text Only
=== Volume Accounting ===
error: -0.27747151255607605
accounting_units: Acre Feet
error_percent: 0.0007499889470636845
flux_in: 36674.50390625
flux_out: 33463.0078125
starting: 322.2446594238281
ending: 3533.462646484375

Filter Plans by Execution Status

Python
# Find executed plans
executed = ras.results_df[ras.results_df['hdf_exists']]
print(f"\nExecuted plans: {executed['plan_number'].tolist()}")

# Find completed plans
completed = ras.results_df[ras.results_df['completed']]
print(f"Completed plans: {completed['plan_number'].tolist()}")

# Find plans with errors
with_errors = ras.results_df[ras.results_df['has_errors']]
if len(with_errors) > 0:
    print(f"Plans with errors: {with_errors['plan_number'].tolist()}")
else:
    print("No plans with errors detected")

# Find plans pending execution
pending = ras.results_df[~ras.results_df['hdf_exists']]
print(f"Plans pending execution: {pending['plan_number'].tolist()}")
Text Only
Executed plans: ['01']
Completed plans: ['01']
No plans with errors detected
Plans pending execution: ['03', '04']

Execute Multiple Plans in Parallel

Python
# Execute remaining plans in parallel
pending_plans = ras.results_df[~ras.results_df['hdf_exists']]['plan_number'].tolist()

if pending_plans:
    print(f"\nExecuting {len(pending_plans)} plans in parallel: {pending_plans}")
    RasCmdr.compute_parallel(plan_number=pending_plans, max_workers=2, num_cores=2)
    print("Parallel execution complete!")
else:
    print("All plans already executed")
Text Only
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Filtered plans to execute: ['03', '04']
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Adjusted max_workers to 2 based on the number of plans to compute: 2
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Created worker folder: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]
2026-01-11 23:57:23 - ras_commander.RasMap - INFO - Successfully parsed RASMapper file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.rasmap
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2577 characters from HDF
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: Unsteady Multi  9-SA run
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 24.0
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.RasPrj - INFO - Updated results_df with 3 plan(s)



Executing 2 plans in parallel: ['03', '04']


2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Created worker folder: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]
2026-01-11 23:57:23 - ras_commander.RasMap - INFO - Successfully parsed RASMapper file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.rasmap
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2577 characters from HDF
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: Unsteady Multi  9-SA run
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 24.0
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p01.hdf
2026-01-11 23:57:23 - ras_commander.RasPrj - INFO - Updated results_df with 3 plan(s)
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Using ras_object with project folder: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Using ras_object with project folder: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]
2026-01-11 23:57:23 - ras_commander.RasUtils - INFO - Using provided plan file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p03
2026-01-11 23:57:23 - ras_commander.RasUtils - INFO - Using provided plan file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p04
2026-01-11 23:57:23 - ras_commander.RasUtils - INFO - Successfully updated file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p03
2026-01-11 23:57:23 - ras_commander.RasUtils - INFO - Successfully updated file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p04
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Set number of cores to 2 for plan: 03
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Running HEC-RAS from the Command Line:
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Running command: "C:\Program Files (x86)\HEC\HEC-RAS\6.6\Ras.exe" -c "C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.prj" "C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p03"
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Set number of cores to 2 for plan: 04
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Running HEC-RAS from the Command Line:
2026-01-11 23:57:23 - ras_commander.RasCmdr - INFO - Running command: "C:\Program Files (x86)\HEC\HEC-RAS\6.6\Ras.exe" -c "C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.prj" "C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p04"
2026-01-11 23:58:00 - ras_commander.RasCmdr - INFO - HEC-RAS execution completed for plan: 03
2026-01-11 23:58:00 - ras_commander.RasCmdr - INFO - Total run time for plan 03: 37.11 seconds
2026-01-11 23:58:00 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p03.hdf
2026-01-11 23:58:00 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p03.hdf
2026-01-11 23:58:00 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p03.hdf
2026-01-11 23:58:00 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2157 characters from HDF
2026-01-11 23:58:00 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p03.hdf
2026-01-11 23:58:00 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p03.hdf
2026-01-11 23:58:00 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: Muncie.p03.hdf
2026-01-11 23:58:00 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: Unsteady Run with 2D 50ft Grid
2026-01-11 23:58:00 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 24.0
2026-01-11 23:58:00 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p03.hdf
2026-01-11 23:58:00 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 1]\Muncie.p03.hdf
2026-01-11 23:58:00 - ras_commander.RasPrj - INFO - Updated results_df with 1 plan(s)
2026-01-11 23:58:00 - ras_commander.RasCmdr - INFO - Plan 03 executed in worker 1: Successful
2026-01-11 23:58:02 - ras_commander.RasCmdr - INFO - HEC-RAS execution completed for plan: 04
2026-01-11 23:58:02 - ras_commander.RasCmdr - INFO - Total run time for plan 04: 38.63 seconds
2026-01-11 23:58:02 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p04.hdf
2026-01-11 23:58:02 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p04.hdf
2026-01-11 23:58:02 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p04.hdf
2026-01-11 23:58:02 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2173 characters from HDF
2026-01-11 23:58:02 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p04.hdf
2026-01-11 23:58:02 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p04.hdf
2026-01-11 23:58:02 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: Muncie.p04.hdf
2026-01-11 23:58:02 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: Unsteady Run with 2D 50ft User n Value R
2026-01-11 23:58:02 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 24.0
2026-01-11 23:58:02 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p04.hdf
2026-01-11 23:58:02 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie [Worker 2]\Muncie.p04.hdf
2026-01-11 23:58:02 - ras_commander.RasPrj - INFO - Updated results_df with 1 plan(s)
2026-01-11 23:58:02 - ras_commander.RasCmdr - INFO - Plan 04 executed in worker 2: Successful
2026-01-11 23:58:02 - ras_commander.RasCmdr - INFO - Consolidating results back to original project folder: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie
2026-01-11 23:58:06 - ras_commander.RasCmdr - INFO - 
Execution Results:
2026-01-11 23:58:06 - ras_commander.RasCmdr - INFO - Plan 03: Successful
2026-01-11 23:58:06 - ras_commander.RasCmdr - INFO - Plan 04: Successful
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2157 characters from HDF
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: Unsteady Run with 2D 50ft Grid
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 24.0
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2173 characters from HDF
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: Unsteady Run with 2D 50ft User n Value R
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 24.0
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.RasPrj - INFO - Updated results_df with 2 plan(s)


Parallel execution complete!

View Complete Results Summary

Python
# Complete results summary
print("\n=== Final Results Summary ===")
summary_cols = ['plan_number', 'plan_title', 'completed', 'has_errors', 
                'runtime_complete_process_hours', 'runtime_complete_process_speed']
print(ras.results_df[summary_cols].to_string())

# Statistics
executed = ras.results_df[ras.results_df['hdf_exists']]
print(f"\n=== Summary Statistics ===")
print(f"Total plans: {len(ras.results_df)}")
print(f"Executed: {len(executed)}")
print(f"Completed successfully: {executed['completed'].sum()}")
print(f"With errors: {executed['has_errors'].sum()}")
print(f"With warnings: {executed['has_warnings'].sum()}")
print(f"Total compute time: {executed['runtime_complete_process_hours'].sum():.4f} hours")
Text Only
=== Final Results Summary ===
  plan_number                                plan_title  completed  has_errors  runtime_complete_process_hours  runtime_complete_process_speed
0          01                  Unsteady Multi  9-SA run       True       False                        0.003299                     7275.789474
1          03            Unsteady Run with 2D 50ft Grid       True       False                        0.009753                     2460.837368
2          04  Unsteady Run with 2D 50ft User n Value R       True       False                        0.010182                     2357.049323

=== Summary Statistics ===
Total plans: 3
Executed: 3
Completed successfully: 3
With errors: 0
With warnings: 0
Total compute time: 0.0232 hours

Manual results_df Update

You can manually refresh results_df for specific plans or all plans.

Python
# Manually update results_df for specific plans
ras.update_results_df(plan_numbers=['01'])
print("Updated results for plan 01")

# Or update all plans
ras.update_results_df()
print("Updated results for all plans")
Text Only
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2577 characters from HDF
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: Unsteady Multi  9-SA run
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 24.0
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.RasPrj - INFO - Updated results_df with 1 plan(s)
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2577 characters from HDF
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: Unsteady Multi  9-SA run
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 24.0
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2157 characters from HDF
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: Unsteady Run with 2D 50ft Grid
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 24.0
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p03.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2173 characters from HDF
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: Unsteady Run with 2D 50ft User n Value R
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 24.0
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p04.hdf
2026-01-11 23:58:06 - ras_commander.RasPrj - INFO - Updated results_df with 3 plan(s)


Updated results for plan 01
Updated results for all plans

Using ResultsSummary Directly

For most workflows, ras.results_df is the preferred interface. If you need lower-level control, you can call ResultsSummary.summarize_plans() directly with plan metadata records, such as ras.plan_df.to_dict('records').

Python
from ras_commander.results import ResultsSummary

# Low-level summary generation from plan metadata records
plan_entries = ras.plan_df.to_dict('records')
direct_summary = ResultsSummary.summarize_plans(plan_entries, ras.project_folder)

display_cols = [
    "plan_number",
    "plan_title",
    "flow_type",
    "hdf_exists",
    "completed",
    "has_errors",
]
print(direct_summary[display_cols].to_string(index=False))

Using ResultsParser Directly

You can parse compute messages directly using ResultsParser.

Python
from ras_commander.hdf import HdfResultsPlan

# Get compute messages for a plan
plan_01_row = ras.results_df[ras.results_df['plan_number'] == '01'].iloc[0]
hdf_path = Path(plan_01_row['hdf_path'])

if hdf_path.exists():
    # Extract messages using HDF-only method (no RasControl locking)
    messages = HdfResultsPlan.get_compute_messages_hdf_only(hdf_path)

    print(f"Compute messages length: {len(messages)} characters")
    print("\nFirst 300 characters:")
    print(messages[:300])

    # Parse for errors/warnings
    parsed = ResultsParser.parse_compute_messages(messages)
    print(f"\nParsed results:")
    for key, value in parsed.items():
        print(f"  {key}: {value}")
Text Only
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects\Muncie\Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: Muncie.p01.hdf
2026-01-11 23:58:06 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 2577 characters from HDF


Compute messages length: 2577 characters

First 300 characters:
Plan: 'Unsteady Multi  9-SA run' (Muncie.p01)
Simulation started at: 11Jan2026 11:57:11 PM

Writing Plan GIS Data...
Completed Writing Plan GIS Data
Writing Geometry...
Computing Bank Lines
Bank lines generated in 55 ms
Computing Edge Lines
Edge Lines generated in 32 ms
Computing XS Interp

Parsed results:
  completed: True
  has_errors: False
  has_warnings: False
  error_count: 0
  warning_count: 0
  first_error_line: None

Benefits of results_df

  1. Quick Status Checks: See execution status without opening HDF files
  2. Error Detection: Automatically detects errors in compute messages
  3. Performance Metrics: Runtime data and compute speeds available
  4. Volume Accounting: Mass balance data for unsteady models
  5. No Locking Issues: Uses HDF-only methods (no RasControl/COM)
  6. Automatic Updates: Refreshes after compute_plan(), compute_parallel(), compute_test_mode()

Cleanup

Python
# Optional: Clean up extracted project
import shutil
example_projects = project_path.parent
if example_projects.name == "example_projects":
    shutil.rmtree(example_projects, ignore_errors=True)
    print(f"Cleaned up: {example_projects}")
Text Only
Cleaned up: C:\Users\billk_clb\anaconda3\envs\rascmdr_piptest\Lib\site-packages\examples\example_projects
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.