RhodeCode

\subsection cs-loc-var Class and instance member variables, auto variables

The names of class and instance member variables and auto variables

(=variables used locally in methods) should look like the following.

\code

all_lower_case_with_underscores

\endcode

\subsection pri-loc-var Private member variables

\code

\endcode

\subsection cs-excep Exceptions

When writing exceptions please comply the following naming conventions.

\code

ClassNameEndsWithException

\endcode

or

LEMON contains several algorithms for this problem.

 - \ref NetworkSimplex Primal Network Simplex algorithm with various

   pivot strategies \ref dantzig63linearprog, \ref kellyoneill91netsimplex.

 - \ref CostScaling Cost Scaling algorithm based on push/augment and

   relabel operations \ref goldberg90approximation, \ref goldberg97efficient,

   \ref bunnagel98efficient.

 - \ref CapacityScaling Capacity Scaling algorithm based on the successive

   shortest path method \ref edmondskarp72theoretical.

 - \ref CycleCanceling Cycle-Canceling algorithms, two of which are

   strongly polynomial \ref klein67primal, \ref goldberg89cyclecanceling.

For example, if the total supply and/or capacities are rather small,

*/

/**

@defgroup min_cut Minimum Cut Algorithms

@ingroup algs

\brief Algorithms for finding minimum cut in graphs.

This group contains the algorithms for finding minimum cut in graphs.

The \e minimum \e cut \e problem is to find a non-empty and non-complete

\f$X\f$ subset of the nodes with minimum overall capacity on

cycle mean is the smallest \f$\epsilon\f$ value so that increasing the

arc lengths uniformly by \f$\epsilon\f$ results in a conservative length

function.

LEMON contains three algorithms for solving the minimum mean cycle problem:

- \ref KarpMmc Karp's original algorithm \ref amo93networkflows,

  \ref dasdan98minmeancycle.

- \ref HartmannOrlinMmc Hartmann-Orlin's algorithm, which is an improved

  version of Karp's algorithm \ref dasdan98minmeancycle.

- \ref HowardMmc Howard's policy iteration algorithm

  \ref dasdan98minmeancycle.

most efficient one, though the best known theoretical bound on its running

time is exponential.

Both \ref KarpMmc "Karp" and \ref HartmannOrlinMmc "Hartmann-Orlin" algorithms

run in time O(ne) and use space O(n<sup>2</sup>+e), but the latter one is

typically faster due to the applied early termination scheme.

*/

/**

@defgroup matching Matching Algorithms

@ingroup algs

\brief Algorithms for finding matchings in graphs and bipartite graphs.

@defgroup graph_properties Connectivity and Other Graph Properties

@ingroup algs

\brief Algorithms for discovering the graph properties

This group contains the algorithms for discovering the graph properties

like connectivity, bipartiteness, euler property, simplicity etc.

\image html connected_components.png

\image latex connected_components.eps "Connected components" width=\textwidth

*/

/**

@ingroup algs

\brief Algorithms for planarity checking, embedding and drawing

This group contains the algorithms for planarity checking,

embedding and drawing.

\image html planar.png

\image latex planar.eps "Plane graph" width=\textwidth

*/

/**

@defgroup approx_algs Approximation Algorithms

  /// and supply values in the algorithm. By default, it is \c int.

  /// \tparam C The number type used for costs and potentials in the

  /// algorithm. By default, it is the same as \c V.

  /// \tparam TR The traits class that defines various types used by the

  /// algorithm. By default, it is \ref CapacityScalingDefaultTraits

  /// "CapacityScalingDefaultTraits<GR, V, C>".

  /// In most cases, this parameter should not be set directly,

  /// consider to use the named template parameters instead.

  ///

  /// \warning Both \c V and \c C must be signed number types.

  /// \warning All input data (capacities, supply values, and costs) must

  /// be integer.

#ifdef DOXYGEN

  template <typename GR, typename V, typename C, typename TR>

#else

  template < typename GR, typename V = int, typename C = V,

             typename TR = CapacityScalingDefaultTraits<GR, V, C> >

#endif

  class CapacityScaling

  {

  public:

    /// The type of the digraph

    typedef typename TR::Digraph Digraph;

      }

      return *this;

    }

    /// \brief Set single source and target nodes and a supply value.

    ///

    /// This function sets a single source node and a single target node

    /// and the required flow value.

    /// If neither this function nor \ref supplyMap() is used before

    /// calling \ref run(), the supply of each node will be set to zero.

    ///

    /// Using this function has the same effect as using \ref supplyMap()

    /// assigned to \c t and all other nodes have zero supply value.

    ///

    /// \param s The source node.

    /// \param t The target node.

    /// \param k The required amount of flow from node \c s to node \c t

    /// (i.e. the supply of \c s and the demand of \c t).

    ///

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

    CapacityScaling& stSupply(const Node& s, const Node& t, Value k) {

      for (int i = 0; i != _node_num; ++i) {

        _supply[i] = 0;

      }

      Graph,

      typename enable_if<typename Graph::BuildTag, void>::type>

    {

      template <typename From, typename NodeRefMap, typename EdgeRefMap>

      static void copy(const From& from, Graph &to,

                       NodeRefMap& nodeRefMap, EdgeRefMap& edgeRefMap) {

        to.build(from, nodeRefMap, edgeRefMap);

      }

    };

  }

  ///

  /// This function returns \c true if the given graph is undirected.

#ifdef DOXYGEN

  template <typename GR>

  bool undirected(const GR& g) { return false; }

#else

  template <typename GR>

  typename enable_if<UndirectedTagIndicator<GR>, bool>::type

  undirected(const GR&) {

    return true;

  }

  template <typename GR>

  /// \brief Implementation of the Cost Scaling algorithm for

  /// finding a \ref min_cost_flow "minimum cost flow".

  ///

  /// \ref CostScaling implements a cost scaling algorithm that performs

  /// push/augment and relabel operations for finding a \ref min_cost_flow

  /// "minimum cost flow" \ref amo93networkflows, \ref goldberg90approximation,

  /// \ref goldberg97efficient, \ref bunnagel98efficient.

  /// It is a highly efficient primal-dual solution method, which

  /// can be viewed as the generalization of the \ref Preflow

  /// "preflow push-relabel" algorithm for the maximum flow problem.

  ///

  /// Most of the parameters of the problem (except for the digraph)

  /// can be given using separate functions, and the algorithm can be

  /// executed using the \ref run() function. If some parameters are not

  /// specified, then default values will be used.

  ///

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

  /// \tparam V The number type used for flow amounts, capacity bounds

  /// and supply values in the algorithm. By default, it is \c int.

  /// \tparam C The number type used for costs and potentials in the

  /// algorithm. By default, it is the same as \c V.

  /// \tparam TR The traits class that defines various types used by the

  /// algorithm. By default, it is \ref CostScalingDefaultTraits

  /// "CostScalingDefaultTraits<GR, V, C>".

  /// In most cases, this parameter should not be set directly,

  /// consider to use the named template parameters instead.

  ///

  /// \warning Both \c V and \c C must be signed number types.

  /// \warning All input data (capacities, supply values, and costs) must

  /// be integer.

  ///

  /// \note %CostScaling provides three different internal methods,

  /// from which the most efficient one is used by default.

  /// For more information, see \ref Method.

#ifdef DOXYGEN

  template <typename GR, typename V, typename C, typename TR>

#else

  template < typename GR, typename V = int, typename C = V,

             typename TR = CostScalingDefaultTraits<GR, V, C> >

#endif

  class CostScaling

  {

      UNBOUNDED

    };

    /// \brief Constants for selecting the internal method.

    ///

    /// Enum type containing constants for selecting the internal method

    /// for the \ref run() function.

    ///

    /// \ref CostScaling provides three internal methods that differ mainly

    /// in their base operations, which are used in conjunction with the

    /// relabel operation.

    /// By default, the so called \ref PARTIAL_AUGMENT

    /// the most efficient and the most robust on various test inputs.

    /// However, the other methods can be selected using the \ref run()

    /// function with the proper parameter.

    enum Method {

      /// Local push operations are used, i.e. flow is moved only on one

      /// admissible arc at once.

      PUSH,

      /// Augment operations are used, i.e. flow is moved on admissible

      /// paths from a node with excess to a node with deficit.

      AUGMENT,

      /// Partial augment operations are used, i.e. flow is moved on

      /// admissible paths started from a node with excess, but the

      }

      return *this;

    }

    /// \brief Set single source and target nodes and a supply value.

    ///

    /// This function sets a single source node and a single target node

    /// and the required flow value.

    /// If neither this function nor \ref supplyMap() is used before

    /// calling \ref run(), the supply of each node will be set to zero.

    ///

    /// Using this function has the same effect as using \ref supplyMap()

    /// assigned to \c t and all other nodes have zero supply value.

    ///

    /// \param s The source node.

    /// \param t The target node.

    /// \param k The required amount of flow from node \c s to node \c t

    /// (i.e. the supply of \c s and the demand of \c t).

    ///

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

    CostScaling& stSupply(const Node& s, const Node& t, Value k) {

      for (int i = 0; i != _res_node_num; ++i) {

        _supply[i] = 0;

      }

  /// executed using the \ref run() function. If some parameters are not

  /// specified, then default values will be used.

  ///

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

  /// \tparam V The number type used for flow amounts, capacity bounds

  /// and supply values in the algorithm. By default, it is \c int.

  /// \tparam C The number type used for costs and potentials in the

  /// algorithm. By default, it is the same as \c V.

  ///

  /// \warning Both \c V and \c C must be signed number types.

  /// \warning All input data (capacities, supply values, and costs) must

  /// be integer.

  ///

  /// \note For more information about the three available methods,

  /// see \ref Method.

#ifdef DOXYGEN

  template <typename GR, typename V, typename C>

#else

  template <typename GR, typename V = int, typename C = V>

#endif

  class CycleCanceling

  {

  public:

      /// over the feasible flows, but this algroithm cannot handle

      /// these cases.

      UNBOUNDED

    };

    /// \brief Constants for selecting the used method.

    ///

    /// Enum type containing constants for selecting the used method

    /// for the \ref run() function.

    ///

    /// \ref CycleCanceling provides three different cycle-canceling

    /// methods. By default, \ref CANCEL_AND_TIGHTEN "Cancel and Tighten"

    /// However, the other methods can be selected using the \ref run()

    /// function with the proper parameter.

    enum Method {

      /// A simple cycle-canceling method, which uses the

      /// \ref BellmanFord "Bellman-Ford" algorithm with limited iteration

      /// number for detecting negative cycles in the residual network.

      SIMPLE_CYCLE_CANCELING,

      /// The "Minimum Mean Cycle-Canceling" algorithm, which is a

      /// well-known strongly polynomial method

      /// \ref goldberg89cyclecanceling. It improves along a

      /// \ref min_mean_cycle "minimum mean cycle" in each iteration.

      /// Its running time complexity is O(n<sup>2</sup>m<sup>3</sup>log(n)).

      }

      return *this;

    }

    /// \brief Set single source and target nodes and a supply value.

    ///

    /// This function sets a single source node and a single target node

    /// and the required flow value.

    /// If neither this function nor \ref supplyMap() is used before

    /// calling \ref run(), the supply of each node will be set to zero.

    ///

    /// Using this function has the same effect as using \ref supplyMap()

    /// assigned to \c t and all other nodes have zero supply value.

    ///

    /// \param s The source node.

    /// \param t The target node.

    /// \param k The required amount of flow from node \c s to node \c t

    /// (i.e. the supply of \c s and the demand of \c t).

    ///

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

    CycleCanceling& stSupply(const Node& s, const Node& t, Value k) {

      for (int i = 0; i != _res_node_num; ++i) {

        _supply[i] = 0;

      }

/// \ingroup graph_properties

/// \file

/// \brief Euler tour iterators and a function for checking the \e Eulerian

/// property.

///

///This file provides Euler tour iterators and a function to check

///if a (di)graph is \e Eulerian.

namespace lemon {

  ///Euler tour iterator for digraphs.

  ///This iterator provides an Euler tour (Eulerian circuit) of a \e directed

  ///graph (if there exists) and it converts to the \c Arc type of the digraph.

  ///

  ///For example, if the given digraph has an Euler tour (i.e it has only one

  ///non-trivial component and the in-degree is equal to the out-degree

  ///for all nodes), then the following code will put the arcs of \c g

  ///to the vector \c et according to an Euler tour of \c g.

  ///\code

  ///  std::vector<ListDigraph::Arc> et;

  ///  for(DiEulerIt<ListDigraph> e(g); e!=INVALID; ++e)

  ///    et.push_back(e);

  ///\endcode

  /// \brief Implementation of the iterated local search algorithm of Grosso,

  /// Locatelli, and Pullan for the maximum clique problem

  ///

  /// \ref GrossoLocatelliPullanMc implements the iterated local search

  /// algorithm of Grosso, Locatelli, and Pullan for solving the \e maximum

  /// \e clique \e problem \ref grosso08maxclique.

  /// It is to find the largest complete subgraph (\e clique) in an

  /// undirected graph, i.e., the largest set of nodes where each

  /// pair of nodes is connected.

  ///

  /// This class provides a simple but highly efficient and robust heuristic

  /// largest one.

  ///

  /// \tparam GR The undirected graph type the algorithm runs on.

  ///

  /// \note %GrossoLocatelliPullanMc provides three different node selection

  /// rules, from which the most powerful one is used by default.

  /// For more information, see \ref SelectionRule.

  template <typename GR>

  class GrossoLocatelliPullanMc

  {

  public:

    /// \brief Constants for specifying the node selection rule.

      /// A node is selected randomly without any evaluation at each step.

      RANDOM,

      /// A node of maximum degree is selected randomly at each step.

      DEGREE_BASED,

      /// A node of minimum penalty is selected randomly at each step.

      /// The node penalties are updated adaptively after each stage of the

      /// search process.

      PENALTY_BASED

    };

  private:

    TEMPLATE_GRAPH_TYPEDEFS(GR);

    typedef std::vector<int> IntVector;

    typedef std::vector<char> BoolVector;

    typedef std::vector<BoolVector> BoolMatrix;

    // Note: vector<char> is used instead of vector<bool> for efficiency reasons

    const GR &_graph;

    IntNodeMap _id;

    // Internal matrix representation of the graph

    BoolMatrix _gr;

    int _n;

    // The current clique

    BoolVector _clique;

    int _size;

    // The best clique found so far

    BoolVector _best_clique;

    int _best_size;

    // The "distances" of the nodes from the current clique.

    // _delta[u] is the number of nodes in the clique that are

    // not connected with u.

  public:

    /// \brief Constructor.

    ///

    /// Constructor.

    /// The global \ref rnd "random number generator instance" is used

    /// during the algorithm.

    ///

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

    GrossoLocatelliPullanMc(const GR& graph) :

      _graph(graph), _id(_graph), _rnd(rnd)

    /// \brief Constructor with random seed.

    ///

    /// Constructor with random seed.

    ///

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

    /// \param seed Seed value for the internal random number generator

    /// that is used during the algorithm.

    GrossoLocatelliPullanMc(const GR& graph, int seed) :

      _graph(graph), _id(_graph), _rnd(seed)

    /// \brief Constructor with random number generator.

    ///

    /// Constructor with random number generator.

    ///

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

    /// \param random A random number generator that is used during the

    /// algorithm.

    GrossoLocatelliPullanMc(const GR& graph, const Random& random) :

      _graph(graph), _id(_graph), _rnd(random)

    /// \name Execution Control

    /// @{

    /// \brief Runs the algorithm.

    ///

    ///

    /// \param rule The node selection rule. For more information, see

    /// \ref SelectionRule.

    ///

    {

      init();

      switch (rule) {

        case RANDOM:

        case DEGREE_BASED:

      }

    }

    /// @}

    /// \name Query Functions

    /// @{

    /// \brief The size of the found clique

    ///

    /// This function returns the size of the found clique.

    ///

    /// \pre run() must be called before using this function.

    int cliqueSize() const {

      return _best_size;

    }

    /// \brief Gives back the found clique in a \c bool node map

      /// \c CliqueNodeIt as one may expect.

      typename GR::Node operator++(int) {

        Node n=*this;

        ++(*this);

        return n;

      }

    };

    /// @}

  private:

    // Adds a node to the current clique

    void addCliqueNode(int u) {

      if (_clique[u]) return;

      _clique[u] = true;

      _size++;

      BoolVector &row = _gr[u];

      for (int i = 0; i != _n; i++) {

        if (!row[i]) _delta[i]++;

      }

    }

      _size = 0;

      _best_clique.clear();

      _best_clique.resize(_n, false);

      _best_size = 0;

      _delta.clear();

      _delta.resize(_n, 0);

      _tabu.clear();

      _tabu.resize(_n, false);

    }

    // Executes the algorithm

    template <typename SelectionRuleImpl>

      if (_n == 1) {

        _best_clique[0] = true;

        _best_size = 1;

      }

      SelectionRuleImpl sel_method(*this);

      IntVector restart_nodes;

        // Perturbation/restart

          restart_nodes.clear();

          for (int i = 0; i != _n; i++) {

              restart_nodes.push_back(i);

          }

        }

        int rs_node = -1;

        if (restart_nodes.size() > 0) {

          rs_node = restart_nodes[_rnd[restart_nodes.size()]];

        } else {

          rs_node = _rnd[_n];

        }

        BoolVector &row = _gr[rs_node];

        for (int i = 0; i != _n; i++) {

          if (_clique[i] && !row[i]) delCliqueNode(i);

            tabu_empty = false;

            if (--max_swap <= 0) break;

          }

          else if ((u = sel_method.nextAddNode()) != -1) {

            // Non-feasible add move

            addCliqueNode(u);

          }

          else break;

        }

        if (_size > _best_size) {

          _best_clique = _clique;

          _best_size = _size;

        }

        sel_method.update();

      }

    }

  }; //class GrossoLocatelliPullanMc

  ///@}

} //namespace lemon

#endif //LEMON_GROSSO_LOCATELLI_PULLAN_MC_H

  /// \brief Implementation of the primal Network Simplex algorithm

  /// for finding a \ref min_cost_flow "minimum cost flow".

  ///

  /// \ref NetworkSimplex implements the primal Network Simplex algorithm

  /// for finding a \ref min_cost_flow "minimum cost flow"

  /// \ref amo93networkflows, \ref dantzig63linearprog,

  /// \ref kellyoneill91netsimplex.

  /// This algorithm is a highly efficient specialized version of the

  /// linear programming simplex method directly for the minimum cost

  /// flow problem.

  ///

  ///

  /// Most of the parameters of the problem (except for the digraph)

  /// can be given using separate functions, and the algorithm can be

  /// executed using the \ref run() function. If some parameters are not

  /// specified, then default values will be used.

  ///

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

  /// \tparam V The number type used for flow amounts, capacity bounds

  /// and supply values in the algorithm. By default, it is \c int.

  /// \tparam C The number type used for costs and potentials in the

  /// algorithm. By default, it is the same as \c V.

  ///

      LEQ

    };

    /// \brief Constants for selecting the pivot rule.

    ///

    /// Enum type containing constants for selecting the pivot rule for

    /// the \ref run() function.

    ///

    /// \ref NetworkSimplex provides five different pivot rule

    /// implementations that significantly affect the running time

    /// of the algorithm.

    /// By default, \ref BLOCK_SEARCH "Block Search" is used, which

    /// test inputs.

    /// However, another pivot rule can be selected using the \ref run()

    /// function with the proper parameter.

    enum PivotRule {

      /// The \e First \e Eligible pivot rule.

      /// The next eligible arc is selected in a wraparound fashion

      /// in every iteration.

      FIRST_ELIGIBLE,

      /// The \e Best \e Eligible pivot rule.

      /// The best eligible arc is selected in every iteration.

      /// candidate list and extends this list in every iteration.

      ALTERING_LIST

    };

  private:

    TEMPLATE_DIGRAPH_TYPEDEFS(GR);

    typedef std::vector<int> IntVector;

    typedef std::vector<Value> ValueVector;

    typedef std::vector<Cost> CostVector;

    typedef std::vector<signed char> CharVector;

    // vector<ArcDirection> for efficiency reasons

    // State constants for arcs

    enum ArcState {

      STATE_UPPER = -1,

      STATE_TREE  =  0,

      STATE_LOWER =  1

    };

    // Direction constants for tree arcs

    enum ArcDirection {

      DIR_DOWN = -1,

    /// \brief Set the supply values of the nodes.

    ///

    /// This function sets the supply values of the nodes.

    /// If neither this function nor \ref stSupply() is used before

    /// calling \ref run(), the supply of each node will be set to zero.

    ///

    /// \param map A node map storing the supply values.

    /// Its \c Value type must be convertible to the \c Value type

    /// of the algorithm.

    ///

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

    template<typename SupplyMap>

    NetworkSimplex& supplyMap(const SupplyMap& map) {

      for (NodeIt n(_graph); n != INVALID; ++n) {

        _supply[_node_id[n]] = map[n];

      }

      return *this;

    }

    /// \brief Set single source and target nodes and a supply value.

    ///

    /// This function sets a single source node and a single target node

    /// and the required flow value.

    /// If neither this function nor \ref supplyMap() is used before

    /// calling \ref run(), the supply of each node will be set to zero.

    ///

    /// Using this function has the same effect as using \ref supplyMap()

    /// assigned to \c t and all other nodes have zero supply value.

    ///

    /// \param s The source node.

    /// \param t The target node.

    /// \param k The required amount of flow from node \c s to node \c t

    /// (i.e. the supply of \c s and the demand of \c t).

    ///

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

    NetworkSimplex& stSupply(const Node& s, const Node& t, Value k) {

      for (int i = 0; i != _node_num; ++i) {

        _supply[i] = 0;

      }

namespace lemon {

  /// \addtogroup paths

  /// @{

  /// \brief A structure for representing directed paths in a digraph.

  ///

  /// A structure for representing directed path in a digraph.

  /// \tparam GR The digraph type in which the path is.

  ///

  /// In a sense, the path can be treated as a list of arcs. The

  /// cannot enumerate the nodes of the path and the source node of

  /// a zero length path is undefined.

  ///

  /// This implementation is a back and front insertable and erasable

  /// path type. It can be indexed in O(1) time. The front and back

  /// insertion and erase is done in O(1) (amortized) time. The

  /// implementation uses two vectors for storing the front and back

  /// insertions.

  template <typename GR>

  class Path {

  public:

      const Path *path;

      int idx;

    };

    /// \brief Length of the path.

    int length() const { return head.size() + tail.size(); }

    /// \brief Return whether the path is empty.

    bool empty() const { return head.empty() && tail.empty(); }

    /// \brief Reset the path to an empty one.

    void clear() { head.clear(); tail.clear(); }

    ///

    /// \pre \c n is in the <tt>[0..length() - 1]</tt> range.

    const Arc& nth(int n) const {

      return n < int(head.size()) ? *(head.rbegin() + n) :

        *(tail.begin() + (n - head.size()));

    }

    ///

    /// \pre \c n is in the <tt>[0..length() - 1]</tt> range.

    ArcIt nthIt(int n) const {

      return ArcIt(*this, n);

    }

    /// \brief The first arc of the path

    const Arc& front() const {

      return head.empty() ? tail.front() : head.back();

    }

    /// \brief Add a new arc before the current path

  protected:

    typedef std::vector<Arc> Container;

    Container head, tail;

  };

  /// \brief A structure for representing directed paths in a digraph.

  ///

  /// A structure for representing directed path in a digraph.