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>
<tab type="mainpage" visible="yes" title=""/>
<tab type="pages" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="Reference"
intro="These topics describe the Toolkit's functions, symbolic constants, and other details related to its usage."/>
<tab type="modules" visible="yes" title="API Reference"
intro="These topics describe the Toolkit's functions, enumerations, and error/warning codes."/>
<tab type="namespaces" visible="yes" title="">
<tab type="namespacelist" 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 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
# grouped member an include statement to the documentation, telling the reader
@@ -778,10 +778,12 @@ WARN_LOGFILE =
INPUT = main.dox \
toolkit-usage.dox \
toolkit-examples.dox \
toolkit-files.dox \
input-file.dox \
toolkit-units.dox \
modules.dox \
../include/epanet2_2.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
# 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.
# 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
# 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.
# 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
# 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.
# 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
# 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
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:
- 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
@@ -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
- 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.
</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:
- @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>.
__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
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 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.
@@ -60,8 +72,13 @@ for more information on EPANET's data model.
@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:
<table style = "border: 0px solid black">
<tr><td>
@image html DataFlow.png
@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.
@@ -84,8 +101,8 @@ with single threaded applications.
analyzed concurrently.
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
library begin with `EN_`.
- Function names in the single-threaded library begin with \b EN while those in the multi-threaded
library begin with \b EN_.
- The multi-threaded functions contain an additional argument that references a particular network project
that the function is applied to.
- 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
These are symbolic constants used as function arguments.
@defgroup Enumerations Enumerated Types
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
@{
@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_initH(EN_Project ph, int initFlag)
@fn int EN_runH(EN_Project ph, long *currentTime)
@fn int EN_nextH(EN_Project ph, long *tStep)
@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)
@}
*/
@@ -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_NodeType
\enum EN_LinkType
\enum EN_PumpType
\enum EN_PumpStateType
\enum EN_CurveType
\enum EN_QualityType
\enum EN_SourceType
@@ -276,16 +278,17 @@ These are symbolic constants used as function arguments.
\enum EN_HeadLossType
\enum EN_NodeProperty
\enum EN_LinkProperty
\enum EN_LinkStatusType
\enum EN_TimeParameter
\enum EN_Option
\enum EN_FlowUnits
\enum EN_DemandModel
\enum EN_MixingModel
\enum EN_StatusReport
\enum EN_StatisticType
\enum EN_InitHydOption
\enum EN_ActionCodeType
\enum EN_AnalysisStatistic
\enum EN_StatusReport
\enum EN_RuleObject
\enum EN_RuleVariable
\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
@@ -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 |
*/
/**
@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:
-# 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:
@@ -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.
Below is a schematic of the network to be built.
<table style = "border: 0px solid black">
<tr><td>
@image html Example2.png
@image latex Example2.eps
</td></tr>
</table>
\code {.c}
#include "epanet2_2.h"
@@ -174,7 +179,7 @@ double cl2dose(char *SourceID, double Ctarget)
EN_solveH(ph);
// 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);
// 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
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:
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:
\code {.c}
EN_Project ph; // a project handle
@@ -20,6 +19,7 @@ EN_deleteproject(&ph);
@section DetectingErrors Detecting Error Conditions
All of the Toolkit functions return an error/warning code. A 0 indicates that the function ran successfully. A number greater than 0 but less than 100 indicates that a warning condition was generated while a number higher than 100 indicates that the function failed.
The meaning of specific error and warning codes are listed in the @ref ErrorCodes and @ref WarningCodes sections of this guide. The Toolkit function @ref EN_geterror can be used to obtain the text of a specific error/warning code. The following example uses a macro named `ERRCODE` along with a variable named `errcode` to execute Toolkit commands only if no fatal errors have already been detected:
\code {.c}
@@ -41,7 +41,7 @@ void runHydraulics(EN_Project ph, char *inputFile, char *reportFile)
@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}
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 .
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}
int index;
@@ -70,11 +70,11 @@ EN_addlink(ph, "P1", EN_PIPE, "J1", "J2", &index);
// additional function calls to complete building the network
\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
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.
@@ -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 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}
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:
-# 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:
@@ -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:
|For Nodes: | For Links: |
|----------------------------------- | ----------------------------------------- |
|`EN_DEMAND` (demand) |`EN_FLOW` (flow rate) |
|`EN_HEAD` (hydraulic head) |`EN_VELOCITY` (flow velocity) |
|`EN_PRESSURE` (pressure) |`EN_HEADLOSS` (head loss) |
|`EN_TANKLEVEL` (tank water level) |`EN_STATUS` (link status) |
|`EN_TANKVOLUME` (tank water volume) |`EN_SETTING` (pump speed or valve setting) |
|`EN_QUALITY` (water quality) |`EN_ENERGY` (pump energy usage) |
|`EN_SOURCEMASS` (source mass inflow)|`EN_PUMP_EFFIC` (pump efficiency) |
|\b EN_DEMAND (demand) |\b EN_FLOW (flow rate) |
|\b EN_HEAD (hydraulic head) |\b EN_VELOCITY (flow velocity) |
|\b EN_PRESSURE (pressure) |\b EN_HEADLOSS (head loss) |
|\b EN_TANKLEVEL (tank water level) |\b EN_STATUS (link status) |
|\b EN_TANKVOLUME (tank water volume) |\b EN_SETTING (pump speed or valve setting) |
|\b EN_QUALITY (water quality) |\b EN_ENERGY (pump energy usage) |
|\b EN_SOURCEMASS (source mass inflow)|\b EN_PUMP_EFFIC (pump efficiency) |
The following code shows how to retrieve the pressure at each node of a network after each time step of a hydraulic analysis (`writetofile` is a user-defined function that will write a record to a file):
\code {.c}
@@ -197,9 +197,9 @@ void getPressures(EN_Project ph)
char id[EN_MAXID + 1];
EN_getcount(ph, EN_NODECOUNT, &numNodes);
EN_openH(ph);
ENinitH(ph, EN_NOSAVE);
EN_initH(ph, EN_NOSAVE);
do {
ENrunH(ph, &t);
EN_runH(ph, &t);
for (i = 1; i <= NumNodes; i++) {
EN_getnodevalue(ph, i, EN_PRESSURE, &p);
EN_getnodeid(ph, i, id);
@@ -207,11 +207,11 @@ void getPressures(EN_Project ph)
}
EN_nextH(&tStep);
} while (tStep > 0);
ENcloseH(ph);
EN_closeH(ph);
}
\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.
@@ -229,7 +229,7 @@ void reportPressureVariation(EN_Project ph)
// Define contents of the report
EN_resetreport(ph);
ENsetreport(ph, "FILE myfile.rpt");
EN_setreport(ph, "FILE myfile.rpt");
EN_setreport(ph, "NODES ALL");
EN_setreport(ph, "PRESSURE PRECISION 1");
EN_setreport(ph, "PRESSURE ABOVE 20");