/* -*- C++ -*-

 *

 * This file is a part of LEMON, a generic C++ optimization library

 *

 * Copyright (C) 2003-2006

 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport

 * (Egervary Research Group on Combinatorial Optimization, EGRES).

 *

 * Permission to use, modify and distribute this software is granted

 * provided that this copyright notice appears in all copies. For

 * precise terms see the accompanying LICENSE file.

 *

 * This software is provided "AS IS" with no warranty of any kind,

 * express or implied, and with no claim as to its suitability for any

 * purpose.

 *

 */

#ifndef LEMON_MAX_MATCHING_H

#define LEMON_MAX_MATCHING_H

#include <queue>

#include <lemon/bits/invalid.h>

#include <lemon/unionfind.h>

#include <lemon/graph_utils.h>

///\ingroup galgs

///\file

///\brief Maximum matching algorithm.

namespace lemon {

  /// \addtogroup galgs

  /// @{

  ///Edmonds' alternating forest maximum matching algorithm.

  ///This class provides Edmonds' alternating forest matching

  ///algorithm. The starting matching (if any) can be passed to the

  ///algorithm using read-in functions \ref readNMapNode, \ref

  ///readNMapEdge or \ref readEMapBool depending on the container. The

  ///resulting maximum matching can be attained by write-out functions

  ///\ref writeNMapNode, \ref writeNMapEdge or \ref writeEMapBool

  ///depending on the preferred container. 

  ///

  ///The dual side of a matching is a map of the nodes to

  ///MaxMatching::pos_enum, having values D, A and C showing the

  ///Gallai-Edmonds decomposition of the graph. The nodes in D induce

  ///a graph with factor-critical components, the nodes in A form the

  ///barrier, and the nodes in C induce a graph having a perfect

  ///matching. This decomposition can be attained by calling \ref

  ///writePos after running the algorithm. 

  ///

  ///\param Graph The undirected graph type the algorithm runs on.

  ///

  ///\author Jacint Szabo  

  template <typename Graph>

  class MaxMatching {

  protected:

    typedef typename Graph::Node Node;

    typedef typename Graph::Edge Edge;

    typedef typename Graph::UEdge UEdge;

    typedef typename Graph::UEdgeIt UEdgeIt;

    typedef typename Graph::NodeIt NodeIt;

    typedef typename Graph::IncEdgeIt IncEdgeIt;

    typedef UnionFindEnum<Node, Graph::template NodeMap> UFE;

  public:

    ///Indicates the Gallai-Edmonds decomposition of the graph.

    ///Indicates the Gallai-Edmonds decomposition of the graph, which

    ///shows an upper bound on the size of a maximum matching. The

    ///nodes with pos_enum \c D induce a graph with factor-critical

    ///components, the nodes in \c A form the canonical barrier, and the

    ///nodes in \c C induce a graph having a perfect matching. 

    enum pos_enum {

      D=0,

      A=1,

      C=2

    }; 

  protected:

    static const int HEUR_density=2;

    const Graph& g;

    typename Graph::template NodeMap<Node> _mate;

    typename Graph::template NodeMap<pos_enum> position;

  public:

    MaxMatching(const Graph& _g) : g(_g), _mate(_g,INVALID), position(_g) {}

    ///Runs Edmonds' algorithm.

    ///Runs Edmonds' algorithm for sparse graphs (number of edges <

    ///2*number of nodes), and a heuristical Edmonds' algorithm with a

    ///heuristic of postponing shrinks for dense graphs. 

    void run() {

      if ( countUEdges(g) < HEUR_density*countNodes(g) ) {

	greedyMatching();

	runEdmonds(0);

      } else runEdmonds(1);

    }

    ///Runs Edmonds' algorithm.

    ///If heur=0 it runs Edmonds' algorithm. If heur=1 it runs

    ///Edmonds' algorithm with a heuristic of postponing shrinks,

    ///giving a faster algorithm for dense graphs.  

    void runEdmonds( int heur = 1 ) {

      //each vertex is put to C

      for(NodeIt v(g); v!=INVALID; ++v)

	position.set(v,C);      

      typename Graph::template NodeMap<Node> ear(g,INVALID); 

      //undefined for the base nodes of the blossoms (i.e. for the

      //representative elements of UFE blossom) and for the nodes in C 

      typename UFE::MapType blossom_base(g);

      UFE blossom(blossom_base);

      typename UFE::MapType tree_base(g);

      UFE tree(tree_base);

      //If these UFE's would be members of the class then also

      //blossom_base and tree_base should be a member.

      //We build only one tree and the other vertices uncovered by the

      //matching belong to C. (They can be considered as singleton

      //trees.) If this tree can be augmented or no more

      //grow/augmentation/shrink is possible then we return to this

      //"for" cycle.

      for(NodeIt v(g); v!=INVALID; ++v) {

	if ( position[v]==C && _mate[v]==INVALID ) {

	  blossom.insert(v);

	  tree.insert(v); 

	  position.set(v,D);

	  if ( heur == 1 ) lateShrink( v, ear, blossom, tree );

	  else normShrink( v, ear, blossom, tree );

	}

      }

    }

    ///Finds a greedy matching starting from the actual matching.

    ///Starting form the actual matching stored, it finds a maximal

    ///greedy matching.

    void greedyMatching() {

      for(NodeIt v(g); v!=INVALID; ++v)

	if ( _mate[v]==INVALID ) {

	  for( IncEdgeIt e(g,v); e!=INVALID ; ++e ) {

	    Node y=g.runningNode(e);

	    if ( _mate[y]==INVALID && y!=v ) {

	      _mate.set(v,y);

	      _mate.set(y,v);

	      break;

	    }

	  }

	} 

    }

    ///Returns the size of the actual matching stored.

    ///Returns the size of the actual matching stored. After \ref

    ///run() it returns the size of a maximum matching in the graph.

    int size() const {

      int s=0;

      for(NodeIt v(g); v!=INVALID; ++v) {

	if ( _mate[v]!=INVALID ) {

	  ++s;

	}

      }

      return s/2;

    }

    ///Resets the actual matching to the empty matching.

    ///Resets the actual matching to the empty matching.  

    ///

    void resetMatching() {

      for(NodeIt v(g); v!=INVALID; ++v)

	_mate.set(v,INVALID);      

    }

    ///Returns the mate of a node in the actual matching.

    ///Returns the mate of a \c node in the actual matching. 

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

    Node mate(Node& node) const {

      return _mate[node];

    } 

    ///Reads a matching from a \c Node valued \c Node map.

    ///Reads a matching from a \c Node valued \c Node map. This map

    ///must be \e symmetric, i.e. if \c map[u]==v then \c map[v]==u

    ///must hold, and \c uv will be an edge of the matching.

    template<typename NMapN>

    void readNMapNode(NMapN& map) {

      for(NodeIt v(g); v!=INVALID; ++v) {

	_mate.set(v,map[v]);   

      } 

    } 

    ///Writes the stored matching to a \c Node valued \c Node map.

    ///Writes the stored matching to a \c Node valued \c Node map. The

    ///resulting map will be \e symmetric, i.e. if \c map[u]==v then \c

    ///map[v]==u will hold, and now \c uv is an edge of the matching.

    template<typename NMapN>

    void writeNMapNode (NMapN& map) const {

      for(NodeIt v(g); v!=INVALID; ++v) {

	map.set(v,_mate[v]);   

      } 

    } 

    ///Reads a matching from an \c UEdge valued \c Node map.

    ///Reads a matching from an \c UEdge valued \c Node map. \c

    ///map[v] must be an \c UEdge incident to \c v. This map must

    ///have the property that if \c g.oppositeNode(u,map[u])==v then

    ///\c \c g.oppositeNode(v,map[v])==u holds, and now some edge

    ///joining \c u to \c v will be an edge of the matching.

    template<typename NMapE>

    void readNMapEdge(NMapE& map) {

      for(NodeIt v(g); v!=INVALID; ++v) {

	UEdge e=map[v];

	if ( e!=INVALID )

	  _mate.set(v,g.oppositeNode(v,e));

      } 

    } 

    ///Writes the matching stored to an \c UEdge valued \c Node map.

    ///Writes the stored matching to an \c UEdge valued \c Node

    ///map. \c map[v] will be an \c UEdge incident to \c v. This

    ///map will have the property that if \c g.oppositeNode(u,map[u])

    ///== v then \c map[u]==map[v] holds, and now this edge is an edge

    ///of the matching.

    template<typename NMapE>

    void writeNMapEdge (NMapE& map)  const {

      typename Graph::template NodeMap<bool> todo(g,true); 

      for(NodeIt v(g); v!=INVALID; ++v) {

	if ( todo[v] && _mate[v]!=INVALID ) {

	  Node u=_mate[v];

	  for(IncEdgeIt e(g,v); e!=INVALID; ++e) {

	    if ( g.runningNode(e) == u ) {

	      map.set(u,e);

	      map.set(v,e);

	      todo.set(u,false);

	      todo.set(v,false);

	      break;

	    }

	  }

	}

      } 

    }

    ///Reads a matching from a \c bool valued \c Edge map.

    ///Reads a matching from a \c bool valued \c Edge map. This map

    ///must have the property that there are no two incident edges \c

    ///e, \c f with \c map[e]==map[f]==true. The edges \c e with \c

    ///map[e]==true form the matching.

    template<typename EMapB>

    void readEMapBool(EMapB& map) {

      for(UEdgeIt e(g); e!=INVALID; ++e) {

	if ( map[e] ) {

	  Node u=g.source(e);	  

	  Node v=g.target(e);

	  _mate.set(u,v);

	  _mate.set(v,u);

	} 

      } 

    }

    ///Writes the matching stored to a \c bool valued \c Edge map.

    ///Writes the matching stored to a \c bool valued \c Edge

    ///map. This map will have the property that there are no two

    ///incident edges \c e, \c f with \c map[e]==map[f]==true. The

    ///edges \c e with \c map[e]==true form the matching.

    template<typename EMapB>

    void writeEMapBool (EMapB& map) const {

      for(UEdgeIt e(g); e!=INVALID; ++e) map.set(e,false);

      typename Graph::template NodeMap<bool> todo(g,true); 

      for(NodeIt v(g); v!=INVALID; ++v) {

	if ( todo[v] && _mate[v]!=INVALID ) {

	  Node u=_mate[v];

	  for(IncEdgeIt e(g,v); e!=INVALID; ++e) {

	    if ( g.runningNode(e) == u ) {

	      map.set(e,true);

	      todo.set(u,false);

	      todo.set(v,false);

	      break;

	    }

	  }

	}

      } 

    }

    ///Writes the canonical decomposition of the graph after running

    ///the algorithm.

    ///After calling any run methods of the class, it writes the

    ///Gallai-Edmonds canonical decomposition of the graph. \c map

    ///must be a node map of \ref pos_enum 's.

    template<typename NMapEnum>

    void writePos (NMapEnum& map) const {

      for(NodeIt v(g); v!=INVALID; ++v)  map.set(v,position[v]);

    }

  private: 

    void lateShrink(Node v, typename Graph::template NodeMap<Node>& ear,  

		    UFE& blossom, UFE& tree);

    void normShrink(Node v, typename Graph::template NodeMap<Node>& ear,  

		    UFE& blossom, UFE& tree);

    void shrink(Node x,Node y, typename Graph::template NodeMap<Node>& ear,  

		UFE& blossom, UFE& tree,std::queue<Node>& Q);

    void shrinkStep(Node& top, Node& middle, Node& bottom,

		    typename Graph::template NodeMap<Node>& ear,  

		    UFE& blossom, UFE& tree, std::queue<Node>& Q);

    bool growOrAugment(Node& y, Node& x, typename Graph::template 

		       NodeMap<Node>& ear, UFE& blossom, UFE& tree, 

		       std::queue<Node>& Q);

    void augment(Node x, typename Graph::template NodeMap<Node>& ear,  

		 UFE& blossom, UFE& tree);

  };

  // **********************************************************************

  //  IMPLEMENTATIONS

  // **********************************************************************

  template <typename Graph>

  void MaxMatching<Graph>::lateShrink(Node v, typename Graph::template 

				      NodeMap<Node>& ear, UFE& blossom, UFE& tree) {

    //We have one tree which we grow, and also shrink but only if it cannot be

    //postponed. If we augment then we return to the "for" cycle of

    //runEdmonds().

    std::queue<Node> Q;   //queue of the totally unscanned nodes

    Q.push(v);  

    std::queue<Node> R;   

    //queue of the nodes which must be scanned for a possible shrink

    while ( !Q.empty() ) {

      Node x=Q.front();

      Q.pop();

      for( IncEdgeIt e(g,x); e!= INVALID; ++e ) {

	Node y=g.runningNode(e);

	//growOrAugment grows if y is covered by the matching and

	//augments if not. In this latter case it returns 1.

	if ( position[y]==C && growOrAugment(y, x, ear, blossom, tree, Q) ) return;

      }

      R.push(x);

    }

    while ( !R.empty() ) {

      Node x=R.front();

      R.pop();

      for( IncEdgeIt e(g,x); e!=INVALID ; ++e ) {

	Node y=g.runningNode(e);

	if ( position[y] == D && blossom.find(x) != blossom.find(y) )  

	  //Recall that we have only one tree.

	  shrink( x, y, ear, blossom, tree, Q);	

	while ( !Q.empty() ) {

	  Node x=Q.front();

	  Q.pop();

	  for( IncEdgeIt e(g,x); e!= INVALID; ++e ) {

	    Node y=g.runningNode(e);

	    //growOrAugment grows if y is covered by the matching and

	    //augments if not. In this latter case it returns 1.

	    if ( position[y]==C && growOrAugment(y, x, ear, blossom, tree, Q) ) return;

	  }

	  R.push(x);

	}

      } //for e

    } // while ( !R.empty() )

  }

  template <typename Graph>

  void MaxMatching<Graph>::normShrink(Node v,

				      typename Graph::template

				      NodeMap<Node>& ear,  

				      UFE& blossom, UFE& tree) {

    //We have one tree, which we grow and shrink. If we augment then we

    //return to the "for" cycle of runEdmonds().

    std::queue<Node> Q;   //queue of the unscanned nodes

    Q.push(v);  

    while ( !Q.empty() ) {

      Node x=Q.front();

      Q.pop();

      for( IncEdgeIt e(g,x); e!=INVALID; ++e ) {

	Node y=g.runningNode(e);

	switch ( position[y] ) {

	case D:          //x and y must be in the same tree

	  if ( blossom.find(x) != blossom.find(y) )

	    //x and y are in the same tree

	    shrink( x, y, ear, blossom, tree, Q);

	  break;

	case C:

	  //growOrAugment grows if y is covered by the matching and

	  //augments if not. In this latter case it returns 1.

	  if ( growOrAugment(y, x, ear, blossom, tree, Q) ) return;

	  break;

	default: break;

       	}

      }

    }

  }

  template <typename Graph>

    void MaxMatching<Graph>::shrink(Node x,Node y, typename 

				    Graph::template NodeMap<Node>& ear,  

				    UFE& blossom, UFE& tree, std::queue<Node>& Q) {

    //x and y are the two adjacent vertices in two blossoms.

    typename Graph::template NodeMap<bool> path(g,false);

    Node b=blossom.find(x);

    path.set(b,true);

    b=_mate[b];

    while ( b!=INVALID ) { 

      b=blossom.find(ear[b]);

      path.set(b,true);

      b=_mate[b];

    } //we go until the root through bases of blossoms and odd vertices

    Node top=y;

    Node middle=blossom.find(top);

    Node bottom=x;

    while ( !path[middle] )

      shrinkStep(top, middle, bottom, ear, blossom, tree, Q);

    //Until we arrive to a node on the path, we update blossom, tree

    //and the positions of the odd nodes.

    Node base=middle;

    top=x;

    middle=blossom.find(top);

    bottom=y;

    Node blossom_base=blossom.find(base);

    while ( middle!=blossom_base )

      shrinkStep(top, middle, bottom, ear, blossom, tree, Q);

    //Until we arrive to a node on the path, we update blossom, tree

    //and the positions of the odd nodes.

    blossom.makeRep(base);

  }

  template <typename Graph>

  void MaxMatching<Graph>::shrinkStep(Node& top, Node& middle, Node& bottom,

				      typename Graph::template

				      NodeMap<Node>& ear,  

				      UFE& blossom, UFE& tree,

				      std::queue<Node>& Q) {

    //We traverse a blossom and update everything.

    ear.set(top,bottom);

    Node t=top;

    while ( t!=middle ) {

      Node u=_mate[t];

      t=ear[u];

      ear.set(t,u);

    } 

    bottom=_mate[middle];

    position.set(bottom,D);

    Q.push(bottom);

    top=ear[bottom];		

    Node oldmiddle=middle;

    middle=blossom.find(top);

    tree.erase(bottom);

    tree.erase(oldmiddle);

    blossom.insert(bottom);

    blossom.join(bottom, oldmiddle);

    blossom.join(top, oldmiddle);

  }

  template <typename Graph>

  bool MaxMatching<Graph>::growOrAugment(Node& y, Node& x, typename Graph::template

					 NodeMap<Node>& ear, UFE& blossom, UFE& tree,

					 std::queue<Node>& Q) {

    //x is in a blossom in the tree, y is outside. If y is covered by

    //the matching we grow, otherwise we augment. In this case we

    //return 1.

    if ( _mate[y]!=INVALID ) {       //grow

      ear.set(y,x);

      Node w=_mate[y];

      blossom.insert(w);

      position.set(y,A);

      position.set(w,D);

      tree.insert(y);

      tree.insert(w);

      tree.join(y,blossom.find(x));  

      tree.join(w,y);  

      Q.push(w);

    } else {                      //augment 

      augment(x, ear, blossom, tree);

      _mate.set(x,y);

      _mate.set(y,x);

      return true;

    }

    return false;

  }

  template <typename Graph>

  void MaxMatching<Graph>::augment(Node x,

				   typename Graph::template NodeMap<Node>& ear,  

				   UFE& blossom, UFE& tree) { 

    Node v=_mate[x];

    while ( v!=INVALID ) {

      Node u=ear[v];

      _mate.set(v,u);

      Node tmp=v;

      v=_mate[u];

      _mate.set(u,tmp);

    }

    Node y=blossom.find(x);

    typename UFE::ItemIt it;

    for (tree.first(it,blossom.find(x)); tree.valid(it); tree.next(it)) {   

      if ( position[it] == D ) {

	typename UFE::ItemIt b_it;

	for (blossom.first(b_it,it); blossom.valid(b_it); blossom.next(b_it)) {  

	  position.set( b_it ,C);

	}

	blossom.eraseClass(it);

      } else position.set( it ,C);

    }

    tree.eraseClass(y);

  }

  /// @}

} //END OF NAMESPACE LEMON

#endif //LEMON_MAX_MATCHING_H