1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/lemon/max_cardinality_search.h Mon Nov 15 22:23:35 2010 +0100
1.3 @@ -0,0 +1,786 @@
1.4 +/* -*- C++ -*-
1.5 + *
1.6 + * This file is a part of LEMON, a generic C++ optimization library
1.7 + *
1.8 + * Copyright (C) 2003-2010
1.9 + * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
1.10 + * (Egervary Research Group on Combinatorial Optimization, EGRES).
1.11 + *
1.12 + * Permission to use, modify and distribute this software is granted
1.13 + * provided that this copyright notice appears in all copies. For
1.14 + * precise terms see the accompanying LICENSE file.
1.15 + *
1.16 + * This software is provided "AS IS" with no warranty of any kind,
1.17 + * express or implied, and with no claim as to its suitability for any
1.18 + * purpose.
1.19 + *
1.20 + */
1.21 +
1.22 +#ifndef LEMON_MAX_CARDINALITY_SEARCH_H
1.23 +#define LEMON_MAX_CARDINALITY_SEARCH_H
1.24 +
1.25 +
1.26 +/// \ingroup search
1.27 +/// \file
1.28 +/// \brief Maximum cardinality search in undirected digraphs.
1.29 +
1.30 +#include <lemon/bin_heap.h>
1.31 +#include <lemon/bucket_heap.h>
1.32 +
1.33 +#include <lemon/error.h>
1.34 +#include <lemon/maps.h>
1.35 +
1.36 +#include <functional>
1.37 +
1.38 +namespace lemon {
1.39 +
1.40 + /// \brief Default traits class of MaxCardinalitySearch class.
1.41 + ///
1.42 + /// Default traits class of MaxCardinalitySearch class.
1.43 + /// \param Digraph Digraph type.
1.44 + /// \param CapacityMap Type of capacity map.
1.45 + template <typename GR, typename CAP>
1.46 + struct MaxCardinalitySearchDefaultTraits {
1.47 + /// The digraph type the algorithm runs on.
1.48 + typedef GR Digraph;
1.49 +
1.50 + template <typename CM>
1.51 + struct CapMapSelector {
1.52 +
1.53 + typedef CM CapacityMap;
1.54 +
1.55 + static CapacityMap *createCapacityMap(const Digraph& g) {
1.56 + return new CapacityMap(g);
1.57 + }
1.58 + };
1.59 +
1.60 + template <typename CM>
1.61 + struct CapMapSelector<ConstMap<CM, Const<int, 1> > > {
1.62 +
1.63 + typedef ConstMap<CM, Const<int, 1> > CapacityMap;
1.64 +
1.65 + static CapacityMap *createCapacityMap(const Digraph&) {
1.66 + return new CapacityMap;
1.67 + }
1.68 + };
1.69 +
1.70 + /// \brief The type of the map that stores the arc capacities.
1.71 + ///
1.72 + /// The type of the map that stores the arc capacities.
1.73 + /// It must meet the \ref concepts::ReadMap "ReadMap" concept.
1.74 + typedef typename CapMapSelector<CAP>::CapacityMap CapacityMap;
1.75 +
1.76 + /// \brief The type of the capacity of the arcs.
1.77 + typedef typename CapacityMap::Value Value;
1.78 +
1.79 + /// \brief Instantiates a CapacityMap.
1.80 + ///
1.81 + /// This function instantiates a \ref CapacityMap.
1.82 + /// \param digraph is the digraph, to which we would like to define
1.83 + /// the CapacityMap.
1.84 + static CapacityMap *createCapacityMap(const Digraph& digraph) {
1.85 + return CapMapSelector<CapacityMap>::createCapacityMap(digraph);
1.86 + }
1.87 +
1.88 + /// \brief The cross reference type used by heap.
1.89 + ///
1.90 + /// The cross reference type used by heap.
1.91 + /// Usually it is \c Digraph::NodeMap<int>.
1.92 + typedef typename Digraph::template NodeMap<int> HeapCrossRef;
1.93 +
1.94 + /// \brief Instantiates a HeapCrossRef.
1.95 + ///
1.96 + /// This function instantiates a \ref HeapCrossRef.
1.97 + /// \param digraph is the digraph, to which we would like to define the
1.98 + /// HeapCrossRef.
1.99 + static HeapCrossRef *createHeapCrossRef(const Digraph &digraph) {
1.100 + return new HeapCrossRef(digraph);
1.101 + }
1.102 +
1.103 + template <typename CapacityMap>
1.104 + struct HeapSelector {
1.105 + template <typename Value, typename Ref>
1.106 + struct Selector {
1.107 + typedef BinHeap<Value, Ref, std::greater<Value> > Heap;
1.108 + };
1.109 + };
1.110 +
1.111 + template <typename CapacityKey>
1.112 + struct HeapSelector<ConstMap<CapacityKey, Const<int, 1> > > {
1.113 + template <typename Value, typename Ref>
1.114 + struct Selector {
1.115 + typedef BucketHeap<Ref, false > Heap;
1.116 + };
1.117 + };
1.118 +
1.119 + /// \brief The heap type used by MaxCardinalitySearch algorithm.
1.120 + ///
1.121 + /// The heap type used by MaxCardinalitySearch algorithm. It should
1.122 + /// maximalize the priorities. The default heap type is
1.123 + /// the \ref BinHeap, but it is specialized when the
1.124 + /// CapacityMap is ConstMap<Digraph::Node, Const<int, 1> >
1.125 + /// to BucketHeap.
1.126 + ///
1.127 + /// \sa MaxCardinalitySearch
1.128 + typedef typename HeapSelector<CapacityMap>
1.129 + ::template Selector<Value, HeapCrossRef>
1.130 + ::Heap Heap;
1.131 +
1.132 + /// \brief Instantiates a Heap.
1.133 + ///
1.134 + /// This function instantiates a \ref Heap.
1.135 + /// \param crossref The cross reference of the heap.
1.136 + static Heap *createHeap(HeapCrossRef& crossref) {
1.137 + return new Heap(crossref);
1.138 + }
1.139 +
1.140 + /// \brief The type of the map that stores whether a node is processed.
1.141 + ///
1.142 + /// The type of the map that stores whether a node is processed.
1.143 + /// It must meet the \ref concepts::WriteMap "WriteMap" concept.
1.144 + /// By default it is a NullMap.
1.145 + typedef NullMap<typename Digraph::Node, bool> ProcessedMap;
1.146 +
1.147 + /// \brief Instantiates a ProcessedMap.
1.148 + ///
1.149 + /// This function instantiates a \ref ProcessedMap.
1.150 + /// \param digraph is the digraph, to which
1.151 + /// we would like to define the \ref ProcessedMap
1.152 +#ifdef DOXYGEN
1.153 + static ProcessedMap *createProcessedMap(const Digraph &digraph)
1.154 +#else
1.155 + static ProcessedMap *createProcessedMap(const Digraph &)
1.156 +#endif
1.157 + {
1.158 + return new ProcessedMap();
1.159 + }
1.160 +
1.161 + /// \brief The type of the map that stores the cardinalities of the nodes.
1.162 + ///
1.163 + /// The type of the map that stores the cardinalities of the nodes.
1.164 + /// It must meet the \ref concepts::WriteMap "WriteMap" concept.
1.165 + typedef typename Digraph::template NodeMap<Value> CardinalityMap;
1.166 +
1.167 + /// \brief Instantiates a CardinalityMap.
1.168 + ///
1.169 + /// This function instantiates a \ref CardinalityMap.
1.170 + /// \param digraph is the digraph, to which we would like to define the \ref
1.171 + /// CardinalityMap
1.172 + static CardinalityMap *createCardinalityMap(const Digraph &digraph) {
1.173 + return new CardinalityMap(digraph);
1.174 + }
1.175 +
1.176 +
1.177 + };
1.178 +
1.179 + /// \ingroup search
1.180 + ///
1.181 + /// \brief Maximum Cardinality Search algorithm class.
1.182 + ///
1.183 + /// This class provides an efficient implementation of Maximum Cardinality
1.184 + /// Search algorithm. The maximum cardinality search first chooses any
1.185 + /// node of the digraph. Then every time it chooses one unprocessed node
1.186 + /// with maximum cardinality, i.e the sum of capacities on out arcs to the nodes
1.187 + /// which were previusly processed.
1.188 + /// If there is a cut in the digraph the algorithm should choose
1.189 + /// again any unprocessed node of the digraph.
1.190 +
1.191 + /// The arc capacities are passed to the algorithm using a
1.192 + /// \ref concepts::ReadMap "ReadMap", so it is easy to change it to any
1.193 + /// kind of capacity.
1.194 + ///
1.195 + /// The type of the capacity is determined by the \ref
1.196 + /// concepts::ReadMap::Value "Value" of the capacity map.
1.197 + ///
1.198 + /// It is also possible to change the underlying priority heap.
1.199 + ///
1.200 + ///
1.201 + /// \param GR The digraph type the algorithm runs on. The value of
1.202 + /// Digraph is not used directly by the search algorithm, it
1.203 + /// is only passed to \ref MaxCardinalitySearchDefaultTraits.
1.204 + /// \param CAP This read-only ArcMap determines the capacities of
1.205 + /// the arcs. It is read once for each arc, so the map may involve in
1.206 + /// relatively time consuming process to compute the arc capacity if
1.207 + /// it is necessary. The default map type is \ref
1.208 + /// ConstMap "ConstMap<concepts::Digraph::Arc, Const<int,1> >". The value
1.209 + /// of CapacityMap is not used directly by search algorithm, it is only
1.210 + /// passed to \ref MaxCardinalitySearchDefaultTraits.
1.211 + /// \param TR Traits class to set various data types used by the
1.212 + /// algorithm. The default traits class is
1.213 + /// \ref MaxCardinalitySearchDefaultTraits
1.214 + /// "MaxCardinalitySearchDefaultTraits<GR, CAP>".
1.215 + /// See \ref MaxCardinalitySearchDefaultTraits
1.216 + /// for the documentation of a MaxCardinalitySearch traits class.
1.217 +
1.218 +#ifdef DOXYGEN
1.219 + template <typename GR, typename CAP, typename TR>
1.220 +#else
1.221 + template <typename GR, typename CAP =
1.222 + ConstMap<typename GR::Arc, Const<int,1> >,
1.223 + typename TR =
1.224 + MaxCardinalitySearchDefaultTraits<GR, CAP> >
1.225 +#endif
1.226 + class MaxCardinalitySearch {
1.227 + public:
1.228 +
1.229 + typedef TR Traits;
1.230 + ///The type of the underlying digraph.
1.231 + typedef typename Traits::Digraph Digraph;
1.232 +
1.233 + ///The type of the capacity of the arcs.
1.234 + typedef typename Traits::CapacityMap::Value Value;
1.235 + ///The type of the map that stores the arc capacities.
1.236 + typedef typename Traits::CapacityMap CapacityMap;
1.237 + ///The type of the map indicating if a node is processed.
1.238 + typedef typename Traits::ProcessedMap ProcessedMap;
1.239 + ///The type of the map that stores the cardinalities of the nodes.
1.240 + typedef typename Traits::CardinalityMap CardinalityMap;
1.241 + ///The cross reference type used for the current heap.
1.242 + typedef typename Traits::HeapCrossRef HeapCrossRef;
1.243 + ///The heap type used by the algorithm. It maximizes the priorities.
1.244 + typedef typename Traits::Heap Heap;
1.245 + private:
1.246 + // Pointer to the underlying digraph.
1.247 + const Digraph *_graph;
1.248 + // Pointer to the capacity map
1.249 + const CapacityMap *_capacity;
1.250 + // Indicates if \ref _capacity is locally allocated (\c true) or not.
1.251 + bool local_capacity;
1.252 + // Pointer to the map of cardinality.
1.253 + CardinalityMap *_cardinality;
1.254 + // Indicates if \ref _cardinality is locally allocated (\c true) or not.
1.255 + bool local_cardinality;
1.256 + // Pointer to the map of processed status of the nodes.
1.257 + ProcessedMap *_processed;
1.258 + // Indicates if \ref _processed is locally allocated (\c true) or not.
1.259 + bool local_processed;
1.260 + // Pointer to the heap cross references.
1.261 + HeapCrossRef *_heap_cross_ref;
1.262 + // Indicates if \ref _heap_cross_ref is locally allocated (\c true) or not.
1.263 + bool local_heap_cross_ref;
1.264 + // Pointer to the heap.
1.265 + Heap *_heap;
1.266 + // Indicates if \ref _heap is locally allocated (\c true) or not.
1.267 + bool local_heap;
1.268 +
1.269 + public :
1.270 +
1.271 + typedef MaxCardinalitySearch Create;
1.272 +
1.273 + ///\name Named template parameters
1.274 +
1.275 + ///@{
1.276 +
1.277 + template <class T>
1.278 + struct DefCapacityMapTraits : public Traits {
1.279 + typedef T CapacityMap;
1.280 + static CapacityMap *createCapacityMap(const Digraph &) {
1.281 + LEMON_ASSERT(false,"Uninitialized parameter.");
1.282 + return 0;
1.283 + }
1.284 + };
1.285 + /// \brief \ref named-templ-param "Named parameter" for setting
1.286 + /// CapacityMap type
1.287 + ///
1.288 + /// \ref named-templ-param "Named parameter" for setting CapacityMap type
1.289 + /// for the algorithm.
1.290 + template <class T>
1.291 + struct SetCapacityMap
1.292 + : public MaxCardinalitySearch<Digraph, CapacityMap,
1.293 + DefCapacityMapTraits<T> > {
1.294 + typedef MaxCardinalitySearch<Digraph, CapacityMap,
1.295 + DefCapacityMapTraits<T> > Create;
1.296 + };
1.297 +
1.298 + template <class T>
1.299 + struct DefCardinalityMapTraits : public Traits {
1.300 + typedef T CardinalityMap;
1.301 + static CardinalityMap *createCardinalityMap(const Digraph &)
1.302 + {
1.303 + LEMON_ASSERT(false,"Uninitialized parameter.");
1.304 + return 0;
1.305 + }
1.306 + };
1.307 + /// \brief \ref named-templ-param "Named parameter" for setting
1.308 + /// CardinalityMap type
1.309 + ///
1.310 + /// \ref named-templ-param "Named parameter" for setting CardinalityMap
1.311 + /// type for the algorithm.
1.312 + template <class T>
1.313 + struct SetCardinalityMap
1.314 + : public MaxCardinalitySearch<Digraph, CapacityMap,
1.315 + DefCardinalityMapTraits<T> > {
1.316 + typedef MaxCardinalitySearch<Digraph, CapacityMap,
1.317 + DefCardinalityMapTraits<T> > Create;
1.318 + };
1.319 +
1.320 + template <class T>
1.321 + struct DefProcessedMapTraits : public Traits {
1.322 + typedef T ProcessedMap;
1.323 + static ProcessedMap *createProcessedMap(const Digraph &) {
1.324 + LEMON_ASSERT(false,"Uninitialized parameter.");
1.325 + return 0;
1.326 + }
1.327 + };
1.328 + /// \brief \ref named-templ-param "Named parameter" for setting
1.329 + /// ProcessedMap type
1.330 + ///
1.331 + /// \ref named-templ-param "Named parameter" for setting ProcessedMap type
1.332 + /// for the algorithm.
1.333 + template <class T>
1.334 + struct SetProcessedMap
1.335 + : public MaxCardinalitySearch<Digraph, CapacityMap,
1.336 + DefProcessedMapTraits<T> > {
1.337 + typedef MaxCardinalitySearch<Digraph, CapacityMap,
1.338 + DefProcessedMapTraits<T> > Create;
1.339 + };
1.340 +
1.341 + template <class H, class CR>
1.342 + struct DefHeapTraits : public Traits {
1.343 + typedef CR HeapCrossRef;
1.344 + typedef H Heap;
1.345 + static HeapCrossRef *createHeapCrossRef(const Digraph &) {
1.346 + LEMON_ASSERT(false,"Uninitialized parameter.");
1.347 + return 0;
1.348 + }
1.349 + static Heap *createHeap(HeapCrossRef &) {
1.350 + LEMON_ASSERT(false,"Uninitialized parameter.");
1.351 + return 0;
1.352 + }
1.353 + };
1.354 + /// \brief \ref named-templ-param "Named parameter" for setting heap
1.355 + /// and cross reference type
1.356 + ///
1.357 + /// \ref named-templ-param "Named parameter" for setting heap and cross
1.358 + /// reference type for the algorithm.
1.359 + template <class H, class CR = typename Digraph::template NodeMap<int> >
1.360 + struct SetHeap
1.361 + : public MaxCardinalitySearch<Digraph, CapacityMap,
1.362 + DefHeapTraits<H, CR> > {
1.363 + typedef MaxCardinalitySearch< Digraph, CapacityMap,
1.364 + DefHeapTraits<H, CR> > Create;
1.365 + };
1.366 +
1.367 + template <class H, class CR>
1.368 + struct DefStandardHeapTraits : public Traits {
1.369 + typedef CR HeapCrossRef;
1.370 + typedef H Heap;
1.371 + static HeapCrossRef *createHeapCrossRef(const Digraph &digraph) {
1.372 + return new HeapCrossRef(digraph);
1.373 + }
1.374 + static Heap *createHeap(HeapCrossRef &crossref) {
1.375 + return new Heap(crossref);
1.376 + }
1.377 + };
1.378 +
1.379 + /// \brief \ref named-templ-param "Named parameter" for setting heap and
1.380 + /// cross reference type with automatic allocation
1.381 + ///
1.382 + /// \ref named-templ-param "Named parameter" for setting heap and cross
1.383 + /// reference type. It can allocate the heap and the cross reference
1.384 + /// object if the cross reference's constructor waits for the digraph as
1.385 + /// parameter and the heap's constructor waits for the cross reference.
1.386 + template <class H, class CR = typename Digraph::template NodeMap<int> >
1.387 + struct SetStandardHeap
1.388 + : public MaxCardinalitySearch<Digraph, CapacityMap,
1.389 + DefStandardHeapTraits<H, CR> > {
1.390 + typedef MaxCardinalitySearch<Digraph, CapacityMap,
1.391 + DefStandardHeapTraits<H, CR> >
1.392 + Create;
1.393 + };
1.394 +
1.395 + ///@}
1.396 +
1.397 +
1.398 + protected:
1.399 +
1.400 + MaxCardinalitySearch() {}
1.401 +
1.402 + public:
1.403 +
1.404 + /// \brief Constructor.
1.405 + ///
1.406 + ///\param digraph the digraph the algorithm will run on.
1.407 + ///\param capacity the capacity map used by the algorithm.
1.408 + ///When no capacity map given, a constant 1 capacity map will
1.409 + ///be allocated.
1.410 +#ifdef DOXYGEN
1.411 + MaxCardinalitySearch(const Digraph& digraph,
1.412 + const CapacityMap& capacity=0 ) :
1.413 +#else
1.414 + MaxCardinalitySearch(const Digraph& digraph,
1.415 + const CapacityMap& capacity=*static_cast<const CapacityMap*>(0) ) :
1.416 +#endif
1.417 + _graph(&digraph),
1.418 + _capacity(&capacity), local_capacity(false),
1.419 + _cardinality(0), local_cardinality(false),
1.420 + _processed(0), local_processed(false),
1.421 + _heap_cross_ref(0), local_heap_cross_ref(false),
1.422 + _heap(0), local_heap(false)
1.423 + { }
1.424 +
1.425 + /// \brief Destructor.
1.426 + ~MaxCardinalitySearch() {
1.427 + if(local_capacity) delete _capacity;
1.428 + if(local_cardinality) delete _cardinality;
1.429 + if(local_processed) delete _processed;
1.430 + if(local_heap_cross_ref) delete _heap_cross_ref;
1.431 + if(local_heap) delete _heap;
1.432 + }
1.433 +
1.434 + /// \brief Sets the capacity map.
1.435 + ///
1.436 + /// Sets the capacity map.
1.437 + /// \return <tt> (*this) </tt>
1.438 + MaxCardinalitySearch &capacityMap(const CapacityMap &m) {
1.439 + if (local_capacity) {
1.440 + delete _capacity;
1.441 + local_capacity=false;
1.442 + }
1.443 + _capacity=&m;
1.444 + return *this;
1.445 + }
1.446 +
1.447 + /// \brief Returns a const reference to the capacity map.
1.448 + ///
1.449 + /// Returns a const reference to the capacity map used by
1.450 + /// the algorithm.
1.451 + const CapacityMap &capacityMap() const {
1.452 + return *_capacity;
1.453 + }
1.454 +
1.455 + /// \brief Sets the map storing the cardinalities calculated by the
1.456 + /// algorithm.
1.457 + ///
1.458 + /// Sets the map storing the cardinalities calculated by the algorithm.
1.459 + /// If you don't use this function before calling \ref run(),
1.460 + /// it will allocate one. The destuctor deallocates this
1.461 + /// automatically allocated map, of course.
1.462 + /// \return <tt> (*this) </tt>
1.463 + MaxCardinalitySearch &cardinalityMap(CardinalityMap &m) {
1.464 + if(local_cardinality) {
1.465 + delete _cardinality;
1.466 + local_cardinality=false;
1.467 + }
1.468 + _cardinality = &m;
1.469 + return *this;
1.470 + }
1.471 +
1.472 + /// \brief Sets the map storing the processed nodes.
1.473 + ///
1.474 + /// Sets the map storing the processed nodes.
1.475 + /// If you don't use this function before calling \ref run(),
1.476 + /// it will allocate one. The destuctor deallocates this
1.477 + /// automatically allocated map, of course.
1.478 + /// \return <tt> (*this) </tt>
1.479 + MaxCardinalitySearch &processedMap(ProcessedMap &m)
1.480 + {
1.481 + if(local_processed) {
1.482 + delete _processed;
1.483 + local_processed=false;
1.484 + }
1.485 + _processed = &m;
1.486 + return *this;
1.487 + }
1.488 +
1.489 + /// \brief Returns a const reference to the cardinality map.
1.490 + ///
1.491 + /// Returns a const reference to the cardinality map used by
1.492 + /// the algorithm.
1.493 + const ProcessedMap &processedMap() const {
1.494 + return *_processed;
1.495 + }
1.496 +
1.497 + /// \brief Sets the heap and the cross reference used by algorithm.
1.498 + ///
1.499 + /// Sets the heap and the cross reference used by algorithm.
1.500 + /// If you don't use this function before calling \ref run(),
1.501 + /// it will allocate one. The destuctor deallocates this
1.502 + /// automatically allocated map, of course.
1.503 + /// \return <tt> (*this) </tt>
1.504 + MaxCardinalitySearch &heap(Heap& hp, HeapCrossRef &cr) {
1.505 + if(local_heap_cross_ref) {
1.506 + delete _heap_cross_ref;
1.507 + local_heap_cross_ref = false;
1.508 + }
1.509 + _heap_cross_ref = &cr;
1.510 + if(local_heap) {
1.511 + delete _heap;
1.512 + local_heap = false;
1.513 + }
1.514 + _heap = &hp;
1.515 + return *this;
1.516 + }
1.517 +
1.518 + /// \brief Returns a const reference to the heap.
1.519 + ///
1.520 + /// Returns a const reference to the heap used by
1.521 + /// the algorithm.
1.522 + const Heap &heap() const {
1.523 + return *_heap;
1.524 + }
1.525 +
1.526 + /// \brief Returns a const reference to the cross reference.
1.527 + ///
1.528 + /// Returns a const reference to the cross reference
1.529 + /// of the heap.
1.530 + const HeapCrossRef &heapCrossRef() const {
1.531 + return *_heap_cross_ref;
1.532 + }
1.533 +
1.534 + private:
1.535 +
1.536 + typedef typename Digraph::Node Node;
1.537 + typedef typename Digraph::NodeIt NodeIt;
1.538 + typedef typename Digraph::Arc Arc;
1.539 + typedef typename Digraph::InArcIt InArcIt;
1.540 +
1.541 + void create_maps() {
1.542 + if(!_capacity) {
1.543 + local_capacity = true;
1.544 + _capacity = Traits::createCapacityMap(*_graph);
1.545 + }
1.546 + if(!_cardinality) {
1.547 + local_cardinality = true;
1.548 + _cardinality = Traits::createCardinalityMap(*_graph);
1.549 + }
1.550 + if(!_processed) {
1.551 + local_processed = true;
1.552 + _processed = Traits::createProcessedMap(*_graph);
1.553 + }
1.554 + if (!_heap_cross_ref) {
1.555 + local_heap_cross_ref = true;
1.556 + _heap_cross_ref = Traits::createHeapCrossRef(*_graph);
1.557 + }
1.558 + if (!_heap) {
1.559 + local_heap = true;
1.560 + _heap = Traits::createHeap(*_heap_cross_ref);
1.561 + }
1.562 + }
1.563 +
1.564 + void finalizeNodeData(Node node, Value capacity) {
1.565 + _processed->set(node, true);
1.566 + _cardinality->set(node, capacity);
1.567 + }
1.568 +
1.569 + public:
1.570 + /// \name Execution control
1.571 + /// The simplest way to execute the algorithm is to use
1.572 + /// one of the member functions called \ref run().
1.573 + /// \n
1.574 + /// If you need more control on the execution,
1.575 + /// first you must call \ref init(), then you can add several source nodes
1.576 + /// with \ref addSource().
1.577 + /// Finally \ref start() will perform the computation.
1.578 +
1.579 + ///@{
1.580 +
1.581 + /// \brief Initializes the internal data structures.
1.582 + ///
1.583 + /// Initializes the internal data structures, and clears the heap.
1.584 + void init() {
1.585 + create_maps();
1.586 + _heap->clear();
1.587 + for (NodeIt it(*_graph) ; it != INVALID ; ++it) {
1.588 + _processed->set(it, false);
1.589 + _heap_cross_ref->set(it, Heap::PRE_HEAP);
1.590 + }
1.591 + }
1.592 +
1.593 + /// \brief Adds a new source node.
1.594 + ///
1.595 + /// Adds a new source node to the priority heap.
1.596 + ///
1.597 + /// It checks if the node has not yet been added to the heap.
1.598 + void addSource(Node source, Value capacity = 0) {
1.599 + if(_heap->state(source) == Heap::PRE_HEAP) {
1.600 + _heap->push(source, capacity);
1.601 + }
1.602 + }
1.603 +
1.604 + /// \brief Processes the next node in the priority heap
1.605 + ///
1.606 + /// Processes the next node in the priority heap.
1.607 + ///
1.608 + /// \return The processed node.
1.609 + ///
1.610 + /// \warning The priority heap must not be empty!
1.611 + Node processNextNode() {
1.612 + Node node = _heap->top();
1.613 + finalizeNodeData(node, _heap->prio());
1.614 + _heap->pop();
1.615 +
1.616 + for (InArcIt it(*_graph, node); it != INVALID; ++it) {
1.617 + Node source = _graph->source(it);
1.618 + switch (_heap->state(source)) {
1.619 + case Heap::PRE_HEAP:
1.620 + _heap->push(source, (*_capacity)[it]);
1.621 + break;
1.622 + case Heap::IN_HEAP:
1.623 + _heap->decrease(source, (*_heap)[source] + (*_capacity)[it]);
1.624 + break;
1.625 + case Heap::POST_HEAP:
1.626 + break;
1.627 + }
1.628 + }
1.629 + return node;
1.630 + }
1.631 +
1.632 + /// \brief Next node to be processed.
1.633 + ///
1.634 + /// Next node to be processed.
1.635 + ///
1.636 + /// \return The next node to be processed or INVALID if the
1.637 + /// priority heap is empty.
1.638 + Node nextNode() {
1.639 + return !_heap->empty() ? _heap->top() : INVALID;
1.640 + }
1.641 +
1.642 + /// \brief Returns \c false if there are nodes
1.643 + /// to be processed in the priority heap
1.644 + ///
1.645 + /// Returns \c false if there are nodes
1.646 + /// to be processed in the priority heap
1.647 + bool emptyQueue() { return _heap->empty(); }
1.648 + /// \brief Returns the number of the nodes to be processed
1.649 + /// in the priority heap
1.650 + ///
1.651 + /// Returns the number of the nodes to be processed in the priority heap
1.652 + int emptySize() { return _heap->size(); }
1.653 +
1.654 + /// \brief Executes the algorithm.
1.655 + ///
1.656 + /// Executes the algorithm.
1.657 + ///
1.658 + ///\pre init() must be called and at least one node should be added
1.659 + /// with addSource() before using this function.
1.660 + ///
1.661 + /// This method runs the Maximum Cardinality Search algorithm from the
1.662 + /// source node(s).
1.663 + void start() {
1.664 + while ( !_heap->empty() ) processNextNode();
1.665 + }
1.666 +
1.667 + /// \brief Executes the algorithm until \c dest is reached.
1.668 + ///
1.669 + /// Executes the algorithm until \c dest is reached.
1.670 + ///
1.671 + /// \pre init() must be called and at least one node should be added
1.672 + /// with addSource() before using this function.
1.673 + ///
1.674 + /// This method runs the %MaxCardinalitySearch algorithm from the source
1.675 + /// nodes.
1.676 + void start(Node dest) {
1.677 + while ( !_heap->empty() && _heap->top()!=dest ) processNextNode();
1.678 + if ( !_heap->empty() ) finalizeNodeData(_heap->top(), _heap->prio());
1.679 + }
1.680 +
1.681 + /// \brief Executes the algorithm until a condition is met.
1.682 + ///
1.683 + /// Executes the algorithm until a condition is met.
1.684 + ///
1.685 + /// \pre init() must be called and at least one node should be added
1.686 + /// with addSource() before using this function.
1.687 + ///
1.688 + /// \param nm must be a bool (or convertible) node map. The algorithm
1.689 + /// will stop when it reaches a node \c v with <tt>nm[v]==true</tt>.
1.690 + template <typename NodeBoolMap>
1.691 + void start(const NodeBoolMap &nm) {
1.692 + while ( !_heap->empty() && !nm[_heap->top()] ) processNextNode();
1.693 + if ( !_heap->empty() ) finalizeNodeData(_heap->top(),_heap->prio());
1.694 + }
1.695 +
1.696 + /// \brief Runs the maximum cardinality search algorithm from node \c s.
1.697 + ///
1.698 + /// This method runs the %MaxCardinalitySearch algorithm from a root
1.699 + /// node \c s.
1.700 + ///
1.701 + ///\note d.run(s) is just a shortcut of the following code.
1.702 + ///\code
1.703 + /// d.init();
1.704 + /// d.addSource(s);
1.705 + /// d.start();
1.706 + ///\endcode
1.707 + void run(Node s) {
1.708 + init();
1.709 + addSource(s);
1.710 + start();
1.711 + }
1.712 +
1.713 + /// \brief Runs the maximum cardinality search algorithm for the
1.714 + /// whole digraph.
1.715 + ///
1.716 + /// This method runs the %MaxCardinalitySearch algorithm from all
1.717 + /// unprocessed node of the digraph.
1.718 + ///
1.719 + ///\note d.run(s) is just a shortcut of the following code.
1.720 + ///\code
1.721 + /// d.init();
1.722 + /// for (NodeIt it(digraph); it != INVALID; ++it) {
1.723 + /// if (!d.reached(it)) {
1.724 + /// d.addSource(s);
1.725 + /// d.start();
1.726 + /// }
1.727 + /// }
1.728 + ///\endcode
1.729 + void run() {
1.730 + init();
1.731 + for (NodeIt it(*_graph); it != INVALID; ++it) {
1.732 + if (!reached(it)) {
1.733 + addSource(it);
1.734 + start();
1.735 + }
1.736 + }
1.737 + }
1.738 +
1.739 + ///@}
1.740 +
1.741 + /// \name Query Functions
1.742 + /// The results of the maximum cardinality search algorithm can be
1.743 + /// obtained using these functions.
1.744 + /// \n
1.745 + /// Before the use of these functions, either run() or start() must be
1.746 + /// called.
1.747 +
1.748 + ///@{
1.749 +
1.750 + /// \brief The cardinality of a node.
1.751 + ///
1.752 + /// Returns the cardinality of a node.
1.753 + /// \pre \ref run() must be called before using this function.
1.754 + /// \warning If node \c v in unreachable from the root the return value
1.755 + /// of this funcion is undefined.
1.756 + Value cardinality(Node node) const { return (*_cardinality)[node]; }
1.757 +
1.758 + /// \brief The current cardinality of a node.
1.759 + ///
1.760 + /// Returns the current cardinality of a node.
1.761 + /// \pre the given node should be reached but not processed
1.762 + Value currentCardinality(Node node) const { return (*_heap)[node]; }
1.763 +
1.764 + /// \brief Returns a reference to the NodeMap of cardinalities.
1.765 + ///
1.766 + /// Returns a reference to the NodeMap of cardinalities. \pre \ref run()
1.767 + /// must be called before using this function.
1.768 + const CardinalityMap &cardinalityMap() const { return *_cardinality;}
1.769 +
1.770 + /// \brief Checks if a node is reachable from the root.
1.771 + ///
1.772 + /// Returns \c true if \c v is reachable from the root.
1.773 + /// \warning The source nodes are initated as unreached.
1.774 + /// \pre \ref run() must be called before using this function.
1.775 + bool reached(Node v) { return (*_heap_cross_ref)[v] != Heap::PRE_HEAP; }
1.776 +
1.777 + /// \brief Checks if a node is processed.
1.778 + ///
1.779 + /// Returns \c true if \c v is processed, i.e. the shortest
1.780 + /// path to \c v has already found.
1.781 + /// \pre \ref run() must be called before using this function.
1.782 + bool processed(Node v) { return (*_heap_cross_ref)[v] == Heap::POST_HEAP; }
1.783 +
1.784 + ///@}
1.785 + };
1.786 +
1.787 +}
1.788 +
1.789 +#endif