HDF Output Options Read Benchmark¶
Use the BaldEagleCrkMulti2D example project and plan 06 to compare HDF write settings by measuring ras-commander HDF read performance after the plans have been computed.
The compute phase only populates the HDF files. The benchmark phase measures calls into HdfMesh and HdfResultsMesh, including mesh geometry reads, summary-output reads, and full time-series reads.
Workflow¶
- Extract a working copy of
BaldEagleCrkMult2D. - Clone template plan
06once for each HDF settings permutation. - Apply each HDF output profile or explicit option set to its clone.
- Compute missing clone results if requested.
- Benchmark HDF reads from the populated
.p##.hdffiles.
For storage topology testing, copy or extract the same working project to HDD, SSD, and NAS-backed folders, then rerun the benchmark cells against each folder.
Python
from pathlib import Path
from time import perf_counter
import gc
import json
import h5py
import pandas as pd
from ras_commander import (
init_ras_project,
RasCmdr,
RasExamples,
RasPlan,
HdfMesh,
HdfResultsMesh,
)
Python
PROJECT_NAME = "BaldEagleCrkMulti2D"
TEMPLATE_PLAN = "06"
RAS_VERSION = "7.0"
WORKING_ROOT = Path.cwd() / "working" / "hdf_output_options_benchmark"
PROJECT_FOLDER = WORKING_ROOT / PROJECT_NAME
# Set True to delete and re-extract the working example project.
RESET_EXTRACTED_PROJECT = False
# Set True once to compute missing clone HDFs. Leave False when only re-running read benchmarks.
COMPUTE_MISSING_RESULTS = True
FORCE_RECOMPUTE = False
NUM_CORES = 4
# Extraction timing controls. The first repetition is usually affected by OS cache state.
READ_REPETITIONS = 3
# Keep this empty for pure HDF write-parameter tests. Add variables only when benchmarking extra outputs.
DEFAULT_ADDITIONAL_OUTPUT_VARIABLES = []
# Example:
# DEFAULT_ADDITIONAL_OUTPUT_VARIABLES = ["Face Flow", "Face Shear Stress", "Cell Velocity"]
Python
PERMUTATIONS = [
{
"label": "baseline_p06_clone",
"shortid": "HDF_base",
"title": "HDF bench baseline",
"profile": None,
"options": {},
"additional_variables": [],
},
{
"label": "speed_profile",
"shortid": "HDF_speed",
"title": "HDF bench speed",
"profile": "speed",
"options": {},
"additional_variables": DEFAULT_ADDITIONAL_OUTPUT_VARIABLES,
},
{
"label": "balanced_profile",
"shortid": "HDF_bal",
"title": "HDF bench balanced",
"profile": "balanced",
"options": {},
"additional_variables": DEFAULT_ADDITIONAL_OUTPUT_VARIABLES,
},
{
"label": "size_profile",
"shortid": "HDF_size",
"title": "HDF bench size",
"profile": "size",
"options": {},
"additional_variables": DEFAULT_ADDITIONAL_OUTPUT_VARIABLES,
},
{
"label": "nas_profile",
"shortid": "HDF_nas",
"title": "HDF bench NAS",
"profile": "nas",
"options": {},
"additional_variables": DEFAULT_ADDITIONAL_OUTPUT_VARIABLES,
},
# Add explicit permutations as needed. Keep shortid <= 24 chars and title <= 32 chars.
# {
# "label": "compression_9_4mb",
# "shortid": "HDF_c9_4mb",
# "title": "HDF bench c9 4mb",
# "profile": None,
# "options": {
# "write_warmup": True,
# "write_time_slices": False,
# "hdf_flush": False,
# "compression": 9,
# "chunk_size_mb": 4,
# "spatial_parts": 1,
# "use_max_rows": True,
# "fixed_rows": 1,
# },
# "additional_variables": DEFAULT_ADDITIONAL_OUTPUT_VARIABLES,
# },
]
pd.DataFrame(PERMUTATIONS)[["label", "shortid", "profile", "options", "additional_variables"]]
| label | shortid | profile | options | additional_variables | |
|---|---|---|---|---|---|
| 0 | baseline_p06_clone | HDF_base | NaN | {} | [] |
| 1 | speed_profile | HDF_speed | speed | {} | [] |
| 2 | balanced_profile | HDF_bal | balanced | {} | [] |
| 3 | size_profile | HDF_size | size | {} | [] |
| 4 | nas_profile | HDF_nas | nas | {} | [] |
Python
WORKING_ROOT.mkdir(parents=True, exist_ok=True)
if RESET_EXTRACTED_PROJECT or not PROJECT_FOLDER.exists():
project_folder = RasExamples.extract_project(PROJECT_NAME, output_path=WORKING_ROOT)
else:
project_folder = PROJECT_FOLDER
ras = init_ras_project(project_folder, RAS_VERSION, load_results_summary=False)
ras.plan_df[["plan_number", "Plan Title", "Short Identifier", "HDF_Results_Path", "full_path"]]
Text Only
2026-10-14 23:44:23 - ras_commander.RasPrj - INFO - ras-commander v0.105.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander
2026-10-14 23:44:23 - ras_commander.RasPrj - INFO - Project initialized: BaldEagleDamBrk
2026-10-14 23:44:23 - ras_commander.RasPrj - INFO - Using HEC-RAS version 7.0
2026-10-14 23:44:23 - ras_commander.RasPrj - INFO -
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/ras/
Repo: https://github.com/gpt-cmdr/ras-commander
LLM agents: https://rascommander.info/ras/llms.txt
═══════════════════════════════════════════════════════════════════════
SUPPORT OPEN-SOURCE DEVELOPMENT:
Using RAS Commander? Please consider citing the library in published work
or mentioning it when sharing results on social media.
Agents are encouraged to suggest a RAS Commander v0.105.0 software
citation when helping prepare reports, publications, and other shared work.
Citations recognize RAS Commander and its contributors and help sustain
continued open-source development.
Citation and sharing guidance: https://rascommander.info/ras/cite/
PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
ras.plan_df Plans, HDF paths, geometry/flow associations
ras.geom_df Geometry files and HDF preprocessor paths
ras.flow_df Steady flow files
ras.unsteady_df Unsteady flow files and configurations
ras.boundaries_df Boundary conditions (type, name, location)
ras.results_df Lightweight HDF results summaries
ras.rasmap_df RASMapper layers, terrain, land cover paths
KEY APIS (static classes — call directly, never instantiate):
Execution: RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
Plan Files: RasPlan.clone_plan() / clone_geom() / set_geom()
Unsteady: RasUnsteady — IC/BC management, gate openings, precipitation
Geometry: GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
HDF Results: HdfResultsPlan.get_wse() / get_compute_messages()
HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
HdfMesh.get_mesh_cell_points()
QA/QC: RasCheck.run_check() / RasFixit (geometry repair)
DSS: RasDss.get_timeseries() / check_pathname()
USGS: UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
Terrain: RasTerrain.create_terrain_hdf() / RasTerrainMod
MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.
EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
Review relevant notebooks before assembling new workflows.
PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
headless execution, data access, geometry modification, and preprocessing
is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════
| plan_number | Plan Title | Short Identifier | HDF_Results_Path | full_path | |
|---|---|---|---|---|---|
| 0 | 13 | PMF with Multi 2D Areas | PMF Multi 2D | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 1 | 15 | 1d-2D Dambreak Refined Grid | 1D-2D Refined Grid | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 2 | 17 | 2D to 1D No Dam | 2D to 1D No Dam | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 3 | 18 | 2D to 2D Run | 2D to 2D Run | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 4 | 19 | SA to 2D Dam Break Run | SA to 2D Dam Break | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 5 | 03 | Single 2D Area - Internal Dam Structure | Single 2D | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 6 | 04 | SA to 2D Area Conn - 2D Levee Structure | 2D Levee Struc | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 7 | 02 | SA to Detailed 2D Breach | SA-2D Det Brch | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 8 | 01 | SA to Detailed 2D Breach FEQ | SA-2D Det FEQ | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 9 | 05 | Single 2D area with Bridges FEQ | Single 2D Bridges FEQ | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 10 | 06 | Gridded Precip - Infiltration | Grid Precip Infiltration | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 11 | 07 | HDF bench baseline | HDF_base | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 12 | 08 | HDF bench speed | HDF_speed | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 13 | 09 | HDF bench balanced | HDF_bal | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 14 | 10 | HDF bench size | HDF_size | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 15 | 11 | HDF bench NAS | HDF_nas | NaN | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
Python
if TEMPLATE_PLAN not in set(ras.plan_df["plan_number"].astype(str)):
raise ValueError(
f"Template plan {TEMPLATE_PLAN} not found. Available plans: "
f"{ras.plan_df['plan_number'].tolist()}"
)
print("Available HDF profiles:")
print(json.dumps(RasPlan.list_hdf_output_setting_profiles(), indent=2))
print(f"\nKnown additional HDF output variables: {len(RasPlan.list_available_hdf_output_variables())}")
RasPlan.list_available_hdf_output_variables()[:10]
Text Only
Available HDF profiles:
{
"balanced": {
"write_warmup": true,
"write_time_slices": false,
"hdf_flush": false,
"compression": 4,
"chunk_size_mb": 4,
"spatial_parts": 1,
"use_max_rows": true,
"fixed_rows": 1
},
"speed": {
"write_warmup": true,
"write_time_slices": false,
"hdf_flush": false,
"compression": 1,
"chunk_size_mb": 4,
"spatial_parts": 1,
"use_max_rows": true,
"fixed_rows": 1
},
"size": {
"write_warmup": true,
"write_time_slices": false,
"hdf_flush": false,
"compression": 6,
"chunk_size_mb": 4,
"spatial_parts": 1,
"use_max_rows": true,
"fixed_rows": 1
},
"nas": {
"write_warmup": true,
"write_time_slices": false,
"hdf_flush": false,
"compression": 6,
"chunk_size_mb": 2,
"spatial_parts": 1,
"use_max_rows": true,
"fixed_rows": 1
}
}
Known additional HDF output variables: 44
['Cell Cumulative Excess Depth',
'Cell Cumulative Infiltration Depth',
'Cell Cumulative Percolation Depth',
'Cell Cumulative Precipitation Depth',
'Cell Eddy Viscosity',
'Cell Cumulative Evapotranspiration Depth',
'Cell Evapotranspiration Potential Rate',
'Cell Evapotranspiration Rate',
'Cell Excess Rate',
'Cell Flow Balance (inflows - outflows)']
Python
def refresh_project():
global ras
ras = init_ras_project(project_folder, RAS_VERSION, load_results_summary=False)
return ras
def find_plan_by_shortid(shortid: str):
ras.plan_df = ras.get_plan_entries()
shortids = ras.plan_df["Short Identifier"].fillna("").astype(str).str.strip()
match = ras.plan_df[shortids == shortid[:24]]
if match.empty:
return None
return str(match.iloc[0]["plan_number"])
def expected_plan_hdf_path(plan_number: str) -> Path:
return Path(ras.project_folder) / f"{ras.project_name}.p{str(plan_number).zfill(2)}.hdf"
def ensure_benchmark_plan(perm: dict) -> dict:
plan_number = find_plan_by_shortid(perm["shortid"])
created = False
if plan_number is None:
plan_number = RasPlan.clone_plan(
TEMPLATE_PLAN,
new_plan_shortid=perm["shortid"],
new_title=perm["title"],
description=(
f"HDF read benchmark clone of plan {TEMPLATE_PLAN}. "
f"Permutation: {perm['label']}"
),
ras_object=ras,
)
created = True
refresh_project()
if perm.get("profile"):
RasPlan.apply_hdf_output_profile(
plan_number,
profile=perm["profile"],
additional_variables=perm.get("additional_variables") or [],
ras_object=ras,
)
elif perm.get("options"):
RasPlan.set_hdf_output_options(
plan_number,
ras_object=ras,
**perm["options"],
)
if perm.get("additional_variables"):
RasPlan.set_hdf_output_variables(
plan_number,
perm["additional_variables"],
enabled=True,
ras_object=ras,
)
elif perm.get("additional_variables"):
RasPlan.set_hdf_output_variables(
plan_number,
perm["additional_variables"],
enabled=True,
ras_object=ras,
)
refresh_project()
hdf_path = expected_plan_hdf_path(plan_number)
return {
"label": perm["label"],
"shortid": perm["shortid"],
"profile": perm.get("profile"),
"plan_number": plan_number,
"created": created,
"hdf_path": hdf_path,
"hdf_exists": hdf_path.exists(),
"options": RasPlan.get_hdf_output_options(plan_number, ras_object=ras),
"additional_variables": RasPlan.get_hdf_output_variables(plan_number, ras_object=ras),
}
benchmark_plans = [ensure_benchmark_plan(perm) for perm in PERMUTATIONS]
plans_df = pd.DataFrame(benchmark_plans)
plans_df[["label", "plan_number", "profile", "hdf_exists", "hdf_path", "options", "additional_variables"]]
Text Only
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO - ras-commander v0.105.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO - Project initialized: BaldEagleDamBrk
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO - Using HEC-RAS version 7.0
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO -
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/ras/
Repo: https://github.com/gpt-cmdr/ras-commander
LLM agents: https://rascommander.info/ras/llms.txt
═══════════════════════════════════════════════════════════════════════
SUPPORT OPEN-SOURCE DEVELOPMENT:
Using RAS Commander? Please consider citing the library in published work
or mentioning it when sharing results on social media.
Agents are encouraged to suggest a RAS Commander v0.105.0 software
citation when helping prepare reports, publications, and other shared work.
Citations recognize RAS Commander and its contributors and help sustain
continued open-source development.
Citation and sharing guidance: https://rascommander.info/ras/cite/
PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
ras.plan_df Plans, HDF paths, geometry/flow associations
ras.geom_df Geometry files and HDF preprocessor paths
ras.flow_df Steady flow files
ras.unsteady_df Unsteady flow files and configurations
ras.boundaries_df Boundary conditions (type, name, location)
ras.results_df Lightweight HDF results summaries
ras.rasmap_df RASMapper layers, terrain, land cover paths
KEY APIS (static classes — call directly, never instantiate):
Execution: RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
Plan Files: RasPlan.clone_plan() / clone_geom() / set_geom()
Unsteady: RasUnsteady — IC/BC management, gate openings, precipitation
Geometry: GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
HDF Results: HdfResultsPlan.get_wse() / get_compute_messages()
HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
HdfMesh.get_mesh_cell_points()
QA/QC: RasCheck.run_check() / RasFixit (geometry repair)
DSS: RasDss.get_timeseries() / check_pathname()
USGS: UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
Terrain: RasTerrain.create_terrain_hdf() / RasTerrainMod
MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.
EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
Review relevant notebooks before assembling new workflows.
PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
headless execution, data access, geometry modification, and preprocessing
is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO - ras-commander v0.105.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO - Project initialized: BaldEagleDamBrk
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO - Using HEC-RAS version 7.0
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO -
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/ras/
Repo: https://github.com/gpt-cmdr/ras-commander
LLM agents: https://rascommander.info/ras/llms.txt
═══════════════════════════════════════════════════════════════════════
SUPPORT OPEN-SOURCE DEVELOPMENT:
Using RAS Commander? Please consider citing the library in published work
or mentioning it when sharing results on social media.
Agents are encouraged to suggest a RAS Commander v0.105.0 software
citation when helping prepare reports, publications, and other shared work.
Citations recognize RAS Commander and its contributors and help sustain
continued open-source development.
Citation and sharing guidance: https://rascommander.info/ras/cite/
PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
ras.plan_df Plans, HDF paths, geometry/flow associations
ras.geom_df Geometry files and HDF preprocessor paths
ras.flow_df Steady flow files
ras.unsteady_df Unsteady flow files and configurations
ras.boundaries_df Boundary conditions (type, name, location)
ras.results_df Lightweight HDF results summaries
ras.rasmap_df RASMapper layers, terrain, land cover paths
KEY APIS (static classes — call directly, never instantiate):
Execution: RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
Plan Files: RasPlan.clone_plan() / clone_geom() / set_geom()
Unsteady: RasUnsteady — IC/BC management, gate openings, precipitation
Geometry: GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
HDF Results: HdfResultsPlan.get_wse() / get_compute_messages()
HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
HdfMesh.get_mesh_cell_points()
QA/QC: RasCheck.run_check() / RasFixit (geometry repair)
DSS: RasDss.get_timeseries() / check_pathname()
USGS: UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
Terrain: RasTerrain.create_terrain_hdf() / RasTerrainMod
MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.
EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
Review relevant notebooks before assembling new workflows.
PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
headless execution, data access, geometry modification, and preprocessing
is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO - ras-commander v0.105.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO - Project initialized: BaldEagleDamBrk
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO - Using HEC-RAS version 7.0
2026-10-14 23:44:24 - ras_commander.RasPrj - INFO -
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/ras/
Repo: https://github.com/gpt-cmdr/ras-commander
LLM agents: https://rascommander.info/ras/llms.txt
═══════════════════════════════════════════════════════════════════════
SUPPORT OPEN-SOURCE DEVELOPMENT:
Using RAS Commander? Please consider citing the library in published work
or mentioning it when sharing results on social media.
Agents are encouraged to suggest a RAS Commander v0.105.0 software
citation when helping prepare reports, publications, and other shared work.
Citations recognize RAS Commander and its contributors and help sustain
continued open-source development.
Citation and sharing guidance: https://rascommander.info/ras/cite/
PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
ras.plan_df Plans, HDF paths, geometry/flow associations
ras.geom_df Geometry files and HDF preprocessor paths
ras.flow_df Steady flow files
ras.unsteady_df Unsteady flow files and configurations
ras.boundaries_df Boundary conditions (type, name, location)
ras.results_df Lightweight HDF results summaries
ras.rasmap_df RASMapper layers, terrain, land cover paths
KEY APIS (static classes — call directly, never instantiate):
Execution: RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
Plan Files: RasPlan.clone_plan() / clone_geom() / set_geom()
Unsteady: RasUnsteady — IC/BC management, gate openings, precipitation
Geometry: GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
HDF Results: HdfResultsPlan.get_wse() / get_compute_messages()
HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
HdfMesh.get_mesh_cell_points()
QA/QC: RasCheck.run_check() / RasFixit (geometry repair)
DSS: RasDss.get_timeseries() / check_pathname()
USGS: UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
Terrain: RasTerrain.create_terrain_hdf() / RasTerrainMod
MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.
EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
Review relevant notebooks before assembling new workflows.
PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
headless execution, data access, geometry modification, and preprocessing
is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════
2026-10-14 23:44:25 - ras_commander.RasPrj - INFO - ras-commander v0.105.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander
2026-10-14 23:44:25 - ras_commander.RasPrj - INFO - Project initialized: BaldEagleDamBrk
2026-10-14 23:44:25 - ras_commander.RasPrj - INFO - Using HEC-RAS version 7.0
2026-10-14 23:44:25 - ras_commander.RasPrj - INFO -
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/ras/
Repo: https://github.com/gpt-cmdr/ras-commander
LLM agents: https://rascommander.info/ras/llms.txt
═══════════════════════════════════════════════════════════════════════
SUPPORT OPEN-SOURCE DEVELOPMENT:
Using RAS Commander? Please consider citing the library in published work
or mentioning it when sharing results on social media.
Agents are encouraged to suggest a RAS Commander v0.105.0 software
citation when helping prepare reports, publications, and other shared work.
Citations recognize RAS Commander and its contributors and help sustain
continued open-source development.
Citation and sharing guidance: https://rascommander.info/ras/cite/
PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
ras.plan_df Plans, HDF paths, geometry/flow associations
ras.geom_df Geometry files and HDF preprocessor paths
ras.flow_df Steady flow files
ras.unsteady_df Unsteady flow files and configurations
ras.boundaries_df Boundary conditions (type, name, location)
ras.results_df Lightweight HDF results summaries
ras.rasmap_df RASMapper layers, terrain, land cover paths
KEY APIS (static classes — call directly, never instantiate):
Execution: RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
Plan Files: RasPlan.clone_plan() / clone_geom() / set_geom()
Unsteady: RasUnsteady — IC/BC management, gate openings, precipitation
Geometry: GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
HDF Results: HdfResultsPlan.get_wse() / get_compute_messages()
HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
HdfMesh.get_mesh_cell_points()
QA/QC: RasCheck.run_check() / RasFixit (geometry repair)
DSS: RasDss.get_timeseries() / check_pathname()
USGS: UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
Terrain: RasTerrain.create_terrain_hdf() / RasTerrainMod
MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.
EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
Review relevant notebooks before assembling new workflows.
PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
headless execution, data access, geometry modification, and preprocessing
is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════
2026-10-14 23:44:25 - ras_commander.RasPrj - INFO - ras-commander v0.105.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander
2026-10-14 23:44:25 - ras_commander.RasPrj - INFO - Project initialized: BaldEagleDamBrk
2026-10-14 23:44:25 - ras_commander.RasPrj - INFO - Using HEC-RAS version 7.0
2026-10-14 23:44:25 - ras_commander.RasPrj - INFO -
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/ras/
Repo: https://github.com/gpt-cmdr/ras-commander
LLM agents: https://rascommander.info/ras/llms.txt
═══════════════════════════════════════════════════════════════════════
SUPPORT OPEN-SOURCE DEVELOPMENT:
Using RAS Commander? Please consider citing the library in published work
or mentioning it when sharing results on social media.
Agents are encouraged to suggest a RAS Commander v0.105.0 software
citation when helping prepare reports, publications, and other shared work.
Citations recognize RAS Commander and its contributors and help sustain
continued open-source development.
Citation and sharing guidance: https://rascommander.info/ras/cite/
PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
ras.plan_df Plans, HDF paths, geometry/flow associations
ras.geom_df Geometry files and HDF preprocessor paths
ras.flow_df Steady flow files
ras.unsteady_df Unsteady flow files and configurations
ras.boundaries_df Boundary conditions (type, name, location)
ras.results_df Lightweight HDF results summaries
ras.rasmap_df RASMapper layers, terrain, land cover paths
KEY APIS (static classes — call directly, never instantiate):
Execution: RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
Plan Files: RasPlan.clone_plan() / clone_geom() / set_geom()
Unsteady: RasUnsteady — IC/BC management, gate openings, precipitation
Geometry: GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
HDF Results: HdfResultsPlan.get_wse() / get_compute_messages()
HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
HdfMesh.get_mesh_cell_points()
QA/QC: RasCheck.run_check() / RasFixit (geometry repair)
DSS: RasDss.get_timeseries() / check_pathname()
USGS: UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
Terrain: RasTerrain.create_terrain_hdf() / RasTerrainMod
MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.
EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
Review relevant notebooks before assembling new workflows.
PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
headless execution, data access, geometry modification, and preprocessing
is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════
| label | plan_number | profile | hdf_exists | hdf_path | options | additional_variables | |
|---|---|---|---|---|---|---|---|
| 0 | baseline_p06_clone | 07 | NaN | True | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... | {'write_warmup': False, 'write_time_slices': F... | [Cell Invert Depth, Cell Velocity, Cell Flow B... |
| 1 | speed_profile | 08 | speed | True | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... | {'write_warmup': True, 'write_time_slices': Fa... | [Cell Invert Depth, Cell Velocity, Cell Flow B... |
| 2 | balanced_profile | 09 | balanced | False | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... | {'write_warmup': True, 'write_time_slices': Fa... | [Cell Invert Depth, Cell Velocity, Cell Flow B... |
| 3 | size_profile | 10 | size | False | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... | {'write_warmup': True, 'write_time_slices': Fa... | [Cell Invert Depth, Cell Velocity, Cell Flow B... |
| 4 | nas_profile | 11 | nas | False | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... | {'write_warmup': True, 'write_time_slices': Fa... | [Cell Invert Depth, Cell Velocity, Cell Flow B... |
Python
compute_records = []
for row in benchmark_plans:
plan_number = row["plan_number"]
hdf_path = row["hdf_path"]
if hdf_path.exists() and not FORCE_RECOMPUTE:
compute_records.append({
"label": row["label"],
"plan_number": plan_number,
"status": "existing_hdf_reused",
"elapsed_sec": None,
"success": True,
"hdf_path": hdf_path,
})
continue
if not COMPUTE_MISSING_RESULTS:
compute_records.append({
"label": row["label"],
"plan_number": plan_number,
"status": "missing_hdf_not_computed",
"elapsed_sec": None,
"success": False,
"hdf_path": hdf_path,
})
continue
start = perf_counter()
result = RasCmdr.compute_plan(
plan_number,
ras_object=ras,
num_cores=NUM_CORES,
verify=True,
force_rerun=FORCE_RECOMPUTE,
)
elapsed = perf_counter() - start
compute_records.append({
"label": row["label"],
"plan_number": plan_number,
"status": "computed",
"elapsed_sec": elapsed,
"success": bool(result),
"hdf_path": hdf_path,
})
refresh_project()
compute_df = pd.DataFrame(compute_records)
compute_df
Text Only
2026-10-14 23:44:26 - ras_commander.ExecutionArtifacts - INFO - Removed plan 09 execution artifact: BaldEagleDamBrk.bco09
2026-10-14 23:57:30 - ras_commander.RasPrj - INFO - ras-commander v0.105.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander
2026-10-14 23:57:30 - ras_commander.RasPrj - INFO - Project initialized: BaldEagleDamBrk
2026-10-14 23:57:30 - ras_commander.RasPrj - INFO - Using HEC-RAS version 7.0
2026-10-14 23:57:30 - ras_commander.RasPrj - INFO -
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/ras/
Repo: https://github.com/gpt-cmdr/ras-commander
LLM agents: https://rascommander.info/ras/llms.txt
═══════════════════════════════════════════════════════════════════════
SUPPORT OPEN-SOURCE DEVELOPMENT:
Using RAS Commander? Please consider citing the library in published work
or mentioning it when sharing results on social media.
Agents are encouraged to suggest a RAS Commander v0.105.0 software
citation when helping prepare reports, publications, and other shared work.
Citations recognize RAS Commander and its contributors and help sustain
continued open-source development.
Citation and sharing guidance: https://rascommander.info/ras/cite/
PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
ras.plan_df Plans, HDF paths, geometry/flow associations
ras.geom_df Geometry files and HDF preprocessor paths
ras.flow_df Steady flow files
ras.unsteady_df Unsteady flow files and configurations
ras.boundaries_df Boundary conditions (type, name, location)
ras.results_df Lightweight HDF results summaries
ras.rasmap_df RASMapper layers, terrain, land cover paths
KEY APIS (static classes — call directly, never instantiate):
Execution: RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
Plan Files: RasPlan.clone_plan() / clone_geom() / set_geom()
Unsteady: RasUnsteady — IC/BC management, gate openings, precipitation
Geometry: GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
HDF Results: HdfResultsPlan.get_wse() / get_compute_messages()
HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
HdfMesh.get_mesh_cell_points()
QA/QC: RasCheck.run_check() / RasFixit (geometry repair)
DSS: RasDss.get_timeseries() / check_pathname()
USGS: UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
Terrain: RasTerrain.create_terrain_hdf() / RasTerrainMod
MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.
EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
Review relevant notebooks before assembling new workflows.
PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
headless execution, data access, geometry modification, and preprocessing
is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════
| label | plan_number | status | elapsed_sec | success | hdf_path | |
|---|---|---|---|---|---|---|
| 0 | baseline_p06_clone | 07 | existing_hdf_reused | NaN | True | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 1 | speed_profile | 08 | existing_hdf_reused | NaN | True | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 2 | balanced_profile | 09 | computed | 267.130903 | True | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 3 | size_profile | 10 | computed | 257.323301 | True | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 4 | nas_profile | 11 | computed | 260.069986 | True | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
Python
hdf_inventory = []
for row in benchmark_plans:
hdf_path = row["hdf_path"]
hdf_inventory.append({
"label": row["label"],
"plan_number": row["plan_number"],
"hdf_exists": hdf_path.exists(),
"hdf_size_mb": hdf_path.stat().st_size / 1024**2 if hdf_path.exists() else None,
"hdf_path": hdf_path,
})
hdf_inventory_df = pd.DataFrame(hdf_inventory)
hdf_inventory_df
| label | plan_number | hdf_exists | hdf_size_mb | hdf_path | |
|---|---|---|---|---|---|
| 0 | baseline_p06_clone | 07 | True | 577.238389 | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 1 | speed_profile | 08 | True | 577.239123 | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 2 | balanced_profile | 09 | True | 568.131610 | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 3 | size_profile | 10 | True | 566.244820 | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
| 4 | nas_profile | 11 | True | 566.244823 | D:\CLB-Temp\clb-t3-pr534\repo\examples\working... |
Python
missing = hdf_inventory_df[~hdf_inventory_df["hdf_exists"]]
if not missing.empty:
print("These plans do not have HDF results yet. Set COMPUTE_MISSING_RESULTS = True and run the compute cell.")
display(missing[["label", "plan_number", "hdf_path"]])
available_hdfs = hdf_inventory_df[hdf_inventory_df["hdf_exists"]].copy()
if available_hdfs.empty:
raise RuntimeError("No populated HDF files are available for read benchmarking.")
first_hdf = Path(available_hdfs.iloc[0]["hdf_path"])
mesh_names = HdfMesh.get_mesh_area_names(first_hdf)
if not mesh_names:
raise RuntimeError(f"No mesh areas found in {first_hdf}")
PRIMARY_MESH = mesh_names[0]
print(f"Primary mesh: {PRIMARY_MESH}")
print(mesh_names)
Text Only
Primary mesh: BaldEagleCr
['BaldEagleCr']
Python
def summarize_output(obj):
summary = {"result_type": type(obj).__name__}
if isinstance(obj, dict):
summary["items"] = len(obj)
summary["shape"] = str({k: getattr(v, "shape", None) for k, v in obj.items()})
return summary
if hasattr(obj, "shape"):
summary["shape"] = str(obj.shape)
if hasattr(obj, "__len__"):
try:
summary["rows_or_len"] = len(obj)
except TypeError:
pass
if hasattr(obj, "memory_usage"):
try:
summary["memory_mb"] = obj.memory_usage(deep=True).sum() / 1024**2
except Exception:
pass
elif hasattr(obj, "nbytes"):
try:
summary["memory_mb"] = obj.nbytes / 1024**2
except Exception:
pass
return summary
def extraction_operations(hdf_path: Path, mesh_name: str):
return [
("mesh_area_names", "mesh_geometry", lambda: HdfMesh.get_mesh_area_names(hdf_path)),
("mesh_cell_points", "mesh_geometry", lambda: HdfMesh.get_mesh_cell_points(hdf_path)),
("mesh_cell_faces", "mesh_geometry", lambda: HdfMesh.get_mesh_cell_faces(hdf_path)),
("mesh_cell_polygons", "mesh_geometry", lambda: HdfMesh.get_mesh_cell_polygons(hdf_path)),
("mesh_summary_max_ws", "summary_results", lambda: HdfResultsMesh.get_mesh_max_ws(hdf_path)),
("mesh_summary_max_face_v", "summary_results", lambda: HdfResultsMesh.get_mesh_max_face_v(hdf_path)),
("timeseries_depth", "timeseries_results", lambda: HdfResultsMesh.get_mesh_timeseries(hdf_path, mesh_name, "Depth", truncate=False)),
("timeseries_water_surface", "timeseries_results", lambda: HdfResultsMesh.get_mesh_timeseries(hdf_path, mesh_name, "Water Surface", truncate=False)),
("max_depth_from_timeseries", "timeseries_results", lambda: HdfResultsMesh.get_mesh_max_depth(hdf_path)),
]
def time_operation(label: str, plan_number: str, hdf_path: Path, operation_name: str, category: str, fn, repeat: int):
gc.collect()
start = perf_counter()
try:
result = fn()
elapsed = perf_counter() - start
output_summary = summarize_output(result)
return {
"label": label,
"plan_number": plan_number,
"operation": operation_name,
"category": category,
"repeat": repeat,
"elapsed_sec": elapsed,
"success": True,
"error": None,
**output_summary,
}
except Exception as exc:
elapsed = perf_counter() - start
return {
"label": label,
"plan_number": plan_number,
"operation": operation_name,
"category": category,
"repeat": repeat,
"elapsed_sec": elapsed,
"success": False,
"error": repr(exc),
"result_type": None,
}
Python
read_records = []
for _, hdf_row in available_hdfs.iterrows():
label = hdf_row["label"]
plan_number = hdf_row["plan_number"]
hdf_path = Path(hdf_row["hdf_path"])
mesh_for_file = HdfMesh.get_mesh_area_names(hdf_path)[0]
for repeat in range(1, READ_REPETITIONS + 1):
for operation_name, category, fn in extraction_operations(hdf_path, mesh_for_file):
read_records.append(
time_operation(
label,
plan_number,
hdf_path,
operation_name,
category,
fn,
repeat,
)
)
read_benchmark_df = pd.DataFrame(read_records)
read_benchmark_df
Text Only
2026-10-14 23:57:33 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p07.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:57:35 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p07.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:57:38 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p07.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:57:40 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p08.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:57:43 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p08.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:57:46 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p08.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:57:48 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p09.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:57:51 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p09.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:57:53 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p09.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:57:56 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p10.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:57:59 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p10.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:58:01 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p10.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:58:04 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p11.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:58:06 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p11.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
2026-10-14 23:58:09 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'BaldEagleCr' in 'BaldEagleDamBrk.p11.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
| label | plan_number | operation | category | repeat | elapsed_sec | success | error | result_type | rows_or_len | shape | memory_mb | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | baseline_p06_clone | 07 | mesh_area_names | mesh_geometry | 1 | 0.001577 | True | NaN | list | 1.0 | NaN | NaN |
| 1 | baseline_p06_clone | 07 | mesh_cell_points | mesh_geometry | 1 | 0.153123 | True | NaN | GeoDataFrame | 19597.0 | (19597, 3) | 0.654246 |
| 2 | baseline_p06_clone | 07 | mesh_cell_faces | mesh_geometry | 1 | 0.307061 | True | NaN | GeoDataFrame | 37594.0 | (37594, 3) | 1.254961 |
| 3 | baseline_p06_clone | 07 | mesh_cell_polygons | mesh_geometry | 1 | 0.757530 | True | NaN | GeoDataFrame | 18066.0 | (18066, 3) | 0.603144 |
| 4 | baseline_p06_clone | 07 | mesh_summary_max_ws | summary_results | 1 | 0.122703 | True | NaN | GeoDataFrame | 18066.0 | (18066, 6) | 0.829276 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 130 | nas_profile | 11 | mesh_summary_max_ws | summary_results | 3 | 0.122698 | True | NaN | GeoDataFrame | 18066.0 | (18066, 6) | 0.829276 |
| 131 | nas_profile | 11 | mesh_summary_max_face_v | summary_results | 3 | 0.336830 | True | NaN | GeoDataFrame | 37594.0 | (37594, 5) | 1.685190 |
| 132 | nas_profile | 11 | timeseries_depth | timeseries_results | 3 | 0.001495 | False | ValueError('Path Results/Unsteady/Output/Outpu... | NaN | NaN | NaN | NaN |
| 133 | nas_profile | 11 | timeseries_water_surface | timeseries_results | 3 | 0.238239 | True | NaN | DataArray | 721.0 | (721, 18066) | 49.688667 |
| 134 | nas_profile | 11 | max_depth_from_timeseries | timeseries_results | 3 | 0.389284 | True | NaN | GeoDataFrame | 18066.0 | (18066, 5) | 0.691443 |
135 rows × 12 columns
Python
successful_reads = read_benchmark_df[read_benchmark_df["success"]].copy()
summary_df = (
successful_reads
.groupby(["label", "plan_number", "category", "operation"], as_index=False)
.agg(
median_elapsed_sec=("elapsed_sec", "median"),
min_elapsed_sec=("elapsed_sec", "min"),
max_elapsed_sec=("elapsed_sec", "max"),
repeats=("elapsed_sec", "count"),
result_type=("result_type", "first"),
shape=("shape", "first"),
rows_or_len=("rows_or_len", "first"),
memory_mb=("memory_mb", "first"),
)
.merge(hdf_inventory_df[["label", "hdf_size_mb"]], on="label", how="left")
.sort_values(["operation", "median_elapsed_sec"])
)
summary_df
| label | plan_number | category | operation | median_elapsed_sec | min_elapsed_sec | max_elapsed_sec | repeats | result_type | shape | rows_or_len | memory_mb | hdf_size_mb | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 22 | nas_profile | 11 | timeseries_results | max_depth_from_timeseries | 0.388339 | 0.386659 | 0.389284 | 3 | GeoDataFrame | (18066, 5) | 18066.0 | 0.691443 | 566.244823 |
| 6 | balanced_profile | 09 | timeseries_results | max_depth_from_timeseries | 0.393192 | 0.392915 | 0.398596 | 3 | GeoDataFrame | (18066, 5) | 18066.0 | 0.691443 | 568.131610 |
| 30 | size_profile | 10 | timeseries_results | max_depth_from_timeseries | 0.403226 | 0.391140 | 0.403962 | 3 | GeoDataFrame | (18066, 5) | 18066.0 | 0.691443 | 566.244820 |
| 14 | baseline_p06_clone | 07 | timeseries_results | max_depth_from_timeseries | 0.410883 | 0.409525 | 0.411668 | 3 | GeoDataFrame | (18066, 5) | 18066.0 | 0.691443 | 577.238389 |
| 38 | speed_profile | 08 | timeseries_results | max_depth_from_timeseries | 0.412137 | 0.404456 | 0.417006 | 3 | GeoDataFrame | (18066, 5) | 18066.0 | 0.691443 | 577.239123 |
| 32 | speed_profile | 08 | mesh_geometry | mesh_area_names | 0.001588 | 0.001553 | 0.001670 | 3 | list | NaN | 1.0 | NaN | 577.239123 |
| 16 | nas_profile | 11 | mesh_geometry | mesh_area_names | 0.001622 | 0.001576 | 0.001836 | 3 | list | NaN | 1.0 | NaN | 566.244823 |
| 0 | balanced_profile | 09 | mesh_geometry | mesh_area_names | 0.001625 | 0.001625 | 0.001641 | 3 | list | NaN | 1.0 | NaN | 568.131610 |
| 8 | baseline_p06_clone | 07 | mesh_geometry | mesh_area_names | 0.001647 | 0.001577 | 0.001713 | 3 | list | NaN | 1.0 | NaN | 577.238389 |
| 24 | size_profile | 10 | mesh_geometry | mesh_area_names | 0.001662 | 0.001613 | 0.001665 | 3 | list | NaN | 1.0 | NaN | 566.244820 |
| 17 | nas_profile | 11 | mesh_geometry | mesh_cell_faces | 0.295849 | 0.294790 | 0.298811 | 3 | GeoDataFrame | (37594, 3) | 37594.0 | 1.254961 | 566.244823 |
| 1 | balanced_profile | 09 | mesh_geometry | mesh_cell_faces | 0.299563 | 0.294819 | 0.305415 | 3 | GeoDataFrame | (37594, 3) | 37594.0 | 1.254961 | 568.131610 |
| 25 | size_profile | 10 | mesh_geometry | mesh_cell_faces | 0.301674 | 0.301360 | 0.314899 | 3 | GeoDataFrame | (37594, 3) | 37594.0 | 1.254961 | 566.244820 |
| 33 | speed_profile | 08 | mesh_geometry | mesh_cell_faces | 0.302782 | 0.299850 | 0.305761 | 3 | GeoDataFrame | (37594, 3) | 37594.0 | 1.254961 | 577.239123 |
| 9 | baseline_p06_clone | 07 | mesh_geometry | mesh_cell_faces | 0.307061 | 0.299792 | 0.310009 | 3 | GeoDataFrame | (37594, 3) | 37594.0 | 1.254961 | 577.238389 |
| 18 | nas_profile | 11 | mesh_geometry | mesh_cell_points | 0.096621 | 0.096132 | 0.098074 | 3 | GeoDataFrame | (19597, 3) | 19597.0 | 0.654246 | 566.244823 |
| 34 | speed_profile | 08 | mesh_geometry | mesh_cell_points | 0.098829 | 0.096539 | 0.102312 | 3 | GeoDataFrame | (19597, 3) | 19597.0 | 0.654246 | 577.239123 |
| 2 | balanced_profile | 09 | mesh_geometry | mesh_cell_points | 0.099343 | 0.097538 | 0.109659 | 3 | GeoDataFrame | (19597, 3) | 19597.0 | 0.654246 | 568.131610 |
| 10 | baseline_p06_clone | 07 | mesh_geometry | mesh_cell_points | 0.100194 | 0.096433 | 0.153123 | 3 | GeoDataFrame | (19597, 3) | 19597.0 | 0.654246 | 577.238389 |
| 26 | size_profile | 10 | mesh_geometry | mesh_cell_points | 0.101147 | 0.096612 | 0.101219 | 3 | GeoDataFrame | (19597, 3) | 19597.0 | 0.654246 | 566.244820 |
| 19 | nas_profile | 11 | mesh_geometry | mesh_cell_polygons | 0.725296 | 0.723392 | 0.727479 | 3 | GeoDataFrame | (18066, 3) | 18066.0 | 0.603144 | 566.244823 |
| 35 | speed_profile | 08 | mesh_geometry | mesh_cell_polygons | 0.729703 | 0.727067 | 0.732903 | 3 | GeoDataFrame | (18066, 3) | 18066.0 | 0.603144 | 577.239123 |
| 3 | balanced_profile | 09 | mesh_geometry | mesh_cell_polygons | 0.729933 | 0.728026 | 0.730046 | 3 | GeoDataFrame | (18066, 3) | 18066.0 | 0.603144 | 568.131610 |
| 11 | baseline_p06_clone | 07 | mesh_geometry | mesh_cell_polygons | 0.730492 | 0.725934 | 0.757530 | 3 | GeoDataFrame | (18066, 3) | 18066.0 | 0.603144 | 577.238389 |
| 27 | size_profile | 10 | mesh_geometry | mesh_cell_polygons | 0.752065 | 0.724155 | 0.755867 | 3 | GeoDataFrame | (18066, 3) | 18066.0 | 0.603144 | 566.244820 |
| 4 | balanced_profile | 09 | summary_results | mesh_summary_max_face_v | 0.333289 | 0.328177 | 0.334972 | 3 | GeoDataFrame | (37594, 5) | 37594.0 | 1.685190 | 568.131610 |
| 12 | baseline_p06_clone | 07 | summary_results | mesh_summary_max_face_v | 0.334236 | 0.332452 | 0.338518 | 3 | GeoDataFrame | (37594, 5) | 37594.0 | 1.685190 | 577.238389 |
| 36 | speed_profile | 08 | summary_results | mesh_summary_max_face_v | 0.336027 | 0.334806 | 0.338964 | 3 | GeoDataFrame | (37594, 5) | 37594.0 | 1.685190 | 577.239123 |
| 20 | nas_profile | 11 | summary_results | mesh_summary_max_face_v | 0.336830 | 0.335064 | 0.368512 | 3 | GeoDataFrame | (37594, 5) | 37594.0 | 1.685190 | 566.244823 |
| 28 | size_profile | 10 | summary_results | mesh_summary_max_face_v | 0.356477 | 0.331925 | 0.372149 | 3 | GeoDataFrame | (37594, 5) | 37594.0 | 1.685190 | 566.244820 |
| 13 | baseline_p06_clone | 07 | summary_results | mesh_summary_max_ws | 0.122703 | 0.121977 | 0.124242 | 3 | GeoDataFrame | (18066, 6) | 18066.0 | 0.829276 | 577.238389 |
| 21 | nas_profile | 11 | summary_results | mesh_summary_max_ws | 0.123067 | 0.122698 | 0.147359 | 3 | GeoDataFrame | (18066, 6) | 18066.0 | 0.829276 | 566.244823 |
| 5 | balanced_profile | 09 | summary_results | mesh_summary_max_ws | 0.123460 | 0.122754 | 0.124520 | 3 | GeoDataFrame | (18066, 6) | 18066.0 | 0.829276 | 568.131610 |
| 37 | speed_profile | 08 | summary_results | mesh_summary_max_ws | 0.125150 | 0.123050 | 0.126765 | 3 | GeoDataFrame | (18066, 6) | 18066.0 | 0.829276 | 577.239123 |
| 29 | size_profile | 10 | summary_results | mesh_summary_max_ws | 0.127625 | 0.126486 | 0.130430 | 3 | GeoDataFrame | (18066, 6) | 18066.0 | 0.829276 | 566.244820 |
| 23 | nas_profile | 11 | timeseries_results | timeseries_water_surface | 0.236662 | 0.234589 | 0.238239 | 3 | DataArray | (721, 18066) | 721.0 | 49.688667 | 566.244823 |
| 31 | size_profile | 10 | timeseries_results | timeseries_water_surface | 0.240778 | 0.237946 | 0.244753 | 3 | DataArray | (721, 18066) | 721.0 | 49.688667 | 566.244820 |
| 7 | balanced_profile | 09 | timeseries_results | timeseries_water_surface | 0.243332 | 0.238264 | 0.247325 | 3 | DataArray | (721, 18066) | 721.0 | 49.688667 | 568.131610 |
| 15 | baseline_p06_clone | 07 | timeseries_results | timeseries_water_surface | 0.259696 | 0.257011 | 0.367545 | 3 | DataArray | (721, 18066) | 721.0 | 49.688667 | 577.238389 |
| 39 | speed_profile | 08 | timeseries_results | timeseries_water_surface | 0.264607 | 0.263478 | 0.270515 | 3 | DataArray | (721, 18066) | 721.0 | 49.688667 | 577.239123 |
Python
pivot = summary_df.pivot_table(
index=["category", "operation"],
columns="label",
values="median_elapsed_sec",
aggfunc="first",
)
pivot
| label | balanced_profile | baseline_p06_clone | nas_profile | size_profile | speed_profile | |
|---|---|---|---|---|---|---|
| category | operation | |||||
| mesh_geometry | mesh_area_names | 0.001625 | 0.001647 | 0.001622 | 0.001662 | 0.001588 |
| mesh_cell_faces | 0.299563 | 0.307061 | 0.295849 | 0.301674 | 0.302782 | |
| mesh_cell_points | 0.099343 | 0.100194 | 0.096621 | 0.101147 | 0.098829 | |
| mesh_cell_polygons | 0.729933 | 0.730492 | 0.725296 | 0.752065 | 0.729703 | |
| summary_results | mesh_summary_max_face_v | 0.333289 | 0.334236 | 0.336830 | 0.356477 | 0.336027 |
| mesh_summary_max_ws | 0.123460 | 0.122703 | 0.123067 | 0.127625 | 0.125150 | |
| timeseries_results | max_depth_from_timeseries | 0.393192 | 0.410883 | 0.388339 | 0.403226 | 0.412137 |
| timeseries_water_surface | 0.243332 | 0.259696 | 0.236662 | 0.240778 | 0.264607 |
Python
ranking_df = (
summary_df
.groupby(["label", "plan_number"], as_index=False)
.agg(
total_median_read_sec=("median_elapsed_sec", "sum"),
hdf_size_mb=("hdf_size_mb", "first"),
)
)
ranking_df["read_rank"] = ranking_df["total_median_read_sec"].rank(method="min")
ranking_df["size_rank"] = ranking_df["hdf_size_mb"].rank(method="min")
ranking_df["balanced_rank_score"] = ranking_df["read_rank"] + ranking_df["size_rank"]
ranking_df.sort_values(["balanced_rank_score", "total_median_read_sec", "hdf_size_mb"])
| label | plan_number | total_median_read_sec | hdf_size_mb | read_rank | size_rank | balanced_rank_score | |
|---|---|---|---|---|---|---|---|
| 2 | nas_profile | 11 | 2.204286 | 566.244823 | 1.0 | 2.0 | 3.0 |
| 0 | balanced_profile | 09 | 2.223737 | 568.131610 | 2.0 | 3.0 | 5.0 |
| 3 | size_profile | 10 | 2.284654 | 566.244820 | 5.0 | 1.0 | 6.0 |
| 1 | baseline_p06_clone | 07 | 2.266910 | 577.238389 | 3.0 | 4.0 | 7.0 |
| 4 | speed_profile | 08 | 2.270822 | 577.239123 | 4.0 | 5.0 | 9.0 |
Python
def inspect_hdf_datasets(hdf_path: Path):
records = []
meshes = HdfMesh.get_mesh_area_names(hdf_path)
with h5py.File(hdf_path, "r") as hdf:
for mesh_name in meshes:
candidate_paths = [
f"Results/Unsteady/Output/Output Blocks/Base Output/Unsteady Time Series/2D Flow Areas/{mesh_name}/Depth",
f"Results/Unsteady/Output/Output Blocks/Base Output/Unsteady Time Series/2D Flow Areas/{mesh_name}/Water Surface",
f"Results/Unsteady/Output/Output Blocks/Base Output/Summary Output/2D Flow Areas/{mesh_name}/Maximum Water Surface",
f"Results/Unsteady/Output/Output Blocks/Base Output/Summary Output/2D Flow Areas/{mesh_name}/Maximum Face Velocity",
]
for dataset_path in candidate_paths:
if dataset_path not in hdf:
continue
item = hdf[dataset_path]
if isinstance(item, h5py.Dataset):
records.append({
"hdf_path": hdf_path,
"mesh_name": mesh_name,
"dataset": dataset_path.split("/")[-1],
"object_type": "dataset",
"shape": item.shape,
"dtype": str(item.dtype),
"chunks": item.chunks,
"compression": item.compression,
"compression_opts": item.compression_opts,
})
else:
records.append({
"hdf_path": hdf_path,
"mesh_name": mesh_name,
"dataset": dataset_path.split("/")[-1],
"object_type": "group",
"shape": None,
"dtype": None,
"chunks": None,
"compression": None,
"compression_opts": None,
})
return records
dataset_records = []
for _, hdf_row in available_hdfs.iterrows():
for record in inspect_hdf_datasets(Path(hdf_row["hdf_path"])):
record.update({
"label": hdf_row["label"],
"plan_number": hdf_row["plan_number"],
})
dataset_records.append(record)
dataset_layout_df = pd.DataFrame(dataset_records)
dataset_layout_df[["label", "plan_number", "mesh_name", "dataset", "shape", "chunks", "compression", "compression_opts"]]
| label | plan_number | mesh_name | dataset | shape | chunks | compression | compression_opts | |
|---|---|---|---|---|---|---|---|---|
| 0 | baseline_p06_clone | 07 | BaldEagleCr | Water Surface | (721, 19597) | (2, 19597) | gzip | 1 |
| 1 | baseline_p06_clone | 07 | BaldEagleCr | Maximum Water Surface | (2, 19597) | (2, 19597) | gzip | 1 |
| 2 | baseline_p06_clone | 07 | BaldEagleCr | Maximum Face Velocity | (2, 37594) | (1, 37594) | gzip | 1 |
| 3 | speed_profile | 08 | BaldEagleCr | Water Surface | (721, 19597) | (2, 19597) | gzip | 1 |
| 4 | speed_profile | 08 | BaldEagleCr | Maximum Water Surface | (2, 19597) | (2, 19597) | gzip | 1 |
| 5 | speed_profile | 08 | BaldEagleCr | Maximum Face Velocity | (2, 37594) | (1, 37594) | gzip | 1 |
| 6 | balanced_profile | 09 | BaldEagleCr | Water Surface | (721, 19597) | (2, 19597) | gzip | 4 |
| 7 | balanced_profile | 09 | BaldEagleCr | Maximum Water Surface | (2, 19597) | (2, 19597) | gzip | 4 |
| 8 | balanced_profile | 09 | BaldEagleCr | Maximum Face Velocity | (2, 37594) | (1, 37594) | gzip | 4 |
| 9 | size_profile | 10 | BaldEagleCr | Water Surface | (721, 19597) | (2, 19597) | gzip | 6 |
| 10 | size_profile | 10 | BaldEagleCr | Maximum Water Surface | (2, 19597) | (2, 19597) | gzip | 6 |
| 11 | size_profile | 10 | BaldEagleCr | Maximum Face Velocity | (2, 37594) | (1, 37594) | gzip | 6 |
| 12 | nas_profile | 11 | BaldEagleCr | Water Surface | (721, 19597) | (2, 19597) | gzip | 6 |
| 13 | nas_profile | 11 | BaldEagleCr | Maximum Water Surface | (2, 19597) | (2, 19597) | gzip | 6 |
| 14 | nas_profile | 11 | BaldEagleCr | Maximum Face Velocity | (2, 37594) | (1, 37594) | gzip | 6 |
Interpreting Results¶
- Use the operation pivot to see whether an HDF setting helps geometry reads, summary reads, or full time-series reads.
- Use the ranking table as a quick read-speed plus file-size score, not as a universal answer.
- Re-run the read benchmark after moving the same populated project to HDD, SSD, and NAS storage. OS cache can dominate short benchmarks, so compare medians over several repetitions and repeat on a quiet machine.
- If additional variables are enabled, only compare against runs where those same variables were enabled; otherwise file size and read timing are not like-for-like.