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

Update docs for version 2.3

Browse Source
This commit is contained in:
Lew Rossman
2025-03-28 09:16:38 -04:00
parent 3da4b1d861
commit bd97f66097
22 changed files with 7055 additions and 37708 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15958
doc/DataFlow.eps
View File

File diff suppressed because it is too large Load Diff

7265
doc/DistributionSystem.eps
View File

File diff suppressed because it is too large Load Diff

2978
doc/Doxyfile-chm Normal file
View File

File diff suppressed because it is too large Load Diff

2
doc/DoxygenLayout.xml
View File

@@ -4,7 +4,7 @@
<navindex>
<tab type="mainpage" visible="yes" title=""/>
<tab type="pages" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="API Reference"
<tab type="topics" 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=""/>

5118
doc/Example2.eps
View File

File diff suppressed because it is too large Load Diff

8420
doc/Network.eps
View File

File diff suppressed because it is too large Load Diff

1556
doc/doxyfile
View File

File diff suppressed because it is too large Load Diff

2681
doc/doxygen-awesome.css Normal file
View File

File diff suppressed because it is too large Load Diff

2
doc/extrastylesheet.css
View File

@@ -1,2 +0,0 @@
h1 { font-size:1.5em; }

12
doc/footer.tex
View File

@@ -1,12 +0,0 @@
% Latex footer for doxygen 1.8.10
%--- End generated contents ---
% Index
\backmatter
\newpage
\phantomsection
\clearemptydoublepage
\addcontentsline{toc}{chapter}{Index}
\printindex
\end{document}

141
doc/header.tex
View File

@@ -1,141 +0,0 @@
% Latex header for doxygen 1.8.10
\documentclass[twoside]{book}
% Packages required by doxygen
\usepackage{fixltx2e}
\usepackage{calc}
\usepackage{doxygen}
\usepackage[export]{adjustbox} % also loads graphicx
\usepackage{graphicx}
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\usepackage{multicol}
\usepackage{multirow}
\PassOptionsToPackage{warn}{textcomp}
\usepackage{textcomp}
\usepackage[nointegrals]{wasysym}
\usepackage[table]{xcolor}
% Font selection
\usepackage[T1]{fontenc}
\usepackage[scaled=.90]{helvet}
\usepackage{courier}
\usepackage{amssymb}
\usepackage{sectsty}
\renewcommand{\familydefault}{\sfdefault}
\allsectionsfont{%
\fontseries{bc}\selectfont%
\color{darkgray}%
}
\renewcommand{\DoxyLabelFont}{%
\fontseries{bc}\selectfont%
\color{darkgray}%
}
\newcommand{\+}{\discretionary{\mbox{\scriptsize$\hookleftarrow$}}{}{}}
% Page & text layout
\usepackage{geometry}
\geometry{%
a4paper,%
top=2.5cm,%
bottom=2.5cm,%
left=2.5cm,%
right=2.5cm%
}
\tolerance=750
\hfuzz=15pt
\hbadness=750
\setlength{\emergencystretch}{15pt}
\setlength{\parindent}{0cm}
\setlength{\parskip}{0.2cm}
\makeatletter
\renewcommand{\paragraph}{%
\@startsection{paragraph}{4}{0ex}{-1.0ex}{1.0ex}{%
\normalfont\normalsize\bfseries\SS@parafont%
}%
}
\renewcommand{\subparagraph}{%
\@startsection{subparagraph}{5}{0ex}{-1.0ex}{1.0ex}{%
\normalfont\normalsize\bfseries\SS@subparafont%
}%
}
\makeatother
% Headers & footers
\usepackage{fancyhdr}
\pagestyle{fancyplain}
\fancyhead[LE]{\fancyplain{}{\bfseries\thepage}}
\fancyhead[CE]{\fancyplain{}{}}
\fancyhead[RE]{\fancyplain{}{\bfseries\leftmark}}
\fancyhead[LO]{\fancyplain{}{\bfseries\rightmark}}
\fancyhead[CO]{\fancyplain{}{}}
\fancyhead[RO]{\fancyplain{}{\bfseries\thepage}}
\fancyfoot[LE]{\fancyplain{}{}}
\fancyfoot[CE]{\fancyplain{}{}}
\fancyfoot[RE]{\fancyplain{}{\bfseries\scriptsize OWA-EPANET 2.2 \textcopyright 2019}}
\fancyfoot[LO]{\fancyplain{}{\bfseries\scriptsize OWA-EPANET 2.2 \textcopyright 2019}}
\fancyfoot[CO]{\fancyplain{}{}}
\fancyfoot[RO]{\fancyplain{}{}}
\renewcommand{\footrulewidth}{0.4pt}
\renewcommand{\chaptermark}[1]{%
\markboth{#1}{}%
}
\renewcommand{\sectionmark}[1]{%
\markright{\thesection\ #1}%
}
% Indices & bibliography
\usepackage{natbib}
\usepackage[titles]{tocloft}
\setcounter{tocdepth}{1}
\setcounter{secnumdepth}{5}
\makeindex
% Hyperlinks (required, but should be loaded last)
\usepackage{ifpdf}
\ifpdf
\usepackage[pdftex,pagebackref=true]{hyperref}
\else
\usepackage[ps2pdf,pagebackref=true]{hyperref}
\fi
\hypersetup{%
colorlinks=true,%
linkcolor=blue,%
citecolor=blue,%
unicode%
}
% Custom commands
\newcommand{\clearemptydoublepage}{%
\newpage{\pagestyle{empty}\cleardoublepage}%
}
%===== C O N T E N T S =====
\begin{document}
% Titlepage & ToC
\hypersetup{pageanchor=false,
bookmarks=true,
bookmarksnumbered=true,
pdfencoding=unicode
}
\pagenumbering{roman}
\begin{titlepage}
\vspace*{7cm}
\begin{center}%
{\Large OWA-EPANET Toolkit\linebreak\linebreak 2.2}\\
\vspace*{1cm}
{\large January 2019}\\
%\vspace*{0.5cm}
%{\small Wed Jan 23 2019 17:57:36}\\
\end{center}
\end{titlepage}
\clearemptydoublepage
\tableofcontents
\clearemptydoublepage
\pagenumbering{arabic}
\hypersetup{pageanchor=true}
%--- Begin generated contents ---

15
doc/main.dox
View File

@@ -6,7 +6,6 @@ EPANET is a program that performs extended period simulation of hydraulic and wa
<table style = "border: 0px solid black">
<tr><td style="vertical-align: top">
@image html DistributionSystem.png
@image latex DistributionSystem.eps
</td></tr>
</table>
@@ -17,6 +16,7 @@ The OWA-EPANET Toolkit is an open-source version of the original EPANET Toolkit
- allowing networks to be built completely from function calls instead of from an input file
- allowing multiple projects to be analyzed in parallel in a thread-safe manner
- adding the ability to use pressure dependent demands in hydraulic analyses
- adding the ability to model fixed and variable area leakage in pipes
- 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.
@@ -25,7 +25,7 @@ Before using the OWA-EPANET Toolkit one should be familiar with the way that EPA
- @subpage DataFlow "Data Flow Diagram"
- @subpage ToolkitVersions "Toolkit Versions"
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://epanet22.readthedocs.io/en/latest/index.html">EPANET 2 Users Manual</a>.
__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. Its activities and code projects are neither affiliated with nor endorsed by the USEPA.
*/
@@ -38,7 +38,6 @@ EPANET models a pipe network as a collection of links connected to nodes. The li
<table style = "border: 0px solid black">
<tr><td>
@image html Network.png
@image latex Network.eps
</td></tr>
</table>
@@ -59,15 +58,14 @@ being taken and if false result in a different set of actions being taken
An EPANET model also contains a number of analysis options that specify:
- the project's flow units which in turn determines its unit system (US or SI)
- the formula used to compute head loss
- the formula used to compute pipe head loss as a function of flow rate
- whether to use a demand driven or a pressure driven analysis
- hydraulic convergence criteria
- hydraulic convergence criteria and water quality tolerances
- time steps used for hydraulic, water quality and reporting
- the type of water quality analysis to perform (chemical reaction, source tracing or water age)
- global values for chemical reaction coefficients that can be overridden for individual pipes
- global values for energy usage parameters that can be overridden for individual pumps.
Please refer to the <a href="https://nepis.epa.gov/Adobe/PDF/P1007WWU.pdf">EPANET 2 Users Manual</a>
Please refer to the <a href="https://epanet22.readthedocs.io/en/latest/index.html">EPANET 2 Users Manual</a>
for more information on EPANET's data model.
*/
@@ -79,7 +77,6 @@ The EPANET Toolkit contains separate code modules for network building, hydrauli
<table style = "border: 0px solid black">
<tr><td>
@image html DataFlow.png
@image latex DataFlow.eps
</td></tr>
</table>
@@ -104,7 +101,7 @@ with single threaded applications.
analyzed concurrently.
Both Toolkit versions utilize identical function names and argument lists with the following exceptions:
- The `#include "epanet2.h"` directive must appear in all C/C++ code modules that use the single-threaded library while `#include "epanet2_2.h"` must be used for the multi-threaded library.
- The <b>`#include epanet2.h`</b> directive must appear in all C/C++ code modules that use the single-threaded library while <b>`#include epanet2_2.h`</b> must be used for the multi-threaded library. (The "_2" portion of the latter file's name means it is the second of two header files provided and is not a minor release number.)
- 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

2
doc/newfooter.html
View File

@@ -4,7 +4,7 @@
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
$navpath
<!-- <li class="footer">OWA-EPANET Toolkit 2.2 &copy 2019</li> -->
<!-- <li class="footer">OWA-EPANET Toolkit 2.3 &copy 2019</li> -->
</ul>
</div>
<!--END GENERATE_TREEVIEW-->

30
doc/readme.md
View File

@@ -1,30 +1,28 @@
## Generating Documentation for OWA-EPANET 2.2
## Generating Documentation for OWA-EPANET 2.3
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.
You must have [Doxygen](http://www.doxygen.nl) version 1.13 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.
To generate a Windows compiled HTML Help file you must have [Microsoft's HTML Help Workshop](http://web.archive.org/web/20160201063255/http://download.microsoft.com/download/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe) installed. Then follow these steps:
1. Open a terminal window and navigate to the project's `doc` directory.
2. Edit the configuration file `Doxyfile-chm` by entering the location where the Help Workshop system was installed next to the `HHC_LOCATION` setting.
3. Issue the command `doxygen Doxyfile-chm` to generate a compiled Help file named `owa-epanet.chm` in the `doc` directory.
4. You can delete the `html-chm` sub-directory created by Doxygen.
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-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-input.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.
- `toolkit-topics.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.
- `Doxyfile`: the Doxygen configuration file for HTML output
- `Doxyfile-chm`: the Doxygen configuration file for HTML Help output
- `DoxygenLayout.xml`: sets the title of the automatically generated *Topics* section to *API Reference* and hides the *Files* section in the tree view pane of the document.
- `doxygen-awsome.css`: applies a custom theme provided by [doxygen-awesome](https://github.com/jothepro/doxygen-awesome-css) to produce a more modern visual style for HTML output.
- `newfooter.html`: replaces the default Doxygen footer in HTML output with a custom one.

1
doc/toolkit-examples.dox
View File

@@ -47,7 +47,6 @@ 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>

3
doc/toolkit-files.dox
View File

@@ -157,7 +157,8 @@ Developers need to issue an include directive for either `epanet2.h` or `epanet2
Several additional function declaration files that provide bindings for other programming languages are included with the Toolkit package:
- <b>`epanet2.bas`</b> for Visual Basic for Applications and Visual Basic 6
- <b>`epanet2.vb`</b> for Visual Basic .NET
- <b>`epanet2.pas`</b> for Delphi Pascal, Free Pascal or Lazarus.
- <b>`epanet2.pas`</b> for Delphi Pascal, Free Pascal or Lazarus.
- <b>`epanet2.cs`</b> for C#
These bindings only support the single-threaded version of the Toolkit.
*/

70
doc/input-file.dox → doc/toolkit-input.dox
View File

@@ -9,11 +9,12 @@ The file is organized by sections where each section begins with a keyword enclo
|@subpage TitlePage "[Title]" |@subpage CurvesPage "[Curves]" |@subpage QualPage "[Quality]" |@subpage OptionsPage "[Options]"|@subpage BackdropPage "[Backdrop]" |
|@subpage JuncsPage "[Junctions]"|@subpage PatsPage "[Patterns]" |@subpage ReactsPage "[Reactions]"|@subpage TimesPage "[Times]" |@subpage CoordsPage "[Coordinates]" |
|@subpage ResvPage "[Reservoirs]"|@subpage EnergyPage "[Energy]" |@subpage SourcesPage "[Sources]" |@subpage ReportPage "[Report]" |@subpage VertexPage "[Vertices]" |
|@subpage TanksPage "[Tanks]" |@subpage StatusPage "[Status]" |@subpage MixingPage "[Mixing]" | |@subpage LabelsPage "[Labels]" |
|@subpage TanksPage "[Tanks]" |@subpage StatusPage "[Status]" |@subpage MixingPage "[Mixing]" |@subpage TagsPage "[Tags]" |@subpage LabelsPage "[Labels]" |
|@subpage PipesPage "[Pipes]" |@subpage CtrlsPage "[Controls]" | | | |
|@subpage PumpsPage "[Pumps]" |@subpage RulesPage "[Rules]" | | | |
|@subpage ValvesPage "[Valves]" |@subpage DmndsPage "[Demands]" | | | |
|@subpage EmitsPage "[Emitters]" | | | | |
|@subpage EmitsPage "[Emitters]" |@subpage LeaksPage "[Leakage]" | | | |
The order of sections is not important. However, whenever a node or link is referred to in a section it must have already been defined in the [JUNCTIONS], [RESERVOIRS], [TANKS], [PIPES], [PUMPS], or [VALVES] sections. Thus it is recommended that these sections be placed first.
@@ -40,7 +41,7 @@ One line for each control which can be of the form:
<b>&nbsp;&nbsp; LINK</b> _linkID_ &nbsp; _status_ &nbsp;<b> AT TIME&nbsp;</b> _time_
<b>&nbsp;&nbsp; LINK</b> _linkID_ &nbsp; _status_ &nbsp;<b> AT CLOCKTIME</b> _clocktime_ &nbsp;<b> AM / PM</b>
<b>&nbsp;&nbsp; LINK</b> _linkID_ &nbsp; _status_ &nbsp;<b> AT CLOCKTIME</b> _clocktime_
where:
<table style = "border: 0px solid black">
@@ -54,7 +55,8 @@ where:
__Remarks:__
1. Simple controls are used to change link status or settings based on tank water level, junction pressure, time into the simulation or time of day.
2. See the notes for the @ref StatusPage section for conventions used in specifying link status and setting, particularly for control valves.
2. See the notes for the @ref StatusPage section for conventions used in specifying link status and setting, particularly for control valves.
3. Adding the keyword <b>DISABLED</b> at the end of a control statement will indicate that the control is disabled and will not be applied.
__Examples:__
@@ -65,8 +67,8 @@ LINK 12 CLOSED IF NODE 23 ABOVE 20
;Open Link 12 if the pressure at Node 130 is under 30 psi<br>
LINK 12 OPEN IF NODE 130 BELOW 30
;Pump PUMP02's speed is set to 1.5 at 16 hours into the simulation<br>
LINK PUMP02 1.5 AT TIME 16
;Disable setting Pump PUMP02's speed to 1.5 at 16 hours into the simulation<br>
LINK PUMP02 1.5 AT TIME 16 DISABLED
;Link 12 is closed at 10 am and opened at 8 pm throughout the simulation<br>
LINK 12 CLOSED AT CLOCKTIME 10 AM<br>
@@ -235,6 +237,26 @@ J3 115 ;No demand at this junction
```
*/
/**
@page LeaksPage [LEAKAGE]
__Purpose:__
Assigns leakage parameters to individual pipes.
__Format:__
A line for each pipe subject to leaking that contains:
- Pipe ID label
- the area of cracks that leak in sq. mm per 100 units of pipe length (ft or m)
- the rate at which cracks expand in sq. mm per unit of pressure head (ft or m)
__Remarks__
1. This section is optional.
2. Leak area is the total area of all cracks assumed to exist per 100 feet (or meters) of pipe.
3. Experimental values of expansion range between 0 and 0.001 (sq mm)/m depending on pipe material and crack size.
*/
/**
@page MixingPage [MIXING]
@@ -904,6 +926,38 @@ __Example:__
@endcode
*/
/**
@page TagsPage [TAGS]
__Purpose:__
Associates category labels (tags) with specific nodes and links.
__Format:__
One line for each node and link with a tag containing:
- the keyword <b>NODE</b> or <b>LINK</b>
- the node or link ID label
- the text of the tag label (with no spaces)
__Remarks:__
1. Tags can be useful for assigning nodes to different pressure zones or for classifying pipes by material or age.
2. If a node or link’s tag is not identified in this section then it is assumed to be blank.
3. The [TAGS] section is optional and has no effect on the hydraulic or water quality calculations.
__Example:__
@code
[TAGS]
;Object ID Tag
;------------------------------
NODE 1001 Zone_A
NODE 1002 Zone_A
NODE 45 Zone_B
LINK 201 UNCI-1960
LINK 202 PVC-1985
@endcode
*/
/**
@page TanksPage [TANKS]
@@ -1048,11 +1102,11 @@ __Remarks:__
|<B>PBV</B> (pressure breaker valve) | Pressure, psi (m) |
|<B>FCV</B> (flow control valve) | Flow (flow units) |
|<B>TCV</B> (throttle control valve) | Partially open loss coefficient |
|<B>PCV</B> (positional control valve) | Fraction open |
|<B>PCV</B> (positional control valve) | Percent open |
|<B>GPV</B> (general purpose valve) | ID of head loss curve |
2. Shutoff valves and check valves are considered to be part of a pipe, not a separate control valve component (see @ref PipesPage).
3. The loss coefficient setting for a TCV should not be less than its fully open loss coefficient.
4. The characteristic curve for a PCV relates the valve's fraction of fully open flow to the fraction open. If not supplied then a linear curve is assumed.
4. The characteristic curve for a PCV relates the valve's percent of fully open flow to the percent open. If not supplied then a linear curve is assumed.
5. The partially opened loss coefficient for a PCV is the inverse of the squared value from its characteristic curve times the fully open loss coefficient.
6. The head loss curve for a GPV relates head loss across the valve to the flow rate through it.
*/

183
doc/modules.dox → doc/toolkit-topics.dox
View File

@@ -71,9 +71,14 @@ These are the toolkit's enumerated types whose members are used as function argu
@fn int EN_runproject(EN_Project ph, const char *f1, const char *f2, const char *f3, void (*pviewprog)(char *))
@fn int EN_init(EN_Project ph, const char *rptFile, const char *outFile, int unitsType, int headLossType)
@fn int EN_open(EN_Project ph, const char *inpFile, const char *rptFile, const char *binOutFile)
@fn int EN_openX(EN_Project ph, const char *inpFile, const char *rptFile, const char *binOutFile)
@fn int EN_getcount(EN_Project ph, int code, int *count)
@fn int EN_gettitle(EN_Project ph, char *line1, char *line2, char *line3)
@fn int EN_settitle(EN_Project ph, char *line1, char *line2, char *line3)
@fn int EN_settitle(EN_Project ph, const char *line1, const char *line2, const char *line3)
@fn int EN_getcomment(EN_Project ph, int object, int index, char *comment)
@fn int EN_setcomment(EN_Project ph, int object, int index, const char *comment)
@fn int EN_gettag(EN_Project ph, int object, int index, char *tag)
@fn int EN_settag(EN_Project ph, int object, int index, const char *tag)
@fn int EN_saveinpfile(EN_Project ph, const char *filename)
@fn int EN_close(EN_Project ph)
@}
@@ -110,17 +115,18 @@ These are the toolkit's enumerated types whose members are used as function argu
/**
@addtogroup Reporting
@{
@fn int EN_writeline(EN_Project ph, char *line)
@fn int EN_writeline(EN_Project ph, const char *line)
@fn int EN_report(EN_Project ph)
@fn int EN_copyreport(EN_Project ph, char *filename)
@fn int EN_copyreport(EN_Project ph, const char *filename)
@fn int EN_clearreport(EN_Project ph)
@fn int EN_resetreport(EN_Project ph)
@fn int EN_setreport(EN_Project ph, char *reportFormat)
@fn int EN_setreport(EN_Project ph, const char *reportFormat)
@fn int EN_setstatusreport(EN_Project ph, int code)
@fn int EN_getversion(int *version)
@fn int EN_geterror(int errcode, char *errmsg, int maxLen)
@fn int EN_getstatistic(EN_Project ph, int type, double* value)
@fn int EN_getresultindex(EN_Project ph, int type, int index, int *value)
@fn int EN_timetonextevent(EN_Project ph, int *eventType, long *duration, int *elementIndex);
@}
*/
@@ -128,7 +134,7 @@ These are the toolkit's enumerated types whose members are used as function argu
/**
@addtogroup Options
@{
@fn int EN_getoption(EN_Project ph, int option, double *value)
@fn int EN_getoption(EN_Project ph, int option, double *out_value)
@fn int EN_setoption(EN_Project ph, int option, double value)
@fn int EN_getflowunits(EN_Project ph, int *units)
@fn int EN_setflowunits(EN_Project ph, int units)
@@ -136,67 +142,66 @@ These are the toolkit's enumerated types whose members are used as function argu
@fn int EN_settimeparam(EN_Project ph, int param, long value)
@fn int EN_getqualinfo(EN_Project ph, int *qualType, char *chemName, char *chemUnits, int *traceNode)
@fn int EN_getqualtype(EN_Project ph, int *qualType, int *traceNode)
@fn int EN_setqualtype(EN_Project ph, int qualType, char *chemName, char *chemUnits, char *traceNode)
@fn int EN_setqualtype(EN_Project ph, int qualType, const char *chemName, const char *chemUnits, const char *traceNode)
@}
*/
/**
@addtogroup Nodes
/** \addtogroup Nodes
@{
@fn int EN_addnode(EN_Project ph, char *id, int nodeType, int *index)
@fn int EN_addnode(EN_Project ph, const char *id, int nodeType, int *out_index)
@fn int EN_deletenode(EN_Project ph, int index, int actionCode)
@fn int EN_getnodeindex(EN_Project ph, char *id, int *index)
@fn int EN_getnodeid(EN_Project ph, int index, char *id)
@fn int EN_setnodeid(EN_Project ph, int index, char *newid)
@fn int EN_getnodetype(EN_Project ph, int index, int *code)
@fn int EN_getnodevalue(EN_Project ph, int index, int code, double *value)
@fn int EN_setnodevalue(EN_Project ph, int index, int code, double v)
@fn int EN_setjuncdata(EN_Project ph, int index, double elev, double dmnd, char *dmndpat)
@fn int EN_settankdata(EN_Project ph, int index, double elev, double initlvl,
double minlvl, double maxlvl, double diam, double minvol, char *volcurve)
@fn int EN_getcoord(EN_Project ph, int index, double *x, double *y)
@fn int EN_getnodeindex(EN_Project ph, const char *id, int *out_index)
@fn int EN_getnodeid(EN_Project ph, int index, char *out_id)
@fn int EN_setnodeid(EN_Project ph, int index, const char *newid)
@fn int EN_getnodetype(EN_Project ph, int index, int *out_nodeType)
@fn int EN_getnodevalue(EN_Project ph, int index, int property, double *out_value)
@fn int EN_getnodevalues(EN_Project ph, int property, double *out_values)
@fn int EN_setnodevalue(EN_Project ph, int index, int property, double value)
@fn int EN_setjuncdata(EN_Project ph, int index, double elev, double dmnd, const char *dmndpat)
@fn int EN_settankdata(EN_Project ph, int index, double elev, double initlvl, double minlvl, double maxlvl, double diam, double minvol, const char *volcurve)
@fn int EN_getcoord(EN_Project ph, int index, double *out_x, double *out_y)
@fn int EN_setcoord(EN_Project ph, int index, double x, double y)
@}
*/
@}*/
/**
@addtogroup Demands
@{
@fn int EN_getdemandmodel(EN_Project ph, int *type, double *pmin, double *preq, double *pexp)
@fn int EN_setdemandmodel(EN_Project ph, int type, double pmin, double preq, double pexp)
@fn int EN_adddemand(EN_Project ph, int nodeIndex, double baseDemand, char *demandPattern, char *demandName)
@fn int EN_adddemand(EN_Project ph, int nodeIndex, double baseDemand, const char *demandPattern, const char *demandName)
@fn int EN_deletedemand(EN_Project ph, int nodeIndex, int demandIndex)
@fn int EN_getdemandindex(EN_Project p, int nodeIndex, char *demandName, int *demandIndex)
@fn int EN_getdemandindex(EN_Project p, int nodeIndex, const char *demandName, int *demandIndex)
@fn int EN_getnumdemands(EN_Project ph, int nodeIndex, int *numDemands)
@fn int EN_getbasedemand(EN_Project ph, int nodeIndex, int demandIndex, double *baseDemand)
@fn int EN_setbasedemand(EN_Project ph, int nodeIndex, int demandIndex, double baseDemand)
@fn int EN_getdemandpattern(EN_Project ph, int nodeIndex, int demandIndex, int *pattIndex)
@fn int EN_setdemandpattern(EN_Project ph, int nodeIndex, int demandIndex, int patIndex)
@fn int EN_getdemandname(EN_Project ph, int nodeIndex, int demandIdx, char *demandName)
@fn int EN_setdemandname(EN_Project ph, int nodeIndex, int demandIdx, char *demandName)
@fn int EN_setdemandname(EN_Project ph, int nodeIndex, int demandIdx, const char *demandName)
@}
*/
/**
@addtogroup Links
@{
@fn int EN_addlink(EN_Project ph, char *id, int linkType, char *fromNode, char *toNode, int *index)
@fn int EN_addlink(EN_Project ph, char *id, int linkType, const char *fromNode, const char *toNode, int *out_index)
@fn int EN_deletelink(EN_Project ph, int index, int actionCode)
@fn int EN_getlinkindex(EN_Project ph, char *id, int *index)
@fn int EN_getlinkindex(EN_Project ph, const char *id, int *out_index)
@fn int EN_getlinkid(EN_Project ph, int index, char *id)
@fn int EN_setlinkid(EN_Project ph, int index, char *newid)
@fn int EN_getlinktype(EN_Project ph, int index, int *linkType)
@fn int EN_setlinkid(EN_Project ph, int index, const char *newid)
@fn int EN_getlinktype(EN_Project ph, int index, int *out_linkType)
@fn int EN_setlinktype(EN_Project ph, int *index, int linkType, int actionCode)
@fn int EN_getlinknodes(EN_Project ph, int index, int *node1, int *node2)
@fn int EN_getlinknodes(EN_Project ph, int index, int *out_node1, int *out_node2)
@fn int EN_setlinknodes(EN_Project ph, int index, int node1, int node2)
@fn int EN_getlinkvalue(EN_Project ph, int index, int property, double *value)
@fn int EN_getlinkvalue(EN_Project ph, int index, int property, double *out_value)
@fn int EN_getlinkvalues(EN_Project ph, int property, double *out_values)
@fn int EN_setlinkvalue(EN_Project ph, int index, int property, double value)
@fn int EN_setpipedata(EN_Project ph, int index, double length, double diam, double rough, double mloss)
@fn int EN_getpumptype(EN_Project ph, int linkIndex, int *pumpType)
@fn int EN_getheadcurveindex(EN_Project ph, int pumpIndex, int *curveIndex)
@fn int EN_getpumptype(EN_Project ph, int linkIndex, int *out_pumpType)
@fn int EN_getheadcurveindex(EN_Project ph, int pumpIndex, int *out_curveIndex)
@fn int EN_setheadcurveindex(EN_Project ph, int pumpIndex, int curveIndex)
@fn int EN_getvertexcount(EN_Project ph, int index, int *count)
@fn int EN_getvertex(EN_Project ph, int index, int vertex, double *x, double *y)
@fn int EN_getvertexcount(EN_Project ph, int index, int *out_count)
@fn int EN_getvertex(EN_Project ph, int index, int vertex, double *out_x, double *out_y)
@fn int EN_setvertex(EN_Project ph, int index, int vertex, double x, double y)
@fn int EN_setvertices(EN_Project ph, int index, double *x, double *y, int count)
@}
@@ -205,33 +210,34 @@ These are the toolkit's enumerated types whose members are used as function argu
/**
@addtogroup Patterns
@{
@fn int EN_addpattern(EN_Project ph, char *id)
@fn int EN_addpattern(EN_Project ph, const char *id)
@fn int EN_deletepattern(EN_Project ph, int index)
@fn int EN_getpatternindex(EN_Project ph, char *id, int *index)
@fn int EN_getpatternindex(EN_Project ph, char *id, int *out_index)
@fn int EN_getpatternid(EN_Project ph, int index, char *id)
@fn int EN_setpatternid(EN_Project ph, int index, char *id)
@fn int EN_getpatternlen(EN_Project ph, int index, int *len)
@fn int EN_getpatternvalue(EN_Project ph, int index, int period, double *value)
@fn int EN_setpatternid(EN_Project ph, int index, const char *id)
@fn int EN_getpatternlen(EN_Project ph, int index, int *out_len)
@fn int EN_getpatternvalue(EN_Project ph, int index, int period, double *out_value)
@fn int EN_setpatternvalue(EN_Project ph, int index, int period, double value)
@fn int EN_getaveragepatternvalue(EN_Project ph, int index, double *value)
@fn int EN_getaveragepatternvalue(EN_Project ph, int index, double *out_value)
@fn int EN_setpattern(EN_Project ph, int index, double *f, int len)
@fn int EN_loadpatternfile(EN_Project ph, const char *filename, const char *id)
@}
*/
/**
@addtogroup Curves
@{
@fn int EN_addcurve(EN_Project ph, char *id)
@fn int EN_addcurve(EN_Project ph, const char *id)
@fn int EN_deletecurve(EN_Project ph, int index)
@fn int EN_getcurveindex(EN_Project ph, char *id, int *index)
@fn int EN_getcurveid(EN_Project ph, int index, char *id)
@fn int EN_setcurveid(EN_Project ph, int index, char *id)
@fn int EN_getcurvelen(EN_Project ph, int index, int *len)
@fn int EN_getcurvetype(EN_Project ph, int index, int *type)
@fn int EN_getcurveindex(EN_Project ph, const char *id, int *out_index)
@fn int EN_getcurveid(EN_Project ph, int index, char *out_id)
@fn int EN_setcurveid(EN_Project ph, int index, const char *id)
@fn int EN_getcurvelen(EN_Project ph, int index, int *out_len)
@fn int EN_getcurvetype(EN_Project ph, int index, int *out_type)
@fn int EN_setcurvetype(EN_Project ph, int index, int type)
@fn int EN_getcurvevalue(EN_Project ph, int curveIndex, int pointIndex, double *x, double *y)
@fn int EN_getcurvevalue(EN_Project ph, int curveIndex, int pointIndex, double *out_x, double *out_y)
@fn int EN_setcurvevalue(EN_Project ph, int curveIndex, int pointIndex, double x, double y)
@fn int EN_getcurve(EN_Project ph, int curveIndex, char* id, int *nPoints, double **xValues, double **yValues)
@fn int EN_getcurve(EN_Project ph, int index, char *out_id, int *out_nPoints, double *out_xValues, double *out_yValues)
@fn int EN_setcurve(EN_Project ph, int index, double *xValues, double *yValues, int nPoints)
@}
*/
@@ -239,10 +245,12 @@ These are the toolkit's enumerated types whose members are used as function argu
/**
@addtogroup Controls
@{
@fn int EN_addcontrol(EN_Project ph, int type, int linkIndex, double setting, int nodeIndex, double level, int *index)
@fn int EN_addcontrol(EN_Project ph, int type, int linkIndex, double setting, int nodeIndex, double level, int *out_index)
@fn int EN_deletecontrol(EN_Project ph, int index)
@fn int EN_getcontrol(EN_Project ph, int index, int *type, int *linkIndex, double *setting, int *nodeIndex, double *level)
@fn int EN_getcontrol(EN_Project ph, int index, int *out_type, int *out_linkIndex, double *out_setting, int *out_nodeIndex, double *out_level)
@fn int EN_setcontrol(EN_Project ph, int index, int type, int linkIndex, double setting, int nodeIndex, double level)
@fn int EN_getcontrolenabled(EN_Project ph, int index, int *out_enabled)
@fn int EN_setcontrolenabled(EN_Project ph, int index, int enabled)
@}
*/
@@ -265,43 +273,50 @@ These are the toolkit's enumerated types whose members are used as function argu
@fn int EN_getelseaction(EN_Project ph, int ruleIndex, int actionIndex, int *linkIndex, int *status, double *setting)
@fn int EN_setelseaction(EN_Project ph, int ruleIndex, int actionIndex, int linkIndex, int status, double setting)
@fn int EN_setrulepriority(EN_Project ph, int index, double priority)
@fn int EN_getruleenabled(EN_Project ph, int index, int *out_enabled)
@fn int EN_setruleenabled(EN_Project ph, int index, int enabled)
@}
*/
/**
@addtogroup Enumerations
@{
\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
\enum EN_ControlType
\enum EN_HeadLossType
\enum EN_NodeProperty
\enum EN_LinkProperty
\enum EN_LinkStatusType
\enum EN_TimeParameter
\enum EN_Option
\enum EN_FlowUnits
\enum EN_PressUnits
\enum EN_DemandModel
\enum EN_MixingModel
\enum EN_StatisticType
\enum EN_InitHydOption
\enum EN_ActionCodeType
\enum EN_AnalysisStatistic
\enum EN_StatusReport
\enum EN_RuleObject
\enum EN_RuleVariable
\enum EN_RuleOperator
\enum EN_RuleStatus
\typedef EN_SizeLimits
\typedef EN_ObjectType
\typedef EN_CountType
\typedef EN_NodeType
\typedef EN_LinkType
\typedef EN_PumpType
\typedef EN_PumpStateType
\typedef EN_CurveType
\typedef EN_QualityType
\typedef EN_SourceType
\typedef EN_ControlType
\typedef EN_HeadLossType
\typedef EN_NodeProperty
\typedef EN_LinkProperty
\typedef EN_LinkStatusType
\typedef EN_TimeParameter
\typedef EN_TimestepEvent
\typedef EN_Option
\typedef EN_FlowUnits
\typedef EN_PressUnits
\typedef EN_DemandModel
\typedef EN_MixingModel
\typedef EN_StatisticType
\typedef EN_InitHydOption
\typedef EN_ActionCodeType
\typedef EN_AnalysisStatistic
\typedef EN_StatusReport
\typedef EN_RuleObject
\typedef EN_RuleVariable
\typedef EN_RuleOperator
\typedef EN_RuleStatus
\def EN_MISSING
\def EN_SET_CLOSED
\def EN_SET_OPEN
\def EN_FALSE
\def EN_TRUE
@}
*/
@@ -349,19 +364,25 @@ These are the toolkit's enumerated types whose members are used as function argu
| 226 | No head curve or power rating for pump |
| 227 | Invalid head curve for pump |
| 230 | Nonincreasing x-values for curve |
| 233 | Network has unconnected node |
| 231 | No data provided for a curve |
| 232 | No data provided for a pattern |
| 233 | Network has unconnected nodes |
| 240 | Function call refers to nonexistent water quality source |
| 241 | Function call refers to nonexistent control |
| 250 | Function call contains invalid format (e.g. too long an ID name) |
| 251 | Function call contains invalid parameter code |
| 252 | Function call rferes to an invalid ID name |
| 253 | Function call refers to nonexistent demand category |
| 254 | Function call refers to node with no coordinates |
| 255 | Function call refers to link with no vertices |
| 257 | Function call refers to nonexistent rule |
| 258 | Function call refers to nonexistent rule clause |
| 259 | Function call attempts to delete a node that still has links connected to it |
| 260 | Function call attempts to delete node assigned as a Trace Node |
| 261 | Function call attempts to delete a node or link contained in a control |
| 262 | Function call attempts to modify network structure while a solver is open |
| 263 | Function call refers to node that is not a tank |
| 299 | An invalid section keyword was detected in an input file |
| ||
| 301 | Identical file names used for different types of files |
| 302 | Cannot open input file |

32
doc/toolkit-usage.dox
View File

@@ -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 \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:
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;
@@ -76,7 +76,7 @@ See the @ref Example2 for a more complete example. The labels used to name objec
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.
The code below is an example of using the property retrieval and setting functions. It changes all links with diameter of 10 inches to 12 inches.
@@ -177,16 +177,24 @@ int runConcurrentQuality(EN_Project ph)
@section results Retrieving Computed Results
The @ref EN_getnodevalue and @ref EN_getlinkvalue functions can also be used to retrieve the results of hydraulic and water quality simulations. The computed parameters (and their Toolkit codes) that can be retrieved are as follows:
|For Nodes: | For Links: |
|----------------------------------- | ----------------------------------------- |
|\b EN_DEMAND (demand) |\b EN_FLOW (flow rate) |
|\b EN_DEMANDDEFICIT (demand deficit) |\b EN_VELOCITY (flow velocity) |
|\b EN_HEAD (hydraulic head) |\b EN_HEADLOSS (head loss) |
|\b EN_PRESSURE (pressure) |\b EN_STATUS (link status) |
|\b EN_TANKLEVEL (tank water level) |\b EN_SETTING (pump speed or valve setting) |
|\b EN_TANKVOLUME (tank water volume) |\b EN_ENERGY (pump energy usage) |
|\b EN_QUALITY (water quality) |\b EN_PUMP_EFFIC (pump efficiency) |
|\b EN_SOURCEMASS (source mass inflow)| |
|For Nodes: | For Links: |
|------------------------------------ | ----------------------------------------- |
|\b EN_DEMAND (total node outflow |\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) |
| |\b EN_LINK_LEAKAGE (pipe leakage flow rate |
In addition, the following quantities related to a node's outflow can be retrieved:
-# EN_FULLDEMAND (consumer demand requested)
-# EN_DEMANDFLOW (consumer demand delivered)
-# EN_DEMANDDEFICIT (difference between consumer demand requested and delivered)
-# EN_EMITTERFLOW (outflow through a node's emitter)
-# EN_LEAKAGEFLOW (outflow due to leakage in a node's connecting pipes)
where `EN_DEMAND` is the sum of `EN_DEMANDFLOW`, `EN_EMITTERFLOW`, and `EN_LEAKAGEFLOW`.
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}