steady_plan¶

SteadyPlan - read HEC-RAS steady-flow plan HDF5 files (.p*.hdf).

Steady plan HDF files embed the same Geometry/ group as geometry HDF files plus Results/Steady/... profile-based output.

SteadyPlan inherits Geometry so all geometry accessors are available. CrossSectionResults, StorageAreaResults, and LateralResults carry geometry attributes and steady-profile result arrays. All result arrays have shape (n_profiles,) (or (n_profiles, n_segments) for segment-level lateral data) where the first axis corresponds to a named steady-flow profile (e.g. "Big", "Bigger", "Biggest").

Bridge, culvert, and inline structure nodes in HEC-RAS 1D steady flow do not produce separate result datasets in the HDF file; their results are embedded in the adjacent upstream/downstream cross-section output. SteadyPlan therefore returns plain geometry objects (no result access) for those types. Only LateralResults carries dedicated result data.

Derived from examination of HEC-RAS 6.6 steady-flow plan HDF output at Results/Steady/Output/Output Blocks/Base Output/Steady Profiles/.

class rivia.hdf.steady_plan.ComputeSummary(run)[source]¶

Bases: object

Steady simulation summary for a plan HDF file.

Wraps the attributes stored under Results/Steady/Summary. Steady-flow runs do not produce volume-accounting output; only run metadata is available.

Variables:: run – Solution status and wall-clock run window.
Parameters:: run (RunStatus)

ok()[source]¶

Return True if the simulation finished successfully.

Logs a CRITICAL message when the solution string does not contain "successfully".

Return type:: bool

run: RunStatus¶

to_dict()[source]¶

Return a nested dict with short, meaningful keys.

Top-level key: "run".

Return type:: dict[str, Any]

class rivia.hdf.steady_plan.CrossSectionResults(geom, hdf, index, root)[source]¶

Bases: CrossSection

Geometry and steady-profile results for one 1-D cross section.

Inherits all geometry attributes from CrossSection.

All result properties return a numpy array of shape (n_profiles,) where each index corresponds to a named steady-flow profile. Use SteadyPlan.profile_names to map indices to profile names.

Parameters:

geom (CrossSection) – Geometry object from CrossSectionCollection.
hdf (File) – Open h5py.File — kept alive by the parent SteadyPlan context.
index (int) – Column index of this XS in the (n_profiles, n_xs) result datasets.
root (str) – HDF path prefix — _STEADY_XS.

additional_variable(name)[source]¶

Load one column from the Additional Variables sub-group.

Parameters:: name (str) – Dataset name inside Additional Variables/, e.g. "Flow Total", "Velocity Channel", "Conveyance Total".
Return type:: ndarray, shape (n_profiles,)
Raises:: KeyError – If name is not present in Additional Variables/.

property alpha: ndarray¶: Velocity-head correction factor α. Shape (n_profiles,).

property beta: ndarray¶: Momentum correction factor β. Shape (n_profiles,).

property conveyance_channel: ndarray¶: Channel conveyance. Shape (n_profiles,).

property conveyance_left_ob: ndarray¶: Left overbank conveyance. Shape (n_profiles,).

property conveyance_right_ob: ndarray¶: Right overbank conveyance. Shape (n_profiles,).

property conveyance_total: ndarray¶: Total conveyance. Shape (n_profiles,).

property critical_energy_grade: ndarray¶: Critical energy grade line elevation. Shape (n_profiles,).

property critical_water_surface: ndarray¶: Critical water surface elevation. Shape (n_profiles,).

property energy_grade: ndarray¶: Energy grade line elevation. Shape (n_profiles,).

property energy_grade_slope: ndarray¶: Energy grade slope (m/m or ft/ft). Shape (n_profiles,).

property flow: ndarray¶: Total flow. Shape (n_profiles,).

property flow_area_channel: ndarray¶: Channel flow area. Shape (n_profiles,).

property flow_area_left_ob: ndarray¶: Left overbank flow area. Shape (n_profiles,).

property flow_area_right_ob: ndarray¶: Right overbank flow area. Shape (n_profiles,).

property flow_area_total: ndarray¶: Total flow area. Shape (n_profiles,).

property flow_channel: ndarray¶: Channel flow. Shape (n_profiles,).

property flow_left_ob: ndarray¶: Left overbank flow. Shape (n_profiles,).

property flow_right_ob: ndarray¶: Right overbank flow. Shape (n_profiles,).

property flow_total: ndarray¶: Total flow. Shape (n_profiles,).

property friction_slope: ndarray¶: Friction slope. Shape (n_profiles,).

property hydraulic_depth_channel: ndarray¶: Channel hydraulic depth. Shape (n_profiles,).

property hydraulic_depth_left_ob: ndarray¶: Left overbank hydraulic depth. Shape (n_profiles,).

property hydraulic_depth_right_ob: ndarray¶: Right overbank hydraulic depth. Shape (n_profiles,).

property hydraulic_depth_total: ndarray¶: Total hydraulic depth. Shape (n_profiles,).

property hydraulic_radius_channel: ndarray¶: Channel hydraulic radius. Shape (n_profiles,).

property hydraulic_radius_left_ob: ndarray¶: Left overbank hydraulic radius. Shape (n_profiles,).

property hydraulic_radius_right_ob: ndarray¶: Right overbank hydraulic radius. Shape (n_profiles,).

property hydraulic_radius_total: ndarray¶: Total hydraulic radius. Shape (n_profiles,).

property ineffective_area_channel: ndarray¶: Channel area including ineffective zones. Shape (n_profiles,).

property ineffective_area_left_ob: ndarray¶: Left overbank area including ineffective zones. Shape (n_profiles,).

property ineffective_area_right_ob: ndarray¶: Right overbank area including ineffective zones. Shape (n_profiles,).

property ineffective_area_total: ndarray¶: Total area including ineffective zones. Shape (n_profiles,).

property mannings_n_channel: ndarray¶: Weighted/composite channel Manning’s n. Shape (n_profiles,).

property mannings_n_left_ob: ndarray¶: Left overbank Manning’s n. Shape (n_profiles,).

property mannings_n_right_ob: ndarray¶: Right overbank Manning’s n. Shape (n_profiles,).

property mannings_n_total: ndarray¶: Total weighted Manning’s n. Shape (n_profiles,).

property max_depth_total: ndarray¶: Total maximum water depth. Shape (n_profiles,).

property shear: ndarray¶: Bed shear stress. Shape (n_profiles,).

property top_width_channel: ndarray¶: Channel top width. Shape (n_profiles,).

property top_width_channel_with_ineffective: ndarray¶: Channel top width including ineffective areas. Shape (n_profiles,).

property top_width_left_ob: ndarray¶: Left overbank top width. Shape (n_profiles,).

property top_width_left_ob_with_ineffective: ndarray¶: Left overbank top width including ineffective areas. Shape (n_profiles,).

property top_width_right_ob: ndarray¶: Right overbank top width. Shape (n_profiles,).

property top_width_right_ob_with_ineffective: ndarray¶: Right overbank top width including ineffective areas. Shape (n_profiles,).

property top_width_total: ndarray¶: Total top width. Shape (n_profiles,).

property top_width_total_with_ineffective: ndarray¶: Total top width including ineffective areas. Shape (n_profiles,).

property velocity_channel: ndarray¶: Channel velocity. Shape (n_profiles,).

property velocity_left_ob: ndarray¶: Left overbank velocity. Shape (n_profiles,).

property velocity_right_ob: ndarray¶: Right overbank velocity. Shape (n_profiles,).

property velocity_total: ndarray¶: Total velocity. Shape (n_profiles,).

property wetted_perimeter_channel: ndarray¶: Channel wetted perimeter. Shape (n_profiles,).

property wetted_perimeter_left_ob: ndarray¶: Left overbank wetted perimeter. Shape (n_profiles,).

property wetted_perimeter_right_ob: ndarray¶: Right overbank wetted perimeter. Shape (n_profiles,).

property wetted_perimeter_total: ndarray¶: Total wetted perimeter. Shape (n_profiles,).

property wse: ndarray¶: Water surface elevation. Shape (n_profiles,).

property wse_total: ndarray¶

Total stage / water surface elevation from Additional Variables.

Sourced from Additional Variables/Water Surface Total. Equivalent to wse for most configurations. Shape (n_profiles,).

class rivia.hdf.steady_plan.CrossSectionResultsCollection(hdf)[source]¶

Bases: CrossSectionCollection

Steady-plan cross section collection with profile results.

Combines geometry from Geometry/Cross Sections with steady-flow result data from Results/Steady/Output/.... Each item is a CrossSectionResults instance.

Parameters:: hdf (File) – Open h5py.File handle.

property names: list[str]¶: Keys of all cross sections with steady results.

class rivia.hdf.steady_plan.LateralResults(geom, group)[source]¶

Bases: LateralStructure

Geometry and steady-profile results for one lateral structure.

Inherits all geometry attributes from LateralStructure.

All result properties return numpy arrays. Scalar results (one value per profile) have shape (n_profiles,). Segment-level results have shape (n_profiles, n_segments) or (n_segments,) for static arrays.

Note

Bridge, culvert, and inline structure nodes do not have separate result datasets in HEC-RAS 1D steady-flow HDF files. StructureCollection returns plain geometry objects for those types.

Parameters:

geom (LateralStructure) – Geometry object from StructureCollection.
group (Group) – h5py.Group at Results/Steady/.../Steady Profiles/Lateral Structures/<name>.

property flow_hw_ds: ndarray¶: Flow at the downstream bounding cross section. Shape (n_profiles,).

property flow_hw_us: ndarray¶: Flow at the upstream bounding cross section. Shape (n_profiles,).

property flow_total: ndarray¶: Total flow through the structure. Shape (n_profiles,).

property flow_weir: ndarray¶: Weir flow component. Shape (n_profiles,).

property segment_flow: ndarray¶

Flow through each HW-TW segment per profile.

Shape (n_profiles, n_segments).

property segment_headwater_rs: ndarray¶

Headwater reach station (RS) for each HW-TW segment.

Shape (n_segments,), dtype byte-string — decode with seg.astype(str) if needed.

property segment_stations: ndarray¶

Lateral structure chainage station for each HW-TW segment.

Shape (n_segments,).

property segment_wse_hw: ndarray¶

Headwater water-surface elevation at each segment per profile.

Shape (n_profiles, n_segments).

property segment_wse_tw: ndarray¶

Tailwater water-surface elevation at each segment per profile.

Shape (n_profiles, n_segments).

property stage_hw: ndarray¶: Headwater stage (weighted average along structure). Shape (n_profiles,).

property stage_hw_ds: ndarray¶: Stage at the downstream bounding cross section. Shape (n_profiles,).

property stage_hw_us: ndarray¶: Stage at the upstream bounding cross section. Shape (n_profiles,).

property stage_tw: ndarray¶: Tailwater stage. Shape (n_profiles,).

property structure_variables: ndarray¶

All structure variables. Shape (n_profiles, n_vars).

Column names are in variable_names.

property variable_names: list[str]¶

Column names from the Structure Variables Variable_Unit attribute.

Falls back to col_0, col_1, … when the attribute is absent.

property weir_variables: ndarray | None¶

Detailed weir hydraulics per HW-TW segment, or None if absent.

Shape (n_profiles, n_segments).

class rivia.hdf.steady_plan.RunStatus(solution, run_window)[source]¶

Bases: object

Run metadata from Results/Steady/Summary.

Variables:

solution – HEC-RAS solution status string, e.g. "Steady Finished Successfully".
run_window – Wall-clock window during which the simulation ran, e.g. "11APR2026 11:53:38 to 11APR2026 11:53:39".

Parameters:

solution (str)
run_window (str)

ok()[source]¶

Return True if the solution string indicates success.

Return type:: bool

parse_run_window()[source]¶

Parse run_window into (start, end) datetimes.

Splits the raw string on " to " and parses each half with the HEC-RAS timestamp format "%d%b%Y %H:%M:%S".

Returns:: (start, end) as timezone-naive datetime.datetime objects, or None when the string is missing, malformed, or cannot be parsed.
Return type:: tuple[datetime, datetime] or None

Examples

s = hdf.compute_summary()
window = s.run.parse_run_window()
if window:
    start, end = window
    print(end - start)   # wall-clock duration

run_window: str¶

solution: str¶

to_dict()[source]¶

Return a dict with short, meaningful keys.

Return type:: dict[str, str]

class rivia.hdf.steady_plan.SteadyPlan(filename)[source]¶

Bases: _PlanHdf, Geometry

Read HEC-RAS steady-flow plan HDF5 output files (*.p*.hdf).

A steady plan HDF file contains the same Geometry/ data as a geometry HDF file, plus Results/Steady/... profile-based output.

Results are indexed by steady-flow profile name (e.g. "Big", "Bigger", "Biggest"). Each result array has shape (n_profiles,) where each index corresponds to a profile.

Parameters:: filename (str | Path) – Path to the plan HDF file. The .hdf suffix is appended automatically if absent.

Examples

with SteadyPlan("Baxter.p01") as hdf:
    profiles = hdf.profile_names          # ["Big", "Bigger", "Biggest"]
    xs = hdf.cross_sections["Baxter River Lower Reach 27470."]
    wse = xs.wse                           # shape (3,)
    vel = xs.velocity_channel              # shape (3,)

    sa = hdf.storage_areas["Northside"]
    sa_wse = sa.wse                        # shape (3,)

compute_summary()[source]¶

Return the steady simulation summary.

Reads the Results/Steady/Summary group and returns a ComputeSummary dataclass with run metadata.

Steady-flow runs do not produce volume accounting; call ComputeSummary.ok() to check whether the solution finished successfully.

Return type:: ComputeSummary
Raises:: KeyError – If Results/Steady/Summary is absent from the HDF file.

Examples

with SteadyPlan("Baxter.p01") as hdf:
    s = hdf.compute_summary()
    print(s.run.solution)
    if s.ok():
        print("Run completed successfully")

property cross_sections: CrossSectionResultsCollection¶: 1-D cross sections with geometry and steady-profile results.

property profile_names: list[str]¶

Steady-flow profile names written by HEC-RAS.

Returns:: Ordered list of profile names, e.g. ["Big", "Bigger", "Biggest"]. The index of each name corresponds to the first axis of all result arrays.
Return type:: list[str]
Raises:: KeyError – If Results/Steady is absent — e.g. the plan has not been run or this is not a steady-flow plan.

property ras_version: str¶

HEC-RAS version string from the plan HDF root attribute.

Returns the File Version root attribute, e.g. 'HEC-RAS 6.6 September 2024'.

runtime_log()[source]¶

Read the runtime compute log from Results/Summary/.

Returns:: Log container with the full text/RTF compute messages and the compute-process table. Steady-specific parsing methods will be added to SteadyRuntimeLog as the library evolves.
Return type:: SteadyRuntimeLog
Raises:: KeyError – If Results/Summary is absent from the HDF file.

property storage_areas: StorageAreaResultsCollection¶: Storage areas with geometry and steady-profile results.

property structures: StructureResultsCollection¶

All structures with geometry and, where available, steady-profile results.

LateralStructure items are upgraded to LateralResults when result data is present. Bridge, culvert, and inline structure items are returned as plain geometry objects — HEC-RAS 1D steady-flow HDF files do not store separate result datasets for those node types.

class rivia.hdf.steady_plan.StorageAreaResults(sa, sa_index, sa_group)[source]¶

Bases: StorageArea

Geometry and steady-profile results for one storage area.

Inherits all geometry properties from StorageArea.

All result properties return a numpy array of shape (n_profiles,) where each index corresponds to a named steady-flow profile. Use SteadyPlan.profile_names to map indices to profile names.

Parameters:

sa (StorageArea) – Parent geometry object whose fields are copied into this instance.
sa_index (int) – 0-based column index of this SA in the (n_profiles, n_sa) datasets Water Surface and Flow stored under Results/Steady/.../Storage Areas.
sa_group (Group | None) – h5py.Group at Results/Steady/.../Steady Profiles/Storage Areas, or None when the plan has no storage-area results.

property connection_names: list[str]¶

Names of the inflow connection sources.

Falls back to index-based names if the attribute is absent.

property connections: ndarray | None¶

Flow from each named connection.

Shape (n_profiles, n_conns), or None when absent. Column names are in connection_names.

property flow: ndarray¶: Net flow. Shape (n_profiles,).

property wse: ndarray¶: Water-surface elevation. Shape (n_profiles,).

class rivia.hdf.steady_plan.StorageAreaResultsCollection(hdf)[source]¶

Bases: StorageAreaCollection

Collection of StorageAreaResults backed by a steady plan HDF.

Overrides StorageAreaCollection to return StorageAreaResults with both geometry and steady results.

Parameters:: hdf (h5py.File)

property names: list[str]¶: Names of all storage areas in the collection.

class rivia.hdf.steady_plan.StructureResultsCollection(hdf)[source]¶

Bases: StructureCollection

Steady-plan structure collection.

Upgrades LateralStructure geometry objects to LateralResults when a matching result group exists under Results/Steady/.../Steady Profiles/Lateral Structures.

All other structure types (Bridge, Culvert, Inline) are returned as plain geometry objects — HEC-RAS 1D steady-flow HDF files do not store separate result datasets for those node types.

Parameters:: hdf (h5py.File)