adds an API function to get information about upcoming events

include/epanet2_2.h

@@ -638,6 +638,16 @@ typedef struct Project *EN_Project;
   */
   int  DLLEXPORT EN_getstatistic(EN_Project ph, int type, double* out_value);
 
+
+  /**
+  @brief Get information about upcoming time step events, and what causes them.
+  @param ph an EPANET project handle.
+  @param[out] eventType the type of event that will occur.
+  @param[out] duration the amount of time in the future this event will occur
+  @param[out] elementIndex the index of the element causing the event.
+  **/
+  int DLLEXPORT EN_timeToNextEvent(EN_Project ph, EN_TimestepEvent *eventType, long *duration, int *elementIndex);
+
   /**
   @brief Retrieves the order in which a node or link appears in an @ref OutFile "output file".
   @param ph an EPANET project handle.

include/epanet2_enums.h

@@ -125,6 +125,18 @@ typedef enum {
   EN_NEXTEVENTTANK = 15  //!< Index of tank with shortest time to become empty or full (read only)
 } EN_TimeParameter;
 
+
+/**
+These are the types of events that can cause a timestep to end.
+**/
+typedef enum {
+  EN_STEP_REPORT       = 0,
+  EN_STEP_HYD          = 1,
+  EN_STEP_WQ           = 2,
+  EN_STEP_TANKEVENT    = 3,
+  EN_STEP_CONTROLEVENT = 4
+} EN_TimestepEvent;
+
 /// Analysis convergence statistics
 /**
 These statistics report the convergence criteria for the most current hydraulic analysis

src/epanet.c

@@ -1610,6 +1610,41 @@ int DLLEXPORT EN_settimeparam(EN_Project p, int param, long value)
     return 0;
 }
 
+
+/// get the time to next event, and give a reason for the time step truncation
+int  DLLEXPORT EN_timeToNextEvent(EN_Project p, EN_TimestepEvent *eventType, long *duration, int *elementIndex)
+{
+  Times  *time = &p->times;
+  long hydStep, tankStep, controlStep;
+
+  hydStep = time->Hstep;
+  tankStep = hydStep;
+  controlStep = hydStep;
+
+  int iTank = tanktimestep(p, &tankStep);
+  int iControl = controltimestep(p, &controlStep);
+
+  // return the lesser of the three step lengths
+  if (controlStep < tankStep) {
+    *eventType = EN_STEP_CONTROLEVENT;
+    *duration = controlStep;
+    *elementIndex = iControl;
+  }
+  else if (tankStep < hydStep) {
+    *eventType = EN_STEP_TANKEVENT;
+    *duration = tankStep;
+    *elementIndex = iTank;
+  }
+  else {
+    *eventType = EN_STEP_HYD;
+    *duration = hydStep;
+    *elementIndex = 0;
+  }
+
+  return 0;
+}
+
+
 int DLLEXPORT EN_getqualinfo(EN_Project p, int *qualType, char *chemName,
                              char *chemUnits, int *traceNode)
 /*----------------------------------------------------------------

src/funcs.h

@@ -155,6 +155,7 @@ void    closehyd(Project *);
 void    setlinkstatus(Project *, int, char, StatusType *, double *);
 void    setlinksetting(Project *, int, double, StatusType *, double *);
 int     tanktimestep(Project *, long *);
+int     controltimestep(Project *, long *);
 void    getenergy(Project *, int, double *, double *);
 double  tankvolume(Project *, int, double);
 double  tankgrade(Project *, int, double);

src/hydraul.c

@@ -34,7 +34,6 @@ void    initlinkflow(Project *, int, char, double);
 void    demands(Project *);
 int     controls(Project *);
 long    timestep(Project *);
-void    controltimestep(Project *, long *);
 void    ruletimestep(Project *, long *);
 void    addenergy(Project *, long);
 void    tanklevels(Project *, long);
@@ -704,7 +703,7 @@ int  tanktimestep(Project *pr, long *tstep)
 }
 
 
-void  controltimestep(Project *pr, long *tstep)
+int  controltimestep(Project *pr, long *tstep)
 /*
 **------------------------------------------------------------------
 **  Input:   *tstep = current time step
@@ -717,7 +716,7 @@ void  controltimestep(Project *pr, long *tstep)
     Network *net = &pr->network;
     Hydraul *hyd = &pr->hydraul;
 
-    int    i, j, k, n;
+    int    i, j, k, n, controlIndex;
     double h, q, v;
     long   t, t1, t2;
     Slink  *link;
@@ -774,10 +773,15 @@ void  controltimestep(Project *pr, long *tstep)
             k = control->Link;
             link = &net->Link[k];
             if ( (link->Type > PIPE && hyd->LinkSetting[k] != control->Setting)
-            ||   (hyd->LinkStatus[k] != control->Status) ) *tstep = t;
+              || (hyd->LinkStatus[k] != control->Status) )
+            {
+              *tstep = t;
+              controlIndex = i;
             }
         }
     }
+    return controlIndex;
+}
 
 
 void  ruletimestep(Project *pr, long *tstep)
@@ -1131,4 +1135,3 @@ void resetpumpflow(Project *pr, int i)
     if (pump->Ptype == CONST_HP)
         pr->hydraul.LinkFlow[i] = pump->Q0;
 }
-