2 * lemon/min_cut.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_MIN_CUT_H
18 #define LEMON_MIN_CUT_H
23 /// \brief Maximum cardinality search and min cut in undirected graphs.
25 #include <lemon/list_graph.h>
26 #include <lemon/list_ugraph.h>
27 #include <lemon/bin_heap.h>
28 #include <lemon/bucket_heap.h>
30 #include <lemon/bits/invalid.h>
31 #include <lemon/error.h>
32 #include <lemon/maps.h>
38 namespace _min_cut_bits {
40 template <typename CapacityMap>
42 template <typename Key, typename Value, typename Ref>
44 typedef BinHeap<Key, Value, Ref, std::greater<Value> > Heap;
48 template <typename CapacityKey>
49 struct HeapSelector<ConstMap<CapacityKey, Const<int, 1> > > {
50 template <typename Key, typename Value, typename Ref>
52 typedef BucketHeap<Key, Ref, false > Heap;
58 /// \brief Default traits class of MaxCardinalitySearch class.
60 /// Default traits class of MaxCardinalitySearch class.
61 /// \param Graph Graph type.
62 /// \param CapacityMap Type of length map.
63 template <typename _Graph, typename _CapacityMap>
64 struct MaxCardinalitySearchDefaultTraits {
65 /// The graph type the algorithm runs on.
68 /// \brief The type of the map that stores the edge capacities.
70 /// The type of the map that stores the edge capacities.
71 /// It must meet the \ref concept::ReadMap "ReadMap" concept.
72 typedef _CapacityMap CapacityMap;
74 /// \brief The type of the capacity of the edges.
75 typedef typename CapacityMap::Value Value;
77 /// \brief The cross reference type used by heap.
79 /// The cross reference type used by heap.
80 /// Usually it is \c Graph::NodeMap<int>.
81 typedef typename Graph::template NodeMap<int> HeapCrossRef;
83 /// \brief Instantiates a HeapCrossRef.
85 /// This function instantiates a \ref HeapCrossRef.
86 /// \param graph is the graph, to which we would like to define the
88 static HeapCrossRef *createHeapCrossRef(const Graph &graph) {
89 return new HeapCrossRef(graph);
92 /// \brief The heap type used by MaxCardinalitySearch algorithm.
94 /// The heap type used by MaxCardinalitySearch algorithm. It should
95 /// maximalize the priorities. The default heap type is
96 /// the \ref BinHeap, but it is specialized when the
97 /// CapacityMap is ConstMap<Graph::Node, Const<int, 1> >
100 /// \sa MaxCardinalitySearch
101 typedef typename _min_cut_bits
102 ::HeapSelector<CapacityMap>
103 ::template Selector<typename Graph::Node, Value, HeapCrossRef>
106 /// \brief Instantiates a Heap.
108 /// This function instantiates a \ref Heap.
109 /// \param crossref The cross reference of the heap.
110 static Heap *createHeap(HeapCrossRef& crossref) {
111 return new Heap(crossref);
114 /// \brief The type of the map that stores whether a nodes is processed.
116 /// The type of the map that stores whether a nodes is processed.
117 /// It must meet the \ref concept::WriteMap "WriteMap" concept.
118 /// By default it is a NullMap.
119 typedef NullMap<typename Graph::Node, bool> ProcessedMap;
121 /// \brief Instantiates a ProcessedMap.
123 /// This function instantiates a \ref ProcessedMap.
124 /// \param graph is the graph, to which
125 /// we would like to define the \ref ProcessedMap
127 static ProcessedMap *createProcessedMap(const Graph &graph)
129 static ProcessedMap *createProcessedMap(const Graph &)
132 return new ProcessedMap();
135 /// \brief The type of the map that stores the cardinalties of the nodes.
137 /// The type of the map that stores the cardinalities of the nodes.
138 /// It must meet the \ref concept::WriteMap "WriteMap" concept.
139 typedef typename Graph::template NodeMap<Value> CardinalityMap;
141 /// \brief Instantiates a CardinalityMap.
143 /// This function instantiates a \ref CardinalityMap.
144 /// \param graph is the graph, to which we would like to define the \ref
146 static CardinalityMap *createCardinalityMap(const Graph &graph) {
147 return new CardinalityMap(graph);
152 /// \ingroup topology
154 /// \brief Maximum Cardinality Search algorithm class.
156 /// This class provides an efficient implementation of Maximum Cardinality
157 /// Search algorithm. The maximum cardinality search chooses first time any
158 /// node of the graph. Then every time it chooses the node which is connected
159 /// to the processed nodes at most in the sum of capacities on the out
160 /// edges. If there is a cut in the graph the algorithm should choose
161 /// again any unprocessed node of the graph. Each node cardinality is
162 /// the sum of capacities on the out edges to the nodes which are processed
163 /// before the given node.
165 /// The edge capacities are passed to the algorithm using a
166 /// \ref concept::ReadMap "ReadMap", so it is easy to change it to any
167 /// kind of capacity.
169 /// The type of the capacity is determined by the \ref
170 /// concept::ReadMap::Value "Value" of the capacity map.
172 /// It is also possible to change the underlying priority heap.
175 /// \param _Graph The graph type the algorithm runs on. The default value
176 /// is \ref ListGraph. The value of Graph is not used directly by
177 /// the search algorithm, it is only passed to
178 /// \ref MaxCardinalitySearchDefaultTraits.
179 /// \param _CapacityMap This read-only EdgeMap determines the capacities of
180 /// the edges. It is read once for each edge, so the map may involve in
181 /// relatively time consuming process to compute the edge capacity if
182 /// it is necessary. The default map type is \ref
183 /// concept::Graph::EdgeMap "Graph::EdgeMap<int>". The value
184 /// of CapacityMap is not used directly by search algorithm, it is only
185 /// passed to \ref MaxCardinalitySearchDefaultTraits.
186 /// \param _Traits Traits class to set various data types used by the
187 /// algorithm. The default traits class is
188 /// \ref MaxCardinalitySearchDefaultTraits
189 /// "MaxCardinalitySearchDefaultTraits<_Graph, _CapacityMap>".
190 /// See \ref MaxCardinalitySearchDefaultTraits
191 /// for the documentation of a MaxCardinalitySearch traits class.
193 /// \author Balazs Dezso
196 template <typename _Graph, typename _CapacityMap, typename _Traits>
198 template <typename _Graph = ListGraph,
199 typename _CapacityMap = typename _Graph::template EdgeMap<int>,
201 MaxCardinalitySearchDefaultTraits<_Graph, _CapacityMap> >
203 class MaxCardinalitySearch {
205 /// \brief \ref Exception for uninitialized parameters.
207 /// This error represents problems in the initialization
208 /// of the parameters of the algorithms.
209 class UninitializedParameter : public lemon::UninitializedParameter {
211 virtual const char* exceptionName() const {
212 return "lemon::MaxCardinalitySearch::UninitializedParameter";
216 typedef _Traits Traits;
217 ///The type of the underlying graph.
218 typedef typename Traits::Graph Graph;
220 ///The type of the capacity of the edges.
221 typedef typename Traits::CapacityMap::Value Value;
222 ///The type of the map that stores the edge capacities.
223 typedef typename Traits::CapacityMap CapacityMap;
224 ///The type of the map indicating if a node is processed.
225 typedef typename Traits::ProcessedMap ProcessedMap;
226 ///The type of the map that stores the cardinalities of the nodes.
227 typedef typename Traits::CardinalityMap CardinalityMap;
228 ///The cross reference type used for the current heap.
229 typedef typename Traits::HeapCrossRef HeapCrossRef;
230 ///The heap type used by the algorithm. It maximize the priorities.
231 typedef typename Traits::Heap Heap;
233 /// Pointer to the underlying graph.
235 /// Pointer to the capacity map
236 const CapacityMap *_capacity;
237 ///Pointer to the map of cardinality.
238 CardinalityMap *_cardinality;
239 ///Indicates if \ref _cardinality is locally allocated (\c true) or not.
240 bool local_cardinality;
241 ///Pointer to the map of processed status of the nodes.
242 ProcessedMap *_processed;
243 ///Indicates if \ref _processed is locally allocated (\c true) or not.
244 bool local_processed;
245 ///Pointer to the heap cross references.
246 HeapCrossRef *_heap_cross_ref;
247 ///Indicates if \ref _heap_cross_ref is locally allocated (\c true) or not.
248 bool local_heap_cross_ref;
249 ///Pointer to the heap.
251 ///Indicates if \ref _heap is locally allocated (\c true) or not.
256 typedef MaxCardinalitySearch Create;
258 ///\name Named template parameters
263 struct DefCardinalityMapTraits : public Traits {
264 typedef T CardinalityMap;
265 static CardinalityMap *createCardinalityMap(const Graph &)
267 throw UninitializedParameter();
270 /// \brief \ref named-templ-param "Named parameter" for setting
271 /// CardinalityMap type
273 /// \ref named-templ-param "Named parameter" for setting CardinalityMap
276 struct DefCardinalityMap
277 : public MaxCardinalitySearch<Graph, CapacityMap,
278 DefCardinalityMapTraits<T> > {
279 typedef MaxCardinalitySearch<Graph, CapacityMap,
280 DefCardinalityMapTraits<T> > Create;
284 struct DefProcessedMapTraits : public Traits {
285 typedef T ProcessedMap;
286 static ProcessedMap *createProcessedMap(const Graph &) {
287 throw UninitializedParameter();
290 /// \brief \ref named-templ-param "Named parameter" for setting
291 /// ProcessedMap type
293 /// \ref named-templ-param "Named parameter" for setting ProcessedMap type
296 struct DefProcessedMap
297 : public MaxCardinalitySearch<Graph, CapacityMap,
298 DefProcessedMapTraits<T> > {
299 typedef MaxCardinalitySearch<Graph, CapacityMap,
300 DefProcessedMapTraits<T> > Create;
303 template <class H, class CR>
304 struct DefHeapTraits : public Traits {
305 typedef CR HeapCrossRef;
307 static HeapCrossRef *createHeapCrossRef(const Graph &) {
308 throw UninitializedParameter();
310 static Heap *createHeap(HeapCrossRef &) {
311 throw UninitializedParameter();
314 /// \brief \ref named-templ-param "Named parameter" for setting heap
315 /// and cross reference type
317 /// \ref named-templ-param "Named parameter" for setting heap and cross
319 template <class H, class CR = typename Graph::template NodeMap<int> >
321 : public MaxCardinalitySearch<Graph, CapacityMap,
322 DefHeapTraits<H, CR> > {
323 typedef MaxCardinalitySearch< Graph, CapacityMap,
324 DefHeapTraits<H, CR> > Create;
327 template <class H, class CR>
328 struct DefStandardHeapTraits : public Traits {
329 typedef CR HeapCrossRef;
331 static HeapCrossRef *createHeapCrossRef(const Graph &graph) {
332 return new HeapCrossRef(graph);
334 static Heap *createHeap(HeapCrossRef &crossref) {
335 return new Heap(crossref);
339 /// \brief \ref named-templ-param "Named parameter" for setting heap and
340 /// cross reference type with automatic allocation
342 /// \ref named-templ-param "Named parameter" for setting heap and cross
343 /// reference type. It can allocate the heap and the cross reference
344 /// object if the cross reference's constructor waits for the graph as
345 /// parameter and the heap's constructor waits for the cross reference.
346 template <class H, class CR = typename Graph::template NodeMap<int> >
347 struct DefStandardHeap
348 : public MaxCardinalitySearch<Graph, CapacityMap,
349 DefStandardHeapTraits<H, CR> > {
350 typedef MaxCardinalitySearch<Graph, CapacityMap,
351 DefStandardHeapTraits<H, CR> >
360 MaxCardinalitySearch() {}
364 /// \brief Constructor.
366 ///\param graph the graph the algorithm will run on.
367 ///\param capacity the capacity map used by the algorithm.
368 MaxCardinalitySearch(const Graph& graph, const CapacityMap& capacity) :
369 _graph(&graph), _capacity(&capacity),
370 _cardinality(0), local_cardinality(false),
371 _processed(0), local_processed(false),
372 _heap_cross_ref(0), local_heap_cross_ref(false),
373 _heap(0), local_heap(false)
376 /// \brief Destructor.
377 ~MaxCardinalitySearch() {
378 if(local_cardinality) delete _cardinality;
379 if(local_processed) delete _processed;
380 if(local_heap_cross_ref) delete _heap_cross_ref;
381 if(local_heap) delete _heap;
384 /// \brief Sets the capacity map.
386 /// Sets the capacity map.
387 /// \return <tt> (*this) </tt>
388 MaxCardinalitySearch &capacityMap(const CapacityMap &m) {
393 /// \brief Sets the map storing the cardinalities calculated by the
396 /// Sets the map storing the cardinalities calculated by the algorithm.
397 /// If you don't use this function before calling \ref run(),
398 /// it will allocate one. The destuctor deallocates this
399 /// automatically allocated map, of course.
400 /// \return <tt> (*this) </tt>
401 MaxCardinalitySearch &cardinalityMap(CardinalityMap &m) {
402 if(local_cardinality) {
404 local_cardinality=false;
410 /// \brief Sets the map storing the processed nodes.
412 /// Sets the map storing the processed nodes.
413 /// If you don't use this function before calling \ref run(),
414 /// it will allocate one. The destuctor deallocates this
415 /// automatically allocated map, of course.
416 /// \return <tt> (*this) </tt>
417 MaxCardinalitySearch &processedMap(ProcessedMap &m)
419 if(local_processed) {
421 local_processed=false;
427 /// \brief Sets the heap and the cross reference used by algorithm.
429 /// Sets the heap and the cross reference used by algorithm.
430 /// If you don't use this function before calling \ref run(),
431 /// it will allocate one. The destuctor deallocates this
432 /// automatically allocated map, of course.
433 /// \return <tt> (*this) </tt>
434 MaxCardinalitySearch &heap(Heap& heap, HeapCrossRef &crossRef) {
435 if(local_heap_cross_ref) {
436 delete _heap_cross_ref;
437 local_heap_cross_ref = false;
439 _heap_cross_ref = &crossRef;
450 typedef typename Graph::Node Node;
451 typedef typename Graph::NodeIt NodeIt;
452 typedef typename Graph::Edge Edge;
453 typedef typename Graph::InEdgeIt InEdgeIt;
457 local_cardinality = true;
458 _cardinality = Traits::createCardinalityMap(*_graph);
461 local_processed = true;
462 _processed = Traits::createProcessedMap(*_graph);
464 if (!_heap_cross_ref) {
465 local_heap_cross_ref = true;
466 _heap_cross_ref = Traits::createHeapCrossRef(*_graph);
470 _heap = Traits::createHeap(*_heap_cross_ref);
474 void finalizeNodeData(Node node, Value capacity) {
475 _processed->set(node, true);
476 _cardinality->set(node, capacity);
480 /// \name Execution control
481 /// The simplest way to execute the algorithm is to use
482 /// one of the member functions called \c run(...).
484 /// If you need more control on the execution,
485 /// first you must call \ref init(), then you can add several source nodes
486 /// with \ref addSource().
487 /// Finally \ref start() will perform the actual path
492 /// \brief Initializes the internal data structures.
494 /// Initializes the internal data structures.
498 for (NodeIt it(*_graph) ; it != INVALID ; ++it) {
499 _processed->set(it, false);
500 _heap_cross_ref->set(it, Heap::PRE_HEAP);
504 /// \brief Adds a new source node.
506 /// Adds a new source node to the priority heap.
508 /// It checks if the node has not yet been added to the heap.
509 void addSource(Node source, Value capacity = 0) {
510 if(_heap->state(source) == Heap::PRE_HEAP) {
511 _heap->push(source, capacity);
515 /// \brief Processes the next node in the priority heap
517 /// Processes the next node in the priority heap.
519 /// \return The processed node.
521 /// \warning The priority heap must not be empty!
522 Node processNextNode() {
523 Node node = _heap->top();
524 finalizeNodeData(node, _heap->prio());
527 for (InEdgeIt it(*_graph, node); it != INVALID; ++it) {
528 Node source = _graph->source(it);
529 switch (_heap->state(source)) {
531 _heap->push(source, (*_capacity)[it]);
534 _heap->decrease(source, (*_heap)[source] + (*_capacity)[it]);
536 case Heap::POST_HEAP:
543 /// \brief Next node to be processed.
545 /// Next node to be processed.
547 /// \return The next node to be processed or INVALID if the
548 /// priority heap is empty.
550 return _heap->empty() ? _heap->top() : INVALID;
553 /// \brief Returns \c false if there are nodes
554 /// to be processed in the priority heap
556 /// Returns \c false if there are nodes
557 /// to be processed in the priority heap
558 bool emptyQueue() { return _heap->empty(); }
559 /// \brief Returns the number of the nodes to be processed
560 /// in the priority heap
562 /// Returns the number of the nodes to be processed in the priority heap
563 int queueSize() { return _heap->size(); }
565 /// \brief Executes the algorithm.
567 /// Executes the algorithm.
569 ///\pre init() must be called and at least one node should be added
570 /// with addSource() before using this function.
572 /// This method runs the Maximum Cardinality Search algorithm from the
575 while ( !_heap->empty() ) processNextNode();
578 /// \brief Executes the algorithm until \c dest is reached.
580 /// Executes the algorithm until \c dest is reached.
582 /// \pre init() must be called and at least one node should be added
583 /// with addSource() before using this function.
585 /// This method runs the %MaxCardinalitySearch algorithm from the source
587 void start(Node dest) {
588 while ( !_heap->empty() && _heap->top()!=dest ) processNextNode();
589 if ( !_heap->empty() ) finalizeNodeData(_heap->top(), _heap->prio());
592 /// \brief Executes the algorithm until a condition is met.
594 /// Executes the algorithm until a condition is met.
596 /// \pre init() must be called and at least one node should be added
597 /// with addSource() before using this function.
599 /// \param nm must be a bool (or convertible) node map. The algorithm
600 /// will stop when it reaches a node \c v with <tt>nm[v]==true</tt>.
601 template <typename NodeBoolMap>
602 void start(const NodeBoolMap &nm) {
603 while ( !_heap->empty() && !nm[_heap->top()] ) processNextNode();
604 if ( !_heap->empty() ) finalizeNodeData(_heap->top(),_heap->prio());
607 /// \brief Runs the maximal cardinality search algorithm from node \c s.
609 /// This method runs the %MaxCardinalitySearch algorithm from a root
612 ///\note d.run(s) is just a shortcut of the following code.
624 /// \brief Runs the maximal cardinality search algorithm for the
627 /// This method runs the %MaxCardinalitySearch algorithm from all
628 /// unprocessed node of the graph.
630 ///\note d.run(s) is just a shortcut of the following code.
633 /// for (NodeIt it(graph); it != INVALID; ++it) {
634 /// if (!d.reached(it)) {
642 for (NodeIt it(*_graph); it != INVALID; ++it) {
652 /// \name Query Functions
653 /// The result of the maximum cardinality search algorithm can be
654 /// obtained using these functions.
656 /// Before the use of these functions, either run() or start() must be
661 /// \brief The cardinality of a node.
663 /// Returns the cardinality of a node.
664 /// \pre \ref run() must be called before using this function.
665 /// \warning If node \c v in unreachable from the root the return value
666 /// of this funcion is undefined.
667 Value cardinality(Node node) const { return (*_cardinality)[node]; }
669 /// \brief Returns a reference to the NodeMap of cardinalities.
671 /// Returns a reference to the NodeMap of cardinalities. \pre \ref run()
672 /// must be called before using this function.
673 const CardinalityMap &cardinalityMap() const { return *_cardinality;}
675 /// \brief Checks if a node is reachable from the root.
677 /// Returns \c true if \c v is reachable from the root.
678 /// \warning The source nodes are inditated as unreached.
679 /// \pre \ref run() must be called before using this function.
680 bool reached(Node v) { return (*_heap_cross_ref)[v] != Heap::PRE_HEAP; }
682 /// \brief Checks if a node is processed.
684 /// Returns \c true if \c v is processed, i.e. the shortest
685 /// path to \c v has already found.
686 /// \pre \ref run() must be called before using this function.
687 bool processed(Node v) { return (*_heap_cross_ref)[v] == Heap::POST_HEAP; }
692 /// \brief Default traits class of MinCut class.
694 /// Default traits class of MinCut class.
695 /// \param Graph Graph type.
696 /// \param CapacityMap Type of length map.
697 template <typename _Graph, typename _CapacityMap>
698 struct MinCutDefaultTraits {
699 /// \brief The type of the capacity of the edges.
700 typedef typename _CapacityMap::Value Value;
702 /// The graph type the algorithm runs on.
703 typedef _Graph Graph;
705 /// The AuxGraph type which is an Graph
706 typedef ListUGraph AuxGraph;
708 /// \brief Instantiates a AuxGraph.
710 /// This function instantiates a \ref AuxGraph.
711 static AuxGraph *createAuxGraph() {
712 return new AuxGraph();
715 /// \brief The type of the map that stores the edge capacities.
717 /// The type of the map that stores the edge capacities.
718 /// It must meet the \ref concept::ReadMap "ReadMap" concept.
719 typedef _CapacityMap CapacityMap;
721 /// \brief Instantiates a CapacityMap.
723 /// This function instantiates a \ref CapacityMap.
725 static CapacityMap *createCapacityMap(const Graph& graph)
727 static CapacityMap *createCapacityMap(const Graph&)
730 throw UninitializedParameter();
733 /// \brief The AuxCapacityMap type
735 /// The type of the map that stores the auxing edge capacities.
736 typedef AuxGraph::UEdgeMap<Value> AuxCapacityMap;
738 /// \brief Instantiates a AuxCapacityMap.
740 /// This function instantiates a \ref AuxCapacityMap.
741 static AuxCapacityMap *createAuxCapacityMap(const AuxGraph& graph) {
742 return new AuxCapacityMap(graph);
745 /// \brief The cross reference type used by heap.
747 /// The cross reference type used by heap.
748 /// Usually it is \c Graph::NodeMap<int>.
749 typedef AuxGraph::NodeMap<int> HeapCrossRef;
751 /// \brief Instantiates a HeapCrossRef.
753 /// This function instantiates a \ref HeapCrossRef.
754 /// \param graph is the graph, to which we would like to define the
756 static HeapCrossRef *createHeapCrossRef(const AuxGraph &graph) {
757 return new HeapCrossRef(graph);
760 /// \brief The heap type used by MinCut algorithm.
762 /// The heap type used by MinCut algorithm. It should
763 /// maximalize the priorities and the heap's key type is
764 /// the aux graph's node.
768 typedef typename _min_cut_bits
769 ::HeapSelector<CapacityMap>
770 ::template Selector<typename AuxGraph::Node, Value, HeapCrossRef>
773 /// \brief Instantiates a Heap.
775 /// This function instantiates a \ref Heap.
776 /// \param crossref The cross reference of the heap.
777 static Heap *createHeap(HeapCrossRef& crossref) {
778 return new Heap(crossref);
781 /// \brief Map from the AuxGraph's node type to the Graph's node type.
783 /// Map from the AuxGraph's node type to the Graph's node type.
784 typedef typename AuxGraph
785 ::template NodeMap<typename Graph::Node> NodeRefMap;
787 /// \brief Instantiates a NodeRefMap.
789 /// This function instantiates a \ref NodeRefMap.
790 static NodeRefMap *createNodeRefMap(const AuxGraph& graph) {
791 return new NodeRefMap(graph);
794 /// \brief Map from the Graph's node type to the Graph's node type.
796 /// Map from the Graph's node type to the Graph's node type.
797 typedef typename Graph
798 ::template NodeMap<typename Graph::Node> ListRefMap;
800 /// \brief Instantiates a ListRefMap.
802 /// This function instantiates a \ref ListRefMap.
803 static ListRefMap *createListRefMap(const Graph& graph) {
804 return new ListRefMap(graph);
810 namespace _min_cut_bits {
811 template <typename _Key>
817 LastTwoMap(int _num) : num(_num) {}
818 void set(const Key& key, bool val) {
825 Key operator[](int index) const { return keys[index]; }
832 /// \ingroup topology
834 /// \brief Calculates the min cut in an undirected graph.
836 /// Calculates the min cut in an undirected graph.
837 /// The algorithm separates the graph's nodes to two partitions with the
838 /// min sum of edge capacities between the two partitions. The
839 /// algorithm can be used to test the netaux reliability specifically
840 /// to test how many links have to be destroyed in the netaux to split it
841 /// at least two distinict subnetaux.
843 /// The complexity of the algorithm is \f$ O(ne\log(n)) \f$ but with
844 /// Fibonacci heap it can be decreased to \f$ O(ne+n^2\log(n)) \f$. When
845 /// the neutral capacity map is used then it uses BucketHeap which
846 /// results \f$ O(ne) \f$ time complexity.
848 template <typename _Graph, typename _CapacityMap, typename _Traits>
850 template <typename _Graph = ListUGraph,
851 typename _CapacityMap = typename _Graph::template UEdgeMap<int>,
852 typename _Traits = MinCutDefaultTraits<_Graph, _CapacityMap> >
856 /// \brief \ref Exception for uninitialized parameters.
858 /// This error represents problems in the initialization
859 /// of the parameters of the algorithms.
860 class UninitializedParameter : public lemon::UninitializedParameter {
862 virtual const char* exceptionName() const {
863 return "lemon::MinCut::UninitializedParameter";
870 typedef _Traits Traits;
871 /// The type of the underlying graph.
872 typedef typename Traits::Graph Graph;
874 /// The type of the capacity of the edges.
875 typedef typename Traits::CapacityMap::Value Value;
876 /// The type of the map that stores the edge capacities.
877 typedef typename Traits::CapacityMap CapacityMap;
878 /// The type of the aux graph
879 typedef typename Traits::AuxGraph AuxGraph;
880 /// The type of the aux capacity map
881 typedef typename Traits::AuxCapacityMap AuxCapacityMap;
882 /// The cross reference type used for the current heap.
883 typedef typename Traits::HeapCrossRef HeapCrossRef;
884 /// The heap type used by the max cardinality algorithm.
885 typedef typename Traits::Heap Heap;
886 /// The node refrefernces between the original and aux graph type.
887 typedef typename Traits::NodeRefMap NodeRefMap;
888 /// The list node refrefernces in the original graph type.
889 typedef typename Traits::ListRefMap ListRefMap;
893 ///\name Named template parameters
897 struct DefNeutralCapacityTraits : public Traits {
898 typedef ConstMap<typename Graph::UEdge, Const<int, 1> > CapacityMap;
899 static CapacityMap *createCapacityMap(const Graph&) {
900 return new CapacityMap();
903 /// \brief \ref named-templ-param "Named parameter" for setting
904 /// the capacity type to constMap<UEdge, int, 1>()
906 /// \ref named-templ-param "Named parameter" for setting
907 /// the capacity type to constMap<UEdge, int, 1>()
908 struct DefNeutralCapacity
909 : public MinCut<Graph, CapacityMap, DefNeutralCapacityTraits> {
910 typedef MinCut<Graph, CapacityMap, DefNeutralCapacityTraits> Create;
914 template <class H, class CR>
915 struct DefHeapTraits : public Traits {
916 typedef CR HeapCrossRef;
918 static HeapCrossRef *createHeapCrossRef(const AuxGraph &) {
919 throw UninitializedParameter();
921 static Heap *createHeap(HeapCrossRef &) {
922 throw UninitializedParameter();
925 /// \brief \ref named-templ-param "Named parameter" for setting heap
926 /// and cross reference type
928 /// \ref named-templ-param "Named parameter" for setting heap and cross
930 template <class H, class CR = typename Graph::template NodeMap<int> >
932 : public MinCut<Graph, CapacityMap, DefHeapTraits<H, CR> > {
933 typedef MinCut< Graph, CapacityMap, DefHeapTraits<H, CR> > Create;
936 template <class H, class CR>
937 struct DefStandardHeapTraits : public Traits {
938 typedef CR HeapCrossRef;
940 static HeapCrossRef *createHeapCrossRef(const AuxGraph &graph) {
941 return new HeapCrossRef(graph);
943 static Heap *createHeap(HeapCrossRef &crossref) {
944 return new Heap(crossref);
948 /// \brief \ref named-templ-param "Named parameter" for setting heap and
949 /// cross reference type with automatic allocation
951 /// \ref named-templ-param "Named parameter" for setting heap and cross
952 /// reference type. It can allocate the heap and the cross reference
953 /// object if the cross reference's constructor waits for the graph as
954 /// parameter and the heap's constructor waits for the cross reference.
955 template <class H, class CR = typename Graph::template NodeMap<int> >
956 struct DefStandardHeap
957 : public MinCut<Graph, CapacityMap, DefStandardHeapTraits<H, CR> > {
958 typedef MinCut<Graph, CapacityMap, DefStandardHeapTraits<H, CR> >
966 /// Pointer to the underlying graph.
968 /// Pointer to the capacity map
969 const CapacityMap *_capacity;
970 /// \brief Indicates if \ref _capacity is locally allocated
971 /// (\c true) or not.
974 /// Pointer to the aux graph.
975 AuxGraph *_aux_graph;
976 /// \brief Indicates if \ref _aux_graph is locally allocated
977 /// (\c true) or not.
978 bool local_aux_graph;
979 /// Pointer to the aux capacity map
980 AuxCapacityMap *_aux_capacity;
981 /// \brief Indicates if \ref _aux_capacity is locally allocated
982 /// (\c true) or not.
983 bool local_aux_capacity;
984 /// Pointer to the heap cross references.
985 HeapCrossRef *_heap_cross_ref;
986 /// \brief Indicates if \ref _heap_cross_ref is locally allocated
987 /// (\c true) or not.
988 bool local_heap_cross_ref;
989 /// Pointer to the heap.
991 /// Indicates if \ref _heap is locally allocated (\c true) or not.
994 /// The min cut value.
996 /// The number of the nodes of the aux graph.
998 /// The first and last node of the min cut in the next list;
999 typename Graph::Node _first_node, _last_node;
1001 /// \brief The first and last element in the list associated
1002 /// to the aux graph node.
1003 NodeRefMap *_first, *_last;
1004 /// \brief The next node in the node lists.
1007 void create_structures() {
1009 local_capacity = true;
1010 _capacity = Traits::createCapacityMap(*_graph);
1013 local_aux_graph = true;
1014 _aux_graph = Traits::createAuxGraph();
1016 if(!_aux_capacity) {
1017 local_aux_capacity = true;
1018 _aux_capacity = Traits::createAuxCapacityMap(*_aux_graph);
1021 _first = Traits::createNodeRefMap(*_aux_graph);
1022 _last = Traits::createNodeRefMap(*_aux_graph);
1024 _next = Traits::createListRefMap(*_graph);
1026 typename Graph::template NodeMap<typename AuxGraph::Node> ref(*_graph);
1028 for (typename Graph::NodeIt it(*_graph); it != INVALID; ++it) {
1029 _next->set(it, INVALID);
1030 typename AuxGraph::Node node = _aux_graph->addNode();
1031 _first->set(node, it);
1032 _last->set(node, it);
1036 for (typename Graph::UEdgeIt it(*_graph); it != INVALID; ++it) {
1037 if (_graph->source(it) == _graph->target(it)) continue;
1038 typename AuxGraph::UEdge uedge =
1039 _aux_graph->addEdge(ref[_graph->source(it)],
1040 ref[_graph->target(it)]);
1041 _aux_capacity->set(uedge, (*_capacity)[it]);
1045 if (!_heap_cross_ref) {
1046 local_heap_cross_ref = true;
1047 _heap_cross_ref = Traits::createHeapCrossRef(*_aux_graph);
1051 _heap = Traits::createHeap(*_heap_cross_ref);
1057 typedef MinCut Create;
1060 /// \brief Constructor.
1062 ///\param graph the graph the algorithm will run on.
1063 ///\param capacity the capacity map used by the algorithm.
1064 MinCut(const Graph& graph, const CapacityMap& capacity)
1066 _capacity(&capacity), local_capacity(false),
1067 _aux_graph(0), local_aux_graph(false),
1068 _aux_capacity(0), local_aux_capacity(false),
1069 _heap_cross_ref(0), local_heap_cross_ref(false),
1070 _heap(0), local_heap(false),
1071 _first(0), _last(0), _next(0) {}
1073 /// \brief Constructor.
1075 /// This constructor can be used only when the Traits class
1076 /// defines how can we instantiate a local capacity map.
1077 /// If the DefNeutralCapacity used the algorithm automatically
1078 /// construct the capacity map.
1080 ///\param graph the graph the algorithm will run on.
1081 MinCut(const Graph& graph)
1083 _capacity(0), local_capacity(false),
1084 _aux_graph(0), local_aux_graph(false),
1085 _aux_capacity(0), local_aux_capacity(false),
1086 _heap_cross_ref(0), local_heap_cross_ref(false),
1087 _heap(0), local_heap(false),
1088 _first(0), _last(0), _next(0) {}
1090 /// \brief Destructor.
1094 if (local_heap) delete _heap;
1095 if (local_heap_cross_ref) delete _heap_cross_ref;
1096 if (_first) delete _first;
1097 if (_last) delete _last;
1098 if (_next) delete _next;
1099 if (local_aux_capacity) delete _aux_capacity;
1100 if (local_aux_graph) delete _aux_graph;
1101 if (local_capacity) delete _capacity;
1104 /// \brief Sets the heap and the cross reference used by algorithm.
1106 /// Sets the heap and the cross reference used by algorithm.
1107 /// If you don't use this function before calling \ref run(),
1108 /// it will allocate one. The destuctor deallocates this
1109 /// automatically allocated heap and cross reference, of course.
1110 /// \return <tt> (*this) </tt>
1111 MinCut &heap(Heap& heap, HeapCrossRef &crossRef)
1113 if (local_heap_cross_ref) {
1114 delete _heap_cross_ref;
1115 local_heap_cross_ref=false;
1117 _heap_cross_ref = &crossRef;
1126 /// \brief Sets the aux graph.
1128 /// Sets the aux graph used by algorithm.
1129 /// If you don't use this function before calling \ref run(),
1130 /// it will allocate one. The destuctor deallocates this
1131 /// automatically allocated graph, of course.
1132 /// \return <tt> (*this) </tt>
1133 MinCut &auxGraph(AuxGraph& aux_graph)
1135 if(local_aux_graph) {
1137 local_aux_graph=false;
1139 _aux_graph = &aux_graph;
1143 /// \brief Sets the aux capacity map.
1145 /// Sets the aux capacity map used by algorithm.
1146 /// If you don't use this function before calling \ref run(),
1147 /// it will allocate one. The destuctor deallocates this
1148 /// automatically allocated graph, of course.
1149 /// \return <tt> (*this) </tt>
1150 MinCut &auxCapacityMap(AuxCapacityMap& aux_capacity_map)
1152 if(local_aux_capacity) {
1153 delete _aux_capacity;
1154 local_aux_capacity=false;
1156 _aux_capacity = &aux_capacity_map;
1160 /// \name Execution control
1161 /// The simplest way to execute the algorithm is to use
1162 /// one of the member functions called \c run().
1164 /// If you need more control on the execution,
1165 /// first you must call \ref init() and then call the start()
1166 /// or proper times the processNextPhase() member functions.
1170 /// \brief Initializes the internal data structures.
1172 /// Initializes the internal data structures.
1174 create_structures();
1175 _first_node = _last_node = INVALID;
1176 _node_num = countNodes(*_graph);
1179 /// \brief Processes the next phase
1181 /// Processes the next phase in the algorithm. The function
1182 /// should be called countNodes(graph) - 1 times to get
1183 /// surely the min cut in the graph. The
1185 ///\return %True when the algorithm finished.
1186 bool processNextPhase() {
1187 if (_node_num <= 1) return true;
1188 using namespace _min_cut_bits;
1190 typedef typename AuxGraph::Node Node;
1191 typedef typename AuxGraph::NodeIt NodeIt;
1192 typedef typename AuxGraph::UEdge UEdge;
1193 typedef typename AuxGraph::IncEdgeIt IncEdgeIt;
1195 typedef typename MaxCardinalitySearch<AuxGraph, AuxCapacityMap>::
1196 template DefHeap<Heap, HeapCrossRef>::
1197 template DefCardinalityMap<NullMap<Node, Value> >::
1198 template DefProcessedMap<LastTwoMap<Node> >::
1199 Create MaxCardinalitySearch;
1201 MaxCardinalitySearch mcs(*_aux_graph, *_aux_capacity);
1202 for (NodeIt it(*_aux_graph); it != INVALID; ++it) {
1203 _heap_cross_ref->set(it, Heap::PRE_HEAP);
1205 mcs.heap(*_heap, *_heap_cross_ref);
1207 LastTwoMap<Node> last_two_nodes(_node_num);
1208 mcs.processedMap(last_two_nodes);
1210 NullMap<Node, Value> cardinality;
1211 mcs.cardinalityMap(cardinality);
1215 Node new_node = _aux_graph->addNode();
1217 typename AuxGraph::template NodeMap<UEdge> edges(*_aux_graph, INVALID);
1219 Node first_node = last_two_nodes[0];
1220 Node second_node = last_two_nodes[1];
1222 _next->set((*_last)[first_node], (*_first)[second_node]);
1223 _first->set(new_node, (*_first)[first_node]);
1224 _last->set(new_node, (*_last)[second_node]);
1226 Value current_cut = 0;
1227 for (IncEdgeIt it(*_aux_graph, first_node); it != INVALID; ++it) {
1228 Node node = _aux_graph->runningNode(it);
1229 current_cut += (*_aux_capacity)[it];
1230 if (node == second_node) continue;
1231 if (edges[node] == INVALID) {
1232 edges[node] = _aux_graph->addEdge(new_node, node);
1233 (*_aux_capacity)[edges[node]] = (*_aux_capacity)[it];
1235 (*_aux_capacity)[edges[node]] += (*_aux_capacity)[it];
1239 if (_first_node == INVALID || current_cut < _min_cut) {
1240 _first_node = (*_first)[first_node];
1241 _last_node = (*_last)[first_node];
1242 _min_cut = current_cut;
1245 _aux_graph->erase(first_node);
1247 for (IncEdgeIt it(*_aux_graph, second_node); it != INVALID; ++it) {
1248 Node node = _aux_graph->runningNode(it);
1249 if (edges[node] == INVALID) {
1250 edges[node] = _aux_graph->addEdge(new_node, node);
1251 (*_aux_capacity)[edges[node]] = (*_aux_capacity)[it];
1253 (*_aux_capacity)[edges[node]] += (*_aux_capacity)[it];
1256 _aux_graph->erase(second_node);
1259 return _node_num == 1;
1262 /// \brief Executes the algorithm.
1264 /// Executes the algorithm.
1266 /// \pre init() must be called
1268 while (!processNextPhase());
1272 /// \brief Runs %MinCut algorithm.
1274 /// This method runs the %Min cut algorithm
1276 /// \note mc.run(s) is just a shortcut of the following code.
1288 /// \name Query Functions
1289 /// The result of the %MinCut algorithm can be obtained using these
1291 /// Before the use of these functions,
1292 /// either run() or start() must be called.
1296 /// \brief Returns the min cut value.
1298 /// Returns the min cut value if the algorithm finished.
1299 /// After the first processNextPhase() it is a value of a
1300 /// valid cut in the graph.
1301 Value minCut() const {
1305 /// \brief Returns a min cut in a NodeMap.
1307 /// It sets the nodes of one of the two partitions to true in
1308 /// the given BoolNodeMap. The map contains a valid cut if the
1309 /// map have been set false previously.
1310 template <typename NodeMap>
1311 Value quickMinCut(NodeMap& nodeMap) const {
1312 for (typename Graph::Node it = _first_node;
1313 it != _last_node; it = (*_next)[it]) {
1314 nodeMap.set(it, true);
1316 nodeMap.set(_last_node, true);
1320 /// \brief Returns a min cut in a NodeMap.
1322 /// It sets the nodes of one of the two partitions to true and
1323 /// the other partition to false. The function first set all of the
1324 /// nodes to false and after it call the quickMinCut() member.
1325 template <typename NodeMap>
1326 Value minCut(NodeMap& nodeMap) const {
1327 for (typename Graph::NodeIt it(*_graph); it != INVALID; ++it) {
1328 nodeMap.set(it, false);
1330 quickMinCut(nodeMap);
1334 /// \brief Returns a min cut in an EdgeMap.
1336 /// If an undirected edge is in a min cut then it will be
1337 /// set to true and the others will be set to false in the given map.
1338 template <typename EdgeMap>
1339 Value cutEdges(EdgeMap& edgeMap) const {
1340 typename Graph::template NodeMap<bool> cut(*_graph, false);
1342 for (typename Graph::EdgeIt it(*_graph); it != INVALID; ++it) {
1343 edgeMap.set(it, cut[_graph->source(it)] ^ cut[_graph->target(it)]);