Skip to content

HDF Modules

Classes for reading and processing HEC-RAS HDF result files.

Core Classes

HdfBase

Base functionality for HDF file operations.

  • get_dataset_info(hdf_path, group_path=None) - Print HDF structure
  • get_attrs(hdf_path, path) - Get attributes at path
  • get_projection(hdf_path) - Get coordinate system
  • parse_ras_datetime(datetime_str) - Parse HEC-RAS datetime string
  • parse_ras_datetime_ms(datetime_bytes) - Parse datetime with milliseconds

HdfPlan

Plan-level information from HDF files.

  • get_plan_info(hdf_path) - Get plan metadata
  • get_simulation_times(hdf_path) - Get start/end times
  • get_plan_parameters(hdf_path) - Get computation parameters
  • get_2d_flow_options(hdf_path) - Get 2D equation set, initial condition time, tolerances, and solver options from computed HDF output

Mesh Operations

HdfMesh

Mesh geometry data.

  • get_mesh_area_names(hdf_path) - List 2D flow areas
  • get_mesh_cell_polygons(hdf_path) - Get cell polygons as GeoDataFrame
  • get_mesh_cell_faces(hdf_path) - Get cell face lines
  • get_mesh_cell_points(hdf_path) - Get cell center points
  • get_mesh_perimeter(hdf_path) - Get mesh perimeter polygon
  • get_mesh_cell_count(hdf_path) - Get number of cells
  • get_nearest_cell(hdf_path, point) - Find nearest cell to point
  • get_nearest_face(hdf_path, point) - Find nearest face to point
  • get_mesh_face_property_tables(hdf_path) - Read face elevation/area/wetted-perimeter/Manning tables

EXPERIMENTAL — not recommended for production or any other non-experimental use. These direct writes have been tested only with HEC-RAS 7.0 April 2026 in one Windows-preprocess/Linux-solve *.p##.tmp.hdf workflow. All other HEC-RAS versions and workflows are untested. They are not general land-cover or geometry-authoring APIs.

The methods require acknowledge_unsupported=True, validate the exact temporary-result role and schema, retain a unique full-file backup, emit a runtime warning, and verify readback:

  • write_linux_tmp_face_property_tables(...) - Replace selected temporary face tables
  • extend_linux_tmp_face_property_tables(...) - Extend temporary tables and return a structured report
  • transform_linux_tmp_face_mannings_n(...) - Transform only the temporary-table Manning column
  • sample_linux_tmp_face_mannings_n_from_landcover_curves(...) - Apply the documented equal-class land-cover sampling heuristic
  • set_mesh_pinned_attribute(...) - Set informational Pinned metadata; this does not protect edits from Windows preprocessing

The former names remain compatibility wrappers through v1.1.x and will not be removed before v1.2.0:

Compatibility name Canonical replacement
set_mesh_face_property_tables() write_linux_tmp_face_property_tables()
extend_face_property_tables() extend_linux_tmp_face_property_tables()
set_face_mannings_n_values() transform_linux_tmp_face_mannings_n()
recompute_face_mannings_n_from_landcover_curves() sample_linux_tmp_face_mannings_n_from_landcover_curves()
pin_property_tables() set_mesh_pinned_attribute()

HdfResultsMesh

2D mesh results.

  • get_mesh_max_ws(hdf_path) - Maximum water surface elevation
  • get_mesh_max_ws_time(hdf_path) - Time of maximum WSE
  • get_mesh_max_depth(hdf_path) - Maximum depth
  • get_mesh_max_face_v(hdf_path) - Maximum face velocity
  • get_mesh_timeseries(hdf_path, mesh, var) - Time series for mesh
  • get_mesh_cells_timeseries(hdf_path, mesh, cell_ids, var) - Cell time series
  • get_mesh_faces_timeseries(hdf_path, mesh, face_ids, var) - Face time series
  • get_profile_line_flow_timeseries(hdf_path, line_name, mesh_name=None, profile_lines_path=None, direction="absolute") - Flow time series across a RAS Mapper profile/reference line
  • get_profile_line_peak_flow(hdf_path, line_name, mesh_name=None, profile_lines_path=None, direction="absolute") - Peak Q and peak time for a profile/reference line

Plan Results

HdfResultsPlan

Plan-level results.

  • get_runtime_data(hdf_path) - Runtime statistics
  • get_volume_accounting(hdf_path) - Volume accounting data
  • get_compute_messages(hdf_path) - Computation messages
  • get_compute_options(hdf_path) - Computation options used
  • is_steady_plan(hdf_path) - Check if steady state
  • get_steady_profile_names(hdf_path) - Get steady profile names
  • get_steady_wse(hdf_path) - Get steady water surface elevations
  • get_steady_info(hdf_path) - Get steady flow metadata

HdfResultsXsec

1D cross-section results.

  • get_xsec_timeseries(hdf_path) - All cross-section time series
  • get_xsec_summary(hdf_path) - Cross-section summary data

1D Geometry

HdfXsec

Cross-section and river geometry extraction from HDF.

  • get_cross_sections(hdf_path) - Extract cross-section geometries as GeoDataFrame
  • get_river_centerlines(hdf_path) - Extract river centerlines
  • get_river_stationing(hdf_path) - Calculate river stationing along centerlines
  • get_river_reaches(hdf_path) - Return model 1D river reach lines
  • get_river_edge_lines(hdf_path) - Return river edge lines
  • get_river_bank_lines(hdf_path) - Extract river bank lines

Structure Data

HdfStruc

Structure geometry and SA/2D connections.

  • get_connection_list(hdf_path) - List SA/2D connections
  • get_connection_profile(hdf_path, name) - Get connection profile
  • get_connection_gates(hdf_path, name) - Get gate data

HdfResultsBreach

Dam breach results.

  • get_breach_timeseries(hdf_path, structure) - Breach time series
  • get_breach_summary(hdf_path, structure) - Breach summary statistics
  • get_breaching_variables(hdf_path, structure) - Breach geometry evolution
  • get_structure_variables(hdf_path, structure) - Structure flow variables

HdfStorageArea

Storage area volume-elevation curve extraction from HDF.

  • get_volume_elevation_curve(hdf_path, sa_name) - Get volume-elevation curve for a storage area
  • get_storage_area_names(hdf_path) - List storage areas in HDF

HdfChannelCapacity

1D channel capacity analysis (multi-AEP).

  • get_channel_capacity(hdf_path, river=None, reach=None) - Compute channel capacity from cross-section geometry and results
  • get_multi_aep_capacity(hdf_paths, aep_labels) - Compare capacity across multiple AEP simulations

HdfStruc1D

1D structure result extraction from plan HDF results.

  • get_structure_max_values(hdf_path, river, reach, rs) - Extract maximum headwater, tailwater, and flow for a bridge, culvert, inline weir, or inline control structure. Raises an actionable ValueError when the plan HDF has no steady/unsteady results, required cross-section result datasets are absent, or the requested structure is not present in the results.
  • list_1d_structures(hdf_path) - List 1D structures identified from result markers. Returns an empty DataFrame quietly when no structures are present in an otherwise readable HDF.

For steady plans, get_structure_max_values() can use the flanking cross sections when the structure is represented in HDF Node Info instead of Cross Section Attributes. The returned hw_source, tw_source, and flow_source fields identify the result locations used.

HdfHydraulicTables

Cross section property tables (HTAB).

  • get_xs_htab(hdf_path, river, reach, station) - Get HTAB data

Infrastructure

HdfPipe

Pipe network analysis.

  • get_pipe_conduits(hdf_path) - Get conduit geometry
  • get_pipe_nodes(hdf_path) - Get node locations
  • get_pipe_network_timeseries(hdf_path, var) - Network time series
  • get_pipe_network_summary(hdf_path) - Network summary
  • get_pipe_profile(hdf_path, conduit_id) - Get conduit profile

HdfPump

Pump station analysis.

  • get_pump_stations(hdf_path) - Get station locations
  • get_pump_groups(hdf_path) - Get pump groups
  • get_pump_station_timeseries(hdf_path, name) - Station time series
  • get_pump_station_summary(hdf_path) - Station summary
  • get_pump_operation_timeseries(hdf_path, name) - Operation history

Analysis

HdfFluvialPluvial

Fluvial-pluvial boundary analysis.

  • calculate_fluvial_pluvial_boundary(hdf_path, delta_t) - Calculate boundary

HdfInfiltration

Native infiltration authoring and read-only inspection.

Geometry File Operations:

  • get_preprocessed_infiltration(hdf_path, mesh_name=None, variable=...) - Read solver-owned per-cell infiltration arrays
  • get_infiltration_baseoverrides(hdf_path) - Retrieve the geometry-wide class-to-parameter fallback table
  • get_infiltration_calibration_regions(hdf_path) - Read every region table in the bulk variable-oriented HDF view
  • get_infiltration_region_overrides(hdf_path, region_name=..., hecras_version=...) - Read one selected region in the class-ordered native view
  • get_infiltration_region_names(hdf_path) - Read stable region names
  • get_infiltration_region_polygons(hdf_path) - Read stable region IDs, names, and polygon geometry
  • create_infiltration_override_regions(hdf_path, region_names, hecras_version=...) - Create native geometry override regions from existing Manning-region polygons
  • set_infiltration_base_overrides(hdf_path, data, hecras_version=...) - Set the native geometry-wide Base Overrides fallback
  • scale_infiltration_base_overrides(hdf_path, data, scale_factors, hecras_version=...) - Scale active geometry-wide Base Overrides while preserving sentinel values
  • set_infiltration_region_overrides(hdf_path, data, region_name=..., hecras_version=...) - Set one native region's parameter table without changing Base Overrides or other regions
  • scale_infiltration_region_overrides(hdf_path, data, scale_factors, region_name=..., hecras_version=...) - Scale one selected region while preserving sentinel values

Raster and Layer Operations:

  • get_infiltration_layer_data(hdf_path) - Get infiltration layer data from HDF
  • set_infiltration_sidecar_parameters(hdf_path, data, hecras_version=...) - Set sidecar parameters through native RASMapper serialization
  • scale_infiltration_sidecar_parameters(hdf_path, data, scale_factors, hecras_version=...) - Scale and save sidecar parameters natively
  • get_classification_polygons(hdf_path) - Read infiltration sidecar classification polygon overrides
  • get_infiltration_map(hdf_path) - Read infiltration raster map
  • calculate_soil_statistics(hdf_path) - Process zonal statistics for soil analysis

The compatibility names create_infiltration_group(), set_infiltration_baseoverrides(), set_infiltration_layer_data(), and scale_infiltration_baseoverrides() delegate to the canonical native APIs through the v1.1.x compatibility window. The historical scale_infiltration_data() name was ambiguous between a geometry HDF and an infiltration sidecar and now fails closed with three explicit choices: the geometry-wide, selected-region, or sidecar scaler. These compatibility names will not be removed before v1.2.0. Ras Commander never hand-authors or selectively deletes /Geometry/Infiltration datasets.

Soil Analysis:

  • get_significant_mukeys(hdf_path, threshold) - Identify mukeys above percentage threshold
  • calculate_total_significant_percentage(hdf_path) - Compute total coverage
  • get_infiltration_parameters(hdf_path, mukey) - Get parameters for specific mukey
  • calculate_weighted_parameters(hdf_path) - Compute weighted average parameters

Data Export:

  • save_statistics(data, path) - Export soil statistics to CSV

HdfLandCover

Land-cover sidecar and final Manning's n extraction.

  • get_landcover_raster_map(hdf_path) - Read land-cover class IDs, names, and Manning's n values
  • set_landcover_mannings_n(hdf_path, mapping, hecras_version=...) - Set sidecar Manning's n through native RASMapper serialization
  • get_classification_polygons(hdf_path) - Read land-cover sidecar classification polygon overrides
  • get_preprocessed_mannings_n(hdf_path) - Read preprocessed cell-center Manning's n values from geometry HDF
  • audit_final_mannings_n(hdf_path, ...) - Strictly audit solver-owned final cell/face Manning arrays
  • estimate_final_mannings_raster(hdf_path, ...) - Build a non-authoritative visualization estimate

Compatibility mappings are retained through v1.1.x and will not be removed before v1.2.0:

Compatibility name Canonical replacement
set_landcover_raster_map() set_landcover_mannings_n()
compute_final_mannings_raster() estimate_final_mannings_raster() for visualization, or audit_final_mannings_n() for solver evidence

HdfBndry

Boundary condition geometry.

  • get_bc_lines(hdf_path) - Get BC lines
  • get_breaklines(hdf_path) - Get breaklines

Utilities

HdfUtils

Utility class for HDF file operations.

Data Conversion:

  • convert_ras_string(value) - Convert RAS HDF strings to Python objects
  • convert_ras_hdf_value(value) - Convert general HDF values to Python objects
  • convert_df_datetimes_to_str(df) - Convert DataFrame datetime columns to strings
  • convert_hdf5_attrs_to_dict(attrs) - Convert HDF5 attributes to dictionary
  • convert_timesteps_to_datetimes(timesteps) - Convert timesteps to datetime objects

Spatial Operations:

  • perform_kdtree_query(source, target) - KDTree search between datasets
  • find_nearest_neighbors(data, k) - Find nearest neighbors within dataset

DateTime Parsing:

  • parse_ras_datetime(datetime_str) - Parse RAS datetime (ddMMMYYYY HH:MM:SS)
  • parse_ras_window_datetime(datetime_str) - Parse simulation window datetime
  • parse_duration(duration_str) - Parse duration strings (HH:MM:SS)
  • parse_ras_datetime_ms(datetime_bytes) - Parse datetime with milliseconds
  • parse_run_time_window(window_str) - Parse time window strings

Visualization

HdfPlot & HdfResultsPlot

Basic plotting utilities.

  • plot_results_max_wsel(gdf) - Plot maximum WSE map

Usage Example

Python
from ras_commander import HdfResultsMesh, HdfResultsPlan, init_ras_project

init_ras_project("/path/to/project", "6.5")

# Get HDF path
hdf_path = ras.plan_df.loc[ras.plan_df['plan_number'] == '01', 'hdf_path'].iloc[0]

# Extract max WSE
max_wse = HdfResultsMesh.get_mesh_max_ws(hdf_path)

# Get runtime stats
runtime = HdfResultsPlan.get_runtime_data(hdf_path)
CLB Engineering Corporation  ·  LLM Forward Engineering
RAS Commander Documentation is a free and open-source project maintained by CLB Engineering Corporation. For agencies and firms modernizing H&H workflows with LLM Forward approaches, contact CLB to partner with the engineers who wrote the automation.