COIN-OR::LEMON - Graph Library

source: lemon-0.x/lemon/min_cut.h @ 2115:4cd528a30ec1

Last change on this file since 2115:4cd528a30ec1 was 2115:4cd528a30ec1, checked in by Balazs Dezso, 18 years ago

Splitted graph files

File size: 43.9 KB
Line 
1/* -*- C++ -*-
2 * lemon/min_cut.h - Part of LEMON, a generic C++ optimization library
3 *
4 * Copyright (C) 2005 Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
5 * (Egervary Research Group on Combinatorial Optimization, EGRES).
6 *
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.
10 *
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
13 * purpose.
14 *
15 */
16
17#ifndef LEMON_MIN_CUT_H
18#define LEMON_MIN_CUT_H
19
20
21/// \ingroup topology
22/// \file
23/// \brief Maximum cardinality search and min cut in undirected graphs.
24
25#include <lemon/list_graph.h>
26#include <lemon/list_ugraph.h>
27#include <lemon/bin_heap.h>
28#include <lemon/bucket_heap.h>
29
30#include <lemon/bits/invalid.h>
31#include <lemon/error.h>
32#include <lemon/maps.h>
33
34#include <functional>
35
36namespace lemon {
37
38  namespace _min_cut_bits {
39
40    template <typename CapacityMap>
41    struct HeapSelector {
42      template <typename Key, typename Value, typename Ref>
43      struct Selector {
44        typedef BinHeap<Key, Value, Ref, std::greater<Value> > Heap;
45      };
46    };
47
48    template <typename CapacityKey>
49    struct HeapSelector<ConstMap<CapacityKey, Const<int, 1> > > {
50      template <typename Key, typename Value, typename Ref>
51      struct Selector {
52        typedef BucketHeap<Key, Ref, false > Heap;
53      };
54    };
55
56  }
57
58  /// \brief Default traits class of MaxCardinalitySearch class.
59  ///
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.
66    typedef _Graph Graph;
67
68    /// \brief The type of the map that stores the edge capacities.
69    ///
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;
73
74    /// \brief The type of the capacity of the edges.
75    typedef typename CapacityMap::Value Value;
76
77    /// \brief The cross reference type used by heap.
78    ///
79    /// The cross reference type used by heap.
80    /// Usually it is \c Graph::NodeMap<int>.
81    typedef typename Graph::template NodeMap<int> HeapCrossRef;
82
83    /// \brief Instantiates a HeapCrossRef.
84    ///
85    /// This function instantiates a \ref HeapCrossRef.
86    /// \param graph is the graph, to which we would like to define the
87    /// HeapCrossRef.
88    static HeapCrossRef *createHeapCrossRef(const Graph &graph) {
89      return new HeapCrossRef(graph);
90    }
91   
92    /// \brief The heap type used by MaxCardinalitySearch algorithm.
93    ///
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> >
98    /// to BucketHeap.
99    ///
100    /// \sa MaxCardinalitySearch
101    typedef typename _min_cut_bits
102    ::HeapSelector<CapacityMap>
103    ::template Selector<typename Graph::Node, Value, HeapCrossRef>
104    ::Heap Heap;
105
106    /// \brief Instantiates a Heap.
107    ///
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);
112    }
113
114    /// \brief The type of the map that stores whether a nodes is processed.
115    ///
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;
120
121    /// \brief Instantiates a ProcessedMap.
122    ///
123    /// This function instantiates a \ref ProcessedMap.
124    /// \param graph is the graph, to which
125    /// we would like to define the \ref ProcessedMap
126#ifdef DOXYGEN
127    static ProcessedMap *createProcessedMap(const Graph &graph)
128#else
129    static ProcessedMap *createProcessedMap(const Graph &)
130#endif
131    {
132      return new ProcessedMap();
133    }
134
135    /// \brief The type of the map that stores the cardinalties of the nodes.
136    ///
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;
140
141    /// \brief Instantiates a CardinalityMap.
142    ///
143    /// This function instantiates a \ref CardinalityMap.
144    /// \param graph is the graph, to which we would like to define the \ref
145    /// CardinalityMap
146    static CardinalityMap *createCardinalityMap(const Graph &graph) {
147      return new CardinalityMap(graph);
148    }
149
150  };
151 
152  /// \ingroup topology
153  ///
154  /// \brief Maximum Cardinality Search algorithm class.
155  ///
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.
164  ///
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.
168  ///
169  /// The type of the capacity is determined by the \ref
170  /// concept::ReadMap::Value "Value" of the capacity map.
171  ///
172  /// It is also possible to change the underlying priority heap.
173  ///
174  ///
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.
192  ///
193  /// \author Balazs Dezso
194
195#ifdef DOXYGEN
196  template <typename _Graph, typename _CapacityMap, typename _Traits>
197#else
198  template <typename _Graph = ListGraph,
199            typename _CapacityMap = typename _Graph::template EdgeMap<int>,
200            typename _Traits =
201            MaxCardinalitySearchDefaultTraits<_Graph, _CapacityMap> >
202#endif
203  class MaxCardinalitySearch {
204  public:
205    /// \brief \ref Exception for uninitialized parameters.
206    ///
207    /// This error represents problems in the initialization
208    /// of the parameters of the algorithms.
209    class UninitializedParameter : public lemon::UninitializedParameter {
210    public:
211      virtual const char* exceptionName() const {
212        return "lemon::MaxCardinalitySearch::UninitializedParameter";
213      }
214    };
215
216    typedef _Traits Traits;
217    ///The type of the underlying graph.
218    typedef typename Traits::Graph Graph;
219   
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;
232  private:
233    /// Pointer to the underlying graph.
234    const Graph *_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.
250    Heap *_heap;
251    ///Indicates if \ref _heap is locally allocated (\c true) or not.
252    bool local_heap;
253
254  public :
255
256    typedef MaxCardinalitySearch Create;
257 
258    ///\name Named template parameters
259
260    ///@{
261
262    template <class T>
263    struct DefCardinalityMapTraits : public Traits {
264      typedef T CardinalityMap;
265      static CardinalityMap *createCardinalityMap(const Graph &)
266      {
267        throw UninitializedParameter();
268      }
269    };
270    /// \brief \ref named-templ-param "Named parameter" for setting
271    /// CardinalityMap type
272    ///
273    /// \ref named-templ-param "Named parameter" for setting CardinalityMap
274    /// type
275    template <class T>
276    struct DefCardinalityMap
277      : public MaxCardinalitySearch<Graph, CapacityMap,
278                                    DefCardinalityMapTraits<T> > {
279      typedef MaxCardinalitySearch<Graph, CapacityMap,
280                                   DefCardinalityMapTraits<T> > Create;
281    };
282   
283    template <class T>
284    struct DefProcessedMapTraits : public Traits {
285      typedef T ProcessedMap;
286      static ProcessedMap *createProcessedMap(const Graph &) {
287        throw UninitializedParameter();
288      }
289    };
290    /// \brief \ref named-templ-param "Named parameter" for setting
291    /// ProcessedMap type
292    ///
293    /// \ref named-templ-param "Named parameter" for setting ProcessedMap type
294    ///
295    template <class T>
296    struct DefProcessedMap
297      : public MaxCardinalitySearch<Graph, CapacityMap,
298                                    DefProcessedMapTraits<T> > {
299      typedef MaxCardinalitySearch<Graph, CapacityMap,
300                                   DefProcessedMapTraits<T> > Create;
301    };
302   
303    template <class H, class CR>
304    struct DefHeapTraits : public Traits {
305      typedef CR HeapCrossRef;
306      typedef H Heap;
307      static HeapCrossRef *createHeapCrossRef(const Graph &) {
308        throw UninitializedParameter();
309      }
310      static Heap *createHeap(HeapCrossRef &) {
311        throw UninitializedParameter();
312      }
313    };
314    /// \brief \ref named-templ-param "Named parameter" for setting heap
315    /// and cross reference type
316    ///
317    /// \ref named-templ-param "Named parameter" for setting heap and cross
318    /// reference type
319    template <class H, class CR = typename Graph::template NodeMap<int> >
320    struct DefHeap
321      : public MaxCardinalitySearch<Graph, CapacityMap,
322                                    DefHeapTraits<H, CR> > {
323      typedef MaxCardinalitySearch< Graph, CapacityMap,
324                                    DefHeapTraits<H, CR> > Create;
325    };
326
327    template <class H, class CR>
328    struct DefStandardHeapTraits : public Traits {
329      typedef CR HeapCrossRef;
330      typedef H Heap;
331      static HeapCrossRef *createHeapCrossRef(const Graph &graph) {
332        return new HeapCrossRef(graph);
333      }
334      static Heap *createHeap(HeapCrossRef &crossref) {
335        return new Heap(crossref);
336      }
337    };
338
339    /// \brief \ref named-templ-param "Named parameter" for setting heap and
340    /// cross reference type with automatic allocation
341    ///
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> >
352      Create;
353    };
354   
355    ///@}
356
357
358  protected:
359
360    MaxCardinalitySearch() {}
361
362  public:     
363   
364    /// \brief Constructor.
365    ///
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)
374    { }
375   
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;
382    }
383
384    /// \brief Sets the capacity map.
385    ///
386    /// Sets the capacity map.
387    /// \return <tt> (*this) </tt>
388    MaxCardinalitySearch &capacityMap(const CapacityMap &m) {
389      _capacity = &m;
390      return *this;
391    }
392
393    /// \brief Sets the map storing the cardinalities calculated by the
394    /// algorithm.
395    ///
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) {
403        delete _cardinality;
404        local_cardinality=false;
405      }
406      _cardinality = &m;
407      return *this;
408    }
409
410    /// \brief Sets the map storing the processed nodes.
411    ///
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)
418    {
419      if(local_processed) {
420        delete _processed;
421        local_processed=false;
422      }
423      _processed = &m;
424      return *this;
425    }
426
427    /// \brief Sets the heap and the cross reference used by algorithm.
428    ///
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;
438      }
439      _heap_cross_ref = &crossRef;
440      if(local_heap) {
441        delete _heap;
442        local_heap = false;
443      }
444      _heap = &heap;
445      return *this;
446    }
447
448  private:
449
450    typedef typename Graph::Node Node;
451    typedef typename Graph::NodeIt NodeIt;
452    typedef typename Graph::Edge Edge;
453    typedef typename Graph::InEdgeIt InEdgeIt;
454
455    void create_maps() {
456      if(!_cardinality) {
457        local_cardinality = true;
458        _cardinality = Traits::createCardinalityMap(*_graph);
459      }
460      if(!_processed) {
461        local_processed = true;
462        _processed = Traits::createProcessedMap(*_graph);
463      }
464      if (!_heap_cross_ref) {
465        local_heap_cross_ref = true;
466        _heap_cross_ref = Traits::createHeapCrossRef(*_graph);
467      }
468      if (!_heap) {
469        local_heap = true;
470        _heap = Traits::createHeap(*_heap_cross_ref);
471      }
472    }
473   
474    void finalizeNodeData(Node node, Value capacity) {
475      _processed->set(node, true);
476      _cardinality->set(node, capacity);
477    }
478
479  public:
480    /// \name Execution control
481    /// The simplest way to execute the algorithm is to use
482    /// one of the member functions called \c run(...).
483    /// \n
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
488    /// computation.
489
490    ///@{
491
492    /// \brief Initializes the internal data structures.
493    ///
494    /// Initializes the internal data structures.
495    void init() {
496      create_maps();
497      _heap->clear();
498      for (NodeIt it(*_graph) ; it != INVALID ; ++it) {
499        _processed->set(it, false);
500        _heap_cross_ref->set(it, Heap::PRE_HEAP);
501      }
502    }
503   
504    /// \brief Adds a new source node.
505    ///
506    /// Adds a new source node to the priority heap.
507    ///
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);
512      }
513    }
514   
515    /// \brief Processes the next node in the priority heap
516    ///
517    /// Processes the next node in the priority heap.
518    ///
519    /// \return The processed node.
520    ///
521    /// \warning The priority heap must not be empty!
522    Node processNextNode() {
523      Node node = _heap->top();
524      finalizeNodeData(node, _heap->prio());
525      _heap->pop();
526     
527      for (InEdgeIt it(*_graph, node); it != INVALID; ++it) {
528        Node source = _graph->source(it);
529        switch (_heap->state(source)) {
530        case Heap::PRE_HEAP:
531          _heap->push(source, (*_capacity)[it]);
532          break;
533        case Heap::IN_HEAP:
534          _heap->decrease(source, (*_heap)[source] + (*_capacity)[it]);
535          break;
536        case Heap::POST_HEAP:
537          break;
538        }
539      }
540      return node;
541    }
542
543    /// \brief Next node to be processed.
544    ///
545    /// Next node to be processed.
546    ///
547    /// \return The next node to be processed or INVALID if the
548    /// priority heap is empty.
549    Node nextNode() {
550      return _heap->empty() ? _heap->top() : INVALID;
551    }
552 
553    /// \brief Returns \c false if there are nodes
554    /// to be processed in the priority heap
555    ///
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
561    ///
562    /// Returns the number of the nodes to be processed in the priority heap
563    int queueSize() { return _heap->size(); }
564   
565    /// \brief Executes the algorithm.
566    ///
567    /// Executes the algorithm.
568    ///
569    ///\pre init() must be called and at least one node should be added
570    /// with addSource() before using this function.
571    ///
572    /// This method runs the Maximum Cardinality Search algorithm from the
573    /// source node(s).
574    void start() {
575      while ( !_heap->empty() ) processNextNode();
576    }
577   
578    /// \brief Executes the algorithm until \c dest is reached.
579    ///
580    /// Executes the algorithm until \c dest is reached.
581    ///
582    /// \pre init() must be called and at least one node should be added
583    /// with addSource() before using this function.
584    ///
585    /// This method runs the %MaxCardinalitySearch algorithm from the source
586    /// nodes.
587    void start(Node dest) {
588      while ( !_heap->empty() && _heap->top()!=dest ) processNextNode();
589      if ( !_heap->empty() ) finalizeNodeData(_heap->top(), _heap->prio());
590    }
591   
592    /// \brief Executes the algorithm until a condition is met.
593    ///
594    /// Executes the algorithm until a condition is met.
595    ///
596    /// \pre init() must be called and at least one node should be added
597    /// with addSource() before using this function.
598    ///
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());
605    }
606   
607    /// \brief Runs the maximal cardinality search algorithm from node \c s.
608    ///
609    /// This method runs the %MaxCardinalitySearch algorithm from a root
610    /// node \c s.
611    ///
612    ///\note d.run(s) is just a shortcut of the following code.
613    ///\code
614    ///  d.init();
615    ///  d.addSource(s);
616    ///  d.start();
617    ///\endcode
618    void run(Node s) {
619      init();
620      addSource(s);
621      start();
622    }
623
624    /// \brief Runs the maximal cardinality search algorithm for the
625    /// whole graph.
626    ///
627    /// This method runs the %MaxCardinalitySearch algorithm from all
628    /// unprocessed node of the graph.
629    ///
630    ///\note d.run(s) is just a shortcut of the following code.
631    ///\code
632    ///  d.init();
633    ///  for (NodeIt it(graph); it != INVALID; ++it) {
634    ///    if (!d.reached(it)) {
635    ///      d.addSource(s);
636    ///      d.start();
637    ///    }
638    ///  }
639    ///\endcode
640    void run() {
641      init();
642      for (NodeIt it(*_graph); it != INVALID; ++it) {
643        if (!reached(it)) {
644          addSource(it);
645          start();
646        }
647      }
648    }
649   
650    ///@}
651
652    /// \name Query Functions
653    /// The result of the maximum cardinality search algorithm can be
654    /// obtained using these functions.
655    /// \n
656    /// Before the use of these functions, either run() or start() must be
657    /// called.
658   
659    ///@{
660
661    /// \brief The cardinality of a node.
662    ///
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]; }
668
669    /// \brief Returns a reference to the NodeMap of cardinalities.
670    ///
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;}
674 
675    /// \brief Checks if a node is reachable from the root.
676    ///
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; }
681
682    /// \brief Checks if a node is processed.
683    ///
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; }
688   
689    ///@}
690  };
691
692  /// \brief Default traits class of MinCut class.
693  ///
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;
701
702    /// The graph type the algorithm runs on.
703    typedef _Graph Graph;
704
705    /// The AuxGraph type which is an Graph
706    typedef ListUGraph AuxGraph;
707
708    /// \brief Instantiates a AuxGraph.
709    ///
710    /// This function instantiates a \ref AuxGraph.
711    static AuxGraph *createAuxGraph() {
712      return new AuxGraph();
713    }
714
715    /// \brief The type of the map that stores the edge capacities.
716    ///
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;
720
721    /// \brief Instantiates a CapacityMap.
722    ///
723    /// This function instantiates a \ref CapacityMap.
724#ifdef DOXYGEN
725    static CapacityMap *createCapacityMap(const Graph& graph)
726#else
727    static CapacityMap *createCapacityMap(const Graph&)
728#endif
729    {
730      throw UninitializedParameter();
731    }
732
733    /// \brief The AuxCapacityMap type
734    ///
735    /// The type of the map that stores the auxing edge capacities.
736    typedef AuxGraph::UEdgeMap<Value> AuxCapacityMap;
737
738    /// \brief Instantiates a AuxCapacityMap.
739    ///
740    /// This function instantiates a \ref AuxCapacityMap.
741    static AuxCapacityMap *createAuxCapacityMap(const AuxGraph& graph) {
742      return new AuxCapacityMap(graph);
743    }
744
745    /// \brief The cross reference type used by heap.
746    ///
747    /// The cross reference type used by heap.
748    /// Usually it is \c Graph::NodeMap<int>.
749    typedef AuxGraph::NodeMap<int> HeapCrossRef;
750
751    /// \brief Instantiates a HeapCrossRef.
752    ///
753    /// This function instantiates a \ref HeapCrossRef.
754    /// \param graph is the graph, to which we would like to define the
755    /// HeapCrossRef.
756    static HeapCrossRef *createHeapCrossRef(const AuxGraph &graph) {
757      return new HeapCrossRef(graph);
758    }
759   
760    /// \brief The heap type used by MinCut algorithm.
761    ///
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.
765    ///
766    /// \sa BinHeap
767    /// \sa MinCut
768    typedef typename _min_cut_bits
769    ::HeapSelector<CapacityMap>
770    ::template Selector<typename AuxGraph::Node, Value, HeapCrossRef>
771    ::Heap Heap;
772   
773    /// \brief Instantiates a Heap.
774    ///
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);
779    }
780
781    /// \brief Map from the AuxGraph's node type to the Graph's node type.
782    ///
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;
786
787    /// \brief Instantiates a NodeRefMap.
788    ///
789    /// This function instantiates a \ref NodeRefMap.
790    static NodeRefMap *createNodeRefMap(const AuxGraph& graph) {
791      return new NodeRefMap(graph);
792    }
793
794    /// \brief Map from the Graph's node type to the Graph's node type.
795    ///
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;
799
800    /// \brief Instantiates a ListRefMap.
801    ///
802    /// This function instantiates a \ref ListRefMap.
803    static ListRefMap *createListRefMap(const Graph& graph) {
804      return new ListRefMap(graph);
805    }
806   
807
808  };
809
810  namespace _min_cut_bits {
811    template <typename _Key>
812    class LastTwoMap {
813    public:
814      typedef _Key Key;
815      typedef bool Value;
816
817      LastTwoMap(int _num) : num(_num) {}
818      void set(const Key& key, bool val) {
819        if (!val) return;
820        --num;
821        if (num > 1) return;
822        keys[num] = key;
823      }
824     
825      Key operator[](int index) const { return keys[index]; }
826    private:
827      Key keys[2];
828      int num;
829    };
830  }
831
832  /// \ingroup topology
833  ///
834  /// \brief Calculates the min cut in an undirected graph.
835  ///
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.
842  ///
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.
847#ifdef DOXYGEN
848  template <typename _Graph, typename _CapacityMap, typename _Traits>
849#else
850  template <typename _Graph = ListUGraph,
851            typename _CapacityMap = typename _Graph::template UEdgeMap<int>,
852            typename _Traits = MinCutDefaultTraits<_Graph, _CapacityMap> >
853#endif
854  class MinCut {
855  public:
856    /// \brief \ref Exception for uninitialized parameters.
857    ///
858    /// This error represents problems in the initialization
859    /// of the parameters of the algorithms.
860    class UninitializedParameter : public lemon::UninitializedParameter {
861    public:
862      virtual const char* exceptionName() const {
863        return "lemon::MinCut::UninitializedParameter";
864      }
865    };
866
867
868  private:
869
870    typedef _Traits Traits;
871    /// The type of the underlying graph.
872    typedef typename Traits::Graph Graph;
873   
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;
890
891  public:
892
893    ///\name Named template parameters
894
895    ///@{
896
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();
901      }
902    };
903    /// \brief \ref named-templ-param "Named parameter" for setting 
904    /// the capacity type to constMap<UEdge, int, 1>()
905    ///
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;
911    };
912
913
914    template <class H, class CR>
915    struct DefHeapTraits : public Traits {
916      typedef CR HeapCrossRef;
917      typedef H Heap;
918      static HeapCrossRef *createHeapCrossRef(const AuxGraph &) {
919        throw UninitializedParameter();
920      }
921      static Heap *createHeap(HeapCrossRef &) {
922        throw UninitializedParameter();
923      }
924    };
925    /// \brief \ref named-templ-param "Named parameter" for setting heap
926    /// and cross reference type
927    ///
928    /// \ref named-templ-param "Named parameter" for setting heap and cross
929    /// reference type
930    template <class H, class CR = typename Graph::template NodeMap<int> >
931    struct DefHeap
932      : public MinCut<Graph, CapacityMap, DefHeapTraits<H, CR> > {
933      typedef MinCut< Graph, CapacityMap, DefHeapTraits<H, CR> > Create;
934    };
935
936    template <class H, class CR>
937    struct DefStandardHeapTraits : public Traits {
938      typedef CR HeapCrossRef;
939      typedef H Heap;
940      static HeapCrossRef *createHeapCrossRef(const AuxGraph &graph) {
941        return new HeapCrossRef(graph);
942      }
943      static Heap *createHeap(HeapCrossRef &crossref) {
944        return new Heap(crossref);
945      }
946    };
947
948    /// \brief \ref named-templ-param "Named parameter" for setting heap and
949    /// cross reference type with automatic allocation
950    ///
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> >
959      Create;
960    };
961
962    ///@}
963
964
965  private:
966    /// Pointer to the underlying graph.
967    const Graph *_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.
972    bool local_capacity;
973
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.
990    Heap *_heap;
991    /// Indicates if \ref _heap is locally allocated (\c true) or not.
992    bool local_heap;
993
994    /// The min cut value.
995    Value _min_cut;
996    /// The number of the nodes of the aux graph.
997    int _node_num;
998    /// The first and last node of the min cut in the next list;
999    typename Graph::Node _first_node, _last_node;
1000
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.
1005    ListRefMap *_next;
1006   
1007    void create_structures() {
1008      if (!_capacity) {
1009        local_capacity = true;
1010        _capacity = Traits::createCapacityMap(*_graph);
1011      }
1012      if(!_aux_graph) {
1013        local_aux_graph = true;
1014        _aux_graph = Traits::createAuxGraph();
1015      }
1016      if(!_aux_capacity) {
1017        local_aux_capacity = true;
1018        _aux_capacity = Traits::createAuxCapacityMap(*_aux_graph);
1019      }
1020
1021      _first = Traits::createNodeRefMap(*_aux_graph);
1022      _last = Traits::createNodeRefMap(*_aux_graph);
1023
1024      _next = Traits::createListRefMap(*_graph);
1025
1026      typename Graph::template NodeMap<typename AuxGraph::Node> ref(*_graph);
1027
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);
1033        ref.set(it, node);
1034      }
1035
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]);
1042       
1043      }
1044
1045      if (!_heap_cross_ref) {
1046        local_heap_cross_ref = true;
1047        _heap_cross_ref = Traits::createHeapCrossRef(*_aux_graph);
1048      }
1049      if (!_heap) {
1050        local_heap = true;
1051        _heap = Traits::createHeap(*_heap_cross_ref);
1052      }
1053    }
1054
1055  public :
1056
1057    typedef MinCut Create;
1058
1059
1060    /// \brief Constructor.
1061    ///
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)
1065      : _graph(&graph),
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) {}
1072
1073    /// \brief Constructor.
1074    ///
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.
1079    ///
1080    ///\param graph the graph the algorithm will run on.
1081    MinCut(const Graph& graph)
1082      : _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) {}
1089
1090    /// \brief Destructor.
1091    ///
1092    /// Destructor.
1093    ~MinCut() {
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;
1102    }
1103
1104    /// \brief Sets the heap and the cross reference used by algorithm.
1105    ///
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)
1112    {
1113      if (local_heap_cross_ref) {
1114        delete _heap_cross_ref;
1115        local_heap_cross_ref=false;
1116      }
1117      _heap_cross_ref = &crossRef;
1118      if (local_heap) {
1119        delete _heap;
1120        local_heap=false;
1121      }
1122      _heap = &heap;
1123      return *this;
1124    }
1125
1126    /// \brief Sets the aux graph.
1127    ///
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)
1134    {
1135      if(local_aux_graph) {
1136        delete _aux_graph;
1137        local_aux_graph=false;
1138      }
1139      _aux_graph = &aux_graph;
1140      return *this;
1141    }
1142
1143    /// \brief Sets the aux capacity map.
1144    ///
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)
1151    {
1152      if(local_aux_capacity) {
1153        delete _aux_capacity;
1154        local_aux_capacity=false;
1155      }
1156      _aux_capacity = &aux_capacity_map;
1157      return *this;
1158    }
1159
1160    /// \name Execution control
1161    /// The simplest way to execute the algorithm is to use
1162    /// one of the member functions called \c run().
1163    /// \n
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.
1167
1168    ///@{
1169
1170    /// \brief Initializes the internal data structures.
1171    ///
1172    /// Initializes the internal data structures.
1173    void init() {
1174      create_structures();
1175      _first_node = _last_node = INVALID;
1176      _node_num = countNodes(*_graph);
1177    }
1178
1179    /// \brief Processes the next phase
1180    ///
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 
1184    ///
1185    ///\return %True when the algorithm finished.
1186    bool processNextPhase() {
1187      if (_node_num <= 1) return true;
1188      using namespace _min_cut_bits;
1189
1190      typedef typename AuxGraph::Node Node;
1191      typedef typename AuxGraph::NodeIt NodeIt;
1192      typedef typename AuxGraph::UEdge UEdge;
1193      typedef typename AuxGraph::IncEdgeIt IncEdgeIt;
1194     
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;
1200     
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);
1204      }
1205      mcs.heap(*_heap, *_heap_cross_ref);
1206
1207      LastTwoMap<Node> last_two_nodes(_node_num);
1208      mcs.processedMap(last_two_nodes);
1209
1210      NullMap<Node, Value> cardinality;
1211      mcs.cardinalityMap(cardinality);
1212
1213      mcs.run();
1214
1215      Node new_node = _aux_graph->addNode();
1216
1217      typename AuxGraph::template NodeMap<UEdge> edges(*_aux_graph, INVALID);
1218     
1219      Node first_node = last_two_nodes[0];
1220      Node second_node = last_two_nodes[1];
1221     
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]);
1225
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];
1234        } else {
1235          (*_aux_capacity)[edges[node]] += (*_aux_capacity)[it];         
1236        }
1237      }
1238
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;
1243      }
1244
1245      _aux_graph->erase(first_node);
1246
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];
1252        } else {
1253          (*_aux_capacity)[edges[node]] += (*_aux_capacity)[it];         
1254        }
1255      }
1256      _aux_graph->erase(second_node);
1257
1258      --_node_num;
1259      return _node_num == 1;
1260    }
1261
1262    /// \brief Executes the algorithm.
1263    ///
1264    /// Executes the algorithm.
1265    ///
1266    /// \pre init() must be called
1267    void start() {
1268      while (!processNextPhase());
1269    }
1270
1271
1272    /// \brief Runs %MinCut algorithm.
1273    ///
1274    /// This method runs the %Min cut algorithm
1275    ///
1276    /// \note mc.run(s) is just a shortcut of the following code.
1277    ///\code
1278    ///  mc.init();
1279    ///  mc.start();
1280    ///\endcode
1281    void run() {
1282      init();
1283      start();
1284    }
1285
1286    ///@}
1287
1288    /// \name Query Functions
1289    /// The result of the %MinCut algorithm can be obtained using these
1290    /// functions.\n
1291    /// Before the use of these functions,
1292    /// either run() or start() must be called.
1293   
1294    ///@{
1295
1296    /// \brief Returns the min cut value.
1297    ///
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 {
1302      return _min_cut;
1303    }
1304
1305    /// \brief Returns a min cut in a NodeMap.
1306    ///
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);
1315           }
1316      nodeMap.set(_last_node, true);
1317      return minCut();
1318    }
1319
1320    /// \brief Returns a min cut in a NodeMap.
1321    ///
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);     
1329      }
1330      quickMinCut(nodeMap);
1331      return minCut();
1332    }
1333
1334    /// \brief Returns a min cut in an EdgeMap.
1335    ///
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);
1341      quickMinCut(cut);
1342      for (typename Graph::EdgeIt it(*_graph); it != INVALID; ++it) {
1343        edgeMap.set(it, cut[_graph->source(it)] ^ cut[_graph->target(it)]);
1344      }
1345      return minCut();
1346    }
1347
1348    ///@}
1349
1350  };
1351}
1352
1353#endif
Note: See TracBrowser for help on using the repository browser.