Some documentation got revised.
2 * lemon/max_matching.h - Part of LEMON, a generic C++ optimization library
4 * Copyright (C) 2005 Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
5 * (Egervary Research Group on Combinatorial Optimization, EGRES).
7 * Permission to use, modify and distribute this software is granted
8 * provided that this copyright notice appears in all copies. For
9 * precise terms see the accompanying LICENSE file.
11 * This software is provided "AS IS" with no warranty of any kind,
12 * express or implied, and with no claim as to its suitability for any
17 #ifndef LEMON_MAX_MATCHING_H
18 #define LEMON_MAX_MATCHING_H
21 #include <lemon/invalid.h>
22 #include <lemon/unionfind.h>
23 #include <lemon/graph_utils.h>
27 ///\brief Maximum matching algorithm.
34 ///Edmonds' alternating forest maximum matching algorithm.
36 ///This class provides Edmonds' alternating forest matching
37 ///algorithm. The starting matching (if any) can be passed to the
38 ///algorithm using read-in functions \ref readNMapNode, \ref
39 ///readNMapEdge or \ref readEMapBool depending on the container. The
40 ///resulting maximum matching can be attained by write-out functions
41 ///\ref writeNMapNode, \ref writeNMapEdge or \ref writeEMapBool
42 ///depending on the preferred container.
44 ///The dual side of a matching is a map of the nodes to
45 ///MaxMatching::pos_enum, having values D, A and C showing the
46 ///Gallai-Edmonds decomposition of the graph. The nodes in D induce
47 ///a graph with factor-critical components, the nodes in A form the
48 ///barrier, and the nodes in C induce a graph having a perfect
49 ///matching. This decomposition can be attained by calling \ref
50 ///writePos after running the algorithm.
52 ///\param Graph The undirected graph type the algorithm runs on.
54 ///\author Jacint Szabo
55 template <typename Graph>
60 typedef typename Graph::Node Node;
61 typedef typename Graph::Edge Edge;
62 typedef typename Graph::UndirEdge UndirEdge;
63 typedef typename Graph::UndirEdgeIt UndirEdgeIt;
64 typedef typename Graph::NodeIt NodeIt;
65 typedef typename Graph::IncEdgeIt IncEdgeIt;
67 typedef UnionFindEnum<Node, Graph::template NodeMap> UFE;
71 ///Indicates the Gallai-Edmonds decomposition of the graph.
73 ///Indicates the Gallai-Edmonds decomposition of the graph, which
74 ///shows an upper bound on the size of a maximum matching. The
75 ///nodes with pos_enum \c D induce a graph with factor-critical
76 ///components, the nodes in \c A form the canonical barrier, and the
77 ///nodes in \c C induce a graph having a perfect matching.
86 static const int HEUR_density=2;
88 typename Graph::template NodeMap<Node> _mate;
89 typename Graph::template NodeMap<pos_enum> position;
93 MaxMatching(const Graph& _g) : g(_g), _mate(_g,INVALID), position(_g) {}
95 ///Runs Edmonds' algorithm.
97 ///Runs Edmonds' algorithm for sparse graphs (number of edges <
98 ///2*number of nodes), and a heuristical Edmonds' algorithm with a
99 ///heuristic of postponing shrinks for dense graphs.
102 ///Runs Edmonds' algorithm.
104 ///If heur=0 it runs Edmonds' algorithm. If heur=1 it runs
105 ///Edmonds' algorithm with a heuristic of postponing shrinks,
106 ///giving a faster algorithm for dense graphs.
107 void runEdmonds( int heur );
109 ///Finds a greedy matching starting from the actual matching.
111 ///Starting form the actual matching stored, it finds a maximal
113 void greedyMatching();
115 ///Returns the size of the actual matching stored.
117 ///Returns the size of the actual matching stored. After \ref
118 ///run() it returns the size of a maximum matching in the graph.
121 ///Resets the actual matching to the empty matching.
123 ///Resets the actual matching to the empty matching.
125 void resetMatching();
127 ///Returns the mate of a node in the actual matching.
129 ///Returns the mate of a \c node in the actual matching.
130 ///Returns INVALID if the \c node is not covered by the actual matching.
131 Node mate(Node& node) const {
135 ///Reads a matching from a \c Node valued \c Node map.
137 ///Reads a matching from a \c Node valued \c Node map. This map
138 ///must be \e symmetric, i.e. if \c map[u]==v then \c map[v]==u
139 ///must hold, and \c uv will be an edge of the matching.
140 template<typename NMapN>
141 void readNMapNode(NMapN& map) {
142 for(NodeIt v(g); v!=INVALID; ++v) {
147 ///Writes the stored matching to a \c Node valued \c Node map.
149 ///Writes the stored matching to a \c Node valued \c Node map. The
150 ///resulting map will be \e symmetric, i.e. if \c map[u]==v then \c
151 ///map[v]==u will hold, and now \c uv is an edge of the matching.
152 template<typename NMapN>
153 void writeNMapNode (NMapN& map) const {
154 for(NodeIt v(g); v!=INVALID; ++v) {
159 ///Reads a matching from an \c UndirEdge valued \c Node map.
161 ///Reads a matching from an \c UndirEdge valued \c Node map. \c
162 ///map[v] must be an \c UndirEdge incident to \c v. This map must
163 ///have the property that if \c g.oppositeNode(u,map[u])==v then
164 ///\c \c g.oppositeNode(v,map[v])==u holds, and now some edge
165 ///joining \c u to \c v will be an edge of the matching.
166 template<typename NMapE>
167 void readNMapEdge(NMapE& map) {
168 for(NodeIt v(g); v!=INVALID; ++v) {
171 _mate.set(v,g.oppositeNode(v,e));
175 ///Writes the matching stored to an \c UndirEdge valued \c Node map.
177 ///Writes the stored matching to an \c UndirEdge valued \c Node
178 ///map. \c map[v] will be an \c UndirEdge incident to \c v. This
179 ///map will have the property that if \c g.oppositeNode(u,map[u])
180 ///== v then \c map[u]==map[v] holds, and now this edge is an edge
182 template<typename NMapE>
183 void writeNMapEdge (NMapE& map) const {
184 typename Graph::template NodeMap<bool> todo(g,true);
185 for(NodeIt v(g); v!=INVALID; ++v) {
186 if ( todo[v] && _mate[v]!=INVALID ) {
188 for(IncEdgeIt e(g,v); e!=INVALID; ++e) {
189 if ( g.runningNode(e) == u ) {
202 ///Reads a matching from a \c bool valued \c Edge map.
204 ///Reads a matching from a \c bool valued \c Edge map. This map
205 ///must have the property that there are no two incident edges \c
206 ///e, \c f with \c map[e]==map[f]==true. The edges \c e with \c
207 ///map[e]==true form the matching.
208 template<typename EMapB>
209 void readEMapBool(EMapB& map) {
210 for(UndirEdgeIt e(g); e!=INVALID; ++e) {
221 ///Writes the matching stored to a \c bool valued \c Edge map.
223 ///Writes the matching stored to a \c bool valued \c Edge
224 ///map. This map will have the property that there are no two
225 ///incident edges \c e, \c f with \c map[e]==map[f]==true. The
226 ///edges \c e with \c map[e]==true form the matching.
227 template<typename EMapB>
228 void writeEMapBool (EMapB& map) const {
229 for(UndirEdgeIt e(g); e!=INVALID; ++e) map.set(e,false);
231 typename Graph::template NodeMap<bool> todo(g,true);
232 for(NodeIt v(g); v!=INVALID; ++v) {
233 if ( todo[v] && _mate[v]!=INVALID ) {
235 for(IncEdgeIt e(g,v); e!=INVALID; ++e) {
236 if ( g.runningNode(e) == u ) {
248 ///Writes the canonical decomposition of the graph after running
251 ///After calling any run methods of the class, it writes the
252 ///Gallai-Edmonds canonical decomposition of the graph. \c map
253 ///must be a node map of \ref pos_enum 's.
254 template<typename NMapEnum>
255 void writePos (NMapEnum& map) const {
256 for(NodeIt v(g); v!=INVALID; ++v) map.set(v,position[v]);
262 void lateShrink(Node v, typename Graph::template NodeMap<Node>& ear,
263 UFE& blossom, UFE& tree);
265 void normShrink(Node v, typename Graph::template NodeMap<Node>& ear,
266 UFE& blossom, UFE& tree);
268 bool noShrinkStep(Node x, typename Graph::template NodeMap<Node>& ear,
269 UFE& blossom, UFE& tree, std::queue<Node>& Q);
271 void shrinkStep(Node& top, Node& middle, Node& bottom,
272 typename Graph::template NodeMap<Node>& ear,
273 UFE& blossom, UFE& tree, std::queue<Node>& Q);
275 void augment(Node x, typename Graph::template NodeMap<Node>& ear,
276 UFE& blossom, UFE& tree);
281 // **********************************************************************
283 // **********************************************************************
286 template <typename Graph>
287 void MaxMatching<Graph>::run() {
288 if ( countUndirEdges(g) < HEUR_density*countNodes(g) ) {
291 } else runEdmonds(1);
295 template <typename Graph>
296 void MaxMatching<Graph>::runEdmonds( int heur=1 ) {
298 for(NodeIt v(g); v!=INVALID; ++v)
301 typename Graph::template NodeMap<Node> ear(g,INVALID);
302 //undefined for the base nodes of the blossoms (i.e. for the
303 //representative elements of UFE blossom) and for the nodes in C
305 typename UFE::MapType blossom_base(g);
306 UFE blossom(blossom_base);
307 typename UFE::MapType tree_base(g);
309 //If these UFE's would be members of the class then also
310 //blossom_base and tree_base should be a member.
312 for(NodeIt v(g); v!=INVALID; ++v) {
313 if ( position[v]==C && _mate[v]==INVALID ) {
317 if ( heur == 1 ) lateShrink( v, ear, blossom, tree );
318 else normShrink( v, ear, blossom, tree );
324 template <typename Graph>
325 void MaxMatching<Graph>::lateShrink(Node v, typename Graph::template NodeMap<Node>& ear,
326 UFE& blossom, UFE& tree) {
328 std::queue<Node> Q; //queue of the totally unscanned nodes
331 //queue of the nodes which must be scanned for a possible shrink
333 while ( !Q.empty() ) {
336 if ( noShrinkStep( x, ear, blossom, tree, Q ) ) return;
340 while ( !R.empty() ) {
344 for( IncEdgeIt e(g,x); e!=INVALID ; ++e ) {
345 Node y=g.runningNode(e);
347 if ( position[y] == D && blossom.find(x) != blossom.find(y) ) {
348 //x and y must be in the same tree
350 typename Graph::template NodeMap<bool> path(g,false);
352 Node b=blossom.find(x);
355 while ( b!=INVALID ) {
356 b=blossom.find(ear[b]);
359 } //going till the root
362 Node middle=blossom.find(top);
364 while ( !path[middle] )
365 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
369 middle=blossom.find(top);
371 Node blossom_base=blossom.find(base);
372 while ( middle!=blossom_base )
373 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
375 blossom.makeRep(base);
376 } // if shrink is needed
378 while ( !Q.empty() ) {
381 if ( noShrinkStep(x, ear, blossom, tree, Q) ) return;
385 } // while ( !R.empty() )
389 template <typename Graph>
390 void MaxMatching<Graph>::normShrink(Node v,
391 typename Graph::template
393 UFE& blossom, UFE& tree) {
394 std::queue<Node> Q; //queue of the unscanned nodes
396 while ( !Q.empty() ) {
401 for( IncEdgeIt e(g,x); e!=INVALID; ++e ) {
402 Node y=g.runningNode(e);
404 switch ( position[y] ) {
405 case D: //x and y must be in the same tree
407 if ( blossom.find(x) != blossom.find(y) ) { //shrink
408 typename Graph::template NodeMap<bool> path(g,false);
410 Node b=blossom.find(x);
413 while ( b!=INVALID ) {
414 b=blossom.find(ear[b]);
417 } //going till the root
420 Node middle=blossom.find(top);
422 while ( !path[middle] )
423 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
427 middle=blossom.find(top);
429 Node blossom_base=blossom.find(base);
430 while ( middle!=blossom_base )
431 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
433 blossom.makeRep(base);
437 if ( _mate[y]!=INVALID ) { //grow
446 tree.join(y,blossom.find(x));
450 augment(x, ear, blossom, tree);
462 template <typename Graph>
463 void MaxMatching<Graph>::greedyMatching() {
464 for(NodeIt v(g); v!=INVALID; ++v)
465 if ( _mate[v]==INVALID ) {
466 for( IncEdgeIt e(g,v); e!=INVALID ; ++e ) {
467 Node y=g.runningNode(e);
468 if ( _mate[y]==INVALID && y!=v ) {
477 template <typename Graph>
478 int MaxMatching<Graph>::size() const {
480 for(NodeIt v(g); v!=INVALID; ++v) {
481 if ( _mate[v]!=INVALID ) {
488 template <typename Graph>
489 void MaxMatching<Graph>::resetMatching() {
490 for(NodeIt v(g); v!=INVALID; ++v)
491 _mate.set(v,INVALID);
494 template <typename Graph>
495 bool MaxMatching<Graph>::noShrinkStep(Node x,
496 typename Graph::template
498 UFE& blossom, UFE& tree,
499 std::queue<Node>& Q) {
500 for( IncEdgeIt e(g,x); e!= INVALID; ++e ) {
501 Node y=g.runningNode(e);
503 if ( position[y]==C ) {
504 if ( _mate[y]!=INVALID ) { //grow
512 tree.join(y,blossom.find(x));
516 augment(x, ear, blossom, tree);
526 template <typename Graph>
527 void MaxMatching<Graph>::shrinkStep(Node& top, Node& middle, Node& bottom,
528 typename Graph::template
530 UFE& blossom, UFE& tree,
531 std::queue<Node>& Q) {
534 while ( t!=middle ) {
539 bottom=_mate[middle];
540 position.set(bottom,D);
543 Node oldmiddle=middle;
544 middle=blossom.find(top);
546 tree.erase(oldmiddle);
547 blossom.insert(bottom);
548 blossom.join(bottom, oldmiddle);
549 blossom.join(top, oldmiddle);
552 template <typename Graph>
553 void MaxMatching<Graph>::augment(Node x,
554 typename Graph::template NodeMap<Node>& ear,
555 UFE& blossom, UFE& tree) {
557 while ( v!=INVALID ) {
565 typename UFE::ItemIt it;
566 for (tree.first(it,blossom.find(x)); tree.valid(it); tree.next(it)) {
567 if ( position[it] == D ) {
568 typename UFE::ItemIt b_it;
569 for (blossom.first(b_it,it); blossom.valid(b_it); blossom.next(b_it)) {
570 position.set( b_it ,C);
572 blossom.eraseClass(it);
573 } else position.set( it ,C);
581 } //END OF NAMESPACE LEMON
583 #endif //LEMON_MAX_MATCHING_H