lemon/howard_mmc.h
author Alpar Juttner <alpar@cs.elte.hu>
Wed, 17 Oct 2018 19:18:04 +0200
branch1.3
changeset 1178 e5af35e6c93f
parent 1092 dceba191c00d
permissions -rw-r--r--
Merge bugfixes #610,#611,#612,#614 to branch 1.3
     1 /* -*- mode: C++; indent-tabs-mode: nil; -*-
     2  *
     3  * This file is a part of LEMON, a generic C++ optimization library.
     4  *
     5  * Copyright (C) 2003-2013
     6  * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
     7  * (Egervary Research Group on Combinatorial Optimization, EGRES).
     8  *
     9  * Permission to use, modify and distribute this software is granted
    10  * provided that this copyright notice appears in all copies. For
    11  * precise terms see the accompanying LICENSE file.
    12  *
    13  * This software is provided "AS IS" with no warranty of any kind,
    14  * express or implied, and with no claim as to its suitability for any
    15  * purpose.
    16  *
    17  */
    18 
    19 #ifndef LEMON_HOWARD_MMC_H
    20 #define LEMON_HOWARD_MMC_H
    21 
    22 /// \ingroup min_mean_cycle
    23 ///
    24 /// \file
    25 /// \brief Howard's algorithm for finding a minimum mean cycle.
    26 
    27 #include <vector>
    28 #include <limits>
    29 #include <lemon/core.h>
    30 #include <lemon/path.h>
    31 #include <lemon/tolerance.h>
    32 #include <lemon/connectivity.h>
    33 
    34 namespace lemon {
    35 
    36   /// \brief Default traits class of HowardMmc class.
    37   ///
    38   /// Default traits class of HowardMmc class.
    39   /// \tparam GR The type of the digraph.
    40   /// \tparam CM The type of the cost map.
    41   /// It must conform to the \ref concepts::ReadMap "ReadMap" concept.
    42 #ifdef DOXYGEN
    43   template <typename GR, typename CM>
    44 #else
    45   template <typename GR, typename CM,
    46     bool integer = std::numeric_limits<typename CM::Value>::is_integer>
    47 #endif
    48   struct HowardMmcDefaultTraits
    49   {
    50     /// The type of the digraph
    51     typedef GR Digraph;
    52     /// The type of the cost map
    53     typedef CM CostMap;
    54     /// The type of the arc costs
    55     typedef typename CostMap::Value Cost;
    56 
    57     /// \brief The large cost type used for internal computations
    58     ///
    59     /// The large cost type used for internal computations.
    60     /// It is \c long \c long if the \c Cost type is integer,
    61     /// otherwise it is \c double.
    62     /// \c Cost must be convertible to \c LargeCost.
    63     typedef double LargeCost;
    64 
    65     /// The tolerance type used for internal computations
    66     typedef lemon::Tolerance<LargeCost> Tolerance;
    67 
    68     /// \brief The path type of the found cycles
    69     ///
    70     /// The path type of the found cycles.
    71     /// It must conform to the \ref lemon::concepts::Path "Path" concept
    72     /// and it must have an \c addBack() function.
    73     typedef lemon::Path<Digraph> Path;
    74   };
    75 
    76   // Default traits class for integer cost types
    77   template <typename GR, typename CM>
    78   struct HowardMmcDefaultTraits<GR, CM, true>
    79   {
    80     typedef GR Digraph;
    81     typedef CM CostMap;
    82     typedef typename CostMap::Value Cost;
    83 #ifdef LEMON_HAVE_LONG_LONG
    84     typedef long long LargeCost;
    85 #else
    86     typedef long LargeCost;
    87 #endif
    88     typedef lemon::Tolerance<LargeCost> Tolerance;
    89     typedef lemon::Path<Digraph> Path;
    90   };
    91 
    92 
    93   /// \addtogroup min_mean_cycle
    94   /// @{
    95 
    96   /// \brief Implementation of Howard's algorithm for finding a minimum
    97   /// mean cycle.
    98   ///
    99   /// This class implements Howard's policy iteration algorithm for finding
   100   /// a directed cycle of minimum mean cost in a digraph
   101   /// \cite dasdan98minmeancycle, \cite dasdan04experimental.
   102   /// This class provides the most efficient algorithm for the
   103   /// minimum mean cycle problem, though the best known theoretical
   104   /// bound on its running time is exponential.
   105   ///
   106   /// \tparam GR The type of the digraph the algorithm runs on.
   107   /// \tparam CM The type of the cost map. The default
   108   /// map type is \ref concepts::Digraph::ArcMap "GR::ArcMap<int>".
   109   /// \tparam TR The traits class that defines various types used by the
   110   /// algorithm. By default, it is \ref HowardMmcDefaultTraits
   111   /// "HowardMmcDefaultTraits<GR, CM>".
   112   /// In most cases, this parameter should not be set directly,
   113   /// consider to use the named template parameters instead.
   114 #ifdef DOXYGEN
   115   template <typename GR, typename CM, typename TR>
   116 #else
   117   template < typename GR,
   118              typename CM = typename GR::template ArcMap<int>,
   119              typename TR = HowardMmcDefaultTraits<GR, CM> >
   120 #endif
   121   class HowardMmc
   122   {
   123   public:
   124 
   125     /// The type of the digraph
   126     typedef typename TR::Digraph Digraph;
   127     /// The type of the cost map
   128     typedef typename TR::CostMap CostMap;
   129     /// The type of the arc costs
   130     typedef typename TR::Cost Cost;
   131 
   132     /// \brief The large cost type
   133     ///
   134     /// The large cost type used for internal computations.
   135     /// By default, it is \c long \c long if the \c Cost type is integer,
   136     /// otherwise it is \c double.
   137     typedef typename TR::LargeCost LargeCost;
   138 
   139     /// The tolerance type
   140     typedef typename TR::Tolerance Tolerance;
   141 
   142     /// \brief The path type of the found cycles
   143     ///
   144     /// The path type of the found cycles.
   145     /// Using the \ref lemon::HowardMmcDefaultTraits "default traits class",
   146     /// it is \ref lemon::Path "Path<Digraph>".
   147     typedef typename TR::Path Path;
   148 
   149     /// The \ref lemon::HowardMmcDefaultTraits "traits class" of the algorithm
   150     typedef TR Traits;
   151 
   152     /// \brief Constants for the causes of search termination.
   153     ///
   154     /// Enum type containing constants for the different causes of search
   155     /// termination. The \ref findCycleMean() function returns one of
   156     /// these values.
   157     enum TerminationCause {
   158 
   159       /// No directed cycle can be found in the digraph.
   160       NO_CYCLE = 0,
   161 
   162       /// Optimal solution (minimum cycle mean) is found.
   163       OPTIMAL = 1,
   164 
   165       /// The iteration count limit is reached.
   166       ITERATION_LIMIT
   167     };
   168 
   169   private:
   170 
   171     TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
   172 
   173     // The digraph the algorithm runs on
   174     const Digraph &_gr;
   175     // The cost of the arcs
   176     const CostMap &_cost;
   177 
   178     // Data for the found cycles
   179     bool _curr_found, _best_found;
   180     LargeCost _curr_cost, _best_cost;
   181     int _curr_size, _best_size;
   182     Node _curr_node, _best_node;
   183 
   184     Path *_cycle_path;
   185     bool _local_path;
   186 
   187     // Internal data used by the algorithm
   188     typename Digraph::template NodeMap<Arc> _policy;
   189     typename Digraph::template NodeMap<bool> _reached;
   190     typename Digraph::template NodeMap<int> _level;
   191     typename Digraph::template NodeMap<LargeCost> _dist;
   192 
   193     // Data for storing the strongly connected components
   194     int _comp_num;
   195     typename Digraph::template NodeMap<int> _comp;
   196     std::vector<std::vector<Node> > _comp_nodes;
   197     std::vector<Node>* _nodes;
   198     typename Digraph::template NodeMap<std::vector<Arc> > _in_arcs;
   199 
   200     // Queue used for BFS search
   201     std::vector<Node> _queue;
   202     int _qfront, _qback;
   203 
   204     Tolerance _tolerance;
   205 
   206     // Infinite constant
   207     const LargeCost INF;
   208 
   209   public:
   210 
   211     /// \name Named Template Parameters
   212     /// @{
   213 
   214     template <typename T>
   215     struct SetLargeCostTraits : public Traits {
   216       typedef T LargeCost;
   217       typedef lemon::Tolerance<T> Tolerance;
   218     };
   219 
   220     /// \brief \ref named-templ-param "Named parameter" for setting
   221     /// \c LargeCost type.
   222     ///
   223     /// \ref named-templ-param "Named parameter" for setting \c LargeCost
   224     /// type. It is used for internal computations in the algorithm.
   225     template <typename T>
   226     struct SetLargeCost
   227       : public HowardMmc<GR, CM, SetLargeCostTraits<T> > {
   228       typedef HowardMmc<GR, CM, SetLargeCostTraits<T> > Create;
   229     };
   230 
   231     template <typename T>
   232     struct SetPathTraits : public Traits {
   233       typedef T Path;
   234     };
   235 
   236     /// \brief \ref named-templ-param "Named parameter" for setting
   237     /// \c %Path type.
   238     ///
   239     /// \ref named-templ-param "Named parameter" for setting the \c %Path
   240     /// type of the found cycles.
   241     /// It must conform to the \ref lemon::concepts::Path "Path" concept
   242     /// and it must have an \c addBack() function.
   243     template <typename T>
   244     struct SetPath
   245       : public HowardMmc<GR, CM, SetPathTraits<T> > {
   246       typedef HowardMmc<GR, CM, SetPathTraits<T> > Create;
   247     };
   248 
   249     /// @}
   250 
   251   protected:
   252 
   253     HowardMmc() {}
   254 
   255   public:
   256 
   257     /// \brief Constructor.
   258     ///
   259     /// The constructor of the class.
   260     ///
   261     /// \param digraph The digraph the algorithm runs on.
   262     /// \param cost The costs of the arcs.
   263     HowardMmc( const Digraph &digraph,
   264                const CostMap &cost ) :
   265       _gr(digraph), _cost(cost), _best_found(false),
   266       _best_cost(0), _best_size(1), _cycle_path(NULL), _local_path(false),
   267       _policy(digraph), _reached(digraph), _level(digraph), _dist(digraph),
   268       _comp(digraph), _in_arcs(digraph),
   269       INF(std::numeric_limits<LargeCost>::has_infinity ?
   270           std::numeric_limits<LargeCost>::infinity() :
   271           std::numeric_limits<LargeCost>::max())
   272     {}
   273 
   274     /// Destructor.
   275     ~HowardMmc() {
   276       if (_local_path) delete _cycle_path;
   277     }
   278 
   279     /// \brief Set the path structure for storing the found cycle.
   280     ///
   281     /// This function sets an external path structure for storing the
   282     /// found cycle.
   283     ///
   284     /// If you don't call this function before calling \ref run() or
   285     /// \ref findCycleMean(), a local \ref Path "path" structure
   286     /// will be allocated. The destuctor deallocates this automatically
   287     /// allocated object, of course.
   288     ///
   289     /// \note The algorithm calls only the \ref lemon::Path::addBack()
   290     /// "addBack()" function of the given path structure.
   291     ///
   292     /// \return <tt>(*this)</tt>
   293     HowardMmc& cycle(Path &path) {
   294       if (_local_path) {
   295         delete _cycle_path;
   296         _local_path = false;
   297       }
   298       _cycle_path = &path;
   299       return *this;
   300     }
   301 
   302     /// \brief Set the tolerance used by the algorithm.
   303     ///
   304     /// This function sets the tolerance object used by the algorithm.
   305     ///
   306     /// \return <tt>(*this)</tt>
   307     HowardMmc& tolerance(const Tolerance& tolerance) {
   308       _tolerance = tolerance;
   309       return *this;
   310     }
   311 
   312     /// \brief Return a const reference to the tolerance.
   313     ///
   314     /// This function returns a const reference to the tolerance object
   315     /// used by the algorithm.
   316     const Tolerance& tolerance() const {
   317       return _tolerance;
   318     }
   319 
   320     /// \name Execution control
   321     /// The simplest way to execute the algorithm is to call the \ref run()
   322     /// function.\n
   323     /// If you only need the minimum mean cost, you may call
   324     /// \ref findCycleMean().
   325 
   326     /// @{
   327 
   328     /// \brief Run the algorithm.
   329     ///
   330     /// This function runs the algorithm.
   331     /// It can be called more than once (e.g. if the underlying digraph
   332     /// and/or the arc costs have been modified).
   333     ///
   334     /// \return \c true if a directed cycle exists in the digraph.
   335     ///
   336     /// \note <tt>mmc.run()</tt> is just a shortcut of the following code.
   337     /// \code
   338     ///   return mmc.findCycleMean() && mmc.findCycle();
   339     /// \endcode
   340     bool run() {
   341       return findCycleMean() && findCycle();
   342     }
   343 
   344     /// \brief Find the minimum cycle mean (or an upper bound).
   345     ///
   346     /// This function finds the minimum mean cost of the directed
   347     /// cycles in the digraph (or an upper bound for it).
   348     ///
   349     /// By default, the function finds the exact minimum cycle mean,
   350     /// but an optional limit can also be specified for the number of
   351     /// iterations performed during the search process.
   352     /// The return value indicates if the optimal solution is found
   353     /// or the iteration limit is reached. In the latter case, an
   354     /// approximate solution is provided, which corresponds to a directed
   355     /// cycle whose mean cost is relatively small, but not necessarily
   356     /// minimal.
   357     ///
   358     /// \param limit  The maximum allowed number of iterations during
   359     /// the search process. Its default value implies that the algorithm
   360     /// runs until it finds the exact optimal solution.
   361     ///
   362     /// \return The termination cause of the search process.
   363     /// For more information, see \ref TerminationCause.
   364     TerminationCause findCycleMean(int limit =
   365                                    std::numeric_limits<int>::max()) {
   366       // Initialize and find strongly connected components
   367       init();
   368       findComponents();
   369 
   370       // Find the minimum cycle mean in the components
   371       int iter_count = 0;
   372       bool iter_limit_reached = false;
   373       for (int comp = 0; comp < _comp_num; ++comp) {
   374         // Find the minimum mean cycle in the current component
   375         if (!buildPolicyGraph(comp)) continue;
   376         while (true) {
   377           if (++iter_count > limit) {
   378             iter_limit_reached = true;
   379             break;
   380           }
   381           findPolicyCycle();
   382           if (!computeNodeDistances()) break;
   383         }
   384 
   385         // Update the best cycle (global minimum mean cycle)
   386         if ( _curr_found && (!_best_found ||
   387              _curr_cost * _best_size < _best_cost * _curr_size) ) {
   388           _best_found = true;
   389           _best_cost = _curr_cost;
   390           _best_size = _curr_size;
   391           _best_node = _curr_node;
   392         }
   393 
   394         if (iter_limit_reached) break;
   395       }
   396 
   397       if (iter_limit_reached) {
   398         return ITERATION_LIMIT;
   399       } else {
   400         return _best_found ? OPTIMAL : NO_CYCLE;
   401       }
   402     }
   403 
   404     /// \brief Find a minimum mean directed cycle.
   405     ///
   406     /// This function finds a directed cycle of minimum mean cost
   407     /// in the digraph using the data computed by findCycleMean().
   408     ///
   409     /// \return \c true if a directed cycle exists in the digraph.
   410     ///
   411     /// \pre \ref findCycleMean() must be called before using this function.
   412     bool findCycle() {
   413       if (!_best_found) return false;
   414       _cycle_path->addBack(_policy[_best_node]);
   415       for ( Node v = _best_node;
   416             (v = _gr.target(_policy[v])) != _best_node; ) {
   417         _cycle_path->addBack(_policy[v]);
   418       }
   419       return true;
   420     }
   421 
   422     /// @}
   423 
   424     /// \name Query Functions
   425     /// The results of the algorithm can be obtained using these
   426     /// functions.\n
   427     /// The algorithm should be executed before using them.
   428 
   429     /// @{
   430 
   431     /// \brief Return the total cost of the found cycle.
   432     ///
   433     /// This function returns the total cost of the found cycle.
   434     ///
   435     /// \pre \ref run() or \ref findCycleMean() must be called before
   436     /// using this function.
   437     Cost cycleCost() const {
   438       return static_cast<Cost>(_best_cost);
   439     }
   440 
   441     /// \brief Return the number of arcs on the found cycle.
   442     ///
   443     /// This function returns the number of arcs on the found cycle.
   444     ///
   445     /// \pre \ref run() or \ref findCycleMean() must be called before
   446     /// using this function.
   447     int cycleSize() const {
   448       return _best_size;
   449     }
   450 
   451     /// \brief Return the mean cost of the found cycle.
   452     ///
   453     /// This function returns the mean cost of the found cycle.
   454     ///
   455     /// \note <tt>alg.cycleMean()</tt> is just a shortcut of the
   456     /// following code.
   457     /// \code
   458     ///   return static_cast<double>(alg.cycleCost()) / alg.cycleSize();
   459     /// \endcode
   460     ///
   461     /// \pre \ref run() or \ref findCycleMean() must be called before
   462     /// using this function.
   463     double cycleMean() const {
   464       return static_cast<double>(_best_cost) / _best_size;
   465     }
   466 
   467     /// \brief Return the found cycle.
   468     ///
   469     /// This function returns a const reference to the path structure
   470     /// storing the found cycle.
   471     ///
   472     /// \pre \ref run() or \ref findCycle() must be called before using
   473     /// this function.
   474     const Path& cycle() const {
   475       return *_cycle_path;
   476     }
   477 
   478     ///@}
   479 
   480   private:
   481 
   482     // Initialize
   483     void init() {
   484       if (!_cycle_path) {
   485         _local_path = true;
   486         _cycle_path = new Path;
   487       }
   488       _queue.resize(countNodes(_gr));
   489       _best_found = false;
   490       _best_cost = 0;
   491       _best_size = 1;
   492       _cycle_path->clear();
   493     }
   494 
   495     // Find strongly connected components and initialize _comp_nodes
   496     // and _in_arcs
   497     void findComponents() {
   498       _comp_num = stronglyConnectedComponents(_gr, _comp);
   499       _comp_nodes.resize(_comp_num);
   500       if (_comp_num == 1) {
   501         _comp_nodes[0].clear();
   502         for (NodeIt n(_gr); n != INVALID; ++n) {
   503           _comp_nodes[0].push_back(n);
   504           _in_arcs[n].clear();
   505           for (InArcIt a(_gr, n); a != INVALID; ++a) {
   506             _in_arcs[n].push_back(a);
   507           }
   508         }
   509       } else {
   510         for (int i = 0; i < _comp_num; ++i)
   511           _comp_nodes[i].clear();
   512         for (NodeIt n(_gr); n != INVALID; ++n) {
   513           int k = _comp[n];
   514           _comp_nodes[k].push_back(n);
   515           _in_arcs[n].clear();
   516           for (InArcIt a(_gr, n); a != INVALID; ++a) {
   517             if (_comp[_gr.source(a)] == k) _in_arcs[n].push_back(a);
   518           }
   519         }
   520       }
   521     }
   522 
   523     // Build the policy graph in the given strongly connected component
   524     // (the out-degree of every node is 1)
   525     bool buildPolicyGraph(int comp) {
   526       _nodes = &(_comp_nodes[comp]);
   527       if (_nodes->size() < 1 ||
   528           (_nodes->size() == 1 && _in_arcs[(*_nodes)[0]].size() == 0)) {
   529         return false;
   530       }
   531       for (int i = 0; i < int(_nodes->size()); ++i) {
   532         _dist[(*_nodes)[i]] = INF;
   533       }
   534       Node u, v;
   535       Arc e;
   536       for (int i = 0; i < int(_nodes->size()); ++i) {
   537         v = (*_nodes)[i];
   538         for (int j = 0; j < int(_in_arcs[v].size()); ++j) {
   539           e = _in_arcs[v][j];
   540           u = _gr.source(e);
   541           if (_cost[e] < _dist[u]) {
   542             _dist[u] = _cost[e];
   543             _policy[u] = e;
   544           }
   545         }
   546       }
   547       return true;
   548     }
   549 
   550     // Find the minimum mean cycle in the policy graph
   551     void findPolicyCycle() {
   552       for (int i = 0; i < int(_nodes->size()); ++i) {
   553         _level[(*_nodes)[i]] = -1;
   554       }
   555       LargeCost ccost;
   556       int csize;
   557       Node u, v;
   558       _curr_found = false;
   559       for (int i = 0; i < int(_nodes->size()); ++i) {
   560         u = (*_nodes)[i];
   561         if (_level[u] >= 0) continue;
   562         for (; _level[u] < 0; u = _gr.target(_policy[u])) {
   563           _level[u] = i;
   564         }
   565         if (_level[u] == i) {
   566           // A cycle is found
   567           ccost = _cost[_policy[u]];
   568           csize = 1;
   569           for (v = u; (v = _gr.target(_policy[v])) != u; ) {
   570             ccost += _cost[_policy[v]];
   571             ++csize;
   572           }
   573           if ( !_curr_found ||
   574                (ccost * _curr_size < _curr_cost * csize) ) {
   575             _curr_found = true;
   576             _curr_cost = ccost;
   577             _curr_size = csize;
   578             _curr_node = u;
   579           }
   580         }
   581       }
   582     }
   583 
   584     // Contract the policy graph and compute node distances
   585     bool computeNodeDistances() {
   586       // Find the component of the main cycle and compute node distances
   587       // using reverse BFS
   588       for (int i = 0; i < int(_nodes->size()); ++i) {
   589         _reached[(*_nodes)[i]] = false;
   590       }
   591       _qfront = _qback = 0;
   592       _queue[0] = _curr_node;
   593       _reached[_curr_node] = true;
   594       _dist[_curr_node] = 0;
   595       Node u, v;
   596       Arc e;
   597       while (_qfront <= _qback) {
   598         v = _queue[_qfront++];
   599         for (int j = 0; j < int(_in_arcs[v].size()); ++j) {
   600           e = _in_arcs[v][j];
   601           u = _gr.source(e);
   602           if (_policy[u] == e && !_reached[u]) {
   603             _reached[u] = true;
   604             _dist[u] = _dist[v] + _cost[e] * _curr_size - _curr_cost;
   605             _queue[++_qback] = u;
   606           }
   607         }
   608       }
   609 
   610       // Connect all other nodes to this component and compute node
   611       // distances using reverse BFS
   612       _qfront = 0;
   613       while (_qback < int(_nodes->size())-1) {
   614         v = _queue[_qfront++];
   615         for (int j = 0; j < int(_in_arcs[v].size()); ++j) {
   616           e = _in_arcs[v][j];
   617           u = _gr.source(e);
   618           if (!_reached[u]) {
   619             _reached[u] = true;
   620             _policy[u] = e;
   621             _dist[u] = _dist[v] + _cost[e] * _curr_size - _curr_cost;
   622             _queue[++_qback] = u;
   623           }
   624         }
   625       }
   626 
   627       // Improve node distances
   628       bool improved = false;
   629       for (int i = 0; i < int(_nodes->size()); ++i) {
   630         v = (*_nodes)[i];
   631         for (int j = 0; j < int(_in_arcs[v].size()); ++j) {
   632           e = _in_arcs[v][j];
   633           u = _gr.source(e);
   634           LargeCost delta = _dist[v] + _cost[e] * _curr_size - _curr_cost;
   635           if (_tolerance.less(delta, _dist[u])) {
   636             _dist[u] = delta;
   637             _policy[u] = e;
   638             improved = true;
   639           }
   640         }
   641       }
   642       return improved;
   643     }
   644 
   645   }; //class HowardMmc
   646 
   647   ///@}
   648 
   649 } //namespace lemon
   650 
   651 #endif //LEMON_HOWARD_MMC_H