Merge branch 'OpenWaterAnalytics:dev' into dev

doc/main.dox

@@ -51,7 +51,7 @@ 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
+level, elapsed time, or 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.

doc/toolkit-input.dox

@@ -344,7 +344,7 @@ __Definitions:__
 
 For <b>CFS, GPM, MGD, IMGD</b>, and <b>AFD</b> other input quantities are expressed in US Customary Units. If flow units are in liters or cubic meters then Metric Units must be used for all other input quantities as well. (See the @ref Units topic). The default flow units are \b GPM.
 
-\b PRESSURE sets the units in which pressure is expressed, for networks using metric units, as determined by the \b UNITS option, the choices are: (\b KPA), or (\b METERS). For networks using US Customary Units, you can only use (\b PSI).
+\b PRESSURE sets the units in which pressure is expressed, for networks using metric units, as determined by the \b UNITS option, the choices are: \b KPA, or \b METERS. For networks using US Customary Units, you can only use \b PSI.
 
 \b HEADLOSS selects a formula to use for computing head loss for flow through a pipe. The choices are the Hazen-Williams (\b H-W ), Darcy-Weisbach (\b D-W ), or Chezy-Manning (\b C-M ) formulas. The default is \b H-W.
 
@@ -526,7 +526,7 @@ One line per node containing:
 
 __Remarks:__
 1. Quality is assumed to be zero for nodes not listed.
-2. Quality represents concentration for chemicals, hours for water age, or percent for source tracing.
+2. Quality represents concentration for chemicals or hours for water age. Values for source tracing are not required and will be ignored.
 3. The <b>[QUALITY]</b> section is optional.
 */
 
@@ -617,6 +617,8 @@ __Definitions:__
 
 \b SUMMARY determines whether a summary table of number of network components and key analysis options is generated. The default is \b YES.
 
+\b MESSAGES determines whether error and warning messages are reported. The default is \b YES.
+
 \b ENERGY determines if a table reporting average energy usage and cost for each pump is provided. The default is \b NO.
 
 \b NODES identifies which nodes will be reported on. You can either list individual node ID labels or use the keywords \b NONE or \b ALL. Additional \b NODES lines can be used to continue the list. The default is \b NONE.
@@ -1067,7 +1069,7 @@ Attaches a descriptive title to the network being analyzed.
 
 __Format:__
 
-Any number of lines of text.
+Up to three lines of text containing no more than 79 characters each can be used as a title.
 
 __Remarks:__
 
@@ -1094,16 +1096,17 @@ One line for each valve containing:
 - ID of valve characteristic curve (PCVs only)
 
 __Remarks:__
-1. Valve types and settings include:
+1. Valve types and settings include: \n
 |Valve Type | Setting |
 |-----------|---------|
-|<B>PRV</B> (pressure reducing valve) | Pressure, psi (m) |
+|<B>PRV</B> (pressure reducing valve) | Pressure (pressure units) |
-|<B>PSV</B> (pressure sustaining valve) | Pressure, psi (m) |
+|<B>PSV</B> (pressure sustaining valve) | Pressure (pressure units) |
-|<B>PBV</B> (pressure breaker valve) | Pressure, psi (m) |
+|<B>PBV</B> (pressure breaker valve) | Pressure (pressure units) |
 |<B>FCV</B> (flow control valve) | Flow (flow units) |
 |<B>TCV</B> (throttle control valve) | Partially open loss coefficient |
 |<B>PCV</B> (positional control valve) | Percent open |
 |<B>GPV</B> (general purpose valve) | ID of head loss curve |
+\n
 2. Shutoff valves and check valves are considered to be part of a pipe, not a separate control valve component (see @ref PipesPage).
 3. The loss coefficient setting for a TCV should not be less than its fully open loss coefficient.
 4. The characteristic curve for a PCV relates the valve's percent of fully open flow to the percent open. If not supplied then a linear curve is assumed.
@@ -1141,8 +1144,6 @@ 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.
 */
 
 /**
@@ -1163,9 +1164,9 @@ __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.
+2. Any convenient geographic, projected or arbitrary Cartesian coordinate system can be used.
 
-3. The locations  of the nodes need not be to actual scale.
+3. The locations of 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.
 */
@@ -1212,7 +1213,7 @@ __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.
+2. The coordinates refer to the upper left corner of the label.
 
 3. The optional anchor node anchors the label to the node when the network layout is re-scaled during zoom-in operations.
 

include/epanet2_2.h

@@ -440,7 +440,7 @@ typedef struct Project *EN_Project;
 
   /**
   @brief Opens a project's water quality solver.
-  @param ph n EPANET project handle.
+  @param ph an EPANET project handle.
   @return an error code.
 
   Call ::EN_openQ prior to running the first water quality analysis using an
@@ -502,7 +502,7 @@ typedef struct Project *EN_Project;
   time step determined by when the next hydraulic event occurs. Use ::EN_stepQ instead
   if you wish to generate results over each water quality time step.
 
-  The value of `tStep` is determined from information produced by the hydraulic analysis
+  The value of `out_tStep` is determined from information produced by the hydraulic analysis
   that preceded the water quality analysis. Treat it as a read-only variable.
 
  <b>Example:</b>
@@ -533,8 +533,8 @@ typedef struct Project *EN_Project;
   quality time step of the simulation, rather than over each hydraulic event period
   as with ::EN_nextQ.
 
-  Use the argument `timeLeft` to determine when no more calls to ::EN_runQ are needed
+  Use the argument `out_timeLeft` to determine when no more calls to ::EN_runQ are needed
-  because the end of the simulation period has been reached (i.e., when `timeLeft` = 0).
+  because the end of the simulation period has been reached (i.e., when `out_timeLeft` = 0).
   */
   int DLLEXPORT EN_stepQ(EN_Project ph, long *out_timeLeft);
 
@@ -1020,7 +1020,7 @@ typedef struct Project *EN_Project;
   @param[out] out_pexp  Pressure exponent in demand function.
   @return an error code.
 
-  Parameters `pmin`, `preq`, and `pexp` are only used when the demand model is `EN_PDA`.
+  Parameters `out_pmin`, `out_preq`, and `out_pexp` are only used when the demand model is `EN_PDA`.
   */
   int DLLEXPORT EN_getdemandmodel(EN_Project ph, int *out_type, double *out_pmin,
                 double *out_preq, double *out_pexp);
@@ -1036,7 +1036,7 @@ typedef struct Project *EN_Project;
 
   Set `type` to `EN_DDA` for a traditional demand driven analysis (in which case the
   remaining three parameter values are ignored) or to `EN_PDA` for a pressure driven
-  analysis. In the latter case a node's demand is computed as:\n 
+  analysis. In the latter case a node's demand is 0 when pressure is below `pmin`, is at full demand when pressure is above `preq`, or is otherwise computed as:\n 
   `Dfull * [ (P - pmin) / (preq - pmin) ] ^ pexp`\n 
   where `Dfull` is the full demand and `P` is the current pressure.
 
@@ -1147,7 +1147,7 @@ typedef struct Project *EN_Project;
   @param[out] out_demandName The name of the selected category.
   @return an error code.
 
-  `demandName` must be sized to contain at least @ref EN_SizeLimits "EN_MAXID+1" characters.
+  `out_demandName` must be sized to contain at least @ref EN_SizeLimits "EN_MAXID+1" characters.
   */
   int DLLEXPORT EN_getdemandname(EN_Project ph, int nodeIndex, int demandIndex, char *out_demandName);
 
@@ -1738,7 +1738,7 @@ typedef struct Project *EN_Project;
   @brief Gets the enabled status of a simple control.
   @param ph an EPANET project handle.
   @param index the control's index (starting from 1).
-  @param out_enabled the control will be either EN_TRUE=enabled or EN_FALSE=disabled.
+  @param out_enabled `EN_TRUE` (= 1) if the control is enabled or `EN_FALSE` (= 0) if it is disabled.
   @return an error code.
   */
   int  DLLEXPORT EN_getcontrolenabled(EN_Project ph, int index, int *out_enabled);
@@ -1747,7 +1747,7 @@ typedef struct Project *EN_Project;
   @brief Sets the enabled status of a simple control.
   @param ph an EPANET project handle.
   @param index the control's index (starting from 1).
-  @param enabled set the control to either EN_TRUE=enabled or EN_FALSE=disabled.
+  @param enabled `EN_TRUE` (= 1) sets the control to enabled, `EN_FALSE` (= 0) sets it to disabled.
   @return an error code.
   */
   int  DLLEXPORT EN_setcontrolenabled(EN_Project ph, int index, int enabled);

include/epanet2_enums.h

@@ -60,9 +60,9 @@ typedef enum {
   EN_TANK_KBULK   = 23, //!< Tank bulk decay coefficient
   EN_TANKVOLUME   = 24, //!< Current computed tank volume (read only)
   EN_MAXVOLUME    = 25, //!< Tank maximum volume (read only)
-  EN_CANOVERFLOW  = 26, //!< Tank can overflow (= 1) or not (= 0)
+  EN_CANOVERFLOW  = 26, //!< `EN_TRUE` (= 1) if the Tank can overflow, `EN_FALSE` (= 0) if it cannot
   EN_DEMANDDEFICIT = 27,//!< Amount that full demand is reduced under PDA (read only)
-  EN_NODE_INCONTROL = 28, //!< Is present in any simple or rule-based control (= 1) or not (= 0)
+  EN_NODE_INCONTROL = 28, //!< `EN_TRUE` (= 1) if the node appears in any control, `EN_FALSE` (= 0) if not
   EN_EMITTERFLOW    = 29, //!< Current emitter flow (read only)
   EN_LEAKAGEFLOW    = 30, //!< Current leakage flow (read only)
   EN_DEMANDFLOW     = 31, //!< Current consumer demand delivered (read only)
@@ -81,7 +81,7 @@ typedef enum {
   EN_MINORLOSS    = 3,  //!< Pipe/valve minor loss coefficient
   EN_INITSTATUS   = 4,  //!< Initial status (see @ref EN_LinkStatusType)
   EN_INITSETTING  = 5,  //!< Initial pump speed or valve setting
-  EN_KBULK        = 6,  //!< Bulk chemical reaction coefficient
+  EN_KBULK        = 6,  //!< Bulk flow chemical reaction coefficient
   EN_KWALL        = 7,  //!< Pipe wall chemical reaction coefficient
   EN_FLOW         = 8,  //!< Current computed flow rate (read only)
   EN_VELOCITY     = 9,  //!< Current computed flow velocity (read only)
@@ -100,7 +100,7 @@ typedef enum {
   EN_PUMP_EPAT    = 22, //!< Pump energy price time pattern index
   EN_LINK_INCONTROL = 23,  //!< Is present in any simple or rule-based control (= 1) or not (= 0)
   EN_GPV_CURVE    = 24, //!< GPV head loss v. flow curve index
-  EN_PCV_CURVE    = 25, //!< PCV loss coeff. curve index
+  EN_PCV_CURVE    = 25, //!< PCV characteristic curve index
   EN_LEAK_AREA    = 26, //!< Pipe leak area (sq mm per 100 length units)
   EN_LEAK_EXPAN   = 27, //!< Leak expansion rate (sq mm per unit of pressure head)
   EN_LINK_LEAKAGE = 28, //!< Current leakage rate (read only)
@@ -222,8 +222,8 @@ initial status (`EN_INITSTATUS`) or its current status (`EN_STATUS`). These opti
 also used with @ref EN_setlinkvalue to set values for these same properties.
 */
 typedef enum {
-  EN_CLOSED       = 0,
+  EN_CLOSED       = 0,  //!< Link is closed and cannot convey any flow
-  EN_OPEN         = 1
+  EN_OPEN         = 1   //!< Link is open and is able to convey flow
 } EN_LinkStatusType;
 
 /// Pump states
@@ -357,7 +357,7 @@ typedef enum {
   EN_TANKORDER      = 21, //!< Bulk water reaction order for tanks
   EN_CONCENLIMIT    = 22, //!< Limiting concentration for growth reactions
   EN_DEMANDPATTERN  = 23, //!< Name of default demand pattern
-  EN_EMITBACKFLOW   = 24, //!< 1 if emitters can backflow, 0 if not
+  EN_EMITBACKFLOW   = 24, //!< `EN_TRUE` (= 1) if emitters can backflow, `EN_FALSE` (= 0) if not
   EN_PRESS_UNITS    = 25, //!< Pressure units (see @ref EN_PressUnits)
   EN_STATUS_REPORT  = 26  //!< Type of status report to produce (see @ref EN_StatusReport)
 } EN_Option;