steady_flow

Read/write HEC-RAS steady flow files (.f**).

SteadyFlow — verbatim-line editor. All lines are stored verbatim; only the specific data blocks that are mutated are reformatted. save() is byte-faithful for every unmodified line.

File format notes:

• Flow data: each River Rch & RM=River,Reach,RS line is immediately followed by N flow values (one per profile) in 8-char fixed-width columns, up to 10 per row. No Num Of Flows= or Flow= prefix.

• Boundary conditions: one Boundary for River Rch & Prof#=River,Reach,N block per reach endpoint per profile. Up/Dn type codes:

  0 — None
  1 — Known WS        (``Up/Dn Known WS=<value>``)
  2 — Critical Depth  (no additional data)
  3 — Normal Depth    (``Up/Dn Slope=<value>``)
  4 — Rating Curve    (``Up/Dn Nval=<count>`` + interleaved stage/flow pairs)
  

Derived from format inspection of HEC-RAS 6.6 example files.

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.steady_flow.SteadyBoundary(river, reach, profile, up_type=0, dn_type=0, up_known_ws=None, dn_known_ws=None, up_slope=None, dn_slope=None, up_rating_curve=<factory>, dn_rating_curve=<factory>)

Bases: object

Boundary conditions for one river/reach endpoint for one flow profile.

up_type / dn_type encode the condition type:

0 — None           (no BC)
1 — Known WS       (``up_known_ws`` / ``dn_known_ws``)
2 — Critical Depth (no additional data required)
3 — Normal Depth   (``up_slope`` / ``dn_slope``)
4 — Rating Curve   (``up_rating_curve`` / ``dn_rating_curve``)

profile is 1-based and matches the profile index in the steady flow file (Boundary for River Rch & Prof#=..., 1).

Parameters:

• river (str)

• reach (str)

• profile (int)

• up_type (int)

• dn_type (int)

• up_known_ws (float | None)

• dn_known_ws (float | None)

• up_slope (float | None)

• dn_slope (float | None)

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

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

dn_known_ws: float | None = None

dn_rating_curve: list[tuple[float, float]]

dn_slope: float | None = None

dn_type: int = 0

profile: int

reach: str

river: str

up_known_ws: float | None = None

up_rating_curve: list[tuple[float, float]]

up_slope: float | None = None

up_type: int = 0

class rivia.model.steady_flow.SteadyFlow(path)

Bases: object

Verbatim-line editor for HEC-RAS steady flow files (.f**).

All lines are loaded into memory verbatim. Targeted edits (e.g. replacing flow values at a cross-section or updating a boundary condition) splice new formatted lines into the list while leaving every other line byte-identical. save() writes the list back; a no-op parse+save produces an identical file.

Flow data is accessed by river / reach / river-station string (get_flows / set_flows). Boundary conditions are accessed by river / reach / 1-based profile number (get_boundary / set_boundary).

Derived from format inspection of HEC-RAS 6.6 example files.

Parameters:

path (str | Path)

property flow_title: str | None

Flow title (Flow Title=).

get(key)

Return the raw stripped value for key, or None if absent.

Return type:

str | None

Parameters:

key (str)

get_boundaries(river, reach)

Return all boundary conditions for a river/reach, sorted by profile.

Returns an empty list if no matching boundaries are found.

Return type:

list[SteadyBoundary]

Parameters:

• river (str)

• reach (str)

get_boundary(river, reach, profile)

Return the boundary conditions for the given reach endpoint and profile.

Returns None if no matching Boundary for River Rch & Prof# line is found.

Return type:

SteadyBoundary | None

Parameters:

• river (str)

• reach (str)

• profile (int)

get_flows(river, reach, rs)

Return flow values (one per profile) at the given location.

Returns None if no matching River Rch & RM line is found. Returns [] if the location exists but contains no parseable values.

Return type:

list[float] | None

Parameters:

• river (str)

• reach (str)

• rs (str)

property n_profiles: int | None

Number of flow profiles (Number of Profiles=).

property profile_names: list[str]

Profile names from the header Profile Names= line, stripped.

Returns an empty list if the key is absent.

property program_version: str | None

HEC-RAS version string.

Checks Program Version= first (modern format), then falls back to Version= (pre-v4 files such as older WAILUPE-style projects). Treat as read-only; HEC-RAS manages this field.

save(path=None)

Write all in-memory lines back to disk.

If path is omitted the source file is overwritten.

Return type:

None

Parameters:

path (str | Path | None)

set(key, value)

Set key to value verbatim. Raises KeyError if absent.

Return type:

None

Parameters:

• key (str)

• value (str)

set_boundary(boundary)

Replace the boundary conditions at the given location.

The entire boundary block (from Boundary for River Rch & Prof#= through its fields) is rebuilt from boundary. Fields irrelevant to the set type are omitted (e.g. Dn Slope= is not written when dn_type != 3).

Raises:

KeyError – No matching Boundary for River Rch & Prof# line found.

Return type:

None

Parameters:

boundary (SteadyBoundary)

set_flows(river, reach, rs, values)

Replace the flow values at the given location.

The number of values in values need not match the current count; the data lines are replaced wholesale.

Parameters:

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

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

• rs (str) – River station string (stripped comparison).

• values (list[float]) – New flow values, one per profile.

Raises:

KeyError – No matching River Rch & RM line found.

Return type:

None