[Lemon-commits] Peter Kovacs: Many doc improvements for Circulat...
Lemon HG
hg at lemon.cs.elte.hu
Mon Dec 1 15:32:25 CET 2008
details: http://lemon.cs.elte.hu/hg/lemon/rev/235be9d4b6ab
changeset: 417:235be9d4b6ab
user: Peter Kovacs <kpeter [at] inf.elte.hu>
date: Sun Nov 30 14:51:05 2008 +0100
description:
Many doc improvements for Circulation (#175)
- More precise doc for members.
- Several doc fixes.
- Add doc for public types.
- Better formulations.
- Add useful notes to the problem description.
- Use supply instead of excess in the doc.
- Hide the doc of the traits class parameter.
- Use \tparam for template parameters.
diffstat:
1 file changed, 230 insertions(+), 131 deletions(-)
lemon/circulation.h | 361 ++++++++++++++++++++++++++++++++-------------------
diffs (truncated from 613 to 300 lines):
diff -r 26fd85a3087e -r 235be9d4b6ab lemon/circulation.h
--- a/lemon/circulation.h Mon Dec 01 14:07:58 2008 +0000
+++ b/lemon/circulation.h Sun Nov 30 14:51:05 2008 +0100
@@ -19,28 +19,28 @@
#ifndef LEMON_CIRCULATION_H
#define LEMON_CIRCULATION_H
-#include <iostream>
-#include <queue>
#include <lemon/tolerance.h>
#include <lemon/elevator.h>
///\ingroup max_flow
///\file
-///\brief Push-prelabel algorithm for finding a feasible circulation.
+///\brief Push-relabel algorithm for finding a feasible circulation.
///
namespace lemon {
/// \brief Default traits class of Circulation class.
///
/// Default traits class of Circulation class.
- /// \param _Graph Digraph type.
- /// \param _CapacityMap Type of capacity map.
- template <typename _Graph, typename _LCapMap,
+ /// \tparam _Diraph Digraph type.
+ /// \tparam _LCapMap Lower bound capacity map type.
+ /// \tparam _UCapMap Upper bound capacity map type.
+ /// \tparam _DeltaMap Delta map type.
+ template <typename _Diraph, typename _LCapMap,
typename _UCapMap, typename _DeltaMap>
struct CirculationDefaultTraits {
- /// \brief The digraph type the algorithm runs on.
- typedef _Graph Digraph;
+ /// \brief The type of the digraph the algorithm runs on.
+ typedef _Diraph Digraph;
/// \brief The type of the map that stores the circulation lower
/// bound.
@@ -56,20 +56,20 @@
/// It must meet the \ref concepts::ReadMap "ReadMap" concept.
typedef _UCapMap UCapMap;
- /// \brief The type of the map that stores the upper bound of
- /// node excess.
+ /// \brief The type of the map that stores the lower bound for
+ /// the supply of the nodes.
///
- /// The type of the map that stores the lower bound of node
- /// excess. It must meet the \ref concepts::ReadMap "ReadMap"
+ /// The type of the map that stores the lower bound for the supply
+ /// of the nodes. It must meet the \ref concepts::ReadMap "ReadMap"
/// concept.
typedef _DeltaMap DeltaMap;
- /// \brief The type of the length of the arcs.
+ /// \brief The type of the flow values.
typedef typename DeltaMap::Value Value;
- /// \brief The map type that stores the flow values.
+ /// \brief The type of the map that stores the flow values.
///
- /// The map type that stores the flow values.
+ /// The type of the map that stores the flow values.
/// It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
typedef typename Digraph::template ArcMap<Value> FlowMap;
@@ -82,9 +82,9 @@
return new FlowMap(digraph);
}
- /// \brief The eleavator type used by Circulation algorithm.
+ /// \brief The elevator type used by the algorithm.
///
- /// The elevator type used by Circulation algorithm.
+ /// The elevator type used by the algorithm.
///
/// \sa Elevator
/// \sa LinkedElevator
@@ -92,7 +92,7 @@
/// \brief Instantiates an Elevator.
///
- /// This function instantiates a \ref Elevator.
+ /// This function instantiates an \ref Elevator.
/// \param digraph The digraph, to which we would like to define
/// the elevator.
/// \param max_level The maximum level of the elevator.
@@ -107,40 +107,88 @@
};
- ///Push-relabel algorithm for the Network Circulation Problem.
+ /**
+ \brief Push-relabel algorithm for the network circulation problem.
- /**
\ingroup max_flow
- This class implements a push-relabel algorithm
- or the Network Circulation Problem.
+ This class implements a push-relabel algorithm for the network
+ circulation problem.
+ It is to find a feasible circulation when lower and upper bounds
+ are given for the flow values on the arcs and lower bounds
+ are given for the supply values of the nodes.
+
The exact formulation of this problem is the following.
- \f[\sum_{e\in\rho(v)}x(e)-\sum_{e\in\delta(v)}x(e)\leq
- -delta(v)\quad \forall v\in V \f]
- \f[ lo(e)\leq x(e) \leq up(e) \quad \forall e\in E \f]
+ Let \f$G=(V,A)\f$ be a digraph,
+ \f$lower, upper: A\rightarrow\mathbf{R}^+_0\f$,
+ \f$delta: V\rightarrow\mathbf{R}\f$. Find a feasible circulation
+ \f$f: A\rightarrow\mathbf{R}^+_0\f$ so that
+ \f[ \sum_{a\in\delta_{out}(v)} f(a) - \sum_{a\in\delta_{in}(v)} f(a)
+ \geq delta(v) \quad \forall v\in V, \f]
+ \f[ lower(a)\leq f(a) \leq upper(a) \quad \forall a\in A. \f]
+ \note \f$delta(v)\f$ specifies a lower bound for the supply of node
+ \f$v\f$. It can be either positive or negative, however note that
+ \f$\sum_{v\in V}delta(v)\f$ should be zero or negative in order to
+ have a feasible solution.
+
+ \note A special case of this problem is when
+ \f$\sum_{v\in V}delta(v) = 0\f$. Then the supply of each node \f$v\f$
+ will be \e equal \e to \f$delta(v)\f$, if a circulation can be found.
+ Thus a feasible solution for the
+ \ref min_cost_flow "minimum cost flow" problem can be calculated
+ in this way.
+
+ \tparam _Digraph The type of the digraph the algorithm runs on.
+ \tparam _LCapMap The type of the lower bound capacity map. The default
+ map type is \ref concepts::Digraph::ArcMap "_Digraph::ArcMap<int>".
+ \tparam _UCapMap The type of the upper bound capacity map. The default
+ map type is \c _LCapMap.
+ \tparam _DeltaMap The type of the map that stores the lower bound
+ for the supply of the nodes. The default map type is
+ \c _Digraph::ArcMap<_UCapMap::Value>.
*/
- template<class _Graph,
- class _LCapMap=typename _Graph::template ArcMap<int>,
- class _UCapMap=_LCapMap,
- class _DeltaMap=typename _Graph::template NodeMap<
- typename _UCapMap::Value>,
- class _Traits=CirculationDefaultTraits<_Graph, _LCapMap,
- _UCapMap, _DeltaMap> >
+#ifdef DOXYGEN
+template< typename _Digraph,
+ typename _LCapMap,
+ typename _UCapMap,
+ typename _DeltaMap,
+ typename _Traits >
+#else
+template< typename _Digraph,
+ typename _LCapMap = typename _Digraph::template ArcMap<int>,
+ typename _UCapMap = _LCapMap,
+ typename _DeltaMap = typename _Digraph::
+ template NodeMap<typename _UCapMap::Value>,
+ typename _Traits=CirculationDefaultTraits<_Digraph, _LCapMap,
+ _UCapMap, _DeltaMap> >
+#endif
class Circulation {
+ public:
+ ///The \ref CirculationDefaultTraits "traits class" of the algorithm.
typedef _Traits Traits;
+ ///The type of the digraph the algorithm runs on.
typedef typename Traits::Digraph Digraph;
- TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
-
+ ///The type of the flow values.
typedef typename Traits::Value Value;
+ /// The type of the lower bound capacity map.
typedef typename Traits::LCapMap LCapMap;
+ /// The type of the upper bound capacity map.
typedef typename Traits::UCapMap UCapMap;
+ /// \brief The type of the map that stores the lower bound for
+ /// the supply of the nodes.
typedef typename Traits::DeltaMap DeltaMap;
+ ///The type of the flow map.
typedef typename Traits::FlowMap FlowMap;
+
+ ///The type of the elevator.
typedef typename Traits::Elevator Elevator;
+ ///The type of the tolerance.
typedef typename Traits::Tolerance Tolerance;
- typedef typename Digraph::template NodeMap<Value> ExcessMap;
+ private:
+
+ TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
const Digraph &_g;
int _node_num;
@@ -155,6 +203,7 @@
Elevator* _level;
bool _local_level;
+ typedef typename Digraph::template NodeMap<Value> ExcessMap;
ExcessMap* _excess;
Tolerance _tol;
@@ -164,7 +213,7 @@
typedef Circulation Create;
- ///\name Named template parameters
+ ///\name Named Template Parameters
///@{
@@ -181,7 +230,7 @@
/// FlowMap type
///
/// \ref named-templ-param "Named parameter" for setting FlowMap
- /// type
+ /// type.
template <typename _FlowMap>
struct SetFlowMap
: public Circulation<Digraph, LCapMap, UCapMap, DeltaMap,
@@ -203,7 +252,11 @@
/// Elevator type
///
/// \ref named-templ-param "Named parameter" for setting Elevator
- /// type
+ /// 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 _Elevator>
struct SetElevator
: public Circulation<Digraph, LCapMap, UCapMap, DeltaMap,
@@ -221,11 +274,17 @@
};
/// \brief \ref named-templ-param "Named parameter" for setting
- /// Elevator type
+ /// Elevator type with automatic allocation
///
/// \ref named-templ-param "Named parameter" for setting Elevator
- /// type. The Elevator should be standard constructor interface, ie.
- /// the digraph and the maximum level should be passed to it.
+ /// 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).
+ /// However an external elevator object could also be passed to the
+ /// algorithm with the \ref elevator(Elevator&) "elevator()" function
+ /// before calling \ref run() or \ref init().
+ /// \sa SetElevator
template <typename _Elevator>
struct SetStandardElevator
: public Circulation<Digraph, LCapMap, UCapMap, DeltaMap,
@@ -248,17 +307,18 @@
/// \param g The digraph the algorithm runs on.
/// \param lo The lower bound capacity of the arcs.
/// \param up The upper bound capacity of the arcs.
- /// \param delta The lower bound on node excess.
+ /// \param delta The lower bound for the supply of the nodes.
Circulation(const Digraph &g,const LCapMap &lo,
const UCapMap &up,const DeltaMap &delta)
: _g(g), _node_num(),
_lo(&lo),_up(&up),_delta(&delta),_flow(0),_local_flow(false),
_level(0), _local_level(false), _excess(0), _el() {}
- /// Destrcutor.
+ /// Destructor.
~Circulation() {
destroyStructures();
}
+
private:
@@ -295,7 +355,7 @@
/// Sets the lower bound capacity map.
/// Sets the lower bound capacity map.
- /// \return \c (*this)
+ /// \return <tt>(*this)</tt>
Circulation& lowerCapMap(const LCapMap& map) {
_lo = ↦
return *this;
@@ -304,25 +364,29 @@
/// Sets the upper bound capacity map.
/// Sets the upper bound capacity map.
- /// \return \c (*this)
+ /// \return <tt>(*this)</tt>
Circulation& upperCapMap(const LCapMap& map) {
_up = ↦
return *this;
}
- /// Sets the lower bound map on excess.
+ /// Sets the lower bound map for the supply of the nodes.
- /// Sets the lower bound map on excess.
More information about the Lemon-commits
mailing list