JIANG/EPANET
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

rethinking the python wrapper (#511)

Browse Source 
* renames certain function parameter declarations and removes double pointer call from the deleteproject function

* deprecates conditonal compilation, removes python-specific headers and function renaming

* fixes tests and docs

* fixes test
This commit is contained in:
Sam Hatchett
2019-07-17 15:19:25 -04:00
committed by GitHub
parent 4cc16913df
commit 3fe11b98ee
18 changed files with 216 additions and 1240 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/modules.dox
View File

@@ -67,7 +67,7 @@ These are the toolkit's enumerated types whose members are used as function argu
@addtogroup Project
@{
@fn int EN_createproject(EN_Project *ph)
@fn int EN_deleteproject(EN_Project *ph)
@fn int EN_deleteproject(EN_Project ph)
@fn int EN_runproject(EN_Project ph, const char *f1, const char *f2, const char *f3, void (*pviewprog)(char *))
@fn int EN_init(EN_Project ph, const char *rptFile, const char *outFile, int unitsType, int headLossType)
@fn int EN_open(EN_Project ph, const char *inpFile, const char *rptFile, const char *binOutFile)
@@ -376,5 +376,5 @@ These are the toolkit's enumerated types whose members are used as function argu
|4 | Pumps cannot deliver enough flow or head - one or more pumps were forced to either shut down (due to insufficient head) or operate beyond the maximum rated flow |
|5 | Valves cannot deliver enough flow - one or more flow control valves could not deliver the required flow even when fully open |
|6 | System has negative pressures - negative pressures occurred at one or more junctions with positive demand |
*/

144
doc/toolkit-examples.dox
View File

@@ -9,7 +9,7 @@ Here are several examples of how the Toolkit can be used for different types of
*/
/** @page Example1 Embedded Engine Example
This example shows how simple it is for the Toolkit to provide a network analysis engine for other applications. There are three steps that the application would need to take:
This example shows how simple it is for the Toolkit to provide a network analysis engine for other applications. There are three steps that the application would need to take:
-# Have the application write network data to an EPANET-formatted input file.
-# Create a project and call @ref EN_runproject, supplying the name of the EPANET input file, the name of a Report file where status and error messages are written, and the name of a binary Output file which will contain analysis results.
@@ -32,9 +32,9 @@ int runEpanet(char* inpFile, char* rptFile, char* outFile)
EN_project ph;
EN_createproject(&pH);
errcode = EN_runproject(ph, inpFile, rptFile, outFile, &writeConsole);
EN_deleteproject(&ph);
EN_deleteproject(ph);
return errcode;
}
}
\endcode
*/
@@ -62,12 +62,12 @@ void netbuilder()
EN_Project ph;
EN_createproject(&ph);
EN_init(ph, "", "", EN_GPM, EN_HW);
// Add the first junction node to the project with
// an elevation of 700 ft and a demand of 0
// an elevation of 700 ft and a demand of 0
EN_addnode(ph, "J1", EN_JUNCTION, &index);
EN_setjuncdata(ph, index, 700, 0, "");
// Add the remaining two junctions with elevations of
// 710 ft and demands of 250 and 500 gpm, respectively
EN_addnode(ph, "J2", EN_JUNCTION, &index);
@@ -84,7 +84,7 @@ void netbuilder()
// and a diameter of 50.5 ft
EN_addnode(ph, "T1", EN_TANK, &index);
EN_settankdata(ph, index, 850, 120, 100, 150, 50.5, 0, "");
// Add the pipes to the project, setting their length,
// diameter, and roughness values
EN_addlink(ph, "P1", EN_PIPE, "J1", "J2", &index);
@@ -95,10 +95,10 @@ void netbuilder()
EN_setpipedata(ph, index, 5280, 14, 100, 0);
EN_addlink(ph, "P4", EN_PIPE, "J2", "J3", &index);
EN_setpipedata(ph, index, 5280, 14, 100, 0);
// Add a pump to the project
EN_addlink(ph, "PUMP", EN_PUMP, "R1", "J1", &index);
// Create a single point head curve (index = 1) and
// assign it to the pump
EN_addcurve(ph, "C1");
@@ -109,53 +109,53 @@ void netbuilder()
EN_saveinpfile(ph, "example2.inp");
// Delete the project
EN_deleteproject(&ph);
}
EN_deleteproject(ph);
}
\endcode
*/
/** @page Example3 Hydrant Rating Curve Example
This example illustrates how the Toolkit could be used to develop a hydrant rating curve used in fire flow studies. This curve shows the amount of flow available at a node in the system as a function of pressure. The curve is generated by running a number of steady state hydraulic analyses with the node of interest subjected to a different demand in each analysis. For this example we assume that the ID label of the node of interest is `MyNode` and that `N` different demand levels stored in the array `D` need to be examined. The corresponding pressures will be stored in `P`. To keep the code more readable, no error checking is made on the results returned from the Toolkit function calls.
This example illustrates how the Toolkit could be used to develop a hydrant rating curve used in fire flow studies. This curve shows the amount of flow available at a node in the system as a function of pressure. The curve is generated by running a number of steady state hydraulic analyses with the node of interest subjected to a different demand in each analysis. For this example we assume that the ID label of the node of interest is `MyNode` and that `N` different demand levels stored in the array `D` need to be examined. The corresponding pressures will be stored in `P`. To keep the code more readable, no error checking is made on the results returned from the Toolkit function calls.
\code {.c}
#include "epanet2_2.h"
#include "epanet2_2.h"
void HydrantRating(char *MyNode, int N, double D[], double P[])
{
void HydrantRating(char *MyNode, int N, double D[], double P[])
{
EN_Project ph;
int i, nodeindex;
long t;
double pressure;
int i, nodeindex;
long t;
double pressure;
// Create a project
EN_createproject(&ph);
// Retrieve network data from an input file
EN_open(ph, "example2.inp", "example2.rpt", "");
EN_open(ph, "example2.inp", "example2.rpt", "");
// Open the hydraulic solver
EN_openH(ph);
EN_openH(ph);
// Get the index of the node of interest
EN_getnodeindex(ph, MyNode, &nodeindex);
EN_getnodeindex(ph, MyNode, &nodeindex);
// Iterate over all demands
for (i=1; i<N; i++)
{
for (i=1; i<N; i++)
{
// Set nodal demand, initialize hydraulics, make a
// single period run, and retrieve pressure
EN_setnodevalue(ph, nodeindex, EN_BASEDEMAND, D[i]);
EN_initH(ph, 0);
EN_runH(ph, &t);
EN_getnodevalue(ph, nodeindex, EN_PRESSURE, &pressure);
P[i] = pressure;
}
EN_setnodevalue(ph, nodeindex, EN_BASEDEMAND, D[i]);
EN_initH(ph, 0);
EN_runH(ph, &t);
EN_getnodevalue(ph, nodeindex, EN_PRESSURE, &pressure);
P[i] = pressure;
}
// Close hydraulics solver & delete the project
EN_closeH(ph);
EN_deleteproject(&ph);
}
EN_closeH(ph);
EN_deleteproject(ph);
}
\endcode
*/
@@ -164,66 +164,66 @@ void HydrantRating(char *MyNode, int N, double D[], double P[])
This example illustrates how the Toolkit could be used to determine the lowest dose of chlorine applied at the entrance to a distribution system needed to ensure that a minimum residual is met throughout the system. We assume that the EPANET input file contains the proper set of kinetic coefficients that describe the rate at which chlorine will decay in the system being studied. In the example code, the ID label of the source node is contained in `SourceID`, the minimum residual target is given by `Ctarget`, and the target is only checked after a start-up duration of 5 days (432,000 seconds). To keep the code more readable, no error checking is made on the results returned from the Toolkit function calls.
\code {.c}
#include "epanet2_2.h"
#include "epanet2_2.h"
double cl2dose(char *SourceID, double Ctarget)
{
int i, nnodes, sourceindex, violation;
double c, csource;
double cl2dose(char *SourceID, double Ctarget)
{
int i, nnodes, sourceindex, violation;
double c, csource;
long t, tstep;
EN_Project ph;
// Open the toolkit & obtain a hydraulic solution
EN_createproject(&ph);
EN_open(ph, "example3.inp", "example3.rpt", "");
EN_solveH(ph);
EN_open(ph, "example3.inp", "example3.rpt", "");
EN_solveH(ph);
// Get the number of nodes and the source node's index
EN_getcount(ph, EN_NODECOUNT, &nnodes);
EN_getnodeindex(ph, SourceID, &sourceindex);
// Get the number of nodes and the source node's index
EN_getcount(ph, EN_NODECOUNT, &nnodes);
EN_getnodeindex(ph, SourceID, &sourceindex);
// Setup the system to analyze for chlorine
// (in case it was not done in the input file)
EN_setqualtype(ph, EN_CHEM, "Chlorine", "mg/L", "");
EN_setqualtype(ph, EN_CHEM, "Chlorine", "mg/L", "");
// Open the water quality solver
EN_openQ(ph);
EN_openQ(ph);
// Begin the search for the source concentration
csource = 0.0;
do {
// Begin the search for the source concentration
csource = 0.0;
do {
// Update source concentration to next level
csource = csource + 0.1;
EN_setnodevalue(ph, sourceindex, EN_SOURCEQUAL, csource);
csource = csource + 0.1;
EN_setnodevalue(ph, sourceindex, EN_SOURCEQUAL, csource);
// Run WQ simulation checking for target violations
violation = 0;
EN_initQ(ph, 0);
do {
EN_runQ(ph, &t);
if (t > 432000) {
for (i=1; i<=nnodes; i++) {
EN_getnodevalue(ph, i, EN_QUALITY, &c);
if (c < Ctarget) {
violation = 1;
break;
}
}
}
EN_nextQ(ph, &tstep);
violation = 0;
EN_initQ(ph, 0);
do {
EN_runQ(ph, &t);
if (t > 432000) {
for (i=1; i<=nnodes; i++) {
EN_getnodevalue(ph, i, EN_QUALITY, &c);
if (c < Ctarget) {
violation = 1;
break;
}
}
}
EN_nextQ(ph, &tstep);
// End WQ run if violation found
} while (!violation && tstep > 0);
} while (!violation && tstep > 0);
// Continue search if violation found
} while (violation && csource <= 4.0);
} while (violation && csource <= 4.0);
// Close up the WQ solver and delete the project
EN_closeQ(ph);
EN_deleteproject(&ph);
return csource;
}
// Close up the WQ solver and delete the project
EN_closeQ(ph);
EN_deleteproject(ph);
return csource;
}
\endcode
*/

122
doc/toolkit-usage.dox
View File

@@ -1,7 +1,7 @@
/**
/**
@page toolkit-usage Usage
The following topics briefly describe how to accomplish some basic tasks using the OWA-EPANET Toolkit. See the @ref ToolkitExamples topic for code listings of complete applications of the Toolkit.
The following topics briefly describe how to accomplish some basic tasks using the OWA-EPANET Toolkit. See the @ref ToolkitExamples topic for code listings of complete applications of the Toolkit.
@section CreateProject Creating a Project
@@ -13,14 +13,14 @@ EN_createproject(&ph);
// Call functions that perform desired analysis
EN_deleteproject(&ph);
EN_deleteproject(ph);
\endcode
@section DetectingErrors 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 @ref ErrorCodes and @ref WarningCodes sections of this guide. The Toolkit function @ref 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:
The meaning of specific error and warning codes are listed in the @ref ErrorCodes and @ref WarningCodes sections of this guide. The Toolkit function @ref 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:
\code {.c}
#define ERRCODE(x) (errcode = ((errcode > 100) ? (errcode) : (x)))
@@ -29,7 +29,7 @@ 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));
@@ -37,7 +37,7 @@ void runHydraulics(EN_Project ph, char *inputFile, char *reportFile)
EN_geterror(ph, errcode, errmsg);
if (errcode) printf("\n%s\n", errmsg);
}
\endcode
\endcode
@section NetworkData Providing Network Data
@@ -45,14 +45,14 @@ Once a project is created there are two ways in which it can be populated with d
\code {.c}
EN_Project ph;
int errcode;
int errcode;
EN_createproject(&ph);
errcode = EN_open(ph, "net1.inp", "net1.rpt", "");
errcode = EN_open(ph, "net1.inp", "net1.rpt", "");
if (errcode == 0)
{
// Call functions that perform desired analysis
}
EN_deleteproject(&ph);
{
// Call functions that perform desired analysis
}
EN_deleteproject(ph);
\endcode
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 .
@@ -78,36 +78,36 @@ The Toolkit contains several functions for retrieving and setting the properties
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 @ref EN_getnodeindex, @ref EN_getlinkindex, @ref EN_getpatternindex, and @ref EN_getcurveindex). Likewise, functions exist to retrieve a component's ID label given its index number (see @ref EN_getlinkid, @ref EN_getnodeid, @ref EN_getpatternid, and @ref EN_getcurveid). The @ref 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 @ref EN_addnode and @ref 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.
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.
\code {.c}
void changeDiameters(EN_Project ph)
{
int i, nLinks;
double diam;
EN_getcount(ph, EN_LINKCOUNT, &nLinks);
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);
{
EN_getlinkvalue(ph, i, EN_DIAMETER, &diam);
if (diam == 10) EN_setlinkvalue(ph, i, EN_DIAMETER, 12);
}
}
}
\endcode
@section hydraulics Computing Hydraulics
There are two ways to use the Toolkit to run a hydraulic analysis:
-# Use the @ref EN_solveH function to run a complete extended period analysis, without having access to intermediate results.
-# Use the @ref EN_openH - @ref EN_initH - @ref EN_runH - @ref EN_nextH - @ref 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.
There are two ways to use the Toolkit to run a hydraulic analysis:
-# Use the @ref EN_solveH function to run a complete extended period analysis, without having access to intermediate results.
-# Use the @ref EN_openH - @ref EN_initH - @ref EN_runH - @ref EN_nextH - @ref EN_closeH series of functions to step through the simulation one hydraulic time step at a time.
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 \b EN_openH to begin the process, then make successive calls to <b>EN_initH - EN_runH - EN_nextH</b> to perform each analysis, and finally call \b EN_closeH to close down the hydraulics system. An example of this is shown below (calls to \b EN_nextH are not needed because we are only making a single period analysis in this example).
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 \b EN_openH to begin the process, then make successive calls to <b>EN_initH - EN_runH - EN_nextH</b> to perform each analysis, and finally call \b EN_closeH to close down the hydraulics system. An example of this is shown below (calls to \b EN_nextH are not needed because we are only making a single period analysis in this example).
\code {.c}
void runHydraulics(EN_Project ph, int nRuns)
{
int i;
int i;
long t;
EN_openH(ph);
for (i = 1; i <= nRuns; i++)
@@ -127,7 +127,7 @@ void runHydraulics(EN_Project ph, int nRuns)
@section quality Computing Water Quality
As with a hydraulic analysis, there are two ways to carry out a water quality analysis:
As with a hydraulic analysis, there are two ways to carry out a water quality analysis:
-# Use the @ref 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.
-# Use the @ref EN_openQ - @ref EN_initQ - @ref EN_runQ - @ref EN_nextQ - @ref EN_closeQ series of functions to step through the simulation one hydraulic time step at a time. (Replacing @ref EN_nextQ with @ref EN_stepQ will step through one water quality time step at a time.)
@@ -144,7 +144,7 @@ int runSequentialQuality(EN_Project ph)
EN_openQ(ph);
EN_initQ(ph, EN_NOSAVE);
do {
EN_runQ(ph, &t);
EN_runQ(ph, &t);
// Access quality results for time t here
EN_nextQ(ph, &tStep);
} while (tStep > 0);
@@ -176,9 +176,9 @@ int runConcurrentQuality(EN_Project ph)
@section results Retrieving Computed Results
The @ref EN_getnodevalue and @ref 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:
The @ref EN_getnodevalue and @ref 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: |
|----------------------------------- | ----------------------------------------- |
|----------------------------------- | ----------------------------------------- |
|\b EN_DEMAND (demand) |\b EN_FLOW (flow rate) |
|\b EN_HEAD (hydraulic head) |\b EN_VELOCITY (flow velocity) |
|\b EN_PRESSURE (pressure) |\b EN_HEADLOSS (head loss) |
@@ -186,57 +186,57 @@ The @ref EN_getnodevalue and @ref EN_getlinkvalue functions can also be used to
|\b EN_TANKVOLUME (tank water volume) |\b EN_SETTING (pump speed or valve setting) |
|\b EN_QUALITY (water quality) |\b EN_ENERGY (pump energy usage) |
|\b EN_SOURCEMASS (source mass inflow)|\b EN_PUMP_EFFIC (pump efficiency) |
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):
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):
\code {.c}
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);
EN_initH(ph, EN_NOSAVE);
do {
EN_runH(ph, &t);
for (i = 1; i <= NumNodes; i++) {
EN_getnodevalue(ph, i, EN_PRESSURE, &p);
EN_getnodeid(ph, i, id);
writetofile(t, id, p);
}
EN_nextH(&tStep);
} while (tStep > 0);
int i, numNodes;
long t, tStep;
double p;
char id[EN_MAXID + 1];
EN_getcount(ph, EN_NODECOUNT, &numNodes);
EN_openH(ph);
EN_initH(ph, EN_NOSAVE);
do {
EN_runH(ph, &t);
for (i = 1; i <= NumNodes; i++) {
EN_getnodevalue(ph, i, EN_PRESSURE, &p);
EN_getnodeid(ph, i, id);
writetofile(t, id, p);
}
EN_nextH(&tStep);
} while (tStep > 0);
EN_closeH(ph);
}
\endcode
@section report 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 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 @ref EN_setreport function is used to define the format of a report while the @ref 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:
The @ref EN_setreport function is used to define the format of a report while the @ref 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:
\code {.c}
void reportPressureVariation(EN_Project ph)
{
// Compute ranges (max - min)
EN_settimeparam(ph, EN_STATISTIC, EN_RANGE);
EN_settimeparam(ph, EN_STATISTIC, EN_RANGE);
// Solve and save hydraulics
EN_solveH(ph);
EN_saveH(ph);
EN_solveH(ph);
EN_saveH(ph);
// Define contents of the report
EN_resetreport(ph);
EN_setreport(ph, "FILE myfile.rpt");
EN_setreport(ph, "NODES ALL");
EN_setreport(ph, "PRESSURE PRECISION 1");
EN_setreport(ph, "PRESSURE ABOVE 20");
EN_resetreport(ph);
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_report(ph);
}
\endcode
*/