Merge pull request #808 from LRossman/dev-leakage

Add leakage into EPANET/dev
OpenWaterAnalytics · Jul 12, 2024 · 3574bdf · 3574bdf
2 parents cc9105f + 5894b67
commit 3574bdf
Show file tree

Hide file tree

Showing 25 changed files with 1,375 additions and 213 deletions.
diff --git a/ReleaseNotes2_3.md b/ReleaseNotes2_3.md
@@ -4,6 +4,7 @@
 This document describes the changes and updates that have been made in version 2.3 of EPANET.
 
  - 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 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.
@@ -52,6 +53,20 @@ This document describes the changes and updates that have been made in version 2
 - Setting the demand multiplier within the `[DEMANDS]` section of INP has been depreciated, please use `DEMAND MULTIPLIER` inside `[OPTIONS]` instead.
 - `EN_PRESS_UNITS` can now be used with `EN_getoption` and `EN_setoption` to get or set the pressure unit used in EPANET.
 - Continuous barrier functions were added to constrain emitter flows to allowable values.
-- The `EN_openx` function has been added to enable the opening of input files with formatting errors through the API. This allows users to continue using toolkit functions even when such errors are present.
+- The `EN_openX` function has been added to enable the opening of input files with formatting errors through the API. This allows users to continue using toolkit functions even when such errors are present.
 - The `EN_getnodesvalues` and `EN_getlinksvalues` were added to retrieve a property value for all nodes or links in the network.
 - Fixed a bug in EN_setnodevalue with EN_EMITTER option that could cause NaN results.
+- Support has been added for FAVAD (Fixed And Variable Area Discharge) modeling of pipe leaks:
+   - A new `[LEAKAGE]` section has been added to the input file format where each line contains the ID name of a pipe, its leak area in sq. mm per 100 length units, and its leak expansion rate in sq. mm per unit of pressure head.
+   - `EN_LEAK_AREA` and `EN_LEAK_EXPAN` can be used with the functions `EN_getlinkvalue` and `EN_setlinkvalue` to retrieve and assign values for a pipe's leak area and expansion properties.
+   - `EN_LINK_LEAKAGE` can be used with `EN_getlinkvalue` to retrieve a pipe's leakage rate at a given point in time.
+   - `EN_LEAKAGEFLOW` can be used with `EN_getnodevalue` to retrieve the leakage demand generated at a node from all its connecting pipes at a given point in time.
+   - `EN_LEAKAGELOSS` can be used with `EN_getstatistic` to retrieve the the total leakage loss in the system at a given point in time as a percentage of total flow entering the system.
+- A new Flow Balance Report has been added to end of a simulation run's Status Report that lists the various components of the system's total inflow and outflow over the simulation period. It also displays the ratio of outflow to inflow as a check on flow continuity.
+- The following constants can be used with EN_getnodevalue to retrieve the components of a node's total demand at a given point in time:
+   - `EN_FULLDEMAND` - the consumer demand requested
+   - `EN_DEMANDFLOW` - the consumer demand delivered
+   - `EN_DEMANDDEFICIT` - the difference between the consumer demand requested and delivered
+   - `EN_EMITTERFLOW` - the node's emitter flow
+   - `EN_LEAKAGEFLOW` - the node's leakage flow
+   - `EN_DEMAND` - the sum of the node's consumer demand, emitter flow, and leakage flow
diff --git a/include/epanet2.bas b/include/epanet2.bas
@@ -5,7 +5,7 @@ Attribute VB_Name = "Module1"
 'Declarations of functions in the EPANET PROGRAMMERs TOOLKIT
 '(EPANET2.DLL)
 
-'Last updated on 09/28/2023
+'Last updated on 06/23/2024
 
 ' These are codes used by the DLL functions
 Public Const EN_ELEVATION = 0     ' Node parameters
@@ -38,6 +38,9 @@ Public Const EN_CANOVERFLOW = 26
 Public Const EN_DEMANDDEFICIT = 27
 Public Const EN_NODE_INCONTROL = 28
 Public Const EN_EMITTERFLOW = 29
+Public Const EN_LEAKAGEFLOW = 30
+Public Const EN_DEMANDFLOW = 31
+Public Const EN_FULLDEMAND = 32
 
 Public Const EN_DIAMETER = 0      ' Link parameters
 Public Const EN_LENGTH = 1
@@ -65,6 +68,9 @@ 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_LEAK_AREA = 26
+Public Const EN_LEAK_EXPAN = 27
+Public Const EN_LINK_LEAKAGE = 28
 
 Public Const EN_DURATION = 0      ' Time parameters
 Public Const EN_HYDSTEP = 1
@@ -90,6 +96,7 @@ Public Const EN_MAXFLOWCHANGE = 3
 Public Const EN_MASSBALANCE = 4
 Public Const EN_DEFICIENTNODES = 5
 Public Const EN_DEMANDREDUCTION = 6
+Public Const EN_LEAKAGELOSS = 7
 
 Public Const EN_NODE = 0          ' Component types
 Public Const EN_LINK = 1
@@ -350,6 +357,7 @@ Public Const EN_TRUE = 1    ' boolean true
  Declare Function ENsettankdata Lib "epanet2.dll" (ByVal index As Long, ByVal elev As Single, ByVal initlvl As Single, ByVal minlvl As Single, ByVal maxlvl As Single, ByVal diam As Single, ByVal minvol As Single, ByVal volcurve As String) As Long
  Declare Function ENgetcoord Lib "epanet2.dll" (ByVal index As Long, x As Double, y As Double) As Long
  Declare Function ENsetcoord Lib "epanet2.dll" (ByVal index As Long, ByVal x As Double, ByVal y As Double) As Long
+ Declare Function ENgetnodevalues Lib "epanet2.dll" (ByVal property as Long, values as Any) As Long
 
 'Nodal Demand Functions
  Declare Function ENgetdemandmodel Lib "epanet2.dll" (type_ As Long, pmin As Single, preq As Single, pexp As Single) As Long
@@ -382,6 +390,7 @@ Public Const EN_TRUE = 1    ' boolean true
  Declare Function ENgetvertex Lib "epanet2.dll" (ByVal index As Long, ByVal vertex As Long, x As Double, y As Double) As Long
  Declare Function ENsetvertex Lib "epanet2.dll" (ByVal index As Long, ByVal vertex As Long, ByVal x As Double, ByVal y As Double) As Long
  Declare Function ENsetvertices Lib "epanet2.dll" (ByVal index As Long, xCoords As Any, yCoords As Any, ByVal count As Long) As Long
+ Declare Function ENgetlinkvalues Lib "epanet2.dll" (ByVal property as Long, values as Any) As Long
 
 'Pump Functions
  Declare Function ENgetheadcurveindex Lib "epanet2.dll" (ByVal linkIndex As Long, curveIndex As Long) As Long

diff --git a/include/epanet2.cs b/include/epanet2.cs
@@ -3,7 +3,7 @@
 using System.Runtime.InteropServices;
 
 //epanet2.cs[By Oscar Vegas]
-//Last updated on 09/28/2023
+//Last updated on 06/23/2024
 
 //Declarations of functions in the EPANET PROGRAMMERs TOOLKIT
 //(EPANET2.DLL) for use with C#
@@ -50,6 +50,9 @@ public static class Epanet
         public const int EN_DEMANDDEFICIT = 27;
         public const int EN_NODE_INCONTROL = 28;
         public const int EN_EMITTERFLOW = 29;
+        public const int EN_LEAKAGEFLOW = 30;
+        public const int EN_DEMANDFLOW = 31;
+        public const int EN_FULLDEMAND = 32;
 
         public const int EN_DIAMETER = 0;      //Link parameters
         public const int EN_LENGTH = 1;
@@ -78,6 +81,9 @@ public static class Epanet
         public const int EN_LINK_INCONTROL = 23;
         public const int EN_GPV_CURVE = 24;
         public const int EN_PCV_CURVE = 25;
+        public const int EN_LEAK_AREA = 26;
+        public const int EN_LEAK_EXPAN = 27;
+        public const int EN_LINK_LEAKAGE = 28;
 
         public const int EN_DURATION = 0;      //Time parameters
         public const int EN_HYDSTEP = 1;
@@ -102,6 +108,7 @@ public static class Epanet
         public const int EN_MASSBALANCE = 4;
         public const int EN_DEFICIENTNODES = 5;
         public const int EN_DEMANDREDUCTION = 6;
+        public const int EN_LEAKAGELOSS = 7;
 
         public const int EN_NODE = 0;          //Component types
         public const int EN_LINK = 1;
@@ -390,6 +397,9 @@ public static class Epanet
         [DllImport(EPANETDLL, EntryPoint = "ENgetresultindex")]
         public static extern int ENgetresultindex(int type, int index, ref int value);
 
+        [DllImport(EPANETDLL, EntryPoint = "ENtimetonextevent")]
+        public static extern int ENtimetonextevent(ref int eventType, ref long duration, ref int elementIndex);
+
 
         //Analysis Options Functions
         [DllImport(EPANETDLL, EntryPoint = "ENgetoption")]
@@ -440,10 +450,10 @@ public static class Epanet
         public static extern int ENgetnodetype(int index, ref int nodeType);
 
         [DllImport(EPANETDLL, EntryPoint = "ENgetnodevalue")]
-        public static extern int ENgetnodevalue(int index, int paramcode, ref float value);
+        public static extern int ENgetnodevalue(int index, int param, ref float value);
 
         [DllImport(EPANETDLL, EntryPoint = "ENsetnodevalue")]
-        public static extern int ENsetnodevalue(int index, int code, float value);
+        public static extern int ENsetnodevalue(int index, int param, float value);
 
         [DllImport(EPANETDLL, EntryPoint = "ENsetjuncdata")]
         public static extern int ENsetjuncdata(int index, float elev, float dmnd, string dmndpat);
@@ -457,6 +467,8 @@ public static class Epanet
         [DllImport(EPANETDLL, EntryPoint = "ENsetcoord")]
         public static extern int ENsetcoord(int index, double x, double y);
 
+        [DllImport(EPANETDLL, EntryPoint = "ENgetnodevalues")]
+        public static extern int ENgetnodevalues(int param, ref float values);
 
         //Nodal Demand Functions
         [DllImport(EPANETDLL, EntryPoint = "ENgetdemandmodel")]
@@ -525,10 +537,10 @@ public static class Epanet
         public static extern int ENsetlinknodes(int index, int node1, int node2);
 
         [DllImport(EPANETDLL, EntryPoint = "ENgetlinkvalue")]
-        public static extern int ENgetlinkvalue(int index, int code, ref float value);
+        public static extern int ENgetlinkvalue(int index, int param, ref float value);
 
         [DllImport(EPANETDLL, EntryPoint = "ENsetlinkvalue")]
-        public static extern int ENsetlinkvalue(int index, int code, float value);
+        public static extern int ENsetlinkvalue(int index, int param, float value);
 
         [DllImport(EPANETDLL, EntryPoint = "ENsetpipedata")]
         public static extern int ENsetpipedata(int index, float length, float diam, float rough, float mloss);
@@ -542,6 +554,9 @@ public static class Epanet
         [DllImport(EPANETDLL, EntryPoint = "ENsetvertices")]
         public static extern int ENsetvertices(int index, ref double[] x, ref double[] y, int count);
 
+        [DllImport(EPANETDLL, EntryPoint = "ENgetlinkvalues")]
+        public static extern int ENgetlinkvalues(int param, ref float values);
+
 
         //Pump Functions
         [DllImport(EPANETDLL, EntryPoint = "ENgetheadcurveindex")]

diff --git a/include/epanet2.def b/include/epanet2.def
@@ -25,6 +25,7 @@ EXPORTS
     ENgetbasedemand               = _ENgetbasedemand@12
     ENgetcomment                  = _ENgetcomment@12
     ENgetcontrol                  = _ENgetcontrol@24                    
+    ENgetcontrolenabled           = _ENgetcontrolenabled@8
     ENgetcoord                    = _ENgetcoord@12
     ENgetcount                    = _ENgetcount@8                       
     ENgetcurve                    = _ENgetcurve@20
@@ -44,13 +45,14 @@ EXPORTS
     ENgetlinkid                   = _ENgetlinkid@8                      
     ENgetlinkindex                = _ENgetlinkindex@8                   
     ENgetlinknodes                = _ENgetlinknodes@12                  
-    ENsetlinknodes                = _ENsetlinknodes@12                  
     ENgetlinktype                 = _ENgetlinktype@8                    
     ENgetlinkvalue                = _ENgetlinkvalue@12
+    ENgetlinkvalues               = _ENgetlinkvalues@8
     ENgetnodeid                   = _ENgetnodeid@8                      
     ENgetnodeindex                = _ENgetnodeindex@8                   
     ENgetnodetype                 = _ENgetnodetype@8                    
-    ENgetnodevalue                = _ENgetnodevalue@12                  
+    ENgetnodevalue                = _ENgetnodevalue@12
+    ENgetnodevalues               = _ENgetnodevalues@8
     ENgetnumdemands               = _ENgetnumdemands@8
     ENgetoption                   = _ENgetoption@8                      
     ENgetpatternid                = _ENgetpatternid@8                   
@@ -63,6 +65,7 @@ EXPORTS
     ENgetqualtype                 = _ENgetqualtype@8
     ENgetresultindex              = _ENgetresultindex@12    
     ENgetrule                     = _ENgetrule@20
+    ENgetruleenabled              = _ENgetruleenabled@8
     ENgetruleID                   = _ENgetruleID@8
     ENgetstatistic                = _ENgetstatistic@8
     ENgetthenaction               = _ENgetthenaction@20
@@ -79,6 +82,7 @@ EXPORTS
     ENopen                        = _ENopen@12                          
     ENopenH                       = _ENopenH@0                          
     ENopenQ                       = _ENopenQ@0
+    ENopenX                       = _ENopenX@12
     ENreport                      = _ENreport@0                         
     ENresetreport                 = _ENresetreport@0                    
     ENrunH                        = _ENrunH@4                           
@@ -89,6 +93,7 @@ EXPORTS
     ENsetbasedemand               = _ENsetbasedemand@12
     ENsetcomment                  = _ENsetcomment@12
     ENsetcontrol                  = _ENsetcontrol@24                    
+    ENsetcontrolenabled           = _ENsetcontrolenabled@8
     ENsetcoord                    = _ENsetcoord@20
     ENsetcurve                    = _ENsetcurve@16
     ENsetcurveid                  = _ENsetcurveid@8
@@ -118,6 +123,7 @@ EXPORTS
     ENsetpremisevalue             = _ENsetpremisevalue@12
     ENsetqualtype                 = _ENsetqualtype@16                   
     ENsetreport                   = _ENsetreport@4                      
+    ENsetruleenabled              = _ENsetruleenabled@8
     ENsetrulepriority             = _ENsetrulepriority@8
     ENsetstatusreport             = _ENsetstatusreport@4
     ENsettankdata                 = _ENsettankdata@32
@@ -129,11 +135,6 @@ EXPORTS
     ENsolveH                      = _ENsolveH@0                         
     ENsolveQ                      = _ENsolveQ@0                         
     ENstepQ                       = _ENstepQ@4
+    ENtimetonextevent             = _ENtimetonextevent@12
     ENusehydfile                  = _ENusehydfile@4
     ENwriteline                   = _ENwriteline@4
-    ENtimetonextevent             = _ENtimetonextevent@12
-    ENopenX                       = _ENopenX@12                          
-    ENgetcontrolenabled           = _ENgetcontrolenabled@8
-    ENsetcontrolenabled           = _ENsetcontrolenabled@8
-    ENgetruleenabled              = _ENgetruleenabled@8
-    ENsetruleenabled              = _ENsetruleenabled@8