Adding a function which returns the mate of a node.
2 * src/lemon/max_matching.h - Part of LEMON, a generic C++ optimization library
4 * Copyright (C) 2004 Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
5 * (Egervary Combinatorial Optimization Research Group, 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>
57 typedef typename Graph::Node Node;
58 typedef typename Graph::Edge Edge;
59 typedef typename Graph::UndirEdgeIt UndirEdgeIt;
60 typedef typename Graph::NodeIt NodeIt;
61 typedef typename Graph::IncEdgeIt IncEdgeIt;
63 typedef UnionFindEnum<Node, Graph::template NodeMap> UFE;
67 ///Indicates the Gallai-Edmonds decomposition of the graph.
69 ///Indicates the Gallai-Edmonds decomposition of the graph, which
70 ///shows an upper bound on the size of a maximum matching. The
71 ///nodes with pos_enum \c D induce a graph with factor-critical
72 ///components, the nodes in \c A form the canonical barrier, and the
73 ///nodes in \c C induce a graph having a perfect matching.
82 static const int HEUR_density=2;
84 typename Graph::template NodeMap<Node> _mate;
85 typename Graph::template NodeMap<pos_enum> position;
89 MaxMatching(const Graph& _g) : g(_g), _mate(_g,INVALID), position(_g) {}
91 ///Runs Edmonds' algorithm.
93 ///Runs Edmonds' algorithm for sparse graphs (number of edges <
94 ///2*number of nodes), and a heuristical Edmonds' algorithm with a
95 ///heuristic of postponing shrinks for dense graphs.
98 ///Runs Edmonds' algorithm.
100 ///If heur=0 it runs Edmonds' algorithm. If heur=1 it runs
101 ///Edmonds' algorithm with a heuristic of postponing shrinks,
102 ///giving a faster algorithm for dense graphs.
103 void runEdmonds( int heur );
105 ///Finds a greedy matching starting from the actual matching.
107 ///Starting form the actual matching stored, it finds a maximal
109 void greedyMatching();
111 ///Returns the size of the actual matching stored.
113 ///Returns the size of the actual matching stored. After \ref
114 ///run() it returns the size of a maximum matching in the graph.
117 ///Resets the actual matching to the empty matching.
119 ///Resets the actual matching to the empty matching.
121 void resetMatching();
123 ///Returns the mate of a node in the actual matching.
125 ///Returns the mate of a \c node in the actual matching.
126 ///Returns INVALID if the \c node is not covered by the actual matching.
127 Node mate(Node& node) const {
131 ///Reads a matching from a \c Node map of \c Nodes.
133 ///Reads a matching from a \c Node map of \c Nodes. This map must be \e
134 ///symmetric, i.e. if \c map[u]==v then \c map[v]==u must hold, and
135 ///\c uv will be an edge of the matching.
136 template<typename NMapN>
137 void readNMapNode(NMapN& map) {
138 for(NodeIt v(g); v!=INVALID; ++v) {
143 ///Writes the stored matching to a \c Node map of \c Nodes.
145 ///Writes the stored matching to a \c Node map of \c Nodes. The
146 ///resulting map will be \e symmetric, i.e. if \c map[u]==v then \c
147 ///map[v]==u will hold, and now \c uv is an edge of the matching.
148 template<typename NMapN>
149 void writeNMapNode (NMapN& map) const {
150 for(NodeIt v(g); v!=INVALID; ++v) {
155 ///Reads a matching from a \c Node map of \c Edges.
157 ///Reads a matching from a \c Node map of incident \c Edges. This
158 ///map must have the property that if \c G.target(map[u])==v then \c
159 ///G.target(map[v])==u must hold, and now this edge is an edge of
161 template<typename NMapE>
162 void readNMapEdge(NMapE& map) {
163 for(NodeIt v(g); v!=INVALID; ++v) {
166 g.source(e) == v ? _mate.set(v,g.target(e)) : _mate.set(v,g.source(e));
170 ///Writes the matching stored to a \c Node map of \c Edges.
172 ///Writes the stored matching to a \c Node map of incident \c
173 ///Edges. This map will have the property that if \c
174 ///g.target(map[u])==v then \c g.target(map[v])==u holds, and now this
175 ///edge is an edge of the matching.
176 template<typename NMapE>
177 void writeNMapEdge (NMapE& map) const {
178 typename Graph::template NodeMap<bool> todo(g,true);
179 for(NodeIt v(g); v!=INVALID; ++v) {
180 if ( todo[v] && _mate[v]!=INVALID ) {
182 for(IncEdgeIt e(g,v); e!=INVALID; ++e) {
183 if ( g.target(e) == u ) {
196 ///Reads a matching from an \c Edge map of \c bools.
198 ///Reads a matching from an \c Edge map of \c bools. This map must
199 ///have the property that there are no two adjacent edges \c e, \c
200 ///f with \c map[e]==map[f]==true. The edges \c e with \c
201 ///map[e]==true form the matching.
202 template<typename EMapB>
203 void readEMapBool(EMapB& map) {
204 for(UndirEdgeIt e(g); e!=INVALID; ++e) {
215 ///Writes the matching stored to an \c Edge map of \c bools.
217 ///Writes the matching stored to an \c Edge map of \c bools. This
218 ///map will have the property that there are no two adjacent edges
219 ///\c e, \c f with \c map[e]==map[f]==true. The edges \c e with \c
220 ///map[e]==true form the matching.
221 template<typename EMapB>
222 void writeEMapBool (EMapB& map) const {
223 for(UndirEdgeIt e(g); e!=INVALID; ++e) map.set(e,false);
225 typename Graph::template NodeMap<bool> todo(g,true);
226 for(NodeIt v(g); v!=INVALID; ++v) {
227 if ( todo[v] && _mate[v]!=INVALID ) {
229 for(IncEdgeIt e(g,v); e!=INVALID; ++e) {
230 if ( g.target(e) == u ) {
242 ///Writes the canonical decomposition of the graph after running
245 ///After calling any run methods of the class, it writes the
246 ///Gallai-Edmonds canonical decomposition of the graph. \c map
247 ///must be a node map of \ref pos_enum 's.
248 template<typename NMapEnum>
249 void writePos (NMapEnum& map) const {
250 for(NodeIt v(g); v!=INVALID; ++v) map.set(v,position[v]);
255 void lateShrink(Node v, typename Graph::template NodeMap<Node>& ear,
256 UFE& blossom, UFE& tree);
258 void normShrink(Node v, typename Graph::NodeMap<Node>& ear,
259 UFE& blossom, UFE& tree);
261 bool noShrinkStep(Node x, typename Graph::NodeMap<Node>& ear,
262 UFE& blossom, UFE& tree, std::queue<Node>& Q);
264 void shrinkStep(Node& top, Node& middle, Node& bottom, typename Graph::NodeMap<Node>& ear,
265 UFE& blossom, UFE& tree, std::queue<Node>& Q);
267 void augment(Node x, typename Graph::NodeMap<Node>& ear,
268 UFE& blossom, UFE& tree);
273 // **********************************************************************
275 // **********************************************************************
278 template <typename Graph>
279 void MaxMatching<Graph>::run() {
280 if ( countUndirEdges(g) < HEUR_density*countNodes(g) ) {
283 } else runEdmonds(1);
287 template <typename Graph>
288 void MaxMatching<Graph>::runEdmonds( int heur=1 ) {
290 for(NodeIt v(g); v!=INVALID; ++v)
293 typename Graph::template NodeMap<Node> ear(g,INVALID);
294 //undefined for the base nodes of the blossoms (i.e. for the
295 //representative elements of UFE blossom) and for the nodes in C
297 typename UFE::MapType blossom_base(g);
298 UFE blossom(blossom_base);
299 typename UFE::MapType tree_base(g);
302 for(NodeIt v(g); v!=INVALID; ++v) {
303 if ( position[v]==C && _mate[v]==INVALID ) {
307 if ( heur == 1 ) lateShrink( v, ear, blossom, tree );
308 else normShrink( v, ear, blossom, tree );
314 template <typename Graph>
315 void MaxMatching<Graph>::lateShrink(Node v, typename Graph::template NodeMap<Node>& ear,
316 UFE& blossom, UFE& tree) {
318 std::queue<Node> Q; //queue of the totally unscanned nodes
321 //queue of the nodes which must be scanned for a possible shrink
323 while ( !Q.empty() ) {
326 if ( noShrinkStep( x, ear, blossom, tree, Q ) ) return;
330 while ( !R.empty() ) {
334 for( IncEdgeIt e(g,x); e!=INVALID ; ++e ) {
337 if ( position[y] == D && blossom.find(x) != blossom.find(y) ) {
338 //x and y must be in the same tree
340 typename Graph::template NodeMap<bool> path(g,false);
342 Node b=blossom.find(x);
345 while ( b!=INVALID ) {
346 b=blossom.find(ear[b]);
349 } //going till the root
352 Node middle=blossom.find(top);
354 while ( !path[middle] )
355 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
359 middle=blossom.find(top);
361 Node blossom_base=blossom.find(base);
362 while ( middle!=blossom_base )
363 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
365 blossom.makeRep(base);
366 } // if shrink is needed
368 while ( !Q.empty() ) {
371 if ( noShrinkStep(x, ear, blossom, tree, Q) ) return;
375 } // while ( !R.empty() )
379 template <typename Graph>
380 void MaxMatching<Graph>::normShrink(Node v, typename Graph::NodeMap<Node>& ear,
381 UFE& blossom, UFE& tree) {
383 std::queue<Node> Q; //queue of the unscanned nodes
385 while ( !Q.empty() ) {
390 for( IncEdgeIt e(g,x); e!=INVALID; ++e ) {
393 switch ( position[y] ) {
394 case D: //x and y must be in the same tree
396 if ( blossom.find(x) != blossom.find(y) ) { //shrink
397 typename Graph::template NodeMap<bool> path(g,false);
399 Node b=blossom.find(x);
402 while ( b!=INVALID ) {
403 b=blossom.find(ear[b]);
406 } //going till the root
409 Node middle=blossom.find(top);
411 while ( !path[middle] )
412 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
416 middle=blossom.find(top);
418 Node blossom_base=blossom.find(base);
419 while ( middle!=blossom_base )
420 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
422 blossom.makeRep(base);
426 if ( _mate[y]!=INVALID ) { //grow
435 tree.join(y,blossom.find(x));
439 augment(x, ear, blossom, tree);
451 template <typename Graph>
452 void MaxMatching<Graph>::greedyMatching() {
453 for(NodeIt v(g); v!=INVALID; ++v)
454 if ( _mate[v]==INVALID ) {
455 for( IncEdgeIt e(g,v); e!=INVALID ; ++e ) {
457 if ( _mate[y]==INVALID && y!=v ) {
466 template <typename Graph>
467 int MaxMatching<Graph>::size() const {
469 for(NodeIt v(g); v!=INVALID; ++v) {
470 if ( _mate[v]!=INVALID ) {
477 template <typename Graph>
478 void MaxMatching<Graph>::resetMatching() {
479 for(NodeIt v(g); v!=INVALID; ++v)
480 _mate.set(v,INVALID);
483 template <typename Graph>
484 bool MaxMatching<Graph>::noShrinkStep(Node x, typename Graph::NodeMap<Node>& ear,
485 UFE& blossom, UFE& tree, std::queue<Node>& Q) {
486 for( IncEdgeIt e(g,x); e!= INVALID; ++e ) {
489 if ( position[y]==C ) {
490 if ( _mate[y]!=INVALID ) { //grow
498 tree.join(y,blossom.find(x));
502 augment(x, ear, blossom, tree);
512 template <typename Graph>
513 void MaxMatching<Graph>::shrinkStep(Node& top, Node& middle, Node& bottom, typename Graph::NodeMap<Node>& ear,
514 UFE& blossom, UFE& tree, std::queue<Node>& Q) {
517 while ( t!=middle ) {
522 bottom=_mate[middle];
523 position.set(bottom,D);
526 Node oldmiddle=middle;
527 middle=blossom.find(top);
529 tree.erase(oldmiddle);
530 blossom.insert(bottom);
531 blossom.join(bottom, oldmiddle);
532 blossom.join(top, oldmiddle);
535 template <typename Graph>
536 void MaxMatching<Graph>::augment(Node x, typename Graph::NodeMap<Node>& ear,
537 UFE& blossom, UFE& tree) {
539 while ( v!=INVALID ) {
547 typename UFE::ItemIt it;
548 for (tree.first(it,blossom.find(x)); tree.valid(it); tree.next(it)) {
549 if ( position[it] == D ) {
550 typename UFE::ItemIt b_it;
551 for (blossom.first(b_it,it); blossom.valid(b_it); blossom.next(b_it)) {
552 position.set( b_it ,C);
554 blossom.eraseClass(it);
555 } else position.set( it ,C);
563 } //END OF NAMESPACE LEMON