Solvers and rating curves

Use these functions for ordinary barrel, group, crossing, capacity, and rating-curve work.

Forward solvers accept the public TailwaterInput contract. Discharge-dependent boundaries are resolved using barrel discharge, total group discharge, or total crossing discharge as documented by each function; rating curves resolve the boundary again at every point. Inverse discharge-for-headwater helpers accept the same contract and solve the coupled HW(Q, TW(Q)) problem by resolving tailwater again at every candidate discharge. A bounded tailwater rating curve also bounds the admissible inverse-flow search; the solver never clamps or extrapolates that boundary.

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.

solve_barrel_hydraulics(barrel, discharge, tailwater, *, inlet_coefficients=None, entrance_loss_coefficient=None, entrance_loss_source=None, configuration=None, g=GRAVITATIONAL_ACCELERATION)

Solve the currently supported provisional single-barrel regimes.

Parameters:

Name	Type	Description	Default
barrel	CulvertBarrel	Culvert barrel domain model.	required
discharge	float	Discharge Q (m³/s), strictly positive.	required
tailwater	TailwaterInput	Absolute tailwater elevation (m) or a boundary resolved at this barrel discharge.	required
inlet_coefficients	InletCoefficients | None	Empirical inlet control coefficients.	None
entrance_loss_coefficient	float | EntranceLossCoefficient | None	Entrance loss coefficient Ke for outlet control.	None
entrance_loss_source	SourceReference | None	Provenance for a numeric entrance-loss override.	None
configuration	SolverConfiguration | None	Injectable project defaults used only when explicit and barrel values are absent.	None
g	float	Gravitational acceleration (m/s²).	GRAVITATIONAL_ACCELERATION

Returns:

BarrelHydraulicResult Hydraulic result including the selected regime, headwater, outlet velocity, and a typed longitudinal HGL/EGL profile where the hydraulic path is resolved.

Notes:

Supported outlet-control profile paths include S1/S2 profiles, hydraulic jumps, and selected mixed free-surface/full-flow states. Unsupported or unresolved transitions remain explicit in the result warnings.

solve_group_hydraulics(group, total_discharge, tailwater, *, inlet_coefficients=None, entrance_loss_coefficient=None, entrance_loss_source=None, configuration=None, g=GRAVITATIONAL_ACCELERATION)

Solve hydraulics for a group of N identical parallel culvert barrels.

Discharge is equally distributed across all N identical barrels: Q_barrel = Q_total / N

For N > 1, the result carries a structured representative-barrel applicability notice. The assumption supports total-flow calculation under sufficiently uniform approach conditions, but does not establish exact barrel-specific flow or velocity.

Parameters:

Name	Type	Description	Default
group	CulvertGroup	Group domain model containing barrel definition and barrel quantity N >= 1.	required
total_discharge	float	Total volumetric discharge through the entire culvert group (m³/s), strictly positive.	required
tailwater	TailwaterInput	Absolute tailwater elevation (m) or a boundary resolved at total group discharge.	required
inlet_coefficients	InletCoefficients | None	Inlet control regression constants.	None
entrance_loss_coefficient	float | EntranceLossCoefficient | None	Entrance loss coefficient Ke for outlet control.	None
entrance_loss_source	SourceReference | None	Provenance for a numeric entrance-loss override.	None
configuration	SolverConfiguration | None	Injectable project defaults used only when explicit and barrel values are absent.	None
g	float	Gravitational acceleration (m/s²).	GRAVITATIONAL_ACCELERATION

Returns:

GroupHydraulicResult Hydraulic solution for the group and its representative single barrel.

solve_crossing_hydraulics(crossing, total_discharge, tailwater, *, configuration=None, g=GRAVITATIONAL_ACCELERATION)

Solve hydraulics for a multi-group culvert crossing sharing upstream headwater.

Finds the common upstream headwater elevation HW_elev such that the sum of discharges across all culvert groups equals total_discharge: sum_i N_i * Q_i(HW_elev, TW_elev) = total_discharge

Parameters:

Name	Type	Description	Default
crossing	CulvertCrossing	Crossing domain model containing one or more culvert groups.	required
total_discharge	float	Total crossing discharge Q_crossing (m³/s), strictly positive.	required
tailwater	TailwaterInput	Absolute tailwater elevation (m) or a boundary resolved at total crossing discharge.	required
configuration	SolverConfiguration | None	Injectable defaults applied consistently to every group calculation.	None
g	float	Gravitational acceleration (m/s²).	GRAVITATIONAL_ACCELERATION

Returns:

CrossingHydraulicResult Hydraulic solution for the entire crossing and each constituent culvert group.

solve_barrel_discharge_for_headwater(barrel, headwater_elevation, tailwater, *, inlet_coefficients=None, entrance_loss_coefficient=None, entrance_loss_source=None, configuration=None, g=GRAVITATIONAL_ACCELERATION)

Solve for single-barrel discharge Q > 0 given a target upstream headwater elevation.

The optional coefficient arguments and configuration follow the same precedence contract as :func:solve_barrel_hydraulics. A TailwaterInput boundary is re-resolved at every candidate barrel discharge.

Returns 0.0 if headwater elevation is at or below the barrel inlet invert.

solve_barrel_discharge_for_headwater_ratio(barrel, headwater_ratio, tailwater, *, inlet_coefficients=None, entrance_loss_coefficient=None, entrance_loss_source=None, configuration=None, g=GRAVITATIONAL_ACCELERATION)

Solve barrel discharge for HW/D using the common TailwaterInput contract.

solve_group_discharge_for_headwater(group, headwater_elevation, tailwater, *, configuration=None, g=GRAVITATIONAL_ACCELERATION)

Return group discharge at a given HW using total flow for TailwaterInput resolution.

solve_crossing_discharge_for_headwater(crossing, headwater_elevation, tailwater, *, configuration=None, g=GRAVITATIONAL_ACCELERATION)

Return total crossing discharge while coupling flow to TailwaterInput stage.

generate_barrel_rating_curve(barrel, discharges, tailwater, *, inlet_coefficients=None, entrance_loss_coefficient=None, configuration=None, g=GRAVITATIONAL_ACCELERATION)

Generate a rating curve for a single culvert barrel across specified discharges.

Parameters:

Name	Type	Description	Default
barrel	CulvertBarrel	Culvert barrel domain model.	required
discharges	Sequence[float]	Sequence of strictly positive flow rates Q (m³/s), ordered monotonically.	required
tailwater	TailwaterInput	Absolute tailwater elevation (m) or a boundary resolved independently at each barrel discharge.	required
inlet_coefficients	InletCoefficients | None	Inlet control regression constants.	None
entrance_loss_coefficient	float | EntranceLossCoefficient | None	Inlet entrance loss coefficient Ke.	None
configuration	SolverConfiguration | None	Injectable defaults applied consistently to every rating point.	None
g	float	Gravitational acceleration (m/s²).	GRAVITATIONAL_ACCELERATION

Returns:

RatingCurveResult Rating curve points sorted by discharge.

generate_crossing_rating_curve(crossing, discharges, tailwater, *, configuration=None, g=GRAVITATIONAL_ACCELERATION)

Generate a rating curve for a multi-group road crossing across specified discharges.

Parameters:

Name	Type	Description	Default
crossing	CulvertCrossing	Culvert crossing domain model.	required
discharges	Sequence[float]	Sequence of strictly positive total crossing discharges Q (m³/s).	required
tailwater	TailwaterInput	Absolute tailwater elevation (m) or a boundary resolved independently at each total crossing discharge.	required
configuration	SolverConfiguration | None	Injectable defaults applied consistently to every crossing calculation.	None
g	float	Gravitational acceleration (m/s²).	GRAVITATIONAL_ACCELERATION

Returns:

RatingCurveResult Rating curve points sorted by discharge.

generate_discharge_range(min_discharge, max_discharge, num_points=11)

Generate linearly spaced positive discharges for rating curve evaluation.

Parameters:

Name	Type	Description	Default
min_discharge	float	Minimum discharge Q_min (m³/s), strictly positive.	required
max_discharge	float	Maximum discharge Q_max (m³/s), strictly greater than min_discharge.	required
num_points	int	Number of points in sequence, must be at least 2.	11

Returns:

tuple[float, ...] Linearly spaced sequence of discharges.

determine_governing_regime(barrel, discharge, tailwater, *, inlet_coefficients=None, entrance_loss_coefficient=None, entrance_loss_source=None, configuration=None, g=GRAVITATIONAL_ACCELERATION)

Determine the governing hydraulic control regime and calculate headwater elevation.

Compares physically admissible inlet- and outlet-control candidates. Supported profile paths include S1/S2, hydraulic jumps, and selected mixed free/full states; unresolved states retain structured warnings.

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 boundary condition or absolute elevation (m).	required
inlet_coefficients	InletCoefficients | None	Empirical inlet control regression coefficients.	None
entrance_loss_coefficient	float | EntranceLossCoefficient | None	Inlet entrance loss coefficient Ke for outlet control.	None
entrance_loss_source	SourceReference | None	Provenance for a numeric entrance-loss override.	None
configuration	SolverConfiguration | None	Injectable project defaults used only when explicit and barrel values are absent.	None
g	float	Gravitational acceleration (m/s²).	GRAVITATIONAL_ACCELERATION

Returns:

BarrelHydraulicResult Complete hydraulic result for the barrel including governing regime, headwater elevation, depths, and outlet velocity.

resolve_tailwater(tailwater, discharge, *, g=GRAVITATIONAL_ACCELERATION)

Resolve a numeric, fixed, or flow-dependent TailwaterInput boundary.