RhodeCode

 - \ref Suurballe A successive shortest path algorithm for finding

   arc-disjoint paths between two nodes having minimum total length.

*/

/**

@defgroup max_flow Maximum Flow Algorithms

@ingroup algs

\brief Algorithms for finding maximum flows.

This group contains the algorithms for finding maximum flows and

feasible circulations.

The \e maximum \e flow \e problem is to find a flow of maximum value between

a single source and a single target. Formally, there is a \f$G=(V,A)\f$

digraph, a \f$cap: A\rightarrow\mathbf{R}^+_0\f$ capacity function and

\f$s, t \in V\f$ source and target nodes.

A maximum flow is an \f$f: A\rightarrow\mathbf{R}^+_0\f$ solution of the

following optimization problem.

\f[ \max\sum_{sv\in A} f(sv) - \sum_{vs\in A} f(vs) \f]

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

    \quad \forall u\in V\setminus\{s,t\} \f]

\f[ 0 \leq f(uv) \leq cap(uv) \quad \forall uv\in A \f]

LEMON contains several algorithms for solving maximum flow problems:

- \ref EdmondsKarp Edmonds-Karp algorithm.

- \ref Preflow Goldberg-Tarjan's preflow push-relabel algorithm.

- \ref DinitzSleatorTarjan Dinitz's blocking flow algorithm with dynamic trees.

- \ref GoldbergTarjan Preflow push-relabel algorithm with dynamic trees.

In most cases the \ref Preflow "Preflow" algorithm provides the

fastest method for computing a maximum flow. All implementations

*/

/**

@defgroup min_cost_flow Minimum Cost Flow Algorithms

@ingroup algs

\brief Algorithms for finding minimum cost flows and circulations.

This group contains the algorithms for finding minimum cost flows and

circulations.

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{Z}\f$,

\f$upper: A\rightarrow\mathbf{Z}\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{Z}\f$ denotes the cost per unit flow

on the arcs and \f$sup: V\rightarrow\mathbf{Z}\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{Z}\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]

graphs.  The matching problems in bipartite graphs are generally

easier than in general graphs. The goal of the matching optimization

can be finding maximum cardinality, maximum weight or minimum cost

matching. The search can be constrained to find perfect or

maximum cardinality matching.

The matching algorithms implemented in LEMON:

- \ref MaxBipartiteMatching Hopcroft-Karp augmenting path algorithm

  for calculating maximum cardinality matching in bipartite graphs.

- \ref PrBipartiteMatching Push-relabel algorithm

  for calculating maximum cardinality matching in bipartite graphs.

- \ref MaxWeightedBipartiteMatching

  Successive shortest path algorithm for calculating maximum weighted

  matching and maximum weighted bipartite matching in bipartite graphs.

- \ref MinCostMaxBipartiteMatching

  Successive shortest path algorithm for calculating minimum cost maximum

  matching in bipartite graphs.

- \ref MaxMatching Edmond's blossom shrinking algorithm for calculating

  maximum cardinality matching in general graphs.

- \ref MaxWeightedMatching Edmond's blossom shrinking algorithm for calculating

  maximum weighted matching in general graphs.

- \ref MaxWeightedPerfectMatching

  Edmond's blossom shrinking algorithm for calculating maximum weighted

  perfect matching in general graphs.

\image html bipartite_matching.png

\image latex bipartite_matching.eps "Bipartite Matching" width=\textwidth

*/

/**

@defgroup spantree Minimum Spanning Tree Algorithms

@ingroup algs

*/

/**

@defgroup auxalg Auxiliary Algorithms

@ingroup algs

\brief Auxiliary algorithms implemented in LEMON.

This group contains some algorithms implemented in LEMON

in order to make it easier to implement complex algorithms.

*/

/**

@defgroup approx Approximation Algorithms

@ingroup algs

\brief Approximation algorithms.

This group contains the approximation and heuristic algorithms

implemented in LEMON.

*/

/**

@defgroup gen_opt_group General Optimization Tools

\brief This group contains some general optimization frameworks

implemented in LEMON.

This group contains some general optimization frameworks

implemented in LEMON.

*/

/**

@defgroup lp_group Lp and Mip Solvers

@ingroup gen_opt_group

 *

 * 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.

 *

 */

/**

\mainpage LEMON Documentation

\section intro Introduction

\subsection whatis What is LEMON

LEMON stands for

<b>L</b>ibrary of <b>E</b>fficient <b>M</b>odels

and <b>O</b>ptimization in <b>N</b>etworks.

It is a C++ template

library aimed at combinatorial optimization tasks which

often involve in working

with graphs.

<b>

LEMON is an <a class="el" href="http://opensource.org/">open&nbsp;source</a>

project.

You are free to use it in your commercial or

non-commercial applications under very permissive

\ref license "license terms".

</b>

\subsection howtoread How to read the documentation

<a class="el" href="http://lemon.cs.elte.hu/pub/tutorial/">LEMON Tutorial</a>.

<a class="el" href="modules.html">Modules</a> section.

If you are a user of the old (0.x) series of LEMON, please check out the

\ref migration "Migration Guide" for the backward incompatibilities.

*/

    /// map. This map should have the property that there are no two incident

    /// edges with \c true value, i.e. it really contains a matching.

    /// \return \c true if the map contains a matching.

    template <typename MatchingMap>

    bool matchingInit(const MatchingMap& matching) {

      createStructures();

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

        (*_matching)[n] = INVALID;

        (*_status)[n] = UNMATCHED;

      }

      for(EdgeIt e(_graph); e!=INVALID; ++e) {

        if (matching[e]) {

          Node u = _graph.u(e);

          if ((*_matching)[u] != INVALID) return false;

          (*_matching)[u] = _graph.direct(e, true);

          (*_status)[u] = MATCHED;

          Node v = _graph.v(e);

          if ((*_matching)[v] != INVALID) return false;

          (*_matching)[v] = _graph.direct(e, false);

          (*_status)[v] = MATCHED;

        }

      }

      return true;

    }

    /// \brief Start Edmonds' algorithm

    ///

    /// This function runs the original Edmonds' algorithm.

    ///

    /// called before using this function.

    void startSparse() {

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

        if ((*_status)[n] == UNMATCHED) {

          (*_blossom_rep)[_blossom_set->insert(n)] = n;

          _tree_set->insert(n);

          (*_status)[n] = EVEN;

          processSparse(n);

        }

      }

    }

    /// \brief Start Edmonds' algorithm with a heuristic improvement 

    /// for dense graphs

    ///

    /// This function runs Edmonds' algorithm with a heuristic of postponing

    /// shrinks, therefore resulting in a faster algorithm for dense graphs.

    ///

    /// called before using this function.

    void startDense() {

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

        if ((*_status)[n] == UNMATCHED) {

          (*_blossom_rep)[_blossom_set->insert(n)] = n;

          _tree_set->insert(n);

          (*_status)[n] = EVEN;

          processDense(n);

        }

      }

    }

    /// \brief Run Edmonds' algorithm

    ///

    /// This function runs Edmonds' algorithm. An additional heuristic of 

    /// postponing shrinks is used for relatively dense graphs 

    /// (for which <tt>m>=2*n</tt> holds).

    void run() {

      if (countEdges(_graph) < 2 * countNodes(_graph)) {

        greedyInit();

        startSparse();

      } else {

        init();

        startDense();

      }

    }

    /// @}

    /// \name Primal Solution

    /// Functions to get the primal solution, i.e. the maximum matching.