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

Numerous updates to project documentation

Browse Source
This commit is contained in:
Lew Rossman
2019-05-30 13:28:32 -04:00
parent 6a5aa372f8
commit 2bbbf736b0
15 changed files with 8685 additions and 270 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7265
doc/DistributionSystem.eps Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
doc/DistributionSystem.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 126 KiB

4
doc/DoxygenLayout.xml
View File

@@ -4,8 +4,8 @@
<navindex> <navindex>
<tab type="mainpage" visible="yes" title=""/> <tab type="mainpage" visible="yes" title=""/>
<tab type="pages" visible="yes" title="" intro=""/> <tab type="pages" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="Reference" <tab type="modules" visible="yes" title="API Reference"
intro="These topics describe the Toolkit's functions, symbolic constants, and other details related to its usage."/> intro="These topics describe the Toolkit's functions, enumerations, and error/warning codes."/>
<tab type="namespaces" visible="yes" title=""> <tab type="namespaces" visible="yes" title="">
<tab type="namespacelist" visible="yes" title="" intro=""/> <tab type="namespacelist" visible="yes" title="" intro=""/>
<tab type="namespacemembers" visible="yes" title="" intro=""/> <tab type="namespacemembers" visible="yes" title="" intro=""/>

14
doc/doxyfile
View File

@@ -535,7 +535,7 @@ HIDE_COMPOUND_REFERENCE= NO
# the files that are included by a file in the documentation of that file. # the files that are included by a file in the documentation of that file.
# The default value is: YES. # The default value is: YES.
SHOW_INCLUDE_FILES = YES SHOW_INCLUDE_FILES = NO
# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
# grouped member an include statement to the documentation, telling the reader # grouped member an include statement to the documentation, telling the reader
@@ -778,10 +778,12 @@ WARN_LOGFILE =
INPUT = main.dox \ INPUT = main.dox \
toolkit-usage.dox \ toolkit-usage.dox \
toolkit-examples.dox \ toolkit-examples.dox \
toolkit-files.dox \
input-file.dox \
toolkit-units.dox \
modules.dox \ modules.dox \
../include/epanet2_2.h \
../include/epanet2_enums.h \ ../include/epanet2_enums.h \
output-format.dox ../include/epanet2_2.h
# This tag can be used to specify the character encoding of the source files # This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1647,7 +1649,7 @@ EXTRA_SEARCH_MAPPINGS =
# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
# The default value is: YES. # The default value is: YES.
GENERATE_LATEX = yes GENERATE_LATEX = NO
# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1690,7 +1692,7 @@ COMPACT_LATEX = NO
# The default value is: a4. # The default value is: a4.
# This tag requires that the tag GENERATE_LATEX is set to YES. # This tag requires that the tag GENERATE_LATEX is set to YES.
PAPER_TYPE = a4 PAPER_TYPE = letter
# The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
# that should be included in the LaTeX output. The package can be specified just # that should be included in the LaTeX output. The package can be specified just
@@ -1774,7 +1776,7 @@ USE_PDFLATEX = YES
# The default value is: NO. # The default value is: NO.
# This tag requires that the tag GENERATE_LATEX is set to YES. # This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_BATCHMODE = NO LATEX_BATCHMODE = YES
# If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the # If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the
# index chapters (such as File Index, Compound Index, etc.) in the output. # index chapters (such as File Index, Compound Index, etc.) in the output.

1039
doc/input-file.dox Normal file
View File

File diff suppressed because it is too large Load Diff

25
doc/main.dox
View File

@@ -1,8 +1,13 @@
/** /**
@mainpage Overview @mainpage Overview
EPANET is a program that performs extended period simulation of hydraulic and water quality behavior within pressurized pipe networks. A network can consist of pipes, nodes (pipe junctions), pumps, valves and storage tanks or reservoirs. EPANET tracks the flow of water in each pipe, the pressure at each node, the height of water in each tank, and the concentration of a chemical species throughout the network during a multi-time period simulation. In addition to chemical species, water age and source tracing can also be simulated. The EPANET Programmer's Toolkit is a library of functions (or API) that allow programmers to customize the use of EPANET's hydraulic and water quality solution engine to their own applications. Both EPANET and its toolkit were originally developed and are currently maintained by the U.S. Environmental Protection Agency (USEPA). EPANET is a program that performs extended period simulation of hydraulic and water quality behavior within water distribution system pipe networks. A network can consist of pipes, nodes (pipe junctions), pumps, valves and storage tanks or reservoirs. EPANET tracks the flow of water in each pipe, the pressure at each node, the height of water in each tank, and the concentration of a chemical species throughout the network during a multi-time period simulation. In addition to chemical species, water age and source tracing can also be simulated. The EPANET Programmer's Toolkit is a library of functions (or API) that allow programmers to customize the use of EPANET's hydraulic and water quality solution engine to their own applications. Both EPANET and its toolkit were originally developed and are currently maintained by the U.S. Environmental Protection Agency (USEPA).
<table style = "border: 0px solid black">
<tr><td style="vertical-align: top">
@image html DistributionSystem.png
@image latex DistributionSystem.eps
</td><td style="vertical-align: top">
The OWA-EPANET Toolkit is an open-source version of the original EPANET Toolkit that extends its capabilities by: The OWA-EPANET Toolkit is an open-source version of the original EPANET Toolkit that extends its capabilities by:
- providing a full set of functions to set and retrieve values for all parameters contained in a network model - providing a full set of functions to set and retrieve values for all parameters contained in a network model
- allowing networks to be built completely from function calls instead of from an input file - allowing networks to be built completely from function calls instead of from an input file
@@ -10,6 +15,8 @@ The OWA-EPANET Toolkit is an open-source version of the original EPANET Toolkit
- adding the ability to use pressure dependent demands in hydraulic analyses - adding the ability to use pressure dependent demands in hydraulic analyses
- producing more robust results with regard to hydraulic convergence, low/zero flow conditions, and water quality mass balance - producing more robust results with regard to hydraulic convergence, low/zero flow conditions, and water quality mass balance
- achieving faster run times for single period hydraulic analyses. - achieving faster run times for single period hydraulic analyses.
</td></tr>
</table>
Before using the OWA-EPANET Toolkit one should be familiar with the way that EPANET represents a pipe network, the design and operating information it requires, and the steps it uses to simulate a network's behavior. The following topics provide some introductory material on these subjects: Before using the OWA-EPANET Toolkit one should be familiar with the way that EPANET represents a pipe network, the design and operating information it requires, and the steps it uses to simulate a network's behavior. The following topics provide some introductory material on these subjects:
- @subpage DataModel "Network Data Model" - @subpage DataModel "Network Data Model"
@@ -18,15 +25,20 @@ Before using the OWA-EPANET Toolkit one should be familiar with the way that EPA
More detailed information can be obtained from reading the <a href="https://nepis.epa.gov/Adobe/PDF/P1007WWU.pdf">EPANET 2 Users Manual</a>. More detailed information can be obtained from reading the <a href="https://nepis.epa.gov/Adobe/PDF/P1007WWU.pdf">EPANET 2 Users Manual</a>.
__Note:__ OWA (Open Water Analytics) exists on GitHub as an open community for the exchange of information and ideas related to computing in the water & wastewater industries. It's activities and code projects are neither affiliated with nor endorsed by the USEPA. __Note:__ <a href="https://github.com/OpenWaterAnalytics">OWA (Open Water Analytics)</a> exists on GitHub as an open community for the exchange of information and ideas related to computing in the water & wastewater industries. It's activities and code projects are neither affiliated with nor endorsed by the USEPA.
*/ */
/** /**
@page DataModel Network Data Model @page DataModel Network Data Model
EPANET models a pipe network as a collection of links connected to nodes. The links represent pipes, pumps, and control valves. The nodes represent junctions, tanks, and reservoirs. The figure below illustrates how these objects can be connected to one another to form a network. EPANET models a pipe network as a collection of links connected to nodes. The links represent pipes, pumps, and control valves. The nodes represent junctions, tanks, and reservoirs. The figure below illustrates how these objects can be connected to one another to form a network.
<table style = "border: 0px solid black">
<tr><td>
@image html Network.png @image html Network.png
@image latex Network.eps @image latex Network.eps
</td></tr>
</table>
Junctions have a user-supplied water withdrawal rate (i.e., consumer demand) associated with them. Tanks are storage units whose water level changes over time. Reservoirs are boundary points where a fixed hydraulic head applies. Junctions have a user-supplied water withdrawal rate (i.e., consumer demand) associated with them. Tanks are storage units whose water level changes over time. Reservoirs are boundary points where a fixed hydraulic head applies.
@@ -60,8 +72,13 @@ for more information on EPANET's data model.
@page DataFlow Data Flow Diagram @page DataFlow Data Flow Diagram
The EPANET Toolkit contains separate code modules for network building, hydraulic analysis, water quality analysis, and report generation. The data flow diagram for analyzing a pipe network is shown below. The processing steps depicted in this diagram can be summarized as follows: The EPANET Toolkit contains separate code modules for network building, hydraulic analysis, water quality analysis, and report generation. The data flow diagram for analyzing a pipe network is shown below. The processing steps depicted in this diagram can be summarized as follows:
<table style = "border: 0px solid black">
<tr><td>
@image html DataFlow.png @image html DataFlow.png
@image latex DataFlow.eps @image latex DataFlow.eps
</td></tr>
</table>
- The network builder receives a description of the network being simulated either from an external input file (.inp) or from a series of function calls that create network objects and assign their properties via code. These data are stored in a Project data structure. - The network builder receives a description of the network being simulated either from an external input file (.inp) or from a series of function calls that create network objects and assign their properties via code. These data are stored in a Project data structure.
@@ -84,8 +101,8 @@ with single threaded applications.
analyzed concurrently. analyzed concurrently.
Both toolkit versions utilize identical function names and argument lists with the following exceptions: Both toolkit versions utilize identical function names and argument lists with the following exceptions:
- Function names in the single-threaded library begin with `EN` while those in the multi-threaded - Function names in the single-threaded library begin with \b EN while those in the multi-threaded
library begin with `EN_`. library begin with \b EN_.
- The multi-threaded functions contain an additional argument that references a particular network project - The multi-threaded functions contain an additional argument that references a particular network project
that the function is applied to. that the function is applied to.
- The multi-threaded library contains two additional functions that allow users to create and delete - The multi-threaded library contains two additional functions that allow users to create and delete

92
doc/modules.dox
View File

@@ -59,8 +59,8 @@ These functions are used for working with rule-based controls.
*/ */
/** /**
@defgroup Constants Symbolic Constants @defgroup Enumerations Enumerated Types
These are symbolic constants used as function arguments. These are the toolkit's enumerated types whose members are used as function arguments.
*/ */
/** /**
@@ -83,13 +83,13 @@ These are symbolic constants used as function arguments.
@addtogroup Hydraulics @addtogroup Hydraulics
@{ @{
@fn int EN_solveH(EN_Project ph) @fn int EN_solveH(EN_Project ph)
@fn int EN_usehydfile(EN_Project ph, char *filename) @fn int EN_usehydfile(EN_Project ph, const char *filename)
@fn int EN_openH(EN_Project ph) @fn int EN_openH(EN_Project ph)
@fn int EN_initH(EN_Project ph, int initFlag) @fn int EN_initH(EN_Project ph, int initFlag)
@fn int EN_runH(EN_Project ph, long *currentTime) @fn int EN_runH(EN_Project ph, long *currentTime)
@fn int EN_nextH(EN_Project ph, long *tStep) @fn int EN_nextH(EN_Project ph, long *tStep)
@fn int EN_saveH(EN_Project ph) @fn int EN_saveH(EN_Project ph)
@fn int EN_savehydfile(EN_Project ph, char *filename) @fn int EN_savehydfile(EN_Project ph, const char *filename)
@fn int EN_closeH(EN_Project ph) @fn int EN_closeH(EN_Project ph)
@} @}
*/ */
@@ -262,13 +262,15 @@ These are symbolic constants used as function arguments.
*/ */
/** /**
@addtogroup Constants @addtogroup Enumerations
@{ @{
@file epanet2_enums.h \enum EN_SizeLimits
\enum EN_ObjectType
\enum EN_CountType \enum EN_CountType
\enum EN_NodeType \enum EN_NodeType
\enum EN_LinkType \enum EN_LinkType
\enum EN_PumpType \enum EN_PumpType
\enum EN_PumpStateType
\enum EN_CurveType \enum EN_CurveType
\enum EN_QualityType \enum EN_QualityType
\enum EN_SourceType \enum EN_SourceType
@@ -276,16 +278,17 @@ These are symbolic constants used as function arguments.
\enum EN_HeadLossType \enum EN_HeadLossType
\enum EN_NodeProperty \enum EN_NodeProperty
\enum EN_LinkProperty \enum EN_LinkProperty
\enum EN_LinkStatusType
\enum EN_TimeParameter \enum EN_TimeParameter
\enum EN_Option \enum EN_Option
\enum EN_FlowUnits \enum EN_FlowUnits
\enum EN_DemandModel \enum EN_DemandModel
\enum EN_MixingModel \enum EN_MixingModel
\enum EN_StatusReport
\enum EN_StatisticType \enum EN_StatisticType
\enum EN_InitHydOption \enum EN_InitHydOption
\enum EN_ActionCodeType \enum EN_ActionCodeType
\enum EN_AnalysisStatistic \enum EN_AnalysisStatistic
\enum EN_StatusReport
\enum EN_RuleObject \enum EN_RuleObject
\enum EN_RuleVariable \enum EN_RuleVariable
\enum EN_RuleOperator \enum EN_RuleOperator
@@ -293,40 +296,6 @@ These are symbolic constants used as function arguments.
@} @}
*/ */
/**
@defgroup Files File Descriptions
These are the various files used by the Toolkit.
@section InputFile Input File
The Input file is a standard EPANET input data file that describes the system being analyzed. It can either be created external to the application being developed with the Toolkit or by the application itself. It is the first file name supplied to the @ref EN_open function. The format of the file is described in Appendix C of the <a href="https://nepis.epa.gov/Adobe/PDF/P1007WWU.pdf">EPANET 2 Users Manual</a>. A project's data associated with its Input file remains accessible until the project is closed down with the @ref EN_close or deleted with @ref EN_deleteproject.
@section ReportFile Report File
The Report file is the second file name supplied to the @ref EN_open function (or the first file name to @ref EN_init). It is used to log any error messages that occur when the Input file is being processed and to record all status messages that are generated during a hydraulic simulation. In addition, if the @ref EN_report function is called the resulting report can also be written to this file as can user-generated lines of text using the @ref EN_writeline function. The format of the report is controlled by statements placed in the [REPORT] section of the Input file and by similar statements included in calls to the @ref EN_setreport function. Only results at a specified uniform reporting time interval are written to this file.
To suppress the writing of all error and warning messages to the Report file either include the command `MESSAGES NO` in the [REPORT] section of the Input file or call the Toolkit function `EN_setreport("MESSAGES NO")`.
To route a formatted report to a different file than the Report file either include the command `FILE filename` in the [REPORT] section of the Input file or call the Toolkit function `EN_setreport("FILE filename")`, where `filename` is the name of the file to use.
Toolkit clients will not be able to access the contents of a Report file until a project is closed. If access is needed before then, the @ref EN_copyreport function can be used to copy its current contents to another file. A @ref EN_clearreport function is also available to clear the current contents of the Report file.
@section OutputFile Output File
The Output file is an unformatted binary file used to store both hydraulic and water quality results at uniform reporting intervals (see @ref OutFileFormat). It is the third file name supplied to the @ref EN_open function (or second name to @ref EN_init). If an empty string ("") is used as its name then a scratch temporary file will be used. Otherwise the Output file will be saved after the @ref EN_close function is called. Saving this file is useful if further post-processing of the output results are needed. The function @ref EN_saveH will transfer hydraulic results to the Output file if no water quality analysis will be made. Using @ref EN_solveQ to run a water quality analysis automatically saves both hydraulic and water quality results to this file. If the @ref EN_initQ - @ref EN_runQ - @ref EN_nextQ set of functions is used to perform a water quality analysis, then results will be saved only if the `saveflag` argument of @ref EN_initQ is set to @ref EN_SAVE. Again, the need to save results to the Output file is application-dependent. If a formatted output report is to be generated using @ref EN_report, then results must first be saved to the Output file.
@section HydraulicsFile Hydraulics File
The Hydraulics file is an unformatted binary file used to store the results of a hydraulic analysis. Results for all time periods are stored, including those at intermediate times when special hydraulic events occur (e.g., pumps and tanks opening or closing because control conditions have been satisfied).
Normally it is a temporary file that is deleted after the @ref EN_deleteproject function is called. However, it will be saved if the @ref EN_savehydfile function is called before that.
Likewise, a previously saved Hydraulics file can be used if the command `HYDRAULICS USE` filename appears in the [OPTIONS] section of the input file, or if the @ref EN_usehydfile function is called.
When the Toolkit function @ref EN_solveH is used to make a hydraulic analysis, results are automatically saved to the Hydraulics file. When the @ref EN_initH - @ref EN_runH - @ref EN_nextH set of functions is used, the `initFlag` argument to @ref EN_initH determines whether results are saved or not. The need to save hydraulic results is application-dependent. They must always be saved to the Hydraulics file if a water quality analysis will follow.
*/
/** /**
@defgroup ErrorCodes Error Codes @defgroup ErrorCodes Error Codes
@@ -409,44 +378,3 @@ When the Toolkit function @ref EN_solveH is used to make a hydraulic analysis, r
|6 | System has negative pressures - negative pressures occurred at one or more junctions with positive demand | |6 | System has negative pressures - negative pressures occurred at one or more junctions with positive demand |
*/ */
/**
@defgroup Units Parameter Units
| Parameter | US Customary | SI Metric |
|----------------|-------------------------|---------------------------|
|Concentration | mg/L or ug/L | mg/L or ug/L |
|Demand | (see Flow units) | (see Flow units) |
|Diameter (Pipes)| inches | millimeters |
|Diameter (Tanks)| feet | meters |
|Efficiency | percent | percent |
|Elevation | feet | meters |
|Emitter Coeff. | flow units @ 1 psi drop | flow units @ 1 meter drop |
|Energy | kwatt - hours | kwatt - hours |
|Flow | CFS (cubic feet / sec) | LPS (liters / sec) |
| | GPM (gallons / min) | LPM (liters / min) |
| | MGD (million gal / day) | MLD (megaliters / day) |
| | IMGD (Imperial MGD) | CMH (cubic meters / hr) |
| | AFD (acre-feet / day) | CMD (cubic meters / day) |
|Friction Factor | unitless | unitless |
|Head | feet | meters |
|Length | feet | meters |
|Minor Loss Coeff. | unitless | unitless |
|Power | horsepower | kwatts |
|Pressure | psi | meters |
|Reaction Coeff. (Bulk) | 1/day (1st-order)| 1/day (1st-order) |
|Reaction Coeff. (Wall) | mass/sq-ft/day (0-order) | mass/sq-m/day (0-order) |
| | ft/day (1st-order) | meters/day (1st-order) |
|Roughness Coeff. | millifeet (Darcy-Weisbach) unitless otherwise| mm (Darcy-Weisbach) unitless otherwise |
|Source Mass Injection | mass/minute | mass/minute |
|Velocity | ft/sec | meters/sec |
|Volume | cubic feet | cubic meters |
|Water Age | hours | hours |
*/
/**
@defgroup OutFileFormat Output File Format
*/

30
doc/readme.md Normal file
View File

@@ -0,0 +1,30 @@
## Generating Documentation for OWA-EPANET 2.2
You must have [Doxygen](http://www.doxygen.nl) installed on your machine to generate documentation for the OWA-EPANET Toolkit. Assuming this is the case, open a terminal window, navigate to the project's **`doc`** directory and issue the command **`doxygen`**. This will generate HTML documentation placed in a sub-directory named **`html`**. From that directory you can launch the **`index.html`** file to view the full documentation in a web browser.
To generate a Windows compiled HTML Help file you must have [Microsoft's HTML Help Workshop](https://www.microsoft.com/en-us/download/details.aspx?id=21138) installed. You then need to edit the Doxygen configuration file **`doxyfile`** as follows:
1. Change the **`GENERATE_HTMLHELP`** setting to **`YES`**.
2. Enter the location where the Help Workshop system was installed next to the
**`HHC_LOCATION`** setting.
After running Doxygen again the resulting Help file named **`owa-epanet.chm`** will appear in the **`html`** sub-directory.
Doxygen uses the special comments placed in the project's **`epanet2_2.h`** and **`epanet2_enums.h`** header files to document EPANET's API. It also uses supplementary material contained in the following files of the project's **`doc`** directory to generate additional pages of documentation:
- **`main.dox`**: generates the *Overview* section.
- **`usage.dox`**: generates the *Usage* section.
- **`toolkit-examples.dox`** : generates the *Examples* section.
- **`toolkit-files.dox`**: generates the *Toolkit Files* section.
- **`input-file.dox`**: generates the *Input File* sub-section.
- **`toolkit-units.dox`**: generates the *Measurement Units* section.
- **`modules.dox`**: defines the contents of the *API Reference* section.
Finally, a group of special Doxygen files are used to customize the format of the generated documentation. These include the following:
- **`doxyfile`**: the main Doxygen configuration file
- **`DoxygenLayout.xml`**: sets the title of the automatically generated *Modules* section to *API Reference* and hides the *Files* section in the tree view pane of the document.
- **`extrastylesheet.css`**: reduces the size of the the h1 heading style.
- **`newfooter.html`**: replaces the default Doxygen footer in HTML output with a custom one.

61
doc/readme.txt
View File

@@ -1,61 +0,0 @@
Generating Documentation for OWA-EPANET 2.2
===========================================
You must have Doxygen (http://www.doxygen.nl/)installed on your machine to generate
documentation for OWA-EPANET's API (aka Toolkit). Assuming this is the case, open a
terminal window, navigate to the project's 'doc' directory and issue the command
'doxygen' to generate documentation in the following formats:
- HTML documentation will be placed in the 'html' sub-directory. Launch 'index.html'
to view it in a web browser.
- Latex documentation will be placed in the 'latex' sub-directory. Assuming you
have a TeX system, such as MikTex (https://miktex.org), installed on your machine
you can generate a PDF of the documentation by issuing the 'make pdf' command from
within the 'latex' directory. The resulting pdf file will be named 'refman.pdf'.
To generate a Windows compiled HTML Help file you must have Microsoft's HTML Help Workshop
(https://www.microsoft.com/en-us/download/details.aspx?id=21138) installed. In this case
you need to first edit the Doxygen configuration file 'Doxyfile' as follows:
1. Change the 'GENERATE_HTMLHELP' setting to 'YES'.
2. Enter the location where the Help Workshop system was installed next to the
'HHC_LOCATION' setting.
After running 'doxygen' again the resulting Help file named 'owa-epanet.chm' will
appear in the 'html' sub-directory.
Doxygen uses the special comments placed in the project's 'epanet2_2.h' and
'epanet2_enums.h' header files to document EPANET's API. It also uses supplementary
material contained in the following files of the project's 'doc' folder to generate
additional pages of documentation:
main.dox - generates the Overview pages.
toolkit-usage.dox: generates the Toolkit Usage page.
toolkit-examples.dox : generates the Toolkit Examples pages.
modules.dox: generates the Reference section of the document consisting of several
module pages that describe Toolkit functions by group, enumerated
constants, file descriptions, error codes, property units, and output
file format.
output-format.dox: generates the pages that describe the format used in different
sections of the output file.
Finally, a group of special Doxygen files are used to customize the format of the
generated documentation. These include the following:
Doxyfile - the main Doxygen configuration file
DoxygenLayout.xml - replaces the title "Modules" with "Reference" and hides the
"Files" section in the tree view pane of the document.
extrastylesheet.css - reduces the size of the the h1 heading style.
newfooter.html - replaces the default Doxygen footer in HTML output with a custom one.
header.tex - replaces the standard title page and footer text used in Latex output.

11
doc/toolkit-examples.dox
View File

@@ -12,9 +12,9 @@ Here are several examples of how the Toolkit can be used for different types of
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. -# Have the application write network data to an EPANET-formatted input file.
-# Create a project and call 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. -# 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.
-# Have the application access the output file to display desired analysis results (see @ref OutFileFormat). -# Have the application access the output file to display desired analysis results (see @ref OutFile).
Here is an example where a callback function `writeConsole` is provided to write EPANET's progress messages to the console: Here is an example where a callback function `writeConsole` is provided to write EPANET's progress messages to the console:
@@ -44,7 +44,12 @@ need to always use an EPANET formatted input file. This creates opportunities to
of network data in one's code, such as relational database files or GIS/CAD files. of network data in one's code, such as relational database files or GIS/CAD files.
Below is a schematic of the network to be built. Below is a schematic of the network to be built.
<table style = "border: 0px solid black">
<tr><td>
@image html Example2.png @image html Example2.png
@image latex Example2.eps
</td></tr>
</table>
\code {.c} \code {.c}
#include "epanet2_2.h" #include "epanet2_2.h"
@@ -174,7 +179,7 @@ double cl2dose(char *SourceID, double Ctarget)
EN_solveH(ph); EN_solveH(ph);
// Get the number of nodes and the source node's index // Get the number of nodes and the source node's index
EN_getcount(ph, EN_NODES, &nnodes); EN_getcount(ph, EN_NODECOUNT, &nnodes);
EN_getnodeindex(ph, SourceID, &sourceindex); EN_getnodeindex(ph, SourceID, &sourceindex);
// Setup the system to analyze for chlorine // Setup the system to analyze for chlorine

144
doc/toolkit-files.dox Normal file
View File

@@ -0,0 +1,144 @@
/** @page Files Toolkit Files
The Toolkit can make use of several different types of files when analyzing a pipe network. These include:
- @subpage InpFile "Input File"
- @subpage RptFile "Report File"
- @subpage OutFile "Output File"
- @subpage HydFile "Hydraulics File"
*/
/**
@page RptFile Report File
The Report file is the second file name supplied to the @ref EN_open function (or the first file name to @ref EN_init). It is used to log any error messages that occur when an Input file is being processed and to record all status messages that are generated during a hydraulic simulation. In addition, if the @ref EN_report function is called the resulting report can also be written to this file as can user-generated lines of text using the @ref EN_writeline function. The format of the report is controlled by statements placed in the @ref ReportPage section of the Input file and by similar statements included in calls to the @ref EN_setreport function. Only results at a specified uniform reporting time interval are written to this file.
To suppress the writing of all error and warning messages to the Report file either include the command <b>`MESSAGES NO`</b> in the @ref ReportPage section of the Input file or call the Toolkit function <b>`EN_setreport("MESSAGES NO")`</b>.
To route a formatted report to a different file than the Report file either include the command <b>`FILE filename`</b> in the @ref ReportPage section of the Input file or call the Toolkit function <b>`EN_setreport("FILE filename")`</b>, where `filename` is the name of the file to use.
Toolkit clients will not be able to access the contents of a Report file until a project is closed. If access is needed before then, the @ref EN_copyreport function can be used to copy its current contents to another file. A @ref EN_clearreport function is also available to clear the current contents of the Report file.
*/
/**
@page OutFile Output File
The Output file is an unformatted binary file used to store both hydraulic and water quality results at uniform reporting intervals. It is the third file name supplied to the @ref EN_open function (or second name to @ref EN_init). If an empty string ("") is used as its name then a scratch temporary file will be used. Otherwise the Output file will be saved after the @ref EN_close function is called. Saving this file is useful if further post-processing of the output results are needed.
The function @ref EN_saveH will transfer hydraulic results to the Output file if no water quality analysis will be made. Using @ref EN_solveQ to run a water quality analysis automatically saves both hydraulic and water quality results to this file. If the @ref EN_initQ - @ref EN_runQ - @ref EN_nextQ set of functions is used to perform a water quality analysis, then results will be saved only if the \b saveflag argument of @ref EN_initQ is set to <B>`EN_SAVE`</B>. Again, the need to save results to the Output file is application-dependent. If a formatted output report is to be generated using @ref EN_report, then results must first be saved to the Output file.
The data written to the file is either 4-byte integers, 4-byte floats, or fixed-size strings whose size is a multiple of 4 bytes. This allows the file to be divided conveniently into 4-byte records. The file consists of four sections of the following sizes in bytes:
| Section | Size in Bytes |
|----------------|----------------------------------------|
|Prolog | 884 + 36*Nnodes + 52*Nlinks + 8*Ntanks |
|Energy Usage | 28*Npumps + 4 |
|Dynamic Results | (16*Nnodes + 32*Nlinks)*Nperiods |
|Epilog | 28 |
where:
- Nnodes = number of nodes (junctions + reservoirs + tanks),
- Nlinks = number of links (pipes + pumps + valves),
- Ntanks = number of tanks and reservoirs,
- Npumps = number of pumps,
- Nperiods = number of reporting periods.
All of these counts are themselves written to the file's Prolog or Epilog sections.
@section Output_Prolog Prolog Section
The Prolog section of an EPANET binary output file contains the following data:
|Item | Type | # Bytes |
|----------------|-----------|-----------|
| Magic Number = 516114521 | Integer | 4 |
| Version (= 200) | Integer | 4 |
| Number of Nodes | Integer | 4 |
| Number of Reservoirs & Tanks | Integer | 4|
| Number of Links | Integer | 4 |
| Number of Pumps | Integer | 4 |
| Number of Valves | Integer | 4 |
| Water Quality Option - see @ref EN_QualityType | Integer | 4 |
| Traced Node Index | Integer | 4 |
| Flow Units Option | Integer | 4 |
| Pressure Units Option:<br>0 = psi<br>1 = meters<br>2 = kPa | Integer | 4 |
| Report Statistic Type - see @ref EN_StatisticType | Integer | 4 |
| Reporting Start Time (sec) | Integer | 4 |
| Reporting Time Step (sec) | Integer | 4 |
| Simulation Duration (sec) | Integer | 4 |
| Project Title (1st line) | Char | 80 |
| Project Title (2nd line) | Char | 80 |
| Project Title (3rd line) | Char | 80 |
| Name of Input File | Char | 260 |
| Name of Report File | Char | 260 |
| Name of Quality Chemical | Char | 32 |
| Chemical Concentration Units | Char | 32 |
| ID String of Each Node | Char | 32*Nnodes |
| ID String of Each Link | Char | 32*Nlinks |
| Index of Head Node of Each Link | Integer | 4*Nlinks |
| Index of Tail Node of Each Link | Integer | 4*Nlinks |
| Type Code of Each Link (see @ref EN_LinkType) | Integer | 4*Nlinks |
| Node Index of Each Tank | Integer | 4*Ntanks |
| Surface Area of Each Tank | Float | 4*Ntanks |
| Elevation of Each Node | Float | 4*Nnodes |
| Length of Each Link | Float | 4*Nlinks |
| Diameter of Each Link | Float | 4*Nlinks |
@section Output_Energy Energy Usage Section
The Energy Usage section of an EPANET binary output file contains the following data:
|Item (Repeated for Each Pump) | Type | # Bytes |
|------------------------------|---------|---------|
| Pump Index in list of links | Integer | 4 |
| Pump Utilization (%) | Float | 4 |
| Average Efficiency (%) | Float | 4 |
| Average kW/MGal (or kW/m^3) | Float | 4 |
| Average kW | Float | 4 |
| Peak kW | Float | 4 |
| Average Cost per Day | Float | 4 |
| Peak Energy Usage (kWh) | Float | 4 |
@section Output_Results Dynamic Results Section
The Dynamic Results section of an EPANET binary output file contains the following set of data for each reporting period (the reporting time step is written to the Output File's @ref Output_Prolog and the number of such steps is written to the @ref Output_Epilog):
| Item | Type | # Bytes |
|------|------|---------|
|Demand at Each Node | Float | 4*Nnodes |
|Head (Grade) at Each Node | Float | 4*Nnodes |
|Pressure at Each Node | Float | 4*Nnodes |
|Water Quality at Each Node | Float | 4*Nnodes |
|Flow in Each Link<br> (negative for reverse flow)| Float | 4*Nlinks |
|Velocity in Each Link | Float | 4*Nlinks |
|Head Loss per 1000 Units of Length for Each Link<br> (total head for pumps and head loss for valves) | Float | 4*Nlinks |
|Average Water Quality in Each Link | Float | 4*Nlinks |
| Status Code for Each Link:<br>0 = closed (pump shutoff head exceeded)<br>1 = temporarily closed<br>2 = closed<br>3 = open<br>4 = active (partially open)<br>5 = open (pump max. flow exceeded)<br>6 = open (FCV can't supply flow)<br>7 = open (PRV/PSV can't supply pressure) | Float | 4*Nlinks |
| Setting for Each Link | Float | 4*Nlinks |
|Reaction Rate for Each Link (mass/L/day) | Float | 4*Nlinks |
|Friction Factor for Each Link | Float | 4*Nlinks |
@section Output_Epilog Epilog Section
The Epilog section of an EPANET binary output file contains the following data:
|Item | Type | # Bytes |
|-----|------|---------|
|Average bulk reaction rate (mass/hr) | Float | 4 |
|Average wall reaction rate (mass/hr) | Float | 4 |
|Average tank reaction rate (mass/hr) | Float | 4 |
|Average source inflow rate (mass/hr) | Float | 4 |
|Number of Reporting Periods | Integer | 4 |
|Warning Flag:<br>0 = no warnings<br>1 = warnings were generated | Integer | 4 |
|Magic Number = 516114521 | Integer | 4 |
*/
/**
@page HydFile Hydraulics File
The Hydraulics file is an unformatted binary file used to store the results of a hydraulic analysis. Results for all time periods are stored, including those at intermediate times when special hydraulic events occur (e.g., pumps and tanks opening or closing because control conditions have been satisfied).
Normally it is a temporary file that is deleted after the @ref EN_deleteproject function is called. However, it will be saved if the @ref EN_savehydfile function is called before that.
Likewise, a previously saved Hydraulics file can be used if the command <b>`HYDRAULICS USE`</b> filename appears in the @ref OptionsPage section of the input file, or if the @ref EN_usehydfile function is called.
When the Toolkit function @ref EN_solveH is used to make a hydraulic analysis, results are automatically saved to the Hydraulics file. When the @ref EN_initH - @ref EN_runH - @ref EN_nextH set of functions is used, the \b initFlag argument to @ref EN_initH determines whether results are saved or not. The need to save hydraulic results is application-dependent. They must always be saved to the Hydraulics file if a water quality analysis will follow.
*/

37
doc/toolkit-units.dox Normal file
View File

@@ -0,0 +1,37 @@
/**
@page Units Measurement Units
The toolkit can use data expressed in either US Customary of SI Metric units. A project's unit system depends on the unit system used for its choice of flow units. If the @ref EN_open function is used to supply data to a project from an Input File then its flow units are set in the @ref OptionsPage section of the file. If the @ref EN_init function is used to initialize a project then the choice of flow units is the fourth argument to the function. The following table lists the units used to express the various parameters in an EPANET model.
| Parameter | US Customary | SI Metric |
|----------------|-------------------------|---------------------------|
|Concentration | mg/L or ug/L | mg/L or ug/L |
|Demand | (see Flow units) | (see Flow units) |
|Diameter (Pipes)| inches | millimeters |
|Diameter (Tanks)| feet | meters |
|Efficiency | percent | percent |
|Elevation | feet | meters |
|Emitter Coeff. | flow units @ 1 psi drop | flow units @ 1 meter drop |
|Energy | kwatt - hours | kwatt - hours |
|Flow | CFS (cubic feet / sec) | LPS (liters / sec) |
| | GPM (gallons / min) | LPM (liters / min) |
| | MGD (million gal / day) | MLD (megaliters / day) |
| | IMGD (Imperial MGD) | CMH (cubic meters / hr) |
| | AFD (acre-feet / day) | CMD (cubic meters / day) |
|Friction Factor | unitless | unitless |
|Head | feet | meters |
|Length | feet | meters |
|Minor Loss Coeff. | unitless | unitless |
|Power | horsepower | kwatts |
|Pressure | psi | meters |
|Reaction Coeff. (Bulk) | 1/day (1st-order)| 1/day (1st-order) |
|Reaction Coeff. (Wall) | mass/sq-ft/day (0-order) | mass/sq-m/day (0-order) |
| | ft/day (1st-order) | meters/day (1st-order) |
|Roughness Coeff. | millifeet (Darcy-Weisbach) unitless otherwise| mm (Darcy-Weisbach) unitless otherwise |
|Source Mass Injection | mass/minute | mass/minute |
|Velocity | ft/sec | meters/sec |
|Volume | cubic feet | cubic meters |
|Water Age | hours | hours |
*/

40
doc/toolkit-usage.dox
View File

@@ -5,8 +5,7 @@ The following topics briefly describe how to accomplish some basic tasks using t
@section CreateProject Creating a Project @section CreateProject Creating a Project
Before any use is made of the Toolkit, a project and its handle must be created. After all processing is 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:
completed the project should be deleted. See the code snippet below:
\code {.c} \code {.c}
EN_Project ph; // a project handle EN_Project ph; // a project handle
@@ -20,6 +19,7 @@ EN_deleteproject(&ph);
@section DetectingErrors Detecting Error Conditions @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. 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} \code {.c}
@@ -41,7 +41,7 @@ void runHydraulics(EN_Project ph, char *inputFile, char *reportFile)
@section NetworkData Providing Network Data @section NetworkData 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 @ref EN_open function to load an EPANET-formatted input file that provides a description of the network to be analyzed. The format of this file is described in Appendix C of the <a href="https://nepis.epa.gov/Adobe/PDF/P1007WWU.pdf">EPANET 2 Users Manual</a>. 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: Once a project is created there are two ways in which it can be populated with data. The first is to use the @ref EN_open function to load an EPANET-formatted @ref InpFile 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:
\code {.c} \code {.c}
EN_Project ph; EN_Project ph;
@@ -57,7 +57,7 @@ EN_deleteproject(&ph);
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 . 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 @ref 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 @ref EN_addnode, @ref EN_addlink, @ref EN_addpattern, @ref EN_addcontrol, etc., can be called to add new objects to the network. Here is a partial example of constructing a network from code: 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 @ref 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 \b EN_add functions, such as @ref EN_addnode, @ref EN_addlink, @ref EN_addpattern, @ref EN_addcontrol, etc., can be called to add new objects to the network. Here is a partial example of constructing a network from code:
\code {.c} \code {.c}
int index; int index;
@@ -70,11 +70,11 @@ EN_addlink(ph, "P1", EN_PIPE, "J1", "J2", &index);
// additional function calls to complete building the network // additional function calls to complete building the network
\endcode \endcode
See the @ref Example2 for a more complete example. The labels used to name objects cannot contain spaces, semi-colons, or double quotes nor exceed @ref 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. See the @ref Example2 for a more complete example. The labels used to name objects cannot contain spaces, semi-colons, or double quotes nor exceed @ref EN_SizeLimits "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.
@section Properties Setting Object Properties @section Properties 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., @ref EN_getnodevalue, @ref EN_getoption, etc.) while the functions used for setting parameter values begin with `EN_set` (e.g., @ref EN_setnodevalue, @ref EN_setoption, etc.). 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 \b EN_get (e.g., @ref EN_getnodevalue, @ref EN_getoption, etc.) while the functions used for setting parameter values begin with \b EN_set (e.g., @ref EN_setnodevalue, @ref 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 @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. 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.
@@ -102,7 +102,7 @@ There are two ways to use the Toolkit to run a hydraulic analysis:
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 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). 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} \code {.c}
void runHydraulics(EN_Project ph, int nRuns) void runHydraulics(EN_Project ph, int nRuns)
@@ -130,7 +130,7 @@ void runHydraulics(EN_Project ph, int nRuns)
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_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 `EN_nextQ` with @ref EN_stepQ will step through one water quality time step at a time.) -# 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.)
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: 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:
@@ -179,13 +179,13 @@ int runConcurrentQuality(EN_Project ph)
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: | |For Nodes: | For Links: |
|----------------------------------- | ----------------------------------------- | |----------------------------------- | ----------------------------------------- |
|`EN_DEMAND` (demand) |`EN_FLOW` (flow rate) | |\b EN_DEMAND (demand) |\b EN_FLOW (flow rate) |
|`EN_HEAD` (hydraulic head) |`EN_VELOCITY` (flow velocity) | |\b EN_HEAD (hydraulic head) |\b EN_VELOCITY (flow velocity) |
|`EN_PRESSURE` (pressure) |`EN_HEADLOSS` (head loss) | |\b EN_PRESSURE (pressure) |\b EN_HEADLOSS (head loss) |
|`EN_TANKLEVEL` (tank water level) |`EN_STATUS` (link status) | |\b EN_TANKLEVEL (tank water level) |\b EN_STATUS (link status) |
|`EN_TANKVOLUME` (tank water volume) |`EN_SETTING` (pump speed or valve setting) | |\b EN_TANKVOLUME (tank water volume) |\b EN_SETTING (pump speed or valve setting) |
|`EN_QUALITY` (water quality) |`EN_ENERGY` (pump energy usage) | |\b EN_QUALITY (water quality) |\b EN_ENERGY (pump energy usage) |
|`EN_SOURCEMASS` (source mass inflow)|`EN_PUMP_EFFIC` (pump efficiency) | |\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} \code {.c}
@@ -197,9 +197,9 @@ void getPressures(EN_Project ph)
char id[EN_MAXID + 1]; char id[EN_MAXID + 1];
EN_getcount(ph, EN_NODECOUNT, &numNodes); EN_getcount(ph, EN_NODECOUNT, &numNodes);
EN_openH(ph); EN_openH(ph);
ENinitH(ph, EN_NOSAVE); EN_initH(ph, EN_NOSAVE);
do { do {
ENrunH(ph, &t); EN_runH(ph, &t);
for (i = 1; i <= NumNodes; i++) { for (i = 1; i <= NumNodes; i++) {
EN_getnodevalue(ph, i, EN_PRESSURE, &p); EN_getnodevalue(ph, i, EN_PRESSURE, &p);
EN_getnodeid(ph, i, id); EN_getnodeid(ph, i, id);
@@ -207,11 +207,11 @@ void getPressures(EN_Project ph)
} }
EN_nextH(&tStep); EN_nextH(&tStep);
} while (tStep > 0); } while (tStep > 0);
ENcloseH(ph); EN_closeH(ph);
} }
\endcode \endcode
@section report Writing a Report @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.
@@ -229,7 +229,7 @@ void reportPressureVariation(EN_Project ph)
// Define contents of the report // Define contents of the report
EN_resetreport(ph); EN_resetreport(ph);
ENsetreport(ph, "FILE myfile.rpt"); EN_setreport(ph, "FILE myfile.rpt");
EN_setreport(ph, "NODES ALL"); EN_setreport(ph, "NODES ALL");
EN_setreport(ph, "PRESSURE PRECISION 1"); EN_setreport(ph, "PRESSURE PRECISION 1");
EN_setreport(ph, "PRESSURE ABOVE 20"); EN_setreport(ph, "PRESSURE ABOVE 20");

117
include/epanet2_2.h
View File

@@ -11,7 +11,7 @@
Authors: see AUTHORS Authors: see AUTHORS
Copyright: see AUTHORS Copyright: see AUTHORS
License: see LICENSE License: see LICENSE
Last Updated: 03/17/2019 Last Updated: 05/30/2019
****************************************************************************** ******************************************************************************
*/ */
@@ -91,7 +91,7 @@ typedef struct Project *EN_Project;
} }
\endcode \endcode
It would be passed into EN_runproject as `&writeConsole`. If this feature is not needed then It would be passed into EN_runproject as `&writeConsole`. If this feature is not needed then
the pviewprog argument should be NULL. the pviewprog argument should be `NULL`.
*/ */
int DLLEXPORT EN_runproject(EN_Project ph, const char *inpFile, const char *rptFile, int DLLEXPORT EN_runproject(EN_Project ph, const char *inpFile, const char *rptFile,
const char *outFile, void (*pviewprog)(char *)); const char *outFile, void (*pviewprog)(char *));
@@ -292,7 +292,7 @@ typedef struct Project *EN_Project;
@return an error or warning code. @return an error or warning code.
This function is used in a loop with ::EN_nextH to run an extended period hydraulic This function is used in a loop with ::EN_nextH to run an extended period hydraulic
simulation. This process automatically updates the simulation clock time so currentTime simulation. This process automatically updates the simulation clock time so \b currentTime
should be treated as a read-only variable. should be treated as a read-only variable.
::EN_initH must have been called prior to running the ::EN_runH - ::EN_nextH loop. ::EN_initH must have been called prior to running the ::EN_runH - ::EN_nextH loop.
@@ -312,7 +312,7 @@ typedef struct Project *EN_Project;
This function is used in a loop with ::EN_runH to run an extended period hydraulic This function is used in a loop with ::EN_runH to run an extended period hydraulic
simulation. simulation.
The value of tstep should be treated as a read-only variable. It is automatically The value of \b tstep should be treated as a read-only variable. It is automatically
computed as the smaller of: computed as the smaller of:
- the time interval until the next hydraulic time step begins - 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 reporting time step begins
@@ -361,7 +361,7 @@ typedef struct Project *EN_Project;
Before calling this function hydraulic results must have been generated and saved by having Before calling this function hydraulic results must have been generated and saved by having
called ::EN_solveH or the ::EN_initH - ::EN_runH - ::EN_nextH sequence with the initflag called ::EN_solveH or the ::EN_initH - ::EN_runH - ::EN_nextH sequence with the initflag
argument of ::EN_initH set to `EN_SAVE` or `EN_SAVE_AND_INIT`. argument of ::EN_initH set to \b EN_SAVE or \b EN_SAVE_AND_INIT.
*/ */
int DLLEXPORT EN_savehydfile(EN_Project ph, const char *filename); int DLLEXPORT EN_savehydfile(EN_Project ph, const char *filename);
@@ -416,15 +416,15 @@ typedef struct Project *EN_Project;
/** /**
@brief Initializes a network prior to running a water quality analysis. @brief Initializes a network prior to running a water quality analysis.
@param ph n EPANET project handle. @param ph an EPANET project handle.
@param saveFlag set to `EN_SAVE` (1) if results are to be saved to the project's @param saveFlag set to \b EN_SAVE (1) if results are to be saved to the project's
binary output file, or to `EN_NOSAVE` (0) if not. binary output file, or to \b EN_NOSAVE (0) if not.
@return an error code. @return an error code.
Call ::EN_initQ prior to running a water quality analysis using ::EN_runQ in Call ::EN_initQ prior to running a water quality analysis using ::EN_runQ in
conjunction with either ::EN_nextQ or ::EN_stepQ. conjunction with either ::EN_nextQ or ::EN_stepQ.
::EN_openQ must have been called prior to calling EN_initQ. ::EN_openQ must have been called prior to calling ::EN_initQ.
Do not call ::EN_initQ if a complete water quality analysis will be made using ::EN_solveQ. Do not call ::EN_initQ if a complete water quality analysis will be made using ::EN_solveQ.
*/ */
@@ -463,7 +463,7 @@ typedef struct Project *EN_Project;
time step determined by when the next hydraulic event occurs. Use ::EN_stepQ instead time step determined by when the next hydraulic event occurs. Use ::EN_stepQ instead
if you wish to generate results over each water quality time step. if you wish to generate results over each water quality time step.
The value of `tStep` is determined from information produced by the hydraulic analysis The value of \b tStep is determined from information produced by the hydraulic analysis
that preceded the water quality analysis. Treat it as a read-only variable. that preceded the water quality analysis. Treat it as a read-only variable.
<b>Example:</b> <b>Example:</b>
@@ -494,8 +494,8 @@ typedef struct Project *EN_Project;
quality time step of the simulation, rather than over each hydraulic event period quality time step of the simulation, rather than over each hydraulic event period
as with ::EN_nextQ. as with ::EN_nextQ.
Use the argument `timeLeft` to determine when no more calls to ::EN_runQ are needed Use the argument \b timeLeft to determine when no more calls to ::EN_runQ are needed
because the end of the simulation period has been reached (i.e., when `timeLeft = 0`). because the end of the simulation period has been reached (i.e., when \b timeLeft = 0).
*/ */
int DLLEXPORT EN_stepQ(EN_Project ph, long *timeLeft); int DLLEXPORT EN_stepQ(EN_Project ph, long *timeLeft);
@@ -580,8 +580,8 @@ typedef struct Project *EN_Project;
@param format a report formatting command. @param format a report formatting command.
@return an error code @return an error code
Acceptable report formatting commands are described in Appendix C of the Acceptable report formatting commands are described in the @ref ReportPage section of
<a href="https://nepis.epa.gov/Adobe/PDF/P1007WWU.pdf">EPANET 2 Users Manual</a>. the @ref InpFile topic.
Formatted results of a simulation can be written to a project's report file Formatted results of a simulation can be written to a project's report file
using the ::EN_report function. using the ::EN_report function.
@@ -596,15 +596,15 @@ typedef struct Project *EN_Project;
Status reporting writes changes in the hydraulics status of network elements to a Status reporting writes changes in the hydraulics status of network elements to a
project's report file as a hydraulic simulation unfolds. There are three levels project's report file as a hydraulic simulation unfolds. There are three levels
of reporting: `EN_NO_REPORT` (no status reporting), `EN_NORMAL_REPORT` (normal of reporting: \b EN_NO_REPORT (no status reporting), \b EN_NORMAL_REPORT (normal
reporting) `EN_FULL_REPORT` (full status reporting). reporting) \b EN_FULL_REPORT (full status reporting).
The full status report contains information at each trial of the solution to the The full status report contains information at each trial of the solution to the
system hydraulic equations at each time step of a simulation. It is useful mainly system hydraulic equations at each time step of a simulation. It is useful mainly
for debugging purposes. for debugging purposes.
If many hydraulic analyses will be run in the application it is recommended that If many hydraulic analyses will be run in the application it is recommended that
status reporting be turned off (`level = EN_NO_REPORT`). status reporting be turned off (<b>level = EN_NO_REPORT</b>).
*/ */
int DLLEXPORT EN_setstatusreport(EN_Project ph, int level); int DLLEXPORT EN_setstatusreport(EN_Project ph, int level);
@@ -625,7 +625,7 @@ typedef struct Project *EN_Project;
@param maxLen maximum number of characters that errmsg can hold @param maxLen maximum number of characters that errmsg can hold
@return an error code @return an error code
Error message strings should be at least @ref EN_MAXMSG characters in length. Error message strings should be at least @ref EN_SizeLimits "EN_MAXMSG" characters in length.
*/ */
int DLLEXPORT EN_geterror(int errcode, char *errmsg, int maxLen); int DLLEXPORT EN_geterror(int errcode, char *errmsg, int maxLen);
@@ -719,7 +719,7 @@ typedef struct Project *EN_Project;
@brief Retrieves the type of water quality analysis to be run. @brief Retrieves the type of water quality analysis to be run.
@param ph an EPANET project handle. @param ph an EPANET project handle.
@param[out] qualType the type of analysis to run (see @ref EN_QualityType). @param[out] qualType the type of analysis to run (see @ref EN_QualityType).
@param[out] traceNode the index of node being traced, if `qualType = EN_TRACE`. @param[out] traceNode the index of node being traced, if <b>qualType = EN_TRACE</b>.
@return an error code. @return an error code.
*/ */
int DLLEXPORT EN_getqualtype(EN_Project ph, int *qualType, int *traceNode); int DLLEXPORT EN_getqualtype(EN_Project ph, int *qualType, int *traceNode);
@@ -730,7 +730,7 @@ typedef struct Project *EN_Project;
@param qualType the type of analysis to run (see @ref EN_QualityType). @param qualType the type of analysis to run (see @ref EN_QualityType).
@param chemName the name of the quality constituent. @param chemName the name of the quality constituent.
@param chemUnits the concentration units of the constituent. @param chemUnits the concentration units of the constituent.
@param traceNode the ID name of the node being traced if `qualType = EN_TRACE`. @param traceNode the ID name of the node being traced if <b>qualType = EN_TRACE</b>.
@return an error code. @return an error code.
Chemical name and units can be an empty string if the analysis is not for a chemical. Chemical name and units can be an empty string if the analysis is not for a chemical.
@@ -766,9 +766,9 @@ typedef struct Project *EN_Project;
@param actionCode the action taken if any control contains the node and its links. @param actionCode the action taken if any control contains the node and its links.
@return an error code. @return an error code.
If `actionCode` is `EN_UNCONDITIONAL` then the node, its incident links and all If \b actionCode is \b EN_UNCONDITIONAL then the node, its incident links and all
simple and rule-based controls that contain them are deleted. If set to 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 \b EN_CONDITIONAL then the node is not deleted if it or its incident links appear
in any controls and error code 261 is returned. in any controls and error code 261 is returned.
*/ */
@@ -790,7 +790,7 @@ typedef struct Project *EN_Project;
@param[out] id the node's ID name. @param[out] id the node's ID name.
@return an error code @return an error code
The ID name must be sized to hold at least @ref EN_MAXID characters. The ID name must be sized to hold at least @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_getnodeid(EN_Project ph, int index, char *id); int DLLEXPORT EN_getnodeid(EN_Project ph, int index, char *id);
@@ -801,7 +801,7 @@ typedef struct Project *EN_Project;
@param newid the new ID name for the node. @param newid the new ID name for the node.
@return an error code. @return an error code.
The ID name must not be longer than @ref EN_MAXID characters. The ID name must not be longer than @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_setnodeid(EN_Project ph, int index, char *newid); int DLLEXPORT EN_setnodeid(EN_Project ph, int index, char *newid);
@@ -906,7 +906,7 @@ typedef struct Project *EN_Project;
@param[out] pexp Pressure exponent in demand function. @param[out] pexp Pressure exponent in demand function.
@return an error code. @return an error code.
Parameters `pmin`, `preq`, and `pexp` are only used when the demand model is `EN_PDA`. Parameters <b>pmin, preq,</b> and \b pexp are only used when the demand model is \b EN_PDA.
*/ */
int DLLEXPORT EN_getdemandmodel(EN_Project ph, int *type, double *pmin, int DLLEXPORT EN_getdemandmodel(EN_Project ph, int *type, double *pmin,
double *preq, double *pexp); double *preq, double *pexp);
@@ -920,15 +920,15 @@ typedef struct Project *EN_Project;
@param pexp Pressure exponent in demand function. @param pexp Pressure exponent in demand function.
@return an error code. @return an error code.
Set `type` to `EN_DDA` for a traditional demand driven analysis (in which case the Set \b type to \b EN_DDA for a traditional demand driven analysis (in which case the
remaining three parameter values are ignored) or to `EN_PDA` for a pressure driven remaining three parameter values are ignored) or to \b EN_PDA for a pressure driven
analysis. In the latter case a node's demand is computed as: analysis. In the latter case a node's demand is computed as:
> `Dfull * [ (P - pmin) / (preq - pmin) ] ^ pexp` > `Dfull * [ (P - pmin) / (preq - pmin) ] ^ pexp`
where `Dfull` is the full demand and `P` is the current pressure. where `Dfull` is the full demand and `P` is the current pressure.
Setting `preq` equal to `pmin` will result in a solution with the smallest amount of Setting \b preq equal to \b pmin will result in a solution with the smallest amount of
demand reductions needed to insure that no node delivers positive demand at a pressure demand reductions needed to insure that no node delivers positive demand at a pressure
below `pmin`. below \b pmin.
*/ */
int DLLEXPORT EN_setdemandmodel(EN_Project ph, int type, double pmin, int DLLEXPORT EN_setdemandmodel(EN_Project ph, int type, double pmin,
double preq, double pexp); double preq, double pexp);
@@ -1035,7 +1035,7 @@ typedef struct Project *EN_Project;
@param[out] demandName The name of the selected category. @param[out] demandName The name of the selected category.
@return an error code. @return an error code.
`demandName` must be sized to contain at least @ref EN_MAXID characters. \b demandName must be sized to contain at least @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_getdemandname(EN_Project ph, int nodeIndex, int demandIndex, char *demandName); int DLLEXPORT EN_getdemandname(EN_Project ph, int nodeIndex, int demandIndex, char *demandName);
@@ -1047,7 +1047,7 @@ typedef struct Project *EN_Project;
@param demandName the new name assigned to the category. @param demandName the new name assigned to the category.
@return Error code. @return Error code.
The category name must contain no more than @ref EN_MAXID characters. The category name must contain no more than @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_setdemandname(EN_Project ph, int nodeIndex, int demandIdx, char *demandName); int DLLEXPORT EN_setdemandname(EN_Project ph, int nodeIndex, int demandIdx, char *demandName);
@@ -1067,13 +1067,18 @@ typedef struct Project *EN_Project;
@param[out] index the index of the newly added link. @param[out] index the index of the newly added link.
@return an error code. @return an error code.
A new pipe is assigned a diameter of 10 inches (or 254 mm), a length of 100 A new pipe is assigned a diameter of 10 inches (254 mm) and a length of 330
feet (or meters), a roughness coefficient of 100 and 0 for all other properties. feet (~ 100 meters). Its roughness coefficient depends on the head loss formula in effect (see @ref EN_HeadLossType) as follows:
- Hazen-Williams formula: 130
- Darcy-Weisbach formula: 0.5 millifeet (0.15 mm)
- Chezy-Manning formula: 0.01
A new pump has a status of `EN_OPEN`, a speed setting of 1, and has no pump All other pipe properties are set to 0.
A new pump has a status of \b EN_OPEN, a speed setting of 1, and has no pump
curve or power rating assigned to it. curve or power rating assigned to it.
A new valve has a diameter of 10 inches (or 254 mm) and all other properties set to 0. A new valve has a diameter of 10 inches (254 mm) and all other properties set to 0.
See @ref EN_LinkProperty. See @ref EN_LinkProperty.
*/ */
@@ -1087,8 +1092,8 @@ typedef struct Project *EN_Project;
@param actionCode The action taken if any control contains the link. @param actionCode The action taken if any control contains the link.
@return an error code. @return an error code.
If `actionCode` is `EN_UNCONDITIONAL` then the link and all simple and rule-based If \b actionCode is \b 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 controls that contain it are deleted. If set to \b EN_CONDITIONAL then the link
is not deleted if it appears in any control and error 261 is returned. is not deleted if it appears in any control and error 261 is returned.
*/ */
int DLLEXPORT EN_deletelink(EN_Project ph, int index, int actionCode); int DLLEXPORT EN_deletelink(EN_Project ph, int index, int actionCode);
@@ -1109,7 +1114,7 @@ typedef struct Project *EN_Project;
@param[out] id The link's ID name. @param[out] id The link's ID name.
@return an error code. @return an error code.
The ID name must be sized to hold at least @ref EN_MAXID characters. The ID name must be sized to hold at least @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_getlinkid(EN_Project ph, int index, char *id); int DLLEXPORT EN_getlinkid(EN_Project ph, int index, char *id);
@@ -1120,7 +1125,7 @@ typedef struct Project *EN_Project;
@param newid the new ID name for the link. @param newid the new ID name for the link.
@return Error code. @return Error code.
The ID name must not be longer than @ref EN_MAXID characters. The ID name must not be longer than @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_setlinkid(EN_Project ph, int index, char *newid); int DLLEXPORT EN_setlinkid(EN_Project ph, int index, char *newid);
@@ -1141,9 +1146,9 @@ typedef struct Project *EN_Project;
@param actionCode the action taken if any controls contain the link. @param actionCode the action taken if any controls contain the link.
@return an error code. @return an error code.
If `actionCode` is `EN_UNCONDITIONAL` then all simple and rule-based controls that If \b actionCode is \b 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 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 \b EN_CONDITIONAL then the type change is cancelled if the link appears in any
control and error 261 is returned. control and error 261 is returned.
*/ */
int DLLEXPORT EN_setlinktype(EN_Project ph, int *index, int linkType, int actionCode); int DLLEXPORT EN_setlinktype(EN_Project ph, int *index, int linkType, int actionCode);
@@ -1281,7 +1286,7 @@ typedef struct Project *EN_Project;
@param[out] id the time pattern's ID name. @param[out] id the time pattern's ID name.
@return an error code. @return an error code.
The ID name must be sized to hold at least @ref EN_MAXID characters. The ID name must be sized to hold at least @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_getpatternid(EN_Project ph, int index, char *id); int DLLEXPORT EN_getpatternid(EN_Project ph, int index, char *id);
@@ -1292,7 +1297,7 @@ typedef struct Project *EN_Project;
@param id the time pattern's new ID name. @param id the time pattern's new ID name.
@return an error code. @return an error code.
The new ID name must not exceed @ref EN_MAXID characters. The new ID name must not exceed @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_setpatternid(EN_Project ph, int index, char *id); int DLLEXPORT EN_setpatternid(EN_Project ph, int index, char *id);
@@ -1342,7 +1347,7 @@ typedef struct Project *EN_Project;
@param len the number of factor values supplied. @param len the number of factor values supplied.
@return an error code. @return an error code.
`values` is a zero-based array that contains `len` elements. \b values is a zero-based array that contains \b len elements.
Use this function to redefine (and resize) a time pattern all at once; Use this function to redefine (and resize) a time pattern all at once;
use @ref EN_setpatternvalue to revise pattern factors one at a time. use @ref EN_setpatternvalue to revise pattern factors one at a time.
@@ -1389,7 +1394,7 @@ typedef struct Project *EN_Project;
@param[out] id the curve's ID name. @param[out] id the curve's ID name.
@return an error code. @return an error code.
The ID name must be sized to hold at least @ref EN_MAXID characters. The ID name must be sized to hold at least @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_getcurveid(EN_Project ph, int index, char *id); int DLLEXPORT EN_getcurveid(EN_Project ph, int index, char *id);
@@ -1400,7 +1405,7 @@ typedef struct Project *EN_Project;
@param id the data curve's new ID name. @param id the data curve's new ID name.
@return an error code. @return an error code.
The new ID name must not exceed @ref EN_MAXID characters. The new ID name must not exceed @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_setcurveid(EN_Project ph, int index, char *id); int DLLEXPORT EN_setcurveid(EN_Project ph, int index, char *id);
@@ -1458,7 +1463,7 @@ typedef struct Project *EN_Project;
The calling program is responsible for making `xValues` and `yValues` large enough The calling program is responsible for making `xValues` and `yValues` large enough
to hold `nPoints` number of data points and for sizing `id` to hold at least to hold `nPoints` number of data points and for sizing `id` to hold at least
@ref EN_MAXID characters. @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_getcurve(EN_Project ph, int index, char* id, int *nPoints, int DLLEXPORT EN_getcurve(EN_Project ph, int index, char* id, int *nPoints,
double *xValues, double *yValues); double *xValues, double *yValues);
@@ -1472,7 +1477,7 @@ typedef struct Project *EN_Project;
@param nPoints the new number of data points for the curve. @param nPoints the new number of data points for the curve.
@return an error code. @return an error code.
`xValues` and `yValues` are zero-based arrays that contains `nPoints` elements. \b xValues and \b yValues are zero-based arrays that contains \b nPoints elements.
Use this function to redefine (and resize) a curve all at once; Use this function to redefine (and resize) a curve all at once;
use @ref EN_setcurvevalue to revise a curve's data points one at a time. use @ref EN_setcurvevalue to revise a curve's data points one at a time.
@@ -1493,7 +1498,7 @@ typedef struct Project *EN_Project;
@param linkIndex the index of a link to control (starting from 1). @param linkIndex the index of a link to control (starting from 1).
@param setting control setting applied to the link. @param setting control setting applied to the link.
@param nodeIndex index of the node used to control the link @param nodeIndex index of the node used to control the link
(0 for `EN_TIMER` and `EN_TIMEOFDAY` controls). (0 for \b EN_TIMER and \b EN_TIMEOFDAY controls).
@param level action level (tank level, junction pressure, or time in seconds) @param level action level (tank level, junction pressure, or time in seconds)
that triggers the control. that triggers the control.
@param[out] index index of the new control. @param[out] index index of the new control.
@@ -1518,7 +1523,7 @@ typedef struct Project *EN_Project;
@param[out] linkIndex the index of the link being controlled. @param[out] linkIndex the index of the link being controlled.
@param[out] setting the control setting applied to the link. @param[out] setting the control setting applied to the link.
@param[out] nodeIndex the index of the node used to trigger the control @param[out] nodeIndex the index of the node used to trigger the control
(0 for `EN_TIMER` and `EN_TIMEOFDAY` controls). (0 for \b EN_TIMER and \b EN_TIMEOFDAY controls).
@param[out] level the action level (tank level, junction pressure, or time in seconds) @param[out] level the action level (tank level, junction pressure, or time in seconds)
that triggers the control. that triggers the control.
@return an error code. @return an error code.
@@ -1534,7 +1539,7 @@ typedef struct Project *EN_Project;
@param linkIndex the index of the link being controlled. @param linkIndex the index of the link being controlled.
@param setting the control setting applied to the link. @param setting the control setting applied to the link.
@param nodeIndex the index of the node used to trigger the control @param nodeIndex the index of the node used to trigger the control
(0 for `EN_TIMER` and `EN_TIMEOFDAY` controls). (0 for \b EN_TIMER and \b EN_TIMEOFDAY controls).
@param level the action level (tank level, junction pressure, or time in seconds) @param level the action level (tank level, junction pressure, or time in seconds)
that triggers the control. that triggers the control.
@return an error code. @return an error code.
@@ -1555,8 +1560,8 @@ typedef struct Project *EN_Project;
@param rule text of the rule following the format used in an EPANET input file. @param rule text of the rule following the format used in an EPANET input file.
@return an error code. @return an error code.
Consult Appendix C of the <a href="https://nepis.epa.gov/Adobe/PDF/P1007WWU.pdf">EPANET 2 Users Manual</a> Consult the @ref RulesPage section of the @ref InpFile topic to learn about a
to learn about a rule's format. Each clause of the rule must end with a newline character `\n`. rule's format. Each clause of the rule must end with a newline character <b>`\n`</b>.
*/ */
int DLLEXPORT EN_addrule(EN_Project ph, char *rule); int DLLEXPORT EN_addrule(EN_Project ph, char *rule);
@@ -1588,7 +1593,7 @@ typedef struct Project *EN_Project;
@param[out] id the rule's ID name. @param[out] id the rule's ID name.
@return Error code. @return Error code.
The ID name must be sized to hold at least @ref EN_MAXID characters. The ID name must be sized to hold at least @ref EN_SizeLimits "EN_MAXID" characters.
*/ */
int DLLEXPORT EN_getruleID(EN_Project ph, int index, char* id); int DLLEXPORT EN_getruleID(EN_Project ph, int index, char* id);
@@ -1598,7 +1603,7 @@ typedef struct Project *EN_Project;
@param ruleIndex the rule's index (starting from 1). @param ruleIndex the rule's index (starting from 1).
@param premiseIndex the position of the premise in the rule's list of premises @param premiseIndex the position of the premise in the rule's list of premises
(starting from 1). (starting from 1).
@param[out] logop the premise's logical operator (`IF` = 1, `AND` = 2, `OR` = 3). @param[out] logop the premise's logical operator ( \b IF = 1, \b AND = 2, \b OR = 3 ).
@param[out] object the type of object the premise refers to (see @ref EN_RuleObject). @param[out] object the type of object the premise refers to (see @ref EN_RuleObject).
@param[out] objIndex the index of the object (e.g. the index of a tank). @param[out] objIndex the index of the object (e.g. the index of a tank).
@param[out] variable the object's variable being compared (see @ref EN_RuleVariable). @param[out] variable the object's variable being compared (see @ref EN_RuleVariable).
@@ -1617,7 +1622,7 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle. @param ph an EPANET project handle.
@param ruleIndex the rule's index (starting from 1). @param ruleIndex the rule's index (starting from 1).
@param premiseIndex the position of the premise in the rule's list of premises. @param premiseIndex the position of the premise in the rule's list of premises.
@param logop the premise's logical operator (`IF` = 1, `AND` = 2, `OR` = 3). @param logop the premise's logical operator ( \b IF = 1, \b AND = 2, \b OR = 3 ).
@param object the type of object the premise refers to (see @ref EN_RuleObject). @param object the type of object the premise refers to (see @ref EN_RuleObject).
@param objIndex the index of the object (e.g. the index of a tank). @param objIndex the index of the object (e.g. the index of a tank).
@param variable the object's variable being compared (see @ref EN_RuleVariable). @param variable the object's variable being compared (see @ref EN_RuleVariable).

76
include/epanet2_enums.h
View File

@@ -9,7 +9,7 @@
Authors: see AUTHORS Authors: see AUTHORS
Copyright: see AUTHORS Copyright: see AUTHORS
License: see LICENSE License: see LICENSE
Last Updated: 04/03/2019 Last Updated: 05/30/2019
****************************************************************************** ******************************************************************************
*/ */
@@ -20,14 +20,20 @@
// --- Define the EPANET toolkit constants // --- Define the EPANET toolkit constants
#define EN_MAXID 31 //!< Max. # characters in ID name /// Size Limts
#define EN_MAXMSG 255 //!< Max. # characters in message text /**
Limits on the size of character arrays used to store ID names
and text messages.
*/
typedef enum {
EN_MAXID = 31, //!< Max. # characters in ID name
EN_MAXMSG = 255 //!< Max. # characters in message text
} EN_SizeLimits;
/// Node properties /// Node properties
/** /**
These node properties can be accessed with @ref EN_getnodevalue and These node properties are used with @ref EN_getnodevalue and @ref EN_setnodevalue.
@ref EN_setnodevalue. Those marked as read only are computed values that can Those marked as read only are computed values that can only be retrieved.
only be retrieved.
*/ */
typedef enum { typedef enum {
EN_ELEVATION = 0, //!< Elevation EN_ELEVATION = 0, //!< Elevation
@@ -60,7 +66,7 @@ typedef enum {
/// Link properties /// Link properties
/** /**
These link properties can be accessed with @ref EN_getlinkvalue and @ref EN_setlinkvalue. These link properties are used with @ref EN_getlinkvalue and @ref EN_setlinkvalue.
Those marked as read only are computed values that can only be retrieved. Those marked as read only are computed values that can only be retrieved.
*/ */
typedef enum { typedef enum {
@@ -91,7 +97,7 @@ typedef enum {
/// Time parameters /// Time parameters
/** /**
These time parameters are accessed using @ref EN_gettimeparam and@ref EN_settimeparam. These time-related options are used with @ref EN_gettimeparam and@ref EN_settimeparam.
All times are expressed in seconds The parameters marked as read only are All times are expressed in seconds The parameters marked as read only are
computed values that can only be retrieved. computed values that can only be retrieved.
*/ */
@@ -130,7 +136,7 @@ typedef enum {
/// Types of network objects /// Types of network objects
/** /**
A network model is composed of these types of objects. The types of objects that comprise a network model.
*/ */
typedef enum { typedef enum {
EN_NODE = 0, //!< Nodes EN_NODE = 0, //!< Nodes
@@ -152,10 +158,10 @@ typedef enum {
EN_PATCOUNT = 3, //!< Number of time patterns EN_PATCOUNT = 3, //!< Number of time patterns
EN_CURVECOUNT = 4, //!< Number of data curves EN_CURVECOUNT = 4, //!< Number of data curves
EN_CONTROLCOUNT = 5, //!< Number of simple controls EN_CONTROLCOUNT = 5, //!< Number of simple controls
EN_RULECOUNT = 6 //!< Number of rule-based controls EN_RULECOUNT = 6 //!< Number of rule-based controls
} EN_CountType; } EN_CountType;
/// Types of nodes /// Node Types
/** /**
These are the different types of nodes that can be returned by calling @ref EN_getnodetype. These are the different types of nodes that can be returned by calling @ref EN_getnodetype.
*/ */
@@ -165,7 +171,7 @@ typedef enum {
EN_TANK = 2 //!< Storage tank node EN_TANK = 2 //!< Storage tank node
} EN_NodeType; } EN_NodeType;
/// Types of links /// Link types
/** /**
These are the different types of links that can be returned by calling @ref EN_getlinktype. These are the different types of links that can be returned by calling @ref EN_getlinktype.
*/ */
@@ -184,7 +190,7 @@ typedef enum {
/// Link status /// Link status
/** /**
One of these values is returned when @ref EN_getlinkvalue is used to retrieve a link's One of these values is returned when @ref EN_getlinkvalue is used to retrieve a link's
initial status (EN_INITSTATUS) or its current status (EN_STATUS). These options are initial status ( \b EN_INITSTATUS ) or its current status ( \b EN_STATUS ). These options are
also used with @ref EN_setlinkvalue to set values for these same properties. also used with @ref EN_setlinkvalue to set values for these same properties.
*/ */
typedef enum { typedef enum {
@@ -195,8 +201,8 @@ typedef enum {
/// Pump states /// Pump states
/** /**
One of these codes is returned when @ref EN_getlinkvalue is used to retrieve a pump's One of these codes is returned when @ref EN_getlinkvalue is used to retrieve a pump's
current operating state (EN_PUMP_STATE). EN_PUMP_XHEAD indicates that the pump has been current operating state ( \b EN_PUMP_STATE ). \b EN_PUMP_XHEAD indicates that the pump has been
shut down because it is being asked to deliver more than its shutoff head. EN_PUMP_XFLOW shut down because it is being asked to deliver more than its shutoff head. \b EN_PUMP_XFLOW
indicates that the pump is being asked to deliver more than its maximum flow. indicates that the pump is being asked to deliver more than its maximum flow.
*/ */
typedef enum { typedef enum {
@@ -218,25 +224,23 @@ typedef enum {
EN_TRACE = 3 //!< Source tracing analysis EN_TRACE = 3 //!< Source tracing analysis
} EN_QualityType; } EN_QualityType;
/// Types of water quality sources /// Water quality source types
/** /**
These are the options for EN_SOURCETYPE, the type of external water quality These are the different types of external water quality sources that can be assigned
source assigned to a node. They are used in @ref EN_getnodevalue and @ref EN_setnodevalue. to a node's \b EN_SOURCETYPE property as used by @ref EN_getnodevalue and @ref EN_setnodevalue.
The EN_SOURCEQUAL property is used in these functions to access a source's strength
and EN_SOURCEPATTERN to access a time pattern applied to the source.
*/ */
typedef enum { typedef enum {
EN_CONCEN = 0, //!< Concentration of any external inflow entering a node EN_CONCEN = 0, //!< Sets the concentration of external inflow entering a node
EN_MASS = 1, //!< Injects a given mass/minute into a node EN_MASS = 1, //!< Injects a given mass/minute into a node
EN_SETPOINT = 2, //!< Sets the concentration leaving a node to a given value EN_SETPOINT = 2, //!< Sets the concentration leaving a node to a given value
EN_FLOWPACED = 3 //!< Adds a given value to the concentration leaving a node EN_FLOWPACED = 3 //!< Adds a given value to the concentration leaving a node
} EN_SourceType; } EN_SourceType;
/// Head loss formula choices /// Head loss formulas
/** /**
These are the choices for the EN_HEADLOSSFORM option in @ref EN_getoption and The available choices for the \b EN_HEADLOSSFORM option in @ref EN_getoption and
@ref EN_setoption. They are also used for the head loss type argument in @ref EN_init. @ref EN_setoption. They are also used for the head loss type argument in @ref EN_init.
Each head loss formula uses a different type of roughness coefficient (EN_ROUGHNESS) Each head loss formula uses a different type of roughness coefficient ( \b EN_ROUGHNESS )
that can be set with @ref EN_setlinkvalue. that can be set with @ref EN_setlinkvalue.
*/ */
typedef enum { typedef enum {
@@ -245,11 +249,11 @@ typedef enum {
EN_CM = 2 //!< Chezy-Manning EN_CM = 2 //!< Chezy-Manning
} EN_HeadLossType; } EN_HeadLossType;
/// Flow units choices /// Flow units
/** /**
These choices for flow units are used with @ref EN_getflowunits and @ref EN_setflowunits. These choices for flow units are used with @ref EN_getflowunits and @ref EN_setflowunits.
They are also used for the flow units type argument in @ref EN_init. If flow units are They are also used for the flow units type argument in @ref EN_init. If flow units are
expressed in US Customary units (EN_CFS through EN_AFD) then all other quantities are expressed in US Customary units ( \b EN_CFS through \b EN_AFD ) then all other quantities are
in US Customary units. Otherwise they are in metric units. in US Customary units. Otherwise they are in metric units.
*/ */
typedef enum { typedef enum {
@@ -265,9 +269,9 @@ typedef enum {
EN_CMD = 9 //!< Cubic meters per day EN_CMD = 9 //!< Cubic meters per day
} EN_FlowUnits; } EN_FlowUnits;
/// Types of demand models /// Demand models
/** /**
These choices for representing consumer demands are used with @ref EN_getdemandmodel These choices for modeling consumer demands are used with @ref EN_getdemandmodel
and @ref EN_setdemandmodel. and @ref EN_setdemandmodel.
A demand driven analysis requires that a junction's full demand be supplied A demand driven analysis requires that a junction's full demand be supplied
@@ -287,7 +291,7 @@ that are applied on a network-wide basis. They are accessed using the
@ref EN_getoption and @ref EN_setoption functions. @ref EN_getoption and @ref EN_setoption functions.
*/ */
typedef enum { typedef enum {
EN_TRIALS = 0, //!< Maximum hydraulic trials allowed for hydraulic convergence EN_TRIALS = 0, //!< Maximum trials allowed for hydraulic convergence
EN_ACCURACY = 1, //!< Total normalized flow change for hydraulic convergence EN_ACCURACY = 1, //!< Total normalized flow change for hydraulic convergence
EN_TOLERANCE = 2, //!< Water quality tolerance EN_TOLERANCE = 2, //!< Water quality tolerance
EN_EMITEXPON = 3, //!< Exponent in emitter discharge formula EN_EMITEXPON = 3, //!< Exponent in emitter discharge formula
@@ -312,7 +316,7 @@ typedef enum {
EN_CONCENLIMIT = 22 //!< Limiting concentration for growth reactions EN_CONCENLIMIT = 22 //!< Limiting concentration for growth reactions
} EN_Option; } EN_Option;
/// Types of simple controls /// Simple control types
/** /**
These are the different types of simple (single statement) controls that can be applied These are the different types of simple (single statement) controls that can be applied
to network links. They are used as an argument to @ref EN_addcontrol,@ref EN_getcontrol, to network links. They are used as an argument to @ref EN_addcontrol,@ref EN_getcontrol,
@@ -329,7 +333,7 @@ typedef enum {
/** /**
These options determine what kind of statistical post-processing should be done on These options determine what kind of statistical post-processing should be done on
the time series of simulation results generated before they are reported using the time series of simulation results generated before they are reported using
@ref EN_report. An option can be chosen by using `STATISTIC option` as the argument @ref EN_report. An option can be chosen by using \b STATISTIC _option_ as the argument
to @ref EN_setreport. to @ref EN_setreport.
*/ */
typedef enum { typedef enum {
@@ -343,7 +347,7 @@ typedef enum {
/// Tank mixing models /// Tank mixing models
/** /**
These are the different types of models that describe water quality mixing in storage tanks. These are the different types of models that describe water quality mixing in storage tanks.
The choice of model is accessed with the EN_MIXMODEL property of a Tank node using The choice of model is accessed with the \b EN_MIXMODEL property of a Tank node using
@ref EN_getnodevalue and @ref EN_setnodevalue. @ref EN_getnodevalue and @ref EN_setnodevalue.
*/ */
typedef enum { typedef enum {
@@ -377,7 +381,7 @@ typedef enum {
/// Types of data curves /// Types of data curves
/** /**
These are the different types of physical relationships that a data curve could These are the different types of physical relationships that a data curve can
represent as returned by calling @ref EN_getcurvetype. represent as returned by calling @ref EN_getcurvetype.
*/ */
typedef enum { typedef enum {
@@ -392,11 +396,11 @@ typedef enum {
/** /**
These codes are used in @ref EN_deletenode and @ref EN_deletelink to indicate what action These codes are used in @ref EN_deletenode and @ref EN_deletelink to indicate what action
should be taken if the node or link being deleted appears in any simple or rule-based should be taken if the node or link being deleted appears in any simple or rule-based
controls. controls or if a deleted node has any links connected to it.
*/ */
typedef enum { typedef enum {
EN_UNCONDITIONAL = 0, //!< Delete all controls that contain object EN_UNCONDITIONAL = 0, //!< Delete all controls and connecing links
EN_CONDITIONAL = 1 //!< Cancel object deletion if contained in controls EN_CONDITIONAL = 1 //!< Cancel object deletion if it appears in controls or has connecting links
} EN_ActionCodeType; } EN_ActionCodeType;
/// Status reporting levels /// Status reporting levels