From 55e2879e2d8fae8b7893a1c205102bbcbdf730c1 Mon Sep 17 00:00:00 2001 From: Lew Rossman Date: Wed, 30 Oct 2019 15:11:20 -0400 Subject: [PATCH] Updates the docs --- ReleaseNotes2_2.md | 4 ++ doc/input-file.dox | 130 ++++++++++++++++++++++++++++++++++++++---- doc/modules.dox | 5 ++ doc/toolkit-files.dox | 2 +- include/epanet2_2.h | 24 ++++++-- 5 files changed, 150 insertions(+), 15 deletions(-) diff --git a/ReleaseNotes2_2.md b/ReleaseNotes2_2.md index d2087e0..e565f1a 100644 --- a/ReleaseNotes2_2.md +++ b/ReleaseNotes2_2.md @@ -200,6 +200,10 @@ With this change EPANET 2.2 now produces perfect mass balances when tested again |`EN_setcomment` |Assigns a descriptive comment to an object| |`EN_clearreport` |Clears the contents of a project's report file | |`EN_copyreport` | Copies the contents of a project's report file | +|`EN_getresultindex` | Gets the order in which a node or link was saved to file | +|`EN_getvertexcount` | Gets the number of vertex points in a link | +|`EN_getvertex` | Gets the coordinates of a vertex point in a link | +|`EN_setvertices` | Assigns a new set of vertex points to a link | In addition to these new functions, a tank's volume curve `EN_VOLCURVE` can be set using `EN_setnodevalue` and `EN_setlinkvalue` can now be used to set the following pump properties: - `EN_PUMP_POWER` (constant power rating) - `EN_PUMP_HCURVE` (head characteristic curve) diff --git a/doc/input-file.dox b/doc/input-file.dox index 2a3e45b..cd4c103 100644 --- a/doc/input-file.dox +++ b/doc/input-file.dox @@ -4,16 +4,16 @@ The Input file is a standard EPANET input data file that describes the system be The file is organized by sections where each section begins with a keyword enclosed in brackets. The various keywords are listed below. Click on a section to see the format of the data it contains. -|Network Components |System Operation |Water Quality |Options & Reporting | -|:-------------------------------|:-------------------------------|:--------------------------------|:-------------------------------| -|@subpage TitlePage "[Title]" |@subpage CurvesPage "[Curves]" |@subpage QualPage "[Quality]" |@subpage OptionsPage "[Options]"| -|@subpage JuncsPage "[Junctions]"|@subpage PatsPage "[Patterns]" |@subpage ReactsPage "[Reactions]"|@subpage TimesPage "[Times]" | -|@subpage ResvPage "[Reservoirs]"|@subpage EnergyPage "[Energy]" |@subpage SourcesPage "[Sources]" |@subpage ReportPage "[Report]" | -|@subpage TanksPage "[Tanks]" |@subpage StatusPage "[Status]" |@subpage MixingPage "[Mixing]" | | -|@subpage PipesPage "[Pipes]" |@subpage CtrlsPage "[Controls]" | | | -|@subpage PumpsPage "[Pumps]" |@subpage RulesPage "[Rules]" | | | -|@subpage ValvesPage "[Valves]" |@subpage DmndsPage "[Demands]" | | | -|@subpage EmitsPage "[Emitters]" | | | | +|Network Components |System Operation |Water Quality |Options & Reporting |GUI Support | +|:-------------------------------|:-------------------------------|:--------------------------------|:-------------------------------|------------------------------------| +|@subpage TitlePage "[Title]" |@subpage CurvesPage "[Curves]" |@subpage QualPage "[Quality]" |@subpage OptionsPage "[Options]"|@subpage BackdropPage "[Backdrop]" | +|@subpage JuncsPage "[Junctions]"|@subpage PatsPage "[Patterns]" |@subpage ReactsPage "[Reactions]"|@subpage TimesPage "[Times]" |@subpage CoordsPage "[Coordinates]" | +|@subpage ResvPage "[Reservoirs]"|@subpage EnergyPage "[Energy]" |@subpage SourcesPage "[Sources]" |@subpage ReportPage "[Report]" |@subpage VertexPage "[Vertices]" | +|@subpage TanksPage "[Tanks]" |@subpage StatusPage "[Status]" |@subpage MixingPage "[Mixing]" | |@subpage LabelsPage "[Labels]" | +|@subpage PipesPage "[Pipes]" |@subpage CtrlsPage "[Controls]" | | | | +|@subpage PumpsPage "[Pumps]" |@subpage RulesPage "[Rules]" | | | | +|@subpage ValvesPage "[Valves]" |@subpage DmndsPage "[Demands]" | | | | +|@subpage EmitsPage "[Emitters]" | | | | | The order of sections is not important. However, whenever a node or link is referred to in a section it must have already been defined in the [JUNCTIONS], [RESERVOIRS], [TANKS], [PIPES], [PUMPS], or [VALVES] sections. Thus it is recommended that these sections be placed first. @@ -21,6 +21,8 @@ Each section can contain one or more lines of data. Blank lines can appear anywh The ID labels used to identify nodes, links, curves and patterns can be any combination of up to 31 characters and numbers. +The GUI Support sections are provided to assist an external program that wishes to draw a visual representation of a project's network. + */ /** @@ -1040,3 +1042,111 @@ __Remarks:__ |GPV (general purpose valve) | ID of head loss curve | 2. Shutoff valves and check valves are considered to be part of a pipe, not a separate control valve component (see @ref PipesPage). */ + +/** +@page BackdropPage [BACKDROP] + +__Purpose:__ + +Identifies a backdrop image and dimensions for visualizing the network's layout. + +__Formats:__ + + + + + +
DIMENSIONS LLx LLy URx URy
UNITS FEET/METERS/DEGREES/NONE
FILEfilename
OFFSETX Y
+ +__Definitions:__ + +DIMENSIONS provides the X and Y coordinates of the lower-left and upper-right corners of the network's +bounding rectangle. Defaults are the extents of the nodal coordinates supplied in the @ref CoordsPage "[COORDINATES]" section. + +UNITS specifies the units that the network's dimensions are given in. Default is NONE. + +FILE supplies the name of the file that contains a backdrop image for the network. + +OFFSET lists the X and Y distance that the upper-left corner of the backdrop image is offset from the +upper-left corner of the network’s bounding rectangle. Default is zero offset. + +__Remarks:__ + +1. The [BACKDROP] section is optional and only provides support for an external GUI program that uses the EPANET engine. + +2. Only Windows Enhanced Metafiles and bitmap files can be used as backdrops. +*/ + +/** +@page CoordsPage [COORDINATES] + +__Purpose:__ + +Assigns map coordinates to network's nodes. + +__Format__: + +One line for each node containing: +- Node ID label +- X-coordinate +- Y-coordinate + +__Remarks:__ + +1. Include one line for each node that has coordinates. + +2. The coordinates represent the distance from the node to an arbitrary origin at the lower left of the network. Any convenient units of measure for this distance can be used. + +3. The locations of the nodes need not be to actual scale. + +4. A [COORDINATES] section is optional and only provides support for an external GUI program that uses the EPANET engine. +*/ + +/** +@page VertexPage [VERTICES] + +__Purpose:__ + +Assigns interior vertex points that describe the shape of network links. + +__Format:__ + +One line for each vertex point in each link containing such points that includes: +- Link ID label +- X-coordinate +- Y-coordinate + +__Remarks:__ + +1. Vertex points allow links to be drawn as polylines instead of simple straight-lines between their end nodes. + +2. The coordinates refer to the same coordinate system used for node and label coordinates. + +3. A [VERTICES] section is optional and only provides support for an external GUI program that uses the EPANET engine. +*/ + +/** +@page LabelsPage [LABELS] + +__Purpose:__ + +Assigns coordinates to labels added to a network's visualization. + +__Format:__ + +One line for each label containing: +- X-coordinate +- Y-coordinate +- Text of label in double quotes +- ID label of an anchor node (optional) + +__Remarks:__ + +1. Include one line for each label. + +2. The coordinates refer to the upper left corner of the label and are with respect to an arbitrary origin at the lower left of the network. + +3. The optional anchor node anchors the label to the node when the network layout is re-scaled during zoom-in operations. + +4. The [LABELS] section is optional and only provides support for an external GUI program that uses the EPANET engine. +*/ diff --git a/doc/modules.dox b/doc/modules.dox index f0dd117..a26ec22 100644 --- a/doc/modules.dox +++ b/doc/modules.dox @@ -120,6 +120,8 @@ These are the toolkit's enumerated types whose members are used as function argu @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) + @} */ @@ -193,6 +195,9 @@ These are the toolkit's enumerated types whose members are used as function argu @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) @} */ diff --git a/doc/toolkit-files.dox b/doc/toolkit-files.dox index 799ded9..28266ff 100644 --- a/doc/toolkit-files.dox +++ b/doc/toolkit-files.dox @@ -151,7 +151,7 @@ The Toolkit provides several header files that are needed to develop C/C++ appli - `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. +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 diff --git a/include/epanet2_2.h b/include/epanet2_2.h index 926ab7d..d5c823a 100644 --- a/include/epanet2_2.h +++ b/include/epanet2_2.h @@ -638,6 +638,20 @@ typedef struct Project *EN_Project; */ int DLLEXPORT EN_getstatistic(EN_Project ph, int type, double* value); + /** + @brief Retrieves the order in which a node or link appears in an @ref OutFile "output file". + @param ph an EPANET project handle. + @param type a type of element (either @ref EN_NODE or @ref EN_LINK). + @param index the element's current index (starting from 1). + @param[out] value the order in which the element's results were written to file. + @return an error code. + + If the element does not appear in the file then its result index is 0. + + This function can be used to correctly retrieve results from an EPANET binary output file + after the order of nodes or links in a network's database has been changed due to editing + operations. + */ int DLLEXPORT EN_getresultindex(EN_Project ph, int type, int index, int *value); /******************************************************************** @@ -1217,7 +1231,7 @@ typedef struct Project *EN_Project; /** @brief Retrieves the number of internal vertex points assigned to a link. @param ph an EPANET project handle. - @param index a link's index. + @param index a link's index (starting from 1). @param[out] count the number of vertex points that describe the link's shape. @return an error code. */ @@ -1226,8 +1240,8 @@ typedef struct Project *EN_Project; /** @brief Retrieves the coordinate's of a vertex point assigned to a link. @param ph an EPANET project handle. - @param index a link's index. - @param vertex a vertex point index. + @param index a link's index (starting from 1). + @param vertex a vertex point index (starting from 1). @param[out] x the vertex's X-coordinate value. @param[out] y the vertex's Y-coordinate value. @return an error code. @@ -1237,11 +1251,13 @@ typedef struct Project *EN_Project; /** @brief Assigns a set of internal vertex points to a link. @param ph an EPANET project handle. - @param index a link's index. + @param index a link's index (starting from 1). @param x an array of X-coordinates for the vertex points. @param y an array of Y-coordinates for the vertex points. @param count the number of vertex points being assigned. @return an error code. + + Replaces any existing vertices previously assigned to the link. */ int DLLEXPORT EN_setvertices(EN_Project ph, int index, double *x, double *y, int count);