RhodeCode

///\ingroup matching

///\file

///\brief Maximum matching algorithms in general graphs.

namespace lemon {

  /// \ingroup matching

  ///

  /// \brief Maximum cardinality matching in general graphs

  ///

  /// This class implements Edmonds' alternating forest matching algorithm

  /// It can be started from an arbitrary initial matching 

  /// (the default is the empty one).

  ///

  /// The dual solution of the problem is a map of the nodes to

  /// \ref MaxMatching::Status "Status", having values \c EVEN (or \c D),

  /// \c ODD (or \c A) and \c MATCHED (or \c C) defining the Gallai-Edmonds

  /// decomposition of the graph. The nodes in \c EVEN/D induce a subgraph

  /// with factor-critical components, the nodes in \c ODD/A form the

  /// canonical barrier, and the nodes in \c MATCHED/C induce a graph having

  /// a perfect matching. The number of the factor-critical components

  /// minus the number of barrier nodes is a lower bound on the

  /// unmatched nodes, and the matching is optimal if and only if this bound is

  ///

  template <typename GR>

  class MaxMatching {

  public:

    /// The graph type of the algorithm

    typedef GR Graph;

    typedef typename Graph::template NodeMap<typename Graph::Arc>

    MatchingMap;

    ///\brief Status constants for Gallai-Edmonds decomposition.

    ///

    ///These constants are used for indicating the Gallai-Edmonds 

    ///decomposition of a graph. The nodes with status \c EVEN (or \c D)

    ///induce a subgraph with factor-critical components, the nodes with

    ///status \c ODD (or \c A) form the canonical barrier, and the nodes

    ///with status \c MATCHED (or \c C) induce a subgraph having a 

    ///perfect matching.

    enum Status {

      EVEN = 1,       ///< = 1. (\c D is an alias for \c EVEN.)

      D = 1,

      MATCHED = 0,    ///< = 0. (\c C is an alias for \c MATCHED.)

      C = 0,

      ODD = -1,       ///< = -1. (\c A is an alias for \c ODD.)

      A = -1,

      UNMATCHED = -2  ///< = -2.

    };

    typedef typename Graph::template NodeMap<Status> StatusMap;

  private:

    TEMPLATE_GRAPH_TYPEDEFS(Graph);

    typedef UnionFindEnum<IntNodeMap> BlossomSet;

    typedef ExtendFindEnum<IntNodeMap> TreeSet;

    typedef RangeMap<Node> NodeIntMap;

    typedef MatchingMap EarMap;

    typedef std::vector<Node> NodeQueue;

      return edge == (*_matching)[_graph.u(edge)];

    }

    /// \brief Return the matching arc (or edge) incident to the given node.

    ///

    /// This function returns the matching arc (or edge) incident to the

    /// given node in the current matching or \c INVALID if the node is 

    /// not covered by the matching.

    Arc matching(const Node& n) const {

      return (*_matching)[n];

    }

    /// \brief Return the mate of the given node.

    ///

    /// This function returns the mate of the given node in the current 

    /// matching or \c INVALID if the node is not covered by the matching.

    Node mate(const Node& n) const {

      return (*_matching)[n] != INVALID ?

        _graph.target((*_matching)[n]) : INVALID;

    }

    /// @}

    /// \name Dual Solution

    /// Functions to get the dual solution, i.e. the Gallai-Edmonds 

    /// decomposition.

    /// @{

    /// \brief Return the status of the given node in the Edmonds-Gallai

    /// decomposition.

    ///

    /// This function returns the \ref Status "status" of the given node

    /// in the Edmonds-Gallai decomposition.

      return (*_status)[n];

    }

    /// \brief Return \c true if the given node is in the barrier.

    ///

    /// This function returns \c true if the given node is in the barrier.

    bool barrier(const Node& n) const {

      return (*_status)[n] == ODD;

    }

    /// @}

  };

  /// \ingroup matching

  /// \f[z_B \ge 0 \quad \forall B \in \mathcal{O}\f]

  /** \f[\min \sum_{u \in V}y_u + \sum_{B \in \mathcal{O}}

      \frac{\vert B \vert - 1}{2}z_B\f] */

  ///

  /// The algorithm can be executed with the run() function. 

  /// After it the matching (the primal solution) and the dual solution

  /// can be obtained using the query functions and the 

  /// \ref MaxWeightedMatching::BlossomIt "BlossomIt" nested class, 

  /// which is able to iterate on the nodes of a blossom. 

  /// If the value type is integer, then the dual solution is multiplied

  /// by \ref MaxWeightedMatching::dualScale "4".

  ///

  /// \tparam WM The type edge weight map. The default type is 

  /// \ref concepts::Graph::EdgeMap "GR::EdgeMap<int>".

#ifdef DOXYGEN

  template <typename GR, typename WM>

#else

  template <typename GR,

            typename WM = typename GR::template EdgeMap<int> >

#endif

  class MaxWeightedMatching {

  public:

    /// The graph type of the algorithm

    typedef GR Graph;

    /// The type of the edge weight map

    typedef WM WeightMap;

    /// The value type of the edge weights

    typedef typename WeightMap::Value Value;

    typedef typename Graph::template NodeMap<typename Graph::Arc>

    MatchingMap;

    /// \brief Scaling factor for dual solution

    ///

    /// Scaling factor for dual solution. It is equal to 4 or 1

    /// according to the value type.

    static const int dualScale =

      std::numeric_limits<Value>::is_integer ? 4 : 1;

  private:

    /// Functions to get the primal solution, i.e. the maximum weighted 

    /// matching.\n

    /// Either \ref run() or \ref start() function should be called before

    /// using them.

    /// @{

    /// \brief Return the weight of the matching.

    ///

    /// This function returns the weight of the found matching.

    ///

    /// \pre Either run() or start() must be called before using this function.

      Value sum = 0;

      for (NodeIt n(_graph); n != INVALID; ++n) {

        if ((*_matching)[n] != INVALID) {

          sum += _weight[(*_matching)[n]];

        }

      }

      return sum /= 2;

    }

    /// \brief Return the size (cardinality) of the matching.

    ///

    /// This function returns the size (cardinality) of the found matching.

    /// \brief Return the matching arc (or edge) incident to the given node.

    ///

    /// This function returns the matching arc (or edge) incident to the

    /// given node in the found matching or \c INVALID if the node is 

    /// not covered by the matching.

    ///

    /// \pre Either run() or start() must be called before using this function.

    Arc matching(const Node& node) const {

      return (*_matching)[node];

    }

    /// \brief Return the mate of the given node.

    ///

    /// This function returns the mate of the given node in the found 

    /// matching or \c INVALID if the node is not covered by the matching.

    ///

    /// \pre Either run() or start() must be called before using this function.

    Node mate(const Node& node) const {

      return (*_matching)[node] != INVALID ?

        _graph.target((*_matching)[node]) : INVALID;

    }

    /// @}

  /// \f[z_B \ge 0 \quad \forall B \in \mathcal{O}\f]

  /** \f[\min \sum_{u \in V}y_u + \sum_{B \in \mathcal{O}}

      \frac{\vert B \vert - 1}{2}z_B\f] */

  ///

  /// The algorithm can be executed with the run() function. 

  /// After it the matching (the primal solution) and the dual solution

  /// can be obtained using the query functions and the 

  /// \ref MaxWeightedPerfectMatching::BlossomIt "BlossomIt" nested class, 

  /// which is able to iterate on the nodes of a blossom. 

  /// If the value type is integer, then the dual solution is multiplied

  /// by \ref MaxWeightedMatching::dualScale "4".

  ///

  /// \tparam WM The type edge weight map. The default type is 

  /// \ref concepts::Graph::EdgeMap "GR::EdgeMap<int>".

#ifdef DOXYGEN

  template <typename GR, typename WM>

#else

  template <typename GR,

            typename WM = typename GR::template EdgeMap<int> >

#endif

  class MaxWeightedPerfectMatching {

  public:

    /// The graph type of the algorithm

    /// The type of the edge weight map

    typedef WM WeightMap;

    /// The value type of the edge weights

    typedef typename WeightMap::Value Value;

    /// \brief Scaling factor for dual solution

    ///

    /// Scaling factor for dual solution, it is equal to 4 or 1

    /// according to the value type.

    static const int dualScale =

      std::numeric_limits<Value>::is_integer ? 4 : 1;

    typedef typename Graph::template NodeMap<typename Graph::Arc>

    MatchingMap;

  private:

    TEMPLATE_GRAPH_TYPEDEFS(Graph);

    typedef typename Graph::template NodeMap<Value> NodePotential;

    typedef std::vector<Node> BlossomNodeList;

    struct BlossomVariable {

      int begin, end;

    /// Functions to get the primal solution, i.e. the maximum weighted 

    /// perfect matching.\n

    /// Either \ref run() or \ref start() function should be called before

    /// using them.

    /// @{

    /// \brief Return the weight of the matching.

    ///

    /// This function returns the weight of the found matching.

    ///

    /// \pre Either run() or start() must be called before using this function.

      Value sum = 0;

      for (NodeIt n(_graph); n != INVALID; ++n) {

        if ((*_matching)[n] != INVALID) {

          sum += _weight[(*_matching)[n]];

        }

      }

      return sum /= 2;

    }

    /// \brief Return \c true if the given edge is in the matching.

    ///

    /// This function returns \c true if the given edge is in the found 

    /// \brief Return the matching arc (or edge) incident to the given node.

    ///

    /// This function returns the matching arc (or edge) incident to the

    /// given node in the found matching or \c INVALID if the node is 

    /// not covered by the matching.

    ///

    /// \pre Either run() or start() must be called before using this function.

    Arc matching(const Node& node) const {

      return (*_matching)[node];

    }

    /// \brief Return the mate of the given node.

    ///

    /// This function returns the mate of the given node in the found 

    /// matching or \c INVALID if the node is not covered by the matching.

    ///

    /// \pre Either run() or start() must be called before using this function.

    Node mate(const Node& node) const {

      return _graph.target((*_matching)[node]);

    }

    /// @}

    const_mat_test = mat_test;

  mat_test.init();

  mat_test.greedyInit();

  mat_test.matchingInit(mat);

  mat_test.startSparse();

  mat_test.startDense();

  mat_test.run();

  const_mat_test.matchingSize();

  const_mat_test.matching(e);

  const_mat_test.matching(n);

  const_mat_test.mate(n);

  MaxMatching<Graph>::Status stat = 

  const_mat_test.barrier(n);

}

void checkMaxWeightedMatchingCompile()

{

  typedef concepts::Graph Graph;

  typedef Graph::Node Node;

  typedef Graph::Edge Edge;

  typedef Graph::EdgeMap<int> WeightMap;

  Graph g;

  Node n;

  Edge e;

  WeightMap w(g);

  MaxWeightedMatching<Graph> mat_test(g, w);

  const MaxWeightedMatching<Graph>&

    const_mat_test = mat_test;

  mat_test.init();

  mat_test.start();

  mat_test.run();

  const_mat_test.matchingSize();

  const_mat_test.matching(e);

  const_mat_test.matching(n);

  const_mat_test.mate(n);

  int k = 0;

  const_mat_test.dualValue();

  const_mat_test.nodeValue(n);

  const_mat_test.blossomNum();

  const_mat_test.blossomSize(k);

  const_mat_test.blossomValue(k);

}

void checkMaxWeightedPerfectMatchingCompile()

{

  Node n;

  Edge e;

  WeightMap w(g);

  MaxWeightedPerfectMatching<Graph> mat_test(g, w);

  const MaxWeightedPerfectMatching<Graph>&

    const_mat_test = mat_test;

  mat_test.init();

  mat_test.start();

  mat_test.run();

  const_mat_test.matching(e);

  const_mat_test.matching(n);

  const_mat_test.mate(n);

  int k = 0;

  const_mat_test.dualValue();

  const_mat_test.nodeValue(n);

  const_mat_test.blossomNum();

  const_mat_test.blossomSize(k);

  const_mat_test.blossomValue(k);

}

void checkMatching(const SmartGraph& graph,

                   const MaxMatching<SmartGraph>& mm) {

  int num = 0;

  IntNodeMap comp_index(graph);

  UnionFind<IntNodeMap> comp(comp_index);

  int barrier_num = 0;

  for (NodeIt n(graph); n != INVALID; ++n) {

          mm.matching(n) != INVALID, "Wrong Gallai-Edmonds decomposition");

      ++barrier_num;

    } else {

      comp.insert(n);

    }

  }

  for (EdgeIt e(graph); e != INVALID; ++e) {

    if (mm.matching(e)) {

      check(e == mm.matching(graph.u(e)), "Wrong matching");

      check(e == mm.matching(graph.v(e)), "Wrong matching");

      ++num;

    }

          "Wrong Gallai-Edmonds decomposition");

          "Wrong Gallai-Edmonds decomposition");

      comp.join(graph.u(e), graph.v(e));

    }

  }

  std::set<int> comp_root;

  int odd_comp_num = 0;

  for (NodeIt n(graph); n != INVALID; ++n) {

      int root = comp.find(n);

      if (comp_root.find(root) == comp_root.end()) {

        comp_root.insert(root);

        if (comp.size(n) % 2 == 1) {

          ++odd_comp_num;

        }

      }

    }

  }

  check(mm.matchingSize() == num, "Wrong matching");

  check(2 * num == countNodes(graph) - (odd_comp_num - barrier_num),