geometry

Read/write HEC-RAS geometry files (.g**).

Geometry — verbatim-line editor for HEC-RAS 1-D geometry files (.g01, .g02, …). All lines are stored verbatim. Typed access is provided for:

  • File metadata (title, program_version, viewing_rectangle)

  • Reach / node inventory (reaches, junctions, node_rs_list)

  • Cross-section data: #Sta/Elev, #Mann, Bank Sta, #XS Ineff, Exp/Cntr, Levee, #Block Obstruct, XS HTab Starting El and Incr (read via get_cross_section(), write via targeted setters)

  • Structure nodes (bridge, culvert, inline/lateral structure) preserved verbatim and accessible via get_node_lines()

save() is byte-faithful for every unmodified line.

Node type codes in Type RM Length L Ch R = TYPE, ...:

1 — Cross Section
2 — Culvert (single or twin-pipe)
3 — Bridge
4 — Multiple Opening
5 — Inline Structure
6 — Lateral Structure

Cross-section fixed-width format (8-char columns):

#Sta/Elev= N          alternating station/elevation pairs, 10 per row
#Mann= N,t,a          triplets (station, n-value, variation), 9 per row
#XS Ineff= N          triplets (x_start, x_end, elevation),  9 per row
                      followed by Permanent Ineff= flags (8-char, 10/row)
#Block Obstruct= N,t  triplets (x_start, x_end, elevation),  9 per row
Levee=lf,ls,le,rf,rs,re[,lfe,rfe]
                      left/right flag(-1=active), station, elevation,
                      optional failure elevations
XS HTab Starting El and Incr=el,incr,count

Vertical (depth/flow-varying) Manning’s n — appears between XS Rating Curve= and Exp/Cntr= when active:

Vertical n Elevations= N    N WSE or flow breakpoints (8-char cols, 10/row)
Vertical n for Station=S    per-station entry; N n-values follow (8-char, 10/row)
...
Vertical n Flow= F          F=0 → WSE breakpoints; F=-1 → flow breakpoints

When vertical n is active, #Mann= N , 0 , 0 stores zone boundary stations only; n-values in that block are all zero (placeholders).

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.geometry.BlockedObstruction(x_start, x_end, elevation)[source]

Bases: object

One blocked-obstruction interval in a cross section (#Block Obstruct).

Flow area between x_start and x_end is blocked up to elevation. Use a very large elevation (e.g. 999) for a permanently blocked zone.

Variables:

  • x_start – Left boundary station.

  • x_end – Right boundary station.

  • elevation – Elevation ceiling of the blocked zone.

Parameters:
elevation: float
x_end: float
x_start: float
class rivia.model.geometry.Bridge(mode, upstream_type, downstream_type, centerline=<factory>, location=('', '', ''), upstream_node=('', '', ''), downstream_node=('', '', ''), weir=None, gate_groups=<factory>, description='', roadway=None, culvert_groups=<factory>, piers=<factory>, node_name='', htab_hw_max=None, htab_tw_max=None, htab_max_flow=None)[source]

Bases: Structure

Bridge or culvert (node types 3 / 2) parsed from a .g** text geometry file.

Mirrors rivia.hdf.geometry.Bridge. Inherits mode, upstream_type, downstream_type, and centerline from Structure.

Differences vs the HDF version:

  • weir: populated from the Deck Dist data line scalar fields (width, coefficient, skew, max_submergence, shape); us_slope, ds_slope, and use_water_surface are always nan / False — not stored in the text format. Redundant with roadway scalars.

  • roadway: full deck geometry including upstream/downstream station, high-chord, and low-chord arrays; None when no Deck Dist line is present.

  • culvert_groups: barrel definitions from Culvert= lines.

  • piers: pier groups from Pier Skew, ... blocks.

  • gate_groups: always [] — bridge/culvert format uses Bridge Culvert hydraulics, not IW Gate Name blocks.

  • description: text-file-specific field from BEGIN/END DESCRIPTION; no equivalent in HDF.

Variables:

  • location – (river, reach, rs) of this structure.

  • upstream_node – (river, reach, rs) of the nearest upstream XS; ("", "", "") when none found.

  • downstream_node – (river, reach, rs) of the nearest downstream XS; ("", "", "") when none found.

  • weir – Overflow weir scalars from the Deck Dist line; None if the line is absent.

  • gate_groups – Always [].

  • description – Node description from BEGIN/END DESCRIPTION.

  • roadway – Full deck geometry (stations, hi/lo chords) from the Deck Dist block; None when absent.

  • culvert_groups – Barrel definitions from Culvert= lines.

  • piers – Pier groups from Pier Skew, ... blocks.

  • node_name – Node name from Node Name=; empty string when absent.

  • htab_hw_max – Max headwater elevation from BC HTab HWMax=; None when absent.

  • htab_tw_max – Max tailwater elevation from BC HTab TWMax=; None when absent.

  • htab_max_flow – Max flow from BC HTab MaxFlow=; None when absent.

Parameters:
culvert_groups: list[CulvertGroup]
description: str = ''
downstream_node: tuple[str, str, str] = ('', '', '')
gate_groups: list[GateGroup]
htab_hw_max: float | None = None
htab_max_flow: float | None = None
htab_tw_max: float | None = None
location: tuple[str, str, str] = ('', '', '')
node_name: str = ''
piers: list[Pier]
roadway: Roadway | None = None
upstream_node: tuple[str, str, str] = ('', '', '')
weir: Weir | None = None
class rivia.model.geometry.CrossSection(river, reach, rs, description='', stations=<factory>, elevations=<factory>, mann_entries=<factory>, mann_type=0, mann_alt=0, bank_left=None, bank_right=None, ineff_areas=<factory>, expansion=0.3, contraction=0.1, left_length=None, channel_length=None, right_length=None, interpolated=False, vertical_n=None, levee_left=None, levee_right=None, blocked_obstructions=<factory>, htab_starting_elevation=None, htab_increment=None, htab_count=None)[source]

Bases: object

Parsed data for one HEC-RAS cross section (node type 1).

Returned by Geometry.get_cross_section(). Write changes back with the targeted setters on Geometry (set_mannings, set_stations, set_bank_stations, set_exp_cntr).

Variables:

  • river – River name.

  • reach – Reach name.

  • rs – River station string (normalised: no trailing whitespace or * interpolation marker).

  • description – Node description from BEGIN/END DESCRIPTION.

  • stations – Station values from #Sta/Elev.

  • elevations – Elevation values from #Sta/Elev.

  • mann_entries – Manning’s n zones from #Mann.

  • mann_type – Type flag from #Mann= N , type , alt header.

  • mann_alt – Alt flag from #Mann= N , type , alt header.

  • bank_left – Left bank station (Bank Sta).

  • bank_right – Right bank station (Bank Sta).

  • ineff_areas – Ineffective flow areas (#XS Ineff).

  • expansion – Expansion loss coefficient (Exp/Cntr).

  • contraction – Contraction loss coefficient (Exp/Cntr).

  • left_length – Left overbank reach length from node header.

  • channel_length – Channel reach length from node header.

  • right_length – Right overbank reach length from node header.

  • interpolated – True if the RS string had a trailing * (HEC-RAS interpolated cross section).

  • vertical_n – Vertical (depth/flow-varying) Manning’s n, or None if the cross section uses flat n-values.

  • levee_left – Left-bank levee (Levee= line), or None.

  • levee_right – Right-bank levee (Levee= line), or None.

  • blocked_obstructions – Blocked-obstruction intervals (#Block Obstruct).

  • htab_starting_elevation – Starting elevation for the hydraulic table (XS HTab Starting El and Incr).

  • htab_increment – Elevation increment for the hydraulic table.

  • htab_count – Number of entries in the hydraulic table.

Parameters:
bank_left: float | None = None
bank_right: float | None = None
blocked_obstructions: list[BlockedObstruction]
channel_length: float | None = None
contraction: float = 0.1
description: str = ''
elevations: list[float]
expansion: float = 0.3
htab_count: int | None = None
htab_increment: float | None = None
htab_starting_elevation: float | None = None
ineff_areas: list[IneffArea]
interpolated: bool = False
left_length: float | None = None
levee_left: LeveeData | None = None
levee_right: LeveeData | None = None
mann_alt: int = 0
mann_entries: list[ManningEntry]
mann_type: int = 0
reach: str
right_length: float | None = None
river: str
rs: str
stations: list[float]
vertical_n: VerticalN | None = None
class rivia.model.geometry.CulvertGroup(name, shape_code, shape_name, span, rise, length, n_top, entrance_loss, exit_loss, inlet_type, outlet_type, upstream_invert, upstream_station, downstream_invert, downstream_station, chart_number, num_barrels=1, n_bottom=None, depth_n_bottom=None)[source]

Bases: object

One culvert barrel definition from a Culvert= line.

Field order matches the comma-separated data on the Culvert= line:

shape, span, rise, length, n, Ke, exit_loss, inlet_type, outlet_type,
us_invert, us_station, ds_invert, ds_station, name, ?, chart_number
Variables:

  • name – Culvert identifier (index 13), e.g. 'Culvert # 1'.

  • shape_code – Shape code (index 0) — see _CULVERT_SHAPES.

  • shape_name – Human-readable shape, e.g. 'Circular', 'Box'.

  • span – Width or diameter (index 1).

  • rise – Height (index 2); 0.0 when blank.

  • length – Barrel length (index 3).

  • n_top – Manning’s roughness coefficient (index 4).

  • entrance_loss – Entrance loss coefficient Ke (index 5).

  • exit_loss – Exit loss coefficient (index 6).

  • inlet_type – Inlet control type code (index 7).

  • outlet_type – Outlet control type code (index 8).

  • upstream_invert – Upstream invert elevation (index 9).

  • upstream_station – Upstream station location (index 10).

  • downstream_invert – Downstream invert elevation (index 11).

  • downstream_station – Downstream station location (index 12).

  • chart_number – Inlet control chart number (index 15).

  • num_barrels – Number of barrels — from BC Culvert Barrel= line; 1 when that line is absent.

  • n_bottom – Bottom Manning’s n — from Culvert Bottom n=; None when absent.

  • depth_n_bottom – Bottom fill depth — from Culvert Bottom Depth=; None when absent.

  • TODO (..) – (no us_station / ds_station columns; barrel stations appear on the next line as num_barrels upstream + num_barrels downstream values in 8-char fixed-width columns). These station values are currently not parsed.

Parameters:
chart_number: int
depth_n_bottom: float | None = None
downstream_invert: float
downstream_station: float
entrance_loss: float
exit_loss: float
inlet_type: int
length: float
n_bottom: float | None = None
n_top: float
name: str
num_barrels: int = 1
outlet_type: int
rise: float
shape_code: int
shape_name: str
span: float
upstream_invert: float
upstream_station: float
class rivia.model.geometry.GateGroup(name, width, height, invert, gate_coefficient, trunnion_exponent, opening_exponent, height_exponent, gate_type, weir_coefficient, is_ogee, spillway_approach_height, design_energy_head, trunnion_height, orifice_coefficient, head_reference, radial_coefficient, is_sharp_crested, use_weir_param1, use_weir_param2, use_weir_param3, openings=<factory>)[source]

Bases: object

One gate group in an inline structure (IW Gate Name block).

Field order follows the comma-delimited IW Gate Name data line:

name,Wd,H,Inv,GCoef,Exp_T,Exp_O,Exp_H,Type,WCoef,Is_Ogee,
SpillHt,DesHd,#Openings,trunnion_height,orifice_coef,
head_ref,radial_coef,,is_sharp_crested,weir_p1,weir_p2,weir_p3
Variables:

  • name – Group name (index 0).

  • width – Gate width — Wd (index 1).

  • height – Gate height — H (index 2).

  • invert – Gate invert elevation — Inv (index 3).

  • gate_coefficient – Gate discharge coefficient (applies to all gate types) — GCoef (index 4). The HDF version names this field sluice_coefficient.

  • trunnion_exponent – Trunnion arm exponent — Exp_T (index 5).

  • opening_exponent – Gate opening exponent — Exp_O (index 6).

  • height_exponent – Gate height exponent — Exp_H (index 7).

  • gate_type – Gate type string — Type (index 8): 'sluice', 'radial', 'overflow_closed_top', 'overflow_open', or 'user_defined_curves'.

  • weir_coefficient – Overflow weir coefficient — WCoef (index 9).

  • is_ogee – True when Is_Ogee (index 10) is -1 (ogee crest shape).

  • spillway_approach_height – Spillway approach height — SpillHt (index 11).

  • design_energy_head – Design energy head — DesHd (index 12).

  • trunnion_height – Trunnion height (index 14).

  • orifice_coefficient – Orifice coefficient (index 15).

  • head_reference – Head reference point — 0 = sill, 1 = centre of opening (index 16).

  • radial_coefficient – Radial (Tainter) gate discharge coefficient (index 17).

  • is_sharp_crested – True when index 19 is -1.

  • use_weir_param1 – True when index 20 is -1.

  • use_weir_param2 – True when index 21 is -1.

  • use_weir_param3 – True when index 22 is -1.

  • openings – Individual gate openings (stations + names).

Parameters:
property Cs: float

Submerged discharge coefficient (alias for orifice_coefficient).

Typical value ~0.8; applied when tailwater submerges the gate opening.

property Cu: float

Unsubmerged discharge coefficient (alias for gate_coefficient).

Typical range 0.5–0.7 for sluice and radial gates.

design_energy_head: float
gate_coefficient: float
gate_type: str
head_reference: int
height: float
height_exponent: float
invert: float
is_ogee: bool
is_sharp_crested: bool
name: str
opening_exponent: float
openings: list[GateOpening]
orifice_coefficient: float
radial_coefficient: float
spillway_approach_height: float
trunnion_exponent: float
trunnion_height: float
use_weir_param1: bool
use_weir_param2: bool
use_weir_param3: bool
weir_coefficient: float
property weir_shape: str

Shape of the overflow weir crest.

Returns 'Ogee', 'Sharp Crested', or 'Broad Crested' based on the is_ogee and is_sharp_crested flags.

width: float
class rivia.model.geometry.GateOpening(name, station, gis=<factory>)[source]

Bases: object

One gate opening within a gate group.

Variables:

  • name – Opening name from IW Gate Opening= line; empty string when the line is absent.

  • station – Lateral station of the gate opening (8-char fixed-width column).

  • gis – GIS (x, y) coordinate pairs from the data line following the IW Gate Opening= line (16-char fixed-width columns). Empty list when the GIS point count is zero.

Parameters:
gis: list[tuple[float, float]]
name: str
station: float
class rivia.model.geometry.Geometry(path)[source]

Bases: object

Verbatim-line editor for HEC-RAS geometry files (.g**).

All lines are loaded verbatim. Structured cross-section data can be read (get_cross_section(), cross_sections()) and written (set_mannings(), set_stations(), set_bank_stations(), set_exp_cntr()). Structure nodes (bridges, culverts, etc.) are accessible as raw lines via get_node_lines().

save() writes all in-memory lines back to disk; a no-op parse+save produces a byte-identical file.

Parameters:

path (str | Path)

all_cross_sections()[source]

Return every cross section in the geometry, in file order.

Iterates all reaches and collects cross sections from each. Structure nodes (bridges, culverts, etc.) are skipped.

Return type:

list[CrossSection]

cross_sections(river, reach)[source]

Return all cross sections in reach, in file order.

Structure nodes (bridges, culverts, etc.) are skipped.

Return type:

list[CrossSection]

Parameters:
get(key)[source]

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

Return type:

str | None

Parameters:

key (str)

get_cross_section(river, reach, rs)[source]

Parse and return the cross section at (river, reach, rs).

Returns None if not found or if the node is not a cross section (type != 1).

Return type:

CrossSection | None

Parameters:
get_node_lines(river, reach, rs)[source]

Return the raw lines for a node block (header inclusive).

Useful for inspecting structure nodes (bridges, culverts, etc.) that are not fully parsed. Returns None if not found.

Return type:

list[str] | None

Parameters:
inline_gate_groups(river, reach, rs)[source]

Return gate group names for an inline structure, in file order.

Parses IW Gate Name header lines from the node block. The name is the first comma-separated field on the data line that immediately follows each header line.

Parameters:

  • river (str) – River name.

  • reach (str) – Reach name.

  • rs (str) – River station of the inline structure.

Returns:

Gate group names, e.g. ["Left Group", "Center Group", "Right Group"].

Return type:

list[str]

Raises:

KeyError – If the node is not found or is not an inline structure (type 5).

property is_modified: bool

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

property junctions: list[str]

Junction names defined in the file, in order of appearance.

node_rs_list(river, reach)[source]

Return (node_type, rs) pairs for every node in reach.

Useful for surveying what cross sections and structures exist. Results are in file order (upstream to downstream for standard HEC-RAS convention).

Return type:

list[tuple[int, str]]

Parameters:
node_type(river, reach, rs)[source]

Return the node type code for (river, reach, rs), or None.

Returns one of NodeType.CROSS_SECTION, NodeType.CULVERT, NodeType.BRIDGE, NodeType.MULTIPLE_OPENING, NodeType.INLINE_STRUCTURE, NodeType.LATERAL_STRUCTURE.

Return type:

int | None

Parameters:
property program_version: str | None

HEC-RAS version that wrote this file (Program Version=).

Treat as read-only; HEC-RAS manages this field.

property reaches: list[tuple[str, str]]

Ordered list of (river, reach) pairs in file order.

save(path=None)[source]

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)[source]

Set key to value verbatim. Raises KeyError if absent.

Return type:

None

Parameters:
set_bank_stations(river, reach, rs, left, right)[source]

Set the left and right bank stations for the given cross section.

Raises:

KeyError – No matching node or no Bank Sta= line found.

Return type:

None

Parameters:
set_blocked_obstructions(river, reach, rs, obstructions)[source]

Replace or remove the blocked-obstruction block for the given XS.

Pass an empty list to remove any existing #Block Obstruct= block. When no block exists, the new block is inserted before Bank Sta=.

Parameters:

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

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

  • rs (str) – River station string.

  • obstructions (list[BlockedObstruction]) – New obstruction list (empty = remove).

Raises:

KeyError – No matching cross-section node found.

Return type:

None

set_exp_cntr(river, reach, rs, expansion, contraction)[source]

Set the expansion/contraction loss coefficients.

Raises:

KeyError – No matching node or no Exp/Cntr= line found.

Return type:

None

Parameters:
set_htab(river, reach, rs, starting_elevation, increment, count)[source]

Set the hydraulic-table parameters for the given cross section.

Replaces the XS HTab Starting El and Incr= line in-place, or inserts it after XS Rating Curve= if absent.

Parameters:

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

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

  • rs (str) – River station string.

  • starting_elevation (float) – First elevation in the hydraulic table.

  • increment (float) – Elevation increment between table entries.

  • count (int) – Number of entries in the hydraulic table.

Raises:

KeyError – No matching cross-section node found.

Return type:

None

set_levee(river, reach, rs, left, right)[source]

Set or remove levee data for the given cross section.

Pass None for both left and right to remove any existing Levee= line. The line is replaced in-place when it already exists; otherwise it is inserted before #XS Ineff= or Bank Sta=.

Parameters:

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

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

  • rs (str) – River station string.

  • left (LeveeData | None) – Left-bank levee definition, or None to clear.

  • right (LeveeData | None) – Right-bank levee definition, or None to clear.

Raises:

KeyError – No matching cross-section node found.

Return type:

None

set_mannings(river, reach, rs, entries, mann_type=None, mann_alt=None)[source]

Replace the Manning’s n data for the given cross section.

The #Mann= header and data rows are rebuilt from entries. If mann_type or mann_alt are None, the existing values from the file are preserved.

Parameters:

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

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

  • rs (str) – River station string (leading/trailing whitespace and trailing * are ignored in comparisons).

  • entries (list[ManningEntry]) – New Manning’s n zones (station, n_value, variation).

  • mann_type (int | None) – Type flag for the #Mann= header. None keeps the existing value.

  • mann_alt (int | None) – Alt flag for the #Mann= header. None keeps the existing value.

Raises:

KeyError – No matching node or no #Mann= line found.

Return type:

None

set_stations(river, reach, rs, stations, elevations)[source]

Replace the station/elevation data for the given cross section.

Parameters:

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

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

  • rs (str) – River station string.

  • stations (list[float]) – New station values.

  • elevations (list[float]) – New elevation values (must match length of stations).

Raises:

  • ValueError – stations and elevations have different lengths.

  • KeyError – No matching node or no #Sta/Elev= line found.

Return type:

None

set_vertical_n(river, reach, rs, vertical_n)[source]

Replace or remove the vertical n block for the given cross section.

When vertical_n is not None the existing block (if any) is replaced in-place; if none exists, the block is inserted after the XS Rating Curve= line. Passing None removes any existing block.

The caller is responsible for ensuring the #Mann block still contains valid zone boundary stations. When vertical n is active HEC-RAS expects those n-values to be 0 (placeholders).

Parameters:

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

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

  • rs (str) – River station string.

  • vertical_n (VerticalN | None) – New vertical n data, or None to remove.

Raises:

KeyError – No matching cross-section node found.

Return type:

None

property structures: StructureCollection

Structure collection parsed from this geometry file.

Returns a StructureCollection whose inlines property holds all inline structures keyed by 'River Reach RS'. The result is cached; invalidated automatically on save().

Example:

g = Geometry("model.g01")
for key, iw in g.structures.inlines.items():
    print(key, [gg.name for gg in iw.gate_groups])
property title: str | None

Geometry title (Geom Title=).

property viewing_rectangle: tuple[float, float, float, float] | None

Map viewport as (min_x, min_y, max_x, max_y), or None.

HEC-RAS writes this as Viewing Rectangle= x1 , y1 , x2 , y2.

class rivia.model.geometry.IneffArea(x_start, x_end, elevation, permanent=False)[source]

Bases: object

One ineffective flow area interval.

Variables:

  • x_start – Left boundary station.

  • x_end – Right boundary station.

  • elevation – Activation elevation (area is ineffective below this).

  • permanent – True if always active (T flag), False if elevation-triggered (F flag).

Parameters:
elevation: float
permanent: bool = False
x_end: float
x_start: float
class rivia.model.geometry.InlineStructure(mode, upstream_type, downstream_type, centerline=<factory>, location=('', '', ''), upstream_node=('', '', ''), downstream_node=('', '', ''), weir=None, gate_groups=<factory>, description='', pilot_flow=0.0, crest_profile=<factory>)[source]

Bases: Structure

Inline structure (node type 5) parsed from a .g** text geometry file.

Mirrors rivia.hdf.geometry.InlineStructure. Inherits mode, upstream_type, downstream_type, and centerline from Structure.

Differences vs the HDF version:

  • upstream_node / downstream_node: use ("", "", "") as the no-value sentinel (same as HDF), populated by walking node_rs_list to find the nearest flanking cross sections.

  • weir: populated from IW Dist even when mode is '' (HDF returns None for mode='').

  • description: text-file-specific field from the BEGIN/END DESCRIPTION block; no equivalent in HDF.

  • pilot_flow: minimum flow through the structure when all gates are fully closed — from IW Pilot Flow=; no equivalent in HDF.

  • crest_profile: station/elevation pairs defining the weir crest geometry — from the #Inline Weir SE= block; no equivalent in HDF.

Variables:

  • location – (river, reach, rs) of this structure.

  • upstream_node – (river, reach, rs) of the nearest upstream XS; ("", "", "") when none found.

  • downstream_node – (river, reach, rs) of the nearest downstream XS; ("", "", "") when none found.

  • weir – Overflow weir data from IW Dist block; None if no IW Dist line is present.

  • gate_groups – Gate group definitions from IW Gate Name blocks.

  • description – Node description from BEGIN/END DESCRIPTION.

  • pilot_flow – Minimum (pilot) flow through the structure — IW Pilot Flow=; 0.0 when absent.

  • crest_profile – Weir crest station/elevation pairs from the #Inline Weir SE= block; empty list when absent.

Parameters:
crest_profile: list[tuple[float, float]]
description: str = ''
downstream_node: tuple[str, str, str] = ('', '', '')
gate_groups: list[GateGroup]
location: tuple[str, str, str] = ('', '', '')
pilot_flow: float = 0.0
upstream_node: tuple[str, str, str] = ('', '', '')
weir: Weir | None = None
class rivia.model.geometry.LateralStructure(mode, upstream_type, downstream_type, centerline=<factory>, location=('', '', ''), upstream_node=('', '', ''), downstream_node='', weir=None, gate_groups=<factory>, description='', pos=0, distance=nan, crest_profile=<factory>, flap_gates=False, tw_multiple_xs=False)[source]

Bases: Structure

Lateral structure (node type 6) parsed from a .g** text geometry file.

Mirrors rivia.hdf.geometry.LateralStructure. Inherits mode, upstream_type, downstream_type, and centerline from Structure.

Differences vs the HDF version:

  • downstream_node: HDF stores the name of the connected Storage Area or 2-D Flow Area. The text format stores a connected river+reach via Lateral Weir End=river,reach,rs,...; this field holds "river reach" (stripped, space-joined). Empty string when the Lateral Weir End= line is absent.

  • weir: built from individual Lateral Weir WD=, Lateral Weir Coef=, and Lateral Weir WSCriteria= lines; skew=0, min_elevation=nan, us_slope/ds_slope=nan.

  • gate_groups: always [] — lateral structures in the text format use Lateral Weir hydraulics, not IW Gate Name blocks.

  • description: text-file-specific field from BEGIN/END DESCRIPTION; no equivalent in HDF.

Variables:

  • location – (river, reach, rs) of this structure.

  • upstream_node – (river, reach, rs) of the nearest upstream XS; ("", "", "") when none found.

  • downstream_node – Connected river+reach as "river reach" (from Lateral Weir End=); empty string when absent.

  • weir – Overflow weir data from Lateral Weir lines; None if no Lateral Weir WD= line is present.

  • gate_groups – Always [].

  • description – Node description from BEGIN/END DESCRIPTION.

  • pos – Bank side of the weir — 0 = left, 1 = right (from Lateral Weir Pos=).

  • distance – Setback distance from the upstream cross section (from Lateral Weir Distance=); nan when absent.

  • crest_profile – Weir crest station/elevation pairs from the Lateral Weir SE= block; empty list when absent.

  • flap_gates – True when Lateral Weir Flap Gates= -1 or 1; False when 0 or absent.

  • tw_multiple_xs – True when tailwater uses multiple XS averaging (Lateral Weir TW Multiple XS= non-zero).

  • TODO (..) – and six coefficients) is not yet parsed.

  • TODO – yet parsed.

  • TODO – position code and distance) is not yet parsed.

  • TODO – coordinate block) is not yet parsed.

  • TODO – parsed.

Parameters:
crest_profile: list[tuple[float, float]]
description: str = ''
distance: float = nan
downstream_node: str = ''
flap_gates: bool = False
gate_groups: list[GateGroup]
location: tuple[str, str, str] = ('', '', '')
pos: int = 0
tw_multiple_xs: bool = False
upstream_node: tuple[str, str, str] = ('', '', '')
weir: Weir | None = None
class rivia.model.geometry.LeveeData(station, elevation, failure_elevation=None)[source]

Bases: object

Levee definition for one bank of a cross section.

Encoded on the Levee= line as a -1 active flag followed by station and elevation.

Variables:

  • station – Lateral station of the levee crest.

  • elevation – Levee crest elevation.

  • failure_elevation – Elevation at which the levee fails; None if not specified.

Parameters:
elevation: float
failure_elevation: float | None = None
station: float
class rivia.model.geometry.ManningEntry(station, n_value, variation=0.0)[source]

Bases: object

One horizontal Manning’s n zone.

Variables:

  • station – Left boundary station of this n zone.

  • n_value – Manning’s roughness coefficient.

  • variation – Third column in the HEC-RAS file. Usually 0; used for vertical-n or alternative-n assignments.

Parameters:
n_value: float
station: float
variation: float = 0.0
class rivia.model.geometry.NodeType(value)[source]

Bases: IntEnum

Node type codes from the Type RM Length L Ch R = TYPE, ... line.

BRIDGE = 3
CROSS_SECTION = 1
CULVERT = 2
INLINE_STRUCTURE = 5
LATERAL_STRUCTURE = 6
MULTIPLE_OPENING = 4
class rivia.model.geometry.Pier(skew, upstream_station, upstream_count, downstream_station, downstream_count, upstream_widths, upstream_elevations, downstream_widths, downstream_elevations)[source]

Bases: object

One pier group from a Pier Skew, UpSta & Num, DnSta & Num= block.

The header line carries the skew, station, and count; four fixed-width blocks (8-char columns, up to 10 per row) immediately follow:

upstream_count   widths
upstream_count   elevations
downstream_count widths
downstream_count elevations
Variables:

  • skew – Pier skew angle in degrees; 0.0 when blank.

  • upstream_station – Station of the upstream pier face.

  • upstream_count – Number of upstream pier elements.

  • downstream_station – Station of the downstream pier face.

  • downstream_count – Number of downstream pier elements.

  • upstream_widths – Width of each upstream pier element.

  • upstream_elevations – Top-of-pier elevation for each upstream element.

  • downstream_widths – Width of each downstream pier element.

  • downstream_elevations – Top-of-pier elevation for each downstream element.

Parameters:
downstream_count: int
downstream_elevations: list[float]
downstream_station: float
downstream_widths: list[float]
skew: float
upstream_count: int
upstream_elevations: list[float]
upstream_station: float
upstream_widths: list[float]
class rivia.model.geometry.Roadway(dist, width, weir_coefficient, skew, max_submergence, shape, min_lo_chord, max_hi_chord, stations_up=<factory>, hi_chord_up=<factory>, lo_chord_up=<factory>, stations_dn=<factory>, hi_chord_dn=<factory>, lo_chord_dn=<factory>)[source]

Bases: object

Deck/roadway geometry from the Deck Dist Width WeirC ... block.

The header Deck Dist Width WeirC Skew NumUp NumDn MinLoCord MaxHiCord MaxSubmerge Is_Ogee is followed by a comma-separated data line and then six fixed-width blocks (8-char columns, up to 10 values per row):

  • numUp upstream deck stations

  • numUp upstream high-chord (top of deck) elevations

  • numUp upstream low-chord (soffit) elevations

  • numDn downstream versions of the above (same layout)

lo_chord_up / lo_chord_dn will be an empty list when the corresponding block is all-blank (some culvert files omit low-chord data).

Variables:

  • dist – Distance from the upstream cross section to the bridge face (index 0).

  • width – Deck/roadway width (index 1).

  • weir_coefficient – Overflow weir discharge coefficient (index 2).

  • skew – Bridge skew angle in degrees (index 3).

  • max_submergence – Maximum submergence ratio (index 8); nan when blank.

  • shape – Overflow weir crest shape — 'Broad Crested' or 'Ogee' (from Is_Ogee flag, index 9).

  • min_lo_chord – Minimum low-chord elevation (index 6); nan when blank.

  • max_hi_chord – Maximum high-chord elevation (index 7); nan when blank.

  • stations_up – Upstream deck station values.

  • hi_chord_up – Upstream high-chord (top of deck) elevations.

  • lo_chord_up – Upstream low-chord (soffit) elevations; empty list when the block is all-blank.

  • stations_dn – Downstream deck station values.

  • hi_chord_dn – Downstream high-chord elevations.

  • lo_chord_dn – Downstream low-chord elevations; empty list when all-blank.

  • TODO (..) – Deck Dist) encodes open-deck / culvert-only options and is not yet parsed.

  • TODO – Yarnell K factor, etc.) is not yet parsed.

  • TODO – parsed.

  • TODO

Parameters:
dist: float
hi_chord_dn: list[float]
hi_chord_up: list[float]
lo_chord_dn: list[float]
lo_chord_up: list[float]
max_hi_chord: float
max_submergence: float
min_lo_chord: float
shape: str
skew: float
stations_dn: list[float]
stations_up: list[float]
weir_coefficient: float
width: float
class rivia.model.geometry.Structure(mode, upstream_type, downstream_type, centerline=<factory>)[source]

Bases: object

Base class for one HEC-RAS structure parsed from a text geometry file.

Mirrors rivia.hdf.geometry.Structure in field names. Key difference:

  • centerline: the text geometry file carries no GIS centreline coordinates for structures; always an empty list. The HDF version stores an (n_pts, 2) numpy array.

Variables:

  • mode –

    HEC-RAS mode string (e.g. 'Weir/Gate/Culverts'). Always '' for inline structures — not stored in the text format.

  • upstream_type – Connection type on the upstream side ('XS', 'SA', '2D', or '--'). Always 'XS' for inline structures.

  • downstream_type – Connection type on the downstream side.

  • centerline – GIS centreline as [(x, y), ...]; always [] from text files.

Parameters:
centerline: list[tuple[float, float]]
downstream_type: str
mode: str
upstream_type: str
class rivia.model.geometry.StructureCollection(inlines, bridges, laterals)[source]

Bases: object

Structure collection parsed from a HEC-RAS text geometry file.

Covers inline structures (node type 5), bridges/culverts (types 3/2), and lateral structures (type 6).

Access structures via the typed properties:

g = Geometry("model.g01")
for key, iw in g.structures.inlines.items():
    print(key, iw.gate_groups)
for key, br in g.structures.bridges.items():
    print(key, br.weir)
for key, lat in g.structures.laterals.items():
    print(key, lat.downstream_node)
Parameters:
property bridges: StructureIndex[Bridge]

All bridges and culverts (types 3 and 2) keyed by 'River Reach RS'.

property inlines: StructureIndex[InlineStructure]

All inline structures (type 5) keyed by 'River Reach RS'.

property laterals: StructureIndex[LateralStructure]

All lateral structures (type 6) keyed by 'River Reach RS'.

property summary: dict[str, int]

Count of each parsed structure type.

class rivia.model.geometry.StructureIndex(items)[source]

Bases: Generic[_T]

Read-only ordered mapping from a string key to a structure object.

Supports both string key ("River Reach RS") and integer positional index. Mirrors the interface of StructureIndex.

Parameters:

items (list[tuple[str, _T]])

items()[source]

Ordered (key, structure) pairs.

Return type:

list[tuple[str, TypeVar(_T)]]

keys()[source]

Ordered list of string keys.

Return type:

list[str]

values()[source]

Ordered list of structure objects.

Return type:

list[TypeVar(_T)]

class rivia.model.geometry.VerticalN(breakpoints, by_flow, stations)[source]

Bases: object

Vertical (depth/flow-varying) Manning’s n for a cross section.

HEC-RAS stores this block between XS Rating Curve= and Exp/Cntr= when vertical variation is active. The #Mann block in the same XS still defines zone boundaries but carries placeholder zero n-values.

Variables:

  • breakpoints – Water-surface elevations (by_flow=False) or flow values (by_flow=True) at which n is tabulated. Length N.

  • by_flow – True when breakpoints are flows (Vertical n Flow=-1); False when they are WSE (Vertical n Flow= 0).

  • stations – Per-station n-value curves, each with N entries.

Parameters:
breakpoints: list[float]
by_flow: bool
stations: list[VerticalNStation]
class rivia.model.geometry.VerticalNStation(station, n_values)[source]

Bases: object

Manning’s n values at one cross-section station, varying by depth or flow.

Variables:

  • station – Lateral station (same coordinate system as #Sta/Elev).

  • n_values – n-value at each breakpoint in VerticalN.

Parameters:
n_values: list[float]
station: float
class rivia.model.geometry.Weir(width, coefficient, shape, max_submergence, min_elevation, skew, dist=nan, spillway_approach_height=nan, design_energy_head=nan, us_slope=nan, ds_slope=nan, use_water_surface=False)[source]

Bases: object

Overflow weir parameters from the IW Dist block.

Mirrors rivia.hdf.geometry.Weir in field names. Key differences vs the HDF version:

  • Always populated when an IW Dist line exists, even when mode is empty (the HDF version returns None for mode='').

  • us_slope, ds_slope: not present in the IW Dist text line; stored as nan.

  • use_water_surface: not stored in the text geometry format; always False.

Variables:

  • width – Weir width (WD, index 1).

  • coefficient – Weir discharge coefficient (Coef, index 2).

  • shape – 'Broad Crested' or 'Ogee' (Is_Ogee, index 6).

  • max_submergence – Maximum submergence ratio (MaxSub, index 4).

  • min_elevation – Minimum weir crest elevation (Min_El, index 5); nan when blank.

  • skew – Weir skew angle in degrees (Skew, index 3).

  • dist – Distance from the upstream XS to the weir face (index 0 of the IW Dist data line); nan for bridges and laterals (not stored in those formats).

  • spillway_approach_height – Spillway approach height — SpillHt (index 7 of the IW Dist data line); nan for bridges and laterals.

  • design_energy_head – Design energy head — DesHd (index 8 of the IW Dist data line); nan for bridges and laterals.

  • us_slope – Upstream face slope H:V; nan — not in text format.

  • ds_slope – Downstream face slope H:V; nan — not in text format.

  • use_water_surface – Use water surface as weir reference head; always False — not in text format.

Parameters:
coefficient: float
design_energy_head: float = nan
dist: float = nan
ds_slope: float = nan
max_submergence: float
min_elevation: float
shape: str
skew: float
spillway_approach_height: float = nan
us_slope: float = nan
use_water_surface: bool = False
width: float