epanet2toolkit: Call 'EPANET' Functions to Simulate Pipe Networks

Description

Enables simulation of water piping networks using 'EPANET'. The package provides functions from the 'EPANET' programmer's toolkit as R functions so that basic or customized simulations can be carried out from R. The package uses 'EPANET' version 2.2 from Open Water Analytics https://github.com/OpenWaterAnalytics/EPANET/releases/tag/v2.2.

Author(s)

Maintainer: Bradley Eck brad@bradeck.net

Authors:

• Ernesto Arandia earandia.ie@gmail.com

• Lew Rossman

Other contributors:

• Michael Tryby [contributor]

• Sam Hatchett [contributor]

• Feng Shang [contributor]

• James Uber [contributor]

• Tom Taxon [contributor]

• Hyoungmin Woo [contributor]

• Jinduan Chen [contributor]

• Yunier Soad [contributor]

• Mike Kane [contributor]

• Demetrios Eliades [contributor]

• Will Furnass [contributor]

• Steffen Macke [contributor]

• Marios Kyriakou [contributor]

• Elad Salomons [contributor]

• Maurizio Cingi [contributor]

• Bryant McDonnell [contributor]

• Angela Marchi [contributor]

• Markus Sunela [contributor]

• Milad Ghiami [contributor]

• IBM Corp. [copyright holder]

• Open Water Analytics [copyright holder]

See Also

Useful links:

• https://github.com/bradleyjeck/epanet2toolkit

Add a new simple control

Description

Add a new simple control

Usage

ENaddcontrol(type, linkIndex, setting, nodeIndex, level)

Arguments

Value

index index of the new control.

Adds a new data curve to a project.

Description

Adds a new data curve to a project.

Usage

ENaddcurve(id)

Arguments

Details

The new curve contains a single data point (1.0, 1.0).

Value

null invisibly

Appends a new demand to a junction node demands list.

Description

Appends a new demand to a junction node demands list.

Usage

ENadddemand(nodeindex, base_demand, demand_pattern, demand_name)

Arguments

Add a link to the network

Description

Add a link to the network

Usage

ENaddlink(id, type, from_node, to_node)

Arguments

Details

A new pipe is assigned a diameter of 10 inches (254 mm) and a length of 330 feet (~ 100 meters). Its roughness coefficient depends on the head loss formula in effect as follows: - Hazen-Williams formula: 130 - Darcy-Weisbach formula: 0.5 millifeet (0.15 mm) - Chezy-Manning formula: 0.01

All other pipe properties are set to 0.

A new pump has a status of EN_OPEN, a speed setting of 1, and has no pump curve or power rating assigned to it.

A new valve has a diameter of 10 inches (254 mm) and all other properties set to 0.

Type must be one of: EN_CVPIPE, EN_PIPE, EN_PUMP, EN_PRV, EN_PSV, EN_PBV, EN_FCV, EN_TCV, EN_GPV

Value

index of new link

Adds a new node

Description

Adds a new node

Usage

ENaddnode(nodeid, nodetype)

Arguments

Details

When a new node is created all of its properties are set to 0.

Value

index the index of the newly added node

Add a new time pattern

Description

Add a new time pattern

Usage

ENaddpattern(patternid)

Arguments

Details

The new pattern contains a single time period whose factor is 1.0.

Value

invisible NULL

Adds a new rule-based control to a project

Description

Adds a new rule-based control to a project

Usage

ENaddrule(rule)

Arguments

Value

null

Clears the contents of a project's report file.

Description

Clears the contents of a project's report file.

Usage

ENclearreport()

Value

Returns NULL invisibly; called for side effect

Close down the EPANET Toolkit system.

Description

ENclose closes the EPANET Toolkit system (including all files being processed).

Usage

ENclose()

Value

Returns NULL invisibly; called for the side effect of closing EPANET.

Note

ENclose must be called when all processing has been completed, even if an error condition was encountered.

See Also

ENopen

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENclose()

close hydraulics engine

Description

ENcloseH closes the hydraulic analysis system, freeing all allocated memory

Usage

ENcloseH()

Details

Call ENcloseH after all hydraulics analyses have been made using ENinitH-ENrunH-ENnextH. Do not call this function if ENsolveH is being used.

Value

Returns NULL invisibly; called for side effect

See Also

ENopenH, ENinitH, ENrunH, ENnextH

Close water quality analysis and free allocated memory

Description

Close water quality analysis and free allocated memory

Usage

ENcloseQ()

Details

Do not call this function if ENsolveQ is being used.

Value

Returns NULL invisibly; called for side effect

Copies the current contents of a project's report file to another file

Description

Copies the current contents of a project's report file to another file

Usage

ENcopyreport(rptFile)

Arguments

Details

This function allows toolkit clients to retrieve the contents of a project's report file while the project is still open.

Value

Returns NULL invisibly; called for side effect

Returns NULL invisibly; called for side effect

Deletes an existing simple control

Description

Deletes an existing simple control

Usage

ENdeletecontrol(controlIndex)

Arguments

Value

null invisibly

Deletes a data curve from a project

Description

Deletes a data curve from a project

Usage

ENdeletecurve(index)

Arguments

Value

null invisibly

Delete a demand from a junction node

Description

Delete a demand from a junction node

Usage

ENdeletedemand(nodeindex, demandindex)

Arguments

Delete a link from the project.

Description

Delete a link from the project.

Usage

ENdeletelink(index, action = "EN_UNCONDITIONAL")

Arguments

Details

If actionCode is EN_UNCONDITIONAL then the link and all simple and rule-based controls that contain it are deleted. If set to EN_CONDITIONAL then the link is not deleted if it appears in any control and error 261 is returned.

Deletes a node

Description

Deletes a node

Usage

ENdeletenode(nodeindex, actionCode)

Arguments

Details

If 'actionCode' is EN_UNCONDITIONAL then the node, its incident links and all simple and rule-based controls that contain them are deleted. If set to EN_CONDITIONAL then the node is not deleted if it or its incident links appear in any controls and error code 261 is returned.

Delete a new time pattern

Description

Delete a new time pattern

Usage

ENdeletepattern(index)

Arguments

Value

invisible NULL

Deletes an existing rule-based control

Description

Deletes an existing rule-based control

Usage

ENdeleterule(index)

Arguments

Value

null

ENepanet

Description

runs a complete EPANET simulation

Usage

ENepanet(inpFile, rptFile, binOutFile = "")

Arguments

Value

Returns NULL invisibly; called for side effect

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp") 
print(inp)
ENepanet( inp, "Net1.rpt") 
# try opening Net1.rpt in a text editor or reading it back
# into R with the read.rpt() function in package epanetReader
myRpt <- epanetReader::read.rpt("Net1.rpt")
summary(myRpt)
# clean-up the created file 
file.remove("Net1.rpt")

Get average of all time factors in a pattern

Description

Get average of all time factors in a pattern

Usage

ENgetaveragepatternvalue(index)

Arguments

Value

the average value

Gets the base demand for one of a node's demand categories.

Description

Gets the base demand for one of a node's demand categories.

Usage

ENgetbasedemand(nodeindex, demand_index = 1)

Arguments

Value

the category's base demand.

ENgetcontrol

Description

Retrieve the parameters of a simple control statement.

Usage

ENgetcontrol(controlindex)

Arguments

Value

list of parameters of the control statement: ctype, lindex, setting, nindex, level

Note

Controls are indexed starting from 1 in the order in which they were entered into the [CONTROLS] section of the EPANET input file.

See Also

ENsetcontrol

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetcontrol(1)
ENclose() 

Get coordinates for a node

Description

Get coordinates for a node

Usage

ENgetcoord(nodeindex)

Arguments

Value

vector of x,y coordinate

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetcoord(3)
ENclose()

Get number of network elements.

Description

ENgetcount retrieves the number of network components of a specific type.

Usage

ENgetcount(compcode)

Arguments

Details

Component codes consist of the following:

The number of junctions in a network equals the number of nodes minus the number of tanks and reservoirs.

Value

The number of network components.

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetcount(0)
ENgetcount("EN_NODECOUNT")
ENclose()

Retrieves the ID name of a curve given its index.

Description

Retrieves the ID name of a curve given its index.

Usage

ENgetcurveid(index)

Arguments

Value

the curve's ID name.

Retrieves the index of a curve given its ID name.

Description

Retrieves the index of a curve given its ID name.

Usage

ENgetcurveindex(id)

Arguments

Value

The curve's index (starting from 1).

Retrieves the number of points in a curve.

Description

Retrieves the number of points in a curve.

Usage

ENgetcurvelen(index)

Arguments

Value

The number of data points assigned to the curve.

Retrieves a curve's type

Description

Retrieves a curve's type

Usage

ENgetcurvetype(index)

Arguments

Value

the curve's type

Retrieves the value of a single data point for a curve.

Description

Retrieves the value of a single data point for a curve.

Usage

ENgetcurvevalue(curveIndex, pointIndex)

Arguments

Value

list with the point's x-value and y-value

Retrieves the index of a node's named demand category

Description

Retrieves the index of a node's named demand category

Usage

ENgetdemandindex(nodeindex, demand_name)

Arguments

Value

demand category index

Get type of demand model in use and its parameters

Description

Get type of demand model in use and its parameters

Usage

ENgetdemandmodel()

Value

named list with parameters of the demand model

Retrieves the name of a node's demand category.

Description

Retrieves the name of a node's demand category.

Usage

ENgetdemandname(nodeindex, demand_index = 1)

Arguments

Value

The name of the selected category.

Gets the base demand for one of a node's demand categories.

Description

Gets the base demand for one of a node's demand categories.

Usage

ENgetdemandpattern(nodeindex, demand_index = 1)

Arguments

Details

A returned pattern index of 0 indicates that no time pattern has been assigned to the demand category.

Value

the category's base demand.

Retrieves index of a time pattern assigned to one of a node's demand categories.

patIndex the index of the category's time pattern.

Gets the properties of an ELSE action in a rule-based control.

Description

Gets the properties of an ELSE action in a rule-based control.

Usage

ENgetelseaction(ruleIndex, actionIndex)

Arguments

Value

list with the following components:

linkIndex

the index of the link in the action

status

the status assigned to the link

setting

the value assigned to the link's setting

Returns the text of an error message generated by an error code

Description

Returns the text of an error message generated by an error code

Usage

ENgeterror(errcode)

Arguments

Value

error message

Retrieve a code number indicating the units used to express all flow rates.

Description

ENgetflowunits retrieves a code number indicating the units used to express all flow rates.

Usage

ENgetflowunits()

Value

An integer, the code numnber indicating the flow units.

Note

Flow units codes are as follows:

Flow units are specified in the [OPTIONS] section of the EPANET Input file.

Flow units in liters or cubic meters implies that metric units are used for all other quantities in addition to flow. Otherwise US units are employed. (See Units of Measurement).

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetflowunits()
ENclose()

Retrieves index of head curve used by a pump

Description

Retrieves index of head curve used by a pump

Usage

ENgetheadcurveindex(linkindex)

Arguments

Value

index of head curve

Retrieve the ID label of a link

Description

ENgetlinkid retrieves the ID label of the link given its index.

Usage

ENgetlinkid(linkindex)

Arguments

Value

character ID

Note

Link indexes are consecutive integers starting from 1.

See Also

ENgetlinkindex

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetlinkid(1)
ENgetlinkid(12)
ENclose()

Retrieve the index of a link

Description

ENgetlinkindex retrieves the index of a link with specified ID.

Usage

ENgetlinkindex(linkid)

Arguments

Value

integer index of requested link

Note

Link indexes are consecutive integers starting from 1.

See Also

ENgetlinkid

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetlinkindex("22")
ENclose()

Retrieve the index of the end nodes of a link

Description

Retrieve the index of the end nodes of a link

Usage

ENgetlinknodes(linkindex)

Arguments

Value

integer vector of node indices for this link

Note

Node and link indexes are consecutive integers starting from 1.

The From and To nodes are as defined for the link in the EPANET input file. The actual direction of flow in the link is not considered.

See Also

ENgetlinkindex

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetlinknodes(1)
ENgetlinknodes(11)
ENclose()

Retrieve the type code for a link

Description

Retrieve the type code for a link

Usage

ENgetlinktype(linkindex)

Arguments

Value

integer type-code of the link

Note

Link indexes are consecutive integers starting from 1. Link type codes consist of the following constants:

See Also

ENgetlinkindex

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetlinktype(1)
ENgetlinktype(12)
ENclose()

Retrieve parameter value for a link

Description

ENgetlinkvalue retrieves the value of a specific link parameter for a link.

Usage

ENgetlinkvalue(linkindex, paramcode)

Arguments

Value

The parameter value of a specified link.

Note

Link indexes are consecutive integers starting from 1. Link parameter codes consist of the following constants:

Parameters 8 - 13 (EN_FLOW through EN_ENERGY) are computed values. The others are design parameters.

Flow rate is positive if the direction of flow is from the designated start node of the link to its designated end node, and negative otherwise.

Values are returned in units which depend on the units used for flow rate in the EPANET input file.

See Also

ENgetlinkindex ENgetflowunits

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen(inp, "Net1.rpt")
ENgetlinkvalue(1, "EN_DIAMETER")
ENgetlinkvalue(1, "EN_LENGTH")
ENgetlinkvalue(8, "EN_DIAMETER")
ENgetlinkvalue(8, "EN_LENGTH")
ENclose()

Retrieve the ID label a node.

Description

ENgetnodeid retrieves the ID label a node from its index

Usage

ENgetnodeid(nodeindex)

Arguments

Value

A character string, the ID label of the specified node.

Note

Node indexes are consecutive integers starting from 1.

See Also

ENgetnodeindex

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetnodeid(1)
ENgetnodeid(5)
ENgetnodeid(9)
ENclose()

Retrieve the index of a node

Description

Retrieve the index of a node

Usage

ENgetnodeindex(nodeid)

Arguments

Value

An integer index of the specified node.

Note

Node indexes are consecutive integers starting from 1.

See Also

ENgetnodeid

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetnodeindex("10")
ENgetnodeindex("23")
ENclose()

Retrieve the node-type code

Description

ENgetnodetype retrieves the node-type code

Usage

ENgetnodetype(nodeindex)

Arguments

Value

integer type-code of the node.

Note

Node indexes are consecutive integers starting from 1.

Node type codes consist of the following constants:

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetnodetype(1)
ENgetnodetype(10)
ENgetnodetype(11)
ENclose()

Retrieve node parameter value.

Description

ENgetnodevalue retrieves the values of specific node parameters.

Usage

ENgetnodevalue(nodeindex, paramcode)

Arguments

Value

parameter value

Note

Node indexes are consecutive integers starting from 1.

Node parameter codes consist of the following constants:

Parameters 9 - 13 (EN_DEMAND through EN_SOURCEMASS) are computed values. The others are input design parameters.

Source types are identified with the following constants:

See [SOURCES] for a description of these source types.

Values are returned in units which depend on the units used for flow rate in the EPANET input file (see Units of Measurement).

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetnodevalue(1, "EN_ELEVATION")
ENgetnodevalue(5, "EN_BASEDEMAND")
ENclose()

Get number of demands for a junction node

Description

Get number of demands for a junction node

Usage

ENgetnumdemands(nodeindex)

Arguments

Value

number of demands

Retrieve the value of an analysis option.

Description

ENgetoption retrieves the value of one or more particular analysis options.

Usage

ENgetoption(optioncode)

Arguments

Details

Option codes consist of the following constants:

Value

numeric value of the specified analysis option(s).

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetoption(0)
ENgetoption("EN_TRIALS")
ENclose()

Retrieve the ID label a time pattern

Description

ENgetpatternid retrieves the ID label of a particular time pattern.

Usage

ENgetpatternid(patternindex)

Arguments

Value

A character string, the pattern ID label of the specified time pattern.

Note

Pattern indexes are consecutive integers starting from 1.

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetpatternid(1)
ENclose()

Retrieve the index a time pattern.

Description

ENgetpatternindex retrieves the index of a time pattern.

Usage

ENgetpatternindex(patternid)

Arguments

Value

An integer, the index of the specified time pattern.

Note

Pattern indexes are consecutive integers starting from 1.

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetpatternindex("1")
ENclose()

Retrieve the number of time periods in a time pattern.

Description

ENgetpatternlen retrieves the number of time periods in a specific time pattern.

Usage

ENgetpatternlen(patternindex)

Arguments

Value

An integer, the time pattern length.

Note

Pattern indexes are consecutive integers starting from 1.

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetpatternlen(1)
ENclose()

Retrieve the multiplier factor for a specific time period

Description

ENgetpatternvalue retrieves the multiplier factor for specific time periods in a pattern.

Usage

ENgetpatternvalue(index, period)

Arguments

Value

A numeric or numeric vector, the multiplier factor for the specific time pattern and period.

Note

Pattern indexes and periods are consecutive integers starting from 1.

See Also

ENgetpatternindex, ENgetpatternlen, ENsetpatternvalue

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetpatternvalue(1,1)
ENgetpatternvalue(1,2)
ENgetpatternvalue(1,3)
ENclose()

Gets the properties of a premise in a rule-based control.

Description

Gets the properties of a premise in a rule-based control.

Usage

ENgetpremise(ruleIndex, premiseIndex)

Arguments

Value

list with components:

logop

the premise's logical operator ( IF = 1, AND = 2, OR = 3 )

object

the type of object the premise refers to

objIndex

the index of the object (e.g. the index of a tank)

variable

the object's variable being compared

relop

the premise's comparison operator

status

the status that the object's status is compared to

value

the value that the object's variable is compared to

Retrieves type of head curve used by a pump

Description

Retrieves type of head curve used by a pump

Usage

ENgetpumptype(linkindex)

Arguments

Value

type of head curve

Get quality analysis information

Description

Get quality analysis information

Usage

ENgetqualinfo()

Value

list with elements: qualcode, chemname, chemunits, tracenode

Examples

inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetqualinfo()
ENclose()
# clean-up the created files
file.remove("Net1.rpt") 

Retrieve the type of water quality analysis called for.

Description

ENgetqualtype retrieves the type of water quality analysis called for.

Usage

ENgetqualtype()

ENgetqualtype()

Value

A named integer vector, the water quality analysis code (see below) and the index of node traced in a source tracing analysis.

list of qualcode and trace node

Note

Water quality analysis codes are as follows:

The tracenode value will be 0 when the quality code is not EN_TRACE.

See Also

ENsetqualtype

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetqualtype()
ENclose()
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetqualtype()
ENclose()
# clean-up the created files
file.remove("Net1.rpt") 

Retrieves the order in which a node or link appears in an output file.

Description

Retrieves the order in which a node or link appears in an output file.

Usage

ENgetresultindex(type, index)

Arguments

Details

If the element does not appear in the file then its result index is 0.

This function can be used to correctly retrieve results from an EPANET binary output file after the order of nodes or links in a network's database has been changed due to editing operations.

Value

the order in which the element's results were written to file.

Retrieves summary information about a rule-based control.

Description

Retrieves summary information about a rule-based control.

Usage

ENgetrule(index)

Arguments

Value

list with components: nPremises number of premises in the rule's IF section; nThenActions number of actions in the rule's THEN section; nElseActions number of actions in the rule's ELSE section; priority the rule's priority value.

Gets the ID name of a rule-based control given its index.

Description

Gets the ID name of a rule-based control given its index.

Usage

ENgetruleID(index)

Arguments

Value

rule's ID name.

Analysis convergence statistics.

Description

Analysis convergence statistics.

Usage

ENgetstatistic(stat)

Arguments

Details

These statistics report the convergence criteria for the most current hydraulic analysis and the cumulative water quality mass balance error at the current simulation time.

Value

value of the stat

Gets properties of THEN action in rule-based control

Description

Gets properties of THEN action in rule-based control

Usage

ENgetthenaction(ruleIndex, actionIndex)

Arguments

Value

list with components: * linkIndex the index of the link in the action (starting from 1) * status the status assigned to the link * setting the value assigned to the link's setting

Get the value of one or more specific analysis time parameters.

Description

ENgettimeparam retrieves the value of one or more specific analysis time parameters.

Usage

ENgettimeparam(paramcode)

Arguments

Details

Time parameter codes consist of the following constants:

Value

A named integer with the value of the specified time parameter.

Examples

# path to Net1.inp example file included with this package 
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp") 
ENopen(inp, "Net1.rpt")
ENgettimeparam("EN_DURATION")
ENgettimeparam("EN_HYDSTEP")
ENclose()

ENgettitle

Description

Retrieves the title lines of the project

Usage

ENgettitle()

Value

character vector of title lines

Retrieve the current version number of the EPANET Toolkit.

Description

ENgetversion retrieves the current version number of the EPANET Toolkit.

Usage

ENgetversion()

Value

An integer, the Toolkit version number.

Note

The version number is a 5-digit integer that increases sequentially from 20001 with each new update of the Toolkit.

Examples

ENgetversion()

Get vertex coordinates

Description

Get vertex coordinates

Usage

ENgetvertex(index, vertex)

Arguments

Value

list with elements x and y

Get number of vertices for a link

Description

Get number of vertices for a link

Usage

ENgetvertexcount(index)

Arguments

Value

number of indices

ENinit

Description

Initializes an empty EPANET network

Usage

ENinit(rptFile, outFile, unitsType, headLossType)

Arguments

Details

This function should be called to create an empty EPANET project without an EPANET-formatted input file. If the project receives it's network data from an input file then there is no need to call this function; use ENopen instead.

Value

Returns NULL invisibly; called for side effect

Initialize hydraulic engine

Description

ENinitH Initializes storage tank levels, link status and settings, and the simulation clock time prior to running a hydraulic analysis.

Usage

ENinitH(flag)

Arguments

Details

Call ENinitH prior to running a hydraulic analysis using ENrunH and ENnextH.ENopenH must have been called prior to calling ENinitH. Do not call ENinitH if a complete hydraulic analysis is being made with a call to ENsolveH. Values of flag have the following meanings:

Set flag to 1 (or 11) if you will be making a subsequent water quality run, using ENreport to generate a report, or using ENsavehydfile to save the binary hydraulics file.

Value

Returns NULL invisibly; called for side effect

See Also

ENopenH, ENrunH, ENnextH, ENcloseH

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENopenH()
ENinitH(0)
ENrunH()
ENcloseH()
ENclose()
# clean-up the created files
file.remove("Net1.rpt") 

Initialize water quality analysis

Description

Initialize water quality analysis

Usage

ENinitQ(saveFlag)

Arguments

Details

Call ENinitQ before running quality analysis using ENrunQ with ENnextQ or ENstepQ. ENopenQ must have been called prior to calling ENinitQ. Do not call ENinitQ with ENsolveQ.

Value

Returns NULL invisibly on success or throws an error or warning

Examples

inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENsolveH()
ENsetqualtype("EN_CHEM", "Chlorine", "mg/L", "")
ENopenQ()
ENinitQ(0)
ENrunQ()
ENcloseQ()
ENclose()
# clean-up the created files
file.remove("Net1.rpt") 

determine the next hydraulic step

Description

ENnextH determines the length of time until the next hydraulic event occurs in an extended period simulation.

Usage

ENnextH()

Details

This function is used in conjunction with ENrunH to perform an extended period hydraulic analysis (see example below).

The return value is automatically computed as the smaller of:

• the time interval until the next hydraulic time step begins

• the time interval until the next reporting time step begins

• the time interval until the next change in demands occurs

• the time interval until a tank becomes full or empty

• the time interval until a control or rule fires

Value

An integer, the time (in seconds) until next hydraulic event occurs or 0 if at the end of the simulation period.

See Also

ENopenH, ENinitH, ENrunH, ENcloseH, ENsettimeparam

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
  # store simulation times
  t = NULL
  ENopenH()
  ENinitH(11)
  repeat {
    t <- c(t, ENrunH())
    tstep <- ENnextH()
    if (tstep == 0) {
      break
    }
  }
  ENcloseH()
  ENclose()
# clean-up the created files
file.remove("Net1.rpt") 
  

Advances WQ simulation to start of the next hydraulic time period.

Description

Advances WQ simulation to start of the next hydraulic time period.

Usage

ENnextQ()

Value

seconds until next hydraulic event occurs or 0 if at the end of the simulation period.

Examples

inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENsolveH()
ENsetqualtype("EN_CHEM", "Chlorine", "mg/L", "")
ENopenQ()
ENinitQ(0)
ENrunQ()
ENnextQ()
ENrunQ()
ENcloseQ()
ENclose()
# clean-up the created files
file.remove("Net1.rpt") 

Open the EPANET Toolkit.

Description

ENopen opens the EPANET Toolkit to analyze a particular water distribution system.

Usage

ENopen(inpFileName, rptFileName, outFileName)

Arguments

Value

returns NULL invisibly on success or raises an error or warning.

Note

If there is no need to save an EPANET's binary Output file, then outFileName can be an empty string ("").

If rptFileName is an empty string, reporting will be made to the operating system stdout device (which is usually the console/terminal).

enOpen must be called before any of the other toolkit functions are used. The only exception is enEpanet.

See Also

ENclose

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENclose()

Open hydraulics analysis system.

Description

ENopenH opens the EPANET hydraulics analysis system.

Usage

ENopenH()

Details

Call ENopenH prior to running the first hydraulic analysis using the ENinitH-ENrunH-ENnextH sequence. Multiple analyses can be made before calling ENcloseH to close the hydraulic analysis system.

Do not call this function if ENsolveH is being used to run a complete hydraulic analysis.

Value

Returns NULL invisibly; called for side effect

See Also

ENinitH, ENrunH, ENnextH, ENcloseH

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENopenH()
ENinitH(0)
ENrunH()
ENcloseH()
ENclose()
# clean-up the created files
file.remove("Net1.rpt") 

Sets up for Water Quality analysis

Description

Sets up for Water Quality analysis

Usage

ENopenQ()

Value

Returns NULL invisibly on success or throws an error or warning

Examples

inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENsolveH()
ENsetqualtype("EN_CHEM", "Chlorine", "mg/L", "")
ENopenQ()
ENinitQ(0)
ENrunQ()
ENcloseQ()
ENclose()
# clean-up the created files
file.remove("Net1.rpt") 

Write simulation report to the report file

Description

Write simulation report to the report file

Usage

ENreport()

Value

Returns NULL invisibly; called for side effect

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt", "Net1.bin")
ENsolveH()
ENsolveQ()
ENreport()
ENclose()
# clean up the created files 
file.remove("Net1.rpt") 
file.remove("Net1.bin") 

Resets a project's report options to their default values.

Description

Resets a project's report options to their default values.

Usage

ENresetreport()

Details

After calling this function the default reporting options are in effect. These are:

• no status report

• no energy report

• no nodes reported on

• no links reported on

• node variables reported to 2 decimal places

• link variables reported to 2 decimal places (3 for friction factor)

• node variables reported are elevation, head, pressure, and quality

• link variables reported are flow, velocity, and head loss.

Value

Returns NULL invisibly; called for side effect

run hydraulics engine

Description

ENrunH Runs a single period hydraulic analysis, retrieving the current simulation clock time t.

Usage

ENrunH()

Details

Use ENrunH along with ENnextH in a while loop to analyze hydraulics in each period of an extended period simulation. This process automatically updates the simulation clock time so treat t as a read-only variable.

ENinitH must have been called prior to running the ENrunH-ENnextH loop.

See ENnextH for an example of using this function.

Value

Current simulation clock time.

See Also

ENopenH, ENinitH, ENnextH, ENcloseH

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENopenH()
ENinitH(0)
ENrunH()
ENcloseH()
ENclose()
# clean-up the created files
file.remove("Net1.rpt") 

Computs WQ results at current time .

Description

Computs WQ results at current time .

Usage

ENrunQ()

Details

used in a loop with ENnextQ() to run an extended period WQ simulation.

Value

current simulation time in seconds

Examples

inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENsolveH()
ENsetqualtype("EN_CHEM", "Chlorine", "mg/L", "")
ENopenQ()
ENinitQ(0)
ENrunQ()
ENcloseQ()
ENclose()
# clean-up the created files
file.remove("Net1.rpt") 

ENsaveH Saves hydraulic results to binary file

Description

ENsaveH

Saves hydraulic results to binary file

Usage

ENsaveH()

Details

Must be called before ENreport() if no WQ simulation has been made. Should not be called if ENsolveQ() will be used.

Value

Returns NULL invisibly; called for side effect

Saves temporary hydraulics file to disk

Description

Saves temporary hydraulics file to disk

Usage

ENsavehydfile(hydfile)

Arguments

Details

Use this function to save the current set of hydraulics results to a file, either for post-processing or to be used at a later time by calling ENusehydfile.

The hydraulics file contains nodal demands and heads and link flows, status, and settings for all hydraulic time steps, even intermediate ones.

Before calling this function hydraulic results must have been generated and saved by having called ENsolveH or the ENinitH - ENrunH - ENnextH sequence with the initflag argument of ENinitH set to EN_SAVE or EN_SAVE_AND_INIT.

Value

Returns NULL invisibly; called for side effect

ENaveinpfile Saves current data to "INP" formatted text file.

Description

ENaveinpfile

Saves current data to "INP" formatted text file.

Usage

ENsaveinpfile(filename)

Arguments

Value

Returns NULL invisibly; called for side effect

Sets the base demand for one of a node's demand categories.

Description

Sets the base demand for one of a node's demand categories.

Usage

ENsetbasedemand(nodeindex, demand_index = 1, base_demand)

Arguments

Set the parameters of a simple control statement

Description

ENsetcontrol sets the parameters of a simple control statements.

Usage

ENsetcontrol(
  cindex,
  ctype = NULL,
  lindex = NULL,
  setting = NULL,
  nindex = NULL,
  level = NULL
)

Arguments

Details

Controls are indexed starting from 1 in the order in which they were entered into the [CONTROLS] section of the EPANET input file. Control type codes consist of the following:

For pipes, a setting of 0 means the pipe is closed and 1 means it is open. For a pump, the setting contains the pump's speed, with 0 meaning the pump is closed and 1 meaning it is open at its normal speed. For a valve, the setting refers to the valve's pressure, flow, or loss coefficient, depending on valve type.

For Timer or Time-of-Day controls set the nindex parameter to 0.

For level controls, if the controlling node nindex is a tank then the level parameter should be a water level above the tank bottom (not an elevation). Otherwise level should be a junction pressure.

To remove a control on a particular link, set the lindex parameter to 0. Values for the other parameters in the function will be ignored.

Value

Returns NULL invisibly on success or raises an error or warning.

See Also

ENsetcontrol

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetcontrol(1)
ENsetcontrol(1, ctype=2, lindex=3, setting=1, nindex=0, level=54)		
ENgetcontrol(1)
ENclose() 

Set coordinates for a node

Description

Set coordinates for a node

Usage

ENsetcoord(nodeindex, x, y)

Arguments

Value

returns NULL invisibily on success or raises an error or warning

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetcoord(3)
ENsetcoord(3,33,44)
ENgetcoord(3)
ENclose()

Changes the ID name of a data curve given its index.

Description

Changes the ID name of a data curve given its index.

Usage

ENsetcurveid(index, id)

Arguments

Value

null invisibly

Sets the value of a single data point for a curve.

Description

Sets the value of a single data point for a curve.

Usage

ENsetcurvevalue(curveIndex, pointIndex, x, y)

Arguments

Value

null invisibly

Sets the type of demand model to use and its parameters.

Description

Sets the type of demand model to use and its parameters.

Usage

ENsetdemandmodel(model, pmin, preq, pexp)

Arguments

Sets the name of a node's demand category.

Description

Sets the name of a node's demand category.

Usage

ENsetdemandname(nodeindex, demand_index, demand_name)

Arguments

Sets the index of a time pattern used for one of a node's demand categories.

Description

Sets the index of a time pattern used for one of a node's demand categories.

Usage

ENsetdemandpattern(nodeindex, demand_index, pattern_index)

Arguments

Details

Specifying a pattern index of 0 indicates that no time pattern is assigned to the demand category.

Set properties of an ELSE action in a rule-based control

Description

Set properties of an ELSE action in a rule-based control

Usage

ENsetelseaction(ruleIndex, actionIndex, linkIndex, status, setting)

Arguments

Value

null invisibly

Sets flow units.

Description

Sets flow units.

Usage

ENsetflowunits(units)

Arguments

Details

Flow units in liters or cubic meters implies that SI metric units are used for all other quantities in addition to flow. Otherwise US Customary units are employed.

Value

null invisibly

Sets index of head curve used by a pump

Description

Sets index of head curve used by a pump

Usage

ENsetheadcurveindex(linkindex, curveindex)

Arguments

Value

null invisibly

Sets properties for a junction

Description

Sets properties for a junction

Usage

ENsetjuncdata(nodeindex, elevation, demand, demand_pattern = "")

Arguments

Details

These properties have units that depend on the units used for flow rate.

Change the ID of a link

Description

Change the ID of a link

Usage

ENsetlinkid(index, newid)

Arguments

Set the indexes of a link's start- and end-nodes

Description

Set the indexes of a link's start- and end-nodes

Usage

ENsetlinknodes(index, node1_index, node2_index)

Arguments

Change a link's type

Description

Change a link's type

Usage

ENsetlinktype(index, type, action = "EN_UNCONDITIONAL")

Arguments

Details

Link type is one of: EN_CVPIPE, EN_PIPE, EN_PUMP, EN_PRV, EN_PSV, EN_PBV, EN_FCV, EN_TCV, EN_GPV

If actionCode is EN_UNCONDITIONAL then all simple and rule-based controls that contain the link are deleted when the link's type is changed. If set to EN_CONDITIONAL then the type change is cancelled if the link appears in any control and error 261 is returned.

Value

link index after the type change

Set a parameter value for a link

Description

Set a parameter value for a link

Usage

ENsetlinkvalue(index, paramcode, value)

Arguments

Details

Links are indexed starting from 1.

Link parameter codes consist of the following constants:

Values are supplied in units which depend on the units used for flow rate in the EPANET input file (see Units of Measurement). Use EN_INITSTATUS and EN_INITSETTING to set the design value for a link's status or setting that exists prior to the start of a simulation. Use EN_STATUS and EN_SETTING to change these values while a simulation is being run (within the ENrunH - ENnextH loop).

If a control valve has its status explicitly set to OPEN or CLOSED, then to make it active again during a simulation you must provide a new valve setting value using the EN_SETTING parameter.

For pipes, either EN_ROUGHNESS or EN_INITSETTING can be used to change roughness.

Value

Returns NULL invisibly on success or raises a warning or error.

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen(inp, "Net1.rpt")
ENgetlinkvalue(8, "EN_LENGTH")
ENsetlinkvalue(8, "EN_LENGTH", 3333)
ENgetlinkvalue(8, "EN_DIAMETER")
ENclose()

Changes the ID name of a node

Description

Changes the ID name of a node

Usage

ENsetnodeid(nodeindex, newid)

Arguments

Set the parameter value for a node.

Description

ENsetnodevalue sets parameter value for one node.

Usage

ENsetnodevalue(index, paramcode = NULL, value = NULL)

Arguments

Details

Nodes are indexed starting from 1 in the order in which they were entered into the [NODES] section of the EPANET input file.

Node parameter codes consist of the following constants:

Source types are identified with the following constants:

See [SOURCES] for a description of these source types.

Values are supplied in units which depend on the units used for flow rate in the EPANET input file (see Units of Measurement).

Value

returns NULL invisibly on success or raises an error or warning.

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetnodevalue(3, "EN_ELEVATION")
ENsetnodevalue(3, "EN_ELEVATION", 777)
ENgetnodevalue(3, "EN_ELEVATION")
ENclose()

Set the value of a particular analysis option.

Description

ENsetoption sets the value of a particular analysis option.

Usage

ENsetoption(optioncode, value)

Arguments

Details

Option codes consist of the following constants:

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetoption("EN_TRIALS")
ENsetoption("EN_TRIALS", 22)
ENgetoption("EN_TRIALS")
ENclose()

Set all of the multiplier factors for a specific time pattern.

Description

ENsetpattern sets all of the multiplier factors for a specific time pattern.

Usage

ENsetpattern(index, factors)

Arguments

Details

Pattern indexes are consecutive integers starting from 1.

Use this function to redefine (and resize) a time pattern all at once; use ENsetpatternvalue to revise pattern factors in specific time periods of a pattern.

See Also

ENgetpatternindex, ENgetpatternlen, ENgetpatternvalue, ENsetpatternvalue

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENsetpattern(1, 1:10)		
ENgetpatternvalue(1,1)
ENgetpatternvalue(1,10)
ENclose()

Change the ID name of a time pattern given its index.

Description

Change the ID name of a time pattern given its index.

Usage

ENsetpatternid(index, id)

Arguments

Value

NULL invisibly

set pattern value

Description

set pattern value

Usage

ENsetpatternvalue(index, period, value)

Arguments

Value

returns NULL inivisbly on success

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetpatternvalue(1,3)
ENsetpatternvalue(1,3, 9.876)
ENgetpatternvalue(1,3)
ENclose()

Sets the properties of a premise in a rule-based control.

Description

Sets the properties of a premise in a rule-based control.

Usage

ENsetpremise(
  ruleIndex,
  premiseIndex,
  logop,
  object,
  objIndex,
  variable,
  relop,
  status,
  value
)

Arguments

Value

null

Sets the index of an object in a premise of a rule-based control

Description

Sets the index of an object in a premise of a rule-based control

Usage

ENsetpremiseindex(ruleIndex, premiseIndex, objIndex)

Arguments

Value

null

Sets the status being compared to in a premise of a rule-based control

Description

Sets the status being compared to in a premise of a rule-based control

Usage

ENsetpremisestatus(ruleIndex, premiseIndex, status)

Arguments

Value

null

Sets the value in a premise of a rule-based control

Description

Sets the value in a premise of a rule-based control

Usage

ENsetpremisevalue(ruleIndex, premiseIndex, value)

Arguments

Value

null

Set the type of water quality analysis called for.

Description

ENsetqualtype sets the type of water quality analysis called for.

Usage

ENsetqualtype(qualcode, chemname = "", chemunits = "", tracenode = "")

Arguments

Details

Water quality analysis codes are as follows:

Chemical name and units can be an empty string if the analysis is not for a chemical. The same holds for the trace node if the analysis is not for source tracing. Note that the trace node is specified by ID and not by index.

Value

returns NULL invisibly on success

See Also

ENgetqualtype

Examples

inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt")
ENgetqualtype()
ENsetqualtype("EN_CHEM", "Chlorine", "mg/L", "")
ENgetqualtype()
ENclose()
# clean-up the created files
file.remove("Net1.rpt") 

Processes a reporting format command.

Description

Processes a reporting format command.

Usage

ENsetreport(format)

Arguments

Sets the priority of a rule-based control.

Description

Sets the priority of a rule-based control.

Usage

ENsetrulepriority(index, priority)

Arguments

Value

null

Sets the level of hydraulic status reporting.

Description

Sets the level of hydraulic status reporting.

Usage

ENsetstatusreport(level)

Arguments

Sets properties for a tank

Description

Sets properties for a tank

Usage

ENsettankdata(
  nodeindex,
  elevation,
  init_level,
  min_level,
  max_level,
  diameter,
  min_volume,
  volume_curve = ""
)

Arguments

Set properties of THEN action in a rule-based control

Description

Set properties of THEN action in a rule-based control

Usage

ENsetthenaction(ruleIndex, actionIndex, linkIndex, status, setting)

Arguments

Value

null

Set the value of a time parameter.

Description

ENsettimeparam sets the value of a time parameter.

Usage

ENsettimeparam(paramcode, timevalue)

Arguments

Details

Time parameter codes consist of the following constants:

Do not change time parameters after calling ENinitH in a hydraulic analysis or ENinitQ in a water quality analysis

Examples

# path to Net1.inp example file included with this package 
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp") 
ENopen(inp, "Net1.rpt")
ENgettimeparam("EN_HYDSTEP")
ENsettimeparam("EN_HYDSTEP", 600)
ENgettimeparam("EN_HYDSTEP")
ENclose()

Set a link's vertices

Description

Set a link's vertices

Usage

ENsetvertices(index, x, y)

Arguments

ENsolveH

Description

Solves the network hydraulics for all time periods

Usage

ENsolveH()

Value

Returns NULL invisibly; called for side effect

Examples

# path to Net1.inp example file included with this package
inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt","Net1.bin")
ENsolveH()
ENsolveQ()
ENgetnodevalue(2, "EN_PRESSURE")
ENclose() 
# clean-up the created files
file.remove("Net1.rpt") 
file.remove("Net1.bin") 

Solve network water quality for all time periods

Description

Solve network water quality for all time periods

Usage

ENsolveQ()

Value

Returns NULL invisibly on success or throws an error or warning

Examples

inp <- file.path( find.package("epanet2toolkit"), "extdata","Net1.inp")  
ENopen( inp, "Net1.rpt","Net1.bin")
ENsolveH()
ENsetqualtype("EN_CHEM", "Chlorine", "mg/L", "")
ENsolveQ()
ENclose()
# clean-up the created files
file.remove("Net1.rpt") 
file.remove("Net1.bin") 

Advances WQ simulation one water quality time step.

Description

Advances WQ simulation one water quality time step.

Usage

ENstepQ()

Value

time remaining in the overall simulation

Uses previously saved binary hydraulics file to supply a project's hydraulics.

Description

Uses previously saved binary hydraulics file to supply a project's hydraulics.

Usage

ENusehydfile(hydfile)

Arguments

Details

Call this function to re-use a set of hydraulic analysis results saved previously. This can save computational time if water quality analyses are being made under the same set of hydraulic conditions.

Do not call this function while the hydraulics solver is open.