1.1 --- a/lemon/suurballe.h Tue Oct 28 18:39:53 2008 +0000
1.2 +++ b/lemon/suurballe.h Tue Oct 28 23:10:27 2008 +0100
1.3 @@ -33,29 +33,31 @@
1.4 /// \addtogroup shortest_path
1.5 /// @{
1.6
1.7 - /// \brief Implementation of an algorithm for finding arc-disjoint
1.8 - /// paths between two nodes having minimum total length.
1.9 + /// \brief Algorithm for finding arc-disjoint paths between two nodes
1.10 + /// having minimum total length.
1.11 ///
1.12 /// \ref lemon::Suurballe "Suurballe" implements an algorithm for
1.13 /// finding arc-disjoint paths having minimum total length (cost)
1.14 - /// from a given source node to a given target node in a directed
1.15 - /// digraph.
1.16 + /// from a given source node to a given target node in a digraph.
1.17 ///
1.18 /// In fact, this implementation is the specialization of the
1.19 /// \ref CapacityScaling "successive shortest path" algorithm.
1.20 ///
1.21 - /// \tparam Digraph The directed digraph type the algorithm runs on.
1.22 + /// \tparam Digraph The digraph type the algorithm runs on.
1.23 + /// The default value is \c ListDigraph.
1.24 /// \tparam LengthMap The type of the length (cost) map.
1.25 + /// The default value is <tt>Digraph::ArcMap<int></tt>.
1.26 ///
1.27 /// \warning Length values should be \e non-negative \e integers.
1.28 ///
1.29 /// \note For finding node-disjoint paths this algorithm can be used
1.30 /// with \ref SplitDigraphAdaptor.
1.31 - ///
1.32 - /// \author Attila Bernath and Peter Kovacs
1.33 -
1.34 - template < typename Digraph,
1.35 +#ifdef DOXYGEN
1.36 + template <typename Digraph, typename LengthMap>
1.37 +#else
1.38 + template < typename Digraph = ListDigraph,
1.39 typename LengthMap = typename Digraph::template ArcMap<int> >
1.40 +#endif
1.41 class Suurballe
1.42 {
1.43 TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
1.44 @@ -75,7 +77,7 @@
1.45
1.46 private:
1.47
1.48 - /// \brief Special implementation of the \ref Dijkstra algorithm
1.49 + /// \brief Special implementation of the Dijkstra algorithm
1.50 /// for finding shortest paths in the residual network.
1.51 ///
1.52 /// \ref ResidualDijkstra is a special implementation of the
1.53 @@ -90,7 +92,7 @@
1.54
1.55 private:
1.56
1.57 - // The directed digraph the algorithm runs on
1.58 + // The digraph the algorithm runs on
1.59 const Digraph &_graph;
1.60
1.61 // The main maps
1.62 @@ -120,7 +122,7 @@
1.63 _graph(digraph), _flow(flow), _length(length), _potential(potential),
1.64 _dist(digraph), _pred(pred), _s(s), _t(t) {}
1.65
1.66 - /// \brief Runs the algorithm. Returns \c true if a path is found
1.67 + /// \brief Run the algorithm. It returns \c true if a path is found
1.68 /// from the source node to the target node.
1.69 bool run() {
1.70 HeapCrossRef heap_cross_ref(_graph, Heap::PRE_HEAP);
1.71 @@ -129,7 +131,7 @@
1.72 _pred[_s] = INVALID;
1.73 _proc_nodes.clear();
1.74
1.75 - // Processing nodes
1.76 + // Process nodes
1.77 while (!heap.empty() && heap.top() != _t) {
1.78 Node u = heap.top(), v;
1.79 Length d = heap.prio() + _potential[u], nd;
1.80 @@ -137,7 +139,7 @@
1.81 heap.pop();
1.82 _proc_nodes.push_back(u);
1.83
1.84 - // Traversing outgoing arcs
1.85 + // Traverse outgoing arcs
1.86 for (OutArcIt e(_graph, u); e != INVALID; ++e) {
1.87 if (_flow[e] == 0) {
1.88 v = _graph.target(e);
1.89 @@ -159,7 +161,7 @@
1.90 }
1.91 }
1.92
1.93 - // Traversing incoming arcs
1.94 + // Traverse incoming arcs
1.95 for (InArcIt e(_graph, u); e != INVALID; ++e) {
1.96 if (_flow[e] == 1) {
1.97 v = _graph.source(e);
1.98 @@ -183,7 +185,7 @@
1.99 }
1.100 if (heap.empty()) return false;
1.101
1.102 - // Updating potentials of processed nodes
1.103 + // Update potentials of processed nodes
1.104 Length t_dist = heap.prio();
1.105 for (int i = 0; i < int(_proc_nodes.size()); ++i)
1.106 _potential[_proc_nodes[i]] += _dist[_proc_nodes[i]] - t_dist;
1.107 @@ -194,7 +196,7 @@
1.108
1.109 private:
1.110
1.111 - // The directed digraph the algorithm runs on
1.112 + // The digraph the algorithm runs on
1.113 const Digraph &_graph;
1.114 // The length map
1.115 const LengthMap &_length;
1.116 @@ -227,7 +229,7 @@
1.117 ///
1.118 /// Constructor.
1.119 ///
1.120 - /// \param digraph The directed digraph the algorithm runs on.
1.121 + /// \param digraph The digraph the algorithm runs on.
1.122 /// \param length The length (cost) values of the arcs.
1.123 /// \param s The source node.
1.124 /// \param t The target node.
1.125 @@ -245,9 +247,9 @@
1.126 delete _dijkstra;
1.127 }
1.128
1.129 - /// \brief Sets the flow map.
1.130 + /// \brief Set the flow map.
1.131 ///
1.132 - /// Sets the flow map.
1.133 + /// This function sets the flow map.
1.134 ///
1.135 /// The found flow contains only 0 and 1 values. It is the union of
1.136 /// the found arc-disjoint paths.
1.137 @@ -262,9 +264,9 @@
1.138 return *this;
1.139 }
1.140
1.141 - /// \brief Sets the potential map.
1.142 + /// \brief Set the potential map.
1.143 ///
1.144 - /// Sets the potential map.
1.145 + /// This function sets the potential map.
1.146 ///
1.147 /// The potentials provide the dual solution of the underlying
1.148 /// minimum cost flow problem.
1.149 @@ -288,14 +290,14 @@
1.150
1.151 /// @{
1.152
1.153 - /// \brief Runs the algorithm.
1.154 + /// \brief Run the algorithm.
1.155 ///
1.156 - /// Runs the algorithm.
1.157 + /// This function runs the algorithm.
1.158 ///
1.159 /// \param k The number of paths to be found.
1.160 ///
1.161 - /// \return \c k if there are at least \c k arc-disjoint paths
1.162 - /// from \c s to \c t. Otherwise it returns the number of
1.163 + /// \return \c k if there are at least \c k arc-disjoint paths from
1.164 + /// \c s to \c t in the digraph. Otherwise it returns the number of
1.165 /// arc-disjoint paths found.
1.166 ///
1.167 /// \note Apart from the return value, <tt>s.run(k)</tt> is just a
1.168 @@ -312,11 +314,11 @@
1.169 return _path_num;
1.170 }
1.171
1.172 - /// \brief Initializes the algorithm.
1.173 + /// \brief Initialize the algorithm.
1.174 ///
1.175 - /// Initializes the algorithm.
1.176 + /// This function initializes the algorithm.
1.177 void init() {
1.178 - // Initializing maps
1.179 + // Initialize maps
1.180 if (!_flow) {
1.181 _flow = new FlowMap(_graph);
1.182 _local_flow = true;
1.183 @@ -333,27 +335,27 @@
1.184 _source, _target );
1.185 }
1.186
1.187 - /// \brief Executes the successive shortest path algorithm to find
1.188 + /// \brief Execute the successive shortest path algorithm to find
1.189 /// an optimal flow.
1.190 ///
1.191 - /// Executes the successive shortest path algorithm to find a
1.192 - /// minimum cost flow, which is the union of \c k or less
1.193 + /// This function executes the successive shortest path algorithm to
1.194 + /// find a minimum cost flow, which is the union of \c k or less
1.195 /// arc-disjoint paths.
1.196 ///
1.197 - /// \return \c k if there are at least \c k arc-disjoint paths
1.198 - /// from \c s to \c t. Otherwise it returns the number of
1.199 + /// \return \c k if there are at least \c k arc-disjoint paths from
1.200 + /// \c s to \c t in the digraph. Otherwise it returns the number of
1.201 /// arc-disjoint paths found.
1.202 ///
1.203 /// \pre \ref init() must be called before using this function.
1.204 int findFlow(int k = 2) {
1.205 - // Finding shortest paths
1.206 + // Find shortest paths
1.207 _path_num = 0;
1.208 while (_path_num < k) {
1.209 - // Running Dijkstra
1.210 + // Run Dijkstra
1.211 if (!_dijkstra->run()) break;
1.212 ++_path_num;
1.213
1.214 - // Setting the flow along the found shortest path
1.215 + // Set the flow along the found shortest path
1.216 Node u = _target;
1.217 Arc e;
1.218 while ((e = _pred[u]) != INVALID) {
1.219 @@ -369,17 +371,17 @@
1.220 return _path_num;
1.221 }
1.222
1.223 - /// \brief Computes the paths from the flow.
1.224 + /// \brief Compute the paths from the flow.
1.225 ///
1.226 - /// Computes the paths from the flow.
1.227 + /// This function computes the paths from the flow.
1.228 ///
1.229 /// \pre \ref init() and \ref findFlow() must be called before using
1.230 /// this function.
1.231 void findPaths() {
1.232 - // Creating the residual flow map (the union of the paths not
1.233 - // found so far)
1.234 + // Create the residual flow map (the union of the paths not found
1.235 + // so far)
1.236 FlowMap res_flow(_graph);
1.237 - for(ArcIt a(_graph);a!=INVALID;++a) res_flow[a]=(*_flow)[a];
1.238 + for(ArcIt a(_graph); a != INVALID; ++a) res_flow[a] = (*_flow)[a];
1.239
1.240 paths.clear();
1.241 paths.resize(_path_num);
1.242 @@ -398,66 +400,66 @@
1.243 /// @}
1.244
1.245 /// \name Query Functions
1.246 - /// The result of the algorithm can be obtained using these
1.247 + /// The results of the algorithm can be obtained using these
1.248 /// functions.
1.249 /// \n The algorithm should be executed before using them.
1.250
1.251 /// @{
1.252
1.253 - /// \brief Returns a const reference to the arc map storing the
1.254 + /// \brief Return a const reference to the arc map storing the
1.255 /// found flow.
1.256 ///
1.257 - /// Returns a const reference to the arc map storing the flow that
1.258 - /// is the union of the found arc-disjoint paths.
1.259 + /// This function returns a const reference to the arc map storing
1.260 + /// the flow that is the union of the found arc-disjoint paths.
1.261 ///
1.262 - /// \pre \ref run() or findFlow() must be called before using this
1.263 - /// function.
1.264 + /// \pre \ref run() or \ref findFlow() must be called before using
1.265 + /// this function.
1.266 const FlowMap& flowMap() const {
1.267 return *_flow;
1.268 }
1.269
1.270 - /// \brief Returns a const reference to the node map storing the
1.271 + /// \brief Return a const reference to the node map storing the
1.272 /// found potentials (the dual solution).
1.273 ///
1.274 - /// Returns a const reference to the node map storing the found
1.275 - /// potentials that provide the dual solution of the underlying
1.276 - /// minimum cost flow problem.
1.277 + /// This function returns a const reference to the node map storing
1.278 + /// the found potentials that provide the dual solution of the
1.279 + /// underlying minimum cost flow problem.
1.280 ///
1.281 - /// \pre \ref run() or findFlow() must be called before using this
1.282 - /// function.
1.283 + /// \pre \ref run() or \ref findFlow() must be called before using
1.284 + /// this function.
1.285 const PotentialMap& potentialMap() const {
1.286 return *_potential;
1.287 }
1.288
1.289 - /// \brief Returns the flow on the given arc.
1.290 + /// \brief Return the flow on the given arc.
1.291 ///
1.292 - /// Returns the flow on the given arc.
1.293 + /// This function returns the flow on the given arc.
1.294 /// It is \c 1 if the arc is involved in one of the found paths,
1.295 /// otherwise it is \c 0.
1.296 ///
1.297 - /// \pre \ref run() or findFlow() must be called before using this
1.298 - /// function.
1.299 + /// \pre \ref run() or \ref findFlow() must be called before using
1.300 + /// this function.
1.301 int flow(const Arc& arc) const {
1.302 return (*_flow)[arc];
1.303 }
1.304
1.305 - /// \brief Returns the potential of the given node.
1.306 + /// \brief Return the potential of the given node.
1.307 ///
1.308 - /// Returns the potential of the given node.
1.309 + /// This function returns the potential of the given node.
1.310 ///
1.311 - /// \pre \ref run() or findFlow() must be called before using this
1.312 - /// function.
1.313 + /// \pre \ref run() or \ref findFlow() must be called before using
1.314 + /// this function.
1.315 Length potential(const Node& node) const {
1.316 return (*_potential)[node];
1.317 }
1.318
1.319 - /// \brief Returns the total length (cost) of the found paths (flow).
1.320 + /// \brief Return the total length (cost) of the found paths (flow).
1.321 ///
1.322 - /// Returns the total length (cost) of the found paths (flow).
1.323 - /// The complexity of the function is \f$ O(e) \f$.
1.324 + /// This function returns the total length (cost) of the found paths
1.325 + /// (flow). The complexity of the function is \f$ O(e) \f$.
1.326 ///
1.327 - /// \pre \ref run() or findFlow() must be called before using this
1.328 - /// function.
1.329 + /// \pre \ref run() or \ref findFlow() must be called before using
1.330 + /// this function.
1.331 Length totalLength() const {
1.332 Length c = 0;
1.333 for (ArcIt e(_graph); e != INVALID; ++e)
1.334 @@ -465,25 +467,25 @@
1.335 return c;
1.336 }
1.337
1.338 - /// \brief Returns the number of the found paths.
1.339 + /// \brief Return the number of the found paths.
1.340 ///
1.341 - /// Returns the number of the found paths.
1.342 + /// This function returns the number of the found paths.
1.343 ///
1.344 - /// \pre \ref run() or findFlow() must be called before using this
1.345 - /// function.
1.346 + /// \pre \ref run() or \ref findFlow() must be called before using
1.347 + /// this function.
1.348 int pathNum() const {
1.349 return _path_num;
1.350 }
1.351
1.352 - /// \brief Returns a const reference to the specified path.
1.353 + /// \brief Return a const reference to the specified path.
1.354 ///
1.355 - /// Returns a const reference to the specified path.
1.356 + /// This function returns a const reference to the specified path.
1.357 ///
1.358 /// \param i The function returns the \c i-th path.
1.359 /// \c i must be between \c 0 and <tt>%pathNum()-1</tt>.
1.360 ///
1.361 - /// \pre \ref run() or findPaths() must be called before using this
1.362 - /// function.
1.363 + /// \pre \ref run() or \ref findPaths() must be called before using
1.364 + /// this function.
1.365 Path path(int i) const {
1.366 return paths[i];
1.367 }
2.1 --- a/test/suurballe_test.cc Tue Oct 28 18:39:53 2008 +0000
2.2 +++ b/test/suurballe_test.cc Tue Oct 28 23:10:27 2008 +0100
2.3 @@ -28,7 +28,7 @@
2.4
2.5 using namespace lemon;
2.6
2.7 -// Checks the feasibility of the flow
2.8 +// Check the feasibility of the flow
2.9 template <typename Digraph, typename FlowMap>
2.10 bool checkFlow( const Digraph& gr, const FlowMap& flow,
2.11 typename Digraph::Node s, typename Digraph::Node t,
2.12 @@ -52,13 +52,13 @@
2.13 return true;
2.14 }
2.15
2.16 -// Checks the optimalitiy of the flow
2.17 +// Check the optimalitiy of the flow
2.18 template < typename Digraph, typename CostMap,
2.19 typename FlowMap, typename PotentialMap >
2.20 bool checkOptimality( const Digraph& gr, const CostMap& cost,
2.21 const FlowMap& flow, const PotentialMap& pi )
2.22 {
2.23 - // Checking the Complementary Slackness optimality condition
2.24 + // Check the "Complementary Slackness" optimality condition
2.25 TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
2.26 bool opt = true;
2.27 for (ArcIt e(gr); e != INVALID; ++e) {
2.28 @@ -71,12 +71,12 @@
2.29 return opt;
2.30 }
2.31
2.32 -// Checks a path
2.33 -template < typename Digraph, typename Path >
2.34 +// Check a path
2.35 +template <typename Digraph, typename Path>
2.36 bool checkPath( const Digraph& gr, const Path& path,
2.37 typename Digraph::Node s, typename Digraph::Node t)
2.38 {
2.39 - // Checking the Complementary Slackness optimality condition
2.40 + // Check the "Complementary Slackness" optimality condition
2.41 TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
2.42 Node n = s;
2.43 for (int i = 0; i < path.length(); ++i) {
2.44 @@ -91,7 +91,7 @@
2.45 {
2.46 DIGRAPH_TYPEDEFS(ListDigraph);
2.47
2.48 - // Reading the test digraph
2.49 + // Read the test digraph
2.50 ListDigraph digraph;
2.51 ListDigraph::ArcMap<int> length(digraph);
2.52 Node source, target;
2.53 @@ -111,7 +111,7 @@
2.54 run();
2.55 input.close();
2.56
2.57 - // Finding 2 paths
2.58 + // Find 2 paths
2.59 {
2.60 Suurballe<ListDigraph> suurballe(digraph, length, source, target);
2.61 check(suurballe.run(2) == 2, "Wrong number of paths");
2.62 @@ -126,7 +126,7 @@
2.63 "Wrong path");
2.64 }
2.65
2.66 - // Finding 3 paths
2.67 + // Find 3 paths
2.68 {
2.69 Suurballe<ListDigraph> suurballe(digraph, length, source, target);
2.70 check(suurballe.run(3) == 3, "Wrong number of paths");
2.71 @@ -141,7 +141,7 @@
2.72 "Wrong path");
2.73 }
2.74
2.75 - // Finding 5 paths (only 3 can be found)
2.76 + // Find 5 paths (only 3 can be found)
2.77 {
2.78 Suurballe<ListDigraph> suurballe(digraph, length, source, target);
2.79 check(suurballe.run(5) == 3, "Wrong number of paths");