lemon/howard.h
author Balazs Dezso <deba@inf.elte.hu>
Sun, 14 Feb 2010 23:14:09 +0100
changeset 833 d2bc45e8f6f2
parent 771 8452ca46e29a
child 841 aa8c9008b3de
permissions -rw-r--r--
Merge bugfix #337
     1 /* -*- C++ -*-
     2  *
     3  * This file is a part of LEMON, a generic C++ optimization library
     4  *
     5  * Copyright (C) 2003-2008
     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_H
    20 #define LEMON_HOWARD_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 Howard class.
    37   ///
    38   /// Default traits class of Howard class.
    39   /// \tparam GR The type of the digraph.
    40   /// \tparam LEN The type of the length map.
    41   /// It must conform to the \ref concepts::ReadMap "ReadMap" concept.
    42 #ifdef DOXYGEN
    43   template <typename GR, typename LEN>
    44 #else
    45   template <typename GR, typename LEN,
    46     bool integer = std::numeric_limits<typename LEN::Value>::is_integer>
    47 #endif
    48   struct HowardDefaultTraits
    49   {
    50     /// The type of the digraph
    51     typedef GR Digraph;
    52     /// The type of the length map
    53     typedef LEN LengthMap;
    54     /// The type of the arc lengths
    55     typedef typename LengthMap::Value Value;
    56 
    57     /// \brief The large value type used for internal computations
    58     ///
    59     /// The large value type used for internal computations.
    60     /// It is \c long \c long if the \c Value type is integer,
    61     /// otherwise it is \c double.
    62     /// \c Value must be convertible to \c LargeValue.
    63     typedef double LargeValue;
    64 
    65     /// The tolerance type used for internal computations
    66     typedef lemon::Tolerance<LargeValue> 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 value types
    77   template <typename GR, typename LEN>
    78   struct HowardDefaultTraits<GR, LEN, true>
    79   {
    80     typedef GR Digraph;
    81     typedef LEN LengthMap;
    82     typedef typename LengthMap::Value Value;
    83 #ifdef LEMON_HAVE_LONG_LONG
    84     typedef long long LargeValue;
    85 #else
    86     typedef long LargeValue;
    87 #endif
    88     typedef lemon::Tolerance<LargeValue> 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 length (cost) in a digraph
   101   /// \ref amo93networkflows, \ref dasdan98minmeancycle.
   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 LEN The type of the length 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 HowardDefaultTraits
   111   /// "HowardDefaultTraits<GR, LEN>".
   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 LEN, typename TR>
   116 #else
   117   template < typename GR,
   118              typename LEN = typename GR::template ArcMap<int>,
   119              typename TR = HowardDefaultTraits<GR, LEN> >
   120 #endif
   121   class Howard
   122   {
   123   public:
   124   
   125     /// The type of the digraph
   126     typedef typename TR::Digraph Digraph;
   127     /// The type of the length map
   128     typedef typename TR::LengthMap LengthMap;
   129     /// The type of the arc lengths
   130     typedef typename TR::Value Value;
   131 
   132     /// \brief The large value type
   133     ///
   134     /// The large value type used for internal computations.
   135     /// By default, it is \c long \c long if the \c Value type is integer,
   136     /// otherwise it is \c double.
   137     typedef typename TR::LargeValue LargeValue;
   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 HowardDefaultTraits "default traits class",
   146     /// it is \ref lemon::Path "Path<Digraph>".
   147     typedef typename TR::Path Path;
   148 
   149     /// The \ref HowardDefaultTraits "traits class" of the algorithm
   150     typedef TR Traits;
   151 
   152   private:
   153 
   154     TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
   155   
   156     // The digraph the algorithm runs on
   157     const Digraph &_gr;
   158     // The length of the arcs
   159     const LengthMap &_length;
   160 
   161     // Data for the found cycles
   162     bool _curr_found, _best_found;
   163     LargeValue _curr_length, _best_length;
   164     int _curr_size, _best_size;
   165     Node _curr_node, _best_node;
   166 
   167     Path *_cycle_path;
   168     bool _local_path;
   169 
   170     // Internal data used by the algorithm
   171     typename Digraph::template NodeMap<Arc> _policy;
   172     typename Digraph::template NodeMap<bool> _reached;
   173     typename Digraph::template NodeMap<int> _level;
   174     typename Digraph::template NodeMap<LargeValue> _dist;
   175 
   176     // Data for storing the strongly connected components
   177     int _comp_num;
   178     typename Digraph::template NodeMap<int> _comp;
   179     std::vector<std::vector<Node> > _comp_nodes;
   180     std::vector<Node>* _nodes;
   181     typename Digraph::template NodeMap<std::vector<Arc> > _in_arcs;
   182     
   183     // Queue used for BFS search
   184     std::vector<Node> _queue;
   185     int _qfront, _qback;
   186 
   187     Tolerance _tolerance;
   188   
   189     // Infinite constant
   190     const LargeValue INF;
   191 
   192   public:
   193   
   194     /// \name Named Template Parameters
   195     /// @{
   196 
   197     template <typename T>
   198     struct SetLargeValueTraits : public Traits {
   199       typedef T LargeValue;
   200       typedef lemon::Tolerance<T> Tolerance;
   201     };
   202 
   203     /// \brief \ref named-templ-param "Named parameter" for setting
   204     /// \c LargeValue type.
   205     ///
   206     /// \ref named-templ-param "Named parameter" for setting \c LargeValue
   207     /// type. It is used for internal computations in the algorithm.
   208     template <typename T>
   209     struct SetLargeValue
   210       : public Howard<GR, LEN, SetLargeValueTraits<T> > {
   211       typedef Howard<GR, LEN, SetLargeValueTraits<T> > Create;
   212     };
   213 
   214     template <typename T>
   215     struct SetPathTraits : public Traits {
   216       typedef T Path;
   217     };
   218 
   219     /// \brief \ref named-templ-param "Named parameter" for setting
   220     /// \c %Path type.
   221     ///
   222     /// \ref named-templ-param "Named parameter" for setting the \c %Path
   223     /// type of the found cycles.
   224     /// It must conform to the \ref lemon::concepts::Path "Path" concept
   225     /// and it must have an \c addBack() function.
   226     template <typename T>
   227     struct SetPath
   228       : public Howard<GR, LEN, SetPathTraits<T> > {
   229       typedef Howard<GR, LEN, SetPathTraits<T> > Create;
   230     };
   231     
   232     /// @}
   233 
   234   public:
   235 
   236     /// \brief Constructor.
   237     ///
   238     /// The constructor of the class.
   239     ///
   240     /// \param digraph The digraph the algorithm runs on.
   241     /// \param length The lengths (costs) of the arcs.
   242     Howard( const Digraph &digraph,
   243             const LengthMap &length ) :
   244       _gr(digraph), _length(length), _best_found(false),
   245       _best_length(0), _best_size(1), _cycle_path(NULL), _local_path(false),
   246       _policy(digraph), _reached(digraph), _level(digraph), _dist(digraph),
   247       _comp(digraph), _in_arcs(digraph),
   248       INF(std::numeric_limits<LargeValue>::has_infinity ?
   249           std::numeric_limits<LargeValue>::infinity() :
   250           std::numeric_limits<LargeValue>::max())
   251     {}
   252 
   253     /// Destructor.
   254     ~Howard() {
   255       if (_local_path) delete _cycle_path;
   256     }
   257 
   258     /// \brief Set the path structure for storing the found cycle.
   259     ///
   260     /// This function sets an external path structure for storing the
   261     /// found cycle.
   262     ///
   263     /// If you don't call this function before calling \ref run() or
   264     /// \ref findMinMean(), it will allocate a local \ref Path "path"
   265     /// structure. The destuctor deallocates this automatically
   266     /// allocated object, of course.
   267     ///
   268     /// \note The algorithm calls only the \ref lemon::Path::addBack()
   269     /// "addBack()" function of the given path structure.
   270     ///
   271     /// \return <tt>(*this)</tt>
   272     Howard& cycle(Path &path) {
   273       if (_local_path) {
   274         delete _cycle_path;
   275         _local_path = false;
   276       }
   277       _cycle_path = &path;
   278       return *this;
   279     }
   280 
   281     /// \brief Set the tolerance used by the algorithm.
   282     ///
   283     /// This function sets the tolerance object used by the algorithm.
   284     ///
   285     /// \return <tt>(*this)</tt>
   286     Howard& tolerance(const Tolerance& tolerance) {
   287       _tolerance = tolerance;
   288       return *this;
   289     }
   290 
   291     /// \brief Return a const reference to the tolerance.
   292     ///
   293     /// This function returns a const reference to the tolerance object
   294     /// used by the algorithm.
   295     const Tolerance& tolerance() const {
   296       return _tolerance;
   297     }
   298 
   299     /// \name Execution control
   300     /// The simplest way to execute the algorithm is to call the \ref run()
   301     /// function.\n
   302     /// If you only need the minimum mean length, you may call
   303     /// \ref findMinMean().
   304 
   305     /// @{
   306 
   307     /// \brief Run the algorithm.
   308     ///
   309     /// This function runs the algorithm.
   310     /// It can be called more than once (e.g. if the underlying digraph
   311     /// and/or the arc lengths have been modified).
   312     ///
   313     /// \return \c true if a directed cycle exists in the digraph.
   314     ///
   315     /// \note <tt>mmc.run()</tt> is just a shortcut of the following code.
   316     /// \code
   317     ///   return mmc.findMinMean() && mmc.findCycle();
   318     /// \endcode
   319     bool run() {
   320       return findMinMean() && findCycle();
   321     }
   322 
   323     /// \brief Find the minimum cycle mean.
   324     ///
   325     /// This function finds the minimum mean length of the directed
   326     /// cycles in the digraph.
   327     ///
   328     /// \return \c true if a directed cycle exists in the digraph.
   329     bool findMinMean() {
   330       // Initialize and find strongly connected components
   331       init();
   332       findComponents();
   333       
   334       // Find the minimum cycle mean in the components
   335       for (int comp = 0; comp < _comp_num; ++comp) {
   336         // Find the minimum mean cycle in the current component
   337         if (!buildPolicyGraph(comp)) continue;
   338         while (true) {
   339           findPolicyCycle();
   340           if (!computeNodeDistances()) break;
   341         }
   342         // Update the best cycle (global minimum mean cycle)
   343         if ( _curr_found && (!_best_found ||
   344              _curr_length * _best_size < _best_length * _curr_size) ) {
   345           _best_found = true;
   346           _best_length = _curr_length;
   347           _best_size = _curr_size;
   348           _best_node = _curr_node;
   349         }
   350       }
   351       return _best_found;
   352     }
   353 
   354     /// \brief Find a minimum mean directed cycle.
   355     ///
   356     /// This function finds a directed cycle of minimum mean length
   357     /// in the digraph using the data computed by findMinMean().
   358     ///
   359     /// \return \c true if a directed cycle exists in the digraph.
   360     ///
   361     /// \pre \ref findMinMean() must be called before using this function.
   362     bool findCycle() {
   363       if (!_best_found) return false;
   364       _cycle_path->addBack(_policy[_best_node]);
   365       for ( Node v = _best_node;
   366             (v = _gr.target(_policy[v])) != _best_node; ) {
   367         _cycle_path->addBack(_policy[v]);
   368       }
   369       return true;
   370     }
   371 
   372     /// @}
   373 
   374     /// \name Query Functions
   375     /// The results of the algorithm can be obtained using these
   376     /// functions.\n
   377     /// The algorithm should be executed before using them.
   378 
   379     /// @{
   380 
   381     /// \brief Return the total length of the found cycle.
   382     ///
   383     /// This function returns the total length of the found cycle.
   384     ///
   385     /// \pre \ref run() or \ref findMinMean() must be called before
   386     /// using this function.
   387     LargeValue cycleLength() const {
   388       return _best_length;
   389     }
   390 
   391     /// \brief Return the number of arcs on the found cycle.
   392     ///
   393     /// This function returns the number of arcs on the found cycle.
   394     ///
   395     /// \pre \ref run() or \ref findMinMean() must be called before
   396     /// using this function.
   397     int cycleArcNum() const {
   398       return _best_size;
   399     }
   400 
   401     /// \brief Return the mean length of the found cycle.
   402     ///
   403     /// This function returns the mean length of the found cycle.
   404     ///
   405     /// \note <tt>alg.cycleMean()</tt> is just a shortcut of the
   406     /// following code.
   407     /// \code
   408     ///   return static_cast<double>(alg.cycleLength()) / alg.cycleArcNum();
   409     /// \endcode
   410     ///
   411     /// \pre \ref run() or \ref findMinMean() must be called before
   412     /// using this function.
   413     double cycleMean() const {
   414       return static_cast<double>(_best_length) / _best_size;
   415     }
   416 
   417     /// \brief Return the found cycle.
   418     ///
   419     /// This function returns a const reference to the path structure
   420     /// storing the found cycle.
   421     ///
   422     /// \pre \ref run() or \ref findCycle() must be called before using
   423     /// this function.
   424     const Path& cycle() const {
   425       return *_cycle_path;
   426     }
   427 
   428     ///@}
   429 
   430   private:
   431 
   432     // Initialize
   433     void init() {
   434       if (!_cycle_path) {
   435         _local_path = true;
   436         _cycle_path = new Path;
   437       }
   438       _queue.resize(countNodes(_gr));
   439       _best_found = false;
   440       _best_length = 0;
   441       _best_size = 1;
   442       _cycle_path->clear();
   443     }
   444     
   445     // Find strongly connected components and initialize _comp_nodes
   446     // and _in_arcs
   447     void findComponents() {
   448       _comp_num = stronglyConnectedComponents(_gr, _comp);
   449       _comp_nodes.resize(_comp_num);
   450       if (_comp_num == 1) {
   451         _comp_nodes[0].clear();
   452         for (NodeIt n(_gr); n != INVALID; ++n) {
   453           _comp_nodes[0].push_back(n);
   454           _in_arcs[n].clear();
   455           for (InArcIt a(_gr, n); a != INVALID; ++a) {
   456             _in_arcs[n].push_back(a);
   457           }
   458         }
   459       } else {
   460         for (int i = 0; i < _comp_num; ++i)
   461           _comp_nodes[i].clear();
   462         for (NodeIt n(_gr); n != INVALID; ++n) {
   463           int k = _comp[n];
   464           _comp_nodes[k].push_back(n);
   465           _in_arcs[n].clear();
   466           for (InArcIt a(_gr, n); a != INVALID; ++a) {
   467             if (_comp[_gr.source(a)] == k) _in_arcs[n].push_back(a);
   468           }
   469         }
   470       }
   471     }
   472 
   473     // Build the policy graph in the given strongly connected component
   474     // (the out-degree of every node is 1)
   475     bool buildPolicyGraph(int comp) {
   476       _nodes = &(_comp_nodes[comp]);
   477       if (_nodes->size() < 1 ||
   478           (_nodes->size() == 1 && _in_arcs[(*_nodes)[0]].size() == 0)) {
   479         return false;
   480       }
   481       for (int i = 0; i < int(_nodes->size()); ++i) {
   482         _dist[(*_nodes)[i]] = INF;
   483       }
   484       Node u, v;
   485       Arc e;
   486       for (int i = 0; i < int(_nodes->size()); ++i) {
   487         v = (*_nodes)[i];
   488         for (int j = 0; j < int(_in_arcs[v].size()); ++j) {
   489           e = _in_arcs[v][j];
   490           u = _gr.source(e);
   491           if (_length[e] < _dist[u]) {
   492             _dist[u] = _length[e];
   493             _policy[u] = e;
   494           }
   495         }
   496       }
   497       return true;
   498     }
   499 
   500     // Find the minimum mean cycle in the policy graph
   501     void findPolicyCycle() {
   502       for (int i = 0; i < int(_nodes->size()); ++i) {
   503         _level[(*_nodes)[i]] = -1;
   504       }
   505       LargeValue clength;
   506       int csize;
   507       Node u, v;
   508       _curr_found = false;
   509       for (int i = 0; i < int(_nodes->size()); ++i) {
   510         u = (*_nodes)[i];
   511         if (_level[u] >= 0) continue;
   512         for (; _level[u] < 0; u = _gr.target(_policy[u])) {
   513           _level[u] = i;
   514         }
   515         if (_level[u] == i) {
   516           // A cycle is found
   517           clength = _length[_policy[u]];
   518           csize = 1;
   519           for (v = u; (v = _gr.target(_policy[v])) != u; ) {
   520             clength += _length[_policy[v]];
   521             ++csize;
   522           }
   523           if ( !_curr_found ||
   524                (clength * _curr_size < _curr_length * csize) ) {
   525             _curr_found = true;
   526             _curr_length = clength;
   527             _curr_size = csize;
   528             _curr_node = u;
   529           }
   530         }
   531       }
   532     }
   533 
   534     // Contract the policy graph and compute node distances
   535     bool computeNodeDistances() {
   536       // Find the component of the main cycle and compute node distances
   537       // using reverse BFS
   538       for (int i = 0; i < int(_nodes->size()); ++i) {
   539         _reached[(*_nodes)[i]] = false;
   540       }
   541       _qfront = _qback = 0;
   542       _queue[0] = _curr_node;
   543       _reached[_curr_node] = true;
   544       _dist[_curr_node] = 0;
   545       Node u, v;
   546       Arc e;
   547       while (_qfront <= _qback) {
   548         v = _queue[_qfront++];
   549         for (int j = 0; j < int(_in_arcs[v].size()); ++j) {
   550           e = _in_arcs[v][j];
   551           u = _gr.source(e);
   552           if (_policy[u] == e && !_reached[u]) {
   553             _reached[u] = true;
   554             _dist[u] = _dist[v] + _length[e] * _curr_size - _curr_length;
   555             _queue[++_qback] = u;
   556           }
   557         }
   558       }
   559 
   560       // Connect all other nodes to this component and compute node
   561       // distances using reverse BFS
   562       _qfront = 0;
   563       while (_qback < int(_nodes->size())-1) {
   564         v = _queue[_qfront++];
   565         for (int j = 0; j < int(_in_arcs[v].size()); ++j) {
   566           e = _in_arcs[v][j];
   567           u = _gr.source(e);
   568           if (!_reached[u]) {
   569             _reached[u] = true;
   570             _policy[u] = e;
   571             _dist[u] = _dist[v] + _length[e] * _curr_size - _curr_length;
   572             _queue[++_qback] = u;
   573           }
   574         }
   575       }
   576 
   577       // Improve node distances
   578       bool improved = false;
   579       for (int i = 0; i < int(_nodes->size()); ++i) {
   580         v = (*_nodes)[i];
   581         for (int j = 0; j < int(_in_arcs[v].size()); ++j) {
   582           e = _in_arcs[v][j];
   583           u = _gr.source(e);
   584           LargeValue delta = _dist[v] + _length[e] * _curr_size - _curr_length;
   585           if (_tolerance.less(delta, _dist[u])) {
   586             _dist[u] = delta;
   587             _policy[u] = e;
   588             improved = true;
   589           }
   590         }
   591       }
   592       return improved;
   593     }
   594 
   595   }; //class Howard
   596 
   597   ///@}
   598 
   599 } //namespace lemon
   600 
   601 #endif //LEMON_HOWARD_H