API Documentation

EPANET-Python Toolkit (EPyT): A Python toolkit for EPANET libraries

How to run:

from epyt import epanet

d = epanet(‘Net1.inp’)

EPANET is software that models water distribution piping systems developed by the US EPA and provided under a public domain licence. This python toolkit serves as an interface between Python and EPANET, to assist researchers and the industry when solving problems related with water distribution systems.

EPANET was developed by the Water Supply and Water Resources Division of the U.S. Environmental Protection Agency’s National Risk Management Research Laboratory. EPANET is under the Public Domain.

The latest EPANET files can downloaded at: https://github.com/OpenWaterAnalytics/EPANET

Inspired by: EPANET-MATLAB Toolkit D.G. Eliades, M. Kyriakou, S. Vrachimis and M.M. Polycarpou, “EPANET-MATLAB Toolkit: An Open-Source Software for Interfacing EPANET with MATLAB”, in Proc. 14th International Conference on Computing and Control for the Water Industry (CCWI), The Netherlands, Nov 2016, p.8. (doi:10.5281/zenodo.831493)

Other python packages related to the EPANET engine: wntr Klise, K.A., Murray, R., Haxton, T. (2018). An overview of the Water Network Tool for Resilience (WNTR), In Proceedings of the 1st International WDSA/CCWI Joint Conference, Kingston, Ontario, Canada, July 23-25, 075, 8p.

epanet-python https://github.com/OpenWaterAnalytics/epanet-python

EPANET-Python Toolkit Licence:

Licensed under the EUPL, Version 1.2 or - as soon they will be approved by the European Commission - subsequent libepanets of the EUPL (the “Licence”) You may not use this work except in compliance with the Licence. You may obtain a copy of the Licence at:

https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an “AS IS” basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Licence for the specific language governing permissions and limitations under the Licence.

class epyt.epanet.EpytValues[source]

Bases: object

disp()[source]

Displays the values on the command window

Parameters:: self (EpytValues class) – Values to be printed on the command window
Returns:: None

to_dict()[source]

Transform EpytValues class values to dict format

Parameters:: self (EpytValues class) – Values to add in the dictionary
Returns:: dictionary with the values
Return type:: dict

to_excel(filename=None, attributes=None, allValues=False)[source]

Save to an Excel file the values of EpytValues class

Parameters:

self (EpytValues class) – Values to add to the Excel file
filename (str, optional) – excel filename, defaults to None
attributes (str or list of str, optional) – attributes to add to the file, defaults to None
allValues (bool, optional) – ‘True’ if all the values will be included in a separate sheet, defaults to False

Returns:

None

to_json(filename=None)[source]

Transforms val class values to json object and saves them to a json file if filename is provided

Parameters:

self (val class) – Values to add in the json file
filename (str, optional) – json filename, defaults to None

Returns:

the json object with the values

Return type:

json object

class epyt.epanet.ToolkitConstants[source]

Bases: object

EN_ACCURACY = 1

EN_AFD = 4

EN_AGE = 2

EN_AVERAGE = 1

EN_BASEDEMAND = 1

EN_BULKORDER = 19

EN_CANOVERFLOW = 26

EN_CFS = 0

EN_CHECKFREQ = 15

EN_CHEM = 1

EN_CM = 2

EN_CMD = 9

EN_CMH = 8

EN_CONCEN = 0

EN_CONCENLIMIT = 22

EN_CONTROL = 4

EN_CONTROLCOUNT = 5

EN_CURVE = 3

EN_CURVECOUNT = 4

EN_CVPIPE = 0

EN_DAMPLIMIT = 17

EN_DEFICIENTNODES = 5

EN_DEMAND = 9

EN_DEMANDCHARGE = 11

EN_DEMANDDEFICIT = 27

EN_DEMANDMULT = 4

EN_DEMANDREDUCTION = 6

EN_DIAMETER = 0

EN_DURATION = 0

EN_DW = 1

EN_ELEVATION = 0

EN_EMITEXPON = 3

EN_EMITTER = 3

EN_ENERGY = 13

EN_FCV = 6

EN_FIFO = 2

EN_FLOW = 8

EN_FLOWCHANGE = 6

EN_FLOWPACED = 3

EN_GLOBALEFFIC = 8

EN_GLOBALPATTERN = 10

EN_GLOBALPRICE = 9

EN_GPM = 1

EN_GPV = 8

EN_HALTFLAG = 13

EN_HEAD = 10

EN_HEADERROR = 5

EN_HEADLOSS = 10

EN_HEADLOSSFORM = 7

EN_HILEVEL = 1

EN_HTIME = 11

EN_HW = 0

EN_HYDSTEP = 1

EN_IMGD = 3

EN_INITFLOW = 10

EN_INITQUAL = 4

EN_INITSETTING = 5

EN_INITSTATUS = 4

EN_INITVOLUME = 14

EN_ITERATIONS = 0

EN_JUNCTION = 0

EN_KBULK = 6

EN_KWALL = 7

EN_LENGTH = 1

EN_LIFO = 3

EN_LINK = 1

EN_LINKCOUNT = 2

EN_LINKPATTERN = 15

EN_LINKQUAL = 14

EN_LOWLEVEL = 0

EN_LPM = 6

EN_LPS = 5

EN_MASS = 1

EN_MASSBALANCE = 4

EN_MAXCHECK = 16

EN_MAXFLOWCHANGE = 3

EN_MAXHEADERROR = 2

EN_MAXID = 32

EN_MAXIMUM = 3

EN_MAXLEVEL = 21

EN_MAXMSG = 255

EN_MAXVOLUME = 25

EN_MGD = 2

EN_MINIMUM = 2

EN_MINLEVEL = 20

EN_MINORLOSS = 3

EN_MINVOLUME = 18

EN_MIX1 = 0

EN_MIX2 = 1

EN_MIXFRACTION = 22

EN_MIXMODEL = 15

EN_MIXZONEVOL = 16

EN_MLD = 7

EN_NEXTEVENT = 14

EN_NEXTEVENTTANK = 15

EN_NODE = 0

EN_NODECOUNT = 0

EN_NONE = 0

EN_NOSAVE = 0

EN_PATCOUNT = 3

EN_PATTERN = 2

EN_PATTERNSTART = 4

EN_PATTERNSTEP = 3

EN_PBV = 5

EN_PERIODS = 9

EN_PIPE = 1

EN_PRESSURE = 11

EN_PRV = 3

EN_PSV = 4

EN_PUMP = 2

EN_PUMP_ECOST = 21

EN_PUMP_ECURVE = 20

EN_PUMP_EFFIC = 17

EN_PUMP_EPAT = 22

EN_PUMP_HCURVE = 19

EN_PUMP_POWER = 18

EN_PUMP_STATE = 16

EN_QTIME = 12

EN_QUALITY = 12

EN_QUALSTEP = 2

EN_RANGE = 4

EN_RELATIVEERROR = 1

EN_REPORTSTART = 6

EN_REPORTSTEP = 5

EN_RESERVOIR = 1

EN_ROUGHNESS = 2

EN_RULE = 5

EN_RULECOUNT = 6

EN_RULESTEP = 7

EN_R_CLOCKTIME = 10

EN_R_DEMAND = 0

EN_R_DRAINTIME = 12

EN_R_FILLTIME = 11

EN_R_FLOW = 5

EN_R_GRADE = 2

EN_R_HEAD = 1

EN_R_IS_ACTIVE = 3

EN_R_IS_CLOSED = 2

EN_R_IS_OPEN = 1

EN_R_LEVEL = 3

EN_R_LINK = 7

EN_R_NODE = 6

EN_R_POWER = 8

EN_R_PRESSURE = 4

EN_R_SETTING = 7

EN_R_STATUS = 6

EN_R_SYSTEM = 8

EN_R_TIME = 9

EN_SAVE = 1

EN_SAVE_AND_INIT = 11

EN_SETPOINT = 2

EN_SETTING = 12

EN_SOURCEMASS = 13

EN_SOURCEPAT = 6

EN_SOURCEQUAL = 5

EN_SOURCETYPE = 7

EN_SP_DIFFUS = 18

EN_SP_GRAVITY = 12

EN_SP_VISCOS = 13

EN_STARTTIME = 10

EN_STATISTIC = 8

EN_STATUS = 11

EN_TANK = 2

EN_TANKCOUNT = 1

EN_TANKDIAM = 17

EN_TANKLEVEL = 8

EN_TANKORDER = 21

EN_TANKVOLUME = 24

EN_TANK_KBULK = 23

EN_TCV = 7

EN_TIMEOFDAY = 3

EN_TIMEPAT = 2

EN_TIMER = 2

EN_TOLERANCE = 2

EN_TRACE = 3

EN_TRIALS = 0

EN_UNBALANCED = 14

EN_VELOCITY = 9

EN_VOLCURVE = 19

EN_WALLORDER = 20

MSX_BULK = 0

MSX_CONCEN = 0

MSX_CONSTANT = 6

MSX_FLOWPACED = 3

MSX_LINK = 1

MSX_MASS = 1

MSX_NODE = 0

MSX_NOSOURCE = -1

MSX_PARAMETER = 5

MSX_PATTERN = 7

MSX_SETPOINT = 2

MSX_SPECIES = 3

MSX_TANK = 2

MSX_TERM = 4

MSX_WALL = 1

class epyt.epanet.epanet(*argv, version=2.2, ph=False, loadfile=False, customlib=None, display_msg=True)[source]

Bases: object

EPyt main functions class

Example with custom library: epanetlib=os.path.join(os.getcwd(), ‘epyt’,’libraries’,’win’,’epanet2.dll’) d = epanet(inpname, msx=True,customlib=epanetlib)

addControls(control, *argv)[source]

Adds a new simple control.

Parameters:: control (float or list) – New Control
Returns:: Control index
Return type:: int

The examples are based on d = epanet(‘Net1.inp’)

Example 1: Close Link 12 if the level in Tank 2 exceeds 20 ft.

>>> index = d.addControls('LINK 12 CLOSED IF NODE 2 ABOVE 20')
>>> d.getControls(index).disp()

Example 2: Open Link 12 if the pressure at Node 11 is under 30 psi.

>>> index = d.addControls('LINK 12 OPEN IF NODE 11 BELOW 30')
>>> d.getControls(index).disp()

Example 3: Pump 9 speed is set to 1.5 at 16 hours or 57600 seconds into the simulation.

>>> index = d.addControls('LINK 9 1.5 AT TIME 16:00')
>>> d.getControls(index).disp()
>>> index = d.addControls('LINK 9 1.5 AT TIME 57600') #in seconds
>>> d.getControls(index).disp()

Example 4: Link 12 is closed at 10 am and opened at 8 pm throughout the simulation.

>>> index_3 = d.addControls('LINK 12 CLOSED AT CLOCKTIME 10:00')
>>> d.getControls(index_3).disp()
>>> index_4 = d.addControls('LINK 12 OPEN AT CLOCKTIME 20:00')
>>> d.getControls(index_4).disp()

Example 5: Adds multiple controls given as cell.

>>> d = epanet("Net1.inp")
>>> control_1 = 'LINK 9 OPEN IF NODE 2 BELOW 110'
>>> control_2 = 'LINK 9 CLOSED IF NODE 2 ABOVE 200'
>>> controls = [control_1, control_2]
>>> index = d.addControls(controls)
>>> d.getControls(index)[0].Control
>>> d.getControls(index)[1].Control

Example 6:

Notes:

index: return index of the new control.
Type: the type of control to add (see EN_ControlType).
linkIndex: the index of a link to control (starting from 1).
setting: control setting applied to the link.
nodeIndex: index of the node used to control the link

(0 for EN_TIMER and EN_TIMEOFDAY controls). * level: action level (tank level, junction pressure, or time in seconds) that triggers the control.

Control type codes consist of the following:

EN_LOWLEVEL 0 Control applied when tank level or node

pressure drops below specified level * EN_HILEVEL 1 Control applied when tank level or node pressure rises above specified level * EN_TIMER 2 Control applied at specific time into simulation * EN_TIMEOFDAY 3 Control applied at specific time of day

Code example: index = d.addControls(type, linkIndex, setting, nodeIndex, level)

>>> index = d.addControls(0, 13, 0, 11, 100)
# retrieve controls of index in dict format
>>> d.getControls(index).to_dict()

See also deleteControls, getControls, setControls, getControlRulesCount.

addCurve(*argv)[source]

Adds a new curve appended to the end of the existing curves. Returns the new curve’s index.

Parameters:

*argv –

value index or value

Raises:

No curve ID or curve values exist

Returns:

new curve valueIndex

Return type:

int

Example: ID selected without a space in between the letters

>>> new_curve_ID = 'NewCurve'
>>> x_y_1 = [0, 730]
>>> x_y_2 = [1000, 500]
>>> x_y_3 = [1350, 260]
# X and Y values selected
>>> values = [x_y_1, x_y_2, x_y_3]
# New curve added
>>> curve_index = d.addCurve(new_curve_ID, values)
# Retrieves all the info of curves
>>> d.getCurvesInfo().disp()

See also getCurvesInfo, getCurveType, setCurve,setCurveValue, setCurveNameID, setCurveComment.

addLinkPipe(pipeID, fromNode, toNode, *argv)[source]

Adds a new pipe. Returns the index of the new pipe.

Properties that can be set(optional):

Length
Diameter
Roughness Coefficient
Minor Loss Coefficient

If no properties are given, the default values are:

length = 330 feet (~100.5 m)
diameter = 10 inches (25.4 cm)
roughness coefficient = 130 (Hazen-Williams formula) or
0.15 mm (Darcy-Weisbach formula) or 0.01 (Chezy-Manning formula)
minor Loss Coefficient = 0

The examples are based on d = epanet(“Net1.inp”)

Example 1: Adds a new pipe given no properties.

>>> pipeID = 'newPipe_1'
>>> fromNode = '10'
>>> toNode = '21'
# Retrieves the number of links
>>> d.getLinkPipeCount()
>>> pipeIndex = d.addLinkPipe(pipeID, fromNode, toNode)
>>> d.getLinkPipeCount()
>>> d.plot()

Example 2: Adds a new pipe given it’s length.

>>> pipeID = 'newPipe_2'
>>> fromNode = '11'
>>> toNode = '22'
>>> length = 600
>>> d.getLinkPipeCount()
>>> pipeIndex = d.addLinkPipe(pipeID, fromNode, toNode, length)
>>> d.getLinkPipeCount()
# Retrieves the new link's length
>>> d.getLinkLength(pipeIndex)
>>> d.plot()

Example 3: Adds a new pipe given it’s length, diameter, roughness coefficient and minor loss coefficient.

>>> pipeID = 'newPipe_3'
>>> fromNode = '31'
>>> toNode = '22'
>>> length = 500
>>> diameter = 15
>>> roughness = 120
>>> minorLossCoeff = 0.2
>>> d.getLinkPipeCount()
>>> pipeIndex = d.addLinkPipe(pipeID, fromNode, toNode, length,
>>>                           diameter, roughness, minorLossCoeff)
>>> d.getLinkPipeCount()
>>> d.getLinkLength(pipeIndex)
# Retrieves the new link's diameter
>>> d.getLinkDiameter(pipeIndex)
# Retrieves the new link's roughness coefficient
>>> d.getLinkRoughnessCoeff(pipeIndex)
# Retrieves the new link's minor loss coefficient
>>> d.getLinkMinorLossCoeff(pipeIndex)
>>> d.plot()

See also plot, setLinkNodesIndex, addLinkPipeCV, addNodeJunction, deleteLink, setLinkDiameter.

addLinkPipeCV(cvpipeID, fromNode, toNode, *argv)[source]

Adds a new control valve pipe. Returns the index of the new control valve pipe.

Properties that can be set(optional):

Length
Diameter
Roughness Coefficient
Minor Loss Coefficient

If no properties are given, the default values are:

length = 330 feet (~100.5 m)
diameter = 10 inches (25.4 cm)
roughness coefficient = 130 (Hazen-Williams formula) or
0.15 mm (Darcy-Weisbach formula) or 0.01 (Chezy-Manning formula)
minor Loss Coefficient = 0

The examples are based on d = epanet(‘Net1.inp’)

Example 1: Adds a new control valve pipe given no properties.

>>> cvPipeID = 'newCVPipe_1'
>>> fromNode = '10'
>>> toNode = '21'
# Retrieves the number of pipes
>>> d.getLinkPipeCount()
>>> cvPipeIndex = d.addLinkPipeCV(cvPipeID, fromNode, toNode)
>>> d.getLinkPipeCount()
# Plots the network in a new figure
>>> d.plot()

Example 2: Adds a new control valve pipe given it’s length.

>>> cvPipeID = 'newCVPipe_2'
>>> fromNode = '11'
>>> toNode = '22'
>>> length = 600
>>> d.getLinkPipeCount()
>>> cvPipeIndex = d.addLinkPipeCV(cvPipeID, fromNode, toNode, length)
>>> d.getLinkPipeCount()
# Retrieves the new link's length
>>> d.getLinkLength(cvPipeIndex)
>>> d.plot()

Example 3: Adds a new control valve pipe given it’s length, diameter, roughness coefficient and minor loss coefficient.

>>> cvPipeID = 'newCVPipe_3'
>>> fromNode = '31'
>>> toNode = '22'
>>> length = 500
>>> diameter = 15
>>> roughness = 120
>>> minorLossCoeff = 0.2
>>> d.getLinkPipeCount()
>>> cvPipeIndex = d.addLinkPipeCV(cvPipeID, fromNode, toNode, length,
>>>                               diameter, roughness, minorLossCoeff)
>>> d.getLinkPipeCount()
>>> d.getLinkLength(cvPipeIndex)
# Retrieves the new link's diameter
>>> d.getLinkDiameter(cvPipeIndex)
# Retrieves the new link's roughness coefficient
>>> d.getLinkRoughnessCoeff(cvPipeIndex)
# Retrieves the new link's minor loss coefficient
>>> d.getLinkMinorLossCoeff(cvPipeIndex)
>>> d.plot()

See also plot, setLinkNodesIndex, addLinkPipe, addNodeJunction, deleteLink, setLinkDiameter.

addLinkPump(pumpID, fromNode, toNode, *argv)[source]

Adds a new pump. Returns the index of the new pump.

Parameters

pumpIDstring: Pump ID.
fromNodenumeric: Starting node.
toNodenumeric: End node.

Returns

indexnumeric

new Pumps index

Properties that can be set(optional):

Initial Status
Initial Speed setting
Power
Pattern index

If no properties are given, the default values are:

initial status = 1 (OPEN)
initial speed setting = 1
power = 0
pattern index = 0

Examples

The examples are based on d = epanet(‘Net1.inp’)

Example 1: Adds a new pump given no properties.

>>> pumpID = 'newPump_1'
>>> fromNode = '10'
>>> toNode = '21'
# Retrieves the number of pumps
>>> d.getLinkPumpCount()
>>> pumpIndex = d.addLinkPump(pumpID, fromNode, toNode)
>>> d.getLinkPumpCount()
# Plots the network in a new figure
>>> d.plot()

Example 2: Adds a new pump given it’s initial status.:

>>> pumpID = 'newPump_2'
>>> fromNode = '31'
>>> toNode = '22'
>>> initialStatus = 0    # (CLOSED)
>>> d.getLinkPumpCount()
>>> pumpIndex = d.addLinkPump(pumpID, fromNode, toNode, initialStatus)
>>> d.getLinkPumpCount()

# Retrieves the new pump’s initial status >>> d.getLinkInitialStatus(pumpIndex) >>> d.plot()

Example 3: Adds a new pump given it’s initial status, initial speed setting, power and pattern index.

>>> pumpID = 'newPump_3'
>>> fromNode = '11'
>>> toNode = '22'
>>> initialStatus = 1    # (OPEN)
>>> initialSetting = 1.2
>>> power = 10
>>> patternIndex = 1
>>> d.getLinkPumpCount()
>>> pumpIndex = d.addLinkPump(pumpID, fromNode, toNode, initialStatus,
>>>                           initialSetting, power, patternIndex)
>>> d.getLinkPumpCount()
>>> d.getLinkInitialStatus(pumpIndex)
# Retrieves the new pump's initial setting
>>> d.getLinkInitialSetting(pumpIndex)
# Retrieves the new pump's power
>>> d.getLinkPumpPower(pumpIndex)
# Retrieves the new pump's pattern index
>>> d.getLinkPumpPatternIndex(pumpIndex)
>>> d.plot()

See also: plot, setLinkNodesIndex, addLinkPipe, addNodeJunction, deleteLink, setLinkInitialStatus.

addLinkValveFCV(vID, fromNode, toNode)[source]

Adds a new FCV valve. Returns the index of the new FCV valve.

The example is based on d = epanet(‘Net1.inp’)

Example:

>>> valveID = 'newValveFCV'
>>> fromNode = '10'
>>> toNode = '21'
>>> valveIndex = d.addLinkValveFCV(valveID, fromNode, toNode)
>>> d.plot()

See also plot, setLinkNodesIndex, addLinkPipe,: addLinkValvePRV, deleteLink, setLinkTypeValveTCV.

addLinkValveGPV(vID, fromNode, toNode)[source]

Adds a new GPV valve. Returns the index of the new GPV valve.

The example is based on d = epanet(‘Net1.inp’)

Example:

>>> valveID = 'newValveGPV'
>>> fromNode = '10'
>>> toNode = '21'
>>> valveIndex = d.addLinkValveGPV(valveID, fromNode, toNode)
>>> d.plot()

See also plot, setLinkNodesIndex, addLinkPipe,: addLinkValvePRV, deleteLink, setLinkTypeValveFCV.

addLinkValvePBV(vID, fromNode, toNode)[source]

Adds a new PBV valve. Returns the index of the new PBV valve.

The example is based on d = epanet(‘Net1.inp’)

Example:

>>> valveID = 'newValvePBV'
>>> fromNode = '10'
>>> toNode = '21'
>>> valveIndex = d.addLinkValvePBV(valveID, fromNode, toNode)
>>> d.plot()

See also plot, setLinkNodesIndex, addLinkPipe,
addLinkValvePRV, deleteLink, setLinkTypeValvePRV.

addLinkValvePRV(vID, fromNode, toNode)[source]

Adds a new PRV valve. Returns the index of the new PRV valve.

# The example is based on d = epanet(‘Net1.inp’)

Example:

>>> valveID = 'newValvePRV'
>>> fromNode = '10'
>>> toNode = '21'
>>> valveIndex = d.addLinkValvePRV(valveID, fromNode, toNode)
>>> d.plot()

See also plot, setLinkNodesIndex, addLinkPipe,: addLinkValvePSV, deleteLink, setLinkTypeValveFCV.

addLinkValvePSV(vID, fromNode, toNode)[source]

Adds a new PSV valve. Returns the index of the new PSV valve.

The example is based on d = epanet(‘Net1.inp’)

Example:

>>> valveID = 'newValvePSV'
>>> fromNode = '10'
>>> toNode = '21'
>>> valveIndex = d.addLinkValvePSV(valveID, fromNode, toNode)
>>> d.plot()

See also plot, setLinkNodesIndex, addLinkPipe,: addLinkValvePRV, deleteLink, setLinkTypeValveGPV.

addLinkValveTCV(vID, fromNode, toNode)[source]

Adds a new TCV valve. Returns the index of the new TCV valve.

The example is based on d = epanet(‘Net1.inp’)

Example:

>>> valveID = 'newValveTCV'
>>> fromNode = '10'
>>> toNode = '21'
>>> valveIndex = d.addLinkValveTCV(valveID, fromNode, toNode)
>>> d.plot()

See also plot, setLinkNodesIndex, addLinkPipe,: addLinkValvePRV, deleteLink, setLinkTypeValveFCV.

addMSXPattern(*args)[source]

Adds new time pattern

Example: d = epanet(‘net2-cl2.inp’); d.loadMSXFile(‘net2-cl2.msx’); print(d.getMSXPatternsNameID()) mult = [0.5, 0.8, 1.2, 1.0, 0.7, 0.3] d.addMSXPattern(‘Pattern1’, mult) print(d.getMSXPattern()) print(d.getMSXPatternsNameID())