Unionfind changes induced some bugs here. Also some augmentations made.
3 * This file is a part of LEMON, a generic C++ optimization library
5 * Copyright (C) 2003-2006
6 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 * (Egervary Research Group on Combinatorial Optimization, EGRES).
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.
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
19 #ifndef LEMON_MAX_MATCHING_H
20 #define LEMON_MAX_MATCHING_H
23 #include <lemon/bits/invalid.h>
24 #include <lemon/unionfind.h>
25 #include <lemon/graph_utils.h>
29 ///\brief Maximum matching algorithm.
36 ///Edmonds' alternating forest maximum matching algorithm.
38 ///This class provides Edmonds' alternating forest matching
39 ///algorithm. The starting matching (if any) can be passed to the
40 ///algorithm using read-in functions \ref readNMapNode, \ref
41 ///readNMapEdge or \ref readEMapBool depending on the container. The
42 ///resulting maximum matching can be attained by write-out functions
43 ///\ref writeNMapNode, \ref writeNMapEdge or \ref writeEMapBool
44 ///depending on the preferred container.
46 ///The dual side of a matching is a map of the nodes to
47 ///MaxMatching::pos_enum, having values D, A and C showing the
48 ///Gallai-Edmonds decomposition of the graph. The nodes in D induce
49 ///a graph with factor-critical components, the nodes in A form the
50 ///barrier, and the nodes in C induce a graph having a perfect
51 ///matching. This decomposition can be attained by calling \ref
52 ///writePos after running the algorithm.
54 ///\param Graph The undirected graph type the algorithm runs on.
56 ///\author Jacint Szabo
57 template <typename Graph>
62 typedef typename Graph::Node Node;
63 typedef typename Graph::Edge Edge;
64 typedef typename Graph::UEdge UEdge;
65 typedef typename Graph::UEdgeIt UEdgeIt;
66 typedef typename Graph::NodeIt NodeIt;
67 typedef typename Graph::IncEdgeIt IncEdgeIt;
69 typedef UnionFindEnum<Node, Graph::template NodeMap> UFE;
73 ///Indicates the Gallai-Edmonds decomposition of the graph.
75 ///Indicates the Gallai-Edmonds decomposition of the graph, which
76 ///shows an upper bound on the size of a maximum matching. The
77 ///nodes with pos_enum \c D induce a graph with factor-critical
78 ///components, the nodes in \c A form the canonical barrier, and the
79 ///nodes in \c C induce a graph having a perfect matching.
88 static const int HEUR_density=2;
90 typename Graph::template NodeMap<Node> _mate;
91 typename Graph::template NodeMap<pos_enum> position;
95 MaxMatching(const Graph& _g) : g(_g), _mate(_g,INVALID), position(_g) {}
97 ///Runs Edmonds' algorithm.
99 ///Runs Edmonds' algorithm for sparse graphs (number of edges <
100 ///2*number of nodes), and a heuristical Edmonds' algorithm with a
101 ///heuristic of postponing shrinks for dense graphs.
103 if ( countUEdges(g) < HEUR_density*countNodes(g) ) {
106 } else runEdmonds(1);
110 ///Runs Edmonds' algorithm.
112 ///If heur=0 it runs Edmonds' algorithm. If heur=1 it runs
113 ///Edmonds' algorithm with a heuristic of postponing shrinks,
114 ///giving a faster algorithm for dense graphs.
115 void runEdmonds( int heur = 1 ) {
117 //each vertex is put to C
118 for(NodeIt v(g); v!=INVALID; ++v)
121 typename Graph::template NodeMap<Node> ear(g,INVALID);
122 //undefined for the base nodes of the blossoms (i.e. for the
123 //representative elements of UFE blossom) and for the nodes in C
125 typename UFE::MapType blossom_base(g);
126 UFE blossom(blossom_base);
127 typename UFE::MapType tree_base(g);
129 //If these UFE's would be members of the class then also
130 //blossom_base and tree_base should be a member.
132 //We build only one tree and the other vertices uncovered by the
133 //matching belong to C. (They can be considered as singleton
134 //trees.) If this tree can be augmented or no more
135 //grow/augmentation/shrink is possible then we return to this
137 for(NodeIt v(g); v!=INVALID; ++v) {
138 if ( position[v]==C && _mate[v]==INVALID ) {
142 if ( heur == 1 ) lateShrink( v, ear, blossom, tree );
143 else normShrink( v, ear, blossom, tree );
149 ///Finds a greedy matching starting from the actual matching.
151 ///Starting form the actual matching stored, it finds a maximal
153 void greedyMatching() {
154 for(NodeIt v(g); v!=INVALID; ++v)
155 if ( _mate[v]==INVALID ) {
156 for( IncEdgeIt e(g,v); e!=INVALID ; ++e ) {
157 Node y=g.runningNode(e);
158 if ( _mate[y]==INVALID && y!=v ) {
167 ///Returns the size of the actual matching stored.
169 ///Returns the size of the actual matching stored. After \ref
170 ///run() it returns the size of a maximum matching in the graph.
173 for(NodeIt v(g); v!=INVALID; ++v) {
174 if ( _mate[v]!=INVALID ) {
182 ///Resets the actual matching to the empty matching.
184 ///Resets the actual matching to the empty matching.
186 void resetMatching() {
187 for(NodeIt v(g); v!=INVALID; ++v)
188 _mate.set(v,INVALID);
191 ///Returns the mate of a node in the actual matching.
193 ///Returns the mate of a \c node in the actual matching.
194 ///Returns INVALID if the \c node is not covered by the actual matching.
195 Node mate(Node& node) const {
199 ///Reads a matching from a \c Node valued \c Node map.
201 ///Reads a matching from a \c Node valued \c Node map. This map
202 ///must be \e symmetric, i.e. if \c map[u]==v then \c map[v]==u
203 ///must hold, and \c uv will be an edge of the matching.
204 template<typename NMapN>
205 void readNMapNode(NMapN& map) {
206 for(NodeIt v(g); v!=INVALID; ++v) {
211 ///Writes the stored matching to a \c Node valued \c Node map.
213 ///Writes the stored matching to a \c Node valued \c Node map. The
214 ///resulting map will be \e symmetric, i.e. if \c map[u]==v then \c
215 ///map[v]==u will hold, and now \c uv is an edge of the matching.
216 template<typename NMapN>
217 void writeNMapNode (NMapN& map) const {
218 for(NodeIt v(g); v!=INVALID; ++v) {
223 ///Reads a matching from an \c UEdge valued \c Node map.
225 ///Reads a matching from an \c UEdge valued \c Node map. \c
226 ///map[v] must be an \c UEdge incident to \c v. This map must
227 ///have the property that if \c g.oppositeNode(u,map[u])==v then
228 ///\c \c g.oppositeNode(v,map[v])==u holds, and now some edge
229 ///joining \c u to \c v will be an edge of the matching.
230 template<typename NMapE>
231 void readNMapEdge(NMapE& map) {
232 for(NodeIt v(g); v!=INVALID; ++v) {
235 _mate.set(v,g.oppositeNode(v,e));
239 ///Writes the matching stored to an \c UEdge valued \c Node map.
241 ///Writes the stored matching to an \c UEdge valued \c Node
242 ///map. \c map[v] will be an \c UEdge incident to \c v. This
243 ///map will have the property that if \c g.oppositeNode(u,map[u])
244 ///== v then \c map[u]==map[v] holds, and now this edge is an edge
246 template<typename NMapE>
247 void writeNMapEdge (NMapE& map) const {
248 typename Graph::template NodeMap<bool> todo(g,true);
249 for(NodeIt v(g); v!=INVALID; ++v) {
250 if ( todo[v] && _mate[v]!=INVALID ) {
252 for(IncEdgeIt e(g,v); e!=INVALID; ++e) {
253 if ( g.runningNode(e) == u ) {
266 ///Reads a matching from a \c bool valued \c Edge map.
268 ///Reads a matching from a \c bool valued \c Edge map. This map
269 ///must have the property that there are no two incident edges \c
270 ///e, \c f with \c map[e]==map[f]==true. The edges \c e with \c
271 ///map[e]==true form the matching.
272 template<typename EMapB>
273 void readEMapBool(EMapB& map) {
274 for(UEdgeIt e(g); e!=INVALID; ++e) {
285 ///Writes the matching stored to a \c bool valued \c Edge map.
287 ///Writes the matching stored to a \c bool valued \c Edge
288 ///map. This map will have the property that there are no two
289 ///incident edges \c e, \c f with \c map[e]==map[f]==true. The
290 ///edges \c e with \c map[e]==true form the matching.
291 template<typename EMapB>
292 void writeEMapBool (EMapB& map) const {
293 for(UEdgeIt e(g); e!=INVALID; ++e) map.set(e,false);
295 typename Graph::template NodeMap<bool> todo(g,true);
296 for(NodeIt v(g); v!=INVALID; ++v) {
297 if ( todo[v] && _mate[v]!=INVALID ) {
299 for(IncEdgeIt e(g,v); e!=INVALID; ++e) {
300 if ( g.runningNode(e) == u ) {
312 ///Writes the canonical decomposition of the graph after running
315 ///After calling any run methods of the class, it writes the
316 ///Gallai-Edmonds canonical decomposition of the graph. \c map
317 ///must be a node map of \ref pos_enum 's.
318 template<typename NMapEnum>
319 void writePos (NMapEnum& map) const {
320 for(NodeIt v(g); v!=INVALID; ++v) map.set(v,position[v]);
326 void lateShrink(Node v, typename Graph::template NodeMap<Node>& ear,
327 UFE& blossom, UFE& tree);
329 void normShrink(Node v, typename Graph::template NodeMap<Node>& ear,
330 UFE& blossom, UFE& tree);
332 void shrink(Node x,Node y, typename Graph::template NodeMap<Node>& ear,
333 UFE& blossom, UFE& tree,std::queue<Node>& Q);
335 void shrinkStep(Node& top, Node& middle, Node& bottom,
336 typename Graph::template NodeMap<Node>& ear,
337 UFE& blossom, UFE& tree, std::queue<Node>& Q);
339 bool growOrAugment(Node& y, Node& x, typename Graph::template
340 NodeMap<Node>& ear, UFE& blossom, UFE& tree,
341 std::queue<Node>& Q);
343 void augment(Node x, typename Graph::template NodeMap<Node>& ear,
344 UFE& blossom, UFE& tree);
349 // **********************************************************************
351 // **********************************************************************
354 template <typename Graph>
355 void MaxMatching<Graph>::lateShrink(Node v, typename Graph::template
356 NodeMap<Node>& ear, UFE& blossom, UFE& tree) {
357 //We have one tree which we grow, and also shrink but only if it cannot be
358 //postponed. If we augment then we return to the "for" cycle of
361 std::queue<Node> Q; //queue of the totally unscanned nodes
364 //queue of the nodes which must be scanned for a possible shrink
366 while ( !Q.empty() ) {
369 for( IncEdgeIt e(g,x); e!= INVALID; ++e ) {
370 Node y=g.runningNode(e);
371 //growOrAugment grows if y is covered by the matching and
372 //augments if not. In this latter case it returns 1.
373 if ( position[y]==C && growOrAugment(y, x, ear, blossom, tree, Q) ) return;
378 while ( !R.empty() ) {
382 for( IncEdgeIt e(g,x); e!=INVALID ; ++e ) {
383 Node y=g.runningNode(e);
385 if ( position[y] == D && blossom.find(x) != blossom.find(y) )
386 //Recall that we have only one tree.
387 shrink( x, y, ear, blossom, tree, Q);
389 while ( !Q.empty() ) {
392 for( IncEdgeIt e(g,x); e!= INVALID; ++e ) {
393 Node y=g.runningNode(e);
394 //growOrAugment grows if y is covered by the matching and
395 //augments if not. In this latter case it returns 1.
396 if ( position[y]==C && growOrAugment(y, x, ear, blossom, tree, Q) ) return;
401 } // while ( !R.empty() )
405 template <typename Graph>
406 void MaxMatching<Graph>::normShrink(Node v,
407 typename Graph::template
409 UFE& blossom, UFE& tree) {
410 //We have one tree, which we grow and shrink. If we augment then we
411 //return to the "for" cycle of runEdmonds().
413 std::queue<Node> Q; //queue of the unscanned nodes
415 while ( !Q.empty() ) {
420 for( IncEdgeIt e(g,x); e!=INVALID; ++e ) {
421 Node y=g.runningNode(e);
423 switch ( position[y] ) {
424 case D: //x and y must be in the same tree
425 if ( blossom.find(x) != blossom.find(y) )
426 //x and y are in the same tree
427 shrink( x, y, ear, blossom, tree, Q);
430 //growOrAugment grows if y is covered by the matching and
431 //augments if not. In this latter case it returns 1.
432 if ( growOrAugment(y, x, ear, blossom, tree, Q) ) return;
441 template <typename Graph>
442 void MaxMatching<Graph>::shrink(Node x,Node y, typename
443 Graph::template NodeMap<Node>& ear,
444 UFE& blossom, UFE& tree, std::queue<Node>& Q) {
445 //x and y are the two adjacent vertices in two blossoms.
447 typename Graph::template NodeMap<bool> path(g,false);
449 Node b=blossom.find(x);
452 while ( b!=INVALID ) {
453 b=blossom.find(ear[b]);
456 } //we go until the root through bases of blossoms and odd vertices
459 Node middle=blossom.find(top);
461 while ( !path[middle] )
462 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
463 //Until we arrive to a node on the path, we update blossom, tree
464 //and the positions of the odd nodes.
468 middle=blossom.find(top);
470 Node blossom_base=blossom.find(base);
471 while ( middle!=blossom_base )
472 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
473 //Until we arrive to a node on the path, we update blossom, tree
474 //and the positions of the odd nodes.
476 blossom.makeRep(base);
481 template <typename Graph>
482 void MaxMatching<Graph>::shrinkStep(Node& top, Node& middle, Node& bottom,
483 typename Graph::template
485 UFE& blossom, UFE& tree,
486 std::queue<Node>& Q) {
487 //We traverse a blossom and update everything.
491 while ( t!=middle ) {
496 bottom=_mate[middle];
497 position.set(bottom,D);
500 Node oldmiddle=middle;
501 middle=blossom.find(top);
503 tree.erase(oldmiddle);
504 blossom.insert(bottom);
505 blossom.join(bottom, oldmiddle);
506 blossom.join(top, oldmiddle);
510 template <typename Graph>
511 bool MaxMatching<Graph>::growOrAugment(Node& y, Node& x, typename Graph::template
512 NodeMap<Node>& ear, UFE& blossom, UFE& tree,
513 std::queue<Node>& Q) {
514 //x is in a blossom in the tree, y is outside. If y is covered by
515 //the matching we grow, otherwise we augment. In this case we
518 if ( _mate[y]!=INVALID ) { //grow
526 tree.join(y,blossom.find(x));
530 augment(x, ear, blossom, tree);
539 template <typename Graph>
540 void MaxMatching<Graph>::augment(Node x,
541 typename Graph::template NodeMap<Node>& ear,
542 UFE& blossom, UFE& tree) {
544 while ( v!=INVALID ) {
552 Node y=blossom.find(x);
553 typename UFE::ItemIt it;
554 for (tree.first(it,blossom.find(x)); tree.valid(it); tree.next(it)) {
555 if ( position[it] == D ) {
556 typename UFE::ItemIt b_it;
557 for (blossom.first(b_it,it); blossom.valid(b_it); blossom.next(b_it)) {
558 position.set( b_it ,C);
560 blossom.eraseClass(it);
561 } else position.set( it ,C);
569 } //END OF NAMESPACE LEMON
571 #endif //LEMON_MAX_MATCHING_H