epyt-flow 0.13.1__py3-none-any.whl → 0.14.1__py3-none-any.whl

epyt_flow/EPANET/EPANET/SRC_engines/quality.c

@@ -1,13 +1,13 @@
 /*
 ******************************************************************************
 Project:      OWA EPANET
-Version:      2.2
+Version:      2.3
 Module:       quality.c
 Description:  implements EPANET's water quality engine
 Authors:      see AUTHORS
 Copyright:    see AUTHORS
 License:      see LICENSE
-Last Updated: 05/15/2019
+Last Updated: 02/14/2025
 ******************************************************************************
 */
 
@@ -63,8 +63,16 @@ int openqual(Project *pr)
     // Build nodal adjacency lists if they don't already exist
     if (net->Adjlist == NULL)
     {
+        // Check for too few nodes & no fixed grade nodes
+        if (net->Nnodes < 2) return 223;
+        if (net->Ntanks == 0) return 224;
+    
+        // Build adjacency lists
         errcode = buildadjlists(net);
         if (errcode ) return errcode;
+
+        // Check for unconnected nodes
+        if (errcode = unlinked(pr)) return errcode;
     }
 
     // Create a memory pool for water quality segments
@@ -175,6 +183,7 @@ int initqual(Project *pr)
     qual->MassBalance.reacted = 0.0;
     qual->MassBalance.final = 0.0;
     qual->MassBalance.ratio = 0.0;
+    qual->MassBalance.segCount = 0;
     return errcode;
 }
 
@@ -402,6 +411,7 @@ int closequal(Project *pr)
         FREE(qual->FlowDir);
         FREE(qual->SortedNodes);
     }
+    freeadjlists(&pr->network);
     return errcode;
 }
 

epyt_flow/EPANET/EPANET/SRC_engines/qualreact.c

@@ -1,13 +1,13 @@
 /*
 ******************************************************************************
 Project:      OWA EPANET
-Version:      2.2
+Version:      2.3
 Module:       qualreact.c
 Description:  computes water quality reactions within pipes and tanks
 Authors:      see AUTHORS
 Copyright:    see AUTHORS
 License:      see LICENSE
-Last Updated: 05/15/2019
+Last Updated: 12/16/2024
 ******************************************************************************
 */
 
@@ -232,7 +232,7 @@ double piperate(Project *pr, int k)
     }
 
     // Compute Reynolds No.
-    // Flow rate made consistent with how its saved to hydraulics file
+    // Flow rate made consistent with how it's saved to hydraulics file
     q = (hyd->LinkStatus[k] <= CLOSED) ? 0.0 : hyd->LinkFlow[k];
     a = PI * d * d / 4.0;         // pipe area
     u = fabs(q) / a;              // flow velocity
@@ -492,6 +492,13 @@ void tankmix1(Project *pr, int i, double vin, double win, double vnet)
        seg->v += vnet;
        seg->v = MAX(0.0, seg->v);
        tank->C = seg->c;
+       
+        // Account for mass lost in tank overflow
+        if (seg->v > tank->Vmax)
+        {
+            qual->MassBalance.outflow += ((seg->v) - tank->Vmax) * tank->C;
+            seg->v = tank->Vmax;
+        }
     }
 }
 
@@ -513,7 +520,8 @@ void tankmix2(Project *pr, int i, double vin, double win, double vnet)
 
     int    k;
     double vt,          // Transferred volume
-           vmz;         // Full mixing zone volume
+           vmz,         // Full mixing zone volume
+           vsz;         // Full stagnant zone volume
     Pseg   mixzone,     // Mixing zone segment
            stagzone;    // Stagnant zone segment
     Stank  *tank = &pr->network.Tank[i];
@@ -525,7 +533,7 @@ void tankmix2(Project *pr, int i, double vin, double win, double vnet)
     if (mixzone == NULL || stagzone == NULL) return;
 
     // Full mixing zone volume
-    vmz = tank->V1max;
+    vmz = tank->V1frac * tank->Vmax;
 
     // Tank is filling
     vt = 0.0;
@@ -558,16 +566,31 @@ void tankmix2(Project *pr, int i, double vin, double win, double vnet)
     // Update segment volumes
     if (vt > 0.0)
     {
-        mixzone->v = vmz;
-        if (vnet > 0.0) stagzone->v += vt;
-        else            stagzone->v = MAX(0.0, ((stagzone->v) - vt));
+        if (vnet > 0.0)
+        {
+           mixzone->v = vmz;
+           stagzone->v += vt;
+            
+            // Account for mass lost in overflow from stagnant zone
+            vsz = (tank->Vmax) - vmz;
+            if (stagzone->v > vsz)
+            {
+                qual->MassBalance.outflow += ((stagzone->v) - vsz) * stagzone->c;
+                stagzone->v = vsz;
+            }
+        }
+        else
+        {
+            stagzone->v = MAX(0.0, ((stagzone->v) - vt));
+            mixzone->v = vmz + vt + vnet;
+        }
     }
     else
     {
         mixzone->v += vnet;
         mixzone->v = MIN(mixzone->v, vmz);
         mixzone->v = MAX(0.0, mixzone->v);
-        stagzone->v = 0.0;
+        if (vmz - mixzone->v > 0.0) stagzone->v = 0.0;
     }
 
     // Use quality of mixing zone to represent quality of
@@ -612,10 +635,13 @@ void tankmix3(Project *pr, int i, double vin, double win, double vnet)
         else addseg(pr, k, vin, cin);
     }
 
-    // Withdraw flow from first segment
+    // Find volume leaving tank, adjusted so its volume doesn't exceed Vmax
+    vout = vin - vnet;
+    if (tank->V >= tank->Vmax && vnet > 0.0) vout = vin;
+
+    // Withdraw outflow from first segment
     vsum = 0.0;
     wsum = 0.0;
-    vout = vin - vnet;
     while (vout > 0.0)
     {
         seg = qual->FirstSeg[k];
@@ -643,6 +669,10 @@ void tankmix3(Project *pr, int i, double vin, double win, double vnet)
     if      (vsum > 0.0)                tank->C = wsum / vsum;
     else if (qual->FirstSeg[k] == NULL) tank->C = 0.0;
     else                                tank->C = qual->FirstSeg[k]->c;
+    
+    // Account for mass lost in overflow from 1st segment
+    if (tank->V >= tank->Vmax && vnet > 0.0)
+        qual->MassBalance.outflow += vnet * tank->C;
 }
 
 
@@ -669,7 +699,7 @@ void tankmix4(Project *pr, int i, double vin, double win, double vnet)
     k = net->Nlinks + i;
     if (qual->LastSeg[k] == NULL || qual->FirstSeg[k] == NULL) return;
 
-    // Find inflows & outflows
+    // Find inflow concentration
     if (vin > 0.0) cin = win / vin;
     else           cin = 0.0;
 
@@ -687,6 +717,33 @@ void tankmix4(Project *pr, int i, double vin, double win, double vnet)
 
         // Update reported tank quality
         tank->C = qual->LastSeg[k]->c;
+        
+        // If tank full then remove vnet from leading segments
+        if (tank->V >= tank->Vmax)
+        {
+            wsum = 0.0;
+            while (vnet > 0.0)
+            {
+                seg = qual->FirstSeg[k];
+                if (seg == NULL)  break;
+                vseg = seg->v;               // Flow volume from leading seg
+                vseg = MIN(vseg, vnet);
+                if (seg == qual->LastSeg[k]) vseg = vnet;
+                wsum += (seg->c) * vseg;
+                vnet -= vseg;               // Remaining flow volume
+                if (vnet >= 0.0 && vseg >= seg->v)  // Seg used up
+                {
+                    if (seg->prev)
+                    {
+                        qual->FirstSeg[k] = seg->prev;
+                        seg->prev = qual->FreeSeg;
+                        qual->FreeSeg = seg;
+                    }
+                }
+                else seg->v -= vseg;   // Remaining volume in segment
+            }
+            qual->MassBalance.outflow += wsum;
+        }
     }
 
     // If tank emptying then remove last segments until vnet consumed
@@ -715,7 +772,7 @@ void tankmix4(Project *pr, int i, double vin, double win, double vnet)
             vsum += vseg;
             wsum += (seg->c) * vseg;
 
-            // ... update remiaing volume to remove
+            // ... update remaining volume to remove
             vnet -= vseg;
 
             // ... if no more volume left in current segment

epyt_flow/EPANET/EPANET/SRC_engines/qualroute.c

@@ -1,13 +1,13 @@
 /*
 ******************************************************************************
 Project:      OWA EPANET
-Version:      2.2
+Version:      2.3
 Module:       qualroute.c
 Description:  computes water quality transport over a single time step
 Authors:      see AUTHORS
 Copyright:    see AUTHORS
 License:      see LICENSE
-Last Updated: 05/15/2019
+Last Updated: 02/14/2025
 ******************************************************************************
 */
 
@@ -183,6 +183,7 @@ void  evalnodeinflow(Project *pr, int k, long tstep, double *volin,
             // ... recycle the used up segment
             seg->prev = qual->FreeSeg;
             qual->FreeSeg = seg;
+            qual->MassBalance.segCount--;                                         
         }
 
         // ... otherwise just reduce this segment's volume
@@ -246,7 +247,7 @@ double  findnodequal(Project *pr, int n, double volin,
         return qual->NodeQual[n];
     }
 
-    // Find quality contribued by any external chemical source
+    // Find quality contributed by any external chemical source
     else qual->SourceQual = findsourcequal(pr, n, volout, tstep);
     if (qual->SourceQual == 0.0) return qual->NodeQual[n];
 
@@ -609,10 +610,10 @@ void initsegs(Project *pr)
         addseg(pr, k, v, c);
 
         // Create a 2nd segment for the 2-compartment tank model
-        if (net->Tank[j].MixModel == MIX2)
+        if (!qual->OutOfMemory && net->Tank[j].MixModel == MIX2)
         {
             // ... mixing zone segment
-            v1 = MAX(0, v - net->Tank[j].V1max);
+            v1 = MAX(0, v - net->Tank[j].V1frac * net->Tank[j].Vmax);
             qual->FirstSeg[k]->v = v1;
 
             // ... stagnant zone segment
@@ -691,4 +692,5 @@ void addseg(Project *pr, int k, double v, double c)
     if (qual->FirstSeg[k] == NULL) qual->FirstSeg[k] = seg;
     if (qual->LastSeg[k] != NULL)  qual->LastSeg[k]->prev = seg;
     qual->LastSeg[k] = seg;
+    qual->MassBalance.segCount++;                                     
 }

epyt_flow/EPANET/EPANET/SRC_engines/report.c

@@ -1,13 +1,13 @@
 /*
  ******************************************************************************
  Project:      OWA EPANET
- Version:      2.2
+ Version:      2.3
  Module:       report.c
  Description:  procedures for writing formatted text to a report file
  Authors:      see AUTHORS
  Copyright:    see AUTHORS
  License:      see LICENSE
- Last Updated: 07/22/2019
+ Last Updated: 02/14/2025
  ******************************************************************************
 */
 
@@ -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);
@@ -67,7 +67,7 @@ int clearreport(Project *pr)
     return 0;
 }
 
-int copyreport(Project* pr, char *filename)
+int copyreport(Project* pr, const char *filename)
 /*
 **------------------------------------------------------
 **   Input:   filename = name of file to copy to
@@ -291,7 +291,7 @@ void writesummary(Project *pr)
   if (qual->Qualflag == NONE || time->Dur == 0.0) sprintf(s, FMT29);
   else if (qual->Qualflag == CHEM)  sprintf(s, FMT30, qual->ChemName);
   else if (qual->Qualflag == TRACE) sprintf(s, FMT31, net->Node[qual->TraceNode].ID);
-  else if (qual->Qualflag == AGE)   printf(s, FMT32);
+  else if (qual->Qualflag == AGE)   sprintf(s, FMT32);
   writeline(pr, s);
   if (qual->Qualflag != NONE && time->Dur > 0)
   {
@@ -422,13 +422,51 @@ void writehydstat(Project *pr, int iter, double relerr)
   writeline(pr, " ");
 }
 
+void writeflowbalance(Project *pr)
+/*
+**-------------------------------------------------------------
+**   Input:   none
+**   Output:  none
+**   Purpose: writes hydraulic flow balance ratio to report file.
+**-------------------------------------------------------------
+*/
+{
+    Hydraul *hyd = &pr->hydraul;
+    Report  *rpt = &pr->report;
+    char s1[MAXMSG+1];
+    double ucf = pr->Ucf[FLOW];
+
+    snprintf(s1, MAXMSG, "Hydraulic Flow Balance (%s)", rpt->Field[DEMAND].Units);
+    writeline(pr, s1);
+    snprintf(s1, MAXMSG, "================================");
+    writeline(pr, s1);
+    snprintf(s1, MAXMSG, "Total Inflow:      %12.3f", hyd->FlowBalance.totalInflow*ucf);
+    writeline(pr, s1);
+    snprintf(s1, MAXMSG, "Consumer Demand:   %12.3f", hyd->FlowBalance.consumerDemand*ucf);
+    writeline(pr, s1);
+    snprintf(s1, MAXMSG, "Demand Deficit:    %12.3f", hyd->FlowBalance.deficitDemand*ucf);
+    writeline(pr, s1);
+    snprintf(s1, MAXMSG, "Emitter Flow:      %12.3f", hyd->FlowBalance.emitterDemand*ucf);
+    writeline(pr, s1);
+    snprintf(s1, MAXMSG, "Leakage Flow:      %12.3f", hyd->FlowBalance.leakageDemand*ucf);
+    writeline(pr, s1);
+    snprintf(s1, MAXMSG, "Total Outflow:     %12.3f", hyd->FlowBalance.totalOutflow*ucf);
+    writeline(pr, s1);
+    snprintf(s1, MAXMSG, "Storage Flow:      %12.3f", hyd->FlowBalance.storageDemand*ucf);
+    writeline(pr, s1);
+    snprintf(s1, MAXMSG, "Flow Ratio:        %12.3f", hyd->FlowBalance.ratio);
+    writeline(pr, s1);
+    snprintf(s1, MAXMSG, "================================\n");
+    writeline(pr, s1);
+}
+    
 void writemassbalance(Project *pr)
 /*
 **-------------------------------------------------------------
 **   Input:   none
 **   Output:  none
 **   Purpose: writes water quality mass balance ratio
-**            (Outflow + Final Storage) / Inflow + Initial Storage)
+**            (Outflow + Final Storage) / Inflow + Initial Storage
 **            to report file.
 **-------------------------------------------------------------
 */
@@ -463,6 +501,8 @@ void writemassbalance(Project *pr)
     writeline(pr, s1);
     snprintf(s1, MAXMSG, "Mass Ratio:         %-.5f", qual->MassBalance.ratio);
     writeline(pr, s1);
+    snprintf(s1, MAXMSG, "Total Segments:     %d", qual->MassBalance.segCount);
+    writeline(pr, s1);                          
     snprintf(s1, MAXMSG, "================================\n");
     writeline(pr, s1);
 }
@@ -876,7 +916,7 @@ void writeheader(Project *pr, int type, int contin)
     }
 }
 
-void writeline(Project *pr, char *s)
+void writeline(Project *pr, const char *s)
 /*
 **--------------------------------------------------------------
 **   Input:   *s = text string
@@ -886,6 +926,12 @@ void writeline(Project *pr, char *s)
 */
 {
     Report *rpt = &pr->report;
+    
+    if (pr->report.reportCallback != NULL)
+    {
+        pr->report.reportCallback(pr->report.reportCallbackUserData, pr, s);
+        return;
+    }
 
     if (rpt->RptFile == NULL) return;
     if (rpt->Rptflag)
@@ -1281,7 +1327,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
@@ -1344,11 +1390,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.
 **----------------------------------------------------------------
@@ -1359,20 +1406,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)
-    {
-        k = alink->link;
-        j = alink->node;
-        if (marked[j] == 2) continue;
-        if (marked[j] == 1)
-        {
-            sprintf(pr->Msg, WARN03c, net->Link[k].ID);
-            writeline(pr, pr->Msg);
-            return;
+    stack[top] = i;
+
+    while (top >= 0) {
+        i = stack[top--];
+        alink = net->Adjlist[i];
+        
+        // Iterate through each link adjacent to the current node
+        while (alink != NULL) {
+            k = alink->link;
+            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)

epyt_flow/EPANET/EPANET/SRC_engines/rules.c

@@ -1,13 +1,13 @@
 /*
  ******************************************************************************
  Project:      OWA EPANET
- Version:      2.2
+ Version:      2.3
  Module:       rules.c
  Description:  implements rule-based controls
  Authors:      see AUTHORS
  Copyright:    see AUTHORS
  License:      see LICENSE
- Last Updated: 05/15/2019
+ Last Updated: 02/11/2025
  ******************************************************************************
 */
 
@@ -32,10 +32,11 @@ enum Rulewords {
   r_THEN,
   r_ELSE,
   r_PRIORITY,
+  r_DISABLED,
   r_ERROR
 };
 char *Ruleword[] = {w_RULE, w_IF,   w_AND,      w_OR,
-                    w_THEN, w_ELSE, w_PRIORITY, NULL};
+                    w_THEN, w_ELSE, w_PRIORITY, w_DISABLED, NULL};
 
 enum Varwords {
   r_DEMAND,
@@ -273,6 +274,16 @@ int ruledata(Project *pr)
           err = newpriority(pr);
           break;
 
+        case r_DISABLED:
+          if (rules->RuleState != r_THEN && rules->RuleState != r_ELSE &&
+              rules->RuleState != r_PRIORITY)
+          {
+              err = 221; 
+              break;
+          }
+          net->Rule[net->Nrules].isEnabled = FALSE;
+          break;
+
         default:
           err = 201;
     }
@@ -404,7 +415,7 @@ void adjustrules(Project *pr, int objtype, int index)
     }
 }
 
-void adjusttankrules(Project *pr)
+void adjusttankrules(Project *pr, int ndiff)
 //-----------------------------------------------------------
 //    Adjusts tank indices in rule premises.
 //-----------------------------------------------------------
@@ -420,7 +431,8 @@ void adjusttankrules(Project *pr)
         p = net->Rule[i].Premises;
         while (p != NULL)
         {
-            if (p->object == r_NODE && p->index > njuncs) p->index++;
+            if (p->object == r_NODE && p->index > njuncs)
+                p->index += ndiff;
             p = p->next;
         }
     }
@@ -472,7 +484,7 @@ int writerule(Project *pr, FILE *f, int ruleIndex)
     Srule      *rule = &net->Rule[ruleIndex];
     Spremise   *p;
     Saction    *a;
-
+    
     // Write each premise clause to the file
     p = rule->Premises;
     fprintf(f, "\nIF   ");
@@ -527,6 +539,11 @@ int checkrules(Project *pr, long dt)
     rules->ActionList = NULL;
     for (i = 1; i <= net->Nrules; i++)
     {
+        // skip if the rule is disabled
+        if (!net->Rule[i].isEnabled)
+        {
+            continue;
+        }
         // If premises true, add THEN clauses to action list
         if (evalpremises(pr, i) == TRUE)
         {
@@ -549,6 +566,126 @@ int checkrules(Project *pr, long dt)
     return actionCount;
 }
 
+void updateruleunits(Project *pr, double dcf, double pcf, double hcf, double qcf)
+//-----------------------------------------------------------
+//    Updates the units of a rule's premises and actions.
+//-----------------------------------------------------------
+{
+    Network *net = &pr->network;
+    Slink  *Link = net->Link;
+
+    int i, k;
+    double x;
+    Spremise *p;
+    Saction *a;
+    
+    for (i = 1; i <= net->Nrules; i++)
+    {
+        p = net->Rule[i].Premises;
+        while (p != NULL)
+        {
+
+            switch (p->variable)
+            {
+            case r_DEMAND:
+                p->value *= dcf;
+                break;
+
+            case r_HEAD:
+            case r_GRADE:
+                p->value *= hcf;
+                break;
+
+            case r_PRESSURE:
+                p->value *= pcf;
+                break;
+
+            case r_LEVEL:
+                p->value *= hcf;
+                break;
+
+            case r_FLOW:
+                p->value *= qcf;
+                break;
+
+            case r_SETTING:
+
+                switch (Link[p->index].Type)
+                {
+                case PRV:
+                case PSV:
+                case PBV:
+                    p->value *= pcf;
+                    break;
+                case FCV:
+                    p->value *= qcf;
+                    break;
+                default:
+                    break;
+                }
+                break;
+            
+            default:
+                break;
+
+            }
+            p = p->next;
+        }
+
+        a = net->Rule[i].ThenActions;
+        while (a != NULL)
+        {
+            k = a->link;
+            x = a->setting;
+
+            // Change link's setting
+            if (x != MISSING)
+            {
+                switch (net->Link[k].Type)
+                {
+                case PRV:
+                case PSV:
+                case PBV:
+                    a->setting *= pcf;
+                    break;
+                case FCV:
+                    a->setting *= qcf;
+                    break;
+                default:
+                    break;
+                }
+            }
+            a = a->next;
+        }
+        a = net->Rule[i].ElseActions;
+        while (a != NULL)
+        {
+            k = a->link;
+            x = a->setting;
+
+            // Change link's setting
+            if (x != MISSING)
+            {
+                switch (net->Link[k].Type)
+                {
+                case PRV:
+                case PSV:
+                case PBV:
+                    a->setting *= pcf;
+                    break;
+                case FCV:
+                    a->setting *= qcf;
+                    break;
+                default:
+                    break;
+                }
+            }
+            a = a->next;
+        }
+    }
+}
+
+
 void newrule(Project *pr)
 //----------------------------------------------------------
 //    Adds a new rule to the project
@@ -564,6 +701,7 @@ void newrule(Project *pr)
     rule->ThenActions = NULL;
     rule->ElseActions = NULL;
     rule->priority = 0.0;
+    rule->isEnabled = TRUE;
     pr->rules.LastPremise = NULL;
     pr->rules.LastThenAction = NULL;
     pr->rules.LastElseAction = NULL;