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

Merge pull request #843 from OpenWaterAnalytics/dev-doc

Browse Source 
Updates to the EPANET Toolkit documentation
This commit is contained in:
Lew Rossman
2025-04-03 12:08:04 -04:00
committed by GitHub
parent 3da4b1d861 2c667e6449
commit ab67dbd84e
24 changed files with 4189 additions and 37794 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
CMakeLists.txt
View File

@@ -1,4 +1,4 @@
# CMakeLists.txt - CMake configuration file for EPANET 2.0
# CMakeLists.txt - CMake configuration file for EPANET 2.3
#
# CMake is a cross-platform build tool. CMake generates platform native
# build systems that can be used with your compiler of choice. CMake uses a
@@ -25,7 +25,7 @@
# CMake is available at https://cmake.org/download/
#
cmake_minimum_required (VERSION 3.5.2)
cmake_minimum_required (VERSION 3.8.0)
project(EPANET)
@@ -34,12 +34,12 @@ list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
option(BUILD_TESTS "Build tests (requires Boost)" OFF)
option(BUILD_PY_LIB "Build library for Python wrapper" OFF)
#option(BUILD_PY_LIB "Build library for Python wrapper" OFF)
option(BUILD_COVERAGE "Build library for coverage" OFF)
IF (NOT BUILD_PY_LIB)
#IF (NOT BUILD_PY_LIB)
add_subdirectory(run)
ENDIF (NOT BUILD_PY_LIB)
#ENDIF (NOT BUILD_PY_LIB)
add_subdirectory(src/outfile)
IF (BUILD_TESTS)
@@ -60,17 +60,14 @@ IF (BUILD_TESTS)
add_subdirectory(tests/util)
ENDIF (BUILD_TESTS)
# Sets the output directory for executables and libraries.
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
# Sets the position independent code property for all targets
SET(CMAKE_POSITION_INDEPENDENT_CODE ON)
IF (APPLE)
set(INSTALL_NAME_DIR @executable_path/../lib)
set(CMAKE_MACOSX_RPATH 1)
@@ -84,8 +81,6 @@ ENDIF (MSVC)
# configure file groups
file(GLOB EPANET_SOURCES RELATIVE ${PROJECT_SOURCE_DIR} src/*.c src/util/*.c)
file(GLOB EPANET_LIB_ALL RELATIVE ${PROJECT_SOURCE_DIR} src/* src/util/*)
# exclude epanet python API from the default build
list(REMOVE_ITEM EPANET_LIB_ALL "src/epanet_py.c")
source_group("Library" FILES ${EPANET_LIB_ALL})
# the shared library
@@ -101,10 +96,8 @@ ENDIF(MSVC AND "${CMAKE_VS_PLATFORM_NAME}" MATCHES "(Win32)")
target_include_directories(epanet2 PUBLIC ${PROJECT_SOURCE_DIR}/include)
install(TARGETS epanet2 DESTINATION lib)
install(FILES ./include/epanet2.h DESTINATION include)
install(FILES ./include/epanet2_2.h DESTINATION include)
install(FILES ./include/epanet2_enums.h DESTINATION include)
install(DIRECTORY ./src/ DESTINATION include FILES_MATCHING PATTERN "*.h")
install(TARGETS epanet2 DESTINATION .)
install(TARGETS runepanet DESTINATION .)
install(FILES ./include/epanet2.h DESTINATION .)
install(FILES ./include/epanet2_2.h DESTINATION .)
install(FILES ./include/epanet2_enums.h DESTINATION .)

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

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

25
doc/readme.md
View File

@@ -1,30 +1,21 @@
## 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.
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.
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.
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
- `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.
*/

186
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,25 +115,27 @@ 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);
@fn int EN_setreportcallback(EN_Project ph, void (*callback)(void *userData, void *EN_projectHandle, const char*))
@fn int EN_setreportcallbackuserdata(EN_Project ph, void *userData)
@}
*/
/**
@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 +143,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 +211,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 +246,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 +274,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 +365,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}

1
include/epanet2.h
View File

@@ -169,6 +169,7 @@ extern "C" {
int DLLEXPORT ENtimetonextevent(int *eventType, long *duration, int *elementIndex);
int DLLEXPORT ENsetreportcallback(void (*callback)(void *userData, void *EN_projectHandle, const char*));
int DLLEXPORT ENsetreportcallbackuserdata(void *userData);

359
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);
@@ -218,14 +218,14 @@ typedef struct Project *EN_Project;
@brief Saves a project's data to an EPANET-formatted text file.
@param ph an EPANET project handle.
@param filename the name of the file to create.
@return Error code
@return an error code
*/
int DLLEXPORT EN_saveinpfile(EN_Project ph, const char *filename);
/**
@brief Closes a project and frees all of its memory.
@param ph an EPANET project handle.
@return Error code
@return an error code
This function clears all existing data from a project but does not delete the
project, so it can be re-used with another set of network data. Use ::EN_deleteproject
@@ -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,11 +327,11 @@ 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
simulation. This process automatically updates the simulation clock time so \b currentTime
simulation. This process automatically updates the simulation clock time so `currentTime`
should be treated as a read-only variable.
::EN_initH must have been called prior to running the ::EN_runH - ::EN_nextH loop.
@@ -344,14 +344,14 @@ 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.
This function is used in a loop with ::EN_runH to run an extended period hydraulic
simulation.
The value of \b tstep should be treated as a read-only variable. It is automatically
The value of `out_tstep` should be treated as a read-only variable. It is automatically
computed as the smaller of:
- the time interval until the next hydraulic time step begins
- the time interval until the next reporting time step begins
@@ -400,7 +400,7 @@ typedef struct Project *EN_Project;
Before calling this function hydraulic results must have been generated and saved by having
called ::EN_solveH or the ::EN_initH - ::EN_runH - ::EN_nextH sequence with the initflag
argument of ::EN_initH set to \b EN_SAVE or \b EN_SAVE_AND_INIT.
argument of ::EN_initH set to `EN_SAVE` or `EN_SAVE_AND_INIT`.
*/
int DLLEXPORT EN_savehydfile(EN_Project ph, const char *filename);
@@ -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
@@ -456,8 +456,8 @@ typedef struct Project *EN_Project;
/**
@brief Initializes a network prior to running a water quality analysis.
@param ph an EPANET project handle.
@param saveFlag set to \b EN_SAVE (1) if results are to be saved to the project's
binary output file, or to \b EN_NOSAVE (0) if not.
@param saveFlag set to `EN_SAVE` (1) if results are to be saved to the project's
binary output file, or to `EN_NOSAVE` (0) if not.
@return an error code.
Call ::EN_initQ prior to running a water quality analysis using ::EN_runQ in
@@ -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
@@ -484,16 +484,16 @@ typedef struct Project *EN_Project;
::EN_initQ must have been called prior to running an ::EN_runQ - ::EN_nextQ
(or ::EN_stepQ) loop.
The current time of the simulation is determined from information saved with the
hydraulic analysis that preceded the water quality analysis. Treat it as a read-only
variable.
The current time of the simulation, `out_currentTime`, is determined from information
saved with the hydraulic analysis that preceded the water quality analysis. Treat it
as a read-only variable.
*/
int DLLEXPORT EN_runQ(EN_Project ph, long *out_currentTime);
/**
@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.
@@ -502,7 +502,7 @@ typedef struct Project *EN_Project;
time step determined by when the next hydraulic event occurs. Use ::EN_stepQ instead
if you wish to generate results over each water quality time step.
The value of \b tStep is determined from information produced by the hydraulic analysis
The value of `tStep` is determined from information produced by the hydraulic analysis
that preceded the water quality analysis. Treat it as a read-only variable.
<b>Example:</b>
@@ -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
@@ -533,8 +533,8 @@ typedef struct Project *EN_Project;
quality time step of the simulation, rather than over each hydraulic event period
as with ::EN_nextQ.
Use the argument \b timeLeft to determine when no more calls to ::EN_runQ are needed
because the end of the simulation period has been reached (i.e., when \b timeLeft = 0).
Use the argument `timeLeft` to determine when no more calls to ::EN_runQ are needed
because the end of the simulation period has been reached (i.e., when `timeLeft` = 0).
*/
int DLLEXPORT EN_stepQ(EN_Project ph, long *out_timeLeft);
@@ -550,22 +550,42 @@ typedef struct Project *EN_Project;
*/
int DLLEXPORT EN_closeQ(EN_Project ph);
/********************************************************************
/*===================================================================
Reporting Functions
********************************************************************/
===================================================================*/
/**
@brief Set a user-supplied callback function for reporting
@brief Sets a user-supplied callback function for reporting
@param ph an EPANET project handle.
@param callback a function pointer with declared signature, which gets called by EPANET for reporting.
@param callback a function pointer used for reporting.
@return an error code.
@details The report callback function must have the signature specified - void(void* userData, EN_Project, char*) -
use the userData parameter to pass any client context necessary (a context pointer or wrapper object perhaps).
Leave un-set or set the report callback to NULL to revert to EPANET's default behavior.
**/
int DLLEXPORT EN_setreportcallback(EN_Project ph, void (*callback)(void *userData, void *EN_projectHandle, const char*));
The callback function replaces the project's report file as
the destination for all output written by ::EN_writeline. It must have
the following signature:
`void(void *userData, void *EN_projectHandle p, const char* s)`
The `userData` parameter is a pointer to a client-side data object.
It can be changed using the ::EN_setreportcallbackuserdata function.
The parameter `s` is a placeholder for the EPANET-generated string
that was passed into ::EN_writeline. Setting the callback function to
NULL reverts to having ::EN_writeline use the project's report file.
*/
int DLLEXPORT EN_setreportcallback(EN_Project ph, void(*callback)(void *userData, void *EN_projectHandle, const char*));
/**
@brief Sets a pointer to a client-side data object
@param ph an EPANET project handle.
@param userData a pointer to a client-side data object.
@return an error code.
The data pointer supplied by this function is passed into the callback
function declared in ::EN_setreportcallback that replaces a project's
report file as the destination for output written with ::EN_writeline.
*/
int DLLEXPORT EN_setreportcallbackuserdata(EN_Project ph, void *userData);
/**
@@ -573,6 +593,9 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param line a text string to write.
@return an error code.
::EN_setreportcallback can be used to assign an alternative destination
to write `line` to in place of the project's report file.
*/
int DLLEXPORT EN_writeline(EN_Project ph, const char *line);
@@ -647,21 +670,21 @@ typedef struct Project *EN_Project;
Status reporting writes changes in the hydraulics status of network elements to a
project's report file as a hydraulic simulation unfolds. There are three levels
of reporting: \b EN_NO_REPORT (no status reporting), \b EN_NORMAL_REPORT (normal
reporting) \b EN_FULL_REPORT (full status reporting).
of reporting: `EN_NO_REPORT` (no status reporting), `EN_NORMAL_REPORT` (normal
reporting) `EN_FULL_REPORT` (full status reporting).
The full status report contains information at each trial of the solution to the
system hydraulic equations at each time step of a simulation. It is useful mainly
for debugging purposes.
If many hydraulic analyses will be run in the application it is recommended that
status reporting be turned off (<b>level = EN_NO_REPORT</b>).
status reporting be turned off (`level` = `EN_NO_REPORT`).
*/
int DLLEXPORT EN_setstatusreport(EN_Project ph, int level);
/**
@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 +707,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 +727,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 +738,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 +766,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 +789,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 +806,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 +818,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 `out_qualType` = `EN_TRACE`.
@return an error code.
*/
int DLLEXPORT EN_getqualtype(EN_Project ph, int *out_qualType, int *out_traceNode);
@@ -807,7 +830,7 @@ typedef struct Project *EN_Project;
@param qualType the type of analysis to run (see @ref EN_QualityType).
@param chemName the name of the quality constituent.
@param chemUnits the concentration units of the constituent.
@param traceNode the ID name of the node being traced if <b>qualType = EN_TRACE</b>.
@param traceNode the ID name of the node being traced if `qualType` = `EN_TRACE`.
@return an error code.
Chemical name and units can be an empty string if the analysis is not for a chemical.
@@ -818,18 +841,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.
@@ -843,9 +866,9 @@ typedef struct Project *EN_Project;
@param actionCode the action taken if any control contains the node and its links.
@return an error code.
If \b actionCode is \b EN_UNCONDITIONAL then the node, its incident links and all
If `actionCode` is `EN_UNCONDITIONAL` then the node, its incident links and all
simple and rule-based controls that contain them are deleted. If set to
\b EN_CONDITIONAL then the node is not deleted if it or its incident links appear
`EN_CONDITIONAL` then the node is not deleted if it or its incident links appear
in any controls and error code 261 is returned.
*/
@@ -855,7 +878,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 +909,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 +919,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 +928,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 +989,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,22 +1005,22 @@ 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.
Parameters `pmin`, `preq`, and `pexp` are only used when the demand model is `EN_PDA`.
*/
int DLLEXPORT EN_getdemandmodel(EN_Project ph, int *out_type, double *out_pmin,
double *out_preq, double *out_pexp);
@@ -1011,15 +1034,13 @@ typedef struct Project *EN_Project;
@param pexp Pressure exponent in demand function.
@return an error code.
Set \b type to \b EN_DDA for a traditional demand driven analysis (in which case the
remaining three parameter values are ignored) or to \b EN_PDA for a pressure driven
analysis. In the latter case a node's demand is computed as:
> `Dfull * [ (P - pmin) / (preq - pmin) ] ^ pexp`
Set `type` to `EN_DDA` for a traditional demand driven analysis (in which case the
remaining three parameter values are ignored) or to `EN_PDA` for a pressure driven
analysis. In the latter case a node's demand is computed as:\n
`Dfull * [ (P - pmin) / (preq - pmin) ] ^ pexp`\n
where `Dfull` is the full demand and `P` is the current pressure.
Setting \b preq equal to \b pmin will result in a solution with the smallest amount of
demand reductions needed to insure that no node delivers positive demand at a pressure
below \b pmin.
A valid value for `preq` must be at least 0.1 pressure units larger than `pmin`.
*/
int DLLEXPORT EN_setdemandmodel(EN_Project ph, int type, double pmin,
double preq, double pexp);
@@ -1054,7 +1075,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 +1085,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 +1095,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 +1117,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
@@ -1126,7 +1147,7 @@ typedef struct Project *EN_Project;
@param[out] out_demandName The name of the selected category.
@return an error code.
\b demandName must be sized to contain at least @ref EN_SizeLimits "EN_MAXID+1" characters.
`demandName` must be sized to contain at least @ref EN_SizeLimits "EN_MAXID+1" characters.
*/
int DLLEXPORT EN_getdemandname(EN_Project ph, int nodeIndex, int demandIndex, char *out_demandName);
@@ -1136,18 +1157,18 @@ typedef struct Project *EN_Project;
@param nodeIndex a node's index (starting from 1).
@param demandIdx the index of one of the node's demand categories (starting from 1).
@param demandName the new name assigned to the category.
@return Error code.
@return an error code.
The category name must contain no more than @ref EN_SizeLimits "EN_MAXID" characters.
*/
int DLLEXPORT EN_setdemandname(EN_Project ph, int nodeIndex, int demandIdx,
const char *demandName);
/********************************************************************
/*===================================================================
Link Functions
********************************************************************/
===================================================================*/
/**
@brief Adds a new link to a project.
@@ -1156,7 +1177,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
@@ -1167,7 +1188,7 @@ typedef struct Project *EN_Project;
All other pipe properties are set to 0.
A new pump has a status of \b EN_OPEN, a speed setting of 1, and has no pump
A new pump has a status of `EN_OPEN`, a speed setting of 1, and has no pump
curve or power rating assigned to it.
A new valve has a diameter of 10 inches (254 mm) and all other properties set to 0.
@@ -1184,8 +1205,8 @@ typedef struct Project *EN_Project;
@param actionCode The action taken if any control contains the link.
@return an error code.
If \b actionCode is \b EN_UNCONDITIONAL then the link and all simple and rule-based
controls that contain it are deleted. If set to \b EN_CONDITIONAL then the link
If `actionCode` is `EN_UNCONDITIONAL` then the link and all simple and rule-based
controls that contain it are deleted. If set to `EN_CONDITIONAL` then the link
is not deleted if it appears in any control and error 261 is returned.
*/
int DLLEXPORT EN_deletelink(EN_Project ph, int index, int actionCode);
@@ -1194,7 +1215,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);
@@ -1215,7 +1236,7 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param index a link's index (starting from 1).
@param newid the new ID name for the link.
@return Error code.
@return an error code.
The ID name must not be longer than @ref EN_SizeLimits "EN_MAXID" characters.
*/
@@ -1225,7 +1246,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);
@@ -1238,9 +1259,9 @@ typedef struct Project *EN_Project;
@param actionCode the action taken if any controls contain the link.
@return an error code.
If \b actionCode is \b EN_UNCONDITIONAL then all simple and rule-based controls that
If `actionCode` is `EN_UNCONDITIONAL` then all simple and rule-based controls that
contain the link are deleted when the link's type is changed. If set to
\b EN_CONDITIONAL then the type change is cancelled if the link appears in any
`EN_CONDITIONAL` then the type change is cancelled if the link appears in any
control and error 261 is returned.
*/
int DLLEXPORT EN_setlinktype(EN_Project ph, int *inout_index, int linkType, int actionCode);
@@ -1249,8 +1270,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 +1291,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 +1302,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 +1340,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 +1350,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 +1380,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 +1399,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 +1413,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 +1441,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 +1472,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 +1482,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 +1501,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);
@@ -1493,7 +1514,7 @@ typedef struct Project *EN_Project;
@param len the number of factor values supplied.
@return an error code.
\b values is a zero-based array that contains \b len elements.
`values` is a zero-based array that contains `len` elements.
Use this function to redefine (and resize) a time pattern all at once;
use @ref EN_setpatternvalue to revise pattern factors one at a time.
@@ -1507,13 +1528,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 +1558,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 +1589,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 +1598,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 +1617,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 +1641,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,
@@ -1641,7 +1662,7 @@ typedef struct Project *EN_Project;
@param nPoints the new number of data points for the curve.
@return an error code.
\b xValues and \b yValues are zero-based arrays that contains \b nPoints elements.
`xValues` and `yValues` are zero-based arrays that contains `nPoints` elements.
Use this function to redefine (and resize) a curve all at once;
use @ref EN_setcurvevalue to revise a curve's data points one at a time.
@@ -1649,11 +1670,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.
@@ -1662,10 +1683,10 @@ typedef struct Project *EN_Project;
@param linkIndex the index of a link to control (starting from 1).
@param setting control setting applied to the link.
@param nodeIndex index of the node used to control the link
(0 for \b EN_TIMER and \b EN_TIMEOFDAY controls).
(0 for `EN_TIMER` and `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 +1704,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
(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_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 `EN_TIMER` and `EN_TIMEOFDAY` controls).
@param[out] out_level the action level (tank level, junction pressure, or time in seconds)
that triggers the control.
@return an error code.
*/
@@ -1703,7 +1724,7 @@ typedef struct Project *EN_Project;
@param linkIndex the index of the link being controlled.
@param setting the control setting applied to the link.
@param nodeIndex the index of the node used to trigger the control
(0 for \b EN_TIMER and \b EN_TIMEOFDAY controls).
(0 for `EN_TIMER` and `EN_TIMEOFDAY` controls).
@param level the action level (tank level, junction pressure, or time in seconds)
that triggers the control.
@return an error code.
@@ -1729,11 +1750,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 +1779,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,
@@ -1772,7 +1793,7 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param index the rule's index (starting from 1).
@param[out] out_id the rule's ID name.
@return Error code.
@return an error code.
The ID name must be sized to hold at least @ref EN_SizeLimits "EN_MAXID+1" characters.
*/
@@ -1784,14 +1805,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 (`IF` = 1, `AND` = 2, `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,
@@ -1803,7 +1824,7 @@ typedef struct Project *EN_Project;
@param ph an EPANET project handle.
@param ruleIndex the rule's index (starting from 1).
@param premiseIndex the position of the premise in the rule's list of premises.
@param logop the premise's logical operator ( \b IF = 1, \b AND = 2, \b OR = 3 ).
@param logop the premise's logical operator (`IF` = 1, `AND` = 2, `OR` = 3 ).
@param object the type of object the premise refers to (see @ref EN_RuleObject).
@param objIndex the index of the object (e.g. the index of a tank).
@param variable the object's variable being compared (see @ref EN_RuleVariable).
@@ -1856,9 +1877,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 +1903,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,

71
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,11 +29,11 @@ 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 {
typedef enum {
EN_ELEVATION = 0, //!< Elevation
EN_BASEDEMAND = 1, //!< Primary demand baseline value
EN_PATTERN = 2, //!< Primary demand time pattern index
@@ -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
@@ -219,7 +217,7 @@ typedef enum {
/// Link status
/**
One of these values is returned when @ref EN_getlinkvalue is used to retrieve a link's
initial status ( \b EN_INITSTATUS ) or its current status ( \b EN_STATUS ). These options are
initial status (`EN_INITSTATUS`) or its current status (`EN_STATUS`). These options are
also used with @ref EN_setlinkvalue to set values for these same properties.
*/
typedef enum {
@@ -230,8 +228,8 @@ typedef enum {
/// Pump states
/**
One of these codes is returned when @ref EN_getlinkvalue is used to retrieve a pump's
current operating state ( \b EN_PUMP_STATE ). \b EN_PUMP_XHEAD indicates that the pump has been
shut down because it is being asked to deliver more than its shutoff head. \b EN_PUMP_XFLOW
current operating state (`EN_PUMP_STATE`). `EN_PUMP_XHEAD` indicates that the pump has been
shut down because it is being asked to deliver more than its shutoff head. `EN_PUMP_XFLOW`
indicates that the pump is being asked to deliver more than its maximum flow.
*/
typedef enum {
@@ -256,7 +254,7 @@ typedef enum {
/// Water quality source types
/**
These are the different types of external water quality sources that can be assigned
to a node's \b EN_SOURCETYPE property as used by @ref EN_getnodevalue and @ref EN_setnodevalue.
to a node's `EN_SOURCETYPE` property as used by @ref EN_getnodevalue and @ref EN_setnodevalue.
*/
typedef enum {
EN_CONCEN = 0, //!< Sets the concentration of external inflow entering a node
@@ -267,9 +265,9 @@ typedef enum {
/// Head loss formulas
/**
The available choices for the \b EN_HEADLOSSFORM option in @ref EN_getoption and
The available choices for the `EN_HEADLOSSFORM` option in @ref EN_getoption and
@ref EN_setoption. They are also used for the head loss type argument in @ref EN_init.
Each head loss formula uses a different type of roughness coefficient ( \b EN_ROUGHNESS )
Each head loss formula uses a different type of roughness coefficient (`EN_ROUGHNESS`)
that can be set with @ref EN_setlinkvalue.
*/
typedef enum {
@@ -282,7 +280,7 @@ typedef enum {
/**
These choices for flow units are used with @ref EN_getflowunits and @ref EN_setflowunits.
They are also used for the flow units type argument in @ref EN_init. If flow units are
expressed in US Customary units ( \b EN_CFS through \b EN_AFD ) then all other quantities are
expressed in US Customary units (`EN_CFS` through `EN_AFD`) then all other quantities are
in US Customary units. Otherwise they are in metric units.
*/
typedef enum {
@@ -301,10 +299,10 @@ typedef enum {
/// Pressure units
/**
The available choices for pressure units for the \b EN_PRESS_UNITS option in @ref EN_getoption
and @ref EN_setoption. For networks using US Customary units for flow ( \b EN_CFS through
\b EN_AFD ) pressure units can only be set as PSI. For network using metric units, you can
select either \b EN_METERS or \b EN_KPA.
The available choices for pressure units for the `EN_PRESS_UNITS` option in @ref EN_getoption
and @ref EN_setoption. For networks using US Customary units for flow (`EN_CFS` through
`EN_AFD`) pressure units can only be set as PSI. For network using metric units, you can
select either `EN_METERS` or `EN_KPA`.
*/
typedef enum {
EN_PSI = 0, //!< Pounds per square inch
@@ -379,9 +377,10 @@ typedef enum {
/// Reporting statistic choices
/**
These options determine what kind of statistical post-processing should be done on
the time series of simulation results generated before they are reported using
@ref EN_report. An option can be chosen by using \b STATISTIC _option_ as the argument
to @ref EN_setreport.
the time series of simulation results before they are reported using @ref EN_report
or saved to the project's binary output file. These options are used in the
@ref EN_gettimeparam and @ref EN_settimeparam functions when `EN_STATISTIC` is the
time parameter being set or retrieved.
*/
typedef enum {
EN_SERIES = 0, //!< Report all time series points
@@ -394,7 +393,7 @@ typedef enum {
/// Tank mixing models
/**
These are the different types of models that describe water quality mixing in storage tanks.
The choice of model is accessed with the \b EN_MIXMODEL property of a Tank node using
The choice of model is accessed with the `EN_MIXMODEL` property of a Tank node using
@ref EN_getnodevalue and @ref EN_setnodevalue.
*/
typedef enum {
@@ -437,7 +436,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 +511,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

3
run/CMakeLists.txt
View File

@@ -1,5 +1,5 @@
# EPANET COMMAND LINE EXECUTABLE
cmake_minimum_required (VERSION 2.8.8)
cmake_minimum_required (VERSION 3.8.0)
# Sets for output directory for executables and libraries.
@@ -31,3 +31,4 @@ if(NOT WIN32)
else(NOT WIN32)
target_link_libraries(runepanet LINK_PUBLIC epanet2)
endif(NOT WIN32)

33
src/epanet.c
View File

@@ -851,13 +851,28 @@ int DLLEXPORT EN_closeQ(EN_Project p)
int DLLEXPORT EN_setreportcallback(EN_Project p, void (*callback)(void*,void*,const char*))
{
/*----------------------------------------------------------------
** Input: callback = a pointer to a reporting function
** Output: none
** Returns: error code
** Purpose: replaces EPANET's normal use of a designated report file
**----------------------------------------------------------------
*/
{
p->report.reportCallback = callback;
return 0;
}
int DLLEXPORT EN_setreportcallbackuserdata(EN_Project p, void *userData)
{
/*----------------------------------------------------------------
** Input: userData = a pointer to a client-side data object
** Output: none
** Returns: error code
** Purpose: sets the client-side data object used in conjunction with
** the callback function in EN_setreportcallback
**----------------------------------------------------------------
*/
{
p->report.reportCallbackUserData = userData;
return 0;
}
@@ -1691,7 +1706,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;