From ebbe8e84e75b5aaca572f71f0a647174bf62d769 Mon Sep 17 00:00:00 2001 From: Sam Hatchett Date: Tue, 29 Sep 2015 17:21:23 -0400 Subject: [PATCH] documenting some functions --- include/epanet2.h | 182 ++++++++++++++++++++++++++++++++++++++++------ src/epanet.c | 165 +---------------------------------------- 2 files changed, 160 insertions(+), 187 deletions(-) diff --git a/include/epanet2.h b/include/epanet2.h index 349e2bf..3d9197e 100755 --- a/include/epanet2.h +++ b/include/epanet2.h @@ -1,5 +1,5 @@ /** @file epanet2.h - @see http://github.com/openwateranalytics/epanet + @see http://github.com/openwateranalytics/epanet */ @@ -201,29 +201,34 @@ /** @defgroup HydraulicFunctions Hydraulic Analysis -~~~~~~~~~~~~~~~{.c} -int errcode; -long t, tstep; + ~~~~~~~~~~~~~~~{.c} + int errcode; + long t, tstep; + + errcode = ENopenH(); + if (!errcode) + { + errcode = ENinitH(EN_SAVE); + if (!errcode) do + { + tstep = 0; + ERRCODE(ENrunH(&t)); + ERRCODE(ENnextH(&tstep)); + } + while (tstep > 0); + } + + ENcloseH(); + ~~~~~~~~~~~~~~~ -errcode = ENopenH(); -if (!errcode) -{ - errcode = ENinitH(EN_SAVE); - if (!errcode) do - { - tstep = 0; - ERRCODE(ENrunH(&t)); - ERRCODE(ENnextH(&tstep)); - } - while (tstep > 0); -} - -ENcloseH(); -~~~~~~~~~~~~~~~ - */ +/** + @defgroup QualityFunctions Water Quality Functions + + */ + // --- Declare the EPANET toolkit functions #if defined(__cplusplus) extern "C" { @@ -304,39 +309,168 @@ extern "C" { @param[out] currentTime The current simulation time in seconds @return Error or warning code @ingroup HydraulicFunctions + @see ENsolveH This function is used in a loop with ENnextH() to run an extended period hydraulic simulation. See ENsolveH() for an example. - - @see ENsolveH */ int DLLEXPORT ENrunH(long *currentTime); /** @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 + + 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); + + + /** + @brief Frees data allocated by hydraulics solver + @return Error code + @ingroup HydraulicFunctions + */ 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); + + /** + @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); + /** + @brief Solves for network water quality in all time periods + @return Error code + @ingroup QualityFunctions + */ int DLLEXPORT ENsolveQ(); + + /** + @brief Sets up data structures for WQ analysis + @return Error code + @ingroup QualityFunctions + */ 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); + + /** + @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); + + /** + @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); + + /** + @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); + + /** + @brief Frees data allocated by water quality solver. + @return Error code. + @ingroup QualityFunctions + */ 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); + + /** + @brief Writes simulation report to the report file + @return Error code + @ingroup FileManagement + */ int DLLEXPORT ENreport(); + + /** + @brief Resets report options to default values + @return Error code + @ingroup FileManagement + */ int DLLEXPORT ENresetreport(); + + /** + @brief Processes a reporting format command + @return Error code + @ingroup FileManagement + */ 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); + + /** + @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); + + /** + @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 ENgettimeparam(int code, long *value); int DLLEXPORT ENgetflowunits(int *code); @@ -374,7 +508,7 @@ extern "C" { @param linkIndex The index of the pump element @param outType The integer-typed pump type signifier (output parameter) @return Error code - */ + */ int DLLEXPORT ENgetpumptype(int linkIndex, int *outType); int DLLEXPORT ENgetversion(int *version); @@ -391,7 +525,7 @@ extern "C" { int DLLEXPORT ENsetqualtype(int qualcode, char *chemname, char *chemunits, char *tracenode); int DLLEXPORT ENgetqualinfo(int *qualcode, char *chemname, char *chemunits, int *tracenode); int DLLEXPORT ENsetbasedemand(int nodeIndex, int demandIdx, EN_API_FLOAT_TYPE baseDemand); - + int DLLEXPORT ENgetcurveindex(char *id, int *index); int DLLEXPORT ENgetcurveid(int index, char *id); int DLLEXPORT ENgetcurvelen(int index, int *len); diff --git a/src/epanet.c b/src/epanet.c index c350434..cbabb0d 100755 --- a/src/epanet.c +++ b/src/epanet.c @@ -473,17 +473,6 @@ int DLLEXPORT ENinitH(int flag) 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; *t = 0; @@ -495,18 +484,6 @@ int DLLEXPORT ENrunH(long *t) 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; *tstep = 0; @@ -519,13 +496,7 @@ int DLLEXPORT ENnextH(long *tstep) int DLLEXPORT ENcloseH() -/*---------------------------------------------------------------- -** Input: none -** Output: none -** Returns: error code -** Purpose: frees data allocated by hydraulics solver -**---------------------------------------------------------------- -*/ + { if (!Openflag) return(102); closehyd(); @@ -535,13 +506,6 @@ int DLLEXPORT ENcloseH() int DLLEXPORT ENsavehydfile(char *filename) -/*---------------------------------------------------------------- -** Input: filename = name of file -** Output: none -** Returns: error code -** Purpose: copies binary hydraulics file to disk -**---------------------------------------------------------------- -*/ { FILE *f; int c; @@ -561,13 +525,6 @@ int DLLEXPORT ENsavehydfile(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; @@ -600,13 +557,6 @@ int DLLEXPORT ENusehydfile(char *filename) int DLLEXPORT ENsolveQ() -/*---------------------------------------------------------------- -** Input: none -** Output: none -** Returns: error code -** Purpose: solves for network water quality in all time periods -**---------------------------------------------------------------- -*/ { int errcode; long t, tstep; @@ -662,13 +612,6 @@ int DLLEXPORT ENsolveQ() int DLLEXPORT ENopenQ() -/*---------------------------------------------------------------- -** Input: none -** Output: none -** Returns: error code -** Purpose: sets up data structures for WQ analysis -**---------------------------------------------------------------- -*/ { int errcode = 0; @@ -688,14 +631,6 @@ int DLLEXPORT ENopenQ() 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; if (!OpenQflag) return(105); @@ -712,17 +647,6 @@ int DLLEXPORT ENinitQ(int saveflag) 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; *t = 0; @@ -734,18 +658,6 @@ int DLLEXPORT ENrunQ(long *t) 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; *tstep = 0; @@ -758,16 +670,6 @@ int DLLEXPORT ENnextQ(long *tstep) 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; *tleft = 0; @@ -780,13 +682,7 @@ int DLLEXPORT ENstepQ(long *tleft) int DLLEXPORT ENcloseQ() -/*---------------------------------------------------------------- -** Input: none -** Output: none -** Returns: error code -** Purpose: frees data allocated by WQ solver -**---------------------------------------------------------------- -*/ + { if (!Openflag) return(102); closequal(); @@ -803,13 +699,6 @@ int DLLEXPORT ENcloseQ() 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); writeline(line); @@ -818,13 +707,6 @@ int DLLEXPORT ENwriteline(char *line) int DLLEXPORT ENreport() -/*---------------------------------------------------------------- -** Input: none -** Output: none -** Returns: error code -** Purpose: writes report to report file -**---------------------------------------------------------------- -*/ { int errcode; @@ -837,13 +719,6 @@ int DLLEXPORT ENreport() int DLLEXPORT ENresetreport() -/*---------------------------------------------------------------- -** Input: none -** Output: none -** Returns: error code -** Purpose: resets report options to default values -**---------------------------------------------------------------- -*/ { int i; if (!Openflag) return(102); @@ -855,13 +730,6 @@ int DLLEXPORT ENresetreport() 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]; 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) -/*---------------------------------------------------------------- -** 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; @@ -950,14 +804,6 @@ int DLLEXPORT ENgetcontrol(int cindex, int *ctype, int *lindex, EN_API_FLOAT_TYP 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; 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) -/*---------------------------------------------------------------- -** 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; *value = 0.0;