Results and diagnostics¶
Return types retain adopted values, source provenance, warnings, and convergence evidence.
RoadwayOvertoppingResult.segment_results preserves the horizontal integration pieces used
for roadway flow. Each RoadwayOvertoppingSegmentResult records the local crest elevation,
effective horizontal length, local upstream/downstream heads, discharge contribution and
integration source. Where downstream submergence applies, the segment also retains a
RoadwaySubmergenceCorrection with the interpolated factor plus the governing FHWA source
and the digital-ordinate source used by the implementation.
For downstream floodway analysis, each roadway segment result also exposes local
unit_discharge in m²/s, a machine-readable flow_state, direct submergence_ratio and
submergence_factor accessors, and physical_interval_length. The supported flow-state
values are inactive, free_unsubmerged, and supported_submerged. The physical interval
length is the horizontal roadway interval represented by the integration point;
effective_length is the Gaussian quadrature weight multiplied by that interval and must
not be interpreted as a physical pavement, shoulder, protection, or floodway design-zone
length. No critical-depth, velocity, Froude-number, shear, momentum, or protection-design
quantity is inferred from these integration results because those derived quantities are
not established as generally applicable across the supported roadway-flow states.
Longitudinal hydraulic profile convention¶
BarrelHydraulicResult.longitudinal_profile is the downstream-consumable profile contract
for plotting and reporting. Stations are SI metres measured along the barrel from the inlet
(0.0) to the outlet (barrel.length). Invert and crown elevations use the same absolute
datum as the barrel inverts and tailwater boundary.
Each HydraulicProfilePoint explicitly identifies its HydraulicProfileState:
free_surface:water_surface_elevationis the physical water surface and is also the HGL;pressurised:water_surface_elevationisNone;hydraulic_grade_elevationis the piezometric HGL and must not be presented as a physical free surface.
energy_grade_elevation is HGL plus velocity head. cumulative_friction_loss accumulates
barrel friction from the inlet station; entrance and exit losses are retained separately on
LongitudinalHydraulicProfile so presentation code does not double count boundary losses.
Supported mixed paths preserve inlet-to-outlet ordering and record their free/full transition
station. The existing ProfilePoint, WaterSurfaceProfile, and InletControlProfile types
remain the direct-step/free-surface calculation records and are not redefined as pressurised
HGL points.
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.
REPRESENTATIVE_BARREL_EQUAL_FLOW_NOTICE = HydraulicApplicabilityNotice(code=ApplicabilityNoticeCode.REPRESENTATIVE_BARREL_EQUAL_FLOW, message='Total group discharge uses a representative-barrel equal-flow assumption for hydraulically identical barrels under sufficiently uniform approach conditions. Individual barrel discharge and velocity may differ with nonuniform approach flow or depressed barrels, so barrel-specific performance requires separate review.', source=NCHRP_734_REPRESENTATIVE_BARREL)
module-attribute
¶
NCHRP_734_REPRESENTATIVE_BARREL = SourceReference(source_id='NCHRP-734-2012-CHAPTER-5-MULTI-BARREL', publication='Hydraulic Loss Coefficients for Culverts, NCHRP Report 734', edition='2012', locator='Chapter 5 conclusions, printed page 49 (local PDF page 57)', url='https://doi.org/10.17226/22673', applicability='Representative average-barrel superposition for total flow through hydraulically identical parallel barrels under sufficiently uniform approach conditions.', notes='Reported nonuniform-approach, depressed-barrel, and individual-barrel differences are observed limitations, not deterministic correction factors.')
module-attribute
¶
BarrelHydraulicResult
dataclass
¶
Hydraulic calculation results for a single culvert barrel.
status
property
¶
Return the most conservative status implied by structured warnings.
GroupHydraulicResult
dataclass
¶
Hydraulic results for identical barrels, including equal-flow applicability.
status
property
¶
Return the representative barrel's computational resolution status.
CrossingHydraulicResult
dataclass
¶
Hydraulic results across a crossing, including aggregated applicability notices.
InletControlResult
dataclass
¶
Inlet control headwater evaluation result.
FullFlowOutletResult
dataclass
¶
Hydraulic solution for a culvert barrel operating under full-flow outlet control.
All elevations, depths, and head losses are in SI metres.
PartialFlowOutletResult
dataclass
¶
Hydraulic outcome for a culvert barrel operating under partial-flow outlet control.
ModernBoxInletResult
dataclass
¶
Direct Table 12 polynomial evaluation for a supported modern box inlet.
RoadwayOvertoppingResult
dataclass
¶
Roadway-weir flow at one upstream and downstream water-surface elevation.
RoadwayOvertoppingSegmentResult
dataclass
¶
Flow contribution from one weighted horizontal roadway integration segment.
interval_start_station and interval_end_station bound the physical
roadway interval represented by the integration point. effective_length
is the Gaussian quadrature weight multiplied by that physical interval and
must not be interpreted as a physical floodway design-zone length.
physical_interval_length
property
¶
Physical horizontal interval represented by this integration result, in metres.
unit_discharge
property
¶
Local roadway unit discharge at the integration station, in m²/s.
flow_state
property
¶
Return the explicit local roadway flow/submergence state.
submergence_ratio
property
¶
Return downstream/upstream local head ratio when a correction applies.
submergence_factor
property
¶
Return the applied sourced submergence factor when a correction applies.
RoadwaySubmergenceCorrection
dataclass
¶
One sourced downstream-submergence correction applied to roadway flow.
CriticalDepthResult
dataclass
¶
Critical depth calculation outcome and associated hydraulic terms.
depth: Critical depth in metres.
specific_energy: Specific energy E = yc + Vc²/(2g) in metres.
froude_number: Froude number at critical depth (1.0 for open-channel flow).
is_submerged: True if critical depth reaches or exceeds the conduit rise.
convergence: Root diagnostics for numerically solved depths; None for analytical
and boundary outcomes.
NormalDepthResult
dataclass
¶
Normal depth calculation outcome and associated hydraulic terms.
depth: Normal depth in metres.
velocity: Mean velocity at normal depth in metres per second.
froude_number: Froude number at normal depth (float('nan') if full/closed).
conveyance: Manning conveyance K = A * R^(2/3) in m^(8/3).
is_full: True if normal depth reaches or exceeds the conduit rise.
capacity_exceeded: True if discharge exceeds open-channel conveyance capacity.
convergence: Root diagnostics for numerically solved depths; None for exact
zero-flow and capacity-boundary outcomes.
ChannelNormalDepthResult
dataclass
¶
Auditable uniform-flow normal-depth result for an open channel.
RatingCurveResult
dataclass
¶
Complete discharge rating curve across multiple operating points.
RatingCurvePoint
dataclass
¶
Hydraulic performance metrics at a single operating discharge.
tailwater_depth is measured above the barrel outlet invert for a barrel
curve, or above the lowest outlet invert for a crossing curve. A Manning
boundary's channel normal depth is separately retained as
tailwater_resolution.depth relative to its channel invert.
WaterSurfaceProfile
dataclass
¶
Complete water surface profile computed along the culvert barrel.
InletControlProfile
dataclass
¶
Forward free-surface profile downstream from an inlet control section.
ProfilePoint
dataclass
¶
Hydraulic state at a discrete longitudinal station along the culvert barrel.
All lengths, depths, and elevations are in SI metres. Station is measured from the culvert inlet (station = 0.0) to the outlet (station = length).
LongitudinalHydraulicProfile
dataclass
¶
Ordered barrel profile combining free-surface and pressurised reaches.
Station is measured from the culvert inlet (0 m) to outlet (barrel length). Boundary losses are retained separately from the station-wise barrel friction accumulation to avoid double counting entrance or exit losses.
is_mixed
property
¶
Return whether both free-surface and pressurised states are present.
HydraulicProfilePoint
dataclass
¶
Station-based hydraulic state for downstream plotting and reporting.
water_surface_elevation is populated only for free-surface flow. For a
pressurised point the piezometric level is represented solely by
hydraulic_grade_elevation so consumers do not confuse HGL with a physical
free surface.
HydraulicProfileState
¶
Bases: StrEnum
Hydraulic meaning of a longitudinal profile point.
HeadLossComponents
dataclass
¶
Scalar head-loss components exposed by one outlet-control calculation.
Values are metres of head. None means the selected method does not calculate
that component as a distinct scalar; it must not be interpreted as zero.
ConvergenceRecord
dataclass
¶
Labelled numerical root result retained for engineering audit.
RootResult
dataclass
¶
Converged root and signed residual, in the caller's canonical units.
Iterations count midpoint evaluations; endpoint evaluation is excluded. The bracket contains the root for a continuous supplied function.
HydraulicWarning
dataclass
¶
Machine-readable warning code with a concise engineering-review message.
result_status
property
¶
Return the minimum result status implied by this warning.
HydraulicApplicabilityNotice
dataclass
¶
Machine-readable hydraulic limitation with its supporting source.
ManningRoughnessSelection
dataclass
¶
Resolved Manning value with its selection basis and source provenance.
used_default
property
¶
Return whether the value came from a library default rather than an override.
RoughnessApplicabilityNotice
dataclass
¶
Machine-readable limitation attached to a roughness fallback.
InletCoefficientSelection
dataclass
¶
Resolved inlet-control coefficient set with its selection basis and source.
used_default
property
¶
Return whether the value came from a geometry/material library default.
EntranceLossSelection
dataclass
¶
Resolved entrance-loss coefficient with its selection basis and source.
used_default
property
¶
Return whether the value came from a geometry/material library default.
ExitLossSelection
dataclass
¶
Resolved exit-loss coefficient with selection basis and source provenance.
used_default
property
¶
Return whether the HDS-5 reservoir/pool assumption supplied the value.
TailwaterResolution
dataclass
¶
Resolved absolute tailwater elevation and calculation provenance.
depth is relative to channel_invert_elevation for a Manning
boundary; it is not culvert-outlet-relative tailwater depth.
InventorySummary
dataclass
¶
Normalized crossing rows and deduplicated adopted calculation parameters.
from_inventory(inventory, warnings=())
classmethod
¶
Build deterministic summaries and deduplicate typed configured components.
CrossingSummary
dataclass
¶
Compact calculation summary for one identified crossing.
GroupSummary
dataclass
¶
Compact solved result for one crossing group.
AdoptedParameterSet
dataclass
¶
One canonical set of empirical values actually adopted by a solved barrel.
FlowRegime
¶
Bases: StrEnum
Culvert hydraulic governing flow regimes.
ProfileCurve
¶
Bases: StrEnum
Supported gradually varied flow profile classifications.
HydraulicWarningCode
¶
Bases: StrEnum
Stable codes for supported calculations that retain a documented limitation.
HydraulicResultStatus
¶
Bases: StrEnum
Computational and hydraulic resolution status of a result.
ConvergenceCalculation
¶
Bases: StrEnum
Hydraulic calculation associated with a numerical root result.
ApplicabilityNoticeCode
¶
Bases: StrEnum
Stable codes for hydraulic and adopted-default applicability limitations.
RoughnessSelectionBasis
¶
Bases: StrEnum
How a resolved Manning roughness value was selected.
InletSelectionBasis
¶
Bases: StrEnum
How a resolved inlet-control coefficient set was selected.
EntranceLossSelectionBasis
¶
Bases: StrEnum
How a resolved entrance-loss coefficient was selected.
ExitLossSelectionBasis
¶
Bases: StrEnum
How a resolved exit-loss coefficient was selected.
TailwaterMethod
¶
Bases: StrEnum
Method used to obtain a downstream tailwater elevation.
TailwaterInterpolation
¶
Bases: StrEnum
How a tailwater rating curve supplied its resolved elevation.
InvalidInputError
¶
Bases: ValueError
An input violates the documented domain of a calculation.
ConvergenceError
¶
Bases: RuntimeError
A bracketed calculation exhausted iterations or floating-point resolution.