OWA-EPANET Toolkit  2.2
Usage

The following topics briefly describe how to accomplish some basic tasks using the OWA-EPANET Toolkit in C/C++ code. See the Examples topic for code listings of complete applications of the Toolkit.

Creating a Project

Before any use is made of the Toolkit, a project and its handle must be created. After all processing is completed the project should be deleted. See the code snippet below:

EN_Project ph; // a project handle
// Call functions that perform desired analysis

Detecting Error Conditions

All of the Toolkit functions return an error/warning code. A 0 indicates that the function ran successfully. A number greater than 0 but less than 100 indicates that a warning condition was generated while a number higher than 100 indicates that the function failed.

The meaning of specific error and warning codes are listed in the Error Codes and Warning Codes sections of this guide. The Toolkit function EN_geterror can be used to obtain the text of a specific error/warning code. The following example uses a macro named ERRCODE along with a variable named errcode to execute Toolkit commands only if no fatal errors have already been detected:

#define ERRCODE(x) (errcode = ((errcode > 100) ? (errcode) : (x)))
void runHydraulics(EN_Project ph, char *inputFile, char *reportFile)
{
int errcode = 0;
char errmsg[EN_MAXMSG + 1];
ERRCODE(EN_open(ph, inputFile, reportFile, ""));
ERRCODE(EN_solveH(ph));
ERRCODE(EN_saveH(ph));
ERRCODE(EN_report(ph));
EN_geterror(ph, errcode, errmsg);
if (errcode) printf("\n%s\n", errmsg);
}

Providing Network Data

Once a project is created there are two ways in which it can be populated with data. The first is to use the EN_open function to load an EPANET-formatted Input File that provides a description of the network to be analyzed. This function should be called immediately after a project is created. It takes as arguments the name of the input file to open and the names of a report file and a binary output file, both of which are optional. Here is a code sample showing this approach:

int errcode;
errcode = EN_open(ph, "net1.inp", "net1.rpt", "");
if (errcode == 0)
{
// Call functions that perform desired analysis
}

After an input file has been loaded in this fashion the resulting network can have objects added or deleted, and their properties set using the various Toolkit functions .

The second method for supplying network data to a project is to use the Toolkit's functions to add objects and to set their properties via code. In this case the EN_init function should be called immediately after creating a project, passing in the names of a report and binary output files (both optional) as well as the choices of flow units and head loss formulas to use. After that the various EN_add functions, such as EN_addnode, EN_addlink, EN_addpattern, EN_addcontrol, etc., can be called to add new objects to the network. Here is a partial example of constructing a network from code:

int index;
EN_init(ph, "net1.rpt", "", EN_GPM, EN_HW);
EN_addnode(ph, "J1", EN_JUNCTION, &index);
EN_addnode(ph, "J2", EN_JUNCTION, &index);
EN_addlink(ph, "P1", EN_PIPE, "J1", "J2", &index);
// additional function calls to complete building the network

See the Network Building Example for a more complete example. The labels used to name objects cannot contain spaces, semi-colons, or double quotes nor exceed EN_MAXID characters in length. While adding objects their properties can be set as described in the next section. Attemtping to change a network's structure by adding or deleting nodes and links while the Toolkit's hydraulic or water quality solvers are open will result in an error condition.

Setting Object Properties

The Toolkit contains several functions for retrieving and setting the properties of a network's objects and its analysis options. The names of retrieval functions all begin with EN_get (e.g., EN_getnodevalue, EN_getoption, etc.) while the functions used for setting parameter values begin with EN_set (e.g., EN_setnodevalue, EN_setoption, etc.).

Most of these functions use an index number to refer to a specific network component (such as a node, link, time pattern or data curve). This number is simply the position of the component in the list of all components of similar type (e.g., node 10 is the tenth node, starting from 1, in the network) and is not the same as the ID label assigned to the component. A series of functions exist to determine a component's index number given its ID label (see EN_getnodeindex, EN_getlinkindex, EN_getpatternindex, and EN_getcurveindex). Likewise, functions exist to retrieve a component's ID label given its index number (see EN_getlinkid, EN_getnodeid, EN_getpatternid, and EN_getcurveid). The EN_getcount function can be used to determine the number of different components in the network. Be aware that a component's index can change as elements are added or deleted from the network. The EN_addnode and EN_addlink functions return the index of the newly added node or link as a convenience for immediately setting their properties.

The code below is an example of using the property retrieval and setting functions. It changes all links with diameter of 10 inches to 12 inches.

void changeDiameters(EN_Project ph)
{
int i, nLinks;
double diam;
EN_getcount(ph, EN_LINKCOUNT, &nLinks);
for (i = 1; i <= nLinks; i++)
{
EN_getlinkvalue(ph, i, EN_DIAMETER, &diam);
if (diam == 10) EN_setlinkvalue(ph, i, EN_DIAMETER, 12);
}
}

Computing Hydraulics

There are two ways to use the Toolkit to run a hydraulic analysis:

  1. Use the EN_solveH function to run a complete extended period analysis, without having access to intermediate results.
  2. Use the EN_openH - EN_initH - EN_runH - EN_nextH - EN_closeH series of functions to step through the simulation one hydraulic time step at a time.

Method 1 is useful if you only want to run a single hydraulic analysis, perhaps to provide input to a water quality analysis. With this method hydraulic results are always saved to an intermediate hydraulics file at every time step.

Method 2 must be used if you need to access results between time steps or if you wish to run many analyses efficiently. To accomplish the latter, you would make only one call to EN_openH to begin the process, then make successive calls to EN_initH - EN_runH - EN_nextH to perform each analysis, and finally call EN_closeH to close down the hydraulics system. An example of this is shown below (calls to EN_nextH are not needed because we are only making a single period analysis in this example).

void runHydraulics(EN_Project ph, int nRuns)
{
int i;
long t;
EN_openH(ph);
for (i = 1; i <= nRuns; i++)
{
// user-supplied function to set parameters
setparams(ph, i);
// initialize hydraulics; don't save them to file
// solve hydraulics
EN_runH(ph, &t);
// user-supplied function to process results
getresults(ph, i);
}
EN_closeH(ph);
}

Computing Water Quality

As with a hydraulic analysis, there are two ways to carry out a water quality analysis:

  1. Use the EN_solveQ function to run a complete extended period analysis, without having access to intermediate results. A complete set of hydraulic results must have been generated either from running a hydraulic analysis or from importing a saved hydraulics file from a previous run.
  2. Use the EN_openQ - EN_initQ - EN_runQ - EN_nextQ - EN_closeQ series of functions to step through the simulation one hydraulic time step at a time. (Replacing EN_nextQ with EN_stepQ will step through one water quality time step at a time.)

The second option can either be carried out after a hydraulic analysis has been run or simultaneously as hydraulics are being computed. Example code for these two alternatives is shown below:

int runSequentialQuality(EN_Project ph)
{
int err;
long t, tStep;
err = EN_solveH(ph);
if (err > 100) return err;
EN_openQ(ph);
do {
EN_runQ(ph, &t);
// Access quality results for time t here
EN_nextQ(ph, &tStep);
} while (tStep > 0);
EN_closeQ(ph);
return 0;
}
int runConcurrentQuality(EN_Project ph)
{
int err = 0;
long t, tStep;
EN_openH(ph);
EN_openQ(ph);
do {
err = EN_runH(ph, &t);
if (err > 100) break;
EN_runQ(ph, &t);
// Access hydraulic & quality results for time t here
EN_nextH(ph, &tStep);
EN_nextQ(ph, &tStep);
} while (tStep > 0);
EN_closeH(ph);
EN_closeQ(ph);
return err;
}

Retrieving Computed Results

The EN_getnodevalue and EN_getlinkvalue functions can also be used to retrieve the results of hydraulic and water quality simulations. The computed parameters (and their Toolkit codes) that can be retrieved are as follows:

For Nodes: For Links:
EN_DEMAND (demand) EN_FLOW (flow rate)
EN_DEMANDDEFICIT (demand deficit) EN_VELOCITY (flow velocity)
EN_HEAD (hydraulic head) EN_HEADLOSS (head loss)
EN_PRESSURE (pressure) EN_STATUS (link status)
EN_TANKLEVEL (tank water level) EN_SETTING (pump speed or valve setting)
EN_TANKVOLUME (tank water volume) EN_ENERGY (pump energy usage)
EN_QUALITY (water quality) EN_PUMP_EFFIC (pump efficiency)
EN_SOURCEMASS (source mass inflow)

The following code shows how to retrieve the pressure at each node of a network after each time step of a hydraulic analysis (writetofile is a user-defined function that will write a record to a file):

void getPressures(EN_Project ph)
{
int i, numNodes;
long t, tStep;
double p;
char id[EN_MAXID + 1];
EN_getcount(ph, EN_NODECOUNT, &numNodes);
EN_openH(ph);
do {
EN_runH(ph, &t);
for (i = 1; i <= NumNodes; i++) {
EN_getnodeid(ph, i, id);
writetofile(t, id, p);
}
EN_nextH(&tStep);
} while (tStep > 0);
EN_closeH(ph);
}

Producing a Report

The Toolkit has some built-in capabilities to produce formatted output results saved to a file. More specialized reporting needs can always be handled by writing custom code.

The EN_setreport function is used to define the format of a report while the EN_report function actually writes the report. The latter should be called only after a hydraulic or water quality analysis has been made. An example of creating a report that lists all nodes where the pressure variation over the duration of the simulation exceeds 20 psi is shown below:

void reportPressureVariation(EN_Project ph)
{
// Compute ranges (max - min)
// Solve and save hydraulics
EN_solveH(ph);
EN_saveH(ph);
// Define contents of the report
EN_setreport(ph, "FILE myfile.rpt");
EN_setreport(ph, "NODES ALL");
EN_setreport(ph, "PRESSURE PRECISION 1");
EN_setreport(ph, "PRESSURE ABOVE 20");
// Write the report to file
EN_report(ph);
}
EN_PIPE
Pipe.
Definition: epanet2_enums.h:184
EN_settimeparam
int EN_settimeparam(EN_Project ph, int param, long value)
Sets the value of a time parameter.
EN_getnodevalue
int EN_getnodevalue(EN_Project ph, int index, int property, double *value)
Retrieves a property value for a node.
EN_geterror
int EN_geterror(int errcode, char *out_errmsg, int maxLen)
Returns the text of an error message generated by an error code.
EN_RANGE
Report maximum - minimum over simulation period.
Definition: epanet2_enums.h:348
EN_saveH
int EN_saveH(EN_Project ph)
Transfers a project's hydraulics results from its temporary hydraulics file to its binary output file...
EN_closeH
int EN_closeH(EN_Project ph)
Closes the hydraulic solver freeing all of its allocated memory.
EN_open
int EN_open(EN_Project ph, const char *inpFile, const char *rptFile, const char *outFile)
Opens an EPANET input file & reads in network data.
EN_MAXMSG
Max. # characters in message text.
Definition: epanet2_enums.h:30
EN_getcount
int EN_getcount(EN_Project ph, int object, int *count)
Retrieves the number of objects of a given type in a project.
EN_addnode
int EN_addnode(EN_Project ph, char *id, int nodeType, int *index)
Adds a new node to a project.
EN_GPM
Gallons per minute.
Definition: epanet2_enums.h:265
EN_Project
struct Project * EN_Project
The EPANET Project wrapper object.
Definition: epanet2_2.h:49
EN_solveH
int EN_solveH(EN_Project ph)
Runs a complete hydraulic simulation with results for all time periods written to a temporary hydraul...
EN_DIAMETER
Pipe/valve diameter.
Definition: epanet2_enums.h:75
EN_nextH
int EN_nextH(EN_Project ph, long *tStep)
Determines the length of time until the next hydraulic event occurs in an extended period simulation.
EN_setreport
int EN_setreport(EN_Project ph, char *format)
Processes a reporting format command.
EN_createproject
int EN_createproject(EN_Project *ph)
Creates an EPANET project.
EN_resetreport
int EN_resetreport(EN_Project ph)
Resets a project's report options to their default values.
EN_closeQ
int EN_closeQ(EN_Project ph)
Closes the water quality solver, freeing all of its allocated memory.
EN_initQ
int EN_initQ(EN_Project ph, int saveFlag)
Initializes a network prior to running a water quality analysis.
EN_init
int EN_init(EN_Project ph, const char *rptFile, const char *outFile, int unitsType, int headLossType)
Initializes an EPANET project.
EN_MAXID
Max. # characters in ID name.
Definition: epanet2_enums.h:29
EN_PRESSURE
Current computed pressure (read only)
Definition: epanet2_enums.h:50
EN_LINKCOUNT
Number of links (pipes + pumps + valves)
Definition: epanet2_enums.h:161
EN_STATISTIC
Reporting statistic code (see EN_StatisticType)
Definition: epanet2_enums.h:115
EN_openH
int EN_openH(EN_Project ph)
Opens a project's hydraulic solver.
EN_getnodeid
int EN_getnodeid(EN_Project ph, int index, char *out_id)
Gets the ID name of a node given its index.
EN_report
int EN_report(EN_Project ph)
Writes simulation results in a tabular format to a project's report file.
EN_NODECOUNT
Number of nodes (junctions + tanks + reservoirs)
Definition: epanet2_enums.h:159
EN_runH
int EN_runH(EN_Project ph, long *currentTime)
Computes a hydraulic solution for the current point in time.
EN_nextQ
int EN_nextQ(EN_Project ph, long *tStep)
Advances a water quality simulation over the time until the next hydraulic event.
EN_HW
Hazen-Williams.
Definition: epanet2_enums.h:251
EN_NOSAVE
Don't save hydraulics; don't re-initialize flows.
Definition: epanet2_enums.h:369
EN_runQ
int EN_runQ(EN_Project ph, long *currentTime)
Makes hydraulic and water quality results at the start of the current time period available to a proj...
EN_deleteproject
int EN_deleteproject(EN_Project ph)
Deletes a currently opened EPANET project.
EN_openQ
int EN_openQ(EN_Project ph)
Opens a project's water quality solver.
EN_initH
int EN_initH(EN_Project ph, int initFlag)
Initializes a network prior to running a hydraulic analysis.
EN_JUNCTION
Junction node.
Definition: epanet2_enums.h:173