Ticket #175: circ_b4fbf36feb57.patch
File circ_b4fbf36feb57.patch, 20.9 KB (added by , 12 years ago) 


lemon/circulation.h
# HG changeset patch # User Peter Kovacs <kpeter@inf.elte.hu> # Date 1228053065 3600 # Node ID b4fbf36feb573d42ed32a2ef8d24dc99c53c0fdc # Parent ef7c870325932290fca520deacfe38191739293c Many doc improvements for Circulation (#175)  More precise doc for members.  Several doc fixes.  Add doc for public types.  Better formulations.  Add useful notes to the problem description.  Use supply instead of excess in the doc.  Hide the doc of the traits class parameter.  Use \tparam for template parameters. diff git a/lemon/circulation.h b/lemon/circulation.h
a b 19 19 #ifndef LEMON_CIRCULATION_H 20 20 #define LEMON_CIRCULATION_H 21 21 22 #include <iostream>23 #include <queue>24 22 #include <lemon/tolerance.h> 25 23 #include <lemon/elevator.h> 26 24 27 25 ///\ingroup max_flow 28 26 ///\file 29 ///\brief Push prelabel algorithm for finding a feasible circulation.27 ///\brief Pushrelabel algorithm for finding a feasible circulation. 30 28 /// 31 29 namespace lemon { 32 30 33 31 /// \brief Default traits class of Circulation class. 34 32 /// 35 33 /// Default traits class of Circulation class. 36 /// \param _Graph Digraph type. 37 /// \param _CapacityMap Type of capacity map. 38 template <typename _Graph, typename _LCapMap, 34 /// \tparam _Diraph Digraph type. 35 /// \tparam _LCapMap Lower bound capacity map type. 36 /// \tparam _UCapMap Upper bound capacity map type. 37 /// \tparam _DeltaMap Delta map type. 38 template <typename _Diraph, typename _LCapMap, 39 39 typename _UCapMap, typename _DeltaMap> 40 40 struct CirculationDefaultTraits { 41 41 42 /// \brief The digraph typethe algorithm runs on.43 typedef _ Graph Digraph;42 /// \brief The type of the digraph the algorithm runs on. 43 typedef _Diraph Digraph; 44 44 45 45 /// \brief The type of the map that stores the circulation lower 46 46 /// bound. … … 56 56 /// It must meet the \ref concepts::ReadMap "ReadMap" concept. 57 57 typedef _UCapMap UCapMap; 58 58 59 /// \brief The type of the map that stores the upper bound of60 /// node excess.59 /// \brief The type of the map that stores the lower bound for 60 /// the supply of the nodes. 61 61 /// 62 /// The type of the map that stores the lower bound of node63 /// excess. It must meet the \ref concepts::ReadMap "ReadMap"62 /// The type of the map that stores the lower bound for the supply 63 /// of the nodes. It must meet the \ref concepts::ReadMap "ReadMap" 64 64 /// concept. 65 65 typedef _DeltaMap DeltaMap; 66 66 67 /// \brief The type of the length of the arcs.67 /// \brief The type of the flow values. 68 68 typedef typename DeltaMap::Value Value; 69 69 70 /// \brief The map typethat stores the flow values.70 /// \brief The type of the map that stores the flow values. 71 71 /// 72 /// The map typethat stores the flow values.72 /// The type of the map that stores the flow values. 73 73 /// It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept. 74 74 typedef typename Digraph::template ArcMap<Value> FlowMap; 75 75 … … 82 82 return new FlowMap(digraph); 83 83 } 84 84 85 /// \brief The ele avator type used by Circulationalgorithm.85 /// \brief The elevator type used by the algorithm. 86 86 /// 87 /// The elevator type used by Circulationalgorithm.87 /// The elevator type used by the algorithm. 88 88 /// 89 89 /// \sa Elevator 90 90 /// \sa LinkedElevator … … 92 92 93 93 /// \brief Instantiates an Elevator. 94 94 /// 95 /// This function instantiates a \ref Elevator.95 /// This function instantiates an \ref Elevator. 96 96 /// \param digraph The digraph, to which we would like to define 97 97 /// the elevator. 98 98 /// \param max_level The maximum level of the elevator. … … 107 107 108 108 }; 109 109 110 ///Pushrelabel algorithm for the Network Circulation Problem. 110 /** 111 \brief Pushrelabel algorithm for the network circulation problem. 111 112 112 /**113 113 \ingroup max_flow 114 This class implements a pushrelabel algorithm 115 or the Network Circulation Problem. 114 This class implements a pushrelabel algorithm for the network 115 circulation problem. 116 It is to find a feasible circulation when lower and upper bounds 117 are given for the flow values on the arcs and lower bounds 118 are given for the supply values of the nodes. 119 116 120 The exact formulation of this problem is the following. 117 \f[\sum_{e\in\rho(v)}x(e)\sum_{e\in\delta(v)}x(e)\leq 118 delta(v)\quad \forall v\in V \f] 119 \f[ lo(e)\leq x(e) \leq up(e) \quad \forall e\in E \f] 121 Let \f$G=(V,A)\f$ be a digraph, 122 \f$lower, upper: A\rightarrow\mathbf{R}^+_0\f$, 123 \f$delta: V\rightarrow\mathbf{R}\f$. Find a feasible circulation 124 \f$f: A\rightarrow\mathbf{R}^+_0\f$ so that 125 \f[ \sum_{a\in\delta_{out}(v)} f(a)  \sum_{a\in\delta_{in}(v)} f(a) 126 \geq delta(v) \quad \forall v\in V, \f] 127 \f[ lower(a)\leq f(a) \leq upper(a) \quad \forall a\in A. \f] 128 \note \f$delta(v)\f$ specifies a lower bound for the supply of node 129 \f$v\f$. It can be either positive or negative, however note that 130 \f$\sum_{v\in V}delta(v)\f$ should be zero or negative in order to 131 have a feasible solution. 132 133 \note A special case of this problem is when 134 \f$\sum_{v\in V}delta(v) = 0\f$. Then the supply of each node \f$v\f$ 135 will be \e equal \e to \f$delta(v)\f$, if a circulation can be found. 136 Thus a feasible solution for the 137 \ref min_cost_flow "minimum cost flow" problem can be calculated 138 in this way. 139 140 \tparam _Digraph The type of the digraph the algorithm runs on. 141 \tparam _LCapMap The type of the lower bound capacity map. The default 142 map type is \ref concepts::Digraph::ArcMap "_Digraph::ArcMap<int>". 143 \tparam _UCapMap The type of the upper bound capacity map. The default 144 map type is \c _LCapMap. 145 \tparam _DeltaMap The type of the map that stores the lower bound 146 for the supply of the nodes. The default map type is 147 \c _Digraph::ArcMap<_UCapMap::Value>. 120 148 */ 121 template<class _Graph, 122 class _LCapMap=typename _Graph::template ArcMap<int>, 123 class _UCapMap=_LCapMap, 124 class _DeltaMap=typename _Graph::template NodeMap< 125 typename _UCapMap::Value>, 126 class _Traits=CirculationDefaultTraits<_Graph, _LCapMap, 127 _UCapMap, _DeltaMap> > 149 #ifdef DOXYGEN 150 template< typename _Digraph, 151 typename _LCapMap, 152 typename _UCapMap, 153 typename _DeltaMap, 154 typename _Traits > 155 #else 156 template< typename _Digraph, 157 typename _LCapMap = typename _Digraph::template ArcMap<int>, 158 typename _UCapMap = _LCapMap, 159 typename _DeltaMap = typename _Digraph:: 160 template NodeMap<typename _UCapMap::Value>, 161 typename _Traits=CirculationDefaultTraits<_Digraph, _LCapMap, 162 _UCapMap, _DeltaMap> > 163 #endif 128 164 class Circulation { 165 public: 129 166 167 ///The \ref CirculationDefaultTraits "traits class" of the algorithm. 130 168 typedef _Traits Traits; 169 ///The type of the digraph the algorithm runs on. 131 170 typedef typename Traits::Digraph Digraph; 132 TEMPLATE_DIGRAPH_TYPEDEFS(Digraph); 133 171 ///The type of the flow values. 134 172 typedef typename Traits::Value Value; 135 173 174 /// The type of the lower bound capacity map. 136 175 typedef typename Traits::LCapMap LCapMap; 176 /// The type of the upper bound capacity map. 137 177 typedef typename Traits::UCapMap UCapMap; 178 /// \brief The type of the map that stores the lower bound for 179 /// the supply of the nodes. 138 180 typedef typename Traits::DeltaMap DeltaMap; 181 ///The type of the flow map. 139 182 typedef typename Traits::FlowMap FlowMap; 183 184 ///The type of the elevator. 140 185 typedef typename Traits::Elevator Elevator; 186 ///The type of the tolerance. 141 187 typedef typename Traits::Tolerance Tolerance; 142 188 143 typedef typename Digraph::template NodeMap<Value> ExcessMap; 189 private: 190 191 TEMPLATE_DIGRAPH_TYPEDEFS(Digraph); 144 192 145 193 const Digraph &_g; 146 194 int _node_num; … … 155 203 Elevator* _level; 156 204 bool _local_level; 157 205 206 typedef typename Digraph::template NodeMap<Value> ExcessMap; 158 207 ExcessMap* _excess; 159 208 160 209 Tolerance _tol; … … 164 213 165 214 typedef Circulation Create; 166 215 167 ///\name Named template parameters216 ///\name Named Template Parameters 168 217 169 218 ///@{ 170 219 … … 181 230 /// FlowMap type 182 231 /// 183 232 /// \ref namedtemplparam "Named parameter" for setting FlowMap 184 /// type 233 /// type. 185 234 template <typename _FlowMap> 186 235 struct SetFlowMap 187 236 : public Circulation<Digraph, LCapMap, UCapMap, DeltaMap, … … 203 252 /// Elevator type 204 253 /// 205 254 /// \ref namedtemplparam "Named parameter" for setting Elevator 206 /// type 255 /// type. If this named parameter is used, then an external 256 /// elevator object must be passed to the algorithm using the 257 /// \ref elevator(Elevator&) "elevator()" function before calling 258 /// \ref run() or \ref init(). 259 /// \sa SetStandardElevator 207 260 template <typename _Elevator> 208 261 struct SetElevator 209 262 : public Circulation<Digraph, LCapMap, UCapMap, DeltaMap, … … 221 274 }; 222 275 223 276 /// \brief \ref namedtemplparam "Named parameter" for setting 224 /// Elevator type 277 /// Elevator type with automatic allocation 225 278 /// 226 279 /// \ref namedtemplparam "Named parameter" for setting Elevator 227 /// type. The Elevator should be standard constructor interface, ie. 228 /// the digraph and the maximum level should be passed to it. 280 /// type with automatic allocation. 281 /// The Elevator should have standard constructor interface to be 282 /// able to automatically created by the algorithm (i.e. the 283 /// digraph and the maximum level should be passed to it). 284 /// However an external elevator object could also be passed to the 285 /// algorithm with the \ref elevator(Elevator&) "elevator()" function 286 /// before calling \ref run() or \ref init(). 287 /// \sa SetElevator 229 288 template <typename _Elevator> 230 289 struct SetStandardElevator 231 290 : public Circulation<Digraph, LCapMap, UCapMap, DeltaMap, … … 248 307 /// \param g The digraph the algorithm runs on. 249 308 /// \param lo The lower bound capacity of the arcs. 250 309 /// \param up The upper bound capacity of the arcs. 251 /// \param delta The lower bound on node excess.310 /// \param delta The lower bound for the supply of the nodes. 252 311 Circulation(const Digraph &g,const LCapMap &lo, 253 312 const UCapMap &up,const DeltaMap &delta) 254 313 : _g(g), _node_num(), 255 314 _lo(&lo),_up(&up),_delta(&delta),_flow(0),_local_flow(false), 256 315 _level(0), _local_level(false), _excess(0), _el() {} 257 316 258 /// Destr cutor.317 /// Destructor. 259 318 ~Circulation() { 260 319 destroyStructures(); 261 320 } 321 262 322 263 323 private: 264 324 … … 295 355 /// Sets the lower bound capacity map. 296 356 297 357 /// Sets the lower bound capacity map. 298 /// \return \c (*this)358 /// \return <tt>(*this)</tt> 299 359 Circulation& lowerCapMap(const LCapMap& map) { 300 360 _lo = ↦ 301 361 return *this; … … 304 364 /// Sets the upper bound capacity map. 305 365 306 366 /// Sets the upper bound capacity map. 307 /// \return \c (*this)367 /// \return <tt>(*this)</tt> 308 368 Circulation& upperCapMap(const LCapMap& map) { 309 369 _up = ↦ 310 370 return *this; 311 371 } 312 372 313 /// Sets the lower bound map on excess.373 /// Sets the lower bound map for the supply of the nodes. 314 374 315 /// Sets the lower bound map on excess.316 /// \return \c (*this)375 /// Sets the lower bound map for the supply of the nodes. 376 /// \return <tt>(*this)</tt> 317 377 Circulation& deltaMap(const DeltaMap& map) { 318 378 _delta = ↦ 319 379 return *this; 320 380 } 321 381 382 /// \brief Sets the flow map. 383 /// 322 384 /// Sets the flow map. 323 324 /// Sets the flow map. 325 /// \return \c (*this) 385 /// If you don't use this function before calling \ref run() or 386 /// \ref init(), an instance will be allocated automatically. 387 /// The destructor deallocates this automatically allocated map, 388 /// of course. 389 /// \return <tt>(*this)</tt> 326 390 Circulation& flowMap(FlowMap& map) { 327 391 if (_local_flow) { 328 392 delete _flow; … … 332 396 return *this; 333 397 } 334 398 335 /// Returns the flow map. 336 337 /// \return The flow map. 399 /// \brief Sets the elevator used by algorithm. 338 400 /// 339 const FlowMap& flowMap() { 340 return *_flow; 341 } 342 343 /// Sets the elevator. 344 345 /// Sets the elevator. 346 /// \return \c (*this) 401 /// Sets the elevator used by algorithm. 402 /// If you don't use this function before calling \ref run() or 403 /// \ref init(), an instance will be allocated automatically. 404 /// The destructor deallocates this automatically allocated elevator, 405 /// of course. 406 /// \return <tt>(*this)</tt> 347 407 Circulation& elevator(Elevator& elevator) { 348 408 if (_local_level) { 349 409 delete _level; … … 353 413 return *this; 354 414 } 355 415 356 /// Returns the elevator. 357 358 /// \return The elevator. 416 /// \brief Returns a const reference to the elevator. 359 417 /// 418 /// Returns a const reference to the elevator. 419 /// 420 /// \pre Either \ref run() or \ref init() must be called before 421 /// using this function. 360 422 const Elevator& elevator() { 361 423 return *_level; 362 424 } 363 425 426 /// \brief Sets the tolerance used by algorithm. 427 /// 364 428 /// Sets the tolerance used by algorithm. 365 366 /// Sets the tolerance used by algorithm.367 ///368 429 Circulation& tolerance(const Tolerance& tolerance) const { 369 430 _tol = tolerance; 370 431 return *this; 371 432 } 372 433 373 /// Returns the tolerance used by algorithm. 374 375 /// Returns the tolerance used by algorithm. 434 /// \brief Returns a const reference to the tolerance. 376 435 /// 436 /// Returns a const reference to the tolerance. 377 437 const Tolerance& tolerance() const { 378 438 return tolerance; 379 439 } 380 440 381 /// \name Execution control 382 /// The simplest way to execute the algorithm is to use one of the 383 /// member functions called \c run(). 384 /// \n 385 /// If you need more control on initial solution or execution then 386 /// you have to call one \ref init() function and then the start() 387 /// function. 441 /// \name Execution Control 442 /// The simplest way to execute the algorithm is to call \ref run().\n 443 /// If you need more control on the initial solution or the execution, 444 /// first you have to call one of the \ref init() functions, then 445 /// the \ref start() function. 388 446 389 447 ///@{ 390 448 391 449 /// Initializes the internal data structures. 392 450 393 /// Initializes the internal data structures. This function sets 394 /// all flow values to the lower bound. 395 /// \return This function returns false if the initialization 396 /// process found a barrier. 451 /// Initializes the internal data structures and sets all flow values 452 /// to the lower bound. 397 453 void init() 398 454 { 399 455 createStructures(); … … 419 475 _level>activate(n); 420 476 } 421 477 422 /// Initializes the internal data structures .478 /// Initializes the internal data structures using a greedy approach. 423 479 424 /// Initializes the internal data structures . This functions uses425 /// greedy approachto construct the initial solution.480 /// Initializes the internal data structures using a greedy approach 481 /// to construct the initial solution. 426 482 void greedyInit() 427 483 { 428 484 createStructures(); … … 457 513 _level>activate(n); 458 514 } 459 515 460 /// Starts the algorithm516 ///Executes the algorithm 461 517 462 ///This function starts the algorithm. 463 ///\return This function returns true if it found a feasible circulation. 518 ///This function executes the algorithm. 519 /// 520 ///\return \c true if a feasible circulation is found. 464 521 /// 465 522 ///\sa barrier() 523 ///\sa barrierMap() 466 524 bool start() 467 525 { 468 526 … … 543 601 return true; 544 602 } 545 603 546 /// Runs the circulationalgorithm.604 /// Runs the algorithm. 547 605 548 /// Runs the circulation algorithm. 549 /// \note fc.run() is just a shortcut of the following code. 606 /// This function runs the algorithm. 607 /// 608 /// \return \c true if a feasible circulation is found. 609 /// 610 /// \note Apart from the return value, c.run() is just a shortcut of 611 /// the following code. 550 612 /// \code 551 /// fc.greedyInit();552 /// return fc.start();613 /// c.greedyInit(); 614 /// c.start(); 553 615 /// \endcode 554 616 bool run() { 555 617 greedyInit(); … … 559 621 /// @} 560 622 561 623 /// \name Query Functions 562 /// The result of the %Circulation algorithm can be obtained using 563 /// these functions. 564 /// \n 565 /// Before the use of these functions, 566 /// either run() or start() must be called. 624 /// The results of the circulation algorithm can be obtained using 625 /// these functions.\n 626 /// Either \ref run() or \ref start() should be called before 627 /// using them. 567 628 568 629 ///@{ 569 630 631 /// \brief Returns the flow on the given arc. 632 /// 633 /// Returns the flow on the given arc. 634 /// 635 /// \pre Either \ref run() or \ref init() must be called before 636 /// using this function. 637 Value flow(const Arc& arc) const { 638 return (*_flow)[arc]; 639 } 640 641 /// \brief Returns a const reference to the flow map. 642 /// 643 /// Returns a const reference to the arc map storing the found flow. 644 /// 645 /// \pre Either \ref run() or \ref init() must be called before 646 /// using this function. 647 const FlowMap& flowMap() { 648 return *_flow; 649 } 650 570 651 /** 571 \brief Returns a barrier572 652 \brief Returns \c true if the given node is in a barrier. 653 573 654 Barrier is a set \e B of nodes for which 574 \f[ \sum_{v\in B}delta(v)< 575 \sum_{e\in\rho(B)}lo(e)\sum_{e\in\delta(B)}up(e) \f] 576 holds. The existence of a set with this property prooves that a feasible 577 flow cannot exists. 655 656 \f[ \sum_{a\in\delta_{out}(B)} upper(a)  657 \sum_{a\in\delta_{in}(B)} lower(a) < \sum_{v\in B}delta(v) \f] 658 659 holds. The existence of a set with this property prooves that a 660 feasible circualtion cannot exist. 661 662 This function returns \c true if the given node is in the found 663 barrier. If a feasible circulation is found, the function 664 gives back \c false for every node. 665 666 \pre Either \ref run() or \ref init() must be called before 667 using this function. 668 669 \sa barrierMap() 578 670 \sa checkBarrier() 579 \sa run()580 671 */ 581 template<class GT> 582 void barrierMap(GT &bar) 672 bool barrier(const Node& node) 673 { 674 return (*_level)[node] >= _el; 675 } 676 677 /// \brief Gives back a barrier. 678 /// 679 /// This function sets \c bar to the characteristic vector of the 680 /// found barrier. \c bar should be a \ref concepts::WriteMap "writable" 681 /// node map with \c bool (or convertible) value type. 682 /// 683 /// If a feasible circulation is found, the function gives back an 684 /// empty set, so \c bar[v] will be \c false for all nodes \c v. 685 /// 686 /// \note This function calls \ref barrier() for each node, 687 /// so it runs in \f$O(n)\f$ time. 688 /// 689 /// \pre Either \ref run() or \ref init() must be called before 690 /// using this function. 691 /// 692 /// \sa barrier() 693 /// \sa checkBarrier() 694 template<class BarrierMap> 695 void barrierMap(BarrierMap &bar) 583 696 { 584 697 for(NodeIt n(_g);n!=INVALID;++n) 585 698 bar.set(n, (*_level)[n] >= _el); 586 699 } 587 700 588 ///Returns true if the node is in the barrier589 590 ///Returns true if the node is in the barrier591 ///\sa barrierMap()592 bool barrier(const Node& node)593 {594 return (*_level)[node] >= _el;595 }596 597 /// \brief Returns the flow on the arc.598 ///599 /// Sets the \c flowMap to the flow on the arcs. This method can600 /// be called after the second phase of algorithm.601 Value flow(const Arc& arc) const {602 return (*_flow)[arc];603 }604 605 701 /// @} 606 702 607 703 /// \name Checker Functions 608 /// The feasibility of the results can be checked using 609 /// these functions. 610 /// \n 611 /// Before the use of these functions, 612 /// either run() or start() must be called. 704 /// The feasibility of the results can be checked using 705 /// these functions.\n 706 /// Either \ref run() or \ref start() should be called before 707 /// using them. 613 708 614 709 ///@{ 615 710 616 ///Check if the \c flow is a feasible circulation 711 ///Check if the found flow is a feasible circulation 712 713 ///Check if the found flow is a feasible circulation, 714 /// 617 715 bool checkFlow() { 618 716 for(ArcIt e(_g);e!=INVALID;++e) 619 717 if((*_flow)[e]<(*_lo)[e](*_flow)[e]>(*_up)[e]) return false; … … 629 727 630 728 ///Check whether or not the last execution provides a barrier 631 729 632 ///Check whether or not the last execution provides a barrier 730 ///Check whether or not the last execution provides a barrier. 633 731 ///\sa barrier() 732 ///\sa barrierMap() 634 733 bool checkBarrier() 635 734 { 636 735 Value delta=0;