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

1454
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>

1
doc/toolkit-files.dox
View File

@@ -158,6 +158,7 @@ Several additional function declaration files that provide bindings for other pr
- <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.cs`</b> for C#
These bindings only support the single-threaded version of the Toolkit.
*/

68
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">
@@ -55,6 +56,7 @@ 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.
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 |

30
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.
@@ -178,15 +178,23 @@ 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: |
|----------------------------------- | ----------------------------------------- |
|\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)| |
|------------------------------------ | ----------------------------------------- |
|\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}

240
include/epanet2_2.h
View File

@@ -48,11 +48,11 @@ extern "C" {
*/
typedef struct Project *EN_Project;
/********************************************************************
/*===================================================================
Project Functions
********************************************************************/
===================================================================*/
/**
@brief Creates an EPANET project.
@@ -209,7 +209,7 @@ typedef struct Project *EN_Project;
@brief Retrieves the number of objects of a given type in a project.
@param ph an EPANET project handle.
@param object a type of object to count (see @ref EN_CountType)
@param[out] count number of objects of the specified type
@param[out] out_count number of objects of the specified type
@return an error code
*/
int DLLEXPORT EN_getcount(EN_Project ph, int object, int *out_count);
@@ -233,11 +233,11 @@ typedef struct Project *EN_Project;
*/
int DLLEXPORT EN_close(EN_Project ph);
/********************************************************************
/*===================================================================
Hydraulic Analysis Functions
********************************************************************/
===================================================================*/
/**
@brief Runs a complete hydraulic simulation with results for all time periods
@@ -327,7 +327,7 @@ typedef struct Project *EN_Project;
/**
@brief Computes a hydraulic solution for the current point in time.
@param ph an EPANET project handle.
@param[out] currentTime the current simulation time in seconds.
@param[out] out_currentTime the current simulation time in seconds.
@return an error or warning code.
This function is used in a loop with ::EN_nextH to run an extended period hydraulic
@@ -344,7 +344,7 @@ typedef struct Project *EN_Project;
@brief Determines the length of time until the next hydraulic event occurs in an
extended period simulation.
@param ph an EPANET project handle.
@param[out] tStep the time (in seconds) until the next hydraulic event or 0 if at
@param[out] out_tStep the time (in seconds) until the next hydraulic event or 0 if at
the end of the full simulation duration.
@return an error code.
@@ -413,11 +413,11 @@ typedef struct Project *EN_Project;
*/
int DLLEXPORT EN_closeH(EN_Project ph);
/********************************************************************
/*===================================================================
Water Quality Analysis Functions
********************************************************************/
===================================================================*/
/**
@brief Runs a complete water quality simulation with results at uniform
@@ -473,7 +473,7 @@ typedef struct Project *EN_Project;
@brief Makes hydraulic and water quality results at the start of the current time
period available to a project's water quality solver.
@param ph an EPANET project handle.
@param[out] currentTime current simulation time in seconds.
@param[out] out_currentTime current simulation time in seconds.
@return an error code.
Use ::EN_runQ along with ::EN_nextQ in a loop to access water quality results at the
@@ -493,7 +493,7 @@ typedef struct Project *EN_Project;
/**
@brief Advances a water quality simulation over the time until the next hydraulic event.
@param ph an EPANET project handle.
@param[out] tStep time (in seconds) until the next hydraulic event or 0 if at the end
@param[out] out_tStep time (in seconds) until the next hydraulic event or 0 if at the end
of the full simulation duration.
@return an error code.
@@ -525,7 +525,7 @@ typedef struct Project *EN_Project;
/**
@brief Advances a water quality simulation by a single water quality time step.
@param ph an EPANET project handle.
@param[out] timeLeft time left (in seconds) to the overall simulation duration.
@param[out] out_timeLeft time left (in seconds) to the overall simulation duration.
@return an error code.
This function is used in a loop with ::EN_runQ to perform an extended period water
@@ -550,11 +550,11 @@ typedef struct Project *EN_Project;
*/
int DLLEXPORT EN_closeQ(EN_Project ph);
/********************************************************************
/*===================================================================
Reporting Functions
********************************************************************/
===================================================================*/
/**
@brief Set a user-supplied callback function for reporting
@@ -661,7 +661,7 @@ typedef struct Project *EN_Project;
/**
@brief Retrieves the toolkit API version number.
@param[out] version the version of the OWA-EPANET toolkit.
@param[out] out_version the version of the OWA-EPANET toolkit.
@return an error code.
The version number is to be interpreted with implied decimals, i.e.,
@@ -684,14 +684,14 @@ typedef struct Project *EN_Project;
@brief Retrieves a particular simulation statistic.
@param ph an EPANET project handle.
@param type the type of statistic to retrieve (see @ref EN_AnalysisStatistic).
@param[out] value the value of the statistic.
@param[out] out_value the value of the statistic.
@return an error code
*/
int DLLEXPORT EN_getstatistic(EN_Project ph, int type, double* out_value);
/**
@brief Get information about upcoming time step events, and what causes them.
@brief Gets information about when the next hydraulic time step occurs.
@param ph an EPANET project handle.
@param[out] eventType the type of event that will occur (see @ref EN_TimestepEvent).
@param[out] duration the amount of time in the future this event will occur
@@ -704,7 +704,7 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param type a type of element (either @ref EN_NODE or @ref EN_LINK).
@param index the element's current index (starting from 1).
@param[out] value the order in which the element's results were written to file.
@param[out] out_value the order in which the element's results were written to file.
@return an error code.
If the element does not appear in the file then its result index is 0.
@@ -715,17 +715,17 @@ typedef struct Project *EN_Project;
*/
int DLLEXPORT EN_getresultindex(EN_Project ph, int type, int index, int *out_value);
/********************************************************************
/*===================================================================
Analysis Options Functions
********************************************************************/
===================================================================*/
/**
@brief Retrieves the value of an analysis option.
@param ph an EPANET project handle.
@param option a type of analysis option (see @ref EN_Option).
@param[out] value the current value of the option.
@param[out] out_value the current value of the option.
@return an error code
*/
int DLLEXPORT EN_getoption(EN_Project ph, int option, double *out_value);
@@ -743,7 +743,7 @@ typedef struct Project *EN_Project;
/**
@brief Retrieves a project's flow units.
@param ph an EPANET project handle.
@param[out] units a flow units code (see @ref EN_FlowUnits)
@param[out] out_units a flow units code (see @ref EN_FlowUnits)
@return an error code.
Flow units in liters or cubic meters implies that SI metric units are used for all
@@ -766,7 +766,7 @@ typedef struct Project *EN_Project;
@brief Retrieves the value of a time parameter.
@param ph an EPANET project handle.
@param param a time parameter code (see @ref EN_TimeParameter).
@param[out] value the current value of the time parameter (in seconds).
@param[out] out_value the current value of the time parameter (in seconds).
@return an error code.
*/
int DLLEXPORT EN_gettimeparam(EN_Project ph, int param, long *out_value);
@@ -783,10 +783,10 @@ typedef struct Project *EN_Project;
/**
@brief Gets information about the type of water quality analysis requested.
@param ph an EPANET project handle.
@param[out] qualType type of analysis to run (see @ref EN_QualityType).
@param[out] out_qualType type of analysis to run (see @ref EN_QualityType).
@param[out] out_chemName name of chemical constituent.
@param[out] out_chemUnits concentration units of the constituent.
@param[out] traceNode index of the node being traced (if applicable).
@param[out] out_traceNode index of the node being traced (if applicable).
@return an error code.
*/
int DLLEXPORT EN_getqualinfo(EN_Project ph, int *out_qualType, char *out_chemName,
@@ -795,8 +795,8 @@ typedef struct Project *EN_Project;
/**
@brief Retrieves the type of water quality analysis to be run.
@param ph an EPANET project handle.
@param[out] qualType the type of analysis to run (see @ref EN_QualityType).
@param[out] traceNode the index of node being traced, if <b>qualType = EN_TRACE</b>.
@param[out] out_qualType the type of analysis to run (see @ref EN_QualityType).
@param[out] out_traceNode the index of node being traced, if <b>qualType = EN_TRACE</b>.
@return an error code.
*/
int DLLEXPORT EN_getqualtype(EN_Project ph, int *out_qualType, int *out_traceNode);
@@ -818,18 +818,18 @@ typedef struct Project *EN_Project;
int DLLEXPORT EN_setqualtype(EN_Project ph, int qualType, const char *chemName,
const char *chemUnits, const char *traceNode);
/********************************************************************
/*===================================================================
Node Functions
********************************************************************/
===================================================================*/
/**
@brief Adds a new node to a project.
@param ph an EPANET project handle.
@param id the ID name of the node to be added.
@param nodeType the type of node being added (see @ref EN_NodeType)
@param[out] index the index of the newly added node
@param[out] out_index the index of the newly added node
@return an error code.
When a new node is created all of its properties (see @ref EN_NodeProperty) are set to 0.
@@ -855,7 +855,7 @@ typedef struct Project *EN_Project;
@brief Gets the index of a node given its ID name.
@param ph an EPANET project handle.
@param id a node ID name.
@param[out] index the node's index (starting from 1).
@param[out] out_index the node's index (starting from 1).
@return an error code
*/
int DLLEXPORT EN_getnodeindex(EN_Project ph, const char *id, int *out_index);
@@ -886,7 +886,7 @@ typedef struct Project *EN_Project;
@brief Retrieves a node's type given its index.
@param ph an EPANET project handle.
@param index a node's index (starting from 1).
@param[out] nodeType the node's type (see @ref EN_NodeType).
@param[out] out_nodeType the node's type (see @ref EN_NodeType).
@return an error code.
*/
int DLLEXPORT EN_getnodetype(EN_Project ph, int index, int *out_nodeType);
@@ -896,20 +896,7 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param index a node's index.
@param property the property to retrieve (see @ref EN_NodeProperty).
@param[out] value the current value of the property.
@return an error code.
Values are returned in units that depend on the units used for flow rate
(see @ref Units).
*/
int DLLEXPORT EN_getnodevalues(EN_Project ph, int property, double *out_values);
/**
@brief Retrieves an array of property values for all nodes.
@param ph an EPANET project handle.
@param property the property to retrieve (see @ref EN_NodeProperty).
@param[out] values an array of values for all nodes.
@param[out] out_value the current value of the property.
@return an error code.
Values are returned in units that depend on the units used for flow rate
@@ -918,6 +905,19 @@ typedef struct Project *EN_Project;
int DLLEXPORT EN_getnodevalue(EN_Project ph, int index, int property, double *out_value);
/**
@brief Retrieves an array of property values for all nodes.
@param ph an EPANET project handle.
@param property the property to retrieve (see @ref EN_NodeProperty).
@param[out] out_values an array of values for all nodes.
@return an error code.
Values are returned in units that depend on the units used for flow rate
(see @ref Units).
*/
int DLLEXPORT EN_getnodevalues(EN_Project ph, int property, double *out_values);
/**
@brief Sets a property value for a node.
@param ph an EPANET project handle.
@@ -966,8 +966,8 @@ typedef struct Project *EN_Project;
@brief Gets the (x,y) coordinates of a node.
@param ph an EPANET project handle.
@param index a node index (starting from 1).
@param[out] x the node's X-coordinate value.
@param[out] y the node's Y-coordinate value.
@param[out] out_x the node's X-coordinate value.
@param[out] out_y the node's Y-coordinate value.
@return an error code.
*/
int DLLEXPORT EN_getcoord(EN_Project ph, int index, double *out_x, double *out_y);
@@ -982,19 +982,19 @@ typedef struct Project *EN_Project;
*/
int DLLEXPORT EN_setcoord(EN_Project ph, int index, double x, double y);
/********************************************************************
/*===================================================================
Nodal Demand Functions
********************************************************************/
===================================================================*/
/**
@brief Retrieves the type of demand model in use and its parameters.
@param ph an EPANET project handle.
@param[out] type Type of demand model (see @ref EN_DemandModel).
@param[out] pmin Pressure below which there is no demand.
@param[out] preq Pressure required to deliver full demand.
@param[out] pexp Pressure exponent in demand function.
@param[out] out_type Type of demand model (see @ref EN_DemandModel).
@param[out] out_pmin Pressure below which there is no demand.
@param[out] out_preq Pressure required to deliver full demand.
@param[out] out_pexp Pressure exponent in demand function.
@return an error code.
Parameters <b>pmin, preq,</b> and \b pexp are only used when the demand model is \b EN_PDA.
@@ -1054,7 +1054,7 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param nodeIndex the index of a node (starting from 1)
@param demandName the name of a demand category for the node
@param[out] demandIndex the index of the demand being sought
@param[out] out_demandIndex the index of the demand being sought
@return an error code
*/
int DLLEXPORT EN_getdemandindex(EN_Project ph, int nodeIndex, const char *demandName,
@@ -1064,7 +1064,7 @@ typedef struct Project *EN_Project;
@brief Retrieves the number of demand categories for a junction node.
@param ph an EPANET project handle.
@param nodeIndex the index of a node (starting from 1).
@param[out] numDemands the number of demand categories assigned to the node.
@param[out] out_numDemands the number of demand categories assigned to the node.
@return an error code.
*/
int DLLEXPORT EN_getnumdemands(EN_Project ph, int nodeIndex, int *out_numDemands);
@@ -1074,7 +1074,7 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param nodeIndex a node's index (starting from 1).
@param demandIndex the index of a demand category for the node (starting from 1).
@param[out] baseDemand the category's base demand.
@param[out] out_baseDemand the category's base demand.
@return an error code.
*/
int DLLEXPORT EN_getbasedemand(EN_Project ph, int nodeIndex, int demandIndex,
@@ -1096,7 +1096,7 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param nodeIndex the node's index (starting from 1).
@param demandIndex the index of a demand category for the node (starting from 1).
@param[out] patIndex the index of the category's time pattern.
@param[out] out_patIndex the index of the category's time pattern.
@return an error code.
A returned pattern index of 0 indicates that no time pattern has been assigned to the
@@ -1143,11 +1143,11 @@ typedef struct Project *EN_Project;
int DLLEXPORT EN_setdemandname(EN_Project ph, int nodeIndex, int demandIdx,
const char *demandName);
/********************************************************************
/*===================================================================
Link Functions
********************************************************************/
===================================================================*/
/**
@brief Adds a new link to a project.
@@ -1156,7 +1156,7 @@ typedef struct Project *EN_Project;
@param linkType The type of link being added (see @ref EN_LinkType)
@param fromNode The ID name of the link's starting node.
@param toNode The ID name of the link's ending node.
@param[out] index the index of the newly added link.
@param[out] out_index the index of the newly added link.
@return an error code.
A new pipe is assigned a diameter of 10 inches (254 mm) and a length of 330
@@ -1194,7 +1194,7 @@ typedef struct Project *EN_Project;
@brief Gets the index of a link given its ID name.
@param ph an EPANET project handle.
@param id a link's ID name.
@param[out] index the link's index (starting from 1).
@param[out] out_index the link's index (starting from 1).
@return an error code.
*/
int DLLEXPORT EN_getlinkindex(EN_Project ph, const char *id, int *out_index);
@@ -1225,7 +1225,7 @@ typedef struct Project *EN_Project;
@brief Retrieves a link's type.
@param ph an EPANET project handle.
@param index a link's index (starting from 1).
@param[out] linkType the link's type (see @ref EN_LinkType).
@param[out] out_linkType the link's type (see @ref EN_LinkType).
@return an error code.
*/
int DLLEXPORT EN_getlinktype(EN_Project ph, int index, int *out_linkType);
@@ -1249,8 +1249,8 @@ typedef struct Project *EN_Project;
@brief Gets the indexes of a link's start- and end-nodes.
@param ph an EPANET project handle.
@param index a link's index (starting from 1).
@param[out] node1 the index of the link's start node (starting from 1).
@param[out] node2 the index of the link's end node (starting from 1).
@param[out] out_node1 the index of the link's start node (starting from 1).
@param[out] out_node2 the index of the link's end node (starting from 1).
@return an error code.
*/
int DLLEXPORT EN_getlinknodes(EN_Project ph, int index, int *out_node1, int *out_node2);
@@ -1270,7 +1270,7 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param index a link's index (starting from 1).
@param property the property to retrieve (see @ref EN_LinkProperty).
@param[out] value the current value of the property.
@param[out] out_value the current value of the property.
@return an error code.
Values are returned in units that depend on the units used for flow rate (see @ref Units).
@@ -1281,7 +1281,7 @@ typedef struct Project *EN_Project;
@brief Retrieves an array of property values for all links.
@param ph an EPANET project handle.
@param property the property to retrieve (see @ref EN_LinkProperty).
@param[out] values an array of values for all links.
@param[out] out_values an array of values for all links.
@return an error code.
Values are returned in units that depend on the units used for flow rate (see @ref Units).
@@ -1319,7 +1319,7 @@ typedef struct Project *EN_Project;
@brief Retrieves the number of internal vertex points assigned to a link.
@param ph an EPANET project handle.
@param index a link's index (starting from 1).
@param[out] count the number of vertex points that describe the link's shape.
@param[out] out_count the number of vertex points that describe the link's shape.
@return an error code.
*/
int DLLEXPORT EN_getvertexcount(EN_Project ph, int index, int *out_count);
@@ -1329,8 +1329,8 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param index a link's index (starting from 1).
@param vertex a vertex point index (starting from 1).
@param[out] x the vertex's X-coordinate value.
@param[out] y the vertex's Y-coordinate value.
@param[out] out_x the vertex's X-coordinate value.
@param[out] out_y the vertex's Y-coordinate value.
@return an error code.
*/
int DLLEXPORT EN_getvertex(EN_Project ph, int index, int vertex, double *out_x, double *out_y);
@@ -1359,17 +1359,17 @@ typedef struct Project *EN_Project;
*/
int DLLEXPORT EN_setvertices(EN_Project ph, int index, double *x, double *y, int count);
/********************************************************************
/*===================================================================
Pump Functions
********************************************************************/
===================================================================*/
/**
@brief Retrieves the type of head curve used by a pump.
@param ph an EPANET project handle.
@param linkIndex the index of a pump link (starting from 1).
@param[out] pumpType the type of head curve used by the pump (see @ref EN_PumpType).
@param[out] out_pumpType the type of head curve used by the pump (see @ref EN_PumpType).
@return an error code.
*/
int DLLEXPORT EN_getpumptype(EN_Project ph, int linkIndex, int *out_pumpType);
@@ -1378,7 +1378,7 @@ typedef struct Project *EN_Project;
@brief Retrieves the curve assigned to a pump's head curve.
@param ph an EPANET project handle.
@param linkIndex the index of a pump link (starting from 1).
@param[out] curveIndex the index of the curve assigned to the pump's head curve.
@param[out] out_curveIndex the index of the curve assigned to the pump's head curve.
@return an error code.
*/
int DLLEXPORT EN_getheadcurveindex(EN_Project ph, int linkIndex, int *out_curveIndex);
@@ -1392,11 +1392,11 @@ typedef struct Project *EN_Project;
*/
int DLLEXPORT EN_setheadcurveindex(EN_Project ph, int linkIndex, int curveIndex);
/********************************************************************
/*===================================================================
Time Pattern Functions
********************************************************************/
===================================================================*/
/**
@brief Adds a new time pattern to a project.
@@ -1420,7 +1420,7 @@ typedef struct Project *EN_Project;
@brief Retrieves the index of a time pattern given its ID name.
@param ph an EPANET project handle.
@param id the ID name of a time pattern.
@param[out] index the time pattern's index (starting from 1).
@param[out] out_index the time pattern's index (starting from 1).
@return an error code.
*/
int DLLEXPORT EN_getpatternindex(EN_Project ph, const char *id, int *out_index);
@@ -1451,7 +1451,7 @@ typedef struct Project *EN_Project;
@brief Retrieves the number of time periods in a time pattern.
@param ph an EPANET project handle.
@param index a time pattern index (starting from 1).
@param[out] len the number of time periods in the pattern.
@param[out] out_len the number of time periods in the pattern.
@return an error code.
*/
int DLLEXPORT EN_getpatternlen(EN_Project ph, int index, int *out_len);
@@ -1461,7 +1461,7 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param index a time pattern index (starting from 1).
@param period a time period in the pattern (starting from 1).
@param[out] value the pattern factor for the given time period.
@param[out] out_value the pattern factor for the given time period.
@return an error code.
*/
int DLLEXPORT EN_getpatternvalue(EN_Project ph, int index, int period, double *out_value);
@@ -1480,7 +1480,7 @@ typedef struct Project *EN_Project;
@brief Retrieves the average of all pattern factors in a time pattern.
@param ph an EPANET project handle.
@param index a time pattern index (starting from 1).
@param[out] value The average of all of the time pattern's factors.
@param[out] out_value The average of all of the time pattern's factors.
@return an error code.
*/
int DLLEXPORT EN_getaveragepatternvalue(EN_Project ph, int index, double *out_value);
@@ -1507,13 +1507,13 @@ typedef struct Project *EN_Project;
@param id the ID name of the new pattern to load.
@return an error code.
*/
int DLLEXPORT EN_loadpatternfile(EN_Project p, const char *filename, const char *id);
int DLLEXPORT EN_loadpatternfile(EN_Project ph, const char *filename, const char *id);
/********************************************************************
/*===================================================================
Data Curve Functions
********************************************************************/
===================================================================*/
/**
@brief Adds a new data curve to a project.
@@ -1537,7 +1537,7 @@ typedef struct Project *EN_Project;
@brief Retrieves the index of a curve given its ID name.
@param ph an EPANET project handle.
@param id the ID name of a curve.
@param[out] index The curve's index (starting from 1).
@param[out] out_index The curve's index (starting from 1).
@return an error code.
*/
int DLLEXPORT EN_getcurveindex(EN_Project ph, const char *id, int *out_index);
@@ -1568,7 +1568,7 @@ typedef struct Project *EN_Project;
@brief Retrieves the number of points in a curve.
@param ph an EPANET project handle.
@param index a curve's index (starting from 1).
@param[out] len The number of data points assigned to the curve.
@param[out] out_len The number of data points assigned to the curve.
@return an error code.
*/
int DLLEXPORT EN_getcurvelen(EN_Project ph, int index, int *out_len);
@@ -1577,7 +1577,7 @@ typedef struct Project *EN_Project;
@brief Retrieves a curve's type.
@param ph an EPANET project handle.
@param index a curve's index (starting from 1).
@param[out] type the curve's type (see @ref EN_CurveType).
@param[out] out_type the curve's type (see @ref EN_CurveType).
@return an error code.
*/
int DLLEXPORT EN_getcurvetype(EN_Project ph, int index, int *out_type);
@@ -1596,8 +1596,8 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param curveIndex a curve's index (starting from 1).
@param pointIndex the index of a point on the curve (starting from 1).
@param[out] x the point's x-value.
@param[out] y the point's y-value.
@param[out] out_x the point's x-value.
@param[out] out_y the point's y-value.
@return an error code.
*/
int DLLEXPORT EN_getcurvevalue(EN_Project ph, int curveIndex, int pointIndex,
@@ -1620,13 +1620,13 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param index a curve's index (starting from 1).
@param[out] out_id the curve's ID name.
@param[out] nPoints the number of data points on the curve.
@param[out] xValues the curve's x-values.
@param[out] yValues the curve's y-values.
@param[out] out_nPoints the number of data points on the curve.
@param[out] out_xValues the curve's x-values.
@param[out] out_yValues the curve's y-values.
@return an error code.
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
The calling program is responsible for making `out_xValues` and `out_yValues` large enough
to hold `out_nPoints` number of data points and for sizing `out_id` to hold at least
@ref EN_SizeLimits "EN_MAXID+1" characters.
*/
int DLLEXPORT EN_getcurve(EN_Project ph, int index, char *out_id, int *out_nPoints,
@@ -1649,11 +1649,11 @@ typedef struct Project *EN_Project;
int DLLEXPORT EN_setcurve(EN_Project ph, int index, double *xValues,
double *yValues, int nPoints);
/********************************************************************
/*===================================================================
Simple Controls Functions
********************************************************************/
===================================================================*/
/**
@brief Adds a new simple control to a project.
@@ -1665,7 +1665,7 @@ typedef struct Project *EN_Project;
(0 for \b EN_TIMER and \b EN_TIMEOFDAY controls).
@param level action level (tank level, junction pressure, or time in seconds)
that triggers the control.
@param[out] index index of the new control.
@param[out] out_index index of the new control.
@return an error code.
*/
int DLLEXPORT EN_addcontrol(EN_Project ph, int type, int linkIndex,
@@ -1683,12 +1683,12 @@ typedef struct Project *EN_Project;
@brief Retrieves the properties of a simple control.
@param ph an EPANET project handle.
@param index the control's index (starting from 1).
@param[out] type the type of control (see @ref EN_ControlType).
@param[out] linkIndex the index of the link being controlled.
@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] out_type the type of control (see @ref EN_ControlType).
@param[out] out_linkIndex the index of the link being controlled.
@param[out] out_setting the control setting applied to the link.
@param[out] out_nodeIndex the index of the node used to trigger the control
(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] out_level the action level (tank level, junction pressure, or time in seconds)
that triggers the control.
@return an error code.
*/
@@ -1729,11 +1729,11 @@ typedef struct Project *EN_Project;
*/
int DLLEXPORT EN_setcontrolenabled(EN_Project ph, int index, int enabled);
/********************************************************************
/*===================================================================
Rule-Based Controls Functions
********************************************************************/
===================================================================*/
/**
@brief Adds a new rule-based control to a project.
@@ -1758,10 +1758,10 @@ typedef struct Project *EN_Project;
@brief Retrieves summary information about a rule-based control.
@param ph an EPANET project handle.
@param index the rule's index (starting from 1).
@param[out] nPremises number of premises in the rule's IF section.
@param[out] nThenActions number of actions in the rule's THEN section.
@param[out] nElseActions number of actions in the rule's ELSE section.
@param[out] priority the rule's priority value.
@param[out] out_nPremises number of premises in the rule's IF section.
@param[out] out_nThenActions number of actions in the rule's THEN section.
@param[out] out_nElseActions number of actions in the rule's ELSE section.
@param[out] out_priority the rule's priority value.
@return an error code.
*/
int DLLEXPORT EN_getrule(EN_Project ph, int index, int *out_nPremises,
@@ -1784,14 +1784,14 @@ typedef struct Project *EN_Project;
@param ruleIndex the rule's index (starting from 1).
@param premiseIndex the position of the premise in the rule's list of premises
(starting from 1).
@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] 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] relop the premise's comparison operator (see @ref EN_RuleOperator).
@param[out] status the status that the object's status is compared to
@param[out] out_logop the premise's logical operator ( \b IF = 1, \b AND = 2, \b OR = 3 ).
@param[out] out_object the type of object the premise refers to (see @ref EN_RuleObject).
@param[out] out_objIndex the index of the object (e.g. the index of a tank).
@param[out] out_variable the object's variable being compared (see @ref EN_RuleVariable).
@param[out] out_relop the premise's comparison operator (see @ref EN_RuleOperator).
@param[out] out_status the status that the object's status is compared to
(see @ref EN_RuleStatus).
@param[out] value the value that the object's variable is compared to.
@param[out] out_value the value that the object's variable is compared to.
@return an error code.
*/
int DLLEXPORT EN_getpremise(EN_Project ph, int ruleIndex, int premiseIndex,
@@ -1856,9 +1856,9 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param ruleIndex the rule's index (starting from 1).
@param actionIndex the index of the THEN action to retrieve (starting from 1).
@param[out] linkIndex the index of the link in the action (starting from 1).
@param[out] status the status assigned to the link (see @ref EN_RuleStatus)
@param[out] setting the value assigned to the link's setting.
@param[out] out_linkIndex the index of the link in the action (starting from 1).
@param[out] out_status the status assigned to the link (see @ref EN_RuleStatus)
@param[out] out_setting the value assigned to the link's setting.
@return an error code.
*/
int DLLEXPORT EN_getthenaction(EN_Project ph, int ruleIndex, int actionIndex,
@@ -1882,9 +1882,9 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param ruleIndex the rule's index (starting from 1).
@param actionIndex the index of the ELSE action to retrieve (starting from 1).
@param[out] linkIndex the index of the link in the action.
@param[out] status the status assigned to the link (see @ref EN_RuleStatus).
@param[out] setting the value assigned to the link's setting.
@param[out] out_linkIndex the index of the link in the action.
@param[out] out_status the status assigned to the link (see @ref EN_RuleStatus).
@param[out] out_setting the value assigned to the link's setting.
@return an error code.
*/
int DLLEXPORT EN_getelseaction(EN_Project ph, int ruleIndex, int actionIndex,

38
include/epanet2_enums.h
View File

@@ -9,7 +9,7 @@
Authors: see AUTHORS
Copyright: see AUTHORS
License: see LICENSE
Last Updated: 02/14/2025
Last Updated: 03/22/2025
******************************************************************************
*/
@@ -17,13 +17,11 @@
#ifndef EPANET2_ENUMS_H
#define EPANET2_ENUMS_H
// --- Define the EPANET toolkit constants
/// Size Limts
/**
Limits on the size of character arrays used to store ID names
and text messages.
/// Character array size limits
/*! \enum EN_SizeLimits
* 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
@@ -31,9 +29,9 @@ typedef enum {
} EN_SizeLimits;
/// Node properties
/**
These node properties are used with @ref EN_getnodevalue and @ref EN_setnodevalue.
Those marked as read only are computed values that can only be retrieved.
/*! \enum EN_NodeProperty
* These node properties are used with @ref EN_getnodevalue and @ref EN_setnodevalue.
* Those marked as read only are computed values that can only be retrieved.
*/
typedef enum {
EN_ELEVATION = 0, //!< Elevation
@@ -133,16 +131,16 @@ typedef enum {
EN_NEXTEVENTTANK = 15 //!< Index of tank with shortest time to become empty or full (read only)
} EN_TimeParameter;
/// Time step events
/**
These are the types of events that can cause a timestep to end.
These are the types of events that can cause a new time step to be taken.
**/
typedef enum {
EN_STEP_REPORT = 0,
EN_STEP_HYD = 1,
EN_STEP_WQ = 2,
EN_STEP_TANKEVENT = 3,
EN_STEP_CONTROLEVENT = 4
EN_STEP_REPORT = 0, //!< A reporting time step has ended
EN_STEP_HYD = 1, //!< A hydraulic time step has ended
EN_STEP_WQ = 2, //!< A water quality time step has ended
EN_STEP_TANKEVENT = 3, //!< A tank has become empty or full
EN_STEP_CONTROLEVENT = 4 //!< A link control needs to be activated
} EN_TimestepEvent;
/// Analysis convergence statistics
@@ -437,7 +435,7 @@ typedef enum {
EN_EFFIC_CURVE = 2, //!< Pump efficiency v. flow curve
EN_HLOSS_CURVE = 3, //!< Valve head loss v. flow curve
EN_GENERIC_CURVE = 4, //!< Generic curve
EN_VALVE_CURVE = 5 //!< Valve loss coeff. v. frac. open
EN_VALVE_CURVE = 5 //!< % of fully open flow v. % open
} EN_CurveType;
/// Deletion action codes
@@ -512,7 +510,7 @@ typedef enum {
#define EN_SET_CLOSED -1.E10 //!< Link set closed indicator
#define EN_SET_OPEN 1.E10 //!< Link set open indicator
#define EN_FALSE 0 // boolean false
#define EN_TRUE 1 // boolean true
#define EN_FALSE 0 //!< boolean false
#define EN_TRUE 1 //!< boolean true
#endif //EPANET2_ENUMS_H

14
src/epanet.c
View File

@@ -1691,7 +1691,19 @@ int DLLEXPORT EN_settimeparam(EN_Project p, int param, long value)
/// get the time to next event, and give a reason for the time step truncation
int DLLEXPORT EN_timetonextevent(EN_Project p, int *eventType, long *duration, int *elementIndex)
int DLLEXPORT EN_timetonextevent(EN_Project p, int *eventType,
long *duration, int *elementIndex)
/*----------------------------------------------------------------
** Input: none
** Output: eventType = event causing a new time step
** to occur (see EN_TimestepEvent)
** duration = seconds until next time step occurs
** elementIndex = index of tank node or simple control
** that triggers a new time step
** Returns: error code
** Purpose: Get information about when the next hydraulic time step occurs
**----------------------------------------------------------------
*/
{
Times *time = &p->times;
long hydStep, tankStep, controlStep;