COIN-OR::LEMON - Graph Library

Ticket #175: circ_b4fbf36feb57.patch

File circ_b4fbf36feb57.patch, 20.9 KB (added by Peter Kovacs, 16 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  
    1919#ifndef LEMON_CIRCULATION_H
    2020#define LEMON_CIRCULATION_H
    2121
    22 #include <iostream>
    23 #include <queue>
    2422#include <lemon/tolerance.h>
    2523#include <lemon/elevator.h>
    2624
    2725///\ingroup max_flow
    2826///\file
    29 ///\brief Push-prelabel algorithm for finding a feasible circulation.
     27///\brief Push-relabel algorithm for finding a feasible circulation.
    3028///
    3129namespace lemon {
    3230
    3331  /// \brief Default traits class of Circulation class.
    3432  ///
    3533  /// 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,
    3939            typename _UCapMap, typename _DeltaMap>
    4040  struct CirculationDefaultTraits {
    4141
    42     /// \brief The digraph type the algorithm runs on.
    43     typedef _Graph Digraph;
     42    /// \brief The type of the digraph the algorithm runs on.
     43    typedef _Diraph Digraph;
    4444
    4545    /// \brief The type of the map that stores the circulation lower
    4646    /// bound.
     
    5656    /// It must meet the \ref concepts::ReadMap "ReadMap" concept.
    5757    typedef _UCapMap UCapMap;
    5858
    59     /// \brief The type of the map that stores the upper bound of
    60     /// node excess.
     59    /// \brief The type of the map that stores the lower bound for
     60    /// the supply of the nodes.
    6161    ///
    62     /// The type of the map that stores the lower bound of node
    63     /// 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"
    6464    /// concept.
    6565    typedef _DeltaMap DeltaMap;
    6666
    67     /// \brief The type of the length of the arcs.
     67    /// \brief The type of the flow values.
    6868    typedef typename DeltaMap::Value Value;
    6969
    70     /// \brief The map type that stores the flow values.
     70    /// \brief The type of the map that stores the flow values.
    7171    ///
    72     /// The map type that stores the flow values.
     72    /// The type of the map that stores the flow values.
    7373    /// It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
    7474    typedef typename Digraph::template ArcMap<Value> FlowMap;
    7575
     
    8282      return new FlowMap(digraph);
    8383    }
    8484
    85     /// \brief The eleavator type used by Circulation algorithm.
     85    /// \brief The elevator type used by the algorithm.
    8686    ///
    87     /// The elevator type used by Circulation algorithm.
     87    /// The elevator type used by the algorithm.
    8888    ///
    8989    /// \sa Elevator
    9090    /// \sa LinkedElevator
     
    9292
    9393    /// \brief Instantiates an Elevator.
    9494    ///
    95     /// This function instantiates a \ref Elevator.
     95    /// This function instantiates an \ref Elevator.
    9696    /// \param digraph The digraph, to which we would like to define
    9797    /// the elevator.
    9898    /// \param max_level The maximum level of the elevator.
     
    107107
    108108  };
    109109
    110   ///Push-relabel algorithm for the Network Circulation Problem.
     110  /**
     111     \brief Push-relabel algorithm for the network circulation problem.
    111112
    112   /**
    113113     \ingroup max_flow
    114      This class implements a push-relabel algorithm
    115      or the Network Circulation Problem.
     114     This class implements a push-relabel 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
    116120     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>.
    120148  */
    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
     150template< typename _Digraph,
     151          typename _LCapMap,
     152          typename _UCapMap,
     153          typename _DeltaMap,
     154          typename _Traits >
     155#else
     156template< 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
    128164  class Circulation {
     165  public:
    129166
     167    ///The \ref CirculationDefaultTraits "traits class" of the algorithm.
    130168    typedef _Traits Traits;
     169    ///The type of the digraph the algorithm runs on.
    131170    typedef typename Traits::Digraph Digraph;
    132     TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
    133 
     171    ///The type of the flow values.
    134172    typedef typename Traits::Value Value;
    135173
     174    /// The type of the lower bound capacity map.
    136175    typedef typename Traits::LCapMap LCapMap;
     176    /// The type of the upper bound capacity map.
    137177    typedef typename Traits::UCapMap UCapMap;
     178    /// \brief The type of the map that stores the lower bound for
     179    /// the supply of the nodes.
    138180    typedef typename Traits::DeltaMap DeltaMap;
     181    ///The type of the flow map.
    139182    typedef typename Traits::FlowMap FlowMap;
     183
     184    ///The type of the elevator.
    140185    typedef typename Traits::Elevator Elevator;
     186    ///The type of the tolerance.
    141187    typedef typename Traits::Tolerance Tolerance;
    142188
    143     typedef typename Digraph::template NodeMap<Value> ExcessMap;
     189  private:
     190
     191    TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
    144192
    145193    const Digraph &_g;
    146194    int _node_num;
     
    155203    Elevator* _level;
    156204    bool _local_level;
    157205
     206    typedef typename Digraph::template NodeMap<Value> ExcessMap;
    158207    ExcessMap* _excess;
    159208
    160209    Tolerance _tol;
     
    164213
    165214    typedef Circulation Create;
    166215
    167     ///\name Named template parameters
     216    ///\name Named Template Parameters
    168217
    169218    ///@{
    170219
     
    181230    /// FlowMap type
    182231    ///
    183232    /// \ref named-templ-param "Named parameter" for setting FlowMap
    184     /// type
     233    /// type.
    185234    template <typename _FlowMap>
    186235    struct SetFlowMap
    187236      : public Circulation<Digraph, LCapMap, UCapMap, DeltaMap,
     
    203252    /// Elevator type
    204253    ///
    205254    /// \ref named-templ-param "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
    207260    template <typename _Elevator>
    208261    struct SetElevator
    209262      : public Circulation<Digraph, LCapMap, UCapMap, DeltaMap,
     
    221274    };
    222275
    223276    /// \brief \ref named-templ-param "Named parameter" for setting
    224     /// Elevator type
     277    /// Elevator type with automatic allocation
    225278    ///
    226279    /// \ref named-templ-param "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
    229288    template <typename _Elevator>
    230289    struct SetStandardElevator
    231290      : public Circulation<Digraph, LCapMap, UCapMap, DeltaMap,
     
    248307    /// \param g The digraph the algorithm runs on.
    249308    /// \param lo The lower bound capacity of the arcs.
    250309    /// \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.
    252311    Circulation(const Digraph &g,const LCapMap &lo,
    253312                const UCapMap &up,const DeltaMap &delta)
    254313      : _g(g), _node_num(),
    255314        _lo(&lo),_up(&up),_delta(&delta),_flow(0),_local_flow(false),
    256315        _level(0), _local_level(false), _excess(0), _el() {}
    257316
    258     /// Destrcutor.
     317    /// Destructor.
    259318    ~Circulation() {
    260319      destroyStructures();
    261320    }
     321
    262322
    263323  private:
    264324
     
    295355    /// Sets the lower bound capacity map.
    296356
    297357    /// Sets the lower bound capacity map.
    298     /// \return \c (*this)
     358    /// \return <tt>(*this)</tt>
    299359    Circulation& lowerCapMap(const LCapMap& map) {
    300360      _lo = &map;
    301361      return *this;
     
    304364    /// Sets the upper bound capacity map.
    305365
    306366    /// Sets the upper bound capacity map.
    307     /// \return \c (*this)
     367    /// \return <tt>(*this)</tt>
    308368    Circulation& upperCapMap(const LCapMap& map) {
    309369      _up = &map;
    310370      return *this;
    311371    }
    312372
    313     /// Sets the lower bound map on excess.
     373    /// Sets the lower bound map for the supply of the nodes.
    314374
    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>
    317377    Circulation& deltaMap(const DeltaMap& map) {
    318378      _delta = &map;
    319379      return *this;
    320380    }
    321381
     382    /// \brief Sets the flow map.
     383    ///
    322384    /// 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>
    326390    Circulation& flowMap(FlowMap& map) {
    327391      if (_local_flow) {
    328392        delete _flow;
     
    332396      return *this;
    333397    }
    334398
    335     /// Returns the flow map.
    336 
    337     /// \return The flow map.
     399    /// \brief Sets the elevator used by algorithm.
    338400    ///
    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>
    347407    Circulation& elevator(Elevator& elevator) {
    348408      if (_local_level) {
    349409        delete _level;
     
    353413      return *this;
    354414    }
    355415
    356     /// Returns the elevator.
    357 
    358     /// \return The elevator.
     416    /// \brief Returns a const reference to the elevator.
    359417    ///
     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.
    360422    const Elevator& elevator() {
    361423      return *_level;
    362424    }
    363425
     426    /// \brief Sets the tolerance used by algorithm.
     427    ///
    364428    /// Sets the tolerance used by algorithm.
    365 
    366     /// Sets the tolerance used by algorithm.
    367     ///
    368429    Circulation& tolerance(const Tolerance& tolerance) const {
    369430      _tol = tolerance;
    370431      return *this;
    371432    }
    372433
    373     /// Returns the tolerance used by algorithm.
    374 
    375     /// Returns the tolerance used by algorithm.
     434    /// \brief Returns a const reference to the tolerance.
    376435    ///
     436    /// Returns a const reference to the tolerance.
    377437    const Tolerance& tolerance() const {
    378438      return tolerance;
    379439    }
    380440
    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.
    388446
    389447    ///@{
    390448
    391449    /// Initializes the internal data structures.
    392450
    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.
    397453    void init()
    398454    {
    399455      createStructures();
     
    419475          _level->activate(n);
    420476    }
    421477
    422     /// Initializes the internal data structures.
     478    /// Initializes the internal data structures using a greedy approach.
    423479
    424     /// Initializes the internal data structures. This functions uses
    425     /// greedy approach to construct the initial solution.
     480    /// Initializes the internal data structures using a greedy approach
     481    /// to construct the initial solution.
    426482    void greedyInit()
    427483    {
    428484      createStructures();
     
    457513          _level->activate(n);
    458514    }
    459515
    460     ///Starts the algorithm
     516    ///Executes the algorithm
    461517
    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.
    464521    ///
    465522    ///\sa barrier()
     523    ///\sa barrierMap()
    466524    bool start()
    467525    {
    468526
     
    543601      return true;
    544602    }
    545603
    546     /// Runs the circulation algorithm.
     604    /// Runs the algorithm.
    547605
    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.
    550612    /// \code
    551     ///   fc.greedyInit();
    552     ///   return fc.start();
     613    ///   c.greedyInit();
     614    ///   c.start();
    553615    /// \endcode
    554616    bool run() {
    555617      greedyInit();
     
    559621    /// @}
    560622
    561623    /// \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.
    567628
    568629    ///@{
    569630
     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
    570651    /**
    571        \brief Returns a barrier
    572        
     652       \brief Returns \c true if the given node is in a barrier.
     653
    573654       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()
    578670       \sa checkBarrier()
    579        \sa run()
    580671    */
    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)
    583696    {
    584697      for(NodeIt n(_g);n!=INVALID;++n)
    585698        bar.set(n, (*_level)[n] >= _el);
    586699    }
    587700
    588     ///Returns true if the node is in the barrier
    589 
    590     ///Returns true if the node is in the barrier
    591     ///\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 can
    600     /// be called after the second phase of algorithm.
    601     Value flow(const Arc& arc) const {
    602       return (*_flow)[arc];
    603     }
    604 
    605701    /// @}
    606702
    607703    /// \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.
    613708
    614709    ///@{
    615710
    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    ///
    617715    bool checkFlow() {
    618716      for(ArcIt e(_g);e!=INVALID;++e)
    619717        if((*_flow)[e]<(*_lo)[e]||(*_flow)[e]>(*_up)[e]) return false;
     
    629727
    630728    ///Check whether or not the last execution provides a barrier
    631729
    632     ///Check whether or not the last execution provides a barrier
     730    ///Check whether or not the last execution provides a barrier.
    633731    ///\sa barrier()
     732    ///\sa barrierMap()
    634733    bool checkBarrier()
    635734    {
    636735      Value delta=0;