Merge branch 'dev' into dev-EN_openX

ReleaseNotes2_3.md

@@ -6,17 +6,17 @@ This document describes the changes and updates that have been made in version 2
  - The check for at least two nodes, one tank/reservoir and no unconnected junction nodes was moved from `EN_open` to `EN_openH` and `EN_openQ` so that partial network data files could be opened by the toolkit.
  - A `EN_setcurvetype` function was added to allow API clients to set a curve's type (e.g., `EN_PUMP_CURVE,` `EN_VOLUME_CURVE,` etc.).
  - A `EN_setvertex` function was added to allow API clients to change the coordinates of a single link vertex.
- - The index of a General Purpose Valve's (GPV's) head loss curve was added to the list of editable Link Properties using the symbolic constant name `EN_GPV_CURVE`.
+ - The indices of a General Purpose Valve (GPV) and a Positional Control Valve (PCV) were added to the list of editable Link Properties using the symbolic constant names `EN_GPV_CURVE` and `EN_PCV_CURVE`, respectively.
- - The `EN_getlinkvalue` and `EN_setlinkvalue` functions were updated to get and set the value of `EN_GPV_CURVE`.
+ - The `EN_getlinkvalue` and `EN_setlinkvalue` functions were updated to get and set the values of `EN_GPV_CURVE` and `EN_PCV_CURVE`.
  - Negative pressure values for `EN_SETTING` are now permitted in the `EN_setlinkvalue` function. 
  - The `EN_STARTTIME` parameter was added into the `EN_settimeparam` function.
- - A `EN_DEMANDPATTERN` parameter was added as the index of the default time pattern used by demands with no specific pattern assigned. It can be set or retrieved with the `EN_setoption` and `EN_getoption` functions, respectively, and is saved to file when the `EN_saveinpfile` function is called.
+ - A `EN_DEMANDPATTERN` parameter was added as the index of the default time pattern used by demands with no specific pattern assigned. It can be set or retrieved with the `EN_setoption` and `EN_getoption` functions, respectively, and is saved to the file when the `EN_saveinpfile` function is called.
  - The `EN_getaveragepatternvalue` function will now accept a pattern index of zero which represents the constant pattern assigned to junction demands by default.
  - The adjustment of a tank's minimum volume (`Vmin`) when its parameters are changed using `EN_setnodevalue` or `EN_settankdata` has been corrected. 
- - A pump whose status is set to CLOSED in the input file now also has its speed setting set to zero which allows a simple pressure control activate the pump correctly.
+ - A pump whose status is set to CLOSED in the input file now also has its speed setting set to zero which allows a simple pressure control to activate the pump correctly.
- - A failure to raise an error condition for a non-positve pipe roughness in the input file has been fixed.
+ - A failure to raise an error condition for a non-positive pipe roughness in the input file has been fixed.
  - The calculation of head loss gradient for low flow conditions was corrected.
- - Improved updating and convergence tests were added to pressure dependent demand analysis.
+ - Improved updating and convergence tests were added to pressure-dependent demand analysis.
  - Improved checks to prevent outflow from empty tanks or inflow to full (non-overflow) tanks, including the case where a link is connected to a pair of tanks, were added.
  - The CI regression test protocol was modified by:
    - changing the absolute tolerance used to compare the closeness of test results to benchmark values from 0 to 0.0001
@@ -24,9 +24,10 @@ This document describes the changes and updates that have been made in version 2
    - dropping the check for identical status report content since it prevents accepting code changes that produce more accurate solutions in fewer iterations.
  - A possible loss of network connectivity when evaluating a Pressure Sustaining Valve was prevented.
  - Having the implied loss coefficient for an active Flow Control Valve be less than its fully opened value was prevented.
- - A new type of valve, a Positional Control Valve (PCV), was added that uses a valve characteristic curve to relate its loss coefficient to its fraction open setting. 
+ - A new type of valve, a Positional Control Valve (PCV), was added. It uses a valve characteristic curve to relate its loss coefficient to a percentage open setting (parameter - `EN_PCV`).
- - A new set of functions have been added to get information about upcoming time step events. Users will now see what type of event is going to cause the end of a time step to occur. See `ENtimetonextevent` and `EN_timetonextevent`.
+ - `EN_VALVE_CURVE` can now be used with the `EN_getcurvetype` and `EN_setcurvetype` to get or set the valve position curve.
- - A new set of functions have been added to allow users to set a reporting callback function. The user-supplied function will recieve all output normally directed to the report file.
+ - A new set of functions has been added to get information about upcoming time step events. Users will now see what type of event is going to cause the end of a time step to occur. See `EN_timetonextevent`.
+ - A new set of functions has been added to allow users to set a reporting callback function. The user-supplied function will receive all output normally directed to the report file.
  - A `EN_EMITBACKFLOW` option was added that either allows emitters to have reverse flow through them (the default) or not.
  - An incorrect tank elevation value set using `EN_settankdata` with SI units has been fixed.
  - The `EN_INITSETTING` option in function `EN_getlinkvalue` will now return `EN_MISSING` for a valve whose initial status is fixed to `EN_OPEN` or `EN_CLOSED`.
@@ -37,14 +38,14 @@ This document describes the changes and updates that have been made in version 2
  - A new error code `263 - node is not a tank` is returned when `EN_settankdata` or `EN_setnodevalue` attempts to set a tank-only parameter for a non-tank node.
  - The function `EN_saveinpfile` was corrected for simple controls on GPV's by saving their status instead of the index of their head loss curve.
  - Support was added for Conan dependency manager.
- - The internal Qualflag variable is now adjusted when an EPANET input file has a QUALITY option not equal to NONE and simulation duration of zero.
+ - The internal Qualflag variable is now adjusted when an EPANET input file has a QUALITY option not equal to NONE and a simulation duration of zero.
  - Support was added for cubic meters per second (`EN_CMS`) flow units.
- - An EPANET input file with a simple timer control that has more than 9 input tokens no longer results in an incorrect hour setting.
+ - An EPANET input file with simple timer control that has more than 9 input tokens no longer results in an incorrect hour setting.
  - Errors in node and link vertex coordinates are now ignored when reading an EPANET input file.
  - Only non-zero demands are now included in the `[DEMANDS]` section of the input file produced by `EN_saveinpfile`.
  - `EN_SET_CLOSED` and `EN_SET_OPEN` constants were added that can be used with `EN_setcontrol` to fix the status of pipes and valves to completely closed or completely open.
  - `EN_EMITTERFLOW` can now be used with `EN_getnodevalue` to retrieve a node's emitter flow rate.
  - `EN_STATUS_REPORT` can now be used with `EN_getoption` and `EN_setoption` to get or set the type of status report that EPANET will generate (`EN_NO_REPORT`, `EN_NORMAL_REPORT` or `EN_FULL_REPORT`).  
  - A possible parser error that could result in a Trace Node ID in an input file not being recognized was fixed.
- - Additional API functions for enabling/disabling controls and rules were added.
+ - Additional API functions for enabling/disabling controls and rules were added (`EN_getcontrolenabled`, `EN_setcontrolenabled`, `EN_getruleenabled`, `EN_setruleenabled`).
- 
+ - Updated the internal function `getclosedlink` in report.c to use a loop instead of recursion to prevent a stack overflow during the analysis of very large disconnections.

include/epanet2.bas

@@ -35,7 +35,7 @@ Public Const EN_TANK_KBULK = 23
 Public Const EN_TANKVOLUME = 24
 Public Const EN_MAXVOLUME = 25
 Public Const EN_CANOVERFLOW = 26
-Public Const EN_DEMANDDEFICIT = 27 
+Public Const EN_DEMANDDEFICIT = 27
 Public Const EN_NODE_INCONTROL = 28
 Public Const EN_EMITTERFLOW = 29
 
@@ -64,7 +64,7 @@ Public Const EN_PUMP_ECOST = 21
 Public Const EN_PUMP_EPAT = 22
 Public Const EN_LINK_INCONTROL = 23
 Public Const EN_GPV_CURVE = 24
-Public Const EN_PCV_CURVE= 25
+Public Const EN_PCV_CURVE = 25
 
 Public Const EN_DURATION = 0      ' Time parameters
 Public Const EN_HYDSTEP = 1
@@ -96,7 +96,7 @@ Public Const EN_LINK = 1
 Public Const EN_TIMEPAT = 2
 Public Const EN_CURVE = 3
 Public Const EN_CONTROL = 4
-Public Const EN_RULE = 5 
+Public Const EN_RULE = 5
 
 Public Const EN_NODECOUNT = 0     ' Component counts
 Public Const EN_TANKCOUNT = 1
@@ -122,7 +122,7 @@ Public Const EN_GPV = 8
 Public Const EN_PCV = 9
 
 Public Const EN_CLOSED = 0        ' Link status types
-Public Const EN_OPEN   = 1
+Public Const EN_OPEN = 1
 
 Public Const EN_PUMP_XHEAD = 0    ' Pump state types
 Public Const EN_PUMP_CLOSED = 2
@@ -175,7 +175,7 @@ Public Const EN_GLOBALPRICE = 9
 Public Const EN_GLOBALPATTERN = 10
 Public Const EN_DEMANDCHARGE = 11
 Public Const EN_SP_GRAVITY = 12
-Public Const EN_SP_VISCOS  = 13
+Public Const EN_SP_VISCOS = 13
 Public Const EN_UNBALANCED = 14
 Public Const EN_CHECKFREQ = 15
 Public Const EN_MAXCHECK = 16
@@ -269,9 +269,12 @@ Public Const EN_STEP_WQ = 2
 Public Const EN_STEP_TANKEVENT = 3
 Public Const EN_STEP_CONTROLEVENT = 4
 
-Public Const EN_MISSING As Double = -1.0E10
+Public Const EN_MISSING As Double = -10000000000#
-Public Const EN_SET_CLOSED As Double = -1.0E10
+Public Const EN_SET_CLOSED As Double = -10000000000#
-Public Const EN_SET_OPEN As Double = 1.0E10
+Public Const EN_SET_OPEN As Double = 10000000000#
+
+Public Const EN_FALSE = 0   ' boolean false
+Public Const EN_TRUE = 1    ' boolean true
 
 'These are the external functions that comprise the DLL
 
@@ -356,7 +359,7 @@ Public Const EN_SET_OPEN As Double = 1.0E10
  Declare Function ENgetdemandindex Lib "epanet2.dll" (ByVal nodeIndex As Long, ByVal demandName As String, demandIndex As Long) As Long
  Declare Function ENgetnumdemands Lib "epanet2.dll" (ByVal nodeIndex As Long, numDemands As Long) As Long
  Declare Function ENgetbasedemand Lib "epanet2.dll" (ByVal nodeIndex As Long, ByVal demandIndex As Long, value As Single) As Long
- Declare Function ENsetbasedemand Lib "epanet2.dll" (ByVal nodeIndex As Long, ByVal demandIndex As Long, ByVal BaseDemand As Single) As Long
+ Declare Function ENsetbasedemand Lib "epanet2.dll" (ByVal nodeIndex As Long, ByVal demandIndex As Long, ByVal baseDemand As Single) As Long
  Declare Function ENgetdemandpattern Lib "epanet2.dll" (ByVal nodeIndex As Long, ByVal demandIndex As Long, patIndex As Long) As Long
  Declare Function ENsetdemandpattern Lib "epanet2.dll" (ByVal nodeIndex As Long, ByVal demandIndex As Long, ByVal patIndex As Long) As Long
  Declare Function ENgetdemandname Lib "epanet2.dll" (ByVal nodeIndex As Long, ByVal demandIndex As Long, ByVal demandName As String) As Long
@@ -416,7 +419,9 @@ Public Const EN_SET_OPEN As Double = 1.0E10
  Declare Function ENdeletecontrol Lib "epanet2.dll" (ByVal index As Long) As Long
  Declare Function ENgetcontrol Lib "epanet2.dll" (ByVal index As Long, type_ As Long, linkIndex As Long, setting As Single, nodeIndex As Long, level As Single) As Long
  Declare Function ENsetcontrol Lib "epanet2.dll" (ByVal index As Long, ByVal type_ As Long, ByVal linkIndex As Long, ByVal setting As Single, ByVal nodeIndex As Long, ByVal level As Single) As Long
-
+ Declare Function ENgetcontrolenabled Lib "epanet2.dll" (ByVal index As Long, out_enabled As Long) As Long
+ Declare Function ENsetcontrolenabled Lib "epanet2.dll" (ByVal index As Long, ByVal enabled As Long) As Long
+ 
 'Rule-Based Control Functions
  Declare Function ENaddrule Lib "epanet2.dll" (ByVal rule As String) As Long
  Declare Function ENdeleterule Lib "epanet2.dll" (ByVal index As Long) As Long
@@ -432,3 +437,6 @@ Public Const EN_SET_OPEN As Double = 1.0E10
  Declare Function ENsetthenaction Lib "epanet2.dll" (ByVal ruleIndex As Long, ByVal actionIndex As Long, ByVal linkIndex As Long, ByVal status As Long, ByVal setting As Single) As Long
  Declare Function ENgetelseaction Lib "epanet2.dll" (ByVal ruleIndex As Long, ByVal actionIndex As Long, linkIndex As Long, status As Long, setting As Single) As Long
  Declare Function ENsetelseaction Lib "epanet2.dll" (ByVal ruleIndex As Long, ByVal actionIndex As Long, ByVal linkIndex As Long, ByVal status As Long, ByVal setting As Single) As Long
+ Declare Function ENgetruleenabled Lib "epanet2.dll" (ByVal index As Long, out_enabled As Long) As Long
+ Declare Function ENsetruleenabled Lib "epanet2.dll" (ByVal index As Long, ByVal enabled As Long) As Long
+

include/epanet2.cs

@@ -269,7 +269,9 @@ namespace EpanetCSharpLibrary
         public const double EN_MISSING = -1.0E10;
         public const double EN_SET_CLOSED = -1.0E10
         public const double EN_SET_OPEN = 1.0E10
-
+        
+        public const int EN_FALSE = 0   // boolean false
+        public const int EN_TRUE  = 1   // boolean true
 
         #region Epanet Imports
 
@@ -632,6 +634,12 @@ namespace EpanetCSharpLibrary
         [DllImport(EPANETDLL, EntryPoint = "ENsetcontrol")]
         public static extern int ENsetcontrol(int index, int type, int linkIndex, float setting, int nodeIndex, float level);
 
+        [DllImport(EPANETDLL, EntryPoint = "ENgetcontrolenabled")]
+        public static extern int ENgetcontrolenabled(int index, int out_enabled);
+
+        [DllImport(EPANETDLL, EntryPoint = "ENsetcontrolenabled")]
+        public static extern int ENsetcontrolenabled(int index, int enabled);
+
 
         //Rule-Based Control Functions
         [DllImport(EPANETDLL, EntryPoint = "ENaddrule")]
@@ -676,6 +684,11 @@ namespace EpanetCSharpLibrary
         [DllImport(EPANETDLL, EntryPoint = "ENsetelseaction")]
         public static extern int ENsetelseaction(int ruleIndex, int actionIndex, int linkIndex, int status, float setting);
 
+        [DllImport(EPANETDLL, EntryPoint = "ENgetruleenabled")]
+        public static extern int ENgetruleenabled(int index, int out_enabled);
+
+        [DllImport(EPANETDLL, EntryPoint = "ENsetruleenabled")]
+        public static extern int ENsetruleenabled(int index, int enabled);
 
         #endregion
     }

include/epanet2.def

@@ -133,3 +133,7 @@ EXPORTS
     ENwriteline                   = _ENwriteline@4
     ENtimetonextevent             = _ENtimetonextevent@12
     ENopenX                       = _ENopenX@12                          
+    ENgetcontrolenabled           = _ENgetcontrolenabled@8
+    ENsetcontrolenabled           = _ENsetcontrolenabled@8
+    ENgetruleenabled              = _ENgetruleenabled@8
+    ENsetruleenabled              = _ENsetruleenabled@8

include/epanet2.pas

@@ -270,6 +270,10 @@ const
  EN_R_IS_OPEN   = 1;   { Rule-based control link status }
  EN_R_IS_CLOSED = 2;
  EN_R_IS_ACTIVE = 3;
+ 
+ EN_FALSE       = 0;   { boolean false }
+ EN_TRUE        = 1;   { boolean true }
+
 
 {$ifdef MSWINDOWS}
  EpanetLib = 'epanet2.dll'; 
@@ -417,6 +421,8 @@ const
  function  ENdeletecontrol(Index: Integer): Integer; stdcall; external EpanetLib;
  function  ENgetcontrol(Index: Integer; var Ctype: Integer; var Link: Integer; var Setting: Single; var Node: Integer; var Level: Single): Integer; stdcall; external EpanetLib;
  function  ENsetcontrol(Index: Integer; Ctype: Integer; Link: Integer; Setting: Single; Node: Integer; Level: Single): Integer; stdcall; external EpanetLib;
+ function  ENgetcontrolenabled(Index: Integer; out_enabled: Integer): Integer; stdcall; external EpanetLib;
+ function  ENsetcontrolenabled(Index: Integer; var enabled: Integer): Integer; stdcall; external EpanetLib;
 
  {Rule-Based Control Functions}
  function ENaddrule(Rule: PAnsiChar): Integer; stdcall; external EpanetLib;
@@ -441,6 +447,8 @@ const
           var Status: Integer; var Setting: Single): Integer; stdcall; external EpanetLib;
  function ENsetelseaction(RuleIndex: Integer; ActionIndex: Integer; LinkIndex: Integer;
           Status: Integer; Setting: Single): Integer; stdcall; external EpanetLib;
+ function  ENgetruleenabled(Index: Integer; out_enabled: Integer): Integer; stdcall; external EpanetLib;
+ function  ENsetruleenabled(Index: Integer; var enabled: Integer): Integer; stdcall; external EpanetLib;
 
 implementation
 

include/epanet2.vb

@@ -261,6 +261,9 @@ Public Const EN_MISSING As Double = -1.0E10
 Public Const EN_SET_CLOSED As Double = -1.0E10
 Public Const EN_SET_OPEN As Double = 1.0E10
 
+Public Const EN_FALSE = 0   ' boolean false
+Public Const EN_TRUE  = 1   ' boolean true
+
 'These are the external functions that comprise the DLL
 
 'Project Functions
@@ -400,6 +403,8 @@ Public Const EN_SET_OPEN As Double = 1.0E10
  Declare Function ENdeletecontrol Lib "epanet2.dll" (ByVal index As Int32) As Int32
  Declare Function ENgetcontrol Lib "epanet2.dll" (ByVal index As Int32, type_ As Int32, linkIndex As Int32, setting As Single, nodeIndex As Int32, level As Single) As Int32
  Declare Function ENsetcontrol Lib "epanet2.dll" (ByVal index As Int32, ByVal type_ As Int32, ByVal linkIndex As Int32, ByVal setting As Single, ByVal nodeIndex As Int32, ByVal level As Single) As Int32
+ Declare Function ENgetcontrolenabled Lib "epanet2.dll" (ByVal index As Int32, out_enabled As Int32) As Int32
+ Declare Function ENsetcontrolenabled Lib "epanet2.dll" (ByVal index As Int32, ByVal enabled As Int32) As Int32
 
 'Rule-Based Control Functions
  Declare Function ENaddrule Lib "epanet2.dll" (ByVal rule As String) As Int32
@@ -416,5 +421,7 @@ Public Const EN_SET_OPEN As Double = 1.0E10
  Declare Function ENsetthenaction Lib "epanet2.dll" (ByVal ruleIndex As Int32, ByVal actionIndex As Int32, ByVal linkIndex As Int32, ByVal status As Int32, ByVal setting As Single) As Int32
  Declare Function ENgetelseaction Lib "epanet2.dll" (ByVal ruleIndex As Int32, ByVal actionIndex As Int32, linkIndex As Int32, status As Int32, setting As Single) As Int32
  Declare Function ENsetelseaction Lib "epanet2.dll" (ByVal ruleIndex As Int32, ByVal actionIndex As Int32, ByVal linkIndex As Int32, ByVal status As Int32, ByVal setting As Single) As Int32
+ Declare Function ENgetruleenabled Lib "epanet2.dll" (ByVal index As Int32, out_enabled As Int32) As Int32
+ Declare Function ENsetruleenabled Lib "epanet2.dll" (ByVal index As Int32, ByVal enabled As Int32) As Int32
 
 End Module

src/report.c

@@ -45,7 +45,7 @@ static void writeenergy(Project *);
 static int  writeresults(Project *);
 static int  disconnected(Project *);
 static void marknodes(Project *, int, int *, char *);
-static void getclosedlink(Project *, int, char *);
+static void getclosedlink(Project *, int, char *, int *);
 static void writelimits(Project *, int, int);
 static int  checklimits(Report *, double *, int, int);
 static char *fillstr(char *, char, int);
@@ -1287,7 +1287,7 @@ int disconnected(Project *pr)
                     clocktime(rpt->Atime, time->Htime));
             writeline(pr, pr->Msg);
         }
-        getclosedlink(pr, j, marked);
+        getclosedlink(pr, j, marked, nodelist);
     }
 
     // Free allocated memory
@@ -1350,11 +1350,12 @@ void marknodes(Project *pr, int m, int *nodelist, char *marked)
     }
 }
 
-void getclosedlink(Project *pr, int i, char *marked)
+void getclosedlink(Project *pr, int i, char *marked, int *stack)
 /*
 **----------------------------------------------------------------
 **   Input:   i = junction index
 **            marked[] = marks nodes already examined
+**            stack[] = stack to hold nodes to examine
 **   Output:  None.
 **   Purpose: Determines if a closed link connects to junction i.
 **----------------------------------------------------------------
@@ -1365,20 +1366,41 @@ void getclosedlink(Project *pr, int i, char *marked)
     int j, k;
     Padjlist alink;
 
+    int top = 0;
+
+    // Mark the current junction as examined and push onto stack
     marked[i] = 2;
-    for (alink = net->Adjlist[i]; alink != NULL; alink = alink->next)
+    stack[top] = i;
-    {
+
-        k = alink->link;
+    while (top >= 0) {
-        j = alink->node;
+        i = stack[top--];
-        if (marked[j] == 2) continue;
+        alink = net->Adjlist[i];
-        if (marked[j] == 1)
+        
-        {
+        // Iterate through each link adjacent to the current node
-            sprintf(pr->Msg, WARN03c, net->Link[k].ID);
+        while (alink != NULL) {
-            writeline(pr, pr->Msg);
+            k = alink->link;
-            return;
+            j = alink->node;
+
+            // Skip nodes that have already been examined
+            if (marked[j] == 2) {
+                alink = alink->next;
+                continue;
+            }
+
+            // If a closed link is found, return and display a warning message
+            if (marked[j] == 1) {
+                sprintf(pr->Msg, WARN03c, net->Link[k].ID);
+                writeline(pr, pr->Msg);
+                return;
+            }
+
+            // Mark the node as examined and push it onto the stack
+            marked[j] = 2;
+            stack[++top] = j;
+            alink = alink->next;
         }
-        else getclosedlink(pr, j, marked);
     }
+
 }
 
 void writelimits(Project *pr, int j1, int j2)

tests/test_valve.cpp

@@ -28,7 +28,7 @@ BOOST_FIXTURE_TEST_CASE(test_PCV_valve, FixtureOpenClose)
     double x[] = { 0.0, 25., 50., 75., 100. };
     double y[] = {0.0, 8.9, 18.4, 40.6, 100.0};
     double v;
-    int linkIndex, curveIndex;
+    int linkIndex, curveIndex, curveType;
 
     // Make steady state run
     error = EN_settimeparam(ph, EN_DURATION, 0);
@@ -50,6 +50,11 @@ BOOST_FIXTURE_TEST_CASE(test_PCV_valve, FixtureOpenClose)
     BOOST_REQUIRE(error == 0);
     error = EN_setcurve(ph, curveIndex, x, y, npts);
     BOOST_REQUIRE(error == 0);
+    error = EN_setcurvetype(ph, curveIndex, EN_VALVE_CURVE);
+    BOOST_REQUIRE(error == 0);
+    error = EN_getcurvetype(ph, curveIndex, &curveType);
+    BOOST_REQUIRE(error == 0);
+    BOOST_REQUIRE(curveType == EN_VALVE_CURVE);
 
     // Assign curve & initial setting to PCV
     error = EN_setlinkvalue(ph, linkIndex, EN_PCV_CURVE, curveIndex);