COIN-OR::LEMON - Graph Library

source: lemon/lemon/max_cardinality_search.h @ 1298:a78e5b779b69

Last change on this file since 1298:a78e5b779b69 was 1271:fb1c7da561ce, checked in by Alpar Juttner <alpar@…>, 6 years ago

Remove long lines (from all but one file)

File size: 26.1 KB
Line 
1/* -*- mode: C++; indent-tabs-mode: nil; -*-
2 *
3 * This file is a part of LEMON, a generic C++ optimization library.
4 *
5 * Copyright (C) 2003-2013
6 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8 *
9 * Permission to use, modify and distribute this software is granted
10 * provided that this copyright notice appears in all copies. For
11 * precise terms see the accompanying LICENSE file.
12 *
13 * This software is provided "AS IS" with no warranty of any kind,
14 * express or implied, and with no claim as to its suitability for any
15 * purpose.
16 *
17 */
18
19#ifndef LEMON_MAX_CARDINALITY_SEARCH_H
20#define LEMON_MAX_CARDINALITY_SEARCH_H
21
22
23/// \ingroup search
24/// \file
25/// \brief Maximum cardinality search in undirected digraphs.
26
27#include <lemon/bin_heap.h>
28#include <lemon/bucket_heap.h>
29
30#include <lemon/error.h>
31#include <lemon/maps.h>
32
33#include <functional>
34
35namespace lemon {
36
37  /// \brief Default traits class of MaxCardinalitySearch class.
38  ///
39  /// Default traits class of MaxCardinalitySearch class.
40  /// \param Digraph Digraph type.
41  /// \param CapacityMap Type of capacity map.
42  template <typename GR, typename CAP>
43  struct MaxCardinalitySearchDefaultTraits {
44    /// The digraph type the algorithm runs on.
45    typedef GR Digraph;
46
47    template <typename CM>
48    struct CapMapSelector {
49
50      typedef CM CapacityMap;
51
52      static CapacityMap *createCapacityMap(const Digraph& g) {
53        return new CapacityMap(g);
54      }
55    };
56
57    template <typename CM>
58    struct CapMapSelector<ConstMap<CM, Const<int, 1> > > {
59
60      typedef ConstMap<CM, Const<int, 1> > CapacityMap;
61
62      static CapacityMap *createCapacityMap(const Digraph&) {
63        return new CapacityMap;
64      }
65    };
66
67    /// \brief The type of the map that stores the arc capacities.
68    ///
69    /// The type of the map that stores the arc capacities.
70    /// It must meet the \ref concepts::ReadMap "ReadMap" concept.
71    typedef typename CapMapSelector<CAP>::CapacityMap CapacityMap;
72
73    /// \brief The type of the capacity of the arcs.
74    typedef typename CapacityMap::Value Value;
75
76    /// \brief Instantiates a CapacityMap.
77    ///
78    /// This function instantiates a \ref CapacityMap.
79    /// \param digraph is the digraph, to which we would like to define
80    /// the CapacityMap.
81    static CapacityMap *createCapacityMap(const Digraph& digraph) {
82      return CapMapSelector<CapacityMap>::createCapacityMap(digraph);
83    }
84
85    /// \brief The cross reference type used by heap.
86    ///
87    /// The cross reference type used by heap.
88    /// Usually it is \c Digraph::NodeMap<int>.
89    typedef typename Digraph::template NodeMap<int> HeapCrossRef;
90
91    /// \brief Instantiates a HeapCrossRef.
92    ///
93    /// This function instantiates a \ref HeapCrossRef.
94    /// \param digraph is the digraph, to which we would like to define the
95    /// HeapCrossRef.
96    static HeapCrossRef *createHeapCrossRef(const Digraph &digraph) {
97      return new HeapCrossRef(digraph);
98    }
99
100    template <typename CapacityMap>
101    struct HeapSelector {
102      template <typename Value, typename Ref>
103      struct Selector {
104        typedef BinHeap<Value, Ref, std::greater<Value> > Heap;
105      };
106    };
107
108    template <typename CapacityKey>
109    struct HeapSelector<ConstMap<CapacityKey, Const<int, 1> > > {
110      template <typename Value, typename Ref>
111      struct Selector {
112        typedef BucketHeap<Ref, false > Heap;
113      };
114    };
115
116    /// \brief The heap type used by MaxCardinalitySearch algorithm.
117    ///
118    /// The heap type used by MaxCardinalitySearch algorithm. It should
119    /// maximalize the priorities. The default heap type is
120    /// the \ref BinHeap, but it is specialized when the
121    /// CapacityMap is ConstMap<Digraph::Node, Const<int, 1> >
122    /// to BucketHeap.
123    ///
124    /// \sa MaxCardinalitySearch
125    typedef typename HeapSelector<CapacityMap>
126    ::template Selector<Value, HeapCrossRef>
127    ::Heap Heap;
128
129    /// \brief Instantiates a Heap.
130    ///
131    /// This function instantiates a \ref Heap.
132    /// \param crossref The cross reference of the heap.
133    static Heap *createHeap(HeapCrossRef& crossref) {
134      return new Heap(crossref);
135    }
136
137    /// \brief The type of the map that stores whether a node is processed.
138    ///
139    /// The type of the map that stores whether a node is processed.
140    /// It must meet the \ref concepts::WriteMap "WriteMap" concept.
141    /// By default it is a NullMap.
142    typedef NullMap<typename Digraph::Node, bool> ProcessedMap;
143
144    /// \brief Instantiates a ProcessedMap.
145    ///
146    /// This function instantiates a \ref ProcessedMap.
147    /// \param digraph is the digraph, to which
148    /// we would like to define the \ref ProcessedMap
149#ifdef DOXYGEN
150    static ProcessedMap *createProcessedMap(const Digraph &digraph)
151#else
152    static ProcessedMap *createProcessedMap(const Digraph &)
153#endif
154    {
155      return new ProcessedMap();
156    }
157
158    /// \brief The type of the map that stores the cardinalities of the nodes.
159    ///
160    /// The type of the map that stores the cardinalities of the nodes.
161    /// It must meet the \ref concepts::WriteMap "WriteMap" concept.
162    typedef typename Digraph::template NodeMap<Value> CardinalityMap;
163
164    /// \brief Instantiates a CardinalityMap.
165    ///
166    /// This function instantiates a \ref CardinalityMap.
167    /// \param digraph is the digraph, to which we would like to
168    /// define the \ref CardinalityMap
169    static CardinalityMap *createCardinalityMap(const Digraph &digraph) {
170      return new CardinalityMap(digraph);
171    }
172
173
174  };
175
176  /// \ingroup search
177  ///
178  /// \brief Maximum Cardinality Search algorithm class.
179  ///
180  /// This class provides an efficient implementation of Maximum Cardinality
181  /// Search algorithm. The maximum cardinality search first chooses any
182  /// node of the digraph. Then every time it chooses one unprocessed node
183  /// with maximum cardinality, i.e the sum of capacities on out arcs
184  /// to the nodes
185  /// which were previusly processed.
186  /// If there is a cut in the digraph the algorithm should choose
187  /// again any unprocessed node of the digraph.
188
189  /// The arc capacities are passed to the algorithm using a
190  /// \ref concepts::ReadMap "ReadMap", so it is easy to change it to any
191  /// kind of capacity.
192  ///
193  /// The type of the capacity is determined by the \ref
194  /// concepts::ReadMap::Value "Value" of the capacity map.
195  ///
196  /// It is also possible to change the underlying priority heap.
197  ///
198  ///
199  /// \param GR The digraph type the algorithm runs on. The value of
200  /// Digraph is not used directly by the search algorithm, it
201  /// is only passed to \ref MaxCardinalitySearchDefaultTraits.
202  /// \param CAP This read-only ArcMap determines the capacities of
203  /// the arcs. It is read once for each arc, so the map may involve in
204  /// relatively time consuming process to compute the arc capacity if
205  /// it is necessary. The default map type is \ref
206  /// ConstMap "ConstMap<concepts::Digraph::Arc, Const<int,1> >". The value
207  /// of CapacityMap is not used directly by search algorithm, it is only
208  /// passed to \ref MaxCardinalitySearchDefaultTraits.
209  /// \param TR Traits class to set various data types used by the
210  /// algorithm.  The default traits class is
211  /// \ref MaxCardinalitySearchDefaultTraits
212  /// "MaxCardinalitySearchDefaultTraits<GR, CAP>".
213  /// See \ref MaxCardinalitySearchDefaultTraits
214  /// for the documentation of a MaxCardinalitySearch traits class.
215
216#ifdef DOXYGEN
217  template <typename GR, typename CAP, typename TR>
218#else
219  template <typename GR, typename CAP =
220            ConstMap<typename GR::Arc, Const<int,1> >,
221            typename TR =
222            MaxCardinalitySearchDefaultTraits<GR, CAP> >
223#endif
224  class MaxCardinalitySearch {
225  public:
226
227    typedef TR Traits;
228    ///The type of the underlying digraph.
229    typedef typename Traits::Digraph Digraph;
230
231    ///The type of the capacity of the arcs.
232    typedef typename Traits::CapacityMap::Value Value;
233    ///The type of the map that stores the arc capacities.
234    typedef typename Traits::CapacityMap CapacityMap;
235    ///The type of the map indicating if a node is processed.
236    typedef typename Traits::ProcessedMap ProcessedMap;
237    ///The type of the map that stores the cardinalities of the nodes.
238    typedef typename Traits::CardinalityMap CardinalityMap;
239    ///The cross reference type used for the current heap.
240    typedef typename Traits::HeapCrossRef HeapCrossRef;
241    ///The heap type used by the algorithm. It maximizes the priorities.
242    typedef typename Traits::Heap Heap;
243  private:
244    // Pointer to the underlying digraph.
245    const Digraph *_graph;
246    // Pointer to the capacity map
247    const CapacityMap *_capacity;
248    // Indicates if \ref _capacity is locally allocated (\c true) or not.
249    bool local_capacity;
250    // Pointer to the map of cardinality.
251    CardinalityMap *_cardinality;
252    // Indicates if \ref _cardinality is locally allocated (\c true) or not.
253    bool local_cardinality;
254    // Pointer to the map of processed status of the nodes.
255    ProcessedMap *_processed;
256    // Indicates if \ref _processed is locally allocated (\c true) or not.
257    bool local_processed;
258    // Pointer to the heap cross references.
259    HeapCrossRef *_heap_cross_ref;
260    // Indicates if \ref _heap_cross_ref is locally allocated (\c true) or not.
261    bool local_heap_cross_ref;
262    // Pointer to the heap.
263    Heap *_heap;
264    // Indicates if \ref _heap is locally allocated (\c true) or not.
265    bool local_heap;
266
267  public :
268
269    typedef MaxCardinalitySearch Create;
270
271    ///\name Named template parameters
272
273    ///@{
274
275    template <class T>
276    struct DefCapacityMapTraits : public Traits {
277      typedef T CapacityMap;
278      static CapacityMap *createCapacityMap(const Digraph &) {
279               LEMON_ASSERT(false,"Uninitialized parameter.");
280        return 0;
281      }
282    };
283    /// \brief \ref named-templ-param "Named parameter" for setting
284    /// CapacityMap type
285    ///
286    /// \ref named-templ-param "Named parameter" for setting CapacityMap type
287    /// for the algorithm.
288    template <class T>
289    struct SetCapacityMap
290      : public MaxCardinalitySearch<Digraph, CapacityMap,
291                                    DefCapacityMapTraits<T> > {
292      typedef MaxCardinalitySearch<Digraph, CapacityMap,
293                                   DefCapacityMapTraits<T> > Create;
294    };
295
296    template <class T>
297    struct DefCardinalityMapTraits : public Traits {
298      typedef T CardinalityMap;
299      static CardinalityMap *createCardinalityMap(const Digraph &)
300      {
301        LEMON_ASSERT(false,"Uninitialized parameter.");
302        return 0;
303      }
304    };
305    /// \brief \ref named-templ-param "Named parameter" for setting
306    /// CardinalityMap type
307    ///
308    /// \ref named-templ-param "Named parameter" for setting CardinalityMap
309    /// type for the algorithm.
310    template <class T>
311    struct SetCardinalityMap
312      : public MaxCardinalitySearch<Digraph, CapacityMap,
313                                    DefCardinalityMapTraits<T> > {
314      typedef MaxCardinalitySearch<Digraph, CapacityMap,
315                                   DefCardinalityMapTraits<T> > Create;
316    };
317
318    template <class T>
319    struct DefProcessedMapTraits : public Traits {
320      typedef T ProcessedMap;
321      static ProcessedMap *createProcessedMap(const Digraph &) {
322               LEMON_ASSERT(false,"Uninitialized parameter.");
323        return 0;
324      }
325    };
326    /// \brief \ref named-templ-param "Named parameter" for setting
327    /// ProcessedMap type
328    ///
329    /// \ref named-templ-param "Named parameter" for setting ProcessedMap type
330    /// for the algorithm.
331    template <class T>
332    struct SetProcessedMap
333      : public MaxCardinalitySearch<Digraph, CapacityMap,
334                                    DefProcessedMapTraits<T> > {
335      typedef MaxCardinalitySearch<Digraph, CapacityMap,
336                                   DefProcessedMapTraits<T> > Create;
337    };
338
339    template <class H, class CR>
340    struct DefHeapTraits : public Traits {
341      typedef CR HeapCrossRef;
342      typedef H Heap;
343      static HeapCrossRef *createHeapCrossRef(const Digraph &) {
344             LEMON_ASSERT(false,"Uninitialized parameter.");
345        return 0;
346      }
347      static Heap *createHeap(HeapCrossRef &) {
348               LEMON_ASSERT(false,"Uninitialized parameter.");
349        return 0;
350      }
351    };
352    /// \brief \ref named-templ-param "Named parameter" for setting heap
353    /// and cross reference type
354    ///
355    /// \ref named-templ-param "Named parameter" for setting heap and cross
356    /// reference type for the algorithm.
357    template <class H, class CR = typename Digraph::template NodeMap<int> >
358    struct SetHeap
359      : public MaxCardinalitySearch<Digraph, CapacityMap,
360                                    DefHeapTraits<H, CR> > {
361      typedef MaxCardinalitySearch< Digraph, CapacityMap,
362                                    DefHeapTraits<H, CR> > Create;
363    };
364
365    template <class H, class CR>
366    struct DefStandardHeapTraits : public Traits {
367      typedef CR HeapCrossRef;
368      typedef H Heap;
369      static HeapCrossRef *createHeapCrossRef(const Digraph &digraph) {
370        return new HeapCrossRef(digraph);
371      }
372      static Heap *createHeap(HeapCrossRef &crossref) {
373        return new Heap(crossref);
374      }
375    };
376
377    /// \brief \ref named-templ-param "Named parameter" for setting heap and
378    /// cross reference type with automatic allocation
379    ///
380    /// \ref named-templ-param "Named parameter" for setting heap and cross
381    /// reference type. It can allocate the heap and the cross reference
382    /// object if the cross reference's constructor waits for the digraph as
383    /// parameter and the heap's constructor waits for the cross reference.
384    template <class H, class CR = typename Digraph::template NodeMap<int> >
385    struct SetStandardHeap
386      : public MaxCardinalitySearch<Digraph, CapacityMap,
387                                    DefStandardHeapTraits<H, CR> > {
388      typedef MaxCardinalitySearch<Digraph, CapacityMap,
389                                   DefStandardHeapTraits<H, CR> >
390      Create;
391    };
392
393    ///@}
394
395
396  protected:
397
398    MaxCardinalitySearch() {}
399
400  public:
401
402    /// \brief Constructor.
403    ///
404    ///\param digraph the digraph the algorithm will run on.
405    ///\param capacity the capacity map used by the algorithm.
406    MaxCardinalitySearch(const Digraph& digraph,
407                         const CapacityMap& capacity) :
408      _graph(&digraph),
409      _capacity(&capacity), local_capacity(false),
410      _cardinality(0), local_cardinality(false),
411      _processed(0), local_processed(false),
412      _heap_cross_ref(0), local_heap_cross_ref(false),
413      _heap(0), local_heap(false)
414    { }
415
416    /// \brief Constructor.
417    ///
418    ///\param digraph the digraph the algorithm will run on.
419    ///
420    ///A constant 1 capacity map will be allocated.
421    MaxCardinalitySearch(const Digraph& digraph) :
422      _graph(&digraph),
423      _capacity(0), local_capacity(false),
424      _cardinality(0), local_cardinality(false),
425      _processed(0), local_processed(false),
426      _heap_cross_ref(0), local_heap_cross_ref(false),
427      _heap(0), local_heap(false)
428    { }
429
430    /// \brief Destructor.
431    ~MaxCardinalitySearch() {
432      if(local_capacity) delete _capacity;
433      if(local_cardinality) delete _cardinality;
434      if(local_processed) delete _processed;
435      if(local_heap_cross_ref) delete _heap_cross_ref;
436      if(local_heap) delete _heap;
437    }
438
439    /// \brief Sets the capacity map.
440    ///
441    /// Sets the capacity map.
442    /// \return <tt> (*this) </tt>
443    MaxCardinalitySearch &capacityMap(const CapacityMap &m) {
444      if (local_capacity) {
445        delete _capacity;
446        local_capacity=false;
447      }
448      _capacity=&m;
449      return *this;
450    }
451
452    /// \brief Returns a const reference to the capacity map.
453    ///
454    /// Returns a const reference to the capacity map used by
455    /// the algorithm.
456    const CapacityMap &capacityMap() const {
457      return *_capacity;
458    }
459
460    /// \brief Sets the map storing the cardinalities calculated by the
461    /// algorithm.
462    ///
463    /// Sets the map storing the cardinalities calculated by the algorithm.
464    /// If you don't use this function before calling \ref run(),
465    /// it will allocate one. The destuctor deallocates this
466    /// automatically allocated map, of course.
467    /// \return <tt> (*this) </tt>
468    MaxCardinalitySearch &cardinalityMap(CardinalityMap &m) {
469      if(local_cardinality) {
470        delete _cardinality;
471        local_cardinality=false;
472      }
473      _cardinality = &m;
474      return *this;
475    }
476
477    /// \brief Sets the map storing the processed nodes.
478    ///
479    /// Sets the map storing the processed nodes.
480    /// If you don't use this function before calling \ref run(),
481    /// it will allocate one. The destuctor deallocates this
482    /// automatically allocated map, of course.
483    /// \return <tt> (*this) </tt>
484    MaxCardinalitySearch &processedMap(ProcessedMap &m)
485    {
486      if(local_processed) {
487        delete _processed;
488        local_processed=false;
489      }
490      _processed = &m;
491      return *this;
492    }
493
494    /// \brief Returns a const reference to the cardinality map.
495    ///
496    /// Returns a const reference to the cardinality map used by
497    /// the algorithm.
498    const ProcessedMap &processedMap() const {
499      return *_processed;
500    }
501
502    /// \brief Sets the heap and the cross reference used by algorithm.
503    ///
504    /// Sets the heap and the cross reference used by algorithm.
505    /// If you don't use this function before calling \ref run(),
506    /// it will allocate one. The destuctor deallocates this
507    /// automatically allocated map, of course.
508    /// \return <tt> (*this) </tt>
509    MaxCardinalitySearch &heap(Heap& hp, HeapCrossRef &cr) {
510      if(local_heap_cross_ref) {
511        delete _heap_cross_ref;
512        local_heap_cross_ref = false;
513      }
514      _heap_cross_ref = &cr;
515      if(local_heap) {
516        delete _heap;
517        local_heap = false;
518      }
519      _heap = &hp;
520      return *this;
521    }
522
523    /// \brief Returns a const reference to the heap.
524    ///
525    /// Returns a const reference to the heap used by
526    /// the algorithm.
527    const Heap &heap() const {
528      return *_heap;
529    }
530
531    /// \brief Returns a const reference to the cross reference.
532    ///
533    /// Returns a const reference to the cross reference
534    /// of the heap.
535    const HeapCrossRef &heapCrossRef() const {
536      return *_heap_cross_ref;
537    }
538
539  private:
540
541    typedef typename Digraph::Node Node;
542    typedef typename Digraph::NodeIt NodeIt;
543    typedef typename Digraph::Arc Arc;
544    typedef typename Digraph::InArcIt InArcIt;
545
546    void create_maps() {
547      if(!_capacity) {
548        local_capacity = true;
549        _capacity = Traits::createCapacityMap(*_graph);
550      }
551      if(!_cardinality) {
552        local_cardinality = true;
553        _cardinality = Traits::createCardinalityMap(*_graph);
554      }
555      if(!_processed) {
556        local_processed = true;
557        _processed = Traits::createProcessedMap(*_graph);
558      }
559      if (!_heap_cross_ref) {
560        local_heap_cross_ref = true;
561        _heap_cross_ref = Traits::createHeapCrossRef(*_graph);
562      }
563      if (!_heap) {
564        local_heap = true;
565        _heap = Traits::createHeap(*_heap_cross_ref);
566      }
567    }
568
569    void finalizeNodeData(Node node, Value capacity) {
570      _processed->set(node, true);
571      _cardinality->set(node, capacity);
572    }
573
574  public:
575    /// \name Execution control
576    /// The simplest way to execute the algorithm is to use
577    /// one of the member functions called \ref run().
578    /// \n
579    /// If you need more control on the execution,
580    /// first you must call \ref init(), then you can add several source nodes
581    /// with \ref addSource().
582    /// Finally \ref start() will perform the computation.
583
584    ///@{
585
586    /// \brief Initializes the internal data structures.
587    ///
588    /// Initializes the internal data structures, and clears the heap.
589    void init() {
590      create_maps();
591      _heap->clear();
592      for (NodeIt it(*_graph) ; it != INVALID ; ++it) {
593        _processed->set(it, false);
594        _heap_cross_ref->set(it, Heap::PRE_HEAP);
595      }
596    }
597
598    /// \brief Adds a new source node.
599    ///
600    /// Adds a new source node to the priority heap.
601    ///
602    /// It checks if the node has not yet been added to the heap.
603    void addSource(Node source, Value capacity = 0) {
604      if(_heap->state(source) == Heap::PRE_HEAP) {
605        _heap->push(source, capacity);
606      }
607    }
608
609    /// \brief Processes the next node in the priority heap
610    ///
611    /// Processes the next node in the priority heap.
612    ///
613    /// \return The processed node.
614    ///
615    /// \warning The priority heap must not be empty!
616    Node processNextNode() {
617      Node node = _heap->top();
618      finalizeNodeData(node, _heap->prio());
619      _heap->pop();
620
621      for (InArcIt it(*_graph, node); it != INVALID; ++it) {
622        Node source = _graph->source(it);
623        switch (_heap->state(source)) {
624        case Heap::PRE_HEAP:
625          _heap->push(source, (*_capacity)[it]);
626          break;
627        case Heap::IN_HEAP:
628          _heap->decrease(source, (*_heap)[source] + (*_capacity)[it]);
629          break;
630        case Heap::POST_HEAP:
631          break;
632        }
633      }
634      return node;
635    }
636
637    /// \brief Next node to be processed.
638    ///
639    /// Next node to be processed.
640    ///
641    /// \return The next node to be processed or INVALID if the
642    /// priority heap is empty.
643    Node nextNode() {
644      return !_heap->empty() ? _heap->top() : INVALID;
645    }
646
647    /// \brief Returns \c false if there are nodes
648    /// to be processed in the priority heap
649    ///
650    /// Returns \c false if there are nodes
651    /// to be processed in the priority heap
652    bool emptyQueue() { return _heap->empty(); }
653    /// \brief Returns the number of the nodes to be processed
654    /// in the priority heap
655    ///
656    /// Returns the number of the nodes to be processed in the priority heap
657    int emptySize() { return _heap->size(); }
658
659    /// \brief Executes the algorithm.
660    ///
661    /// Executes the algorithm.
662    ///
663    ///\pre init() must be called and at least one node should be added
664    /// with addSource() before using this function.
665    ///
666    /// This method runs the Maximum Cardinality Search algorithm from the
667    /// source node(s).
668    void start() {
669      while ( !_heap->empty() ) processNextNode();
670    }
671
672    /// \brief Executes the algorithm until \c dest is reached.
673    ///
674    /// Executes the algorithm until \c dest is reached.
675    ///
676    /// \pre init() must be called and at least one node should be added
677    /// with addSource() before using this function.
678    ///
679    /// This method runs the %MaxCardinalitySearch algorithm from the source
680    /// nodes.
681    void start(Node dest) {
682      while ( !_heap->empty() && _heap->top()!=dest ) processNextNode();
683      if ( !_heap->empty() ) finalizeNodeData(_heap->top(), _heap->prio());
684    }
685
686    /// \brief Executes the algorithm until a condition is met.
687    ///
688    /// Executes the algorithm until a condition is met.
689    ///
690    /// \pre init() must be called and at least one node should be added
691    /// with addSource() before using this function.
692    ///
693    /// \param nm must be a bool (or convertible) node map. The algorithm
694    /// will stop when it reaches a node \c v with <tt>nm[v]==true</tt>.
695    template <typename NodeBoolMap>
696    void start(const NodeBoolMap &nm) {
697      while ( !_heap->empty() && !nm[_heap->top()] ) processNextNode();
698      if ( !_heap->empty() ) finalizeNodeData(_heap->top(),_heap->prio());
699    }
700
701    /// \brief Runs the maximum cardinality search algorithm from node \c s.
702    ///
703    /// This method runs the %MaxCardinalitySearch algorithm from a root
704    /// node \c s.
705    ///
706    ///\note d.run(s) is just a shortcut of the following code.
707    ///\code
708    ///  d.init();
709    ///  d.addSource(s);
710    ///  d.start();
711    ///\endcode
712    void run(Node s) {
713      init();
714      addSource(s);
715      start();
716    }
717
718    /// \brief Runs the maximum cardinality search algorithm for the
719    /// whole digraph.
720    ///
721    /// This method runs the %MaxCardinalitySearch algorithm from all
722    /// unprocessed node of the digraph.
723    ///
724    ///\note d.run(s) is just a shortcut of the following code.
725    ///\code
726    ///  d.init();
727    ///  for (NodeIt it(digraph); it != INVALID; ++it) {
728    ///    if (!d.reached(it)) {
729    ///      d.addSource(s);
730    ///      d.start();
731    ///    }
732    ///  }
733    ///\endcode
734    void run() {
735      init();
736      for (NodeIt it(*_graph); it != INVALID; ++it) {
737        if (!reached(it)) {
738          addSource(it);
739          start();
740        }
741      }
742    }
743
744    ///@}
745
746    /// \name Query Functions
747    /// The results of the maximum cardinality search algorithm can be
748    /// obtained using these functions.
749    /// \n
750    /// Before the use of these functions, either run() or start() must be
751    /// called.
752
753    ///@{
754
755    /// \brief The cardinality of a node.
756    ///
757    /// Returns the cardinality of a node.
758    /// \pre \ref run() must be called before using this function.
759    /// \warning If node \c v in unreachable from the root the return value
760    /// of this funcion is undefined.
761    Value cardinality(Node node) const { return (*_cardinality)[node]; }
762
763    /// \brief The current cardinality of a node.
764    ///
765    /// Returns the current cardinality of a node.
766    /// \pre the given node should be reached but not processed
767    Value currentCardinality(Node node) const { return (*_heap)[node]; }
768
769    /// \brief Returns a reference to the NodeMap of cardinalities.
770    ///
771    /// Returns a reference to the NodeMap of cardinalities. \pre \ref run()
772    /// must be called before using this function.
773    const CardinalityMap &cardinalityMap() const { return *_cardinality;}
774
775    /// \brief Checks if a node is reachable from the root.
776    ///
777    /// Returns \c true if \c v is reachable from the root.
778    /// \warning The source nodes are initated as unreached.
779    /// \pre \ref run() must be called before using this function.
780    bool reached(Node v) { return (*_heap_cross_ref)[v] != Heap::PRE_HEAP; }
781
782    /// \brief Checks if a node is processed.
783    ///
784    /// Returns \c true if \c v is processed, i.e. the shortest
785    /// path to \c v has already found.
786    /// \pre \ref run() must be called before using this function.
787    bool processed(Node v) { return (*_heap_cross_ref)[v] == Heap::POST_HEAP; }
788
789    ///@}
790  };
791
792}
793
794#endif
Note: See TracBrowser for help on using the repository browser.