v2.2

* removing reference to strncpy

* Fixing memory problems with test_toolkit

Fixes memory leaks and some minor refactoring.

* Update test_toolkit.hpp

removing crtdbg.h from header

* Update CMakeLists.txt

Restoring test_net_builder to test_toolkit.exe

* Cleaning up include statements adding crtdbg.h

* Fixing index error in test

* Add more analysis options to the API (issue #425)

* Fixed epanet2_enums.h

* Eliminates use of temporary linked lists to process Patterns & Curves (issue #449)

* Update input2.c

* Bug fix for 2Comp and LIFO tank mixing models (issue #448)

* Triggering build to update benchmarks

* Added new reg tests

Updating reference build id

* Initial commit list

generic linked list

* Update test_list.cpp

Tests are passing

* Update list.h

Adding documentation

* Fix typo

* Fixing bug in head_list

* Fixing indentation

* Fixed memory leak

Fixed memory leak in test_head_list

* Clean up and inline comments

* Updating file headers

* Update list.c

Updating in line comments.

* Update test_list.cpp

* Fixing indent

Spaces not tabs

* Update list.c

Fixing indent

* Update test_list.cpp

Updating file header to reflect proper attribution

* Expanding test

Added test where data is a struct

* Fixing indent

* Work in progress

* Reorganized to contain list abstraction

* Update list.c

* Refactoring head_list and tail_list

Simplifying head and tail list. Adding delete_node() to list API.

* Update test_list.cpp

* Update test_list.cpp

Fixing bug on gcc

* Fixing bug

* Fixing bug on gcc

* Update CMakeLists.txt

Adding test_list to ctest

* Fixes memory leak in EN_addnode() (#455)


* Fixing memory leak in EN_addnode()

* Separating test_net_builder from test_toolkit

Making test_net_builder a standalone test

* Removing BOOST_TEST_MAIN

* Work in progress

* Updating unit tests

* Fixing compilation bug on gcc

* Work in progress

compiles with warnings, definitely not working

* Update demand.h

* Work in progress

Implementing demand_list

* Work in progress

Creating function for validateing element ID strings

* Work in progress

Refactoring cstr_copy and adding test

* Update cstr_helper.c

fixing indentation

* Update cstr_helper.c

Fixing indentation

* Update test_cstrhelper.cpp

Fixed mem leak

* Adding element id validity checks

* Adding element id validity check

Adding checks for element set id functions

* Fixing build warnings on gcc

* Update errror code from 250 to 252

* Work in progress

Implementing generic demand pattern lists. Compiles but does not run.

* Update demand.c

Work in progress

* Return object index from EN_addnode and EN_addlink (issue #432)

Adds an output argument to EN_addnode and EN_addlink that returns the index of the newly added object.
Also refactors the validity check on object ID names.

* Fixed compilation errors

* Update test_node.cpp

* Create test_demand_data.cpp

* test demand data passing

* Work in progress

Fixing problems when demand lists are null

* Passing open and close test

* get/set demand name are passing

* Updated criteria for valid object ID name

* Work in progress

* Work in progress

Working on demand lists

* Work in progress

Fixing memory leaks
Unit tests passing

* Cleaning up build on gcc

* Cleaning up gcc build

* Fixing bug

* Working on gcc bug

Tests are passing on Appveyor

* Update inpfile.c

Trying to isolate bug

* GCC Bug

* Refactored xstrcpy function

* Update inpfile.c

Testing linux build

* Update epanet.c

Trying to isolate bug

* updating get demand name and write demands

Everything passing locally

* Update test_project.cpp

Isolating bug on gcc

* Isolating bug

Not writing demand section of input file should eliminate it

* Update demand.c

Fixing bug in get_category_name when category_name is NULL

* Restoring write_demands section in saveinpfile

* Update test_demand_data.cpp

Adding index to addnode calls. Fixing indent

* Update demand.c

* Reverted handling of default pattern

When creating demands, no pattern is marked with a zero. Then when data is adjusted it gets updated to default.

* Update epanet.c

Updating EN_getnodevalue() and EN_setnodevalue() to process the primary demand located at the head of the demand list

* Update demand.c

* Work in progress

code cleanup, addressed issue raised in review, and implemented EN_adddemand()

* Adding key and search to list

* Adding remove node method to generic list

* Adding remove demand method to toolkit

* Fix bug and test remove demand

* Fix problems with setting tank parameters (issue #464 )

* Fixed NULL pointer error, if no label is provided after the rule keyword.

* Create Makefile2.bat

Co-Authored-By: Demetrios G. Eliades <eldemet@users.noreply.github.com>
Co-Authored-By: Elad Salomons <selad@optiwater.com>

* Create LICENSE

* Fixed NULL pointer error, if no label is provided after the rule keyword.
Add NULL guard in freerules function. Use strncat and strncpy to ensure
the buffer lengths are adhered to.

* For "conditional" do delete a node connected to a link

For "conditional" deletion the node is deleted only if all of its links have been explicitly deleted beforehand #473

Co-Authored-By: Lew Rossman <lrossman@outlook.com>

* Create CODE_OF_CONDUCT.md

* Refactors the API's demand editing functions

* Update test_demand.cpp

* Update CODE_OF_CONDUCT.md

* Update rules.c

Fix broken win build script

* Updates to doc files

* Documentation edits

* Update Makefile.bat

Updates on the Microsoft SDK 7.1 compilation script to generate runepanet.exe and to use the \include\epanet2.def

* Update Makefile2.bat

Modified epanet2.exe to runepanet.exe, for consistency.

* Delete epanet2.def

Deleted the redundant `epanet2.def` file in the WindSDK folder

* Minor format change to status report

* Removing status reports from CI testing

* rm WinSDK folder and update Makefiles

Co-Authored-By: Demetrios G. Eliades <eldemet@users.noreply.github.com>

* Restored CI testing of status reports

* Removes _DEBUG directives from all source files

This commit removes the #ifdef _DEBUG statements at the top of all source code files per issue #482. It also updates the doc files to stress that the speedup observed for hydraulic analysis with the MMD node re-ordering method only applies to single period runs.

* Fix refactor of types.h

* updates authors

* updates AUTHORS and generator script

* Update run\CMakeLists.txt

* add help file win_build.md

Co-Authored-By: Elad Salomons <selad@optiwater.com>

* move win_build.md to root dir and renaiming to BUILDING.md

* Move BuildAndTest.md to the tools directory

* Update BUILDING.md

* Update BUILDING.md

* Update BUILDING.md

* Fixes problem with findpattern() function (issue #498)

* Change default properties for new pipe created with EN_addlink (issue #500)

* Numerous updates to project documentation

* Adds tank overflow feature

* Updating docs for tank overflow feature

* Updating VB include files

* Update input3.c

* Identifies overflowing tank in Status Report

* Update Makefile.bat

* Update Makefile2.bat

#508

* rethinking the python wrapper (#511)

* renames certain function parameter declarations and removes double pointer call from the deleteproject function

* deprecates conditonal compilation, removes python-specific headers and function renaming

* fixes tests and docs

* fixes test

* PDA fixes

* Minor update to force new CI test

* Another minor change to force another CI test

* Fixes Overflow and PDA tests not being run

* Fix EN_getElseaction and EN_setelseaction

Co-Authored-By: Andreas Ashikkis <andreasashikkis@users.noreply.github.com>

* Add -MT switch for CMake Windows build

* Updates to the docs

* Update BUILDING.md

* Build script updates

* Fixes EN_setlinkvalue bug

* fix in EN_deleteLink

when pipes are deleted via deletelink it also deletes comment of last link

Co-Authored-By: Pavlos Pavlou <pavlou.v.pavlos@ucy.ac.cy>

* rm set to null in functions EN_deletenode, EN_deletelink

* trial actions config

* Update ccpp.yml

* welcome to the Actions beta

* fixes mkstemp file handle-leaking behavior (#529)

* reverts posix include (#533)

... because it is not needed

* Fixes bugs in pump and demand head loss gradients

* Removed dependence on unistd.h in project.c

Travis CI failed because system could not find unistd.h.

* getTmpName() and xstrcpy() made safer

* Fixed use of strncpy in xstrcpy()

* Refactor of hydcoeffs.c

Simplifies and unifies how limit on head gradient at low flow is handled.

* Update ReleaseNotes2_2.md

* Return error if node/link name is too long (#535)

* co-authored with @ehsan-shafiee

* removes errant slashes

* Throws correct error for ID name too long

* Revert "Throws correct error for ID name too long"

This reverts commit 57b4873f5882cb9fd983f7e1e5a703b9e442cd74.

* fixes #534 by bubbling error codes up from add node/link internal functions

* fixes tests on Mac at least

* fixes improper success code

* Error 252 (not 250) returned for ID name too long.

From errors.dat: DAT(252,"invalid ID name")

* Fixes problems with EN_addnode() (#543)

See issue #542 . Also modifies unit test test_node to check that fixup works.

* Adds EN_getresultindex function to the API

See issue #546 . Also fixes a small bug in project.c.

* Adds link vertex get/set functions to the API

* Fixes to EN_addlink and EN_deletelink

* Updates the docs

* Bug fix for EN_setcurve

Adjusts params of any pump that uses the curve whose data is modified by EN_setcurve or EN_setcurvevalue (issue #550 ).

* Bug fix for EN_getrule

Fixes possible seg fault condition in EN_getrule. Also defines EN_MISSING as an API constant since it can be assigned internally to several variables that are retrievable by the API.

* Updating the docs

* Adds error check to EN_setheadcurveindex

See issue #556 .

* Update epanet2.pas

* Incorrect characterd

There was a character ’ instead of ' which created an error when compiling LaTeX.

* fixes a crashing issue in freedata (#559)

The freedata function used cached values for sizes of certain arrays found in the parser struct. However, now that the network is mutable, those values can become invalid. Relying instead on the actual array lengths prevents freeing unallocated memory, or ignoring cleanup on newly created elements.

* Bug fix for valvecheck function

See issue #561

* Restored prior update to project.c that got overwritten

* Fixed editing errors made to project.c

* PDF Guide

PDF users' guide for EPANET, and some minor corrections to readme.md to fix some formatting issues.

* HTML Users Guide

* Fixes a "copy over" bug in input3.c

The copying of one input line token over another was causing a compilation error under Clang. With v2.2 this copying is no longer needed so the line of code in question was simply deleted.

This commit also deletes the HTML and Latex output generated by running Doxygen that got added from the previous update to dev since they don't really belong in a source code repo.

* Correction made to doc files

The output-format.dox file was deprecated and not included in the doxyfile so it was deleted. The description of the format of of the Energy Usage section of the binary output in toolkit-files.dox was corrected.

* Update ReleaseNotes2_2.md

I added the v2.2 contributing authors to the notes. I checked PR's from 2017 and beyond and these were the only names I could find. Please append any one I might have missed.

* Fixes problem with re-opening const. HP pumps

See latest comments in issue #528. Also, the setlinkflow() function was deleted as it was never called anywhere.

* Update README.md (#539)

* Update README.md

* Update README.md

Some section titles were re-named to conform to GitHub guidelines and the OWA info was moved to a CREDITS section.

* Update README.md

Added link to the Community Forum page.

* Replaced OWA copyright with "(see AUTHORS)".

* Update AUTHORS

Copied format used by the OWA-SWMM project.

* Update README.md

The Disclaimer section was edited to reflect that there actually is a "collaborative" connection between USEPA and OWA.

* updates CI badges

* cleanup of readme links and unused files

* possessive vs contraction

* adding contributor to notes

doc/DoxygenLayout.xml

@@ -0,0 +1,195 @@
+<doxygenlayout version="1.0">
+  <!-- Generated by doxygen 1.8.10 -->
+  <!-- Navigation index tabs for HTML output -->
+  <navindex>
+    <tab type="mainpage" visible="yes" title=""/>
+    <tab type="pages" visible="yes" title="" intro=""/>
+    <tab type="modules" visible="yes" title="API Reference"
+    intro="These topics describe the Toolkit's functions, enumerations, and error/warning codes."/>
+    <tab type="namespaces" visible="yes" title="">
+      <tab type="namespacelist" visible="yes" title="" intro=""/>
+      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="classes" visible="yes" title="">
+      <tab type="classlist" visible="yes" title="" intro=""/>
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+      <tab type="hierarchy" visible="yes" title="" intro=""/>
+      <tab type="classmembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="files" visible="no" title="">
+      <tab type="filelist" visible="no" title="" intro=""/>
+      <tab type="globals" visible="no" title="" intro=""/>
+    </tab>
+    <tab type="examples" visible="yes" title="" intro=""/>  
+  </navindex>
+
+  <!-- Layout definition for a class page -->
+  <class>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <inheritancegraph visible="$CLASS_GRAPH"/>
+    <collaborationgraph visible="$COLLABORATION_GRAPH"/>
+    <memberdecl>
+      <nestedclasses visible="yes" title=""/>
+      <publictypes title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <publicslots title=""/>
+      <signals title=""/>
+      <publicmethods title=""/>
+      <publicstaticmethods title=""/>
+      <publicattributes title=""/>
+      <publicstaticattributes title=""/>
+      <protectedtypes title=""/>
+      <protectedslots title=""/>
+      <protectedmethods title=""/>
+      <protectedstaticmethods title=""/>
+      <protectedattributes title=""/>
+      <protectedstaticattributes title=""/>
+      <packagetypes title=""/>
+      <packagemethods title=""/>
+      <packagestaticmethods title=""/>
+      <packageattributes title=""/>
+      <packagestaticattributes title=""/>
+      <properties title=""/>
+      <events title=""/>
+      <privatetypes title=""/>
+      <privateslots title=""/>
+      <privatemethods title=""/>
+      <privatestaticmethods title=""/>
+      <privateattributes title=""/>
+      <privatestaticattributes title=""/>
+      <friends title=""/>
+      <related title="" subtitle=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <constructors title=""/>
+      <functions title=""/>
+      <related title=""/>
+      <variables title=""/>
+      <properties title=""/>
+      <events title=""/>
+    </memberdef>
+    <allmemberslink visible="yes"/>
+    <usedfiles visible="$SHOW_USED_FILES"/>
+    <authorsection visible="yes"/>
+  </class>
+
+  <!-- Layout definition for a namespace page -->
+  <namespace>
+    <briefdescription visible="yes"/>
+    <memberdecl>
+      <nestednamespaces visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </namespace>
+
+  <!-- Layout definition for a file page -->
+  <file>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <includegraph visible="$INCLUDE_GRAPH"/>
+    <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
+    <sourcelink visible="yes"/>
+    <memberdecl>
+      <classes visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection/>
+  </file>
+
+  <!-- Layout definition for a group page -->
+  <group>
+    <briefdescription visible="yes"/>
+    <groupgraph visible="$GROUP_GRAPHS"/>
+    <memberdecl>
+      <nestedgroups visible="yes" title="File Sections"/>
+      <dirs visible="yes" title=""/>
+      <files visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title="Overview"/>
+    <memberdef>
+      <pagedocs/>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </group>
+
+  <!-- Layout definition for a directory page -->
+  <directory>
+    <briefdescription visible="yes"/>
+    <directorygraph visible="yes"/>
+    <memberdecl>
+      <dirs visible="yes"/>
+      <files visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+  </directory>
+</doxygenlayout>

doc/How-to-use-the-toolkit.dox

@@ -1,43 +0,0 @@
-/** 
-@page how-to-use How to Use the Toolkit
-
-The following topics briefly describe how to accomplish some basic tasks for which the Toolkit would be used. See the Example Applications topic for code listings of complete applications of the Toolkit. 
-
-@section open-close Opening and Closing the Toolkit
-
-The Toolkit must open an EPANET [Input File](Input-File) to obtain a description of the pipe network to be analyzed before any of its other functions can be called. (The exception to this is the @ref ENepanet function, which performs a complete hydraulic/water quality simulation similar to a command line execution of EPANET). Once all analysis is completed, it must close itself down to free all allocated memory. The functions for doing this are @ref ENopen and @ref ENclose, respectively. An example of using these functions is shown below.
-
-~~~~~~~~~~~~~~~{.c}
-char *f1,  // Name of input file  
-     *f2,  // name of report file 
-     *f3;  // name of output file (can be blank) 
-int  errcode; 
-errcode = ENopen(f1, f2, f3); 
-if (errcode > 0) { 
-  ENclose(); 
-  return; 
-} 
-{ Call functions that perform desired analysis } 
-ENclose();
-~~~~~~~~~~~~~~~
-
-@section parameters Retrieving and Setting Network Parameters
-
-The Toolkit has various functions available for retrieving and setting the parameters that define the design and operation of the pipe network being analyzed. The names of retrieval functions all begin with `ENget` (e.g., [ENgetnodevalue](ENgetnodevalue), [ENgetoption](ENgetoption), etc.) while the functions used for setting parameter values begin with `ENset` (e.g., [ENsetnodevalue](ENsetnodevalue), [ENsetoption](ENsetoption), etc.).
-
-Most of these functions use an index number to reference a specific network component (such as a node, link, or time pattern). 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 in the Input File being processed. A series of functions exist to determine a component's index number given its ID label (see [ENgetlinkindex](ENgetlinkindex), [ENgetnodeindex](ENgetnodeindex), and [ENgetpatternindex](ENgetpatternindex)). Likewise, functions exist to retrieve a component's ID label given its index number (see [ENgetlinkid](ENgetlinkid), [ENgetnodeid](ENgetnodeid), and [ENgetpatternid](ENgetpatternid)). The [ENgetcount](ENgetcount) function can be used to determine the number of different components in the network. 
-
-The code below is an example of using the parameter retrieval and setting functions. It changes all pipes with diameter of 10 inches to 12 inches. 
-
-~~~~~~~~~~~~~~~{.c}
-int   i, Nlinks; 
-float D; 
-ENgetcount(EN_LINKCOUNT, &Nlinks); 
-for (i = 1; i <= Nlinks; i++) { 
-  ENgetlinkvalue(i, EN_DIAMETER, &D); 
-  if (D == 10) ENsetlinkvalue(i, EN_DIAMETER, 12); 
-}
-~~~~~~~~~~~~~~~
-
-
-*/

doc/Toolkit-Overview.dox

@@ -1,23 +0,0 @@
-/** 
-@page toolkit-overview Toolkit Overview
-
-
-The Programmer's Toolkit is an extension of the EPANET simulation package. EPANET performs extended period simulation of hydraulic and water quality behavior within pressurized pipe networks. A network can consist of pipes, nodes (pipe junctions), pumps, valves and storage tanks or reservoirs. EPANET tracks the flow of water in each pipe, the pressure at each node, the height of water in each tank, and the concentration of a chemical species throughout the network during a multi-time period simulation. In addition to chemical species, water age and source tracing can also be simulated. 
-
-The Toolkit provides a series of functions that allow programmers to customize the use of EPANET's hydraulic and water quality solution engine to their own applications. Before using the Toolkit one should become familiar with the way that EPANET represents a pipe network and the design and operating information it requires to perform a simulation. This information can be obtained from reading EPANET's on-line Help file or from the EPANET Users Manual. 
-
-A typical usage of the Toolkit functions to analyze a distribution system might look as follows:
-
-1. Use the @ref ENopen function to open the Toolkit system, along with an EPANET [Input file](Input-File).
-2. Use the `ENsetxxx` series of functions to change selected system characteristics.  
-3. Run a full hydraulic simulation using the @ref ENsolveH function (which automatically saves results to a [Hydraulics file](Hydraulics-File)) or use the @ref ENopenH - @ref ENinitH - @ref ENrunH - @ref ENnextH - @ref ENcloseH series of functions to step through a hydraulic simulation, accessing results along the way with the `ENgetxxx` series of functions.  
-4. Run a full water quality simulation using @ref ENsolveQ (which automatically saves hydraulic and water quality results to an [Output file](Output-File)) or use the @ref ENopenQ - @ref ENinitQ - @ref ENrunQ - @ref ENnextQ (or @ref ENstepQ) - @ref ENcloseQ series of functions to step through a water quality simulation, accessing results along the way with the `ENgetxxx` series of functions.  
-5. Return to Step 2 to run additional analyses or use the @ref ENreport function to write a formatted report to the [Report file](Report-File).  
-6. Call the @ref ENclose function to close all files and release system memory.  
-
-More specific examples of using the functions can be found in the [Example Applications](Example-Applications) topic. 
-
-
-- @subpage how-to-use
-
-*/

doc/doxyfile

@@ -1,4 +1,4 @@
-# Doxyfile 1.8.11
+# Doxyfile 1.8.10
 
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project.
@@ -32,13 +32,13 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = EPANET
+PROJECT_NAME           = "OWA-EPANET Toolkit"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2.1
+PROJECT_NUMBER         = 2.2
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = ../epanet-owa-dox
+OUTPUT_DIRECTORY       = 
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -226,7 +226,7 @@ SEPARATE_MEMBER_PAGES  = NO
 # uses this value to replace tabs by spaces in code fragments.
 # Minimum value: 1, maximum value: 16, default value: 4.
 
-TAB_SIZE               = 2
+TAB_SIZE               = 4
 
 # This tag can be used to specify a number of aliases that act as commands in
 # the documentation. An alias has the form:
@@ -535,7 +535,7 @@ HIDE_COMPOUND_REFERENCE= NO
 # the files that are included by a file in the documentation of that file.
 # The default value is: YES.
 
-SHOW_INCLUDE_FILES     = YES
+SHOW_INCLUDE_FILES     = NO
 
 # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
 # grouped member an include statement to the documentation, telling the reader
@@ -694,7 +694,7 @@ FILE_VERSION_FILTER    =
 # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
 # tag is left empty.
 
-LAYOUT_FILE            = 
+LAYOUT_FILE            = DoxygenLayout.xml
 
 # The CITE_BIB_FILES tag can be used to specify one or more bib files containing
 # the reference definitions. This must be a list of .bib files. The .bib
@@ -749,12 +749,6 @@ WARN_IF_DOC_ERROR      = YES
 
 WARN_NO_PARAMDOC       = NO
 
-# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
-# a warning is encountered.
-# The default value is: NO.
-
-WARN_AS_ERROR          = NO
-
 # The WARN_FORMAT tag determines the format of the warning messages that doxygen
 # can produce. The string should contain the $file, $line, and $text tags, which
 # will be replaced by the file and line number from which the warning originated
@@ -781,10 +775,15 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../include \
-                         ../src \
-                         ../doc \
-                         ../
+INPUT                  = main.dox \
+                         toolkit-usage.dox \
+                         toolkit-examples.dox \
+                         toolkit-files.dox \
+                         input-file.dox \
+                         toolkit-units.dox \
+                         modules.dox \
+                         ../include/epanet2_enums.h \
+                         ../include/epanet2_2.h
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -806,8 +805,8 @@ INPUT_ENCODING         = UTF-8
 # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp,
 # *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h,
 # *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc,
-# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f, *.for, *.tcl,
-# *.vhd, *.vhdl, *.ucf, *.qsf, *.as and *.js.
+# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd,
+# *.vhdl, *.ucf, *.qsf, *.as and *.js.
 
 FILE_PATTERNS          = *.c \
                          *.cc \
@@ -856,7 +855,7 @@ FILE_PATTERNS          = *.c \
 # be searched for input files as well.
 # The default value is: NO.
 
-RECURSIVE              = NO
+RECURSIVE              = YES
 
 # The EXCLUDE tag can be used to specify files and/or directories that should be
 # excluded from the INPUT source files. This way you can easily exclude a
@@ -918,7 +917,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = 
+IMAGE_PATH             = .
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -934,10 +933,6 @@ IMAGE_PATH             =
 # Note that the filter must not add or remove lines; it is applied before the
 # code is scanned, but not when the output code is generated. If lines are added
 # or removed, the anchors will not be placed correctly.
-#
-# Note that for custom extensions or not directly supported extensions you also
-# need to set EXTENSION_MAPPING for the extension otherwise the files are not
-# properly processed by doxygen.
 
 INPUT_FILTER           = 
 
@@ -947,10 +942,6 @@ INPUT_FILTER           =
 # (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how
 # filters are used. If the FILTER_PATTERNS tag is empty or if none of the
 # patterns match the file name, INPUT_FILTER is applied.
-#
-# Note that for custom extensions or not directly supported extensions you also
-# need to set EXTENSION_MAPPING for the extension otherwise the files are not
-# properly processed by doxygen.
 
 FILTER_PATTERNS        = 
 
@@ -1068,7 +1059,7 @@ VERBATIM_HEADERS       = YES
 # rich C++ code for which doxygen's built-in parser lacks the necessary type
 # information.
 # Note: The availability of this option depends on whether or not doxygen was
-# generated with the -Duse-libclang=ON option for CMake.
+# compiled with the --with-libclang option.
 # The default value is: NO.
 
 CLANG_ASSISTED_PARSING = NO
@@ -1122,7 +1113,7 @@ GENERATE_HTML          = YES
 # The default directory is: html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_OUTPUT            = ../../epanet-owa-dox
+HTML_OUTPUT            = html
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).
@@ -1149,7 +1140,7 @@ HTML_FILE_EXTENSION    = .html
 # of the possible markers and block names see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_HEADER            = 
+HTML_HEADER            =
 
 # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
 # generated HTML page. If the tag is left blank doxygen will generate a standard
@@ -1159,7 +1150,7 @@ HTML_HEADER            =
 # that doxygen normally uses.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_FOOTER            = 
+HTML_FOOTER            = newfooter.html
 
 # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
 # sheet that is used by each HTML page. It can be used to fine-tune the look of
@@ -1184,7 +1175,7 @@ HTML_STYLESHEET        =
 # list). For an example see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  = 
+HTML_EXTRA_STYLESHEET  = extrastylesheet.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -1323,7 +1314,7 @@ GENERATE_HTMLHELP      = NO
 # written to the html output directory.
 # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
 
-CHM_FILE               = 
+CHM_FILE               =   owa_epanet.chm
 
 # The HHC_LOCATION tag can be used to specify the location (absolute path
 # including file name) of the HTML help compiler (hhc.exe). If non-empty,
@@ -1331,7 +1322,7 @@ CHM_FILE               =
 # The file has to be specified with full path.
 # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
 
-HHC_LOCATION           = 
+HHC_LOCATION           = "c:\Program Files (x86)\HTML Help Workshop\hhc.exe"
 
 # The GENERATE_CHI flag controls if a separate .chi index file is generated
 # (YES) or that it should be included in the master .chm file (NO).
@@ -1453,7 +1444,7 @@ ECLIPSE_DOC_ID         = org.doxygen.Project
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-DISABLE_INDEX          = NO
+DISABLE_INDEX          = YES
 
 # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
 # structure should be generated to display hierarchical information. If the tag
@@ -1480,7 +1471,7 @@ GENERATE_TREEVIEW      = YES
 # Minimum value: 0, maximum value: 20, default value: 4.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-ENUM_VALUES_PER_LINE   = 4
+ENUM_VALUES_PER_LINE   = 0
 
 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used
 # to set the initial width (in pixels) of the frame in which the tree is shown.
@@ -1658,7 +1649,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = NO
+GENERATE_LATEX         = YES
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1701,7 +1692,7 @@ COMPACT_LATEX          = NO
 # The default value is: a4.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-PAPER_TYPE             = a4
+PAPER_TYPE             = letter
 
 # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
 # that should be included in the LaTeX output. The package can be specified just
@@ -1729,7 +1720,7 @@ EXTRA_PACKAGES         =
 # to HTML_HEADER.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-LATEX_HEADER           = 
+LATEX_HEADER           = header.tex
 
 # The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the
 # generated LaTeX document. The footer should contain everything after the last
@@ -1740,7 +1731,7 @@ LATEX_HEADER           =
 # Note: Only use a user-defined footer if you know what you are doing!
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-LATEX_FOOTER           = 
+LATEX_FOOTER           =
 
 # The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined
 # LaTeX style sheets that are included after the standard style sheets created
@@ -1751,7 +1742,7 @@ LATEX_FOOTER           =
 # list).
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-LATEX_EXTRA_STYLESHEET = 
+LATEX_EXTRA_STYLESHEET =
 
 # The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the LATEX_OUTPUT output
@@ -1785,14 +1776,14 @@ USE_PDFLATEX           = YES
 # The default value is: NO.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-LATEX_BATCHMODE        = NO
+LATEX_BATCHMODE        = YES
 
 # If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the
 # index chapters (such as File Index, Compound Index, etc.) in the output.
 # The default value is: NO.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-LATEX_HIDE_INDICES     = NO
+LATEX_HIDE_INDICES     = YES
 
 # If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source
 # code with syntax highlighting in the LaTeX output.
@@ -1812,14 +1803,6 @@ LATEX_SOURCE_CODE      = NO
 
 LATEX_BIB_STYLE        = plain
 
-# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated
-# page will contain the date and time when the page was generated. Setting this
-# to NO can help when comparing the output of multiple runs.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_LATEX is set to YES.
-
-LATEX_TIMESTAMP        = NO
-
 #---------------------------------------------------------------------------
 # Configuration options related to the RTF output
 #---------------------------------------------------------------------------
@@ -2059,7 +2042,7 @@ MACRO_EXPANSION        = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = YES
+EXPAND_ONLY_PREDEF     = NO
 
 # If the SEARCH_INCLUDES tag is set to YES, the include files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -2175,7 +2158,7 @@ PERL_PATH              = /usr/bin/perl
 # powerful graphs.
 # The default value is: YES.
 
-CLASS_DIAGRAMS         = YES
+CLASS_DIAGRAMS         = NO
 
 # You can define message sequence charts within doxygen comments using the \msc
 # command. Doxygen will then run the mscgen tool (see:

doc/extrastylesheet.css

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

doc/footer.tex

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

doc/header.tex

@@ -0,0 +1,141 @@
+% 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 ---

doc/main.dox

@@ -1,12 +1,119 @@
-/** 
-@mainpage EPANET Open Source
+/**
+@mainpage Overview
 
-The EPANET Open-Source Library is a pressurized pipe network hydraulic and water quality analysis toolkit, originally developed by USEPA, written in C. 
+EPANET is a program that performs extended period simulation of hydraulic and water quality behavior within water distribution system pipe networks. A network can consist of pipes, nodes (pipe junctions), pumps, valves and storage tanks or reservoirs. EPANET tracks the flow of water in each pipe, the pressure at each node, the height of water in each tank, and the concentration of a chemical species throughout the network during a multi-time period simulation. In addition to chemical species, water age and source tracing can also be simulated.
 
-__Note:__ This repository is not affiliated with, or endorsed by, the USEPA. For the "official" release of EPANET (2.00.12 UI and Toolkit) please go to the [EPA's GitHub repo](https://github.com/USEPA/Water-Distribution-Network-Model) or [the USEPA website](http://www2.epa.gov/water-research/epanet). It is also not the graphical user interface version. This is the hydraulic and water quality solver engine.
+<table style = "border: 0px solid black">
+<tr><td style="vertical-align: top">
+@image html DistributionSystem.png
+@image latex DistributionSystem.eps
+</td></tr>
+</table>
 
-However, if you are interested in extending EPANET for academic, personal, or commercial use, then you've come to the right place. For community discussion, FAQ, and roadmapping of the project, go to the [Community Forum](http://community.wateranalytics.org/category/epanet). 
+The EPANET Programmer's Toolkit is a library of functions (or API) written in C that allow programmers to customize the use of EPANET's hydraulic and water quality solution engine to their own applications. Both EPANET and its toolkit were originally developed by the U.S. Environmental Protection Agency (USEPA).
 
-- @subpage toolkit-overview "Toolkit Overview"
+The OWA-EPANET Toolkit is an open-source version of the original EPANET Toolkit that extends its capabilities by:
+- providing a full set of functions to set and retrieve values for all parameters contained in a network model
+- allowing networks to be built completely from function calls instead of from an input file
+- allowing multiple projects to be analyzed in parallel in a thread-safe manner
+- adding the ability to use pressure dependent demands in hydraulic analyses
+- producing more robust results with regard to hydraulic convergence, low/zero flow conditions, and water quality mass balance
+- achieving faster run times for single period hydraulic analyses.
 
-*/
+Before using the OWA-EPANET Toolkit one should be familiar with the way that EPANET represents a pipe network, the design and operating information it requires, and the steps it uses to simulate a network's behavior. The following topics provide some introductory material on these subjects:
+- @subpage DataModel "Network Data Model"
+- @subpage 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>.
+
+__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.
+*/
+
+/**
+@page DataModel Network Data Model
+
+EPANET models a pipe network as a collection of links connected to nodes. The links represent pipes, pumps, and control valves. The nodes represent junctions, tanks, and reservoirs. The figure below illustrates how these objects can be connected to one another to form a network.
+
+<table style = "border: 0px solid black">
+<tr><td>
+@image html Network.png
+@image latex Network.eps
+</td></tr>
+</table>
+
+Junctions have a user-supplied water withdrawal rate (i.e., consumer demand) associated with them. Tanks are storage units whose water level changes over time. Reservoirs are boundary points where a fixed hydraulic head applies.
+
+Pipes have a length, diameter and roughness coefficient that determines their head loss as a function of flow rate. Pumps have either a constant power rating or a head curve that determines the head they add as a function of flow rate. Valves are used to regulate either flow or pressure. Controls can be applied to completely open or close a link or to adjust its setting (pump speed or valve setting).
+
+In addition to these physical objects an EPANET model can also contain the following data objects:
+- time patterns that allow demands, quality source strength and pump speed settings to vary at fixed
+intervals of time
+- data curves that describe relationships between two quantities, such as head versus flow for pumps and
+volume versus water level for tanks
+- simple controls that adjust a link's setting (such as a pump's status) based on node pressure, tank
+level, elapsed time, ot time of day
+- rule-based controls that consist of one or more premises that if true result in one set of actions
+being taken and if false result in a different set of actions being taken
+- water quality sources that introduce a chemical constituent into the network at specified nodes.
+
+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
+- whether to use a demand driven or a pressure driven analysis
+- hydraulic convergence criteria
+- 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>
+for more information on EPANET's data model.
+*/
+
+/**
+@page DataFlow Data Flow Diagram
+
+The EPANET Toolkit contains separate code modules for network building, hydraulic analysis, water quality analysis, and report generation. The data flow diagram for analyzing a pipe network is shown below. The processing steps depicted in this diagram can be summarized as follows:
+
+<table style = "border: 0px solid black">
+<tr><td>
+@image html DataFlow.png
+@image latex DataFlow.eps
+</td></tr>
+</table>
+
+- The network builder receives a description of the network being simulated either from an external input file (.inp) or from a series of function calls that create network objects and assign their properties via code. These data are stored in a Project data structure.
+
+- The hydraulics solver carries out an extended period hydraulic simulation. The results obtained at every time step can be written to an external, unformatted (binary) hydraulics file (.hyd). Some of these time steps might represent intermediate points in time where system conditions change because of tanks becoming full or empty or pumps turning on or off due to level controls or timed operation.
+
+- If a water quality simulation is requested, the water quality solver accesses the flow data from the hydraulics file as it computes substance transport and reaction throughout the network over each hydraulic time step. During this process it can write both the formerly computed hydraulic results as well as its water quality results for each preset reporting interval to an unformatted (binary) output file (.out). If no water quality analysis was called for, then the hydraulic results stored in the .hyd file can simply be written out to the binary output file at uniform reporting intervals.
+
+- If requested, a report writer reads back the computed simulation results from the binary output file (.out) for each reporting period and writes out selected values to a formatted report file (.rpt). Any error or warning messages generated during the run are also written to this file.
+
+Toolkit functions exist to carry out all of these steps under the programmer's control, including the ability to read and modify the contents of the Project data structure.
+*/
+
+/**
+@page ToolkitVersions Toolkit Versions
+
+The Toolkit comes with two sets of identical functions that programmers can utilize:
+- the single-threaded version of the Toolkit is compatible with previous releases and only works
+with single threaded applications.
+- the multi-threaded version allows users to create multiple EPANET data sets (called projects) that can be
+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.
+- Function names in the single-threaded library begin with \b EN while those in the multi-threaded
+library begin with \b EN_ .
+- The multi-threaded functions contain an additional argument that references a particular network project
+that the function is applied to.
+- The multi-threaded library contains two additional functions that allow users to create and delete
+EPANET projects.
+- The single-threaded library uses single precision for its floating point arguments while the
+multi-threaded library uses double precision.
+
+To avoid unnecessary duplication this document only discusses the multi-threaded version of the
+Toolkit.
+*/

doc/modules.dox

@@ -0,0 +1,387 @@
+/**
+@defgroup Project Project Functions
+These functions are used to manage a project.
+*/
+
+/**
+@defgroup Hydraulics Hydraulic Analysis Functions
+These functions are used to perform a hydraulic analysis.
+*/
+
+/**
+@defgroup Quality Water Quality Analysis Functions
+These functions are used to perform a water quality analysis.
+*/
+
+/**
+@defgroup Reporting Reporting Functions
+These functions are used to report simulation results.
+*/
+
+/**
+@defgroup Options Analysis Options Functions
+These functions are used to get and set analysis options.
+*/
+
+/**
+@defgroup Nodes Network Node Functions
+These functions are used for working with network nodes.
+*/
+
+/**
+@defgroup Demands Nodal Demand Functions
+These functions are used for managing nodal demands.
+*/
+
+/**
+@defgroup Links Network Link Functions
+These functions are used for working with network links.
+*/
+
+/**
+@defgroup Patterns Time Pattern Functions
+These functions are used for working with time patterns.
+*/
+
+/**
+@defgroup Curves Data Curve Functions
+These functions are used for working with data curves.
+*/
+
+/**
+@defgroup Controls Simple Control Functions
+These functions are used for working with simple conditional controls.
+*/
+
+/**
+@defgroup Rules Rule-Based Control Functions
+These functions are used for working with rule-based controls.
+*/
+
+/**
+@defgroup Enumerations Enumerated Types
+These are the toolkit's enumerated types whose members are used as function arguments.
+*/
+
+/**
+@addtogroup Project
+@{
+@fn int EN_createproject(EN_Project *ph)
+@fn int EN_deleteproject(EN_Project ph)
+@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_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_saveinpfile(EN_Project ph, const char *filename)
+@fn int EN_close(EN_Project ph)
+@}
+*/
+
+/**
+@addtogroup Hydraulics
+@{
+@fn int EN_solveH(EN_Project ph)
+@fn int EN_usehydfile(EN_Project ph, const char *filename)
+@fn int EN_openH(EN_Project ph)
+@fn int EN_initH(EN_Project ph, int initFlag)
+@fn int EN_runH(EN_Project ph, long *currentTime)
+@fn int EN_nextH(EN_Project ph, long *tStep)
+@fn int EN_saveH(EN_Project ph)
+@fn int EN_savehydfile(EN_Project ph, const char *filename)
+@fn int EN_closeH(EN_Project ph)
+@}
+*/
+
+/**
+@addtogroup Quality
+@{
+@fn int EN_solveQ(EN_Project ph)
+@fn int EN_openQ(EN_Project ph)
+@fn int EN_initQ(EN_Project ph, int saveFlag)
+@fn int EN_runQ(EN_Project ph, long *currentTime)
+@fn int EN_nextQ(EN_Project ph, long *tStep)
+@fn int EN_stepQ(EN_Project ph, long *timeLeft)
+@fn int EN_closeQ(EN_Project ph)
+@}
+*/
+
+/**
+@addtogroup Reporting
+@{
+@fn int EN_writeline(EN_Project ph, char *line)
+@fn int EN_report(EN_Project ph)
+@fn int EN_copyreport(EN_Project ph, 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_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)
+
+@}
+*/
+
+/**
+@addtogroup Options
+@{
+@fn int EN_getoption(EN_Project ph, int option, double *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)
+@fn int EN_gettimeparam(EN_Project ph, int param, long *value)
+@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)
+@}
+*/
+
+/**
+@addtogroup Nodes
+@{
+@fn int EN_addnode(EN_Project ph, char *id, int nodeType, int *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_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_deletedemand(EN_Project ph, int nodeIndex, int demandIndex)
+@fn int EN_getdemandindex(EN_Project p, int nodeIndex, 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)
+@}
+*/
+
+/**
+@addtogroup Links
+@{
+@fn int EN_addlink(EN_Project ph, char *id, int linkType, char *fromNode, char *toNode, int *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_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_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_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_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_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_setvertices(EN_Project ph, int index, double *x, double *y, int count)
+@}
+*/
+
+/**
+@addtogroup Patterns
+@{
+@fn int EN_addpattern(EN_Project ph, 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_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_setpatternvalue(EN_Project ph, int index, int period, double value)
+@fn int EN_getaveragepatternvalue(EN_Project ph, int index, double *value)
+@fn int EN_setpattern(EN_Project ph, int index, double *f, int len)
+@}
+*/
+
+/**
+@addtogroup Curves
+@{
+@fn int EN_addcurve(EN_Project ph, 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_getcurvevalue(EN_Project ph, int curveIndex, int pointIndex, double *x, double *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_setcurve(EN_Project ph, int index, double *xValues, double *yValues, int nPoints)
+@}
+*/
+
+/**
+@addtogroup Controls
+@{
+@fn int EN_addcontrol(EN_Project ph, int type, int linkIndex, double setting, int nodeIndex, double level, int *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_setcontrol(EN_Project ph, int index, int type, int linkIndex, double setting, int nodeIndex, double level)
+@}
+*/
+
+/**
+@addtogroup Rules
+@{
+@fn int EN_addrule(EN_Project ph, char *rule)
+@fn int EN_deleterule(EN_Project ph, int index)
+@fn int EN_getrule(EN_Project ph, int index, int *nPremises, int *nThenActions, int *nElseActions, double *priority)
+@fn int EN_getruleID(EN_Project ph, int index, char* id);
+@fn int EN_getpremise(EN_Project ph, int ruleIndex, int premiseIndex, int *logop,  int *object, int *objIndex,
+        int *variable, int *relop, int *status, double *value)
+@fn int EN_setpremise(EN_Project ph, int ruleIndex, int premiseIndex,
+                 int logop, int object, int objIndex, int variable, int relop, int status, double value)
+@fn int EN_setpremiseindex(EN_Project ph, int ruleIndex, int premiseIndex, int objIndex)
+@fn int EN_setpremisestatus(EN_Project ph, int ruleIndex, int premiseIndex, int status)
+@fn int EN_setpremisevalue(EN_Project ph, int ruleIndex, int premiseIndex, double value)
+@fn int EN_getthenaction(EN_Project ph, int ruleIndex, int actionIndex, int *linkIndex, int *status, double *setting)
+@fn int EN_setthenaction(EN_Project ph, int ruleIndex, int actionIndex, int linkIndex, int status, double setting)
+@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)
+@}
+*/
+
+/**
+@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_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
+\def EN_MISSING
+@}
+*/
+
+/**
+@defgroup ErrorCodes Error Codes
+
+| Code | Meaning                           |
+|------|---------                          |
+| 0    | No error                          |
+| 101  | Insufficient memory available     |
+| 102  | No network data available         |
+| 103  | Hydraulic solver not opened   |
+| 104  | No hydraulics for water quality analysis |
+| 105  | Water quality solver not opened |
+| 106  | No results saved to report on |
+| 107  | Hydraulics supplied from external file |
+| 108  | Cannot use external file while hydraulics solver is open |
+| 110  | Cannot solve network hydraulic equations |
+| 120  | Cannot solve water quality transport equations |
+|  ||
+| 200  | One or more errors in an input file |
+| 201  | Syntax error |
+| 202  | Function call contains an illegal numeric value |
+| 203  | Function call refers to an undefined node |
+| 204  | Function call refers to an undefined link |
+| 205  | Function call refers to an undefined time pattern |
+| 206  | Function call refers to an undefined curve |
+| 207  | Function call attempts to control a check valve pipe or a GPV valve |
+| 208  | Function call contains illegal PDA pressure limits |
+| 209  | Function call contains an illegal node property value |
+| 211  | Function call contains an illegal link property value |
+| 212  | Function call refers to an undefined Trace Node |
+| 213  | Function call contains an invalid option value |
+| 214  | Too many characters in a line of an input file |
+| 215  | Function call contains a duplicate ID label |
+| 216  | Function call refers to an undefined pump |
+| 217  | Invalid pump energy data |
+| 219  | Illegal valve connection to tank node |
+| 220  | Illegal valve connection to another valve |
+| 221  | Mis-placed clause in rule-based control |
+| 222  | Link assigned same start and end nodes |
+| 223  | Not enough nodes in network |
+| 224  | No tanks or reservoirs in network |
+| 225  | Invalid lower/upper levels for tank |
+| 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 |
+| 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 |
+| 253  | Function call refers to nonexistent demand category |
+| 254  | Function call refers to node with no coordinates |
+| 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 |
+|  ||
+| 301  | Identical file names used for different types of files |
+| 302  | Cannot open input file |
+| 303  | Cannot open report file |
+| 304  | Cannot open output file |
+| 305  | Cannot open hydraulics file |
+| 306  | Hydraulics file does not match network data |
+| 307  | Cannot read hydraulics file |
+| 308  | Cannot save results to binary file |
+| 309  | Cannot save results to report file |
+
+*/
+
+/**
+@defgroup WarningCodes Warning Codes
+
+| Code | Description                       |
+|------|---------                          |
+|1 | System hydraulically unbalanced - convergence to a hydraulic solution was not achieved in the allowed number of trials |
+|2 | System may be hydraulically unstable - hydraulic convergence was only achieved after the status of all links was held fixed |
+|3 | System disconnected - one or more nodes with positive demands were disconnected from all supply sources |
+|4 | Pumps cannot deliver enough flow or head - one or more pumps were forced to either shut down (due to insufficient head) or operate beyond the maximum rated flow |
+|5 | Valves cannot deliver enough flow - one or more flow control valves could not deliver the required flow even when fully open |
+|6 | System has negative pressures - negative pressures occurred at one or more junctions with positive demand |
+
+*/

doc/modules_controls.dox

@@ -1,12 +0,0 @@
-/**
-
-@defgroup Controls Managing Controls
-
-
-@addtogroup Controls
-@{
-@enum EN_ControlType
-@fn int ENgetcontrol(int controlIndex, int *controlType, int *linkIndex, EN_API_FLOAT_TYPE *setting, int *nodeIndex, EN_API_FLOAT_TYPE *level)
-@fn int ENsetcontrol(int cindex, int ctype, int lindex, EN_API_FLOAT_TYPE setting, int nindex, EN_API_FLOAT_TYPE level)
-@}
-*/

doc/modules_curves.dox

@@ -1,20 +0,0 @@
-/**
-
-@defgroup Curves
-
-
-@addtogroup Curves
-@{
-@fn int ENgetcurve(int curveIndex, char* id, int *nValues, EN_API_FLOAT_TYPE **xValues, EN_API_FLOAT_TYPE **yValues)
-@fn int ENgetheadcurveindex(int index, int *curveindex)
-@fn int ENgetpumptype(int index, int *type)
-@fn int ENgetheadcurve(int linkIndex, char *curveId)
-@fn int ENgetcurveindex(char *id, int *index)
-@fn int ENgetcurveid(int index, char *id)
-@fn int ENgetcurvelen(int index, int *len)
-@fn int ENgetcurvevalue(int index, int pnt, EN_API_FLOAT_TYPE *x, EN_API_FLOAT_TYPE *y)
-@fn int ENsetcurvevalue(int index, int pnt, EN_API_FLOAT_TYPE x, EN_API_FLOAT_TYPE y)
-@fn int ENsetcurve(int index, EN_API_FLOAT_TYPE *x, EN_API_FLOAT_TYPE *y, int len)
-@fn int ENaddcurve(char *id)
-@}
-*/

doc/modules_filemanagement.dox

@@ -1,20 +0,0 @@
-/**
-
-@defgroup FileManagement File Management
-
-
-
-
-
-
-@addtogroup FileManagement
-@{
-@fn int ENwriteline (char *line)
-@fn int ENreport ()
-@fn int ENresetreport ()
-@fn int ENsetreport (char *reportFormat)
-@fn int ENopen (char *inpFile, char *rptFile, char *binOutFile)
-@fn int ENsaveinpfile (char *filename)
-@fn int ENclose()
-@}
-*/

doc/modules_hydraulicfunctions.dox

@@ -1,41 +0,0 @@
-/**
-
-@defgroup HydraulicFunctions Hydraulic Analysis
-
-~~~~~~~~~~~~~~~{.c}
-int  errcode;
-long t, tstep;
-
-errcode = ENopenH();
-if (!errcode) {
-	errcode = ENinitH(EN_SAVE);
-	if (!errcode) {
-		do {
-			tstep = 0;
-			ERRCODE(ENrunH(&t));
-			ERRCODE(ENnextH(&tstep));
-		} while (tstep > 0);
-	}
-}
-
-ENcloseH();
-~~~~~~~~~~~~~~~
-
-
-
-@addtogroup HydraulicFunctions
-@{
-
-@fn int ENsolveH()
-@fn int ENsaveH()
-@fn int ENopenH()
-@fn int ENinitH(int initFlag)
-@fn int ENrunH(long *currentTime)
-@fn int ENnextH(long *tStep)
-@fn int ENcloseH()
-@fn int ENsavehydfile(char *filename)
-@fn int ENusehydfile(char *filename)
-@fn int ENgetstatistic(int code, EN_API_FLOAT_TYPE* value)
-
-@}
-*/

doc/modules_networkinfo.dox

@@ -1,16 +0,0 @@
-/**
-
-@defgroup NetworkInfo Network Info
-
-
-@addtogroup NetworkInfo
-@{
-@fn int ENgetcount (int code, int *count) 
-@fn int ENgetnodeindex (char *id, int *index) 
-@fn int ENgetnodeid (int index, char *id) 
-@fn int ENgetnodetype (int index, int *code)
-@fn int ENgetnodevalue (int index, int code, EN_API_FLOAT_TYPE *value)
-@fn int ENgetcoord (int index, EN_API_FLOAT_TYPE *x, EN_API_FLOAT_TYPE *y)
-@fn int ENsetcoord (int index, EN_API_FLOAT_TYPE x, EN_API_FLOAT_TYPE y)
-@}
-*/

doc/modules_patterns.dox

@@ -1,14 +0,0 @@
-/**
-
-@defgroup Patterns
-
-
-@addtogroup Patterns
-@{
-@fn int ENgetpatternindex (char *id, int *index)
-@fn int ENgetpatternid (int index, char *id)
-@fn int ENgetpatternlen (int index, int *len)
-@fn int ENgetpatternvalue (int index, int period, EN_API_FLOAT_TYPE *value)
-@fn int ENgetaveragepatternvalue (int index, EN_API_FLOAT_TYPE *value)
-@}
-*/

doc/modules_qualityfunctions.dox

@@ -1,17 +0,0 @@
-/**
-
-@defgroup QualityFunctions Water Quality Functions
-
-
-
-@addtogroup QualityFunctions
-@{
-@fn int ENsolveQ ()
-@fn int ENopenQ ()
-@fn int ENinitQ (int saveFlag)
-@fn int ENrunQ (long *currentTime)
-@fn int ENnextQ (long *tStep)
-@fn int ENstepQ (long *timeLeft)
-@fn int ENcloseQ ()
-@}
-*/

doc/modules_toolkitoptions.dox

@@ -1,14 +0,0 @@
-/**
-
-@defgroup ToolkitOptions Toolkit Options
-
-
-@addtogroup ToolkitOptions
-@{
-@fn int ENgetoption (int code, EN_API_FLOAT_TYPE *value)
-@fn int ENgettimeparam (int code, long *value)
-@fn int ENgetflowunits (int *code)
-@fn int ENgetqualtype (int *qualcode, int *tracenode)
-@fn int ENgeterror (int errcode, char *errmsg, int maxLen)
-@}
-*/

doc/newfooter.html

@@ -0,0 +1,15 @@
+<!-- HTML footer for doxygen 1.8.10-->
+<!-- start footer part -->
+<!--BEGIN GENERATE_TREEVIEW-->
+<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> -->
+  </ul>
+</div>
+<!--END GENERATE_TREEVIEW-->
+<!--BEGIN !GENERATE_TREEVIEW-->
+<!--    <li class="footer">OWA-EPANET Toolkit 2.2 &copy 2019</li> -->
+<!--END !GENERATE_TREEVIEW-->
+</body>
+</html>

doc/readme.md

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

doc/toolkit-examples.dox

@@ -0,0 +1,229 @@
+/** @page ToolkitExamples Examples
+Here are several examples of how the Toolkit can be used for different types of network analyses.
+
+- @subpage Example1 "Embedded Engine Example"
+- @subpage Example2 "Network Building Example"
+- @subpage Example3 "Hydrant Rating Curve Example"
+- @subpage Example4 "Chlorine Dosage Example"
+
+*/
+
+/** @page Example1 Embedded Engine Example
+This example shows how simple it is for the Toolkit to provide a network analysis engine for other applications. There are three steps that the application would need to take:
+-# Have the application write network data to an EPANET-formatted input file.
+
+-# Create a project and call @ref EN_runproject, supplying the name of the EPANET input file, the name of a Report file where status and error messages are written, and the name of a binary Output file which will contain analysis results.
+
+-# Have the application access the output file to display desired analysis results (see @ref OutFile).
+
+Here is an example where a callback function `writeConsole` is provided to write EPANET's progress messages to the console:
+
+\code {.c}
+#include "epanet2_2.h"
+
+void  writeConsole(char *s)
+{
+    fprintf(stdout, "\n%s", s);
+}
+
+int runEpanet(char* inpFile, char* rptFile, char* outFile)
+{
+    int errcode;
+    EN_project ph;
+    EN_createproject(&pH);
+    errcode = EN_runproject(ph, inpFile, rptFile, outFile, &writeConsole);
+    EN_deleteproject(ph);
+    return errcode;
+}
+\endcode
+*/
+
+/** @page Example2 Network Building Example
+This example shows how a network can be built just through toolkit function calls, eliminating the
+need to always use an EPANET formatted input file. This creates opportunities to use other sources
+of network data in one's code, such as relational database files or GIS/CAD files.
+
+Below is a schematic of the network to be built.
+<table style = "border: 0px solid black">
+<tr><td>
+@image html Example2.png
+@image latex Example2.eps
+</td></tr>
+</table>
+
+\code {.c}
+#include "epanet2_2.h"
+
+void netbuilder()
+{
+    // Create a project that uses gpm for flow units and
+    // the Hazen-Williams formula for head loss
+    int index;
+    EN_Project ph;
+    EN_createproject(&ph);
+    EN_init(ph, "", "", EN_GPM, EN_HW);
+
+    // Add the first junction node to the project with
+    // an elevation of 700 ft and a demand of 0
+    EN_addnode(ph, "J1", EN_JUNCTION, &index);
+    EN_setjuncdata(ph, index, 700, 0, "");
+
+    // Add the remaining two junctions with elevations of
+    //  710 ft and demands of 250 and 500 gpm, respectively
+    EN_addnode(ph, "J2", EN_JUNCTION, &index);
+    EN_setjuncdata(ph, index, 710, 250, "");
+    EN_addnode(ph, "J3", EN_JUNCTION, &index);
+    EN_setjuncdata(ph, index, 710, 500, "");
+
+    // Add the reservoir at an elevation of 650 ft
+    EN_addnode(ph, "R1", EN_RESERVOIR, &index);
+    EN_setnodevalue(ph, index, EN_ELEVATION, 650);
+
+    // Add the tank node at elevation of 850 ft, initial water level
+    // at 120 ft, minimum level at 100 ft, maximum level at 150 ft
+    // and a diameter of 50.5 ft
+    EN_addnode(ph, "T1", EN_TANK, &index);
+    EN_settankdata(ph, index, 850, 120, 100, 150, 50.5, 0, "");
+
+    // Add the pipes to the project, setting their length,
+    // diameter, and roughness values
+    EN_addlink(ph, "P1", EN_PIPE, "J1", "J2", &index);
+    EN_setpipedata(ph, index, 10560, 12, 100, 0);
+    EN_addlink(ph, "P2", EN_PIPE, "J1", "T1", &index);
+    EN_setpipedata(ph, index, 5280, 14, 100, 0);
+    EN_addlink(ph, "P3", EN_PIPE, "J1", "J3", &index);
+    EN_setpipedata(ph, index, 5280, 14, 100, 0);
+    EN_addlink(ph, "P4", EN_PIPE, "J2", "J3", &index);
+    EN_setpipedata(ph, index, 5280, 14, 100, 0);
+
+    // Add a pump to the project
+    EN_addlink(ph, "PUMP", EN_PUMP, "R1", "J1", &index);
+
+    // Create a single point head curve (index = 1) and
+    // assign it to the pump
+    EN_addcurve(ph, "C1");
+    EN_setcurvevalue(ph, 1, 1, 1500, 250);
+    EN_setlinkvalue(ph, index, EN_PUMP_HCURVE, 1);
+
+    // Save the project for future use
+    EN_saveinpfile(ph, "example2.inp");
+
+    // Delete the project
+    EN_deleteproject(ph);
+}
+\endcode
+*/
+
+/** @page Example3 Hydrant Rating Curve Example
+
+This example illustrates how the Toolkit could be used to develop a hydrant rating curve used in fire flow studies. This curve shows the amount of flow available at a node in the system as a function of pressure. The curve is generated by running a number of steady state hydraulic analyses with the node of interest subjected to a different demand in each analysis. For this example we assume that the ID label of the node of interest is `MyNode` and that `N` different demand levels stored in the array `D` need to be examined. The corresponding pressures will be stored in `P`. To keep the code more readable, no error checking is made on the results returned from the Toolkit function calls.
+
+\code {.c}
+#include "epanet2_2.h"
+
+void HydrantRating(char *MyNode, int N, double D[], double P[])
+{
+    EN_Project ph;
+    int   i, nodeindex;
+    long  t;
+    double pressure;
+
+    // Create a project
+    EN_createproject(&ph);
+
+    // Retrieve network data from an input file
+    EN_open(ph, "example2.inp", "example2.rpt", "");
+
+    // Open the hydraulic solver
+    EN_openH(ph);
+
+    // Get the index of the node of interest
+    EN_getnodeindex(ph, MyNode, &nodeindex);
+
+    // Iterate over all demands
+    for (i=1; i<N; i++)
+    {
+        // Set nodal demand, initialize hydraulics, make a
+        // single period run, and retrieve pressure
+        EN_setnodevalue(ph, nodeindex, EN_BASEDEMAND, D[i]);
+        EN_initH(ph, 0);
+        EN_runH(ph, &t);
+        EN_getnodevalue(ph, nodeindex, EN_PRESSURE, &pressure);
+        P[i] = pressure;
+    }
+
+    // Close hydraulics solver & delete the project
+    EN_closeH(ph);
+    EN_deleteproject(ph);
+}
+\endcode
+*/
+
+/** @page Example4 Chlorine Dosage Example
+
+This example illustrates how the Toolkit could be used to determine the lowest dose of chlorine applied at the entrance to a distribution system needed to ensure that a minimum residual is met throughout the system. We assume that the EPANET input file contains the proper set of kinetic coefficients that describe the rate at which chlorine will decay in the system being studied. In the example code, the ID label of the source node is contained in `SourceID`, the minimum residual target is given by `Ctarget`, and the target is only checked after a start-up duration of 5 days (432,000 seconds). To keep the code more readable, no error checking is made on the results returned from the Toolkit function calls.
+
+\code {.c}
+#include "epanet2_2.h"
+
+double cl2dose(char *SourceID, double Ctarget)
+{
+    int i, nnodes, sourceindex, violation;
+    double c, csource;
+    long t, tstep;
+    EN_Project ph;
+
+    // Open the toolkit & obtain a hydraulic solution
+    EN_createproject(&ph);
+    EN_open(ph, "example3.inp", "example3.rpt", "");
+    EN_solveH(ph);
+
+    // Get the number of nodes and the source node's index
+    EN_getcount(ph, EN_NODECOUNT, &nnodes);
+    EN_getnodeindex(ph, SourceID, &sourceindex);
+
+    // Setup the system to analyze for chlorine
+    // (in case it was not done in the input file)
+    EN_setqualtype(ph, EN_CHEM, "Chlorine", "mg/L", "");
+
+    // Open the water quality solver
+    EN_openQ(ph);
+
+    // Begin the search for the source concentration
+    csource = 0.0;
+    do {
+
+        // Update source concentration to next level
+        csource = csource + 0.1;
+        EN_setnodevalue(ph, sourceindex, EN_SOURCEQUAL, csource);
+
+        // Run WQ simulation checking for target violations
+        violation = 0;
+        EN_initQ(ph, 0);
+        do {
+            EN_runQ(ph, &t);
+            if (t > 432000) {
+                for (i=1; i<=nnodes; i++) {
+                    EN_getnodevalue(ph, i, EN_QUALITY, &c);
+                    if (c < Ctarget) {
+                        violation = 1;
+                        break;
+                    }
+                }
+            }
+            EN_nextQ(ph, &tstep);
+
+        // End WQ run if violation found
+        } while (!violation && tstep > 0);
+
+    // Continue search if violation found
+    } while (violation && csource <= 4.0);
+
+    // Close up the WQ solver and delete the project
+    EN_closeQ(ph);
+    EN_deleteproject(ph);
+    return csource;
+}
+\endcode
+
+*/

doc/toolkit-files.dox

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

doc/toolkit-units.dox

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

doc/toolkit-usage.dox

@@ -0,0 +1,243 @@
+/**
+@page toolkit-usage Usage
+
+The following topics briefly describe how to accomplish some basic tasks using the OWA-EPANET Toolkit in C/C++ code. See the @ref ToolkitExamples topic for code listings of complete applications of the Toolkit.
+
+@section CreateProject Creating a Project
+
+Before any use is made of the Toolkit, a project and its handle must be created. After all processing is completed the project should be deleted. See the code snippet below:
+
+\code {.c}
+EN_Project ph;  // a project handle
+EN_createproject(&ph);
+
+// Call functions that perform desired analysis
+
+EN_deleteproject(ph);
+\endcode
+
+@section DetectingErrors Detecting Error Conditions
+
+All of the Toolkit functions return an error/warning code. A 0 indicates that the function ran successfully. A number greater than 0 but less than 100 indicates that a warning condition was generated while a number higher than 100 indicates that the function failed.
+
+The meaning of specific error and warning codes are listed in the @ref ErrorCodes and @ref WarningCodes sections of this guide. The Toolkit function @ref EN_geterror can be used to obtain the text of a specific error/warning code. The following example uses a macro named `ERRCODE` along with a variable named `errcode` to execute Toolkit commands only if no fatal errors have already been detected:
+
+\code {.c}
+#define ERRCODE(x) (errcode = ((errcode > 100) ? (errcode) : (x)))
+
+void runHydraulics(EN_Project ph, char *inputFile, char *reportFile)
+{
+    int errcode = 0;
+    char errmsg[EN_MAXMSG + 1];
+
+    ERRCODE(EN_open(ph, inputFile, reportFile, ""));
+    ERRCODE(EN_solveH(ph));
+    ERRCODE(EN_saveH(ph));
+    ERRCODE(EN_report(ph));
+    EN_geterror(ph, errcode, errmsg);
+    if (errcode) printf("\n%s\n", errmsg);
+}
+\endcode
+
+@section NetworkData Providing Network Data
+
+Once a project is created there are two ways in which it can be populated with data. The first is to use the @ref EN_open function to load an EPANET-formatted @ref InpFile that provides a description of the network to be analyzed. This function should be called immediately after a project is created. It takes as arguments the name of the input file to open and the names of a report file and a binary output file, both of which are optional. Here is a code sample showing this approach:
+
+\code {.c}
+EN_Project ph;
+int  errcode;
+EN_createproject(&ph);
+errcode = EN_open(ph, "net1.inp", "net1.rpt", "");
+if (errcode == 0)
+{
+    // Call functions that perform desired analysis
+}
+EN_deleteproject(ph);
+\endcode
+
+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:
+
+\code {.c}
+int index;
+EN_Project ph;
+EN_createproject(&ph);
+EN_init(ph, "net1.rpt", "", EN_GPM, EN_HW);
+EN_addnode(ph, "J1", EN_JUNCTION, &index);
+EN_addnode(ph, "J2", EN_JUNCTION, &index);
+EN_addlink(ph, "P1", EN_PIPE, "J1", "J2", &index);
+// additional function calls to complete building the network
+\endcode
+
+See the @ref Example2 for a more complete example. The labels used to name objects cannot contain spaces, semi-colons, or double quotes nor exceed @ref EN_SizeLimits "EN_MAXID" characters in length. While adding objects their properties can be set as described in the next section. Attemtping to change a network's structure by adding or deleting nodes and links while the Toolkit's hydraulic or water quality solvers are open will result in an error condition.
+
+@section Properties Setting Object Properties
+
+The Toolkit contains several functions for retrieving and setting the properties of a network's objects and its analysis options. The names of retrieval functions all begin with \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.
+
+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.
+
+\code {.c}
+void changeDiameters(EN_Project ph)
+{
+    int   i, nLinks;
+    double diam;
+    EN_getcount(ph, EN_LINKCOUNT, &nLinks);
+    for (i = 1; i <= nLinks; i++)
+    {
+        EN_getlinkvalue(ph, i, EN_DIAMETER, &diam);
+        if (diam == 10) EN_setlinkvalue(ph, i, EN_DIAMETER, 12);
+    }
+}
+\endcode
+
+@section hydraulics Computing Hydraulics
+
+There are two ways to use the Toolkit to run a hydraulic analysis:
+-# Use the @ref EN_solveH function to run a complete extended period analysis, without having access to intermediate results.
+-# Use the @ref EN_openH - @ref EN_initH - @ref EN_runH - @ref EN_nextH - @ref EN_closeH series of functions to step through the simulation one hydraulic time step at a time.
+
+Method 1 is useful if you only want to run a single hydraulic analysis, perhaps to provide input to a water quality analysis. With this method hydraulic results are always saved to an intermediate hydraulics file at every time step.
+
+Method 2 must be used if you need to access results between time steps or if you wish to run many analyses efficiently. To accomplish the latter, you would make only one call to \b EN_openH to begin the process, then make successive calls to <b>EN_initH - EN_runH - EN_nextH</b> to perform each analysis, and finally call \b EN_closeH to close down the hydraulics system. An example of this is shown below (calls to \b EN_nextH are not needed because we are only making a single period analysis in this example).
+
+\code {.c}
+void runHydraulics(EN_Project ph, int nRuns)
+{
+    int  i;
+    long t;
+    EN_openH(ph);
+    for (i = 1; i <= nRuns; i++)
+    {
+        // user-supplied function to set parameters
+        setparams(ph, i);
+        // initialize hydraulics; don't save them to file
+        EN_initH(ph, EN_NOSAVE);
+        // solve hydraulics
+        EN_runH(ph, &t);
+        // user-supplied function to process results
+        getresults(ph, i);
+    }
+    EN_closeH(ph);
+}
+\endcode
+
+@section quality Computing Water Quality
+
+As with a hydraulic analysis, there are two ways to carry out a water quality analysis:
+
+-# Use the @ref EN_solveQ function to run a complete extended period analysis, without having access to intermediate results. A complete set of hydraulic results must have been generated either from running a hydraulic analysis or from importing a saved hydraulics file from a previous run.
+-# Use the @ref EN_openQ - @ref EN_initQ - @ref EN_runQ - @ref EN_nextQ - @ref EN_closeQ series of functions to step through the simulation one hydraulic time step at a time. (Replacing @ref EN_nextQ with @ref EN_stepQ will step through one water quality time step at a time.)
+
+The second option can either be carried out after a hydraulic analysis has been run or simultaneously as hydraulics are being computed. Example code for these two alternatives is shown below:
+
+\code {.c}
+int runSequentialQuality(EN_Project ph)
+{
+    int err;
+    long t, tStep;
+    err = EN_solveH(ph);
+    if (err > 100) return err;
+    EN_openQ(ph);
+    EN_initQ(ph, EN_NOSAVE);
+    do {
+        EN_runQ(ph, &t);
+        // Access quality results for time t here
+        EN_nextQ(ph, &tStep);
+    } while (tStep > 0);
+    EN_closeQ(ph);
+    return 0;
+}
+
+int runConcurrentQuality(EN_Project ph)
+{
+    int err = 0;
+    long t, tStep;
+    EN_openH(ph);
+    EN_initH(ph, EN_NOSAVE);
+    EN_openQ(ph);
+    EN_initQ(ph, EN_NOSAVE);
+    do {
+        err = EN_runH(ph, &t);
+        if (err > 100) break;
+        EN_runQ(ph, &t);
+        // Access hydraulic & quality results for time t here
+        EN_nextH(ph, &tStep);
+        EN_nextQ(ph, &tStep);
+    } while (tStep > 0);
+    EN_closeH(ph);
+    EN_closeQ(ph);
+    return err;
+}
+\endcode
+
+@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)| |
+
+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}
+void getPressures(EN_Project ph)
+{
+    int   i, numNodes;
+    long  t, tStep;
+    double p;
+    char  id[EN_MAXID + 1];
+    EN_getcount(ph, EN_NODECOUNT, &numNodes);
+    EN_openH(ph);
+    EN_initH(ph, EN_NOSAVE);
+    do {
+        EN_runH(ph, &t);
+        for (i = 1; i <= NumNodes; i++) {
+            EN_getnodevalue(ph, i, EN_PRESSURE, &p);
+            EN_getnodeid(ph, i, id);
+            writetofile(t, id, p);
+        }
+        EN_nextH(&tStep);
+    } while (tStep > 0);
+    EN_closeH(ph);
+}
+\endcode
+
+@section report Producing a Report
+
+The Toolkit has some built-in capabilities to produce formatted output results saved to a file. More specialized reporting needs can always be handled by writing custom code.
+
+The @ref EN_setreport function is used to define the format of a report while the @ref EN_report function actually writes the report. The latter should be called only after a hydraulic or water quality analysis has been made. An example of creating a report that lists all nodes where the pressure variation over the duration of the simulation exceeds 20 psi is shown below:
+
+\code {.c}
+void reportPressureVariation(EN_Project ph)
+{
+    // Compute ranges (max - min)
+    EN_settimeparam(ph, EN_STATISTIC, EN_RANGE);
+
+    // Solve and save hydraulics
+    EN_solveH(ph);
+    EN_saveH(ph);
+
+    // Define contents of the report
+    EN_resetreport(ph);
+    EN_setreport(ph, "FILE myfile.rpt");
+    EN_setreport(ph, "NODES ALL");
+    EN_setreport(ph, "PRESSURE PRECISION 1");
+    EN_setreport(ph, "PRESSURE ABOVE 20");
+
+    // Write the report to file
+    EN_report(ph);
+}
+\endcode
+
+*/