4d8d82ddc2
* 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
164 lines
11 KiB
Plaintext
164 lines
11 KiB
Plaintext
/** @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.
|
|
*/
|