Completions.
2 #ifndef LEMON_MAX_MATCHING_H
3 #define LEMON_MAX_MATCHING_H
7 ///\brief Maximum matching algorithm.
12 #include <unionfind.h>
19 ///Maximum matching algorithms class.
21 ///This class provides Edmonds' alternating forest matching
22 ///algorithm. The starting matching (if any) can be passed to the
23 ///algorithm using read-in functions \ref readNMapNode, \ref
24 ///readNMapEdge or \ref readEMapBool depending on the container. The
25 ///resulting maximum matching can be attained by write-out functions
26 ///\ref writeNMapNode, \ref writeNMapEdge or \ref writeEMapBool
27 ///depending on the preferred container.
29 ///The dual side of a mathcing is a map of the nodes to
30 ///MaxMatching::pos_enum, having values D, A and C showing the
31 ///Gallai-Edmonds decomposition of the graph. The nodes in D induce
32 ///a graph with factor-critical components, the nodes in A form the
33 ///barrier, and the nodes in C induce a graph having a perfect
34 ///matching. This decomposition can be attained by calling \ref
35 ///writePos after running the algorithm. Before subsequent runs,
36 ///the function \ref resetPos() must be called.
38 ///\param Graph The undirected graph type the algorithm runs on.
40 ///\author Jacint Szabo
41 template <typename Graph>
43 typedef typename Graph::Node Node;
44 typedef typename Graph::Edge Edge;
45 typedef typename Graph::EdgeIt EdgeIt;
46 typedef typename Graph::NodeIt NodeIt;
47 typedef typename Graph::OutEdgeIt OutEdgeIt;
49 typedef UnionFindEnum<Node, Graph::template NodeMap> UFE;
53 ///Indicates the Gallai-Edmonds decomposition of the graph.
55 ///Indicates the Gallai-Edmonds decomposition of the graph, which
56 ///shows an upper bound on the size of a maximum matching. The
57 ///nodes with pos_enum \c D induce a graph with factor-critical
58 ///components, the nodes in \c A form the canonical barrier, and the
59 ///nodes in \c C induce a graph having a perfect matching.
69 typename Graph::template NodeMap<Node> mate;
70 typename Graph::template NodeMap<pos_enum> position;
74 MaxMatching(const Graph& _G) : G(_G), mate(_G,INVALID), position(_G,C) {}
76 ///Runs Edmonds' algorithm.
78 ///Runs Edmonds' algorithm for sparse graphs (edgeNum >=
79 ///2*nodeNum), and a heuristical Edmonds' algorithm with a
80 ///heuristic of postponing shrinks for dense graphs. \pre Before
81 ///the subsequent calls \ref resetPos must be called.
84 ///Runs Edmonds' algorithm.
86 ///If heur=0 it runs Edmonds' algorithm. If heur=1 it runs
87 ///Edmonds' algorithm with a heuristic of postponing shrinks,
88 ///giving a faster algorithm for dense graphs. \pre Before the
89 ///subsequent calls \ref resetPos must be called.
90 void runEdmonds( int heur );
92 ///Finds a greedy matching starting from the actual matching.
94 ///Starting form the actual matching stored, it finds a maximal
96 void greedyMatching();
98 ///Returns the size of the actual matching stored.
100 ///Returns the size of the actual matching stored. After \ref
101 ///run() it returns the size of a maximum matching in the graph.
104 ///Resets the map storing the Gallai-Edmonds decomposition.
106 ///Resets the map storing the Gallai-Edmonds decomposition of the
107 ///graph, making it possible to run the algorithm. Must be called
108 ///before all runs of the Edmonds algorithm, except for the first
112 ///Resets the actual matching to the empty matching.
114 ///Resets the actual matching to the empty matching.
116 void resetMatching();
118 ///Reads a matching from a \c Node map of \c Nodes.
120 ///Reads a matching from a \c Node map of \c Nodes. This map must be \e
121 ///symmetric, i.e. if \c map[u]=v then \c map[v]=u must hold, and
122 ///now \c uv is an edge of the matching.
123 template<typename NMapN>
124 void readNMapNode(NMapN& map) {
126 for( G.first(v); G.valid(v); G.next(v)) {
131 ///Writes the stored matching to a \c Node map of \c Nodes.
133 ///Writes the stored matching to a \c Node map of \c Nodes. The
134 ///resulting map will be \e symmetric, i.e. if \c map[u]=v then \c
135 ///map[v]=u will hold, and now \c uv is an edge of the matching.
136 template<typename NMapN>
137 void writeNMapNode (NMapN& map) const {
139 for( G.first(v); G.valid(v); G.next(v)) {
144 ///Reads a matching from a \c Node map of \c Edges.
146 ///Reads a matching from a \c Node map of incident \c Edges. This
147 ///map must have the property that if \c G.bNode(map[u])=v then \c
148 ///G.bNode(map[v])=u must hold, and now this edge is an edge of
150 template<typename NMapE>
151 void readNMapEdge(NMapE& map) {
153 for( G.first(v); G.valid(v); G.next(v)) {
156 G.source(e) == v ? mate.set(v,G.target(e)) : mate.set(v,G.source(e));
160 ///Writes the matching stored to a \c Node map of \c Edges.
162 ///Writes the stored matching to a \c Node map of incident \c
163 ///Edges. This map will have the property that if \c
164 ///G.bNode(map[u])=v then \c G.bNode(map[v])=u holds, and now this
165 ///edge is an edge of the matching.
166 template<typename NMapE>
167 void writeNMapEdge (NMapE& map) const {
168 typename Graph::template NodeMap<bool> todo(G,false);
170 for( G.first(v); G.valid(v); G.next(v)) {
171 if ( mate[v]!=INVALID ) todo.set(v,true);
174 for( G.first(e); G.valid(e); G.next(e)) {
175 if ( todo[G.target(e)] && todo[G.source(e)] ) {
178 if ( mate[u]=v && mate[v]=u ) {
188 ///Reads a matching from an \c Edge map of \c bools.
190 ///Reads a matching from an \c Edge map of \c bools. This map must
191 ///have the property that there are no two adjacent edges \c e, \c
192 ///f with \c map[e]=map[f]=true. The edges \c e with \c
193 ///map[e]=true form the matching.
194 template<typename EMapB>
195 void readEMapBool(EMapB& map) {
197 for( G.first(e); G.valid(e); G.next(e)) {
208 ///Writes the matching stored to an \c Edge map of \c bools.
210 ///Writes the matching stored to an \c Edge map of \c bools. This
211 ///map will have the property that there are no two adjacent edges
212 ///\c e, \c f with \c map[e]=map[f]=true. The edges \c e with \c
213 ///map[e]=true form the matching.
214 template<typename EMapB>
215 void writeEMapBool (EMapB& map) const {
216 typename Graph::template NodeMap<bool> todo(G,false);
218 for( G.first(v); G.valid(v); G.next(v)) {
219 if ( mate[v]!=INVALID ) todo.set(v,true);
223 for( G.first(e); G.valid(e); G.next(e)) {
225 if ( todo[G.target(e)] && todo[G.source(e)] ) {
228 if ( mate[u]=v && mate[v]=u ) {
237 ///Writes the canonical decomposition of the graph after running
240 ///After calling any run methods of the class, and before calling
241 ///\ref resetPos(), it writes the Gallai-Edmonds canonical
242 ///decomposition of the graph. \c map must be a node map
243 ///of \ref pos_enum 's.
244 template<typename NMapEnum>
245 void writePos (NMapEnum& map) const {
247 for( G.first(v); G.valid(v); G.next(v)) map.set(v,position[v]);
252 void lateShrink(Node v, typename Graph::template NodeMap<Node>& ear,
253 UFE& blossom, UFE& tree);
255 void normShrink(Node v, typename Graph::NodeMap<Node>& ear,
256 UFE& blossom, UFE& tree);
258 bool noShrinkStep(Node x, typename Graph::NodeMap<Node>& ear,
259 UFE& blossom, UFE& tree, std::queue<Node>& Q);
261 void shrinkStep(Node& top, Node& middle, Node& bottom, typename Graph::NodeMap<Node>& ear,
262 UFE& blossom, UFE& tree, std::queue<Node>& Q);
264 void augment(Node x, typename Graph::NodeMap<Node>& ear,
265 UFE& blossom, UFE& tree);
270 // **********************************************************************
272 // **********************************************************************
275 template <typename Graph>
276 void MaxMatching<Graph>::run() {
277 if ( G.edgeNum() > 2*G.nodeNum() ) {
280 } else runEdmonds(0);
283 template <typename Graph>
284 void MaxMatching<Graph>::runEdmonds( int heur=1 ) {
286 typename Graph::template NodeMap<Node> ear(G,INVALID);
287 //undefined for the base nodes of the blossoms (i.e. for the
288 //representative elements of UFE blossom) and for the nodes in C
290 typename UFE::MapType blossom_base(G);
291 UFE blossom(blossom_base);
292 typename UFE::MapType tree_base(G);
296 for( G.first(v); G.valid(v); G.next(v) ) {
297 if ( position[v]==C && mate[v]==INVALID ) {
301 if ( heur == 1 ) lateShrink( v, ear, blossom, tree );
302 else normShrink( v, ear, blossom, tree );
307 template <typename Graph>
308 void MaxMatching<Graph>::lateShrink(Node v, typename Graph::template NodeMap<Node>& ear,
309 UFE& blossom, UFE& tree) {
311 std::queue<Node> Q; //queue of the totally unscanned nodes
314 //queue of the nodes which must be scanned for a possible shrink
316 while ( !Q.empty() ) {
319 if ( noShrinkStep( x, ear, blossom, tree, Q ) ) return;
323 while ( !R.empty() ) {
328 for( G.first(e,x); G.valid(e); G.next(e) ) {
331 if ( position[y] == D && blossom.find(x) != blossom.find(y) ) {
332 //x and y must be in the same tree
334 typename Graph::template NodeMap<bool> path(G,false);
336 Node b=blossom.find(x);
339 while ( b!=INVALID ) {
340 b=blossom.find(ear[b]);
343 } //going till the root
346 Node middle=blossom.find(top);
348 while ( !path[middle] )
349 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
353 middle=blossom.find(top);
355 Node blossom_base=blossom.find(base);
356 while ( middle!=blossom_base )
357 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
359 blossom.makeRep(base);
360 } // if shrink is needed
362 while ( !Q.empty() ) {
365 if ( noShrinkStep(x, ear, blossom, tree, Q) ) return;
369 } // while ( !R.empty() )
372 template <typename Graph>
373 void MaxMatching<Graph>::normShrink(Node v, typename Graph::NodeMap<Node>& ear,
374 UFE& blossom, UFE& tree) {
376 std::queue<Node> Q; //queue of the unscanned nodes
378 while ( !Q.empty() ) {
383 for( G.first(e,x); G.valid(e); G.next(e) ) {
386 switch ( position[y] ) {
387 case D: //x and y must be in the same tree
388 if ( blossom.find(x) != blossom.find(y) ) { //shrink
389 typename Graph::template NodeMap<bool> path(G,false);
391 Node b=blossom.find(x);
394 while ( b!=INVALID ) {
395 b=blossom.find(ear[b]);
398 } //going till the root
401 Node middle=blossom.find(top);
403 while ( !path[middle] )
404 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
408 middle=blossom.find(top);
410 Node blossom_base=blossom.find(base);
411 while ( middle!=blossom_base )
412 shrinkStep(top, middle, bottom, ear, blossom, tree, Q);
414 blossom.makeRep(base);
418 if ( mate[y]!=INVALID ) { //grow
426 tree.join(y,blossom.find(x));
430 augment(x, ear, blossom, tree);
442 template <typename Graph>
443 void MaxMatching<Graph>::greedyMatching() {
445 for( G.first(v); G.valid(v); G.next(v) )
446 if ( mate[v]==INVALID ) {
448 for( G.first(e,v); G.valid(e); G.next(e) ) {
450 if ( mate[y]==INVALID && y!=v ) {
459 template <typename Graph>
460 int MaxMatching<Graph>::size() const {
463 for(G.first(v); G.valid(v); G.next(v) ) {
464 if ( G.valid(mate[v]) ) {
471 template <typename Graph>
472 void MaxMatching<Graph>::resetPos() {
474 for( G.first(v); G.valid(v); G.next(v))
478 template <typename Graph>
479 void MaxMatching<Graph>::resetMatching() {
481 for( G.first(v); G.valid(v); G.next(v))
485 template <typename Graph>
486 bool MaxMatching<Graph>::noShrinkStep(Node x, typename Graph::NodeMap<Node>& ear,
487 UFE& blossom, UFE& tree, std::queue<Node>& Q) {
489 for( G.first(e,x); G.valid(e); G.next(e) ) {
492 if ( position[y]==C ) {
493 if ( mate[y]!=INVALID ) { //grow
501 tree.join(y,blossom.find(x));
505 augment(x, ear, blossom, tree);
515 template <typename Graph>
516 void MaxMatching<Graph>::shrinkStep(Node& top, Node& middle, Node& bottom, typename Graph::NodeMap<Node>& ear,
517 UFE& blossom, UFE& tree, std::queue<Node>& Q) {
520 while ( t!=middle ) {
526 position.set(bottom,D);
529 Node oldmiddle=middle;
530 middle=blossom.find(top);
532 tree.erase(oldmiddle);
533 blossom.insert(bottom);
534 blossom.join(bottom, oldmiddle);
535 blossom.join(top, oldmiddle);
538 template <typename Graph>
539 void MaxMatching<Graph>::augment(Node x, typename Graph::NodeMap<Node>& ear,
540 UFE& blossom, UFE& tree) {
542 while ( G.valid(v) ) {
550 typename UFE::ItemIt it;
551 for (tree.first(it,blossom.find(x)); tree.valid(it); tree.next(it)) {
552 if ( position[it] == D ) {
553 typename UFE::ItemIt b_it;
554 for (blossom.first(b_it,it); blossom.valid(b_it); blossom.next(b_it)) {
555 position.set( b_it ,C);
557 blossom.eraseClass(it);
558 } else position.set( it ,C);
567 } //END OF NAMESPACE LEMON