wntr.network.elements module¶

The wntr.network.elements module includes elements of a water network model, including junction, tank, reservoir, pipe, pump, valve, pattern, timeseries, demands, curves, and sources.

Contents

 Junction(name, wn) Junction class, inherited from Node. Tank(name, wn) Tank class, inherited from Node. Reservoir(name, wn[, base_head, head_pattern]) Reservoir class, inherited from Node Pipe(name, start_node_name, end_node_name, wn) Pipe class, inherited from Link. Pump(name, start_node_name, end_node_name, wn) Pump class, inherited from Link. HeadPump(name, start_node_name, ...) Head pump class, inherited from Pump. PowerPump(name, start_node_name, ...) Power pump class, inherited from Pump. Valve(name, start_node_name, end_node_name, wn) Valve class, inherited from Link. PRValve(name, start_node_name, end_node_name, wn) Pressure reducing valve class, inherited from Valve. PSValve(name, start_node_name, end_node_name, wn) Pressure sustaining valve class, inherited from Valve. PBValve(name, start_node_name, end_node_name, wn) Pressure breaker valve class, inherited from Valve. FCValve(name, start_node_name, end_node_name, wn) Flow control valve class, inherited from Valve. TCValve(name, start_node_name, end_node_name, wn) Throttle control valve class, inherited from Valve. GPValve(name, start_node_name, end_node_name, wn) General purpose valve class, inherited from Valve. Pattern(name[, multipliers, time_options, wrap]) Pattern class. TimeSeries(model, base[, pattern_name, category]) Time series class. Demands(patterns, *args) Demands class. Curve(name[, curve_type, points, ...]) Curve base class. Source(model, name, node_name, source_type, ...) Water quality source class.
class wntr.network.elements.Junction(name, wn)[source]

Bases: Node

Junction class, inherited from Node.

Junctions are the nodes that contain demand, emitters, and water quality sources.

Constructor

This class is intended to be instantiated through the add_junction() method. Direct creation through the constructor is highly discouraged.

Parameters

Attributes

 name The name of the node (read only) node_type "Junction" (read only) head (read-only) the current simulation head at the node (total head) demand (read-only) the current simulation demand at the node (actual demand) demand_timeseries_list list of demand patterns and base multipliers elevation elevation of the junction required_pressure The required pressure attribute is used for pressure-dependent demand simulations. minimum_pressure The minimum pressure attribute is used for pressure-dependent demand simulations. pressure_exponent The pressure exponent attribute is used for pressure-dependent demand simulations. emitter_coefficient if not None, then activate an emitter with the specified coefficient base_demand Get the base_value of the first demand in the demand_timeseries_list. coordinates The node coordinates, (x,y) initial_quality The initial quality (concentration) at the node tag A tag or label for the node

Read-only simulation results

 demand (read-only) the current simulation demand at the node (actual demand) head (read-only) the current simulation head at the node (total head) pressure (read-only) the current simulation pressure at the node quality (read-only) the current simulation quality at the node leak_demand (read-only) the current simulation leak demand at the node leak_status (read-only) the current simulation leak status at the node leak_area (read-only) the current simulation leak area at the node leak_discharge_coeff (read-only) the current simulation leak discharge coefficient
property elevation

elevation of the junction

Type

float

property demand_timeseries_list

list of demand patterns and base multipliers

Type

Demands

property required_pressure

The required pressure attribute is used for pressure-dependent demand simulations. This is the lowest pressure at which the junction receives the full requested demand. If set to None, the global value in wn.options.hydraulic.required_pressure is used.

Type

float

property minimum_pressure

The minimum pressure attribute is used for pressure-dependent demand simulations. Below this pressure, the junction will not receive any water. If set to None, the global value in wn.options.hydraulic.minimum_pressure is used.

Type

float

property pressure_exponent

The pressure exponent attribute is used for pressure-dependent demand simulations. If set to None, the global value in wn.options.hydraulic.pressure_exponent is used.

Type

float

property emitter_coefficient

if not None, then activate an emitter with the specified coefficient

Type

float

property nominal_pressure

deprecated - use required pressure

property node_type

"Junction" (read only)

Type

str

add_demand(base, pattern_name, category=None)[source]

Add a new demand entry to the Junction

Parameters
• base (float) – The base demand value for this new entry

• pattern_name (str or None) – The name of the pattern to use or None for a constant value

• category (str, optional) – A category name for this demand

property base_demand

Get the base_value of the first demand in the demand_timeseries_list.

This is a read-only property.

add_leak(wn, area, discharge_coeff=0.75, start_time=None, end_time=None)[source]

Add a leak control to the water network model

Leaks are modeled by:

Q = discharge_coeff*area*sqrt(2*g*h)

where:

Q is the volumetric flow rate of water out of the leak g is the acceleration due to gravity h is the gauge head at the junction, P_g/(rho*g); Note that this is not the hydraulic head (P_g + elevation)

Parameters
• wn (WaterNetworkModel) – Water network model containing the junction with the leak. This information is needed because the WaterNetworkModel object stores all controls, including when the leak starts and stops.

• area (float) – Area of the leak in m^2.

• discharge_coeff (float) – Leak discharge coefficient; Takes on values between 0 and 1.

• start_time (int) – Start time of the leak in seconds. If the start_time is None, it is assumed that an external control will be used to start the leak (otherwise, the leak will not start).

• end_time (int) – Time at which the leak is fixed in seconds. If the end_time is None, it is assumed that an external control will be used to end the leak (otherwise, the leak will not end).

remove_leak(wn)[source]

Remove a leak control from the water network model

Parameters

wn (WaterNetworkModel) – Water network model

add_fire_fighting_demand(wn, fire_flow_demand, fire_start, fire_end, pattern_name=None)[source]

Add a new fire flow demand entry to the Junction

Parameters
• wn (WaterNetworkModel) – Water network model

• fire_flow_demand (float) – Fire flow demand

• fire_start (int) – Start time of the fire flow in seconds.

• fire_end (int) – End time of the fire flow in seconds.

• pattern_name (str or None) – Pattern name. If pattern name is None, the pattern name is assigned to junction name + ‘_fire’

remove_fire_fighting_demand(wn)[source]

Removes a fire flow demand entry to the Junction

Parameters

wn (WaterNetworkModel) – Water network model

property coordinates

The node coordinates, (x,y)

Type

tuple

property demand

(read-only) the current simulation demand at the node (actual demand)

Type

float

property head

(read-only) the current simulation head at the node (total head)

Type

float

property initial_quality

The initial quality (concentration) at the node

Type

float

property leak_area

(read-only) the current simulation leak area at the node

Type

float

property leak_demand

(read-only) the current simulation leak demand at the node

Type

float

property leak_discharge_coeff

(read-only) the current simulation leak discharge coefficient

Type

float

property leak_status

(read-only) the current simulation leak status at the node

Type

bool

property name

The name of the node (read only)

Type

str

property pressure

(read-only) the current simulation pressure at the node

Type

float

property quality

(read-only) the current simulation quality at the node

Type

float

property tag

A tag or label for the node

Type

str

to_dict()

Dictionary representation of the node

class wntr.network.elements.Tank(name, wn)[source]

Bases: Node

Tank class, inherited from Node.

Tank volume can be defined using a constant diameter or a volume curve. If the tank has a volume curve, the diameter has no effect on hydraulic simulations.

Constructor

This class is intended to be instantiated through the add_tank() method. Direct creation through the constructor is highly discouraged.

Parameters

Attributes

 name The name of the node (read only) node_type returns "Tank" head (read-only) the current simulation head at the node (total head) demand (read-only) the current simulation demand at the node (actual demand) elevation elevation to the bottom of the tank. init_level The initial tank level at the start of simulation min_level minimum level for the tank to be able to drain max_level maximum level before tank begins to overflow (if permitted) diameter diameter of the tank as a cylinder min_vol minimum volume to be able to drain (when using a tank curve) vol_curve_name Name of the volume curve to use, or None vol_curve The volume curve, if defined (read only) overflow Is this tank allowed to overflow mixing_model The mixing model to be used by EPANET. mixing_fraction for water quality simulations only, the compartment size for 2-compartment mixing bulk_coeff bulk reaction coefficient for this tank only; leave None to use global value coordinates The node coordinates, (x,y) initial_quality The initial quality (concentration) at the node tag A tag or label for the node

Read-only simulation results

 head (read-only) the current simulation head at the node (total head) level (read-only) the current simulation tank level (= head - elevation) pressure (read-only) the current simulation pressure (head - elevation) quality (read-only) the current simulation quality at the node leak_demand (read-only) the current simulation leak demand at the node leak_status (read-only) the current simulation leak status at the node leak_area (read-only) the current simulation leak area at the node leak_discharge_coeff (read-only) the current simulation leak discharge coefficient
property elevation

elevation to the bottom of the tank. head = level + elevation

Type

float

property min_level

minimum level for the tank to be able to drain

Type

float

property max_level

maximum level before tank begins to overflow (if permitted)

Type

float

property diameter

diameter of the tank as a cylinder

Type

float

property min_vol

minimum volume to be able to drain (when using a tank curve)

Type

float

property mixing_model

The mixing model to be used by EPANET. This only affects water quality simulations and has no impact on the WNTRSimulator. Uses the MixType enum object, or it will convert string values from MIXED, 2COMP, FIFO and LIFO. By default, this is set to None, and will produce no output in the EPANET INP file and EPANET will assume complete and instantaneous mixing (MIXED).

property mixing_fraction

for water quality simulations only, the compartment size for 2-compartment mixing

Type

float

property bulk_coeff

bulk reaction coefficient for this tank only; leave None to use global value

Type

float

property init_level

The initial tank level at the start of simulation

property node_type

returns "Tank"

property vol_curve

The volume curve, if defined (read only)

Set this using the vol_curve_name.

property vol_curve_name

Name of the volume curve to use, or None

property overflow

Is this tank allowed to overflow

Type

bool

property level

(read-only) the current simulation tank level (= head - elevation)

Type

float

property pressure

(read-only) the current simulation pressure (head - elevation)

Type

float

get_volume(level=None)[source]

Returns tank volume at a given level

Parameters

level (float or NoneType (optional)) – The level at which the volume is to be calculated. If level=None, then the volume is calculated at the current tank level (self.level)

Returns

vol (float) – Tank volume at a given level

add_leak(wn, area, discharge_coeff=0.75, start_time=None, end_time=None)[source]

Add a leak to a tank.

Leaks are modeled by:

Q = discharge_coeff*area*sqrt(2*g*h)

where:

Q is the volumetric flow rate of water out of the leak g is the acceleration due to gravity h is the gauge head at the bottom of the tank, P_g/(rho*g); Note that this is not the hydraulic head (P_g + elevation)

Note that WNTR assumes the leak is at the bottom of the tank.

Parameters
• wn (WaterNetworkModel) – The WaterNetworkModel object containing the tank with the leak. This information is needed because the WaterNetworkModel object stores all controls, including when the leak starts and stops.

• area (float) – Area of the leak in m^2.

• discharge_coeff (float) – Leak discharge coefficient; Takes on values between 0 and 1.

• start_time (int) – Start time of the leak in seconds. If the start_time is None, it is assumed that an external control will be used to start the leak (otherwise, the leak will not start).

• end_time (int) – Time at which the leak is fixed in seconds. If the end_time is None, it is assumed that an external control will be used to end the leak (otherwise, the leak will not end).

remove_leak(wn)[source]

Remove a leak from a tank

Parameters

wn (WaterNetworkModel) – Water network model

property coordinates

The node coordinates, (x,y)

Type

tuple

property demand

(read-only) the current simulation demand at the node (actual demand)

Type

float

property head

(read-only) the current simulation head at the node (total head)

Type

float

property initial_quality

The initial quality (concentration) at the node

Type

float

property leak_area

(read-only) the current simulation leak area at the node

Type

float

property leak_demand

(read-only) the current simulation leak demand at the node

Type

float

property leak_discharge_coeff

(read-only) the current simulation leak discharge coefficient

Type

float

property leak_status

(read-only) the current simulation leak status at the node

Type

bool

property name

The name of the node (read only)

Type

str

property quality

(read-only) the current simulation quality at the node

Type

float

property tag

A tag or label for the node

Type

str

to_dict()

Dictionary representation of the node

class wntr.network.elements.Reservoir(name, wn, base_head=0.0, head_pattern=None)[source]

Bases: Node

Reservoir class, inherited from Node

Constructor

This class is intended to be instantiated through the add_reservoir() method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the reservoir.

• wn (WaterNetworkModel) – The water network model this reservoir will belong to.

• base_head (float, optional) – Base head at the reservoir. Internal units must be meters (m).

• head_pattern (str, optional) – Head pattern name

Attributes

 name The name of the node (read only) node_type "Reservoir" (read only) base_head The constant head (elevation) for the reservoir, or the base value for a head timeseries head_pattern_name Name of the head pattern to use head_timeseries The head timeseries for the reservoir (read only) tag A tag or label for the node initial_quality The initial quality (concentration) at the node coordinates The node coordinates, (x,y)

Read-only simulation results

 demand (read-only) the current simulation demand at the node (actual demand) head (read-only) the current simulation head at the node (total head) pressure (read-only) the current simulation pressure (0.0 for reservoirs) quality (read-only) the current simulation quality at the node
property node_type

"Reservoir" (read only)

property head_timeseries

The head timeseries for the reservoir (read only)

property base_head

The constant head (elevation) for the reservoir, or the base value for a head timeseries

property head_pattern_name

Name of the head pattern to use

Type

str

property pressure

(read-only) the current simulation pressure (0.0 for reservoirs)

Type

float

property coordinates

The node coordinates, (x,y)

Type

tuple

property demand

(read-only) the current simulation demand at the node (actual demand)

Type

float

property head

(read-only) the current simulation head at the node (total head)

Type

float

property initial_quality

The initial quality (concentration) at the node

Type

float

property leak_area

(read-only) the current simulation leak area at the node

Type

float

property leak_demand

(read-only) the current simulation leak demand at the node

Type

float

property leak_discharge_coeff

(read-only) the current simulation leak discharge coefficient

Type

float

property leak_status

(read-only) the current simulation leak status at the node

Type

bool

property name

The name of the node (read only)

Type

str

property quality

(read-only) the current simulation quality at the node

Type

float

property tag

A tag or label for the node

Type

str

to_dict()

Dictionary representation of the node

class wntr.network.elements.Pipe(name, start_node_name, end_node_name, wn)[source]

Bases: Link

Pipe class, inherited from Link.

Constructor

This class is intended to be instantiated through the add_pipe() method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the pipe

• start_node_name (string) – Name of the start node

• end_node_name (string) – Name of the end node

• wn (WaterNetworkModel) – The water network model this pipe will belong to.

Attributes

 name The link name (read-only) start_node_name The name of the start node (read only) end_node_name The name of the end node (read only) link_type returns "Pipe" length length of the pipe diameter diameter of the pipe roughness pipe roughness minor_loss minor loss coefficient cv does this pipe have a check valve bulk_coeff if not None, then a pipe specific bulk reaction coefficient wall_coeff if not None, then a pipe specific wall reaction coefficient initial_status The initial status (Opened, Closed, Active) of the Link start_node The start node object. end_node The end node object. tag A tag or label for this link vertices A list of curve points, in the direction of start node to end node.

Read-only simulation results

 flow (read-only) current simulated flow through the link velocity (read-only) current simulated velocity through the link headloss (read-only) current simulated headloss friction_factor (read-only) the current simulation friction factor in the pipe reaction_rate (read-only) the current simulation reaction rate in the pipe quality (read-only) current simulated average link quality status the current status of the pipe

returns "Pipe"

property length

length of the pipe

Type

float

property diameter

diameter of the pipe

Type

float

property roughness

pipe roughness

Type

float

property minor_loss

minor loss coefficient

Type

float

property cv

does this pipe have a check valve

Type

bool

property bulk_coeff

if not None, then a pipe specific bulk reaction coefficient

Type

float or None

property wall_coeff

if not None, then a pipe specific wall reaction coefficient

Type

float or None

property status

the current status of the pipe

Type

LinkStatus

property friction_factor

(read-only) the current simulation friction factor in the pipe

Type

float

property reaction_rate

(read-only) the current simulation reaction rate in the pipe

Type

float

property end_node

The end node object.

Type

Node

property end_node_name

The name of the end node (read only)

Type

str

property flow

(read-only) current simulated flow through the link

Type

float

property headloss

(read-only) current simulated headloss

Type

float

property initial_setting

The initial setting for the link (if Active)

Type

float

property initial_status

The initial status (Opened, Closed, Active) of the Link

Type

LinkStatus

property name

The link name (read-only)

Type

str

property quality

(read-only) current simulated average link quality

Type

float

property setting

(read-only) current simulated setting of the link

Type

float

property start_node

The start node object.

Type

Node

property start_node_name

The name of the start node (read only)

Type

str

property tag

A tag or label for this link

Type

str

to_dict()

Dictionary representation of the link

property velocity

(read-only) current simulated velocity through the link

Type

float

property vertices

A list of curve points, in the direction of start node to end node.

The vertices should be listed as a list of (x,y) tuples when setting.

class wntr.network.elements.Pump(name, start_node_name, end_node_name, wn)[source]

Bases: Link

Pump class, inherited from Link.

For details about the different subclasses, please see one of the following: HeadPump and PowerPump

Constructor

This class is intended to be instantiated through the add_pump method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the pump

• start_node_name (string) – Name of the start node

• end_node_name (string) – Name of the end node

• wn (WaterNetworkModel) – The water network model this pump will belong to.

Attributes

 name The link name (read-only) link_type "Pump" (read only) start_node The start node object. start_node_name The name of the start node (read only) end_node The end node object. end_node_name The name of the end node (read only) initial_status The initial status (Opened, Closed, Active) of the Link initial_setting The initial setting for the link (if Active) speed_timeseries timeseries of speed values (retrieve only) efficiency pump efficiency energy_price energy price surcharge (only used by EPANET) energy_pattern energy pattern name tag A tag or label for this link vertices A list of curve points, in the direction of start node to end node.

Read-only simulation results

 flow (read-only) current simulated flow through the link headloss (read-only) current simulated headloss velocity (read-only) current simulated velocity through the link quality (read-only) current simulated average link quality status the current status of the pump setting Alias to speed for consistency with other link types
property efficiency

pump efficiency

Type

float

property energy_price

energy price surcharge (only used by EPANET)

Type

float

property energy_pattern

energy pattern name

Type

str

property status

the current status of the pump

Type

LinkStatus

"Pump" (read only)

Type

str

property speed_timeseries

timeseries of speed values (retrieve only)

Type

TimeSeries

property base_speed

base multiplier for a speed timeseries

Type

float

property speed_pattern_name

pattern name for the speed

Type

str

property setting

Alias to speed for consistency with other link types

add_outage(wn, start_time, end_time=None, priority=6, add_after_outage_rule=False)[source]

Add a pump outage rule to the water network model.

Parameters
• model (WaterNetworkModel) – The water network model this outage will belong to.

• start_time (int) – The time at which the outage starts.

• end_time (int) – The time at which the outage stops.

• priority (int) – The outage rule priority, default = 6 (very high)

• add_after_outage_rule (bool) – Flag indicating if a rule is added to open the pump after the outage. Pump status after the outage is generally defined by existing controls/rules in the water network model. For example, the pump opens based on the level of a specific tank.

remove_outage(wn)[source]

Remove an outage control from the water network model

Parameters

wn (WaterNetworkModel) – Water network model

property end_node

The end node object.

Type

Node

property end_node_name

The name of the end node (read only)

Type

str

property flow

(read-only) current simulated flow through the link

Type

float

property headloss

(read-only) current simulated headloss

Type

float

property initial_setting

The initial setting for the link (if Active)

Type

float

property initial_status

The initial status (Opened, Closed, Active) of the Link

Type

LinkStatus

property name

The link name (read-only)

Type

str

property quality

(read-only) current simulated average link quality

Type

float

property start_node

The start node object.

Type

Node

property start_node_name

The name of the start node (read only)

Type

str

property tag

A tag or label for this link

Type

str

to_dict()

Dictionary representation of the link

property velocity

(read-only) current simulated velocity through the link

Type

float

property vertices

A list of curve points, in the direction of start node to end node.

The vertices should be listed as a list of (x,y) tuples when setting.

class wntr.network.elements.HeadPump(name, start_node_name, end_node_name, wn)[source]

Bases: Pump

Head pump class, inherited from Pump.

This type of pump uses a pump curve (see curves). The curve is set using the pump_curve_name attribute. The curve itself can be accessed using the get_pump_curve() method.

Constructor

This class is intended to be instantiated through the add_pump method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the pump

• start_node_name (string) – Name of the start node

• end_node_name (string) – Name of the end node

• wn (WaterNetworkModel) – The water network model this pump will belong to.

Attributes

 name The link name (read-only) link_type "Pump" (read only) start_node The start node object. start_node_name The name of the start node (read only) end_node The end node object. end_node_name The name of the end node (read only) initial_status The initial status (Opened, Closed, Active) of the Link initial_setting The initial setting for the link (if Active) pump_type "HEAD" (read only) pump_curve_name the pump curve name speed_timeseries timeseries of speed values (retrieve only) efficiency pump efficiency energy_price energy price surcharge (only used by EPANET) energy_pattern energy pattern name tag A tag or label for this link vertices A list of curve points, in the direction of start node to end node.

Read-only simulation results

 flow (read-only) current simulated flow through the link headloss (read-only) current simulated headloss velocity (read-only) current simulated velocity through the link quality (read-only) current simulated average link quality status the current status of the pump setting Alias to speed for consistency with other link types
property pump_type

"HEAD" (read only)

Type

str

property pump_curve_name

the pump curve name

Type

str

get_pump_curve()[source]

Get the pump curve object

Returns

Curve – the head curve for this pump

get_head_curve_coefficients()[source]

Returns the A, B, C coefficients pump curves.

• For a single point curve, the coefficients are generated according to the following equation:

$$A = 4/3 * H$$

$$B = 1/3 * H/Q^2$$

$$C = 2$$

• For a two point curve, C is set to 1 and a straight line is fit between the points.

• For three point and multi-point curves, the coefficients are generated using scipy.optimize.curve_fit with the following equation:

$$H = A - B*Q^C$$

Returns

• Tuple of pump curve coefficient (A, B, C). All floats.

• The coefficients are only calculated the first time this function

• is called for a given HeadPump

get_design_flow()[source]

Returns the design flow value for the pump. Equals to the first point on the pump curve.

add_outage(wn, start_time, end_time=None, priority=6, add_after_outage_rule=False)

Add a pump outage rule to the water network model.

Parameters
• model (WaterNetworkModel) – The water network model this outage will belong to.

• start_time (int) – The time at which the outage starts.

• end_time (int) – The time at which the outage stops.

• priority (int) – The outage rule priority, default = 6 (very high)

• add_after_outage_rule (bool) – Flag indicating if a rule is added to open the pump after the outage. Pump status after the outage is generally defined by existing controls/rules in the water network model. For example, the pump opens based on the level of a specific tank.

property base_speed

base multiplier for a speed timeseries

Type

float

property efficiency

pump efficiency

Type

float

property end_node

The end node object.

Type

Node

property end_node_name

The name of the end node (read only)

Type

str

property energy_pattern

energy pattern name

Type

str

property energy_price

energy price surcharge (only used by EPANET)

Type

float

property flow

(read-only) current simulated flow through the link

Type

float

property headloss

(read-only) current simulated headloss

Type

float

property initial_setting

The initial setting for the link (if Active)

Type

float

property initial_status

The initial status (Opened, Closed, Active) of the Link

Type

LinkStatus

"Pump" (read only)

Type

str

property name

The link name (read-only)

Type

str

property quality

(read-only) current simulated average link quality

Type

float

remove_outage(wn)

Remove an outage control from the water network model

Parameters

wn (WaterNetworkModel) – Water network model

property setting

Alias to speed for consistency with other link types

property speed_pattern_name

pattern name for the speed

Type

str

property speed_timeseries

timeseries of speed values (retrieve only)

Type

TimeSeries

property start_node

The start node object.

Type

Node

property start_node_name

The name of the start node (read only)

Type

str

property status

the current status of the pump

Type

LinkStatus

property tag

A tag or label for this link

Type

str

to_dict()

Dictionary representation of the link

property velocity

(read-only) current simulated velocity through the link

Type

float

property vertices

A list of curve points, in the direction of start node to end node.

The vertices should be listed as a list of (x,y) tuples when setting.

class wntr.network.elements.PowerPump(name, start_node_name, end_node_name, wn)[source]

Bases: Pump

Power pump class, inherited from Pump.

This is a constant power type of pump. The constant power is set and modified through the power attribute.

Constructor

This class is intended to be instantiated through the add_pump method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the pump

• start_node_name (string) – Name of the start node

• end_node_name (string) – Name of the end node

• wn (WaterNetworkModel) – The water network model this pump will belong to.

Attributes

 name The link name (read-only) link_type "Pump" (read only) start_node The start node object. start_node_name The name of the start node (read only) end_node The end node object. end_node_name The name of the end node (read only) initial_status The initial status (Opened, Closed, Active) of the Link initial_setting The initial setting for the link (if Active) pump_type "POWER" (read only) power the fixed power value speed_timeseries timeseries of speed values (retrieve only) efficiency pump efficiency energy_price energy price surcharge (only used by EPANET) energy_pattern energy pattern name tag A tag or label for this link vertices A list of curve points, in the direction of start node to end node.

Read-only simulation results

 flow (read-only) current simulated flow through the link headloss (read-only) current simulated headloss velocity (read-only) current simulated velocity through the link quality (read-only) current simulated average link quality status the current status of the pump setting Alias to speed for consistency with other link types
property pump_type

"POWER" (read only)

Type

str

property power

the fixed power value

Type

float

add_outage(wn, start_time, end_time=None, priority=6, add_after_outage_rule=False)

Add a pump outage rule to the water network model.

Parameters
• model (WaterNetworkModel) – The water network model this outage will belong to.

• start_time (int) – The time at which the outage starts.

• end_time (int) – The time at which the outage stops.

• priority (int) – The outage rule priority, default = 6 (very high)

• add_after_outage_rule (bool) – Flag indicating if a rule is added to open the pump after the outage. Pump status after the outage is generally defined by existing controls/rules in the water network model. For example, the pump opens based on the level of a specific tank.

property base_speed

base multiplier for a speed timeseries

Type

float

property efficiency

pump efficiency

Type

float

property end_node

The end node object.

Type

Node

property end_node_name

The name of the end node (read only)

Type

str

property energy_pattern

energy pattern name

Type

str

property energy_price

energy price surcharge (only used by EPANET)

Type

float

property flow

(read-only) current simulated flow through the link

Type

float

property headloss

(read-only) current simulated headloss

Type

float

property initial_setting

The initial setting for the link (if Active)

Type

float

property initial_status

The initial status (Opened, Closed, Active) of the Link

Type

LinkStatus

"Pump" (read only)

Type

str

property name

The link name (read-only)

Type

str

property quality

(read-only) current simulated average link quality

Type

float

remove_outage(wn)

Remove an outage control from the water network model

Parameters

wn (WaterNetworkModel) – Water network model

property setting

Alias to speed for consistency with other link types

property speed_pattern_name

pattern name for the speed

Type

str

property speed_timeseries

timeseries of speed values (retrieve only)

Type

TimeSeries

property start_node

The start node object.

Type

Node

property start_node_name

The name of the start node (read only)

Type

str

property status

the current status of the pump

Type

LinkStatus

property tag

A tag or label for this link

Type

str

to_dict()

Dictionary representation of the link

property velocity

(read-only) current simulated velocity through the link

Type

float

property vertices

A list of curve points, in the direction of start node to end node.

The vertices should be listed as a list of (x,y) tuples when setting.

class wntr.network.elements.Valve(name, start_node_name, end_node_name, wn)[source]

Bases: Link

Valve class, inherited from Link.

For details about the subclasses, please see one of the following: PRValve, PSValve, PBValve, FCValve, TCValve, and GPValve.

Constructor

This class is intended to be instantiated through the add_valve method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the valve

• start_node_name (string) – Name of the start node

• end_node_name (string) – Name of the end node

• wn (WaterNetworkModel) – The water network model this valve will belong to.

Attributes

 name The link name (read-only) link_type returns "Valve" start_node The start node object. start_node_name The name of the start node (read only) end_node The end node object. end_node_name The name of the end node (read only) initial_status The initial status (Opened, Closed, Active) of the Link initial_setting The initial setting for the link (if Active) valve_type returns None because this is an abstact class tag A tag or label for this link vertices A list of curve points, in the direction of start node to end node.

Result attributes

 flow (read-only) current simulated flow through the link velocity (read-only) current simulated velocity through the link headloss (read-only) current simulated headloss quality (read-only) current simulated average link quality status (abstract) current status of the link setting (read-only) current simulated setting of the link
property status

(abstract) current status of the link

Type

LinkStatus

returns "Valve"

property valve_type

returns None because this is an abstact class

property end_node

The end node object.

Type

Node

property end_node_name

The name of the end node (read only)

Type

str

property flow

(read-only) current simulated flow through the link

Type

float

property headloss

(read-only) current simulated headloss

Type

float

property initial_setting

The initial setting for the link (if Active)

Type

float

property initial_status

The initial status (Opened, Closed, Active) of the Link

Type

LinkStatus

property name

The link name (read-only)

Type

str

property quality

(read-only) current simulated average link quality

Type

float

property setting

(read-only) current simulated setting of the link

Type

float

property start_node

The start node object.

Type

Node

property start_node_name

The name of the start node (read only)

Type

str

property tag

A tag or label for this link

Type

str

to_dict()

Dictionary representation of the link

property velocity

(read-only) current simulated velocity through the link

Type

float

property vertices

A list of curve points, in the direction of start node to end node.

The vertices should be listed as a list of (x,y) tuples when setting.

class wntr.network.elements.PRValve(name, start_node_name, end_node_name, wn)[source]

Bases: Valve

Pressure reducing valve class, inherited from Valve.

Constructor

This class is intended to be instantiated through the add_valve method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the pump

• start_node_name (string) – Name of the start node

• end_node_name (string) – Name of the end node

• wn (WaterNetworkModel) – The water network model this valve will belong to.

Attributes

 name The link name (read-only) link_type returns "Valve" start_node The start node object. start_node_name The name of the start node (read only) end_node The end node object. end_node_name The name of the end node (read only) initial_status The initial status (Opened, Closed, Active) of the Link initial_setting The initial setting for the link (if Active) valve_type returns "PRV" tag A tag or label for this link vertices A list of curve points, in the direction of start node to end node.

Result attributes

 flow (read-only) current simulated flow through the link velocity (read-only) current simulated velocity through the link headloss (read-only) current simulated headloss quality (read-only) current simulated average link quality status (abstract) current status of the link setting (read-only) current simulated setting of the link
property valve_type

returns "PRV"

property end_node

The end node object.

Type

Node

property end_node_name

The name of the end node (read only)

Type

str

property flow

(read-only) current simulated flow through the link

Type

float

property headloss

(read-only) current simulated headloss

Type

float

property initial_setting

The initial setting for the link (if Active)

Type

float

property initial_status

The initial status (Opened, Closed, Active) of the Link

Type

LinkStatus

returns "Valve"

property name

The link name (read-only)

Type

str

property quality

(read-only) current simulated average link quality

Type

float

property setting

(read-only) current simulated setting of the link

Type

float

property start_node

The start node object.

Type

Node

property start_node_name

The name of the start node (read only)

Type

str

property status

(abstract) current status of the link

Type

LinkStatus

property tag

A tag or label for this link

Type

str

to_dict()

Dictionary representation of the link

property velocity

(read-only) current simulated velocity through the link

Type

float

property vertices

A list of curve points, in the direction of start node to end node.

The vertices should be listed as a list of (x,y) tuples when setting.

class wntr.network.elements.PSValve(name, start_node_name, end_node_name, wn)[source]

Bases: Valve

Pressure sustaining valve class, inherited from Valve.

Constructor

This class is intended to be instantiated through the add_valve method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the pump

• start_node_name (string) – Name of the start node

• end_node_name (string) – Name of the end node

• wn (WaterNetworkModel) – The water network model this valve will belong to.

Attributes

 name The link name (read-only) link_type returns "Valve" start_node The start node object. start_node_name The name of the start node (read only) end_node The end node object. end_node_name The name of the end node (read only) initial_status The initial status (Opened, Closed, Active) of the Link initial_setting The initial setting for the link (if Active) valve_type returns "PSV" tag A tag or label for this link vertices A list of curve points, in the direction of start node to end node.

Result attributes

 flow (read-only) current simulated flow through the link velocity (read-only) current simulated velocity through the link headloss (read-only) current simulated headloss quality (read-only) current simulated average link quality status (abstract) current status of the link setting (read-only) current simulated setting of the link
property valve_type

returns "PSV"

property end_node

The end node object.

Type

Node

property end_node_name

The name of the end node (read only)

Type

str

property flow

(read-only) current simulated flow through the link

Type

float

property headloss

(read-only) current simulated headloss

Type

float

property initial_setting

The initial setting for the link (if Active)

Type

float

property initial_status

The initial status (Opened, Closed, Active) of the Link

Type

LinkStatus

returns "Valve"

property name

The link name (read-only)

Type

str

property quality

(read-only) current simulated average link quality

Type

float

property setting

(read-only) current simulated setting of the link

Type

float

property start_node

The start node object.

Type

Node

property start_node_name

The name of the start node (read only)

Type

str

property status

(abstract) current status of the link

Type

LinkStatus

property tag

A tag or label for this link

Type

str

to_dict()

Dictionary representation of the link

property velocity

(read-only) current simulated velocity through the link

Type

float

property vertices

A list of curve points, in the direction of start node to end node.

The vertices should be listed as a list of (x,y) tuples when setting.

class wntr.network.elements.PBValve(name, start_node_name, end_node_name, wn)[source]

Bases: Valve

Pressure breaker valve class, inherited from Valve.

Constructor

This class is intended to be instantiated through the add_valve method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the pump

• start_node_name (string) – Name of the start node

• end_node_name (string) – Name of the end node

• wn (WaterNetworkModel) – The water network model this valve will belong to.

Attributes

 name The link name (read-only) link_type returns "Valve" start_node The start node object. start_node_name The name of the start node (read only) end_node The end node object. end_node_name The name of the end node (read only) initial_status The initial status (Opened, Closed, Active) of the Link initial_setting The initial setting for the link (if Active) valve_type returns "PBV" tag A tag or label for this link vertices A list of curve points, in the direction of start node to end node.

Result attributes

 flow (read-only) current simulated flow through the link velocity (read-only) current simulated velocity through the link headloss (read-only) current simulated headloss quality (read-only) current simulated average link quality status (abstract) current status of the link setting (read-only) current simulated setting of the link
property valve_type

returns "PBV"

property end_node

The end node object.

Type

Node

property end_node_name

The name of the end node (read only)

Type

str

property flow

(read-only) current simulated flow through the link

Type

float

property headloss

(read-only) current simulated headloss

Type

float

property initial_setting

The initial setting for the link (if Active)

Type

float

property initial_status

The initial status (Opened, Closed, Active) of the Link

Type

LinkStatus

returns "Valve"

property name

The link name (read-only)

Type

str

property quality

(read-only) current simulated average link quality

Type

float

property setting

(read-only) current simulated setting of the link

Type

float

property start_node

The start node object.

Type

Node

property start_node_name

The name of the start node (read only)

Type

str

property status

(abstract) current status of the link

Type

LinkStatus

property tag

A tag or label for this link

Type

str

to_dict()

Dictionary representation of the link

property velocity

(read-only) current simulated velocity through the link

Type

float

property vertices

A list of curve points, in the direction of start node to end node.

The vertices should be listed as a list of (x,y) tuples when setting.

class wntr.network.elements.FCValve(name, start_node_name, end_node_name, wn)[source]

Bases: Valve

Flow control valve class, inherited from Valve.

Constructor

This class is intended to be instantiated through the add_valve method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the pump

• start_node_name (string) – Name of the start node

• end_node_name (string) – Name of the end node

• wn (WaterNetworkModel) – The water network model this valve will belong to

Attributes

 name The link name (read-only) link_type returns "Valve" start_node The start node object. start_node_name The name of the start node (read only) end_node The end node object. end_node_name The name of the end node (read only) initial_status The initial status (Opened, Closed, Active) of the Link initial_setting The initial setting for the link (if Active) valve_type returns "FCV" tag A tag or label for this link vertices A list of curve points, in the direction of start node to end node.

Result attributes

 flow (read-only) current simulated flow through the link velocity (read-only) current simulated velocity through the link headloss (read-only) current simulated headloss quality (read-only) current simulated average link quality status (abstract) current status of the link setting (read-only) current simulated setting of the link
property valve_type

returns "FCV"

property end_node

The end node object.

Type

Node

property end_node_name

The name of the end node (read only)

Type

str

property flow

(read-only) current simulated flow through the link

Type

float

property headloss

(read-only) current simulated headloss

Type

float

property initial_setting

The initial setting for the link (if Active)

Type

float

property initial_status

The initial status (Opened, Closed, Active) of the Link

Type

LinkStatus

returns "Valve"

property name

The link name (read-only)

Type

str

property quality

(read-only) current simulated average link quality

Type

float

property setting

(read-only) current simulated setting of the link

Type

float

property start_node

The start node object.

Type

Node

property start_node_name

The name of the start node (read only)

Type

str

property status

(abstract) current status of the link

Type

LinkStatus

property tag

A tag or label for this link

Type

str

to_dict()

Dictionary representation of the link

property velocity

(read-only) current simulated velocity through the link

Type

float

property vertices

A list of curve points, in the direction of start node to end node.

The vertices should be listed as a list of (x,y) tuples when setting.

class wntr.network.elements.TCValve(name, start_node_name, end_node_name, wn)[source]

Bases: Valve

Throttle control valve class, inherited from Valve.

Constructor

This class is intended to be instantiated through the add_valve method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the pump

• start_node_name (string) – Name of the start node

• end_node_name (string) – Name of the end node

• wn (WaterNetworkModel) – The water network model this valve will belong to

Attributes

 name The link name (read-only) link_type returns "Valve" start_node The start node object. start_node_name The name of the start node (read only) end_node The end node object. end_node_name The name of the end node (read only) initial_status The initial status (Opened, Closed, Active) of the Link initial_setting The initial setting for the link (if Active) valve_type returns "TCV" tag A tag or label for this link vertices A list of curve points, in the direction of start node to end node.

Result attributes

 flow (read-only) current simulated flow through the link velocity (read-only) current simulated velocity through the link headloss (read-only) current simulated headloss quality (read-only) current simulated average link quality status (abstract) current status of the link setting (read-only) current simulated setting of the link
property valve_type

returns "TCV"

property end_node

The end node object.

Type

Node

property end_node_name

The name of the end node (read only)

Type

str

property flow

(read-only) current simulated flow through the link

Type

float

property headloss

(read-only) current simulated headloss

Type

float

property initial_setting

The initial setting for the link (if Active)

Type

float

property initial_status

The initial status (Opened, Closed, Active) of the Link

Type

LinkStatus

returns "Valve"

property name

The link name (read-only)

Type

str

property quality

(read-only) current simulated average link quality

Type

float

property setting

(read-only) current simulated setting of the link

Type

float

property start_node

The start node object.

Type

Node

property start_node_name

The name of the start node (read only)

Type

str

property status

(abstract) current status of the link

Type

LinkStatus

property tag

A tag or label for this link

Type

str

to_dict()

Dictionary representation of the link

property velocity

(read-only) current simulated velocity through the link

Type

float

property vertices

A list of curve points, in the direction of start node to end node.

The vertices should be listed as a list of (x,y) tuples when setting.

class wntr.network.elements.GPValve(name, start_node_name, end_node_name, wn)[source]

Bases: Valve

General purpose valve class, inherited from Valve.

Constructor

This class is intended to be instantiated through the add_valve method. Direct creation through the constructor is highly discouraged.

Parameters
• name (string) – Name of the pump

• start_node_name (string) – Name of the start node

• end_node_name (string) – Name of the end node

• wn (WaterNetworkModel) – The water network model this valve will belong to

Attributes

 name The link name (read-only) link_type returns "Valve" start_node The start node object. start_node_name The name of the start node (read only) end_node The end node object. end_node_name The name of the end node (read only) initial_status The initial status (Opened, Closed, Active) of the Link initial_setting The initial setting for the link (if Active) valve_type returns "GPV" headloss_curve the headloss curve object (read only) headloss_curve_name Returns the pump curve name if pump_type is 'HEAD', otherwise returns None tag A tag or label for this link vertices A list of curve points, in the direction of start node to end node.

Result attributes

 flow (read-only) current simulated flow through the link velocity (read-only) current simulated velocity through the link headloss (read-only) current simulated headloss quality (read-only) current simulated average link quality status (abstract) current status of the link setting (read-only) current simulated setting of the link
property valve_type

returns "GPV"

property headloss_curve

the headloss curve object (read only)

Type

Curve

property headloss_curve_name

Returns the pump curve name if pump_type is ‘HEAD’, otherwise returns None

property end_node

The end node object.

Type

Node

property end_node_name

The name of the end node (read only)

Type

str

property flow

(read-only) current simulated flow through the link

Type

float

property headloss

(read-only) current simulated headloss

Type

float

property initial_setting

The initial setting for the link (if Active)

Type

float

property initial_status

The initial status (Opened, Closed, Active) of the Link

Type

LinkStatus

returns "Valve"

property name

The link name (read-only)

Type

str

property quality

(read-only) current simulated average link quality

Type

float

property setting

(read-only) current simulated setting of the link

Type

float

property start_node

The start node object.

Type

Node

property start_node_name

The name of the start node (read only)

Type

str

property status

(abstract) current status of the link

Type

LinkStatus

property tag

A tag or label for this link

Type

str

to_dict()

Dictionary representation of the link

property velocity

(read-only) current simulated velocity through the link

Type

float

property vertices

A list of curve points, in the direction of start node to end node.

The vertices should be listed as a list of (x,y) tuples when setting.

class wntr.network.elements.Pattern(name, multipliers=[], time_options=None, wrap=True)[source]

Bases: object

Pattern class.

Constructor

This class is intended to be instantiated through the add_pattern method.

Parameters
• name (string) – Name of the pattern.

• multipliers (list) – A list of multipliers that makes up the pattern.

• time_options (wntr TimeOptions or tuple) – The water network model options.time object or a tuple of (pattern_start, pattern_timestep) in seconds.

• wrap (bool, optional) – Boolean indicating if the pattern should be wrapped. If True (the default), then the pattern repeats itself forever; if False, after the pattern has been exhausted, it will return 0.0.

classmethod binary_pattern(name, start_time, end_time, step_size, duration, wrap=False)[source]

Creates a binary pattern (single instance of step up, step down).

Parameters
• name (string) – Name of the pattern.

• start_time (int) – The time at which the pattern turns “on” (1.0).

• end_time (int) – The time at which the pattern turns “off” (0.0).

• step_size (int) – Pattern step size.

• duration (int) – Total length of the pattern.

• wrap (bool, optional) – Boolean indicating if the pattern should be wrapped. If True, then the pattern repeats itself forever; if False (the default), after the pattern has been exhausted, it will return 0.0.

Returns

A new pattern object with a list of 1’s and 0’s as multipliers.

property multipliers

Returns the pattern multiplier values

property time_options

Returns the TimeOptions object

to_dict()[source]

Dictionary representation of the pattern

at(time)[source]

Returns the pattern value at a specific time

Parameters

time (int) – Time in seconds

class wntr.network.elements.TimeSeries(model, base, pattern_name=None, category=None)[source]

Bases: object

Time series class.

A TimeSeries object contains a base value, Pattern object, and category. The object can be used to store changes in junction demand, source injection, pricing, pump speed, and reservoir head. The class provides methods to calculate values using the base value and a multiplier pattern.

Constructor

Parameters
• base (number) – A number that represents the baseline value.

• pattern_registry (PatternRegistry) – The pattern registry for looking up patterns

• pattern (str, optional) – If None, then the value will be constant. Otherwise, the Pattern will be used. (default = None)

• category (string, optional) – A category, description, or other name that is useful to the user (default = None).

Raises

ValueError – If base or pattern are invalid types

property base_value

Returns the baseline value.

property pattern

Returns the Pattern object.

property pattern_name

Returns the name of the pattern.

property category

Returns the category.

at(time)[source]

Returns the value at a specific time.

Parameters

time (int) – Time in seconds

to_dict()[source]

Dictionary representation of the time series

class wntr.network.elements.Demands(patterns, *args)[source]

Bases: MutableSequence

Demands class.

The Demands object is used to store multiple demands per junction in a list. The class includes specialized demand-specific calls and type checking.

A demand list is a list of demands and can be used with all normal list- like commands.

The demand list does not have any attributes, but can be created by passing in demand objects or demand tuples as (base_demand, pattern, category_name)

to_ts(obj)[source]

Time series representation of demands

insert(index, obj)[source]

S.insert(index, object) - insert object before index

append(obj)[source]

S.append(object) - append object to the end

extend(iterable)[source]

S.extend(iterable) - extend list by appending elements from the iterable

clear()[source]

S.clear() - remove all entries

at(time, category=None, multiplier=1)[source]

Return the total demand at a given time.

count(value) integer -- return number of occurrences of value
index(value[, start[, stop]]) integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

pop([index]) item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

remove_category(category)[source]

Remove all demands from a specific category

base_demand_list(category=None)[source]

Returns a list of the base demands, optionally of a single category.

pattern_list(category=None)[source]

Returns a list of the patterns, optionally of a single category.

category_list()[source]

Returns a list of all the pattern categories.

class wntr.network.elements.Curve(name, curve_type=None, points=[], original_units=None, current_units='SI', options=None)[source]

Bases: object

Curve base class.

Constructor

This class is intended to be instantiated through the add_curve method.

Parameters
• name (str) – Name of the curve.

• curve_type (str) – The type of curve: None (unspecified), HEAD, HEADLOSS, VOLUME or EFFICIENCY

• points (list) – The points in the curve. List of 2-tuples (x,y) ordered by increasing x

• original_units (str) – The units the points were defined in

• current_units (str) – The units the points are currently defined in. This MUST be ‘SI’ by the time one of the simulators is run.

• options (Options, optional) – Water network options to lookup headloss function

property original_units

The original units the points were written in.

property current_units

The current units that the points are in

property name

Curve names must be unique among curves

property points

The points in the curve. List of 2-tuples (x,y) ordered by increasing x

property curve_type

None (unspecified), HEAD, HEADLOSS, VOLUME or EFFICIENCY

Type

The type of curve

property num_points

Returns the number of points in the curve.

to_dict()[source]

Dictionary representation of the curve

set_units(original=None, current=None)[source]

Set the units flags for the curve.

Use this after converting the points, if necessary, to indicate that conversion to SI units is complete.

class wntr.network.elements.Source(model, name, node_name, source_type, strength, pattern=None)[source]

Bases: object

Water quality source class.

Constructor

This class is intended to be instantiated through the add_source method.

Parameters
• name (string) – Name of the source.

• node_name (string) – Injection node.

• source_type (string) – Source type, options = CONCEN, MASS, FLOWPACED, or SETPOINT.

• strength (float) – Source strength in Mass/Time for MASS and Mass/Volume for CONCEN, FLOWPACED, or SETPOINT.

• pattern (Pattern, optional) – If None, then the value will be constant. Otherwise, the Pattern will be used (default = None).

Attributes

 name the name for this source node_name the node where this source is located source_type the source type for this source strength_timeseries timeseries of the source values (read only)
property strength_timeseries

timeseries of the source values (read only)

Type

TimeSeries

property name

the name for this source

Type

str

property node_name

the node where this source is located

Type

str

property source_type

the source type for this source

Type

str