Skip to content

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

  1. Extract a working copy of BaldEagleCrkMult2D.
  2. Clone template plan 06 once for each HDF settings permutation.
  3. Apply each HDF output profile or explicit option set to its clone.
  4. Compute missing clone results if requested.
  5. Benchmark HDF reads from the populated .p##.hdf files.

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.