Inputs and configuration

Public types used to describe culverts, crossings, boundaries, and solver policy.

TailwaterInput is the public input contract for forward barrel, group, crossing, and rating-curve solvers. It accepts either an absolute water-surface elevation in metres or a TailwaterBoundary that resolves elevation and provenance for the applicable discharge. TailwaterRatingCurve accepts at least two TailwaterRatingPoint values with strictly increasing discharge and nondecreasing absolute elevation. It returns exact tabulated stages or linear interpolation inside the supplied range and rejects extrapolation.

Roadway overtopping accepts either a constant-elevation RoadwayWeir or an irregular RoadwayProfileWeir. Irregular profiles use a RoadwayCrestProfile of strictly increasing RoadwayCrestPoint station/elevation coordinates. Free overflow does not require a surface class. Downstream-submerged roadway flow requires RoadwaySurface.PAVED or RoadwaySurface.GRAVEL, because the implemented correction is limited to those sourced FHWA relationships. The correction is bounded to a local downstream/upstream head ratio of 0.99. Ratios between 0.99 and equal stage fail closed rather than extrapolating the sourced curve; exactly equal upstream and downstream water levels produce zero roadway flow. For a crossing, the common-headwater solve is bounded to this same supported domain and rejects a requested discharge below the minimum evaluable submerged-roadway capacity.

Independent, early-stage culvert hydraulics library.

The package exposes internally tested geometry and hydraulic components through provisional combined solvers. External engineering validation is not yet complete.

RoadwayOvertoppingInput = RoadwayWeir | RoadwayProfileWeir

TailwaterInput = TailwaterBoundary | float

CircularGeometry dataclass

Bases: CrossSectionGeometry

Circular pipe barrel geometry defined by internal diameter in metres.

All properties and methods return SI units.

span property

Internal diameter in metres.

rise property

Internal diameter in metres.

area_full property

Full circular cross-sectional area in square metres (pi * D² / 4).

wetted_perimeter_full property

Full circular wetted perimeter in metres (pi * D).

hydraulic_radius_full property

Full circular hydraulic radius in metres (D / 4).

from_mm(diameter_mm) classmethod

Construct circular geometry from an internal diameter in millimetres.

area(depth)

Wetted flow area at the specified depth in square metres.

wetted_perimeter(depth)

Wetted perimeter at the specified depth in metres.

top_width(depth)

Free-surface top width at the specified depth in metres.

Returns 0.0 for depth <= 0 and for depth >= diameter (closed crown).

hydrostatic_pressure_moment(depth)

Return the exact circular-segment hydrostatic first moment in cubic metres.

RectangularGeometry

Bases: CrossSectionGeometry

Rectangular box culvert barrel geometry defined by internal span and rise in metres.

All properties and methods return SI units.

span property

Internal horizontal span (width) in metres.

rise property

Internal vertical rise (height) in metres.

area_full property

Full cross-sectional flow area in square metres (span * rise).

wetted_perimeter_full property

Full internal wetted perimeter in metres (2 * (span + rise)).

from_mm(span_mm, rise_mm) classmethod

Construct rectangular geometry from internal span and rise in millimetres.

area(depth)

Wetted flow area at the specified depth in square metres.

wetted_perimeter(depth)

Wetted perimeter at the specified depth in metres.

top_width(depth)

Free-surface top width at the specified depth in metres.

Returns 0.0 for depth <= 0 and for depth >= rise (closed top slab).

hydrostatic_pressure_moment(depth)

Return the exact rectangular hydrostatic first moment in cubic metres.

FilletedRectangularGeometry

Bases: CrossSectionGeometry

Box culvert section with an equal triangular fillet at each internal corner.

span and rise are the maximum clear dimensions. fillet is the horizontal and vertical leg length of each 45-degree triangular fillet. All dimensions and returned quantities use SI units.

span property

Maximum internal horizontal span in metres.

rise property

Maximum internal vertical rise in metres.

fillet property

Horizontal and vertical fillet leg length in metres.

area_full property

Net full-flow area after removing four triangular fillets.

wetted_perimeter_full property

Internal perimeter including all four diagonal fillet faces.

from_mm(span_mm, rise_mm, fillet_mm) classmethod

Construct a filleted box from millimetre dimensions.

area(depth)

Wetted net area at depth in square metres.

wetted_perimeter(depth)

Wetted boundary length, excluding the free surface for partial flow.

top_width(depth)

Free-surface width at depth in metres.

CrossSectionGeometry

Bases: ABC

Abstract base class for culvert barrel cross-section geometries.

All physical dimensions and computed quantities are in SI units (metres, square metres). Subclasses implement specific shapes (e.g. circular, rectangular box).

span abstractmethod property

Maximum internal horizontal width in metres.

rise abstractmethod property

Maximum internal vertical height in metres.

area_full abstractmethod property

Full cross-sectional flow area in square metres.

wetted_perimeter_full abstractmethod property

Full internal wetted perimeter in metres.

hydraulic_radius_full property

Full hydraulic radius in metres (area_full / wetted_perimeter_full).

is_full(depth)

Return True if water depth reaches or exceeds the conduit rise.

area(depth) abstractmethod

Wetted flow area at the specified depth in square metres.

wetted_perimeter(depth) abstractmethod

Wetted perimeter at the specified depth in metres.

top_width(depth) abstractmethod

Free-surface top width at the specified depth in metres.

Returns 0.0 when depth <= 0 or when depth >= rise (closed conduit at/above crown).

hydraulic_radius(depth)

Hydraulic radius R = A / P at the specified depth in metres.

Returns 0.0 for depth <= 0. Returns hydraulic_radius_full for depth >= rise.

hydraulic_depth(depth)

Hydraulic depth D_h = A / T at the specified depth in metres.

Raises InvalidInputError when top width is 0 (dry conduit or closed conduit at/above crown).

hydrostatic_pressure_moment(depth)

Return integral(area(z), z=0..depth) in cubic metres.

This generic composite-Simpson implementation supports future geometry classes. Performance-sensitive built-in shapes override it analytically.

CulvertBarrel dataclass

A physical culvert barrel defined by authoritative inverts and longitudinal length.

All lengths, inverts, and computed elevations are in SI metres. Slope is derived from the drop (inlet_invert - outlet_invert) and barrel length. Adverse slopes (outlet_invert > inlet_invert) raise InvalidInputError.

drop property

Total vertical fall along the barrel in metres (inlet_invert - outlet_invert).

slope property

Longitudinal barrel bed slope S0 = drop / length (dimensionless).

is_horizontal property

Return True if the barrel has zero slope (inlet_invert == outlet_invert).

inlet_crown property

Absolute elevation of the barrel crown at the inlet in metres.

outlet_crown property

Absolute elevation of the barrel crown at the outlet in metres.

CulvertGroup dataclass

Hydraulically identical parallel barrels represented with equal barrel flow.

For quantity > 1, solvers divide total group discharge equally between barrels. This representative-barrel model is intended for total-flow calculations under sufficiently uniform approach conditions; it does not establish exact barrel-specific discharge or velocity under nonuniform approach flow or depressed-barrel conditions.

total_full_area property

Total cross-sectional flow area of all barrels in the group in square metres.

total_span property

Combined nominal horizontal span of all barrels in the group in metres.

CulvertCrossing dataclass

A multi-barrel or multi-group culvert crossing sharing upstream headwater.

A crossing consists of one or more culvert groups, each with its own size, shape, material, inverts, and quantity of parallel barrels.

num_groups property

Total number of culvert groups in the crossing.

total_barrels property

Total number of individual culvert barrels across all groups.

total_full_area property

Total full cross-sectional flow area of all barrels in square metres.

min_inlet_invert property

Lowest inlet invert elevation among all groups in metres.

max_inlet_invert property

Highest inlet invert elevation among all groups in metres.

min_outlet_invert property

Lowest outlet invert elevation among all groups in metres.

max_outlet_invert property

Highest outlet invert elevation among all groups in metres.

min_headwater_reference_elevation property

Lowest inlet or roadway crest that can begin conveying upstream flow.

CulvertInventory dataclass

Independent road crossings collected for calculation and compact reporting.

update_configuration(crossing_id, new_configuration)

Replace a crossing configuration and discard its now-stale result.

update_result(crossing_id, result)

Attach a result to the matching crossing configuration.

CulvertInventoryItem dataclass

One stably identified road crossing and its optional hydraulic result.

RoadwayWeir dataclass

A constant-elevation roadway crest represented as a broad-crested weir.

discharge_coefficient is the SI coefficient in Q = C_d L H**1.5 and therefore has units of m**0.5/s. HDS-5 requires it to be selected from the roadway geometry and overtopping-depth curves; the library intentionally supplies no universal default.

surface is optional for free overflow. It must be PAVED or GRAVEL before a supported downstream-submergence correction can be applied.

minimum_crest_elevation property

Lowest roadway elevation represented by the constant crest.

RoadwayProfileWeir dataclass

An irregular roadway crest integrated between station/elevation coordinates.

crest_length property

Horizontal station span of the roadway profile in metres.

crest_elevation property

Minimum crest elevation, retained as a scalar compatibility summary.

minimum_crest_elevation property

Lowest roadway elevation represented by the profile.

RoadwayCrestProfile dataclass

Piecewise-linear roadway crest defined by increasing station coordinates.

crest_length property

Horizontal station span of the roadway profile in metres.

minimum_crest_elevation property

Lowest roadway elevation represented by the profile.

RoadwayCrestPoint dataclass

One horizontal station/elevation coordinate on an irregular roadway crest.

RoadwaySurface

Bases: StrEnum

Roadway surface classes supported by the sourced submergence relationship.

TailwaterBoundary

Bases: Protocol

Flow-dependent or fixed tailwater boundary contract.

resolve(discharge, *, g=GRAVITATIONAL_ACCELERATION)

Resolve absolute tailwater elevation for the receiving discharge.

TailwaterCondition dataclass

Downstream tailwater specified as an absolute water-surface elevation.

depth_at_invert(outlet_invert)

Return nonnegative tailwater depth at a barrel outlet invert.

resolve(discharge, *, g=GRAVITATIONAL_ACCELERATION)

Return this fixed elevation through the common boundary interface.

ManningChannelTailwater dataclass

Normal-depth tailwater for a prismatic downstream channel.

friction_slope is the Manning energy slope. Representative bed slope is an approximation valid only under the documented uniform-flow assumption. method_source documents that method; the other source fields document the independently selected project parameters.

resolve(discharge, *, g=GRAVITATIONAL_ACCELERATION)

Resolve normal depth and absolute downstream water-surface elevation.

TailwaterRatingCurve dataclass

User-supplied monotonic discharge/elevation tailwater boundary.

The curve uses exact elevations at supplied points and linear interpolation between them. Discharges outside its closed range are rejected; the boundary never clamps or extrapolates.

min_discharge property

Lowest discharge supported without extrapolation.

max_discharge property

Highest discharge supported without extrapolation.

resolve(discharge, *, g=GRAVITATIONAL_ACCELERATION)

Resolve an in-range stage without clamping or extrapolation.

TailwaterRatingPoint dataclass

One user-supplied discharge and absolute water-surface elevation pair.

OpenChannelSection

Bases: Protocol

SI geometry contract for a prismatic open channel.

area(depth)

Return wetted flow area in square metres.

wetted_perimeter(depth)

Return wetted perimeter in metres.

top_width(depth)

Return free-surface top width in metres.

RectangularChannel dataclass

Open rectangular channel with vertical side walls.

area(depth)

Return wetted flow area in square metres.

wetted_perimeter(depth)

Return wetted perimeter in metres.

top_width(depth)

Return free-surface top width in metres.

TrapezoidalChannel dataclass

Open trapezoid with independent horizontal-to-vertical side slopes.

A zero bottom width represents a triangular section when at least one side slope is positive.

area(depth)

Return wetted flow area in square metres.

wetted_perimeter(depth)

Return wetted perimeter in metres.

top_width(depth)

Return free-surface top width in metres.

CulvertMaterial dataclass

A culvert barrel material and its documented Manning roughness range.

InletCoefficients dataclass

Empirical regression constants and equation form for culvert inlet control.

EntranceLossCoefficient dataclass

Entrance loss coefficient Ke and source metadata for culvert outlet control.

ModernBoxInlet dataclass

Physical identity needed to select a corrected Figure 93 inlet relationship.

corner_fillet property

Corner-fillet leg length in metres, or zero for a sharp-corner box.

span_to_rise_ratio property

Nominal clear span-to-rise ratio of one barrel.

net_opening_area property

Total net opening area across all barrels in square metres.

SolverConfiguration dataclass

Immutable configuration object holding solver-facing defaults and policies.

This class decouples hardcoded library defaults from the resolution logic, allowing consumers to inject project-specific defaults without mutating global state.

RootTolerances dataclass

Numerical tolerances, not engineering acceptance limits.

x_abs has the units of the independent variable; x_rel is dimensionless. Optional residual_abs has the units of the supplied function. When set, both interval and residual criteria must pass (an exact zero always passes).

SourceReference dataclass

A specific publication locator and its documented applicability.

locator should identify an equation, table, figure or section. Free-text applicability is provenance, not executable range enforcement; coefficient models must add explicit shape/configuration/range validation in Phase 4. url may be omitted for controlled manufacturer specifications or other non-public documents; publication, edition, and locator remain mandatory.

ControlType

Bases: StrEnum

Location of the hydraulic control governing a result.

GeometryShape

Bases: StrEnum

Geometry families to which empirical coefficients may apply.

CspCorrugation

Bases: StrEnum

MRWA helically wound CSP corrugation pitch by depth in millimetres.

InletEquationForm

Bases: IntEnum

FHWA HDS-5 unsubmerged inlet-control equation form.

BoxCrownTreatment

Bases: StrEnum

Supported box-inlet crown-edge treatments.

BoxWingwallTreatment

Bases: StrEnum

Supported Figure 93 wingwall arrangements.