Merge branch 'dev'

Author: LRossman

ReleaseNotes2_3.md

@@ -137,3 +137,14 @@ This document describes the changes and updates that have been made in version 2
  - A failure to close a temporary hydraulics file between successive simulations of an opened project was fixed.
 
  - Corrupting the index of a water quality Trace Node when adding or deleting a node was fixed.
+
+ ### Patch Releases
+ #### 2.3.1:
+ - Restores the ability to assign an initial status of fully open to a valve and corrects how the setting of a Positional Control Valve is changed using the API or with a control.
+ #### 2.3.2:
+ - Fixes how `EN_setpipedata` assigns a minor loss coefficient to a pipe.
+ #### 2.3.3:
+ - Corrects how `EN_setlinkvalue` assigns OPEN/CLOSED status to a link.
+ #### 2.3.4:
+ - Fixes errors converting the units of the Leak Area and Leak Area Expansion parameters used in the FAVAD pipe leakage model.
+ - To avoid reporting that full tanks are overflowing when they see negligible net inflows or outflows, those flows are now ignored when updating the tank's volume and head.

src/epanet.c

@@ -7,7 +7,7 @@
  Authors:      see AUTHORS
  Copyright:    see AUTHORS
  License:      see LICENSE
- Last Updated: 09/03/2025
+ Last Updated: 01/28/2026
  ******************************************************************************
 */
 
@@ -4020,11 +4020,11 @@ int DLLEXPORT EN_getlinkvalue(EN_Project p, int index, int property, double *val
         break;
 
     case EN_LEAK_AREA:
-        v = Link[index].LeakArea * Ucf[LENGTH];
+        v = Link[index].LeakArea / Ucf[LENGTH];
         break;
 
     case EN_LEAK_EXPAN:
-        v = Link[index].LeakExpan * Ucf[LENGTH];
+        v = Link[index].LeakExpan / Ucf[LENGTH];
         break;
 
     case EN_LINK_LEAKAGE:
@@ -4287,14 +4287,14 @@ int DLLEXPORT EN_setlinkvalue(EN_Project p, int index, int property, double valu
         }
         break;
 
-    case EN_LEAK_AREA:  // leak area in sq mm per 100 pipe length units
+    case EN_LEAK_AREA:  // leak area per 100 pipe lengths units
         if (value < 0.0) return 211;
-        Link[index].LeakArea = value / Ucf[LENGTH];
+        Link[index].LeakArea = value * Ucf[LENGTH];
         break;
 
-    case EN_LEAK_EXPAN:  // leak area expansion slope (sq mm per unit of head)
+    case EN_LEAK_EXPAN:  // leak area expansion slope per 100 pipe length units
         if (value < 0.0) return 211;
-        Link[index].LeakExpan = value / Ucf[LENGTH];
+        Link[index].LeakExpan = value * Ucf[LENGTH];
         break;
 
     case EN_VALVE_TYPE:

src/hydraul.c

@@ -7,7 +7,7 @@
  Authors:      see AUTHORS
  Copyright:    see AUTHORS
  License:      see LICENSE
- Last Updated: 04/19/2025
+ Last Updated: 01/28/2026
  ******************************************************************************
 */
 
@@ -1066,6 +1066,7 @@ void  tanklevels(Project *pr, long tstep)
 
         // Update the tank's volume & water elevation
         n = tank->Node;
+        if (ABS(hyd->NodeDemand[n]) <= QZERO) continue;
         dv = hyd->NodeDemand[n] * tstep;
         tank->V += dv;
 

src/inpfile.c

@@ -370,7 +370,8 @@ int saveinpfile(Project *pr, const char *fname)
         link = &net->Link[i];
         if (link->LeakArea == 0.0 && link->LeakExpan == 0.0) continue;
         fprintf(f, "\n %-31s %14.6f %14.6f", link->ID,
-        link->LeakArea * pr->Ucf[LENGTH], link->LeakExpan * pr->Ucf[LENGTH]);
+            link->LeakArea / pr->Ucf[LENGTH],
+            link->LeakExpan / pr->Ucf[LENGTH]);
     }
 
     // Write [STATUS] section

src/input1.c

@@ -7,7 +7,7 @@ Description:  retrieves network data from an EPANET input file
 Authors:      see AUTHORS
 Copyright:    see AUTHORS
 License:      see LICENSE
-Last Updated: 04/19/2025
+Last Updated: 01/28/2026
 ******************************************************************************
 */
 
@@ -602,8 +602,8 @@ void convertunits(Project *pr)
             link->Kw /= SECperDAY;
 
             // Convert leakage parameters
-            link->LeakArea /= pr->Ucf[LENGTH];
-            link->LeakExpan /= pr->Ucf[LENGTH];
+            link->LeakArea *= pr->Ucf[LENGTH];
+            link->LeakExpan *= pr->Ucf[LENGTH];
         }
 
         else if (link->Type == PUMP)

src/leakage.c

@@ -7,18 +7,18 @@
  Authors:      see AUTHORS
  Copyright:    see AUTHORS
  License:      see LICENSE
- Last Updated: 09/10/2025
+ Last Updated: 01/28/2026
  ******************************************************************************
 */
 /*
 This module uses the FAVAD (Fixed and Variable Discharge) equation to model
 leaky pipes:
   
-  Q = Co * L * (Ao + m * H) * sqrt(H)
+  Q = Co * (Ao + m * H) * sqrt(H)
   
-where Q = pipe leak flow rate, Co = an orifice coefficient (= 0.6*sqrt(2g)),
-L = pipe length, Ao = initial area of leak per unit of pipe length,
-m = change in leak area per unit of pressure head, and H = pressure head.
+where Q = pipe leak flow rate, Co = an orifice coefficient = 0.6*sqrt(2g),
+Ao = initial area of leak, m = change in leak area per unit of pressure
+head, and H = pressure head.
 
 The inverted form of this equation is used to model the leakage demand from
 a pipe's end node using a pair of equivalent emitters as follows:
@@ -27,13 +27,8 @@ a pipe's end node using a pair of equivalent emitters as follows:
   H = Cva * Qva^(2/3)
   
 where Qfa = fixed area node leakage rate, Qva = variable area node leakage rate,
-Cfa = 1 / SUM(Co*(L/2)*Ao)^2, Cva = 1 / SUM(Co*(L/2)*m)^2/3, and
+Cfa = 1 / SUM(Co/2*Ao)^2, Cva = 1 / SUM(Co/2*m)^2/3, and
 SUM(x) is the summation of x over all pipes connected to the node.
-
-In implementing this model, the pipe property "LeakArea" represents Ao in
-sq. mm per 100 units of pipe length and "LeakExpan" represents m in sq. mm
-per unit of pressure head.
-
 */
 #include <stdlib.h>
 #include <math.h>
@@ -154,8 +149,8 @@ void convert_pipe_to_node_leakage(Project *pr)
     Snode *node1;
     Snode *node2;
 
-    // Orifice coeff. with conversion from sq. mm to sq. m
-    c_orif = 4.8149866 * 1.e-6;
+    // Orifice coeff. = 0.6 * sqrt(2 * g) * (sq m per sq mm)
+    c_orif = 4.8149766 * 1.e-6;
 
     // Examine each link
     for (i = 1; i <= net->Nlinks; i++)
@@ -173,10 +168,10 @@ void convert_pipe_to_node_leakage(Project *pr)
         // Get pipe's fixed and variable area leak coeffs.
         if (link->LeakArea == 0.0 && link->LeakExpan == 0.0) continue;
         c_area = c_orif * link->LeakArea / SQR(MperFT);
-        c_expan = c_orif * link->LeakExpan;
+        c_expan = c_orif * link->LeakExpan / MperFT;
 
         // Adjust for number of 100-ft pipe sections
-        len = link->Len * pr->Ucf[LENGTH] / 100.;
+        len = link->Len / 100.;
         if (node1->Type == JUNCTION && node2->Type == JUNCTION)
         {
             len *= 0.5;
@@ -286,11 +281,11 @@ double findlinkleakage(Project *pr, int i)
     h2 = hyd->NodeHead[n2] - net->Node[n2].El;
     h2 = MAX(h2, 0.0);
 
-    // Pipe leak parameters converted to feet
+    // Pipe leak parameters
     a = link->LeakArea / SQR(MperFT);
-    m = link->LeakExpan;
-    len = link->Len * pr->Ucf[LENGTH] / 100.; // # 100 ft pipe lengths
-    c = 4.8149866 * len / 2.0 * 1.e-6;
+    m = link->LeakExpan / MperFT;
+    len = link->Len / 100.; // # 100 ft pipe lengths
+    c = 4.8149766 * (len / 2.0) * 1.0e-6;
 
     // Leakage from 1st half of pipe connected to node n1
     q1 = 0.0;

src/types.h

@@ -7,7 +7,7 @@
  Authors:      see AUTHORS
  Copyright:    see AUTHORS
  License:      see LICENSE
- Last Updated: 09/03/2025
+ Last Updated: 02/03/2026
  ******************************************************************************
 */
 
@@ -31,7 +31,7 @@ typedef  int          INT4;
    Various constants
 ----------------------------------------------
 */
-#define   CODEVERSION        20303
+#define   CODEVERSION        20304
 #define   MAGICNUMBER        516114521
 #define   ENGINE_VERSION     201   // Used for binary hydraulics file
 #define   EOFMARK            0x1A  // Use 0x04 for UNIX systems

tests/test_leakage.cpp

@@ -7,7 +7,7 @@
  Authors:      see AUTHORS
  Copyright:    see AUTHORS
  License:      see LICENSE
- Last Updated: 06/26/2024
+ Last Updated: 02/02/2026
  ******************************************************************************
 */
 
@@ -33,6 +33,9 @@ BOOST_AUTO_TEST_CASE(test_leakage_model)
     int Pipe21, Junc21, Junc22;
 	double pipe21Leak, junc21Leak, junc22Leak;
     EN_Project ph = NULL;
+    double A, C, M, L, E1, E2, H1, H2, Q1, Q2, Q;
+    const double GPMperCFS = 448.831;
+    const double MperFT = 0.3048;
 
     error = EN_createproject(&ph);
     BOOST_REQUIRE(error == 0);
@@ -82,6 +85,42 @@ BOOST_AUTO_TEST_CASE(test_leakage_model)
 	//printf("\n Node leakage flow: %.4f\n", junc21Leak + junc22Leak);
     BOOST_REQUIRE(abs(pipe21Leak - (junc21Leak+junc22Leak)) < 0.01);
 
+    // Independently verify pipe leakage flow
+    
+    // Retrieve leak parameters (in mm units)
+    EN_getlinkvalue(ph, Pipe21, EN_LEAK_AREA, &A);
+    EN_getlinkvalue(ph, Pipe21, EN_LEAK_EXPAN, &M);
+    
+    // Convert leak parameters to feet units
+    A = A / MperFT / MperFT / 1.e6;
+    M = M / MperFT / 1.e6;
+    
+    // Find number of 100-ft pipe lengths
+    EN_getlinkvalue(ph, Pipe21, EN_LENGTH, &L);
+    L = L / 100.;
+    
+    // Compute orifice coefficient
+    C = 0.6 * sqrt(2. * 32.2);
+    
+    // Find pressure heads at up and down stream nodes
+	EN_getnodevalue(ph, Junc21, EN_ELEVATION, &E1);
+	EN_getnodevalue(ph, Junc22, EN_ELEVATION, &E2);
+	EN_getnodevalue(ph, Junc21, EN_HEAD, &H1);
+	EN_getnodevalue(ph, Junc22, EN_HEAD, &H2);
+	H1 = H1 - E1;
+	H2 = H2 - E2;
+
+    // Compute leakage flow over each half of pipe (in cfs)
+    Q1 = C * (L/2.) * (A + M * H1) * sqrt(H1);
+    Q2 = C * (L/2.) * (A + M * H2) * sqrt(H2);
+    
+    // Find total pipe leakage in gpm
+    Q = (Q1 + Q2) * GPMperCFS;
+//    printf(" Calculated leakage: %.4f\n", Q);
+    
+    // Compare pipe leakage with EPANET's value
+    BOOST_REQUIRE(abs(pipe21Leak - Q) < 0.01);
+
 // Clean up
     error = EN_close(ph);
     BOOST_REQUIRE(error == 0);