lemon/circulation.h
author Alpar Juttner <alpar@cs.elte.hu>
Thu, 05 Nov 2009 15:50:01 +0100
changeset 784 1a7fe3bef514
parent 713 4ac30454f1c1
parent 689 86c49553fea5
child 786 e20173729589
permissions -rw-r--r--
Merge #321
alpar@399
     1
/* -*- mode: C++; indent-tabs-mode: nil; -*-
alpar@399
     2
 *
alpar@399
     3
 * This file is a part of LEMON, a generic C++ optimization library.
alpar@399
     4
 *
alpar@440
     5
 * Copyright (C) 2003-2009
alpar@399
     6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
alpar@399
     7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
alpar@399
     8
 *
alpar@399
     9
 * Permission to use, modify and distribute this software is granted
alpar@399
    10
 * provided that this copyright notice appears in all copies. For
alpar@399
    11
 * precise terms see the accompanying LICENSE file.
alpar@399
    12
 *
alpar@399
    13
 * This software is provided "AS IS" with no warranty of any kind,
alpar@399
    14
 * express or implied, and with no claim as to its suitability for any
alpar@399
    15
 * purpose.
alpar@399
    16
 *
alpar@399
    17
 */
alpar@399
    18
alpar@399
    19
#ifndef LEMON_CIRCULATION_H
alpar@399
    20
#define LEMON_CIRCULATION_H
alpar@399
    21
alpar@399
    22
#include <lemon/tolerance.h>
alpar@399
    23
#include <lemon/elevator.h>
kpeter@622
    24
#include <limits>
alpar@399
    25
alpar@399
    26
///\ingroup max_flow
alpar@399
    27
///\file
kpeter@402
    28
///\brief Push-relabel algorithm for finding a feasible circulation.
alpar@399
    29
///
alpar@399
    30
namespace lemon {
alpar@399
    31
alpar@399
    32
  /// \brief Default traits class of Circulation class.
alpar@399
    33
  ///
alpar@399
    34
  /// Default traits class of Circulation class.
kpeter@610
    35
  ///
kpeter@610
    36
  /// \tparam GR Type of the digraph the algorithm runs on.
kpeter@610
    37
  /// \tparam LM The type of the lower bound map.
kpeter@610
    38
  /// \tparam UM The type of the upper bound (capacity) map.
kpeter@610
    39
  /// \tparam SM The type of the supply map.
kpeter@492
    40
  template <typename GR, typename LM,
kpeter@610
    41
            typename UM, typename SM>
alpar@399
    42
  struct CirculationDefaultTraits {
alpar@399
    43
kpeter@402
    44
    /// \brief The type of the digraph the algorithm runs on.
kpeter@492
    45
    typedef GR Digraph;
alpar@399
    46
kpeter@610
    47
    /// \brief The type of the lower bound map.
alpar@399
    48
    ///
kpeter@610
    49
    /// The type of the map that stores the lower bounds on the arcs.
kpeter@610
    50
    /// It must conform to the \ref concepts::ReadMap "ReadMap" concept.
kpeter@610
    51
    typedef LM LowerMap;
alpar@399
    52
kpeter@610
    53
    /// \brief The type of the upper bound (capacity) map.
alpar@399
    54
    ///
kpeter@610
    55
    /// The type of the map that stores the upper bounds (capacities)
kpeter@610
    56
    /// on the arcs.
kpeter@610
    57
    /// It must conform to the \ref concepts::ReadMap "ReadMap" concept.
kpeter@610
    58
    typedef UM UpperMap;
alpar@399
    59
kpeter@610
    60
    /// \brief The type of supply map.
alpar@399
    61
    ///
kpeter@610
    62
    /// The type of the map that stores the signed supply values of the 
kpeter@610
    63
    /// nodes. 
kpeter@610
    64
    /// It must conform to the \ref concepts::ReadMap "ReadMap" concept.
kpeter@610
    65
    typedef SM SupplyMap;
alpar@399
    66
kpeter@641
    67
    /// \brief The type of the flow and supply values.
kpeter@641
    68
    typedef typename SupplyMap::Value Value;
alpar@399
    69
kpeter@402
    70
    /// \brief The type of the map that stores the flow values.
alpar@399
    71
    ///
kpeter@402
    72
    /// The type of the map that stores the flow values.
kpeter@610
    73
    /// It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap"
kpeter@610
    74
    /// concept.
kpeter@713
    75
#ifdef DOXYGEN
kpeter@713
    76
    typedef GR::ArcMap<Value> FlowMap;
kpeter@713
    77
#else
kpeter@641
    78
    typedef typename Digraph::template ArcMap<Value> FlowMap;
kpeter@713
    79
#endif
alpar@399
    80
alpar@399
    81
    /// \brief Instantiates a FlowMap.
alpar@399
    82
    ///
alpar@399
    83
    /// This function instantiates a \ref FlowMap.
kpeter@610
    84
    /// \param digraph The digraph for which we would like to define
alpar@399
    85
    /// the flow map.
alpar@399
    86
    static FlowMap* createFlowMap(const Digraph& digraph) {
alpar@399
    87
      return new FlowMap(digraph);
alpar@399
    88
    }
alpar@399
    89
kpeter@402
    90
    /// \brief The elevator type used by the algorithm.
alpar@399
    91
    ///
kpeter@402
    92
    /// The elevator type used by the algorithm.
alpar@399
    93
    ///
kpeter@713
    94
    /// \sa Elevator, LinkedElevator
kpeter@713
    95
#ifdef DOXYGEN
kpeter@713
    96
    typedef lemon::Elevator<GR, GR::Node> Elevator;
kpeter@713
    97
#else
alpar@399
    98
    typedef lemon::Elevator<Digraph, typename Digraph::Node> Elevator;
kpeter@713
    99
#endif
alpar@399
   100
alpar@399
   101
    /// \brief Instantiates an Elevator.
alpar@399
   102
    ///
kpeter@402
   103
    /// This function instantiates an \ref Elevator.
kpeter@610
   104
    /// \param digraph The digraph for which we would like to define
alpar@399
   105
    /// the elevator.
alpar@399
   106
    /// \param max_level The maximum level of the elevator.
alpar@399
   107
    static Elevator* createElevator(const Digraph& digraph, int max_level) {
alpar@399
   108
      return new Elevator(digraph, max_level);
alpar@399
   109
    }
alpar@399
   110
alpar@399
   111
    /// \brief The tolerance used by the algorithm
alpar@399
   112
    ///
alpar@399
   113
    /// The tolerance used by the algorithm to handle inexact computation.
kpeter@641
   114
    typedef lemon::Tolerance<Value> Tolerance;
alpar@399
   115
alpar@399
   116
  };
alpar@399
   117
kpeter@402
   118
  /**
kpeter@402
   119
     \brief Push-relabel algorithm for the network circulation problem.
alpar@399
   120
alpar@399
   121
     \ingroup max_flow
kpeter@610
   122
     This class implements a push-relabel algorithm for the \e network
kpeter@610
   123
     \e circulation problem.
kpeter@402
   124
     It is to find a feasible circulation when lower and upper bounds
kpeter@610
   125
     are given for the flow values on the arcs and lower bounds are
kpeter@610
   126
     given for the difference between the outgoing and incoming flow
kpeter@610
   127
     at the nodes.
kpeter@402
   128
alpar@399
   129
     The exact formulation of this problem is the following.
kpeter@622
   130
     Let \f$G=(V,A)\f$ be a digraph, \f$lower: A\rightarrow\mathbf{R}\f$
kpeter@622
   131
     \f$upper: A\rightarrow\mathbf{R}\cup\{\infty\}\f$ denote the lower and
kpeter@622
   132
     upper bounds on the arcs, for which \f$lower(uv) \leq upper(uv)\f$
kpeter@610
   133
     holds for all \f$uv\in A\f$, and \f$sup: V\rightarrow\mathbf{R}\f$
kpeter@610
   134
     denotes the signed supply values of the nodes.
kpeter@610
   135
     If \f$sup(u)>0\f$, then \f$u\f$ is a supply node with \f$sup(u)\f$
kpeter@610
   136
     supply, if \f$sup(u)<0\f$, then \f$u\f$ is a demand node with
kpeter@610
   137
     \f$-sup(u)\f$ demand.
kpeter@622
   138
     A feasible circulation is an \f$f: A\rightarrow\mathbf{R}\f$
kpeter@610
   139
     solution of the following problem.
kpeter@402
   140
kpeter@610
   141
     \f[ \sum_{uv\in A} f(uv) - \sum_{vu\in A} f(vu)
kpeter@610
   142
     \geq sup(u) \quad \forall u\in V, \f]
kpeter@610
   143
     \f[ lower(uv) \leq f(uv) \leq upper(uv) \quad \forall uv\in A. \f]
kpeter@610
   144
     
kpeter@610
   145
     The sum of the supply values, i.e. \f$\sum_{u\in V} sup(u)\f$ must be
kpeter@610
   146
     zero or negative in order to have a feasible solution (since the sum
kpeter@610
   147
     of the expressions on the left-hand side of the inequalities is zero).
kpeter@610
   148
     It means that the total demand must be greater or equal to the total
kpeter@610
   149
     supply and all the supplies have to be carried out from the supply nodes,
kpeter@610
   150
     but there could be demands that are not satisfied.
kpeter@610
   151
     If \f$\sum_{u\in V} sup(u)\f$ is zero, then all the supply/demand
kpeter@610
   152
     constraints have to be satisfied with equality, i.e. all demands
kpeter@610
   153
     have to be satisfied and all supplies have to be used.
kpeter@610
   154
     
kpeter@610
   155
     If you need the opposite inequalities in the supply/demand constraints
kpeter@610
   156
     (i.e. the total demand is less than the total supply and all the demands
kpeter@610
   157
     have to be satisfied while there could be supplies that are not used),
kpeter@610
   158
     then you could easily transform the problem to the above form by reversing
kpeter@610
   159
     the direction of the arcs and taking the negative of the supply values
kpeter@610
   160
     (e.g. using \ref ReverseDigraph and \ref NegMap adaptors).
kpeter@610
   161
kpeter@622
   162
     This algorithm either calculates a feasible circulation, or provides
kpeter@622
   163
     a \ref barrier() "barrier", which prooves that a feasible soultion
kpeter@622
   164
     cannot exist.
kpeter@622
   165
kpeter@610
   166
     Note that this algorithm also provides a feasible solution for the
kpeter@610
   167
     \ref min_cost_flow "minimum cost flow problem".
kpeter@402
   168
kpeter@492
   169
     \tparam GR The type of the digraph the algorithm runs on.
kpeter@610
   170
     \tparam LM The type of the lower bound map. The default
kpeter@492
   171
     map type is \ref concepts::Digraph::ArcMap "GR::ArcMap<int>".
kpeter@610
   172
     \tparam UM The type of the upper bound (capacity) map.
kpeter@610
   173
     The default map type is \c LM.
kpeter@610
   174
     \tparam SM The type of the supply map. The default map type is
kpeter@492
   175
     \ref concepts::Digraph::NodeMap "GR::NodeMap<UM::Value>".
alpar@399
   176
  */
kpeter@402
   177
#ifdef DOXYGEN
kpeter@492
   178
template< typename GR,
kpeter@492
   179
          typename LM,
kpeter@492
   180
          typename UM,
kpeter@610
   181
          typename SM,
kpeter@492
   182
          typename TR >
kpeter@402
   183
#else
kpeter@492
   184
template< typename GR,
kpeter@492
   185
          typename LM = typename GR::template ArcMap<int>,
kpeter@492
   186
          typename UM = LM,
kpeter@610
   187
          typename SM = typename GR::template NodeMap<typename UM::Value>,
kpeter@610
   188
          typename TR = CirculationDefaultTraits<GR, LM, UM, SM> >
kpeter@402
   189
#endif
alpar@399
   190
  class Circulation {
kpeter@402
   191
  public:
alpar@399
   192
kpeter@402
   193
    ///The \ref CirculationDefaultTraits "traits class" of the algorithm.
kpeter@492
   194
    typedef TR Traits;
kpeter@402
   195
    ///The type of the digraph the algorithm runs on.
alpar@399
   196
    typedef typename Traits::Digraph Digraph;
kpeter@641
   197
    ///The type of the flow and supply values.
kpeter@641
   198
    typedef typename Traits::Value Value;
alpar@399
   199
kpeter@610
   200
    ///The type of the lower bound map.
kpeter@610
   201
    typedef typename Traits::LowerMap LowerMap;
kpeter@610
   202
    ///The type of the upper bound (capacity) map.
kpeter@610
   203
    typedef typename Traits::UpperMap UpperMap;
kpeter@610
   204
    ///The type of the supply map.
kpeter@610
   205
    typedef typename Traits::SupplyMap SupplyMap;
kpeter@402
   206
    ///The type of the flow map.
alpar@399
   207
    typedef typename Traits::FlowMap FlowMap;
kpeter@402
   208
kpeter@402
   209
    ///The type of the elevator.
alpar@399
   210
    typedef typename Traits::Elevator Elevator;
kpeter@402
   211
    ///The type of the tolerance.
alpar@399
   212
    typedef typename Traits::Tolerance Tolerance;
alpar@399
   213
kpeter@402
   214
  private:
kpeter@402
   215
kpeter@402
   216
    TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
alpar@399
   217
alpar@399
   218
    const Digraph &_g;
alpar@399
   219
    int _node_num;
alpar@399
   220
kpeter@610
   221
    const LowerMap *_lo;
kpeter@610
   222
    const UpperMap *_up;
kpeter@610
   223
    const SupplyMap *_supply;
alpar@399
   224
alpar@399
   225
    FlowMap *_flow;
alpar@399
   226
    bool _local_flow;
alpar@399
   227
alpar@399
   228
    Elevator* _level;
alpar@399
   229
    bool _local_level;
alpar@399
   230
kpeter@641
   231
    typedef typename Digraph::template NodeMap<Value> ExcessMap;
alpar@399
   232
    ExcessMap* _excess;
alpar@399
   233
alpar@399
   234
    Tolerance _tol;
alpar@399
   235
    int _el;
alpar@399
   236
alpar@399
   237
  public:
alpar@399
   238
alpar@399
   239
    typedef Circulation Create;
alpar@399
   240
kpeter@402
   241
    ///\name Named Template Parameters
alpar@399
   242
alpar@399
   243
    ///@{
alpar@399
   244
kpeter@559
   245
    template <typename T>
alpar@401
   246
    struct SetFlowMapTraits : public Traits {
kpeter@559
   247
      typedef T FlowMap;
alpar@399
   248
      static FlowMap *createFlowMap(const Digraph&) {
alpar@399
   249
        LEMON_ASSERT(false, "FlowMap is not initialized");
alpar@399
   250
        return 0; // ignore warnings
alpar@399
   251
      }
alpar@399
   252
    };
alpar@399
   253
alpar@399
   254
    /// \brief \ref named-templ-param "Named parameter" for setting
alpar@399
   255
    /// FlowMap type
alpar@399
   256
    ///
alpar@399
   257
    /// \ref named-templ-param "Named parameter" for setting FlowMap
kpeter@402
   258
    /// type.
kpeter@559
   259
    template <typename T>
alpar@401
   260
    struct SetFlowMap
kpeter@610
   261
      : public Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
kpeter@559
   262
                           SetFlowMapTraits<T> > {
kpeter@610
   263
      typedef Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
kpeter@559
   264
                          SetFlowMapTraits<T> > Create;
alpar@399
   265
    };
alpar@399
   266
kpeter@559
   267
    template <typename T>
alpar@401
   268
    struct SetElevatorTraits : public Traits {
kpeter@559
   269
      typedef T Elevator;
alpar@399
   270
      static Elevator *createElevator(const Digraph&, int) {
alpar@399
   271
        LEMON_ASSERT(false, "Elevator is not initialized");
alpar@399
   272
        return 0; // ignore warnings
alpar@399
   273
      }
alpar@399
   274
    };
alpar@399
   275
alpar@399
   276
    /// \brief \ref named-templ-param "Named parameter" for setting
alpar@399
   277
    /// Elevator type
alpar@399
   278
    ///
alpar@399
   279
    /// \ref named-templ-param "Named parameter" for setting Elevator
kpeter@402
   280
    /// type. If this named parameter is used, then an external
kpeter@402
   281
    /// elevator object must be passed to the algorithm using the
kpeter@402
   282
    /// \ref elevator(Elevator&) "elevator()" function before calling
kpeter@402
   283
    /// \ref run() or \ref init().
kpeter@402
   284
    /// \sa SetStandardElevator
kpeter@559
   285
    template <typename T>
alpar@401
   286
    struct SetElevator
kpeter@610
   287
      : public Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
kpeter@559
   288
                           SetElevatorTraits<T> > {
kpeter@610
   289
      typedef Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
kpeter@559
   290
                          SetElevatorTraits<T> > Create;
alpar@399
   291
    };
alpar@399
   292
kpeter@559
   293
    template <typename T>
alpar@401
   294
    struct SetStandardElevatorTraits : public Traits {
kpeter@559
   295
      typedef T Elevator;
alpar@399
   296
      static Elevator *createElevator(const Digraph& digraph, int max_level) {
alpar@399
   297
        return new Elevator(digraph, max_level);
alpar@399
   298
      }
alpar@399
   299
    };
alpar@399
   300
alpar@399
   301
    /// \brief \ref named-templ-param "Named parameter" for setting
kpeter@402
   302
    /// Elevator type with automatic allocation
alpar@399
   303
    ///
alpar@399
   304
    /// \ref named-templ-param "Named parameter" for setting Elevator
kpeter@402
   305
    /// type with automatic allocation.
kpeter@402
   306
    /// The Elevator should have standard constructor interface to be
kpeter@402
   307
    /// able to automatically created by the algorithm (i.e. the
kpeter@402
   308
    /// digraph and the maximum level should be passed to it).
kpeter@402
   309
    /// However an external elevator object could also be passed to the
kpeter@402
   310
    /// algorithm with the \ref elevator(Elevator&) "elevator()" function
kpeter@402
   311
    /// before calling \ref run() or \ref init().
kpeter@402
   312
    /// \sa SetElevator
kpeter@559
   313
    template <typename T>
alpar@401
   314
    struct SetStandardElevator
kpeter@610
   315
      : public Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
kpeter@559
   316
                       SetStandardElevatorTraits<T> > {
kpeter@610
   317
      typedef Circulation<Digraph, LowerMap, UpperMap, SupplyMap,
kpeter@559
   318
                      SetStandardElevatorTraits<T> > Create;
alpar@399
   319
    };
alpar@399
   320
alpar@399
   321
    /// @}
alpar@399
   322
alpar@399
   323
  protected:
alpar@399
   324
alpar@399
   325
    Circulation() {}
alpar@399
   326
alpar@399
   327
  public:
alpar@399
   328
kpeter@610
   329
    /// Constructor.
alpar@399
   330
alpar@399
   331
    /// The constructor of the class.
kpeter@610
   332
    ///
kpeter@610
   333
    /// \param graph The digraph the algorithm runs on.
kpeter@610
   334
    /// \param lower The lower bounds for the flow values on the arcs.
kpeter@610
   335
    /// \param upper The upper bounds (capacities) for the flow values 
kpeter@610
   336
    /// on the arcs.
kpeter@610
   337
    /// \param supply The signed supply values of the nodes.
kpeter@610
   338
    Circulation(const Digraph &graph, const LowerMap &lower,
kpeter@610
   339
                const UpperMap &upper, const SupplyMap &supply)
kpeter@610
   340
      : _g(graph), _lo(&lower), _up(&upper), _supply(&supply),
kpeter@610
   341
        _flow(NULL), _local_flow(false), _level(NULL), _local_level(false),
kpeter@610
   342
        _excess(NULL) {}
alpar@399
   343
kpeter@402
   344
    /// Destructor.
alpar@399
   345
    ~Circulation() {
alpar@399
   346
      destroyStructures();
alpar@399
   347
    }
alpar@399
   348
kpeter@402
   349
alpar@399
   350
  private:
alpar@399
   351
kpeter@622
   352
    bool checkBoundMaps() {
kpeter@622
   353
      for (ArcIt e(_g);e!=INVALID;++e) {
kpeter@622
   354
        if (_tol.less((*_up)[e], (*_lo)[e])) return false;
kpeter@622
   355
      }
kpeter@622
   356
      return true;
kpeter@622
   357
    }
kpeter@622
   358
alpar@399
   359
    void createStructures() {
alpar@399
   360
      _node_num = _el = countNodes(_g);
alpar@399
   361
alpar@399
   362
      if (!_flow) {
alpar@399
   363
        _flow = Traits::createFlowMap(_g);
alpar@399
   364
        _local_flow = true;
alpar@399
   365
      }
alpar@399
   366
      if (!_level) {
alpar@399
   367
        _level = Traits::createElevator(_g, _node_num);
alpar@399
   368
        _local_level = true;
alpar@399
   369
      }
alpar@399
   370
      if (!_excess) {
alpar@399
   371
        _excess = new ExcessMap(_g);
alpar@399
   372
      }
alpar@399
   373
    }
alpar@399
   374
alpar@399
   375
    void destroyStructures() {
alpar@399
   376
      if (_local_flow) {
alpar@399
   377
        delete _flow;
alpar@399
   378
      }
alpar@399
   379
      if (_local_level) {
alpar@399
   380
        delete _level;
alpar@399
   381
      }
alpar@399
   382
      if (_excess) {
alpar@399
   383
        delete _excess;
alpar@399
   384
      }
alpar@399
   385
    }
alpar@399
   386
alpar@399
   387
  public:
alpar@399
   388
kpeter@610
   389
    /// Sets the lower bound map.
alpar@399
   390
kpeter@610
   391
    /// Sets the lower bound map.
kpeter@402
   392
    /// \return <tt>(*this)</tt>
kpeter@610
   393
    Circulation& lowerMap(const LowerMap& map) {
alpar@399
   394
      _lo = &map;
alpar@399
   395
      return *this;
alpar@399
   396
    }
alpar@399
   397
kpeter@610
   398
    /// Sets the upper bound (capacity) map.
alpar@399
   399
kpeter@610
   400
    /// Sets the upper bound (capacity) map.
kpeter@402
   401
    /// \return <tt>(*this)</tt>
kpeter@622
   402
    Circulation& upperMap(const UpperMap& map) {
alpar@399
   403
      _up = &map;
alpar@399
   404
      return *this;
alpar@399
   405
    }
alpar@399
   406
kpeter@610
   407
    /// Sets the supply map.
alpar@399
   408
kpeter@610
   409
    /// Sets the supply map.
kpeter@402
   410
    /// \return <tt>(*this)</tt>
kpeter@610
   411
    Circulation& supplyMap(const SupplyMap& map) {
kpeter@610
   412
      _supply = &map;
alpar@399
   413
      return *this;
alpar@399
   414
    }
alpar@399
   415
kpeter@402
   416
    /// \brief Sets the flow map.
kpeter@402
   417
    ///
alpar@399
   418
    /// Sets the flow map.
kpeter@402
   419
    /// If you don't use this function before calling \ref run() or
kpeter@402
   420
    /// \ref init(), an instance will be allocated automatically.
kpeter@402
   421
    /// The destructor deallocates this automatically allocated map,
kpeter@402
   422
    /// of course.
kpeter@402
   423
    /// \return <tt>(*this)</tt>
alpar@399
   424
    Circulation& flowMap(FlowMap& map) {
alpar@399
   425
      if (_local_flow) {
alpar@399
   426
        delete _flow;
alpar@399
   427
        _local_flow = false;
alpar@399
   428
      }
alpar@399
   429
      _flow = &map;
alpar@399
   430
      return *this;
alpar@399
   431
    }
alpar@399
   432
kpeter@402
   433
    /// \brief Sets the elevator used by algorithm.
alpar@399
   434
    ///
kpeter@402
   435
    /// Sets the elevator used by algorithm.
kpeter@402
   436
    /// If you don't use this function before calling \ref run() or
kpeter@402
   437
    /// \ref init(), an instance will be allocated automatically.
kpeter@402
   438
    /// The destructor deallocates this automatically allocated elevator,
kpeter@402
   439
    /// of course.
kpeter@402
   440
    /// \return <tt>(*this)</tt>
alpar@399
   441
    Circulation& elevator(Elevator& elevator) {
alpar@399
   442
      if (_local_level) {
alpar@399
   443
        delete _level;
alpar@399
   444
        _local_level = false;
alpar@399
   445
      }
alpar@399
   446
      _level = &elevator;
alpar@399
   447
      return *this;
alpar@399
   448
    }
alpar@399
   449
kpeter@402
   450
    /// \brief Returns a const reference to the elevator.
alpar@399
   451
    ///
kpeter@402
   452
    /// Returns a const reference to the elevator.
kpeter@402
   453
    ///
kpeter@402
   454
    /// \pre Either \ref run() or \ref init() must be called before
kpeter@402
   455
    /// using this function.
kpeter@420
   456
    const Elevator& elevator() const {
alpar@399
   457
      return *_level;
alpar@399
   458
    }
alpar@399
   459
kpeter@689
   460
    /// \brief Sets the tolerance used by the algorithm.
kpeter@402
   461
    ///
kpeter@689
   462
    /// Sets the tolerance object used by the algorithm.
kpeter@689
   463
    /// \return <tt>(*this)</tt>
kpeter@688
   464
    Circulation& tolerance(const Tolerance& tolerance) {
alpar@399
   465
      _tol = tolerance;
alpar@399
   466
      return *this;
alpar@399
   467
    }
alpar@399
   468
kpeter@402
   469
    /// \brief Returns a const reference to the tolerance.
alpar@399
   470
    ///
kpeter@689
   471
    /// Returns a const reference to the tolerance object used by
kpeter@689
   472
    /// the algorithm.
alpar@399
   473
    const Tolerance& tolerance() const {
kpeter@688
   474
      return _tol;
alpar@399
   475
    }
alpar@399
   476
kpeter@402
   477
    /// \name Execution Control
kpeter@402
   478
    /// The simplest way to execute the algorithm is to call \ref run().\n
kpeter@713
   479
    /// If you need better control on the initial solution or the execution,
kpeter@713
   480
    /// you have to call one of the \ref init() functions first, then
kpeter@402
   481
    /// the \ref start() function.
alpar@399
   482
alpar@399
   483
    ///@{
alpar@399
   484
alpar@399
   485
    /// Initializes the internal data structures.
alpar@399
   486
kpeter@402
   487
    /// Initializes the internal data structures and sets all flow values
kpeter@402
   488
    /// to the lower bound.
alpar@399
   489
    void init()
alpar@399
   490
    {
kpeter@622
   491
      LEMON_DEBUG(checkBoundMaps(),
kpeter@622
   492
        "Upper bounds must be greater or equal to the lower bounds");
kpeter@622
   493
alpar@399
   494
      createStructures();
alpar@399
   495
alpar@399
   496
      for(NodeIt n(_g);n!=INVALID;++n) {
alpar@611
   497
        (*_excess)[n] = (*_supply)[n];
alpar@399
   498
      }
alpar@399
   499
alpar@399
   500
      for (ArcIt e(_g);e!=INVALID;++e) {
alpar@399
   501
        _flow->set(e, (*_lo)[e]);
kpeter@581
   502
        (*_excess)[_g.target(e)] += (*_flow)[e];
kpeter@581
   503
        (*_excess)[_g.source(e)] -= (*_flow)[e];
alpar@399
   504
      }
alpar@399
   505
alpar@399
   506
      // global relabeling tested, but in general case it provides
alpar@399
   507
      // worse performance for random digraphs
alpar@399
   508
      _level->initStart();
alpar@399
   509
      for(NodeIt n(_g);n!=INVALID;++n)
alpar@399
   510
        _level->initAddItem(n);
alpar@399
   511
      _level->initFinish();
alpar@399
   512
      for(NodeIt n(_g);n!=INVALID;++n)
alpar@399
   513
        if(_tol.positive((*_excess)[n]))
alpar@399
   514
          _level->activate(n);
alpar@399
   515
    }
alpar@399
   516
kpeter@402
   517
    /// Initializes the internal data structures using a greedy approach.
alpar@399
   518
kpeter@402
   519
    /// Initializes the internal data structures using a greedy approach
kpeter@402
   520
    /// to construct the initial solution.
alpar@399
   521
    void greedyInit()
alpar@399
   522
    {
kpeter@622
   523
      LEMON_DEBUG(checkBoundMaps(),
kpeter@622
   524
        "Upper bounds must be greater or equal to the lower bounds");
kpeter@622
   525
alpar@399
   526
      createStructures();
alpar@399
   527
alpar@399
   528
      for(NodeIt n(_g);n!=INVALID;++n) {
alpar@611
   529
        (*_excess)[n] = (*_supply)[n];
alpar@399
   530
      }
alpar@399
   531
alpar@399
   532
      for (ArcIt e(_g);e!=INVALID;++e) {
kpeter@622
   533
        if (!_tol.less(-(*_excess)[_g.target(e)], (*_up)[e])) {
alpar@399
   534
          _flow->set(e, (*_up)[e]);
kpeter@581
   535
          (*_excess)[_g.target(e)] += (*_up)[e];
kpeter@581
   536
          (*_excess)[_g.source(e)] -= (*_up)[e];
kpeter@622
   537
        } else if (_tol.less(-(*_excess)[_g.target(e)], (*_lo)[e])) {
alpar@399
   538
          _flow->set(e, (*_lo)[e]);
kpeter@581
   539
          (*_excess)[_g.target(e)] += (*_lo)[e];
kpeter@581
   540
          (*_excess)[_g.source(e)] -= (*_lo)[e];
alpar@399
   541
        } else {
kpeter@641
   542
          Value fc = -(*_excess)[_g.target(e)];
alpar@399
   543
          _flow->set(e, fc);
kpeter@581
   544
          (*_excess)[_g.target(e)] = 0;
kpeter@581
   545
          (*_excess)[_g.source(e)] -= fc;
alpar@399
   546
        }
alpar@399
   547
      }
alpar@399
   548
alpar@399
   549
      _level->initStart();
alpar@399
   550
      for(NodeIt n(_g);n!=INVALID;++n)
alpar@399
   551
        _level->initAddItem(n);
alpar@399
   552
      _level->initFinish();
alpar@399
   553
      for(NodeIt n(_g);n!=INVALID;++n)
alpar@399
   554
        if(_tol.positive((*_excess)[n]))
alpar@399
   555
          _level->activate(n);
alpar@399
   556
    }
alpar@399
   557
kpeter@402
   558
    ///Executes the algorithm
alpar@399
   559
kpeter@402
   560
    ///This function executes the algorithm.
kpeter@402
   561
    ///
kpeter@402
   562
    ///\return \c true if a feasible circulation is found.
alpar@399
   563
    ///
alpar@399
   564
    ///\sa barrier()
kpeter@402
   565
    ///\sa barrierMap()
alpar@399
   566
    bool start()
alpar@399
   567
    {
alpar@399
   568
alpar@399
   569
      Node act;
alpar@399
   570
      Node bact=INVALID;
alpar@399
   571
      Node last_activated=INVALID;
alpar@399
   572
      while((act=_level->highestActive())!=INVALID) {
alpar@399
   573
        int actlevel=(*_level)[act];
alpar@399
   574
        int mlevel=_node_num;
kpeter@641
   575
        Value exc=(*_excess)[act];
alpar@399
   576
alpar@399
   577
        for(OutArcIt e(_g,act);e!=INVALID; ++e) {
alpar@399
   578
          Node v = _g.target(e);
kpeter@641
   579
          Value fc=(*_up)[e]-(*_flow)[e];
alpar@399
   580
          if(!_tol.positive(fc)) continue;
alpar@399
   581
          if((*_level)[v]<actlevel) {
alpar@399
   582
            if(!_tol.less(fc, exc)) {
alpar@399
   583
              _flow->set(e, (*_flow)[e] + exc);
kpeter@581
   584
              (*_excess)[v] += exc;
alpar@399
   585
              if(!_level->active(v) && _tol.positive((*_excess)[v]))
alpar@399
   586
                _level->activate(v);
kpeter@581
   587
              (*_excess)[act] = 0;
alpar@399
   588
              _level->deactivate(act);
alpar@399
   589
              goto next_l;
alpar@399
   590
            }
alpar@399
   591
            else {
alpar@399
   592
              _flow->set(e, (*_up)[e]);
kpeter@581
   593
              (*_excess)[v] += fc;
alpar@399
   594
              if(!_level->active(v) && _tol.positive((*_excess)[v]))
alpar@399
   595
                _level->activate(v);
alpar@399
   596
              exc-=fc;
alpar@399
   597
            }
alpar@399
   598
          }
alpar@399
   599
          else if((*_level)[v]<mlevel) mlevel=(*_level)[v];
alpar@399
   600
        }
alpar@399
   601
        for(InArcIt e(_g,act);e!=INVALID; ++e) {
alpar@399
   602
          Node v = _g.source(e);
kpeter@641
   603
          Value fc=(*_flow)[e]-(*_lo)[e];
alpar@399
   604
          if(!_tol.positive(fc)) continue;
alpar@399
   605
          if((*_level)[v]<actlevel) {
alpar@399
   606
            if(!_tol.less(fc, exc)) {
alpar@399
   607
              _flow->set(e, (*_flow)[e] - exc);
kpeter@581
   608
              (*_excess)[v] += exc;
alpar@399
   609
              if(!_level->active(v) && _tol.positive((*_excess)[v]))
alpar@399
   610
                _level->activate(v);
kpeter@581
   611
              (*_excess)[act] = 0;
alpar@399
   612
              _level->deactivate(act);
alpar@399
   613
              goto next_l;
alpar@399
   614
            }
alpar@399
   615
            else {
alpar@399
   616
              _flow->set(e, (*_lo)[e]);
kpeter@581
   617
              (*_excess)[v] += fc;
alpar@399
   618
              if(!_level->active(v) && _tol.positive((*_excess)[v]))
alpar@399
   619
                _level->activate(v);
alpar@399
   620
              exc-=fc;
alpar@399
   621
            }
alpar@399
   622
          }
alpar@399
   623
          else if((*_level)[v]<mlevel) mlevel=(*_level)[v];
alpar@399
   624
        }
alpar@399
   625
kpeter@581
   626
        (*_excess)[act] = exc;
alpar@399
   627
        if(!_tol.positive(exc)) _level->deactivate(act);
alpar@399
   628
        else if(mlevel==_node_num) {
alpar@399
   629
          _level->liftHighestActiveToTop();
alpar@399
   630
          _el = _node_num;
alpar@399
   631
          return false;
alpar@399
   632
        }
alpar@399
   633
        else {
alpar@399
   634
          _level->liftHighestActive(mlevel+1);
alpar@399
   635
          if(_level->onLevel(actlevel)==0) {
alpar@399
   636
            _el = actlevel;
alpar@399
   637
            return false;
alpar@399
   638
          }
alpar@399
   639
        }
alpar@399
   640
      next_l:
alpar@399
   641
        ;
alpar@399
   642
      }
alpar@399
   643
      return true;
alpar@399
   644
    }
alpar@399
   645
kpeter@402
   646
    /// Runs the algorithm.
alpar@399
   647
kpeter@402
   648
    /// This function runs the algorithm.
kpeter@402
   649
    ///
kpeter@402
   650
    /// \return \c true if a feasible circulation is found.
kpeter@402
   651
    ///
kpeter@402
   652
    /// \note Apart from the return value, c.run() is just a shortcut of
kpeter@402
   653
    /// the following code.
alpar@399
   654
    /// \code
kpeter@402
   655
    ///   c.greedyInit();
kpeter@402
   656
    ///   c.start();
alpar@399
   657
    /// \endcode
alpar@399
   658
    bool run() {
alpar@399
   659
      greedyInit();
alpar@399
   660
      return start();
alpar@399
   661
    }
alpar@399
   662
alpar@399
   663
    /// @}
alpar@399
   664
alpar@399
   665
    /// \name Query Functions
kpeter@402
   666
    /// The results of the circulation algorithm can be obtained using
kpeter@402
   667
    /// these functions.\n
kpeter@402
   668
    /// Either \ref run() or \ref start() should be called before
kpeter@402
   669
    /// using them.
alpar@399
   670
alpar@399
   671
    ///@{
alpar@399
   672
kpeter@641
   673
    /// \brief Returns the flow value on the given arc.
kpeter@402
   674
    ///
kpeter@641
   675
    /// Returns the flow value on the given arc.
kpeter@402
   676
    ///
kpeter@402
   677
    /// \pre Either \ref run() or \ref init() must be called before
kpeter@402
   678
    /// using this function.
kpeter@641
   679
    Value flow(const Arc& arc) const {
kpeter@402
   680
      return (*_flow)[arc];
kpeter@402
   681
    }
kpeter@402
   682
kpeter@402
   683
    /// \brief Returns a const reference to the flow map.
kpeter@402
   684
    ///
kpeter@402
   685
    /// Returns a const reference to the arc map storing the found flow.
kpeter@402
   686
    ///
kpeter@402
   687
    /// \pre Either \ref run() or \ref init() must be called before
kpeter@402
   688
    /// using this function.
kpeter@420
   689
    const FlowMap& flowMap() const {
kpeter@402
   690
      return *_flow;
kpeter@402
   691
    }
kpeter@402
   692
alpar@399
   693
    /**
kpeter@402
   694
       \brief Returns \c true if the given node is in a barrier.
kpeter@402
   695
alpar@399
   696
       Barrier is a set \e B of nodes for which
kpeter@402
   697
kpeter@610
   698
       \f[ \sum_{uv\in A: u\in B} upper(uv) -
kpeter@610
   699
           \sum_{uv\in A: v\in B} lower(uv) < \sum_{v\in B} sup(v) \f]
kpeter@402
   700
kpeter@402
   701
       holds. The existence of a set with this property prooves that a
kpeter@402
   702
       feasible circualtion cannot exist.
kpeter@402
   703
kpeter@402
   704
       This function returns \c true if the given node is in the found
kpeter@402
   705
       barrier. If a feasible circulation is found, the function
kpeter@402
   706
       gives back \c false for every node.
kpeter@402
   707
kpeter@402
   708
       \pre Either \ref run() or \ref init() must be called before
kpeter@402
   709
       using this function.
kpeter@402
   710
kpeter@402
   711
       \sa barrierMap()
alpar@399
   712
       \sa checkBarrier()
alpar@399
   713
    */
kpeter@420
   714
    bool barrier(const Node& node) const
kpeter@402
   715
    {
kpeter@402
   716
      return (*_level)[node] >= _el;
kpeter@402
   717
    }
kpeter@402
   718
kpeter@402
   719
    /// \brief Gives back a barrier.
kpeter@402
   720
    ///
kpeter@402
   721
    /// This function sets \c bar to the characteristic vector of the
kpeter@402
   722
    /// found barrier. \c bar should be a \ref concepts::WriteMap "writable"
kpeter@402
   723
    /// node map with \c bool (or convertible) value type.
kpeter@402
   724
    ///
kpeter@402
   725
    /// If a feasible circulation is found, the function gives back an
kpeter@402
   726
    /// empty set, so \c bar[v] will be \c false for all nodes \c v.
kpeter@402
   727
    ///
kpeter@402
   728
    /// \note This function calls \ref barrier() for each node,
kpeter@559
   729
    /// so it runs in O(n) time.
kpeter@402
   730
    ///
kpeter@402
   731
    /// \pre Either \ref run() or \ref init() must be called before
kpeter@402
   732
    /// using this function.
kpeter@402
   733
    ///
kpeter@402
   734
    /// \sa barrier()
kpeter@402
   735
    /// \sa checkBarrier()
kpeter@402
   736
    template<class BarrierMap>
kpeter@420
   737
    void barrierMap(BarrierMap &bar) const
alpar@399
   738
    {
alpar@399
   739
      for(NodeIt n(_g);n!=INVALID;++n)
alpar@399
   740
        bar.set(n, (*_level)[n] >= _el);
alpar@399
   741
    }
alpar@399
   742
alpar@399
   743
    /// @}
alpar@399
   744
alpar@399
   745
    /// \name Checker Functions
kpeter@402
   746
    /// The feasibility of the results can be checked using
kpeter@402
   747
    /// these functions.\n
kpeter@402
   748
    /// Either \ref run() or \ref start() should be called before
kpeter@402
   749
    /// using them.
alpar@399
   750
alpar@399
   751
    ///@{
alpar@399
   752
kpeter@402
   753
    ///Check if the found flow is a feasible circulation
kpeter@402
   754
kpeter@402
   755
    ///Check if the found flow is a feasible circulation,
kpeter@402
   756
    ///
kpeter@420
   757
    bool checkFlow() const {
alpar@399
   758
      for(ArcIt e(_g);e!=INVALID;++e)
alpar@399
   759
        if((*_flow)[e]<(*_lo)[e]||(*_flow)[e]>(*_up)[e]) return false;
alpar@399
   760
      for(NodeIt n(_g);n!=INVALID;++n)
alpar@399
   761
        {
kpeter@641
   762
          Value dif=-(*_supply)[n];
alpar@399
   763
          for(InArcIt e(_g,n);e!=INVALID;++e) dif-=(*_flow)[e];
alpar@399
   764
          for(OutArcIt e(_g,n);e!=INVALID;++e) dif+=(*_flow)[e];
alpar@399
   765
          if(_tol.negative(dif)) return false;
alpar@399
   766
        }
alpar@399
   767
      return true;
alpar@399
   768
    }
alpar@399
   769
alpar@399
   770
    ///Check whether or not the last execution provides a barrier
alpar@399
   771
kpeter@402
   772
    ///Check whether or not the last execution provides a barrier.
alpar@399
   773
    ///\sa barrier()
kpeter@402
   774
    ///\sa barrierMap()
kpeter@420
   775
    bool checkBarrier() const
alpar@399
   776
    {
kpeter@641
   777
      Value delta=0;
kpeter@641
   778
      Value inf_cap = std::numeric_limits<Value>::has_infinity ?
kpeter@641
   779
        std::numeric_limits<Value>::infinity() :
kpeter@641
   780
        std::numeric_limits<Value>::max();
alpar@399
   781
      for(NodeIt n(_g);n!=INVALID;++n)
alpar@399
   782
        if(barrier(n))
kpeter@610
   783
          delta-=(*_supply)[n];
alpar@399
   784
      for(ArcIt e(_g);e!=INVALID;++e)
alpar@399
   785
        {
alpar@399
   786
          Node s=_g.source(e);
alpar@399
   787
          Node t=_g.target(e);
kpeter@622
   788
          if(barrier(s)&&!barrier(t)) {
kpeter@622
   789
            if (_tol.less(inf_cap - (*_up)[e], delta)) return false;
kpeter@622
   790
            delta+=(*_up)[e];
kpeter@622
   791
          }
alpar@399
   792
          else if(barrier(t)&&!barrier(s)) delta-=(*_lo)[e];
alpar@399
   793
        }
alpar@399
   794
      return _tol.negative(delta);
alpar@399
   795
    }
alpar@399
   796
alpar@399
   797
    /// @}
alpar@399
   798
alpar@399
   799
  };
alpar@399
   800
alpar@399
   801
}
alpar@399
   802
alpar@399
   803
#endif