Hydraulic methods

Lower-level public calculations for applications that need to assemble or inspect a hydraulic workflow explicitly. All dimensions and hydraulic values use SI units.

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.

calculate_inlet_control_headwater(barrel, discharge, *, coefficients=None, g=GRAVITATIONAL_ACCELERATION)

Calculate the upstream headwater depth and elevation under inlet control.

Evaluates Form 1 or Form 2 unsubmerged weir flow, submerged orifice flow, or the project's cubic-Hermite implementation of the HDS-5 requirement for a smooth transition tangent to both bounding curves. This is not HY-8's fitted fifth-degree polynomial method.

calculate_modern_box_inlet_headwater(inlet, discharge, *, g=GRAVITATIONAL_ACCELERATION)

Evaluate the corrected Table 12 polynomial within its documented useful range.

unsubmerged_headwater_form_1(q_star, hc_over_d, slope, coefficients)

Compute unsubmerged headwater ratio HWi / D using HDS-5 Equation A.1.

HWi / D = Hc / D + K * (q*)^M + Ks * S

unsubmerged_headwater_form_2(q_star, coefficients)

Compute unsubmerged headwater ratio HWi / D using HDS-5 Equation A.2.

HWi / D = K * (q*)^M

submerged_headwater(q_star, slope, coefficients)

Compute submerged orifice headwater ratio HWi / D using HDS-5 Equation A.3.

HWi / D = c * (q*)² + Y + Ks * S

transition_headwater(q_star, hwi_d_unsub_at_limit, hwi_d_sub_at_threshold, unsubmerged_tangent, submerged_tangent, q_star_low=Q_STAR_UNSUBMERGED_LIMIT, q_star_high=Q_STAR_SUBMERGED_THRESHOLD)

Join inlet-control branches with a cubic curve tangent at both endpoints.

HDS-5 Appendix A, printed page A.1, specifies a curve drawn between and tangent to the unsubmerged and submerged curves, and printed page A.6 says the nomograph transition was drawn by hand. It does not prescribe a digital interpolation algorithm. Cubic Hermite interpolation is the project's deterministic C1 implementation of that construction; it is not HY-8's fitted polynomial method.

flow_parameter(discharge, area, rise, ku=KU_SI)

Compute the dimensionless discharge parameter q* = (Ku * Q) / (A * D^0.5).

calculate_full_flow_outlet_headwater(barrel, discharge, tailwater, entrance_loss_coefficient, exit_loss_coefficient=None, g=GRAVITATIONAL_ACCELERATION)

Calculate headwater elevation and losses for a culvert under full-flow outlet control.

Uses FHWA HDS-5 Section 3.1.4 energy balance: H = he + hf + ho HW_elevation = HGL_outlet + H HW_depth = HW_elevation - inlet_invert

where HGL_outlet is the hydraulic grade line elevation at the outlet invert: HGL_outlet = outlet_invert + h_o_eff h_o_eff = max(TW_depth, (dc + D) / 2)

Parameters:

Name	Type	Description	Default
barrel	CulvertBarrel	Culvert barrel domain model with geometry, inverts, length, and roughness.	required
discharge	float	Volumetric flow rate Q through the barrel (m³/s), must be strictly positive.	required
tailwater	TailwaterCondition | float	Downstream boundary condition as a TailwaterCondition object or absolute elevation (m).	required
entrance_loss_coefficient	float | EntranceLossCoefficient	Entrance loss coefficient Ke.	required
exit_loss_coefficient	float | None	Explicit exit loss coefficient Ko. If omitted, the sourced HDS-5 value of 1.0 for discharge into a reservoir or pool is adopted.	None
g	float	Gravitational acceleration (m/s²).	GRAVITATIONAL_ACCELERATION

Returns:

FullFlowOutletResult Comprehensive hydraulic result including headwater depth, headwater elevation, effective tailwater depth, component head losses, and velocity.

calculate_partial_flow_outlet_headwater(barrel, discharge, tailwater, entrance_loss_coefficient, num_steps=50, g=GRAVITATIONAL_ACCELERATION)

Calculate headwater elevation for partially full culvert outlet control via backwater.

Parameters:

Name	Type	Description	Default
barrel	CulvertBarrel	Culvert barrel domain model.	required
discharge	float	Discharge Q (m³/s), strictly positive.	required
tailwater	TailwaterCondition | float	Tailwater condition or elevation (m).	required
entrance_loss_coefficient	float | EntranceLossCoefficient	Entrance loss coefficient Ke.	required
num_steps	int	Number of steps for the direct-step integration.	50
g	float	Gravitational acceleration (m/s²).	GRAVITATIONAL_ACCELERATION

Returns:

PartialFlowOutletResult Comprehensive partial-flow outlet control result including full profile points.

calculate_downstream_full_flow_length(barrel, discharge, tailwater)

Return barrel length whose full-flow HGL is at or above the crown.

The downstream HGL starts at tailwater and rises upstream by the full-section Manning friction slope. A linear intersection with the sloping crown identifies whether the entire barrel or only a downstream segment can remain pressurised.

calculate_entrance_loss(velocity_head, ke)

Entrance loss he = Ke * hv in metres.

calculate_friction_loss(length, friction_slope)

Friction loss hf = L * Sf in metres.

calculate_exit_loss(velocity_head, ko=STANDARD_EXIT_LOSS_COEFFICIENT)

Exit loss ho = Ko * hv in metres.

calculate_total_head_loss(entrance_loss, friction_loss, exit_loss)

Total head loss H = he + hf + ho in metres.

compute_backwater_profile(barrel, discharge, tailwater, entrance_loss_coefficient, num_steps=50, g=GRAVITATIONAL_ACCELERATION)

Compute backwater free-surface profile along a culvert barrel via the direct-step method.

Integrates from downstream outlet (station = length) upstream towards the inlet (station = 0) for subcritical or drawdown profiles (M1, M2, H2, S1).

Parameters:

Name	Type	Description	Default
barrel	CulvertBarrel	Culvert barrel domain model.	required
discharge	float	Volumetric flow rate Q (m³/s), strictly positive.	required
tailwater	TailwaterCondition | float	Downstream tailwater condition or elevation (m).	required
entrance_loss_coefficient	float | EntranceLossCoefficient	Inlet entrance loss coefficient Ke.	required
num_steps	int	Number of direct-step depth increments.	50
g	float	Gravitational acceleration (m/s²).	GRAVITATIONAL_ACCELERATION

Returns:

WaterSurfaceProfile Computed profile points ordered from inlet (station 0.0) to outlet (station L), governing curve type, and upstream headwater elevation.

Notes:

This routine supports free-surface backwater curves and an upstream full-flow continuation when an M2 profile reaches the crown. A submerged outlet alone does not prove that the whole barrel is full; use the regime solver for that state.

compute_inlet_control_s2_profile(barrel, discharge, num_steps=25, g=GRAVITATIONAL_ACCELERATION)

Route an S2 profile downstream from critical depth toward normal depth.

This routine is limited to a positive, hydraulically steep, prismatic barrel where normal depth is below critical depth. It does not determine whether a downstream S1 profile or hydraulic jump intrudes into the barrel; the governing solver therefore uses it only for the unambiguous low-tailwater S2n case. The default depth discretisation is intended for rapid rating calculations; callers can increase num_steps for profile plotting or refinement checks.

compute_steep_inlet_control_profile(barrel, discharge, tailwater, num_steps=25, g=GRAVITATIONAL_ACCELERATION)

Resolve S2, swept-out-jump, in-barrel JS1, or inlet-reaching S1 flow.

The S2 profile is routed downstream and compared with the backward S1 profile using conjugate depths from equal momentum. A duplicated station at an identified jump records the pre- and post-jump depths explicitly.

calculate_roadway_overtopping(roadway, headwater_elevation, tailwater_elevation)

Calculate roadway flow from HDS-5 Equation 3.9 with bounded extensions.

Constant-elevation RoadwayWeir inputs preserve the original direct broad-crested-weir calculation. RoadwayProfileWeir inputs integrate the same equation over a piecewise-linear station/elevation profile using the four-point Gaussian procedure documented for FHWA HY8.

When tailwater is above a local crest, the paved or gravel submergence factor is linearly interpolated from the source-traceable digital ordinates through a downstream/upstream head ratio of 0.99. Ratios closer to equal stage fail closed because the digitised equal-stage ordinate would imply non-zero flow in this static capacity solver. Exactly equal upstream and downstream water levels return zero roadway flow.

calculate_critical_depth(geometry, discharge, *, g=GRAVITATIONAL_ACCELERATION, tolerances=_DEFAULT_CRITICAL_TOLERANCES)

Compute the critical depth where Froude number Fr = 1 (minimum specific energy).

For rectangular cross-sections, an exact closed-form analytical solution is used. For other geometries, the continuous relation gA(y)³ - Q²T(y) = 0 is solved using a bracket-preserving Brent solver.

calculate_normal_depth(geometry, discharge, slope, roughness, *, g=GRAVITATIONAL_ACCELERATION, tolerances=_DEFAULT_NORMAL_TOLERANCES)

Compute the uniform flow normal depth satisfying Manning's equation.

For circular conduits, solves strictly on the stable monotonically increasing branch (y <= 0.9382 * D), avoiding the non-monotone crown region.

calculate_channel_normal_depth(section, discharge, friction_slope, roughness, *, g=GRAVITATIONAL_ACCELERATION, initial_upper_depth=1.0, max_bracket_expansions=60, tolerances=_DEFAULT_CHANNEL_NORMAL_TOLERANCES)

Solve Manning normal depth for a prismatic open channel.

friction_slope is the Manning energy slope. A representative bed slope is commonly used only under the uniform-flow assumption.

calculate_sequent_depth(geometry, discharge, supercritical_depth, *, g=GRAVITATIONAL_ACCELERATION)

Return the subcritical conjugate depth for a supercritical approach.

The two depths have equal momentum functions. None means the conjugate free surface would reach or exceed the crown, so no free-surface root exists within the closed culvert section.

cross_section_velocity(discharge, area)

Mean cross-sectional velocity V = Q / A in metres per second.

velocity_head(velocity, g=GRAVITATIONAL_ACCELERATION)

Velocity head hv = V² / (2*g) in metres.

specific_energy(depth, velocity_head)

Specific energy E = y + hv in metres.

Assumes uniform velocity distribution (Coriolis coefficient alpha = 1).

water_surface_elevation_from_energy_grade(energy_grade_elevation, discharge, flow_area, g=GRAVITATIONAL_ACCELERATION)

Convert an energy-grade elevation to water level using approach velocity head.

The discharge and area must describe the same approach section. A unit velocity distribution coefficient is assumed.

froude_number(discharge, area, top_width, g=GRAVITATIONAL_ACCELERATION)

Froude number Fr = sqrt(Q² * T / (g * A³)) for free-surface flow.

Requires positive area, top width, and gravitational acceleration. Raises InvalidInputError for closed-conduit flow where top width is zero.

hydraulic_radius(section, depth)

Return hydraulic radius A/P for an open-channel section.

A dry section returns zero. A wet section with no positive wetted perimeter violates the geometry contract and fails explicitly.

manning_discharge(area, hydraulic_radius, slope, roughness)

Manning uniform discharge Q = (1 / n) * A * R^(2/3) * sqrt(S0) in cubic metres per second.

manning_friction_slope(discharge, area, hydraulic_radius, roughness)

Manning friction slope Sf = (n * |Q| / (A * R^(2/3)))² (dimensionless).

friction_head_loss(length, friction_slope)

Friction head loss hf = L * Sf in metres.

minor_head_loss(loss_coefficient, velocity_head)

Minor / local head loss h_local = K * hv in metres.

hydrostatic_pressure_moment(geometry, depth)

Return the hydrostatic first moment about the free surface in cubic metres.

Built-in geometries use exact expressions. A composite-Simpson fallback in :class:CrossSectionGeometry keeps the relation available to future shapes.

momentum_function(geometry, discharge, depth, *, g=GRAVITATIONAL_ACCELERATION)

Return open-channel momentum function Q^2/(g*A) + A*y_bar in m3.

dimension_mm_to_m(dimension_mm)

Convert a strictly positive culvert dimension in millimetres to metres.

solve_bracketed(function, lower, upper, *, tolerances=_DEFAULT_TOLERANCES, max_iterations=200)

Solve a continuous scalar function with opposite signs at finite bounds.

Caller owns continuity and hydraulic branch selection. This routine neither expands the bracket nor infers a physically admissible flow regime. Nonfinite function values fail immediately. User exceptions propagate unchanged.

solve_brent(function, lower, upper, *, tolerances=_DEFAULT_TOLERANCES, max_iterations=100)

Solve a continuous scalar function using Brent's method with guaranteed bracketing.

Combines bisection, secant, and inverse quadratic interpolation for superlinear convergence while strictly confining the solution within the bracket.

Parameters:

Name	Type	Description	Default
function	Callable[[float], float]	Continuous scalar function f(x).	required
lower	float	Lower bound of the bracket.	required
upper	float	Upper bound of the bracket, strictly greater than lower.	required
tolerances	RootTolerances	Convergence criteria for bracket width and residual.	_DEFAULT_TOLERANCES
max_iterations	int	Maximum allowed iterations, strictly positive.	100

Returns:

RootResult Converged root, residual, enclosing bracket, and iteration count.

resolve_inlet_coefficients(barrel, *, override=None, configuration=None)

Resolve inlet-control coefficients using override > barrel > geometry/material default.

Parameters:

Name	Type	Description	Default
barrel	CulvertBarrel	Culvert barrel domain model.	required
override	InletCoefficients | None	Explicit user-supplied coefficient set. Always wins when provided.	None
configuration	SolverConfiguration | None	Project configuration supplying defaults. Uses library defaults if None.	None

Returns:

InletCoefficientSelection Resolved coefficients with selection basis and source provenance.

resolve_modern_box_inlet_coefficients(inlet)

Resolve the unique corrected coefficient row for a supported physical inlet.

Unsupported or ambiguous combinations fail closed instead of falling back to a visually similar inlet.

resolve_entrance_loss_coefficient(barrel, *, override=None, override_source=None, configuration=None)

Resolve entrance-loss coefficient using override > barrel > geometry default.

Parameters:

Name	Type	Description	Default
barrel	CulvertBarrel	Culvert barrel domain model.	required
override	float | EntranceLossCoefficient | None	Explicit user-supplied Ke value or typed coefficient. Always wins.	None
override_source	SourceReference | None	Source provenance for a numeric override. Only valid with a numeric override.	None
configuration	SolverConfiguration | None	Project configuration supplying defaults. Uses library defaults if None.	None

Returns:

EntranceLossSelection Resolved Ke with selection basis and source provenance.

resolve_exit_loss_coefficient(override=None)

Resolve Ko from an optional numeric override or the sourced HDS-5 default.

resolve_manning_roughness(material, *, override=None, override_source=None, nominal_diameter_mm=None, csp_corrugation=None, allow_documented_fallback=False)

Resolve an overridable preliminary Manning value for hydraulic calculations.

Explicit positive overrides always win and may include a manufacturer or project source. Concrete pipe and box records use the current MRWA ranges. Context-dependent CSP requires diameter and corrugation. Plastic requires manufacturer data unless the caller explicitly opts into the documented HDS-5 fallback, which carries a notice.

resolve_csp_manning_roughness(nominal_diameter_mm, corrugation, *, override=None)

Resolve CSP Manning roughness using an override or MRWA Table 2.2.

A positive finite override always wins. Otherwise the diameter must be a listed MRWA nominal size; diameters at or above 1950 mm use the table's 1950 & Larger row. Unavailable corrugation/diameter combinations fail explicitly instead of borrowing a value from another pipe.