From 6e7cf5f02a0ee82d40261d406be1aaaa270b9dea Mon Sep 17 00:00:00 2001 From: Sam Hatchett Date: Mon, 30 Nov 2015 12:02:01 -0500 Subject: [PATCH] more dox, nesting pages #33 --- doc/How-to-use-the-toolkit.dox | 43 ++++++++++++++++++++++++++++++++++ doc/Toolkit-Overview.dox | 23 ++++++++++++++++++ doc/doxyfile | 2 +- doc/{main.md => main.dox} | 7 ++++-- doc/modules.dox | 0 doc/modules_controls.dox | 4 ---- 6 files changed, 72 insertions(+), 7 deletions(-) create mode 100644 doc/How-to-use-the-toolkit.dox create mode 100644 doc/Toolkit-Overview.dox rename doc/{main.md => main.dox} (90%) delete mode 100644 doc/modules.dox diff --git a/doc/How-to-use-the-toolkit.dox b/doc/How-to-use-the-toolkit.dox new file mode 100644 index 0000000..503990d --- /dev/null +++ b/doc/How-to-use-the-toolkit.dox @@ -0,0 +1,43 @@ +/** +@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); +} +~~~~~~~~~~~~~~~ + + +*/ \ No newline at end of file diff --git a/doc/Toolkit-Overview.dox b/doc/Toolkit-Overview.dox new file mode 100644 index 0000000..85fc282 --- /dev/null +++ b/doc/Toolkit-Overview.dox @@ -0,0 +1,23 @@ +/** +@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 + +*/ \ No newline at end of file diff --git a/doc/doxyfile b/doc/doxyfile index ae5fd65..e53d875 100644 --- a/doc/doxyfile +++ b/doc/doxyfile @@ -943,7 +943,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = main.md +USE_MDFILE_AS_MAINPAGE = #--------------------------------------------------------------------------- # Configuration options related to source browsing diff --git a/doc/main.md b/doc/main.dox similarity index 90% rename from doc/main.md rename to doc/main.dox index 79ccd00..19e54f5 100755 --- a/doc/main.md +++ b/doc/main.dox @@ -1,5 +1,5 @@ -EPANET Open-Source {#epanet_readme} -====== +/** +@mainpage EPANET Open Source The EPANET Open-Source Library is a pressurized pipe network hydraulic and water quality analysis toolkit, originally developed by USEPA, written in C. @@ -7,3 +7,6 @@ __Note:__ This repository is not affiliated with, or endorsed by, the USEPA. For 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). +- @subpage toolkit-overview "Toolkit Overview" + +*/ \ No newline at end of file diff --git a/doc/modules.dox b/doc/modules.dox deleted file mode 100644 index e69de29..0000000 diff --git a/doc/modules_controls.dox b/doc/modules_controls.dox index a9897a6..820c32a 100644 --- a/doc/modules_controls.dox +++ b/doc/modules_controls.dox @@ -3,10 +3,6 @@ @defgroup Controls Managing Controls - - - - @addtogroup Controls @{ @enum EN_ControlType