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

documenting some functions

Browse Source
This commit is contained in:
Sam Hatchett
2015-09-29 17:21:23 -04:00
parent 09cc193e73
commit ebbe8e84e7
2 changed files with 160 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
include/epanet2.h
View File

@@ -1,5 +1,5 @@
/** @file epanet2.h /** @file epanet2.h
@see http://github.com/openwateranalytics/epanet @see http://github.com/openwateranalytics/epanet
*/ */
@@ -201,29 +201,34 @@
/** /**
@defgroup HydraulicFunctions Hydraulic Analysis @defgroup HydraulicFunctions Hydraulic Analysis
~~~~~~~~~~~~~~~{.c} ~~~~~~~~~~~~~~~{.c}
int errcode; int errcode;
long t, tstep; long t, tstep;
errcode = ENopenH(); errcode = ENopenH();
if (!errcode) if (!errcode)
{ {
errcode = ENinitH(EN_SAVE); errcode = ENinitH(EN_SAVE);
if (!errcode) do if (!errcode) do
{ {
tstep = 0; tstep = 0;
ERRCODE(ENrunH(&t)); ERRCODE(ENrunH(&t));
ERRCODE(ENnextH(&tstep)); ERRCODE(ENnextH(&tstep));
} }
while (tstep > 0); while (tstep > 0);
} }
ENcloseH(); ENcloseH();
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
*/ */
/**
@defgroup QualityFunctions Water Quality Functions
*/
// --- Declare the EPANET toolkit functions // --- Declare the EPANET toolkit functions
#if defined(__cplusplus) #if defined(__cplusplus)
extern "C" { extern "C" {
@@ -304,39 +309,168 @@ extern "C" {
@param[out] currentTime The current simulation time in seconds @param[out] currentTime The current simulation time in seconds
@return Error or warning code @return Error or warning code
@ingroup HydraulicFunctions @ingroup HydraulicFunctions
@see ENsolveH
This function is used in a loop with ENnextH() to run This function is used in a loop with ENnextH() to run
an extended period hydraulic simulation. an extended period hydraulic simulation.
See ENsolveH() for an example. See ENsolveH() for an example.
@see ENsolveH
*/ */
int DLLEXPORT ENrunH(long *currentTime); int DLLEXPORT ENrunH(long *currentTime);
/** /**
@brief Determine time (in seconds) until next hydraulic event @brief Determine time (in seconds) until next hydraulic event
@param[out] tstep Time (seconds) until next hydraulic event. 0 marks end of simulation period.
@return Error code
@ingroup HydraulicFunctions @ingroup HydraulicFunctions
This function is used in a loop with ENrunH() to run an extended period hydraulic simulation.
See ENsolveH() for an example.
*/ */
int DLLEXPORT ENnextH(long *tStep); int DLLEXPORT ENnextH(long *tStep);
/**
@brief Frees data allocated by hydraulics solver
@return Error code
@ingroup HydraulicFunctions
*/
int DLLEXPORT ENcloseH(); int DLLEXPORT ENcloseH();
/**
@brief Copies binary hydraulics file to disk
@param filename Name of file to be created
@return Error code
@ingroup HydraulicFunctions
*/
int DLLEXPORT ENsavehydfile(char *filename); int DLLEXPORT ENsavehydfile(char *filename);
/**
@brief Opens previously saved binary hydraulics file
@param filename Name of file to be used
@return Error code
@ingroup HydraulicFunctions
*/
int DLLEXPORT ENusehydfile(char *filename); int DLLEXPORT ENusehydfile(char *filename);
/**
@brief Solves for network water quality in all time periods
@return Error code
@ingroup QualityFunctions
*/
int DLLEXPORT ENsolveQ(); int DLLEXPORT ENsolveQ();
/**
@brief Sets up data structures for WQ analysis
@return Error code
@ingroup QualityFunctions
*/
int DLLEXPORT ENopenQ(); int DLLEXPORT ENopenQ();
/**
@brief Initializes water quality analysis
@param saveFlag EN_SAVE (1) if results saved to file, EN_NOSAVE (0) if not
@return Error code
@ingroup QualityFunctions
*/
int DLLEXPORT ENinitQ(int saveFlag); int DLLEXPORT ENinitQ(int saveFlag);
/**
@brief Retrieves hydraulic & WQ results at time t.
@param[out] t Current simulation time, in seconds.
@return Error code
@ingroup QualityFunctions
This function is used in a loop with ENnextQ() to run
an extended period WQ simulation. See ENsolveQ() for
an example.
*/
int DLLEXPORT ENrunQ(long *currentTime); int DLLEXPORT ENrunQ(long *currentTime);
/**
@brief Advances WQ simulation to next hydraulic event.
@param[out] tStep Time in seconds until next hydraulic event. 0 marks end of simulation period.
@return Error code
@ingroup QualityFunctions
This function is used in a loop with ENrunQ() to run
an extended period WQ simulation. See ENsolveQ() for
an example.
*/
int DLLEXPORT ENnextQ(long *tStep); int DLLEXPORT ENnextQ(long *tStep);
/**
@brief Advances WQ simulation by a single WQ time step
@param[out] timeLeft Time left in overall simulation (in seconds)
@return Error code
@ingroup QualityFunctions
This function is used in a loop with ENrunQ() to run
an extended period WQ simulation.
*/
int DLLEXPORT ENstepQ(long *timeLeft); int DLLEXPORT ENstepQ(long *timeLeft);
/**
@brief Frees data allocated by water quality solver.
@return Error code.
@ingroup QualityFunctions
*/
int DLLEXPORT ENcloseQ(); int DLLEXPORT ENcloseQ();
/**
@brief Writes line of text to the report file.
@param line Text string to write
@return Error code.
@ingroup FileManagement
*/
int DLLEXPORT ENwriteline(char *line); int DLLEXPORT ENwriteline(char *line);
/**
@brief Writes simulation report to the report file
@return Error code
@ingroup FileManagement
*/
int DLLEXPORT ENreport(); int DLLEXPORT ENreport();
/**
@brief Resets report options to default values
@return Error code
@ingroup FileManagement
*/
int DLLEXPORT ENresetreport(); int DLLEXPORT ENresetreport();
/**
@brief Processes a reporting format command
@return Error code
@ingroup FileManagement
*/
int DLLEXPORT ENsetreport(char *reportFormat); int DLLEXPORT ENsetreport(char *reportFormat);
/**
@brief Retrieves parameters that define a simple control
@param cindex Control index (position of control statement in the input file, starting from 1)
@param[out] ctype Control type code (see EPANET2.H)
@param[out] lindex Index of controlled link
@param[out] setting Control setting on link
@param[out] nindex Index of controlling node (0 for TIMER or TIMEOFDAY control)
@param[out] level Control level (tank level, junction pressure, or time (seconds))
@return Error code
*/
int DLLEXPORT ENgetcontrol(int controlIndex, int *controlType, int *linkIdx, EN_API_FLOAT_TYPE *setting, int *nodeIdx, EN_API_FLOAT_TYPE *level); int DLLEXPORT ENgetcontrol(int controlIndex, int *controlType, int *linkIdx, EN_API_FLOAT_TYPE *setting, int *nodeIdx, EN_API_FLOAT_TYPE *level);
/**
@brief Retrieves the number of components of a given type in the network.
@param code Component code (see EPANET2.H)
@param[out] count Number of components in network
@return Error code
*/
int DLLEXPORT ENgetcount(int code, int *count); int DLLEXPORT ENgetcount(int code, int *count);
/**
@brief Gets value for an analysis option
@param Code option code (see EPANET2.H)
@param[out] value Option value
@return Error code
*/
int DLLEXPORT ENgetoption(int code, EN_API_FLOAT_TYPE *value); int DLLEXPORT ENgetoption(int code, EN_API_FLOAT_TYPE *value);
int DLLEXPORT ENgettimeparam(int code, long *value); int DLLEXPORT ENgettimeparam(int code, long *value);
int DLLEXPORT ENgetflowunits(int *code); int DLLEXPORT ENgetflowunits(int *code);
@@ -374,7 +508,7 @@ extern "C" {
@param linkIndex The index of the pump element @param linkIndex The index of the pump element
@param outType The integer-typed pump type signifier (output parameter) @param outType The integer-typed pump type signifier (output parameter)
@return Error code @return Error code
*/ */
int DLLEXPORT ENgetpumptype(int linkIndex, int *outType); int DLLEXPORT ENgetpumptype(int linkIndex, int *outType);
int DLLEXPORT ENgetversion(int *version); int DLLEXPORT ENgetversion(int *version);

165
src/epanet.c
View File

@@ -473,17 +473,6 @@ int DLLEXPORT ENinitH(int flag)
int DLLEXPORT ENrunH(long *t) int DLLEXPORT ENrunH(long *t)
/*----------------------------------------------------------------
** Input: none (no need to supply a value for *t)
** Output: *t = current simulation time (seconds)
** Returns: error/warning code
** Purpose: solves hydraulics for conditions at time t.
**
** This function is used in a loop with ENnextH() to run
** an extended period hydraulic simulation.
** See ENsolveH() for an example.
**----------------------------------------------------------------
*/
{ {
int errcode; int errcode;
*t = 0; *t = 0;
@@ -495,18 +484,6 @@ int DLLEXPORT ENrunH(long *t)
int DLLEXPORT ENnextH(long *tstep) int DLLEXPORT ENnextH(long *tstep)
/*----------------------------------------------------------------
** Input: none (no need to supply a value for *tstep)
** Output: *tstep = time (seconds) until next hydraulic event
** (0 marks end of simulation period)
** Returns: error code
** Purpose: determines time until next hydraulic event.
**
** This function is used in a loop with ENrunH() to run
** an extended period hydraulic simulation.
** See ENsolveH() for an example.
**----------------------------------------------------------------
*/
{ {
int errcode; int errcode;
*tstep = 0; *tstep = 0;
@@ -519,13 +496,7 @@ int DLLEXPORT ENnextH(long *tstep)
int DLLEXPORT ENcloseH() int DLLEXPORT ENcloseH()
/*----------------------------------------------------------------
** Input: none
** Output: none
** Returns: error code
** Purpose: frees data allocated by hydraulics solver
**----------------------------------------------------------------
*/
{ {
if (!Openflag) return(102); if (!Openflag) return(102);
closehyd(); closehyd();
@@ -535,13 +506,6 @@ int DLLEXPORT ENcloseH()
int DLLEXPORT ENsavehydfile(char *filename) int DLLEXPORT ENsavehydfile(char *filename)
/*----------------------------------------------------------------
** Input: filename = name of file
** Output: none
** Returns: error code
** Purpose: copies binary hydraulics file to disk
**----------------------------------------------------------------
*/
{ {
FILE *f; FILE *f;
int c; int c;
@@ -561,13 +525,6 @@ int DLLEXPORT ENsavehydfile(char *filename)
int DLLEXPORT ENusehydfile(char *filename) int DLLEXPORT ENusehydfile(char *filename)
/*----------------------------------------------------------------
** Input: filename = name of file
** Output: none
** Returns: error code
** Purpose: opens previously saved binary hydraulics file
**----------------------------------------------------------------
*/
{ {
int errcode; int errcode;
@@ -600,13 +557,6 @@ int DLLEXPORT ENusehydfile(char *filename)
int DLLEXPORT ENsolveQ() int DLLEXPORT ENsolveQ()
/*----------------------------------------------------------------
** Input: none
** Output: none
** Returns: error code
** Purpose: solves for network water quality in all time periods
**----------------------------------------------------------------
*/
{ {
int errcode; int errcode;
long t, tstep; long t, tstep;
@@ -662,13 +612,6 @@ int DLLEXPORT ENsolveQ()
int DLLEXPORT ENopenQ() int DLLEXPORT ENopenQ()
/*----------------------------------------------------------------
** Input: none
** Output: none
** Returns: error code
** Purpose: sets up data structures for WQ analysis
**----------------------------------------------------------------
*/
{ {
int errcode = 0; int errcode = 0;
@@ -688,14 +631,6 @@ int DLLEXPORT ENopenQ()
int DLLEXPORT ENinitQ(int saveflag) int DLLEXPORT ENinitQ(int saveflag)
/*----------------------------------------------------------------
** Input: saveflag = EN_SAVE (1) if results saved to file,
** EN_NOSAVE (0) if not
** Output: none
** Returns: error code
** Purpose: initializes WQ analysis
**----------------------------------------------------------------
*/
{ {
int errcode = 0; int errcode = 0;
if (!OpenQflag) return(105); if (!OpenQflag) return(105);
@@ -712,17 +647,6 @@ int DLLEXPORT ENinitQ(int saveflag)
int DLLEXPORT ENrunQ(long *t) int DLLEXPORT ENrunQ(long *t)
/*----------------------------------------------------------------
** Input: none (no need to supply a value for *t)
** Output: *t = current simulation time (seconds)
** Returns: error code
** Purpose: retrieves hydraulic & WQ results at time t.
**
** This function is used in a loop with ENnextQ() to run
** an extended period WQ simulation. See ENsolveQ() for
** an example.
**----------------------------------------------------------------
*/
{ {
int errcode; int errcode;
*t = 0; *t = 0;
@@ -734,18 +658,6 @@ int DLLEXPORT ENrunQ(long *t)
int DLLEXPORT ENnextQ(long *tstep) int DLLEXPORT ENnextQ(long *tstep)
/*----------------------------------------------------------------
** Input: none (no need to supply a value for *tstep)
** Output: *tstep = time (seconds) until next hydraulic event
** (0 marks end of simulation period)
** Returns: error code
** Purpose: advances WQ simulation to next hydraulic event.
**
** This function is used in a loop with ENrunQ() to run
** an extended period WQ simulation. See ENsolveQ() for
** an example.
**----------------------------------------------------------------
*/
{ {
int errcode; int errcode;
*tstep = 0; *tstep = 0;
@@ -758,16 +670,6 @@ int DLLEXPORT ENnextQ(long *tstep)
int DLLEXPORT ENstepQ(long *tleft) int DLLEXPORT ENstepQ(long *tleft)
/*----------------------------------------------------------------
** Input: none
** Output: *tleft = time left in overall simulation (seconds)
** Returns: error code
** Purpose: advances WQ simulation by a single WQ time step
**
** This function is used in a loop with ENrunQ() to run
** an extended period WQ simulation.
**----------------------------------------------------------------
*/
{ {
int errcode; int errcode;
*tleft = 0; *tleft = 0;
@@ -780,13 +682,7 @@ int DLLEXPORT ENstepQ(long *tleft)
int DLLEXPORT ENcloseQ() int DLLEXPORT ENcloseQ()
/*----------------------------------------------------------------
** Input: none
** Output: none
** Returns: error code
** Purpose: frees data allocated by WQ solver
**----------------------------------------------------------------
*/
{ {
if (!Openflag) return(102); if (!Openflag) return(102);
closequal(); closequal();
@@ -803,13 +699,6 @@ int DLLEXPORT ENcloseQ()
int DLLEXPORT ENwriteline(char *line) int DLLEXPORT ENwriteline(char *line)
/*----------------------------------------------------------------
** Input: line = text string
** Output: none
** Returns: error code
** Purpose: writes line of text to report file
**----------------------------------------------------------------
*/
{ {
if (!Openflag) return(102); if (!Openflag) return(102);
writeline(line); writeline(line);
@@ -818,13 +707,6 @@ int DLLEXPORT ENwriteline(char *line)
int DLLEXPORT ENreport() int DLLEXPORT ENreport()
/*----------------------------------------------------------------
** Input: none
** Output: none
** Returns: error code
** Purpose: writes report to report file
**----------------------------------------------------------------
*/
{ {
int errcode; int errcode;
@@ -837,13 +719,6 @@ int DLLEXPORT ENreport()
int DLLEXPORT ENresetreport() int DLLEXPORT ENresetreport()
/*----------------------------------------------------------------
** Input: none
** Output: none
** Returns: error code
** Purpose: resets report options to default values
**----------------------------------------------------------------
*/
{ {
int i; int i;
if (!Openflag) return(102); if (!Openflag) return(102);
@@ -855,13 +730,6 @@ int DLLEXPORT ENresetreport()
int DLLEXPORT ENsetreport(char *s) int DLLEXPORT ENsetreport(char *s)
/*----------------------------------------------------------------
** Input: s = report format command
** Output: none
** Returns: error code
** Purpose: processes a reporting format command
**----------------------------------------------------------------
*/
{ {
char s1[MAXLINE+1]; char s1[MAXLINE+1];
if (!Openflag) return(102); if (!Openflag) return(102);
@@ -897,20 +765,6 @@ int DLLEXPORT ENgetversion(int *v)
int DLLEXPORT ENgetcontrol(int cindex, int *ctype, int *lindex, EN_API_FLOAT_TYPE *setting, int *nindex, EN_API_FLOAT_TYPE *level) int DLLEXPORT ENgetcontrol(int cindex, int *ctype, int *lindex, EN_API_FLOAT_TYPE *setting, int *nindex, EN_API_FLOAT_TYPE *level)
/*----------------------------------------------------------------
** Input: cindex = control index (position of control statement
** in the input file, starting from 1)
** Output: *ctype = control type code (see EPANET2.H)
** *lindex = index of controlled link
** *setting = control setting on link
** *nindex = index of controlling node (0 for TIMER
** or TIMEOFDAY control)
** *level = control level (tank level, junction
** pressure, or time (seconds))
** Returns: error code
** Purpose: retrieves parameters that define a simple control
**----------------------------------------------------------------
*/
{ {
double s, lvl; double s, lvl;
@@ -950,14 +804,6 @@ int DLLEXPORT ENgetcontrol(int cindex, int *ctype, int *lindex, EN_API_FLOAT_TYP
int DLLEXPORT ENgetcount(int code, int *count) int DLLEXPORT ENgetcount(int code, int *count)
/*----------------------------------------------------------------
** Input: code = component code (see EPANET2.H)
** Output: *count = number of components in network
** Returns: error code
** Purpose: retrieves the number of components of a
** given type in the network
**----------------------------------------------------------------
*/
{ {
*count = 0; *count = 0;
if (!Openflag) return(102); if (!Openflag) return(102);
@@ -976,13 +822,6 @@ int DLLEXPORT ENgetcount(int code, int *count)
int DLLEXPORT ENgetoption(int code, EN_API_FLOAT_TYPE *value) int DLLEXPORT ENgetoption(int code, EN_API_FLOAT_TYPE *value)
/*----------------------------------------------------------------
** Input: code = option code (see EPANET2.H)
** Output: *value = option value
** Returns: error code
** Purpose: gets value for an analysis option
**----------------------------------------------------------------
*/
{ {
double v = 0.0; double v = 0.0;
*value = 0.0; *value = 0.0;