WaterNetworkModel#

module wntr.network.model

class WaterNetworkModel[source]#

Bases: AbstractModel

Water network model class.

Parameters:: inp_file_name (string (optional)) – Directory and filename of EPANET inp file to load into the WaterNetworkModel object.

__init__(inp_file_name=None)[source]#

add_control(name, control_object)[source]#

Adds a control or rule to the water network model

Parameters:

name (string) – control object name.
control_object (Control or Rule) – Control or Rule object.

add_curve(name, curve_type, xy_tuples_list)[source]#

Adds a curve to the water network model

Parameters:

name (string) – Name of the curve.
curve_type (string) – Type of curve. Options are HEAD, EFFICIENCY, VOLUME, HEADLOSS.
xy_tuples_list (list of (x, y) tuples) – List of X-Y coordinate tuples on the curve.

add_junction(name, base_demand=0.0, demand_pattern=None, elevation=0.0, coordinates=None, demand_category=None)[source]#

Adds a junction to the water network model

Parameters:

name (string) – Name of the junction.
base_demand (float) – Base demand at the junction.
demand_pattern (string or Pattern) – Name of the demand pattern or the Pattern object
elevation (float) – Elevation of the junction.
coordinates (tuple of floats) – X-Y coordinates of the node location.
demand_category (string) – Name of the demand category

add_pattern(name, pattern=None)[source]#

Adds a pattern to the water network model

The pattern can be either a list of values (list, numpy array, etc.) or a Pattern object. The Pattern class has options to automatically create certain types of patterns, such as a single, on/off pattern (previously created using the start_time and stop_time arguments to this function) – see the class documentation for examples.

Warning

Patterns must be added to the model prior to adding any model element that uses the pattern, such as junction demands, sources, etc. Patterns are linked by reference, so changes to a pattern affects all elements using that pattern.

Warning

Patterns always use the global water network model options.time values. Patterns will not be resampled to match these values, it is assumed that patterns created using Pattern(…) or Pattern.binary_pattern(…) object used the same pattern timestep value as the global value, and they will be treated accordingly.

Parameters:

name (string) – Name of the pattern.
pattern (list of floats or Pattern) – A list of floats that make up the pattern, or a Pattern object.

Raises:

ValueError – If adding a pattern with name that already exists.

add_pipe(name, start_node_name, end_node_name, length=304.8, diameter=0.3048, roughness=100, minor_loss=0.0, initial_status='OPEN', check_valve=False)[source]#

Adds a pipe to the water network model

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.
length (float, optional) – Length of the pipe.
diameter (float, optional) – Diameter of the pipe.
roughness (float, optional) – Pipe roughness coefficient.
minor_loss (float, optional) – Pipe minor loss coefficient.
initial_status (string or LinkStatus, optional) – Pipe initial status. Options are ‘OPEN’ or ‘CLOSED’.
check_valve (bool, optional) – True if the pipe has a check valve. False if the pipe does not have a check valve.

add_pump(name, start_node_name, end_node_name, pump_type='POWER', pump_parameter=50.0, speed=1.0, pattern=None, initial_status='OPEN')[source]#

Adds a pump to the water network model

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.
pump_type (string, optional) – Type of information provided for a pump. Options are ‘POWER’ or ‘HEAD’.
pump_parameter (float or string) – For a POWER pump, the pump power. For a HEAD pump, the head curve name.
speed (float) – Relative speed setting (1.0 is normal speed)
pattern (string) – Name of the speed pattern
initial_status (string or LinkStatus) – Pump initial status. Options are ‘OPEN’ or ‘CLOSED’.

add_reservoir(name, base_head=0.0, head_pattern=None, coordinates=None)[source]#

Adds a reservoir to the water network model

Parameters:

name (string) – Name of the reservoir.
base_head (float, optional) – Base head at the reservoir.
head_pattern (string, optional) – Name of the head pattern.
coordinates (tuple of floats, optional) – X-Y coordinates of the node location.

add_source(name, node_name, source_type, quality, pattern=None)[source]#

Adds a source to the water network model

Parameters:

name (string) – Name of the source
node_name (string) – Injection node.
source_type (string) – Source type, options = CONCEN, MASS, FLOWPACED, or SETPOINT
quality (float) – Source strength in Mass/Time for MASS and Mass/Volume for CONCEN, FLOWPACED, or SETPOINT
pattern (string or Pattern object) – Pattern name or object

add_tank(name, elevation=0.0, init_level=3.048, min_level=0.0, max_level=6.096, diameter=15.24, min_vol=0.0, vol_curve=None, overflow=False, coordinates=None)[source]#

Adds a tank to the water network model

Parameters:

name (string) – Name of the tank.
elevation (float) – Elevation at the tank.
init_level (float) – Initial tank level.
min_level (float) – Minimum tank level.
max_level (float) – Maximum tank level.
diameter (float) – Tank diameter.
min_vol (float) – Minimum tank volume.
vol_curve (str, optional) – Name of a volume curve
overflow (bool) – Overflow indicator (Always False for the WNTRSimulator)
coordinates (tuple of floats, optional) – X-Y coordinates of the node location.

add_valve(name, start_node_name, end_node_name, diameter=0.3048, valve_type='PRV', minor_loss=0.0, initial_setting=0.0, initial_status='ACTIVE')[source]#

Adds a valve to the water network model

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.
diameter (float, optional) – Diameter of the valve.
valve_type (string, optional) – Type of valve. Options are ‘PRV’, ‘PSV’, ‘PBV’, ‘FCV’, ‘TCV’, and ‘GPV’
minor_loss (float, optional) – Pipe minor loss coefficient.
initial_setting (float or string, optional) – Valve initial setting. Pressure setting for PRV, PSV, or PBV. Flow setting for FCV. Loss coefficient for TCV. Name of headloss curve for GPV.
initial_status (string or LinkStatus) – Valve initial status. Options are ‘OPEN’, ‘CLOSED’, or ‘ACTIVE’.

assign_demand(demand, pattern_prefix='ResetDemand')[source]#

Assign demands using values in a DataFrame.

New demands are specified in a pandas DataFrame indexed by time (in seconds). The method resets junction demands by creating a new demand pattern and using a base demand of 1. The demand pattern is resampled to match the water network model pattern timestep. This method can be used to reset demands in a water network model to demands from a pressure dependent demand simulation.

Parameters:

demand (pandas DataFrame) – A pandas DataFrame containing demands (index = time, columns = junction names)
pattern_prefix (string) – Pattern name prefix, default = ‘ResetDemand’. The junction name is appended to the prefix to create a new pattern name. If the pattern name already exists, an error is thrown and the user should use a different pattern prefix name.

controls()[source]#

Returns a generator to iterate over all controls

Return type:: A generator in the format (name, object).

convert_controls_to_rules(priority=3)[source]#

Convert all controls to rules.

Note that for an exact match between controls and rules, the rule timestep must be very small.

Parameters:: priority (int, optional) – Rule priority, default is 3.

describe(level=0)[source]#

Describe number of components in the network model

Parameters:

level (int (0, 1, or 2)) –

Level 0 returns the number of Nodes, Links, Patterns, Curves, Sources, and Controls.
Level 1 includes information from Level 0 but divides Nodes into Junctions, Tanks, and Reservoirs, divides Links into Pipes, Pumps, and Valves, and divides Curves into Pump, Efficiency, Headloss, and Volume.
Level 2 includes information from Level 1 but divides Pumps into Head and Power, and divides Valves into PRV, PSV, PBV, TCV, FCV, and GPV.

Return type:

A dictionary with component counts

from_dict(d)[source]#

Append the model with elements from a dictionary.

Parameters:: d (dict) – Dictionary representation of the WaterNetworkModel

from_gis(gis_data)[source]#

Append the model with elements from GeoDataFrames

Parameters:: gis_data (WaterNetworkGIS or dictionary of GeoDataFrames) – GeoDataFrames containing water network attributes. If gis_data is a dictionary, then the keys are junctions, tanks, reservoirs, pipes, pumps, and valves. If the pumps or valves are Points, they will be converted to Lines with the same start and end node location.
Return type:: WaterNetworkModel

get_control(name)[source]#

Get a specific control or rule

Parameters:: name (str) – The control name
Returns:: ctrl
Return type:: Control or Rule

get_curve(name)[source]#

Get a specific curve

Parameters:: name (str) – The curve name
Return type:: Curve

get_graph(node_weight=None, link_weight=None, modify_direction=False)[source]#

Convert a WaterNetworkModel into a networkx MultiDiGraph

Deprecated since version 0.5.0.

Use to_graph() instead

Parameters:

node_weight (dict or pandas Series (optional)) – Node weights
link_weight (dict or pandas Series (optional)) – Link weights.
modify_direction (bool (optional)) – If True, than if the link weight is negative, the link start and end node are switched and the abs(weight) is assigned to the link (this is useful when weighting graphs by flowrate). If False, link direction and weight are not changed.

Return type:

networkx MultiDiGraph

get_link(name)[source]#

Get a specific link

Parameters:: name (str) – The link name
Return type:: Pipe, Pump, or Valve

get_links_for_node(node_name, flag='ALL')[source]#

Returns a list of links connected to a node

Parameters:

node_name (string) – Name of the node.
flag (string) – Options are ‘ALL’, ‘INLET’, ‘OUTLET’. ‘ALL’ returns all links connected to the node. ‘INLET’ returns links that have the specified node as an end node. ‘OUTLET’ returns links that have the specified node as a start node.

Return type:

A list of link names connected to the node

get_node(name)[source]#

Get a specific node

Parameters:: name (str) – The node name
Return type:: Junction, Tank, or Reservoir

get_pattern(name)[source]#

Get a specific pattern

Parameters:: name (str) – The pattern name
Return type:: Pattern

get_source(name)[source]#

Get a specific source

Parameters:: name (str) – The source name
Return type:: Source

query_link_attribute(attribute, operation=None, value=None, link_type=None)[source]#

Query link attributes, for example get all pipe diameters > threshold

Parameters:

attribute (string) – Link attribute
operation (numpy operator) – Numpy operator, options include np.greater, np.greater_equal, np.less, np.less_equal, np.equal, np.not_equal.
value (float or int) – Threshold
link_type (Link type) – Link type, options include wntr.network.model.Link, wntr.network.model.Pipe, wntr.network.model.Pump, wntr.network.model.Valve, or None. Default = None. Note None and wntr.network.model.Link produce the same results.

Returns:

A pandas Series that contains the attribute that satisfies the
operation threshold for a given link_type.

Notes

If operation and value are both None, the Series will contain the attributes for all links with the specified attribute.

query_node_attribute(attribute, operation=None, value=None, node_type=None)[source]#

Query node attributes, for example get all nodes with elevation <= threshold

Parameters:

attribute (string) – Node attribute.
operation (numpy operator) – Numpy operator, options include np.greater, np.greater_equal, np.less, np.less_equal, np.equal, np.not_equal.
value (float or int) – Threshold
node_type (Node type) – Node type, options include wntr.network.model.Node, wntr.network.model.Junction, wntr.network.model.Reservoir, wntr.network.model.Tank, or None. Default = None. Note None and wntr.network.model.Node produce the same results.

Returns:

A pandas Series that contains the attribute that satisfies the
operation threshold for a given node_type.

Notes

If operation and value are both None, the Series will contain the attributes for all nodes with the specified attribute.

remove_control(name)[source]#: Removes a control from the water network model

remove_curve(name)[source]#: Removes a curve from the water network model

remove_link(name, with_control=False, force=False)[source]#: Removes a link from the water network model

remove_node(name, with_control=False, force=False)[source]#: Removes a node from the water network model

remove_pattern(name)[source]#: Removes a pattern from the water network model

remove_source(name)[source]#

Removes a source from the water network model

Parameters:: name (string) – The name of the source object to be removed

reset_initial_values()[source]#: Resets all initial values in the network

sources()[source]#

Returns a generator to iterate over all sources

Return type:: A generator in the format (name, object).

to_dict()[source]#

Dictionary representation of the WaterNetworkModel.

Return type:: dict

to_gis(crs=None, pumps_as_points=False, valves_as_points=False)[source]#

Convert a WaterNetworkModel into GeoDataFrames

Parameters:

crs (str, optional) – Coordinate reference system, by default None
pumps_as_points (bool, optional) – Represent pumps as points (True) or lines (False), by default False
valves_as_points (bool, optional) – Represent valves as points (True) or lines (False), by default False

Returns:

WaterNetworkGIS object that contains junctions, tanks, reservoirs, pipes,
pumps, and valves GeoDataFrames

to_graph(node_weight=None, link_weight=None, modify_direction=False)[source]#

Convert a WaterNetworkModel into a networkx MultiDiGraph

Parameters:

node_weight (dict or pandas Series (optional)) – Node weights
link_weight (dict or pandas Series (optional)) – Link weights.
modify_direction (bool (optional)) – If True, than if the link weight is negative, the link start and end node are switched and the abs(weight) is assigned to the link (this is useful when weighting graphs by flowrate). If False, link direction and weight are not changed.

Return type:

networkx MultiDiGraph

property control_name_list#

Get a list of control/rule names

Return type:: list of strings

property curve_name_list#

Get a list of curve names

Return type:: list of strings

property curves#

The curve registry (as property) or a generator for iteration (as function call)

Return type:: CurveRegistry

property fcv_name_list#

Get a list of fcv names

Return type:: list of strings

property fcvs#: Iterator over all flow control valves (FCVs)

property gpv_name_list#

Get a list of gpv names

Return type:: list of strings

property gpvs#: Iterator over all general purpose valves (GPVs)

property head_pump_name_list#

Get a list of head pump names

Return type:: list of strings

property head_pumps#: Iterator over all head-based pumps

property junction_name_list#

Get a list of junction names

Return type:: list of strings

property junctions#: Iterator over all junctions

property link_name_list#

Get a list of link names

Return type:: list of strings

property links#

The link registry (as property) or a generator for iteration (as function call)

Return type:: LinkRegistry

property node_name_list#

Get a list of node names

Return type:: list of strings

property nodes#

The node registry (as property) or a generator for iteration (as function call)

Return type:: NodeRegistry

property num_controls#: The number of controls

property num_curves#: The number of curves

property num_junctions#: The number of junctions

property num_links#: The number of links

property num_nodes#: The number of nodes

property num_patterns#: The number of patterns

property num_pipes#: The number of pipes

property num_pumps#: The number of pumps

property num_reservoirs#: The number of reservoirs

property num_sources#: The number of sources

property num_tanks#: The number of tanks

property num_valves#: The number of valves

property options#

The model’s options object

Return type:: Options

property pattern_name_list#

Get a list of pattern names

Return type:: list of strings

property patterns#

The pattern registry (as property) or a generator for iteration (as function call)

Return type:: PatternRegistry

property pbv_name_list#

Get a list of pbv names

Return type:: list of strings

property pbvs#: Iterator over all pressure breaker valves (PBVs)

property pipe_name_list#

Get a list of pipe names

Return type:: list of strings

property pipes#: Iterator over all pipes

property power_pump_name_list#

Get a list of power pump names

Return type:: list of strings

property power_pumps#: Iterator over all power pumps

property prv_name_list#

Get a list of prv names

Return type:: list of strings

property prvs#: Iterator over all pressure reducing valves (PRVs)

property psv_name_list#

Get a list of psv names

Return type:: list of strings

property psvs#: Iterator over all pressure sustaining valves (PSVs)

property pump_name_list#

Get a list of pump names (both types included)

Return type:: list of strings

property pumps#: Iterator over all pumps

property reservoir_name_list#

Get a list of reservoir names

Return type:: list of strings

property reservoirs#: Iterator over all reservoirs

property source_name_list#

Get a list of source names

Return type:: list of strings

property tank_name_list#

Get a list of tanks names

Return type:: list of strings

property tanks#: Iterator over all tanks

property tcv_name_list#

Get a list of tcv names

Return type:: list of strings

property tcvs#: Iterator over all throttle control valves (TCVs)

property valve_name_list#

Get a list of valve names (all types included)

Return type:: list of strings

property valves#: Iterator over all valves