wntr.extensions.design_verification#

Hydraulic design-verification extension for WNTR.

The extension applies proposed pipe-diameter changes and WNTR time and hydraulic simulation options to independent copies of a water network model, runs hydraulic simulations, and evaluates engineering constraints.

Verification considers pipe diameter and the WNTR time and hydraulic simulation option groups.

exception DesignVerificationError[source]#

Bases: Exception

Base exception for design-verification failures.

classmethod __new__(*args, **kwargs)#
__init__(*args, **kwargs)#
add_note()#

Exception.add_note(note) – add a note to the exception

with_traceback()#

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#
exception IncompleteHydraulicResultsError[source]#

Bases: DesignVerificationError, RuntimeError

Raised when simulator results cannot support verification.

classmethod __new__(*args, **kwargs)#
__init__(*args, **kwargs)#
add_note()#

Exception.add_note(note) – add a note to the exception

with_traceback()#

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#
exception InvalidConstraintError[source]#

Bases: DesignVerificationError, ValueError

Raised when hydraulic constraint settings are invalid.

classmethod __new__(*args, **kwargs)#
__init__(*args, **kwargs)#
add_note()#

Exception.add_note(note) – add a note to the exception

with_traceback()#

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#
exception InvalidDesignError[source]#

Bases: DesignVerificationError, ValueError

Raised when a proposed pipe design is invalid.

classmethod __new__(*args, **kwargs)#
__init__(*args, **kwargs)#
add_note()#

Exception.add_note(note) – add a note to the exception

with_traceback()#

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#
class AllPumpCurveResult[source]#

Bases: object

Combined operating-curve result for every head pump.

__init__(head_pumps_in_network, head_pumps_evaluable, all_head_pumps_evaluable, all_pumps_passed, number_of_pumps_exceeding_curves, total_curve_exceedance_observations, governing_pump_name, maximum_pump_flow_ratio, pump_results)#
all_head_pumps_evaluable: bool#
all_pumps_passed: bool#
governing_pump_name: str | None#
head_pumps_evaluable: int#
head_pumps_in_network: int#
maximum_pump_flow_ratio: float | None#
number_of_pumps_exceeding_curves: int#
pump_results: tuple[PumpCurveResult, ...]#
total_curve_exceedance_observations: int#
class ConstraintResult[source]#

Bases: object

Store the result of one hydraulic-constraint assessment.

Parameters:

  • critical_value (float) – Minimum pressure or maximum absolute velocity found in the hydraulic-results table.

  • compliance_pct (float) – Percentage of assessed values satisfying the constraint.

  • feasible (bool) – Whether the required compliance percentage was achieved.

  • critical_component (str) – Name of the junction or pipe containing the critical value.

  • critical_time (Hashable) – Simulation time corresponding to the critical value.

__init__(critical_value, compliance_pct, feasible, critical_component, critical_time)#
compliance_pct: float#
critical_component: str#
critical_time: Hashable#
critical_value: float#
feasible: bool#
class HydraulicScenario[source]#

Bases: object

Describe simulation options for one hydraulic assessment.

Parameters:

  • name (str) – User-facing name for the hydraulic scenario.

  • options (Options) – WNTR simulation options. The design-verification extension applies the time and hydraulic option groups to an independent copy of the water network model.

__init__(name, options)#
name: str#
options: Options#
class PipeDesign[source]#

Bases: object

Describe proposed diameter changes for selected pipes.

Parameters:

  • name (str) – User-facing name for the design alternative.

  • diameters_m (Mapping[str, float]) – Mapping of pipe names to proposed diameters in metres.

__init__(name, diameters_m)#
diameters_m: Mapping[str, float]#
name: str#
class PumpCurveResult[source]#

Bases: object

Result of auditing one head pump against its operating curve.

__init__(pump_name, curve_name, evaluable, passed, active_observations, exceedance_observations, curve_maximum_flow_m3s, maximum_active_flow_m3s, maximum_allowed_flow_m3s, maximum_flow_ratio, critical_time)#
active_observations: int#
critical_time: Hashable | None#
curve_maximum_flow_m3s: float | None#
curve_name: str | None#
evaluable: bool#
exceedance_observations: int#
maximum_active_flow_m3s: float | None#
maximum_allowed_flow_m3s: float | None#
maximum_flow_ratio: float | None#
passed: bool#
pump_name: str#
class VerificationResult[source]#

Bases: object

Store the combined result of one hydraulic verification run.

Parameters:

  • design_name (str or None) – Name of the applied pipe design, or None for the unchanged baseline network.

  • scenario_name (str) – Name of the hydraulic scenario.

  • simulator_name (str) – Name of the hydraulic simulator used.

  • pressure_result (ConstraintResult) – Minimum-pressure constraint result.

  • velocity_result (ConstraintResult) – Maximum-velocity constraint result.

  • feasible (bool) – Whether pressure, velocity and applicable pump operating-curve requirements were met.

  • simulation_error_code (int or None) – Simulator error code, when one is supplied by WNTR.

  • pump_result (AllPumpCurveResult or None) – Head-pump operating-curve audit result, when available.

__init__(design_name, scenario_name, simulator_name, pressure_result, velocity_result, feasible, simulation_error_code=None, pump_result=None)#
design_name: str | None#
feasible: bool#
pressure_result: ConstraintResult#
pump_result: AllPumpCurveResult | None = None#
scenario_name: str#
simulation_error_code: int | None = None#
simulator_name: str#
velocity_result: ConstraintResult#
apply_hydraulic_scenario(wn, scenario)[source]#

Apply hydraulic simulation options to an independent network copy.

The verification scenario changes only the WNTR time and hydraulic simulation option groups. The original WaterNetworkModel is not modified.

Parameters:
Returns:

  • scenario_wn (WaterNetworkModel) – Independent network copy containing the selected time and hydraulic simulation options.

  • audit (dict) – Dictionary recording the original and applied simulation options.

Return type:

tuple[WaterNetworkModel, dict[str, object]]

apply_pipe_design(wn, design)[source]#

Apply selected pipe-diameter changes to a copied network.

The original WaterNetworkModel is not modified.

Parameters:

  • wn (WaterNetworkModel) – Original WNTR water-distribution network model.

  • design (PipeDesign) – Proposed pipe-diameter changes in metres.

Returns:

  • trial_wn (WaterNetworkModel) – Independent copy of the original network containing the proposed diameter changes.

  • audit_records (list of dict) – Records containing each pipe’s original and proposed diameter.

Raises:

  • TypeError – If wn is not a WaterNetworkModel or design is not a PipeDesign.

  • ValueError – If the design name is empty, the design contains no changes, or a proposed diameter is invalid.

  • KeyError – If a named pipe does not exist in the network.

Return type:

tuple[WaterNetworkModel, list[dict[str, float | str]]]

audit_head_pump_curves(network, flowrate, *, status=None, setting=None, relative_tolerance=1e-09)[source]#

Audit every head pump against the maximum flow in its curve.

Pump affinity scaling is respected by multiplying the maximum curve-point flow by the pump speed reported in the hydraulic setting result. When no setting result is supplied, the pump’s configured base speed is used.

Parameters:

  • network (WaterNetworkModel) – WNTR water-network model used for the simulation.

  • flowrate (pd.DataFrame) – Link-flowrate results indexed by simulation time.

  • status (pd.DataFrame or None, optional) – Optional link-status results. Positive values are treated as active.

  • setting (pd.DataFrame or None, optional) – Optional link-setting results. For pumps, this represents speed.

  • relative_tolerance (float, optional) – Relative numerical tolerance applied to the curve-domain limit.

evaluate_maximum_velocity(velocity, maximum_velocity_mps, required_compliance_pct=100.0, velocity_tolerance_mps=0.0)[source]#

Evaluate maximum absolute pipe-velocity compliance.

Parameters:

  • velocity (pd.DataFrame) – Pipe-velocity results. Rows represent simulation times and columns represent pipe names.

  • maximum_velocity_mps (float) – Maximum allowable absolute velocity in metres per second.

  • required_compliance_pct (float, optional) – Percentage of pipe-time values required to satisfy the velocity limit.

  • velocity_tolerance_mps (float, optional) – Non-negative numerical tolerance applied above the maximum absolute velocity limit. The default of zero preserves strict comparison behaviour.

Returns:

Velocity-compliance result and critical location.

Return type:

ConstraintResult

evaluate_minimum_pressure(pressure, minimum_pressure_m, required_compliance_pct=100.0, pressure_tolerance_m=0.0)[source]#

Evaluate minimum-pressure compliance.

Parameters:

  • pressure (pd.DataFrame) – Junction-pressure results. Rows represent simulation times and columns represent junction names.

  • minimum_pressure_m (float) – Minimum allowable pressure head in metres.

  • required_compliance_pct (float, optional) – Percentage of junction-time values required to satisfy the pressure limit.

  • pressure_tolerance_m (float, optional) – Non-negative numerical tolerance applied below the minimum pressure limit. The default of zero preserves strict comparison behaviour.

Returns:

Pressure-compliance result and critical location.

Return type:

ConstraintResult

run_design_verification(wn, scenario, *, design=None, simulator='WNTRSimulator', minimum_pressure_m=15.0, maximum_velocity_mps=2.5, required_compliance_pct=100.0, pressure_tolerance_m=0.0, velocity_tolerance_mps=0.0)[source]#

Run one hydraulic design-verification assessment.

The original network is protected from modification. Pipe-diameter changes and hydraulic simulation-option changes are applied to independent copies.

Parameters:

  • wn (WaterNetworkModel) – Original WNTR water-distribution network model.

  • scenario (HydraulicScenario) – WNTR time and hydraulic simulation options to assess.

  • design (PipeDesign or None, optional) – Optional pipe-diameter design. If omitted, the unchanged baseline network is assessed.

  • simulator (str, optional) – Hydraulic simulation engine. Accepted values are WNTRSimulator and EpanetSimulator.

  • minimum_pressure_m (float, optional) – Minimum acceptable junction pressure in metres.

  • maximum_velocity_mps (float, optional) – Maximum acceptable absolute pipe velocity in metres per second.

  • required_compliance_pct (float, optional) – Required percentage of assessed node-time and pipe-time values satisfying each constraint.

  • pressure_tolerance_m (float, optional) – Non-negative numerical tolerance applied below the minimum pressure limit. The default of zero preserves strict comparison behaviour.

  • velocity_tolerance_mps (float, optional) – Non-negative numerical tolerance applied above the maximum absolute velocity limit. The default of zero preserves strict comparison behaviour.

Returns:

  • verification (VerificationResult) – Structured pressure, velocity, pump and overall feasibility result.

  • hydraulic_results (Any) – Raw WNTR hydraulic simulation results.

  • audit (dict) – Record of the applied design, scenario, simulator and assessed components.

Return type:

tuple[VerificationResult, Any, dict[str, object]]

run_verification_batch(wn, scenarios, *, designs=None, simulators=('WNTRSimulator',), minimum_pressure_m=15.0, maximum_velocity_mps=2.5, required_compliance_pct=100.0, pressure_tolerance_m=0.0, velocity_tolerance_mps=0.0, continue_on_error=True, retain_hydraulic_results=False)[source]#

Run every requested design-scenario-simulator combination.

Parameters:

  • wn (WaterNetworkModel) – Original WNTR water-distribution network.

  • scenarios (Sequence[HydraulicScenario]) – Hydraulic scenarios containing WNTR time and hydraulic options.

  • designs (Sequence[PipeDesign | None] or None, optional) – Pipe-diameter designs to assess. Use None for the unchanged baseline network. When omitted, only the baseline is assessed.

  • simulators (Sequence[str] or str, optional) – WNTRSimulator or EpanetSimulator, or a sequence containing those names.

  • minimum_pressure_m (float, optional) – Minimum acceptable junction pressure.

  • maximum_velocity_mps (float, optional) – Maximum acceptable absolute pipe velocity.

  • required_compliance_pct (float, optional) – Required pressure and velocity compliance percentage.

  • pressure_tolerance_m (float, optional) – Numerical tolerance below the minimum pressure limit.

  • velocity_tolerance_mps (float, optional) – Numerical tolerance above the maximum velocity limit.

  • continue_on_error (bool, optional) – Record an experiment failure and continue when True.

  • retain_hydraulic_results (bool, optional) – Retain raw hydraulic result objects in returned records.

Returns:

  • summary (pd.DataFrame) – One row per requested experiment.

  • records (dict) – Detailed records keyed by experiment ID.

Return type:

tuple[DataFrame, dict[str, dict[str, Any]]]

Modules

batch

Run reproducible batches of hydraulic design-verification experiments.

constraints

Hydraulic-constraint calculations for design verification.

design

Apply proposed pipe-design changes to a WNTR model.

exceptions

Exceptions raised by hydraulic design verification.

models

Data models for hydraulic design verification.

pumps

Head-pump operating-curve auditing for hydraulic verification.

runner

Run hydraulic simulations and verify design constraints.

scenarios

Apply hydraulic simulation options to WNTR models.