diff --git a/BUILDING.md b/BUILDING.md index 3d3052e..14cd45d 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1,6 +1,8 @@ -The most straightforward way to build the EPANET files is by using `CMake` ([https://cmake.org/](https://cmake.org/)). `CMake` is a cross-platform build tool. `CMake` generates platform native build systems that can be used with your compiler of choice. `CMake` uses a generator concept to represent different build tooling. `CMake` automatically detects the platform it is running on and generates the appropriate makefiles for the platform default compiler. Different generators can also be specified. +### How to Build OWA-EPANET -The project's `CMake` file (`CMakeLists.txt`) is located in its root directory and supports builds for Linux, Mac OS and Windows. To build the EPANET library and its command line executable using `CMake`, first open a console window and navigate to the project's root directory. Then enter the following commands: +The most straightforward way to build the OWA-EPANET project is by using `CMake` ([https://cmake.org/](https://cmake.org/)), a cross-platform build tool that generates platform native build systems that can be used with your compiler of choice. `CMake` uses a generator concept to represent different build tooling. It automatically detects the platform it is running on and generates the appropriate makefiles for the platform's default compiler. Different generators can also be specified. + +The project's `CMake` configuration file (`CMakeLists.txt`) is located in its root directory and supports builds for Linux, Mac OS and Windows. To build the EPANET library and its command line executable using `CMake`, first open a command prompt console window and navigate to the project's root directory. Then enter the following commands: ``` mkdir build cd build @@ -11,8 +13,8 @@ Note: Use `cmake -G "Visual Studio 15 2017 Win64" ..` as the third command for a Under Windows the resulting EPANET toolkit library `epanet2.dll` and its command line executable `runepanet.exe` will be in the `build\bin\Release` directory. The `build\lib\Release` directory contains an `epanet2.lib` file which is needed to build C/C++ applications using the Windows version of the library. For Linux and Mac OS the EPANET toolkit shared library `libepanet2.so` appears in the `build/lib` directory and the command line executable `runepanet` is in the `build/bin` directory. -In addition, two Windows one-click-build scripts are included in the `win_build` directory: -1. `Makefile2.bat`: this script uses the `CMake` file and requires the build tools for Visual Studio available from [https://visualstudio.microsoft.com/downloads/](https://visualstudio.microsoft.com/downloads/). The Community version will work just fine. This script was tested with Visual Studio 2017 and 2019. -2. `Makefile.bat`: this is the legacy build script compatible with Visual Studio 2010 which conforms with the C89 Standard which was the standard EPANET supported from earlier versions. This script requires the installation of Microsoft Windows SDK 7.1 ([https://www.microsoft.com/en-us/download/details.aspx?id=8279](https://www.microsoft.com/en-us/download/details.aspx?id=8279)). +As an alternative to using `CMake` for a Windows build, two one-click-build scripts are included in the `win_build` directory: +1. `Makefile2.bat`: this script requires both `CMake` and the build tools for Visual Studio (available from [https://visualstudio.microsoft.com/downloads/](https://visualstudio.microsoft.com/downloads/) be installed on your machine. It can be executed from any command prompt window. The Community version of Visual Studio will work just fine. This script was tested with both Visual Studio 2017 and 2019. +2. `Makefile.bat`: this build script uses only Visual Studio commands and does not require `CMake`. It is compatible with both Visual Studio 2010 and 2017 and should be executed from a Visual Studio x86 Native Tools command prompt window. Both scripts will build the EPANET library and the command line executable for the 32 and 64 bit Windows platforms, placing them in the `win_build\32bit` and `win_build\64bit` directories, respectively. \ No newline at end of file diff --git a/doc/input-file.dox b/doc/input-file.dox index 4d8ce9b..2a3e45b 100644 --- a/doc/input-file.dox +++ b/doc/input-file.dox @@ -344,7 +344,7 @@ The \b HYDRAULICS option allows you to either SAVE the current hydraulics \b MINIMUM PRESSURE is the pressure below which no demand can be delivered under a pressure driven analysis. It has no effect on a demand driven analysis. Its default value is 0. -\b REQUIRED PRESSURE is the pressure required to supply a node's full demand under a pressure driven analysis. It has no effect on a demand driven analysis. Its default value is 0. +\b REQUIRED PRESSURE is the pressure required to supply a node's full demand under a pressure driven analysis. It has no effect on a demand driven analysis. It must be at least 0.1 psi or m higher than the MINIMUM PRESSURE, which is also its default value. \b PRESSURE EXPONENT is the power to which pressure is raised when computing the demand delivered to a node under a pressure driven analysis. It has no effect on a demand driven analysis. Its default value is 0.5. diff --git a/doc/main.dox b/doc/main.dox index b5c4d1c..347ae24 100755 --- a/doc/main.dox +++ b/doc/main.dox @@ -1,13 +1,17 @@ /** @mainpage Overview -EPANET is a program that performs extended period simulation of hydraulic and water quality behavior within water distribution system pipe networks. A network can consist of pipes, nodes (pipe junctions), pumps, valves and storage tanks or reservoirs. EPANET tracks the flow of water in each pipe, the pressure at each node, the height of water in each tank, and the concentration of a chemical species throughout the network during a multi-time period simulation. In addition to chemical species, water age and source tracing can also be simulated. The EPANET Programmer's Toolkit is a library of functions (or API) that allow programmers to customize the use of EPANET's hydraulic and water quality solution engine to their own applications. Both EPANET and its toolkit were originally developed and are currently maintained by the U.S. Environmental Protection Agency (USEPA). +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. +
@image html DistributionSystem.png @image latex DistributionSystem.eps - +
+ +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). + 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 @@ -15,8 +19,6 @@ The OWA-EPANET Toolkit is an open-source version of the original EPANET Toolkit - adding the ability to use pressure dependent demands in hydraulic analyses - producing more robust results with regard to hydraulic convergence, low/zero flow conditions, and water quality mass balance - achieving faster run times for single period hydraulic analyses. - - 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" @@ -45,23 +47,24 @@ Junctions have a user-supplied water withdrawal rate (i.e., consumer demand) ass 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 inflows and pump speed settings to vary at fixed +- 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. +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 -- the type of water quality analysis to perform - time steps used for hydraulic, water quality and reporting -- global values for reaction coefficients that can be overridden for individual pipes +- 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 EPANET 2 Users Manual @@ -94,15 +97,16 @@ Toolkit functions exist to carry out all of these steps under the programmer's c /** @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 +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: +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_. +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 @@ -111,5 +115,5 @@ EPANET projects. multi-threaded library uses double precision. To avoid unnecessary duplication this document only discusses the multi-threaded version of the -toolkit. +Toolkit. */ diff --git a/doc/modules.dox b/doc/modules.dox index 16d82c5..f0dd117 100644 --- a/doc/modules.dox +++ b/doc/modules.dox @@ -321,6 +321,7 @@ These are the toolkit's enumerated types whose members are used as function argu | 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 | diff --git a/doc/newfooter.html b/doc/newfooter.html index b1b6ac2..6ef6196 100644 --- a/doc/newfooter.html +++ b/doc/newfooter.html @@ -4,12 +4,12 @@ -
  • OWA-EPANET Toolkit 2.2 © 2019
    • + diff --git a/doc/toolkit-files.dox b/doc/toolkit-files.dox index acf2a85..799ded9 100644 --- a/doc/toolkit-files.dox +++ b/doc/toolkit-files.dox @@ -4,6 +4,7 @@ The Toolkit can make use of several different types of files when analyzing a pi - @subpage RptFile "Report File" - @subpage OutFile "Output File" - @subpage HydFile "Hydraulics File" +- @subpage HeaderFiles "Header Files" */ /** @@ -142,3 +143,20 @@ Likewise, a previously saved Hydraulics file can be used if the command `HYDR 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: +- `epanet2.h` contains declarations of the single-threaded version of the Toolkit (the ENxxx named functions). +- `epanet2_2.h` contains declarations of the multi-threaded version of the Toolkit (the EN_xxx named functions). +- `epanet2_enums.h` contains definitions of the symbolic constants used by the Toolkit. +- `epanet2.lib` 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: +- `epanet2.bas` for Visual Basic for Applications and Visual Basic 6 +- `epanet2.vb` for Visual Basic .NET +- `epanet2.pas` for Delphi Pascal, Free Pascal or Lazarus. + +These bindings only support the single-threaded version of the Toolkit. +*/ diff --git a/doc/toolkit-usage.dox b/doc/toolkit-usage.dox index 1c4d8cf..3bf06de 100644 --- a/doc/toolkit-usage.dox +++ b/doc/toolkit-usage.dox @@ -1,7 +1,7 @@ /** @page toolkit-usage Usage -The following topics briefly describe how to accomplish some basic tasks using the OWA-EPANET Toolkit. See the @ref ToolkitExamples topic for code listings of complete applications of the Toolkit. +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 @@ -180,12 +180,13 @@ The @ref EN_getnodevalue and @ref EN_getlinkvalue functions can also be used to |For Nodes: | For Links: | |----------------------------------- | ----------------------------------------- | |\b EN_DEMAND (demand) |\b EN_FLOW (flow rate) | -|\b EN_HEAD (hydraulic head) |\b EN_VELOCITY (flow velocity) | -|\b EN_PRESSURE (pressure) |\b EN_HEADLOSS (head loss) | -|\b EN_TANKLEVEL (tank water level) |\b EN_STATUS (link status) | -|\b EN_TANKVOLUME (tank water volume) |\b EN_SETTING (pump speed or valve setting) | -|\b EN_QUALITY (water quality) |\b EN_ENERGY (pump energy usage) | -|\b EN_SOURCEMASS (source mass inflow)|\b EN_PUMP_EFFIC (pump efficiency) | +|\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}