unsteady_flow

Read/write HEC-RAS unsteady flow files (.u**).

UnsteadyFlow — structured editor. Boundary conditions are parsed into typed dataclass objects and may be sorted by river station. save() reconstructs the boundary section from the objects; trailing meteorological / non-Newtonian lines are still written verbatim.

Convention

get_* methods return None when the requested item is not found. set_* methods raise KeyError when the target does not exist.

class rivia.model.unsteady_flow.FlowHydrograph(river, reach, river_station, _location_tail='', interval='1HOUR', values=<factory>, flow_hydrograph_slope=None, stage_tw_check=0, dss_file='', dss_path='', use_dss=False, use_fixed_start=False, fixed_start=', ', is_critical=False, critical_boundary_flow='', _extra_lines=<factory>)

Bases: _Boundary

Upstream / internal flow hydrograph boundary.

Parameters:

• river (str)

• reach (str)

• river_station (str)

• _location_tail (str)

• interval (str)

• values (list[float])

• flow_hydrograph_slope (str | None)

• stage_tw_check (int)

• dss_file (str)

• dss_path (str)

• use_dss (bool)

• use_fixed_start (bool)

• fixed_start (str)

• is_critical (bool)

• critical_boundary_flow (str)

• _extra_lines (list[str])

critical_boundary_flow: str = ''

dss_file: str = ''

dss_path: str = ''

fixed_start: str = ','

flow_hydrograph_slope: str | None = None

interval: str = '1HOUR'

is_critical: bool = False

stage_tw_check: int = 0

use_dss: bool = False

use_fixed_start: bool = False

values: list[float]

property window: tuple[datetime, datetime] | None

Return (start, end) as Python datetimes, or None.

None is returned when use_fixed_start is False. The end date is start + len(values) * parse_interval(interval).

class rivia.model.unsteady_flow.FrictionSlope(river, reach, river_station, _location_tail='', slope=0.0, value2=0.0)

Bases: _Boundary

Normal-depth (friction slope) downstream boundary.

Parameters:

• river (str)

• reach (str)

• river_station (str)

• _location_tail (str)

• slope (float)

• value2 (float)

slope: float = 0.0

value2: float = 0.0

class rivia.model.unsteady_flow.GateBoundary(river, reach, river_station, _location_tail='', gates=<factory>)

Bases: _Boundary

Inline structure with one or more gated openings.

Parameters:

• river (str)

• reach (str)

• river_station (str)

• _location_tail (str)

• gates (list[GateOpening])

gates: list[GateOpening]

class rivia.model.unsteady_flow.GateOpening(gate_name='', dss_path='', use_dss=False, time_interval='1HOUR', use_fixed_start=False, fixed_start=', ', values=<factory>)

Bases: object

Time series of openings for one gate.

Parameters:

• gate_name (str)

• dss_path (str)

• use_dss (bool)

• time_interval (str)

• use_fixed_start (bool)

• fixed_start (str)

• values (list[float])

dss_path: str = ''

fixed_start: str = ','

gate_name: str = ''

time_interval: str = '1HOUR'

use_dss: bool = False

use_fixed_start: bool = False

values: list[float]

class rivia.model.unsteady_flow.InitialFlowLoc(river, reach, river_station, flow)

Bases: object

Initial flow at a river / reach / station.

Parameters:

• river (str)

• reach (str)

• river_station (str)

• flow (float)

flow: float

reach: str

river: str

river_station: str

class rivia.model.unsteady_flow.InitialRainfallRunoffElev(river, reach, river_station, elevation)

Bases: object

Initial water surface elevation for a reservoir / RRR.

Parameters:

• river (str)

• reach (str)

• river_station (str)

• elevation (float)

elevation: float

reach: str

river: str

river_station: str

class rivia.model.unsteady_flow.InitialStorageElev(name, elevation)

Bases: object

Initial water surface elevation for a storage area.

Parameters:

• name (str)

• elevation (float)

elevation: float

name: str

class rivia.model.unsteady_flow.LateralInflow(river, reach, river_station, _location_tail='', interval='1HOUR', values=<factory>, is_uniform=False, dss_file='', dss_path='', use_dss=False, use_fixed_start=False, fixed_start=', ', is_critical=False, critical_boundary_flow='', _extra_lines=<factory>)

Bases: _Boundary

Lateral or uniform lateral inflow hydrograph.

Parameters:

• river (str)

• reach (str)

• river_station (str)

• _location_tail (str)

• interval (str)

• values (list[float])

• is_uniform (bool)

• dss_file (str)

• dss_path (str)

• use_dss (bool)

• use_fixed_start (bool)

• fixed_start (str)

• is_critical (bool)

• critical_boundary_flow (str)

• _extra_lines (list[str])

critical_boundary_flow: str = ''

dss_file: str = ''

dss_path: str = ''

fixed_start: str = ','

interval: str = '1HOUR'

is_critical: bool = False

is_uniform: bool = False

use_dss: bool = False

use_fixed_start: bool = False

values: list[float]

property window: tuple[datetime, datetime] | None

Return (start, end) as Python datetimes, or None.

None is returned when use_fixed_start is False. The end date is start + len(values) * parse_interval(interval).

class rivia.model.unsteady_flow.NormalDepth(river, reach, river_station, _location_tail='', slope=0.0)

Bases: _Boundary

Normal-depth boundary specified as a single slope value.

Parameters:

• river (str)

• reach (str)

• river_station (str)

• _location_tail (str)

• slope (float)

slope: float = 0.0

class rivia.model.unsteady_flow.RatingCurve(river, reach, river_station, _location_tail='', pairs=<factory>, dss_path='', use_dss=False, use_fixed_start=False, fixed_start=', ', is_critical=False, critical_boundary_flow='', _extra_lines=<factory>)

Bases: _Boundary

Rating-curve downstream boundary.

Parameters:

• river (str)

• reach (str)

• river_station (str)

• _location_tail (str)

• pairs (list[tuple[float, float]])

• dss_path (str)

• use_dss (bool)

• use_fixed_start (bool)

• fixed_start (str)

• is_critical (bool)

• critical_boundary_flow (str)

• _extra_lines (list[str])

critical_boundary_flow: str = ''

dss_path: str = ''

fixed_start: str = ','

is_critical: bool = False

pairs: list[tuple[float, float]]

use_dss: bool = False

use_fixed_start: bool = False

class rivia.model.unsteady_flow.StageHydrograph(river, reach, river_station, _location_tail='', interval='1HOUR', values=<factory>, dss_path='', use_dss=False, use_fixed_start=False, fixed_start=', ', _extra_lines=<factory>)

Bases: _Boundary

Stage (water-surface) hydrograph boundary.

Parameters:

• river (str)

• reach (str)

• river_station (str)

• _location_tail (str)

• interval (str)

• values (list[float])

• dss_path (str)

• use_dss (bool)

• use_fixed_start (bool)

• fixed_start (str)

• _extra_lines (list[str])

dss_path: str = ''

fixed_start: str = ','

interval: str = '1HOUR'

use_dss: bool = False

use_fixed_start: bool = False

values: list[float]

property window: tuple[datetime, datetime] | None

Return (start, end) as Python datetimes, or None.

None is returned when use_fixed_start is False. The end date is start + len(values) * parse_interval(interval).

class rivia.model.unsteady_flow.UnsteadyFlow(path)

Bases: object

Structured editor for HEC-RAS unsteady flow files (.u**).

Boundary conditions are parsed into typed dataclass objects stored in boundaries. Boundaries may be sorted by river station (useful for workflows that address gates or lateral inflows by index).

save() reconstructs the boundary section from the objects; the header, initial conditions, and trailing meteorological / Non-Newtonian lines are preserved verbatim.

Note

save() is not byte-identical to the original when boundaries are reordered or values are changed, because the file is reconstructed from parsed objects — the file is reconstructed from parsed data.

Parameters:

path (str | Path)

property flow_hydrographs: list[FlowHydrograph]

All FlowHydrograph boundaries, in file order.

property flow_title: str | None

Flow file title (Flow Title=), or None if absent.

property friction_slopes: list[FrictionSlope]

All FrictionSlope boundaries, in file order.

property gate_boundaries: list[GateBoundary]

All GateBoundary boundaries, in file order.

get_flow_hydrograph(river, reach, rs)

Return flow hydrograph values for the given location, or None.

Return type:

list[float] | None

Parameters:

• river (str)

• reach (str)

• rs (str)

get_gate_openings(river, reach, rs, gate_name)

Return gate opening values for the given location and gate name, or None.

Return type:

list[float] | None

Parameters:

• river (str)

• reach (str)

• rs (str)

• gate_name (str)

get_initial_flow(river, reach, rs)

Return the initial flow at the given location, or None.

Return type:

float | None

Parameters:

• river (str)

• reach (str)

• rs (str)

get_lateral_inflow(river, reach, rs)

Return lateral inflow values for the given location, or None.

Return type:

list[float] | None

Parameters:

• river (str)

• reach (str)

• rs (str)

property is_modified: bool

True if any value has been changed since the last save().

property lateral_inflows: list[LateralInflow]

All LateralInflow boundaries, in file order.

property program_version: str | None

HEC-RAS version string (Program Version=), or None if absent.

property restart: tuple[int, str | None]

Return (flag, filename) for the restart configuration.

flag is the Use Restart value (0 = disabled, 1 = enabled). filename is the Restart Filename value, or None if absent.

save(path=None)

Reconstruct and write the unsteady flow file.

The file is built as: 1. Header lines (verbatim from parse) 2. Initial condition lines (reconstructed from objects) 3. Boundary section (reconstructed from boundaries) 4. Trailing lines (verbatim from parse)

Parameters:

path (str | Path | None) – Destination path. Overwrites the source file if omitted.

Return type:

None

set_all_gate_openings(values)

Set gate opening values across all gates in all GateBoundary.

Parameters:

values (list[float | list[float]]) – One entry per gate (in order across all boundaries). Each entry is either a scalar float (broadcast to the gate’s existing time-series length) or a list[float] (used as-is). If values is shorter than the total number of gates, the remaining gates are left unchanged.

Return type:

None

set_all_lateral_inflows(values)

Set lateral inflow values across all LateralInflow boundaries.

Parameters:

values (list[float | list[float]]) – One entry per lateral inflow (in file order). Each entry is either a scalar float (broadcast to the boundary’s existing time-series length) or a list[float] (used as-is). If values is shorter than the total number of lateral inflows, the remaining boundaries are left unchanged.

Return type:

None

set_flow_hydrograph(index, values)

Set flow hydrograph values by position in flow_hydrographs.

Parameters:

• index (int) – Position in the filtered flow-hydrograph list.

• values (list[float | int] | float | int) – New flow values. A scalar is broadcast to the length of the existing time series.

Return type:

None

set_flow_hydrograph_at(river, reach, rs, values)

Set flow hydrograph values by location.

Parameters:

• values (list[float | int] | float | int) – A scalar is broadcast to the existing time-series length.

• river (str)

• reach (str)

• rs (str)

Return type:

None

set_gate_opening(index, values, gate_index=0)

Set gate opening values by position in gate_boundaries.

Parameters:

• index (int) – Position in the filtered gate-boundary list.

• values (list[float | int] | float | int) – New opening values. A scalar is broadcast to the length of the existing gate opening time series.

• gate_index (int) – Which gate within the boundary (default 0).

Return type:

None

set_gate_opening_at(river, reach, rs, gate, values)

Set gate opening values by location and gate name or index.

Parameters:

• gate (str | int) – Gate name string, or a zero-based integer index into the boundary’s gate list.

• values (list[float | int] | float | int) – A scalar is broadcast to the existing time-series length.

• river (str)

• reach (str)

• rs (str)

Return type:

None

set_initial_flow(index, flow)

Update the initial flow at index in initial_flow_locs.

Parameters:

• index (int) – Zero-based position in initial_flow_locs.

• flow (float) – New flow value.

Raises:

IndexError – index is out of range.

Return type:

None

set_initial_flow_at(river, reach, rs, flow)

Update the initial flow at the given location.

Parameters:

• river (str) – River name (case-insensitive match).

• reach (str) – Reach name (case-insensitive match).

• rs (str) – River station string.

• flow (float) – New flow value.

Raises:

KeyError – No matching Initial Flow Loc entry found.

Return type:

None

set_lateral_inflow(index, values)

Set lateral inflow values by position in lateral_inflows.

Parameters:

• values (list[float | int] | float | int) – New flow values. A scalar is broadcast to the length of the existing time series.

• index (int)

Return type:

None

set_lateral_inflow_at(river, reach, rs, values)

Set lateral inflow values by location.

Parameters:

• values (list[float | int] | float | int) – A scalar is broadcast to the existing time-series length.

• river (str)

• reach (str)

• rs (str)

Return type:

None

sort_flow_hydrographs(*, descending=True)

Sort FlowHydrograph entries by river station.

Parameters:

descending (bool) – If True (default), highest station first (upstream → downstream for standard RAS numbering). Pass False for ascending order (lowest station first).

Return type:

None

sort_gate_boundaries(*, descending=True)

Sort GateBoundary entries by river station.

Other boundary types remain at their original positions.

Parameters:

descending (bool) – If True (default), highest station first (upstream → downstream for standard RAS numbering). Pass False for ascending order (lowest station first).

Return type:

None

sort_lateral_inflows(*, descending=True)

Sort LateralInflow entries by river station.

Parameters:

descending (bool) – If True (default), highest station first (upstream → downstream for standard RAS numbering). Pass False for ascending order (lowest station first).

Return type:

None

property write_ic_file: bool | None

Whether to write an initial conditions file at the end of simulation.

Returns True if Write IC File at Sim End=-1, False if 0, or None if the key is absent (older files).