Ticket #438: 438-ee2fe24de015-howard-limit.patch

lemon/howard_mmc.h

@@ -149 +149 @@
     /// The \ref HowardMmcDefaultTraits "traits class" of the algorithm
     typedef TR Traits;
 
+    /// \brief Constants for the causes of search termination.
+    ///
+    /// Enum type containing constants for the different causes of search
+    /// termination. The \ref findCycleMean(int) function returns one of
+    /// these values.
+    enum TerminationCause {
+    
+      /// Optimal solution (minimum cycle mean) is found.
+      OPTIMAL,
+      
+      /// No directed cycle can be found in the digraph.
+      NO_CYCLE,
+
+      /// The iteration count limit is reached.
+      ITERATION_LIMIT
+    };
+
   private:
 
     TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
@@ -330 +347 @@
     /// cycles in the digraph.
     ///
     /// \return \c true if a directed cycle exists in the digraph.
+    ///
+    /// \note <tt>mmc.findCycleMean()</tt> is just a shortcut of the
+    /// following code.
+    /// \code
+    ///   return mmc.findCycleMean(-1) == mmc.OPTIMAL;
+    /// \endcode
     bool findCycleMean() {
+      return findCycleMean(-1) == OPTIMAL;
+    }
+
+    /// \brief Find the minimum cycle mean.
+    ///
+    /// This function finds the minimum mean cost of the directed
+    /// cycles in the digraph or at least an upper bound for it.
+    /// At most the given number of iterations are performed during
+    /// the search process. The return value indicates if the optimal
+    /// solution is found or the iteration limit is reached.
+    /// In the latter case, an approximate solution can be obtained
+    /// using the query functions.
+    /// Such an approximate solution corresponds to a directed cycle 
+    /// whose mean cost is relatively small, but not necessarily
+    /// minimal.
+    ///
+    /// \param limit  The maximum allowed number of iterations duirng
+    /// the search process. Negative values mean that this limitation
+    /// is disabled, i.e. the algorithm runs until it finds the exact
+    /// optimal solution.
+    ///
+    /// \return The termination cause of the search process.
+    /// For more information, see \ref TerminationCause. 
+    TerminationCause findCycleMean(int limit) {
       // Initialize and find strongly connected components
       init();
       findComponents();
+      
+      // Check iteration limit
+      if (limit < 0) limit = std::numeric_limits<int>::max();
 
       // Find the minimum cycle mean in the components
+      int iter_count = 0;
+      bool iter_limit = false;
       for (int comp = 0; comp < _comp_num; ++comp) {
         // Find the minimum mean cycle in the current component
         if (!buildPolicyGraph(comp)) continue;
         while (true) {
+          if (++iter_count > limit) {
+            iter_limit = true;
+            break;
+          }
           findPolicyCycle();
           if (!computeNodeDistances()) break;
         }
+
         // Update the best cycle (global minimum mean cycle)
         if ( _curr_found && (!_best_found ||
              _curr_cost * _best_size < _best_cost * _curr_size) ) {
@@ -351 +408 @@
           _best_size = _curr_size;
           _best_node = _curr_node;
         }
+        
+        if (iter_limit) break;
       }
-      return _best_found;
+
+      if (iter_limit) {
+        return ITERATION_LIMIT;
+      } else {
+        return _best_found ? OPTIMAL : NO_CYCLE;
+      }
     }
 
     /// \brief Find a minimum mean directed cycle.

test/min_mean_cycle_test.cc

@@ -210 +210 @@
     checkMmcAlg<HowardMmc<GR, IntArcMap> >(gr, l2, c2,  5, 2);
     checkMmcAlg<HowardMmc<GR, IntArcMap> >(gr, l3, c3,  0, 1);
     checkMmcAlg<HowardMmc<GR, IntArcMap> >(gr, l4, c4, -1, 1);
+    
+    // Howard with iteration limit
+    HowardMmc<GR, IntArcMap> mmc(gr, l1);
+    check((mmc.findCycleMean(2) == HowardMmc<GR, IntArcMap>::ITERATION_LIMIT),
+      "Wrong termination cause");
+    check((mmc.findCycleMean(4) == HowardMmc<GR, IntArcMap>::OPTIMAL),
+      "Wrong termination cause");
   }
 
   return 0;