[Lemon-commits] Peter Kovacs: Many doc improvements for Preflow ...
Lemon HG
hg at lemon.cs.elte.hu
Sun Nov 30 10:51:21 CET 2008
details: http://lemon.cs.elte.hu/hg/lemon/rev/37054b67d807
changeset: 408:37054b67d807
user: Peter Kovacs <kpeter [at] inf.elte.hu>
date: Sun Nov 30 00:50:31 2008 +0100
description:
Many doc improvements for Preflow (#176)
- More precise doc for members.
- Add doc for public types.
- Hide the doc of the traits class parameter.
- Removing \author comments.
- Use \tparam for template parameters.
diffstat:
1 file changed, 156 insertions(+), 109 deletions(-)
lemon/preflow.h | 265 ++++++++++++++++++++++++++++++++-----------------------
diffs (truncated from 480 to 300 lines):
diff -r db3251947eba -r 37054b67d807 lemon/preflow.h
--- a/lemon/preflow.h Sun Nov 30 00:48:07 2008 +0100
+++ b/lemon/preflow.h Sun Nov 30 00:50:31 2008 +0100
@@ -31,13 +31,13 @@
/// \brief Default traits class of Preflow class.
///
/// Default traits class of Preflow class.
- /// \param _Graph Digraph type.
- /// \param _CapacityMap Type of capacity map.
- template <typename _Graph, typename _CapacityMap>
+ /// \tparam _Digraph Digraph type.
+ /// \tparam _CapacityMap Capacity map type.
+ template <typename _Digraph, typename _CapacityMap>
struct PreflowDefaultTraits {
- /// \brief The digraph type the algorithm runs on.
- typedef _Graph Digraph;
+ /// \brief The type of the digraph the algorithm runs on.
+ typedef _Digraph Digraph;
/// \brief The type of the map that stores the arc capacities.
///
@@ -45,12 +45,12 @@
/// It must meet the \ref concepts::ReadMap "ReadMap" concept.
typedef _CapacityMap CapacityMap;
- /// \brief The type of the length of the arcs.
+ /// \brief The type of the flow values.
typedef typename CapacityMap::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;
@@ -63,7 +63,7 @@
return new FlowMap(digraph);
}
- /// \brief The eleavator type used by Preflow algorithm.
+ /// \brief The elevator type used by Preflow algorithm.
///
/// The elevator type used by Preflow algorithm.
///
@@ -73,7 +73,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.
@@ -91,44 +91,46 @@
/// \ingroup max_flow
///
- /// \brief %Preflow algorithms class.
+ /// \brief %Preflow algorithm class.
///
- /// This class provides an implementation of the Goldberg's \e
- /// preflow \e algorithm producing a flow of maximum value in a
- /// digraph. The preflow algorithms are the fastest known max
+ /// This class provides an implementation of Goldberg-Tarjan's \e preflow
+ /// \e push-relabel algorithm producing a flow of maximum value in a
+ /// digraph. The preflow algorithms are the fastest known maximum
/// flow algorithms. The current implementation use a mixture of the
/// \e "highest label" and the \e "bound decrease" heuristics.
/// The worst case time complexity of the algorithm is \f$O(n^2\sqrt{e})\f$.
///
- /// The algorithm consists from two phases. After the first phase
- /// the maximal flow value and the minimum cut can be obtained. The
- /// second phase constructs the feasible maximum flow on each arc.
+ /// The algorithm consists of two phases. After the first phase
+ /// the maximum flow value and the minimum cut is obtained. The
+ /// second phase constructs a feasible maximum flow on each arc.
///
- /// \param _Graph The digraph type the algorithm runs on.
- /// \param _CapacityMap The flow map type.
- /// \param _Traits Traits class to set various data types used by
- /// the algorithm. The default traits class is \ref
- /// PreflowDefaultTraits. See \ref PreflowDefaultTraits for the
- /// documentation of a %Preflow traits class.
- ///
- ///\author Jacint Szabo and Balazs Dezso
+ /// \tparam _Digraph The type of the digraph the algorithm runs on.
+ /// \tparam _CapacityMap The type of the capacity map. The default map
+ /// type is \ref concepts::Digraph::ArcMap "_Digraph::ArcMap<int>".
#ifdef DOXYGEN
- template <typename _Graph, typename _CapacityMap, typename _Traits>
+ template <typename _Digraph, typename _CapacityMap, typename _Traits>
#else
- template <typename _Graph,
- typename _CapacityMap = typename _Graph::template ArcMap<int>,
- typename _Traits = PreflowDefaultTraits<_Graph, _CapacityMap> >
+ template <typename _Digraph,
+ typename _CapacityMap = typename _Digraph::template ArcMap<int>,
+ typename _Traits = PreflowDefaultTraits<_Digraph, _CapacityMap> >
#endif
class Preflow {
public:
+ ///The \ref PreflowDefaultTraits "traits class" of the algorithm.
typedef _Traits Traits;
+ ///The type of the digraph the algorithm runs on.
typedef typename Traits::Digraph Digraph;
+ ///The type of the capacity map.
typedef typename Traits::CapacityMap CapacityMap;
+ ///The type of the flow values.
typedef typename Traits::Value Value;
+ ///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;
private:
@@ -188,7 +190,7 @@
typedef Preflow Create;
- ///\name Named template parameters
+ ///\name Named Template Parameters
///@{
@@ -205,7 +207,7 @@
/// FlowMap type
///
/// \ref named-templ-param "Named parameter" for setting FlowMap
- /// type
+ /// type.
template <typename _FlowMap>
struct SetFlowMap
: public Preflow<Digraph, CapacityMap, SetFlowMapTraits<_FlowMap> > {
@@ -226,7 +228,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 Preflow<Digraph, CapacityMap, SetElevatorTraits<_Elevator> > {
@@ -243,11 +249,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 Preflow<Digraph, CapacityMap,
@@ -273,14 +285,14 @@
/// \param source The source node.
/// \param target The target node.
Preflow(const Digraph& digraph, const CapacityMap& capacity,
- Node source, Node target)
+ Node source, Node target)
: _graph(digraph), _capacity(&capacity),
_node_num(0), _source(source), _target(target),
_flow(0), _local_flow(false),
_level(0), _local_level(false),
_excess(0), _tolerance(), _phase() {}
- /// \brief Destrcutor.
+ /// \brief Destructor.
///
/// Destructor.
~Preflow() {
@@ -290,7 +302,7 @@
/// \brief Sets the capacity map.
///
/// Sets the capacity map.
- /// \return \c (*this)
+ /// \return <tt>(*this)</tt>
Preflow& capacityMap(const CapacityMap& map) {
_capacity = ↦
return *this;
@@ -299,7 +311,11 @@
/// \brief Sets the flow map.
///
/// Sets the flow map.
- /// \return \c (*this)
+ /// 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>
Preflow& flowMap(FlowMap& map) {
if (_local_flow) {
delete _flow;
@@ -309,17 +325,32 @@
return *this;
}
- /// \brief Returns the flow map.
+ /// \brief Sets the source node.
///
- /// \return The flow map.
- const FlowMap& flowMap() {
- return *_flow;
+ /// Sets the source node.
+ /// \return <tt>(*this)</tt>
+ Preflow& source(const Node& node) {
+ _source = node;
+ return *this;
}
- /// \brief Sets the elevator.
+ /// \brief Sets the target node.
///
- /// Sets the elevator.
- /// \return \c (*this)
+ /// Sets the target node.
+ /// \return <tt>(*this)</tt>
+ Preflow& target(const Node& node) {
+ _target = node;
+ return *this;
+ }
+
+ /// \brief Sets the elevator used by algorithm.
+ ///
+ /// Sets the elevator used by algorithm.
+ /// 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 elevator,
+ /// of course.
+ /// \return <tt>(*this)</tt>
Preflow& elevator(Elevator& elevator) {
if (_local_level) {
delete _level;
@@ -329,29 +360,14 @@
return *this;
}
- /// \brief Returns the elevator.
+ /// \brief Returns a const reference to the elevator.
///
- /// \return The elevator.
+ /// Returns a const reference to the elevator.
+ ///
+ /// \pre Either \ref run() or \ref init() must be called before
+ /// using this function.
const Elevator& elevator() {
return *_level;
- }
-
- /// \brief Sets the source node.
- ///
- /// Sets the source node.
- /// \return \c (*this)
- Preflow& source(const Node& node) {
- _source = node;
- return *this;
- }
-
- /// \brief Sets the target node.
- ///
- /// Sets the target node.
- /// \return \c (*this)
- Preflow& target(const Node& node) {
- _target = node;
- return *this;
}
/// \brief Sets the tolerance used by algorithm.
@@ -362,27 +378,26 @@
return *this;
}
- /// \brief Returns the tolerance used by algorithm.
+ /// \brief Returns a const reference to the tolerance.
///
- /// Returns the tolerance used by algorithm.
+ /// Returns a const reference to the tolerance.
const Tolerance& tolerance() const {
return tolerance;
}
More information about the Lemon-commits
mailing list