RhodeCode

 */

namespace lemon {

/**

\page min_cost_flow Minimum Cost Flow Problem

\section mcf_def Definition (GEQ form)

The \e minimum \e cost \e flow \e problem is to find a feasible flow of

minimum total cost from a set of supply nodes to a set of demand nodes

in a network with capacity constraints (lower and upper bounds)

and arc costs.

Formally, let \f$G=(V,A)\f$ be a digraph, \f$lower: A\rightarrow\mathbf{R}\f$,

\f$upper: A\rightarrow\mathbf{R}\cup\{+\infty\}\f$ denote the lower and

upper bounds for the flow values on the arcs, for which

\f$lower(uv) \leq upper(uv)\f$ must hold for all \f$uv\in A\f$,

\f$cost: A\rightarrow\mathbf{R}\f$ denotes the cost per unit flow

on the arcs and \f$sup: V\rightarrow\mathbf{R}\f$ denotes the

signed supply values of the nodes.

If \f$sup(u)>0\f$, then \f$u\f$ is a supply node with \f$sup(u)\f$

supply, if \f$sup(u)<0\f$, then \f$u\f$ is a demand node with

\f$-sup(u)\f$ demand.

A minimum cost flow is an \f$f: A\rightarrow\mathbf{R}\f$ solution

of the following optimization problem.

\f[ \min\sum_{uv\in A} f(uv) \cdot cost(uv) \f]

\f[ \sum_{uv\in A} f(uv) - \sum_{vu\in A} f(vu) \geq

    sup(u) \quad \forall u\in V \f]

\f[ lower(uv) \leq f(uv) \leq upper(uv) \quad \forall uv\in A \f]

The sum of the supply values, i.e. \f$\sum_{u\in V} sup(u)\f$ must be

zero or negative in order to have a feasible solution (since the sum

of the expressions on the left-hand side of the inequalities is zero).

It means that the total demand must be greater or equal to the total

supply and all the supplies have to be carried out from the supply nodes,

but there could be demands that are not satisfied.

If \f$\sum_{u\in V} sup(u)\f$ is zero, then all the supply/demand

constraints have to be satisfied with equality, i.e. all demands

have to be satisfied and all supplies have to be used.

\section mcf_algs Algorithms

LEMON contains several algorithms for solving this problem, for more

information see \ref min_cost_flow_algs "Minimum Cost Flow Algorithms".

A feasible solution for this problem can be found using \ref Circulation.

\section mcf_dual Dual Solution

The dual solution of the minimum cost flow problem is represented by

node potentials \f$\pi: V\rightarrow\mathbf{R}\f$.

An \f$f: A\rightarrow\mathbf{R}\f$ primal feasible solution is optimal

if and only if for some \f$\pi: V\rightarrow\mathbf{R}\f$ node potentials

the following \e complementary \e slackness optimality conditions hold.

 - For all \f$uv\in A\f$ arcs:

   - if \f$cost^\pi(uv)>0\f$, then \f$f(uv)=lower(uv)\f$;

   - if \f$lower(uv)<f(uv)<upper(uv)\f$, then \f$cost^\pi(uv)=0\f$;

   - if \f$cost^\pi(uv)<0\f$, then \f$f(uv)=upper(uv)\f$.

 - For all \f$u\in V\f$ nodes:

   - if \f$\sum_{uv\in A} f(uv) - \sum_{vu\in A} f(vu) \neq sup(u)\f$,

     then \f$\pi(u)=0\f$.

Here \f$cost^\pi(uv)\f$ denotes the \e reduced \e cost of the arc

\f$uv\in A\f$ with respect to the potential function \f$\pi\f$, i.e.

\f[ cost^\pi(uv) = cost(uv) + \pi(u) - \pi(v).\f]

All algorithms provide dual solution (node potentials), as well,

if an optimal flow is found.

\section mcf_eq Equality Form

The above \ref mcf_def "definition" is actually more general than the

usual formulation of the minimum cost flow problem, in which strict

equalities are required in the supply/demand contraints.

\f[ \min\sum_{uv\in A} f(uv) \cdot cost(uv) \f]

\f[ \sum_{uv\in A} f(uv) - \sum_{vu\in A} f(vu) =

    sup(u) \quad \forall u\in V \f]

\f[ lower(uv) \leq f(uv) \leq upper(uv) \quad \forall uv\in A \f]

However if the sum of the supply values is zero, then these two problems

are equivalent.

The \ref min_cost_flow_algs "algorithms" in LEMON support the general

form, so if you need the equality form, you have to ensure this additional

contraint manually.

\section mcf_leq Opposite Inequalites (LEQ Form)

Another possible definition of the minimum cost flow problem is

when there are <em>"less or equal"</em> (LEQ) supply/demand constraints,

instead of the <em>"greater or equal"</em> (GEQ) constraints.

\f[ \min\sum_{uv\in A} f(uv) \cdot cost(uv) \f]

\f[ \sum_{uv\in A} f(uv) - \sum_{vu\in A} f(vu) \leq

    sup(u) \quad \forall u\in V \f]

\f[ lower(uv) \leq f(uv) \leq upper(uv) \quad \forall uv\in A \f]

It means that the total demand must be less or equal to the 

total supply (i.e. \f$\sum_{u\in V} sup(u)\f$ must be zero or

positive) and all the demands have to be satisfied, but there

could be supplies that are not carried out from the supply

nodes.

The equality form is also a special case of this form, of course.

You could easily transform this case to the \ref mcf_def "GEQ form"

of the problem by reversing the direction of the arcs and taking the

negative of the supply values (e.g. using \ref ReverseDigraph and

\ref NegMap adaptors).

However \ref NetworkSimplex algorithm also supports this form directly

for the sake of convenience.

Note that the optimality conditions for this supply constraint type are

slightly differ from the conditions that are discussed for the GEQ form,

namely the potentials have to be non-negative instead of non-positive.

An \f$f: A\rightarrow\mathbf{R}\f$ feasible solution of this problem

is optimal if and only if for some \f$\pi: V\rightarrow\mathbf{R}\f$

node potentials the following conditions hold.

 - For all \f$uv\in A\f$ arcs:

   - if \f$cost^\pi(uv)>0\f$, then \f$f(uv)=lower(uv)\f$;

   - if \f$lower(uv)<f(uv)<upper(uv)\f$, then \f$cost^\pi(uv)=0\f$;

   - if \f$cost^\pi(uv)<0\f$, then \f$f(uv)=upper(uv)\f$.

 - For all \f$u\in V\f$ nodes:

   - if \f$\sum_{uv\in A} f(uv) - \sum_{vu\in A} f(vu) \neq sup(u)\f$,

     then \f$\pi(u)=0\f$.

*/

}

      }

      _mask = new MaskMap(*_gr, false);

    }

  public :

    typedef BellmanFord Create;

    /// \name Named Template Parameters

    ///@{

    template <class T>

    struct SetPredMapTraits : public Traits {

      typedef T PredMap;

      static PredMap *createPredMap(const Digraph&) {

        LEMON_ASSERT(false, "PredMap is not initialized");

        return 0; // ignore warnings

      }

    };

    /// \brief \ref named-templ-param "Named parameter" for setting

    /// \c PredMap type.

    ///

    /// \ref named-templ-param "Named parameter" for setting

    /// \c PredMap type.

    /// It must conform to the \ref concepts::WriteMap "WriteMap" concept.

    template <class T>

    struct SetPredMap 

      : public BellmanFord< Digraph, LengthMap, SetPredMapTraits<T> > {

      typedef BellmanFord< Digraph, LengthMap, SetPredMapTraits<T> > Create;

    };

    template <class T>

    struct SetDistMapTraits : public Traits {

      typedef T DistMap;

      static DistMap *createDistMap(const Digraph&) {

        LEMON_ASSERT(false, "DistMap is not initialized");

        return 0; // ignore warnings

      }

    };

    /// \brief \ref named-templ-param "Named parameter" for setting

    /// \c DistMap type.

    ///

    /// \ref named-templ-param "Named parameter" for setting

    /// \c DistMap type.

    /// It must conform to the \ref concepts::WriteMap "WriteMap" concept.

    template <class T>

    struct SetDistMap 

      : public BellmanFord< Digraph, LengthMap, SetDistMapTraits<T> > {

      typedef BellmanFord< Digraph, LengthMap, SetDistMapTraits<T> > Create;

    };

    template <class T>

    struct SetOperationTraitsTraits : public Traits {

      typedef T OperationTraits;

    };

    /// \brief \ref named-templ-param "Named parameter" for setting 

    /// \c OperationTraits type.

    ///

    /// \ref named-templ-param "Named parameter" for setting

    /// \c OperationTraits type.

    template <class T>

    struct SetOperationTraits

      : public BellmanFord< Digraph, LengthMap, SetOperationTraitsTraits<T> > {

      typedef BellmanFord< Digraph, LengthMap, SetOperationTraitsTraits<T> >

      Create;

    };

    ///@}

  protected:

    BellmanFord() {}

  public:      

    /// \brief Constructor.

    ///

    /// Constructor.

    /// \param g The digraph the algorithm runs on.

    /// \param length The length map used by the algorithm.

    BellmanFord(const Digraph& g, const LengthMap& length) :

      _gr(&g), _length(&length),

      _pred(0), _local_pred(false),

      _dist(0), _local_dist(false), _mask(0) {}

    ///Destructor.

    ~BellmanFord() {

      if(_local_pred) delete _pred;

      if(_local_dist) delete _dist;

      if(_mask) delete _mask;

    }

    /// \brief Sets the length map.

    ///

    /// Sets the length map.

    /// \return <tt>(*this)</tt>

    BellmanFord &lengthMap(const LengthMap &map) {

      _length = ↦

      return *this;

    }

    /// \brief Sets the map that stores the predecessor arcs.

    ///

    /// Sets the map that stores the predecessor arcs.

    /// If you don't use this function before calling \ref run()

    /// or \ref init(), an instance will be allocated automatically.

    /// The destructor deallocates this automatically allocated map,

    /// of course.

    /// \return <tt>(*this)</tt>

    BellmanFord &predMap(PredMap &map) {

      if(_local_pred) {

	delete _pred;

	_local_pred=false;

      }

      _pred = ↦

      return *this;

    }

    /// \brief Sets the map that stores the distances of the nodes.

    ///

    /// Sets the map that stores the distances of the nodes calculated

    /// by the algorithm.

    /// If you don't use this function before calling \ref run()

    /// or \ref init(), an instance will be allocated automatically.

      /// \brief Increment operator.

      ///

      /// Increment operator.

      ActiveIt& operator++() {

        --_index;

        return *this; 

      }

      bool operator==(const ActiveIt& it) const { 

        return static_cast<Node>(*this) == static_cast<Node>(it); 

      }

      bool operator!=(const ActiveIt& it) const { 

        return static_cast<Node>(*this) != static_cast<Node>(it); 

      }

      bool operator<(const ActiveIt& it) const { 

        return static_cast<Node>(*this) < static_cast<Node>(it); 

      }

    private:

      const BellmanFord* _algorithm;

      int _index;

    };

    /// \name Query Functions

    /// The result of the Bellman-Ford algorithm can be obtained using these

    /// functions.\n

    /// Either \ref run() or \ref init() should be called before using them.

    ///@{

    /// \brief The shortest path to the given node.

    ///    

    /// Gives back the shortest path to the given node from the root(s).

    ///

    /// \warning \c t should be reached from the root(s).

    ///

    /// \pre Either \ref run() or \ref init() must be called before

    /// using this function.

    Path path(Node t) const

    {

      return Path(*_gr, *_pred, t);

    }

    /// \brief The distance of the given node from the root(s).

    ///

    /// Returns the distance of the given node from the root(s).

    ///

    /// \warning If node \c v is not reached from the root(s), then

    /// the return value of this function is undefined.

    ///

    /// \pre Either \ref run() or \ref init() must be called before

    /// using this function.

    Value dist(Node v) const { return (*_dist)[v]; }

    /// \brief Returns the 'previous arc' of the shortest path tree for

    /// the given node.

    ///

    /// This function returns the 'previous arc' of the shortest path

    /// tree for node \c v, i.e. it returns the last arc of a

    /// shortest path from a root to \c v. It is \c INVALID if \c v

    /// is not reached from the root(s) or if \c v is a root.

    ///

    /// The shortest path tree used here is equal to the shortest path

    ///

    /// \pre Either \ref run() or \ref init() must be called before

    /// using this function.

    Arc predArc(Node v) const { return (*_pred)[v]; }

    /// \brief Returns the 'previous node' of the shortest path tree for

    /// the given node.

    ///

    /// This function returns the 'previous node' of the shortest path

    /// tree for node \c v, i.e. it returns the last but one node of

    /// a shortest path from a root to \c v. It is \c INVALID if \c v

    /// is not reached from the root(s) or if \c v is a root.

    ///

    /// The shortest path tree used here is equal to the shortest path

    ///

    /// \pre Either \ref run() or \ref init() must be called before

    /// using this function.

    Node predNode(Node v) const { 

      return (*_pred)[v] == INVALID ? INVALID : _gr->source((*_pred)[v]); 

    }

    /// \brief Returns a const reference to the node map that stores the

    /// distances of the nodes.

    ///

    /// Returns a const reference to the node map that stores the distances

    /// of the nodes calculated by the algorithm.

    ///

    /// \pre Either \ref run() or \ref init() must be called before

    /// using this function.

    const DistMap &distMap() const { return *_dist;}

    /// \brief Returns a const reference to the node map that stores the

    /// predecessor arcs.

    ///

    /// Returns a const reference to the node map that stores the predecessor

    /// arcs, which form the shortest path tree (forest).

    ///

    /// \pre Either \ref run() or \ref init() must be called before

    /// using this function.

    const PredMap &predMap() const { return *_pred; }

    /// \brief Checks if a node is reached from the root(s).

    ///

    /// Returns \c true if \c v is reached from the root(s).

    ///

    /// \pre Either \ref run() or \ref init() must be called before

    /// using this function.

    bool reached(Node v) const {

      return (*_dist)[v] != OperationTraits::infinity();

    }

    /// \brief Gives back a negative cycle.

    ///    

    /// This function gives back a directed cycle with negative total

    /// length if the algorithm has already found one.

    /// Otherwise it gives back an empty path.

    lemon::Path<Digraph> negativeCycle() {

      typename Digraph::template NodeMap<int> state(*_gr, -1);

      lemon::Path<Digraph> cycle;

      for (int i = 0; i < int(_process.size()); ++i) {

        if (state[_process[i]] != -1) continue;

        for (Node v = _process[i]; (*_pred)[v] != INVALID;

             v = _gr->source((*_pred)[v])) {

          if (state[v] == i) {

            cycle.addFront((*_pred)[v]);

            for (Node u = _gr->source((*_pred)[v]); u != v;

                 u = _gr->source((*_pred)[u])) {

              cycle.addFront((*_pred)[u]);

            }

            return cycle;

          }

          else if (state[v] >= 0) {

            break;

          }

          state[v] = i;

        }

      }

      return cycle;

 *

 * This file is a part of LEMON, a generic C++ optimization library.

 *

 * Copyright (C) 2003-2009

 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport

 * (Egervary Research Group on Combinatorial Optimization, EGRES).

 *

 * Permission to use, modify and distribute this software is granted

 * provided that this copyright notice appears in all copies. For

 * precise terms see the accompanying LICENSE file.

 *

 * This software is provided "AS IS" with no warranty of any kind,

 * express or implied, and with no claim as to its suitability for any

 * purpose.

 *

 */

#ifndef LEMON_BFS_H

#define LEMON_BFS_H

///\ingroup search

///\file

///\brief BFS algorithm.

#include <lemon/list_graph.h>

#include <lemon/bits/path_dump.h>

#include <lemon/core.h>

#include <lemon/error.h>

#include <lemon/maps.h>

#include <lemon/path.h>

namespace lemon {

  ///Default traits class of Bfs class.

  ///Default traits class of Bfs class.

  ///\tparam GR Digraph type.

  template<class GR>

  struct BfsDefaultTraits

  {

    ///The type of the digraph the algorithm runs on.

    typedef GR Digraph;

    ///\brief The type of the map that stores the predecessor

    ///arcs of the shortest paths.

    ///

    ///The type of the map that stores the predecessor

    ///arcs of the shortest paths.

    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.

    typedef typename Digraph::template NodeMap<typename Digraph::Arc> PredMap;

    ///Instantiates a \c PredMap.

    ///This function instantiates a \ref PredMap.

    ///\param g is the digraph, to which we would like to define the

    ///\ref PredMap.

    static PredMap *createPredMap(const Digraph &g)

    {

      return new PredMap(g);

    }

    ///The type of the map that indicates which nodes are processed.

    ///The type of the map that indicates which nodes are processed.

    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.

    typedef NullMap<typename Digraph::Node,bool> ProcessedMap;

    ///Instantiates a \c ProcessedMap.

    ///This function instantiates a \ref ProcessedMap.

    ///\param g is the digraph, to which

    ///we would like to define the \ref ProcessedMap

#ifdef DOXYGEN

    static ProcessedMap *createProcessedMap(const Digraph &g)

#else

    static ProcessedMap *createProcessedMap(const Digraph &)

#endif

    {

      return new ProcessedMap();

    }

    ///The type of the map that indicates which nodes are reached.

    ///The type of the map that indicates which nodes are reached.

    ///It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.

    typedef typename Digraph::template NodeMap<bool> ReachedMap;

    ///Instantiates a \c ReachedMap.

    ///This function instantiates a \ref ReachedMap.

    ///\param g is the digraph, to which

    ///we would like to define the \ref ReachedMap.

    static ReachedMap *createReachedMap(const Digraph &g)

    {

      return new ReachedMap(g);

    }

    ///The type of the map that stores the distances of the nodes.

    ///The type of the map that stores the distances of the nodes.

    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.

    typedef typename Digraph::template NodeMap<int> DistMap;

    ///Instantiates a \c DistMap.

    ///This function instantiates a \ref DistMap.

    ///\param g is the digraph, to which we would like to define the

    ///\ref DistMap.

    static DistMap *createDistMap(const Digraph &g)

    {

      return new DistMap(g);

    }

  };

  ///%BFS algorithm class.

  ///\ingroup search

  ///This class provides an efficient implementation of the %BFS algorithm.

  ///

  ///There is also a \ref bfs() "function-type interface" for the BFS

  ///algorithm, which is convenient in the simplier cases and it can be

  ///used easier.

  ///

  ///\tparam GR The type of the digraph the algorithm runs on.

  ///The default type is \ref ListDigraph.

#ifdef DOXYGEN

  template <typename GR,

            typename TR>

#else

  template <typename GR=ListDigraph,

            typename TR=BfsDefaultTraits<GR> >

#endif

                                  G->source((*_pred)[v]); }

    ///\brief Returns a const reference to the node map that stores the

    /// distances of the nodes.

    ///

    ///Returns a const reference to the node map that stores the distances

    ///of the nodes calculated by the algorithm.

    ///

    ///\pre Either \ref run(Node) "run()" or \ref init()

    ///must be called before using this function.

    const DistMap &distMap() const { return *_dist;}

    ///\brief Returns a const reference to the node map that stores the

    ///predecessor arcs.

    ///

    ///Returns a const reference to the node map that stores the predecessor

    ///arcs, which form the shortest path tree (forest).

    ///

    ///\pre Either \ref run(Node) "run()" or \ref init()

    ///must be called before using this function.

    const PredMap &predMap() const { return *_pred;}

    ///Checks if the given node is reached from the root(s).

    ///Returns \c true if \c v is reached from the root(s).

    ///

    ///\pre Either \ref run(Node) "run()" or \ref init()

    ///must be called before using this function.

    bool reached(Node v) const { return (*_reached)[v]; }

    ///@}

  };

  ///Default traits class of bfs() function.

  ///Default traits class of bfs() function.

  ///\tparam GR Digraph type.

  template<class GR>

  struct BfsWizardDefaultTraits

  {

    ///The type of the digraph the algorithm runs on.

    typedef GR Digraph;

    ///\brief The type of the map that stores the predecessor

    ///arcs of the shortest paths.

    ///

    ///The type of the map that stores the predecessor

    ///arcs of the shortest paths.

    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.

    typedef typename Digraph::template NodeMap<typename Digraph::Arc> PredMap;

    ///Instantiates a PredMap.

    ///This function instantiates a PredMap.

    ///\param g is the digraph, to which we would like to define the

    ///PredMap.

    static PredMap *createPredMap(const Digraph &g)

    {

      return new PredMap(g);

    }

    ///The type of the map that indicates which nodes are processed.

    ///The type of the map that indicates which nodes are processed.

    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.

    typedef NullMap<typename Digraph::Node,bool> ProcessedMap;

    ///Instantiates a ProcessedMap.

    ///This function instantiates a ProcessedMap.

    ///\param g is the digraph, to which

    ///we would like to define the ProcessedMap.

#ifdef DOXYGEN

    static ProcessedMap *createProcessedMap(const Digraph &g)

#else

    static ProcessedMap *createProcessedMap(const Digraph &)

#endif

    {

      return new ProcessedMap();

    }

    ///The type of the map that indicates which nodes are reached.

    ///The type of the map that indicates which nodes are reached.

    ///It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.

    typedef typename Digraph::template NodeMap<bool> ReachedMap;

    ///Instantiates a ReachedMap.

    ///This function instantiates a ReachedMap.

    ///\param g is the digraph, to which

    ///we would like to define the ReachedMap.

    static ReachedMap *createReachedMap(const Digraph &g)

    {

      return new ReachedMap(g);

    }

    ///The type of the map that stores the distances of the nodes.

    ///The type of the map that stores the distances of the nodes.

    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.

    typedef typename Digraph::template NodeMap<int> DistMap;

    ///Instantiates a DistMap.

    ///This function instantiates a DistMap.

    ///\param g is the digraph, to which we would like to define

    ///the DistMap

    static DistMap *createDistMap(const Digraph &g)

    {

      return new DistMap(g);

    }

    ///The type of the shortest paths.

    ///The type of the shortest paths.

    ///It must conform to the \ref concepts::Path "Path" concept.

    typedef lemon::Path<Digraph> Path;

  };

  /// Default traits class used by BfsWizard

  /// Default traits class used by BfsWizard.

  /// \tparam GR The type of the digraph.

  template<class GR>

  class BfsWizardBase : public BfsWizardDefaultTraits<GR>

  {

    typedef BfsWizardDefaultTraits<GR> Base;

  protected:

    //The type of the nodes in the digraph.

    typedef typename Base::Digraph::Node Node;

    template <typename T>

    struct SetFlowMapTraits : public Traits {

      typedef T FlowMap;

      static FlowMap *createFlowMap(const Digraph&) {

        LEMON_ASSERT(false, "FlowMap is not initialized");

        return 0; // ignore warnings

      }

    };

    /// \brief \ref named-templ-param "Named parameter" for setting

    /// FlowMap type

    ///

    /// \ref named-templ-param "Named parameter" for setting FlowMap

    /// type.

    template <typename T>

    struct SetFlowMap

      : public Circulation<Digraph, LowerMap, UpperMap, SupplyMap,

                           SetFlowMapTraits<T> > {

      typedef Circulation<Digraph, LowerMap, UpperMap, SupplyMap,

                          SetFlowMapTraits<T> > Create;

    };

    template <typename T>

    struct SetElevatorTraits : public Traits {

      typedef T Elevator;

      static Elevator *createElevator(const Digraph&, int) {

        LEMON_ASSERT(false, "Elevator is not initialized");

        return 0; // ignore warnings

      }

    };

    /// \brief \ref named-templ-param "Named parameter" for setting

    /// Elevator type

    ///

    /// \ref named-templ-param "Named parameter" for setting Elevator

    /// type. If this named parameter is used, then an external

    /// elevator object must be passed to the algorithm using the

    /// \ref elevator(Elevator&) "elevator()" function before calling

    /// \ref run() or \ref init().

    /// \sa SetStandardElevator

    template <typename T>

    struct SetElevator

      : public Circulation<Digraph, LowerMap, UpperMap, SupplyMap,

                           SetElevatorTraits<T> > {

      typedef Circulation<Digraph, LowerMap, UpperMap, SupplyMap,

                          SetElevatorTraits<T> > Create;

    };

    template <typename T>

    struct SetStandardElevatorTraits : public Traits {

      typedef T Elevator;

      static Elevator *createElevator(const Digraph& digraph, int max_level) {

        return new Elevator(digraph, max_level);

      }

    };

    /// \brief \ref named-templ-param "Named parameter" for setting

    /// Elevator type with automatic allocation

    ///

    /// \ref named-templ-param "Named parameter" for setting Elevator

    /// type with automatic allocation.

    /// The Elevator should have standard constructor interface to be

    /// able to automatically created by the algorithm (i.e. the

    /// digraph and the maximum level should be passed to it).

    /// algorithm with the \ref elevator(Elevator&) "elevator()" function

    /// before calling \ref run() or \ref init().

    /// \sa SetElevator

    template <typename T>

    struct SetStandardElevator

      : public Circulation<Digraph, LowerMap, UpperMap, SupplyMap,

                       SetStandardElevatorTraits<T> > {

      typedef Circulation<Digraph, LowerMap, UpperMap, SupplyMap,

                      SetStandardElevatorTraits<T> > Create;

    };

    /// @}

  protected:

    Circulation() {}

  public:

    /// Constructor.

    /// The constructor of the class.

    ///

    /// \param graph The digraph the algorithm runs on.

    /// \param lower The lower bounds for the flow values on the arcs.

    /// \param upper The upper bounds (capacities) for the flow values 

    /// on the arcs.

    /// \param supply The signed supply values of the nodes.

    Circulation(const Digraph &graph, const LowerMap &lower,

                const UpperMap &upper, const SupplyMap &supply)

      : _g(graph), _lo(&lower), _up(&upper), _supply(&supply),

        _flow(NULL), _local_flow(false), _level(NULL), _local_level(false),

        _excess(NULL) {}

    /// Destructor.

    ~Circulation() {

      destroyStructures();

    }

  private:

    bool checkBoundMaps() {

      for (ArcIt e(_g);e!=INVALID;++e) {

        if (_tol.less((*_up)[e], (*_lo)[e])) return false;

      }

      return true;

    }

    void createStructures() {

      _node_num = _el = countNodes(_g);

      if (!_flow) {

        _flow = Traits::createFlowMap(_g);

        _local_flow = true;

      }

      if (!_level) {

        _level = Traits::createElevator(_g, _node_num);

        _local_level = true;

      }

      if (!_excess) {

        _excess = new ExcessMap(_g);

      }

    }

    /// \ref SmartDigraph may have additional functionality.

    ///

    /// \sa Graph

    class Digraph {

    private:

      /// Diraphs are \e not copy constructible. Use DigraphCopy instead.

      Digraph(const Digraph &) {}

      /// \brief Assignment of a digraph to another one is \e not allowed.

      /// Use DigraphCopy instead.

      void operator=(const Digraph &) {}

    public:

      /// Default constructor.

      Digraph() { }

      /// The node type of the digraph

      /// This class identifies a node of the digraph. It also serves

      /// as a base class of the node iterators,

      /// thus they convert to this type.

      class Node {

      public:

        /// Default constructor

        /// Default constructor.

        /// \warning It sets the object to an undefined value.

        Node() { }

        /// Copy constructor.

        /// Copy constructor.

        ///

        Node(const Node&) { }

        /// %Invalid constructor \& conversion.

        /// Initializes the object to be invalid.

        /// \sa Invalid for more details.

        Node(Invalid) { }

        /// Equality operator

        /// Equality operator.

        ///

        /// Two iterators are equal if and only if they point to the

        /// same object or both are \c INVALID.

        bool operator==(Node) const { return true; }

        /// Inequality operator

        /// Inequality operator.

        bool operator!=(Node) const { return true; }

        /// Artificial ordering operator.

        /// Artificial ordering operator.

        ///

        /// \note This operator only has to define some strict ordering of

        /// the nodes; this order has nothing to do with the iteration

        /// ordering of the nodes.

        bool operator<(Node) const { return false; }

      };

      /// Iterator class for the nodes.

      /// This iterator goes through each node of the digraph.

      /// of nodes in a digraph \c g of type \c %Digraph like this:

      ///\code

      /// int count=0;

      /// for (Digraph::NodeIt n(g); n!=INVALID; ++n) ++count;

      ///\endcode

      class NodeIt : public Node {

      public:

        /// Default constructor

        /// Default constructor.

        /// \warning It sets the iterator to an undefined value.

        NodeIt() { }

        /// Copy constructor.

        /// Copy constructor.

        ///

        NodeIt(const NodeIt& n) : Node(n) { }

        /// %Invalid constructor \& conversion.

        /// Initializes the iterator to be invalid.

        /// \sa Invalid for more details.

        NodeIt(Invalid) { }

        /// Sets the iterator to the first node.

        /// Sets the iterator to the first node of the given digraph.

        ///

        explicit NodeIt(const Digraph&) { }

        /// Sets the iterator to the given node.

        /// Sets the iterator to the given node of the given digraph.

        ///

        NodeIt(const Digraph&, const Node&) { }

        /// Next node.

        /// Assign the iterator to the next node.

        ///

        NodeIt& operator++() { return *this; }

      };

      /// The arc type of the digraph

      /// This class identifies an arc of the digraph. It also serves

      /// as a base class of the arc iterators,

      /// thus they will convert to this type.

      class Arc {

      public:

        /// Default constructor

        /// Default constructor.

        /// \warning It sets the object to an undefined value.

        Arc() { }

        /// Copy constructor.

        /// Copy constructor.

        ///

        Arc(const Arc&) { }

        /// %Invalid constructor \& conversion.

        /// Initializes the object to be invalid.

        /// \sa Invalid for more details.

        Arc(Invalid) { }

        /// Equality operator

        /// Equality operator.

        ///

        /// Two iterators are equal if and only if they point to the

        /// same object or both are \c INVALID.

        bool operator==(Arc) const { return true; }

        /// Inequality operator

        /// Inequality operator.

        bool operator!=(Arc) const { return true; }

        /// Artificial ordering operator.

        /// Artificial ordering operator.

        ///

        /// \note This operator only has to define some strict ordering of

        /// the arcs; this order has nothing to do with the iteration

        /// ordering of the arcs.

        bool operator<(Arc) const { return false; }

      };

      /// Iterator class for the outgoing arcs of a node.

      /// This iterator goes trough the \e outgoing arcs of a certain node

      /// of a digraph.

      /// of outgoing arcs of a node \c n

      /// in a digraph \c g of type \c %Digraph as follows.

      ///\code

      /// int count=0;

      /// for (Digraph::OutArcIt a(g, n); a!=INVALID; ++a) ++count;

      ///\endcode

      class OutArcIt : public Arc {

      public:

        /// Default constructor

        /// Default constructor.

        /// \warning It sets the iterator to an undefined value.

        OutArcIt() { }

        /// Copy constructor.

        /// Copy constructor.

        ///

        OutArcIt(const OutArcIt& e) : Arc(e) { }

        /// %Invalid constructor \& conversion.

        /// Initializes the iterator to be invalid.

        /// \sa Invalid for more details.

        OutArcIt(Invalid) { }

        /// Sets the iterator to the first outgoing arc.

        /// Sets the iterator to the first outgoing arc of the given node.

        ///

        OutArcIt(const Digraph&, const Node&) { }

        /// Sets the iterator to the given arc.

        /// Sets the iterator to the given arc of the given digraph.

        ///

        OutArcIt(const Digraph&, const Arc&) { }

        /// Next outgoing arc

        /// Assign the iterator to the next

        /// outgoing arc of the corresponding node.

        OutArcIt& operator++() { return *this; }

      };

      /// Iterator class for the incoming arcs of a node.

      /// This iterator goes trough the \e incoming arcs of a certain node

      /// of a digraph.

      /// of incoming arcs of a node \c n

      /// in a digraph \c g of type \c %Digraph as follows.

      ///\code

      /// int count=0;

      /// for(Digraph::InArcIt a(g, n); a!=INVALID; ++a) ++count;

      ///\endcode

      class InArcIt : public Arc {

      public:

        /// Default constructor

        /// Default constructor.

        /// \warning It sets the iterator to an undefined value.

        InArcIt() { }

        /// Copy constructor.

        /// Copy constructor.

        ///

        InArcIt(const InArcIt& e) : Arc(e) { }

        /// %Invalid constructor \& conversion.

        /// Initializes the iterator to be invalid.

        /// \sa Invalid for more details.

        InArcIt(Invalid) { }

        /// Sets the iterator to the first incoming arc.

        /// Sets the iterator to the first incoming arc of the given node.

        ///

        InArcIt(const Digraph&, const Node&) { }

        /// Sets the iterator to the given arc.

        /// Sets the iterator to the given arc of the given digraph.

        ///

        InArcIt(const Digraph&, const Arc&) { }

        /// Next incoming arc

        /// Assign the iterator to the next

        /// incoming arc of the corresponding node.

        InArcIt& operator++() { return *this; }

      };

      /// Iterator class for the arcs.

      /// This iterator goes through each arc of the digraph.

      /// of arcs in a digraph \c g of type \c %Digraph as follows:

      ///\code

      /// int count=0;

      /// for(Digraph::ArcIt a(g); a!=INVALID; ++a) ++count;

      ///\endcode

      class ArcIt : public Arc {

      public:

        /// Default constructor

        /// Default constructor.

        /// \warning It sets the iterator to an undefined value.

        ArcIt() { }

        /// Copy constructor.

        /// Copy constructor.

        ///

        ArcIt(const ArcIt& e) : Arc(e) { }

        /// %Invalid constructor \& conversion.

        /// Initializes the iterator to be invalid.

        /// \sa Invalid for more details.

        ArcIt(Invalid) { }

        /// Sets the iterator to the first arc.