Index: lemon/suurballe.h =================================================================== --- lemon/suurballe.h (revision 345) +++ lemon/suurballe.h (revision 346) @@ -34,17 +34,18 @@ /// @{ - /// \brief Implementation of an algorithm for finding arc-disjoint - /// paths between two nodes having minimum total length. + /// \brief Algorithm for finding arc-disjoint paths between two nodes + /// having minimum total length. /// /// \ref lemon::Suurballe "Suurballe" implements an algorithm for /// finding arc-disjoint paths having minimum total length (cost) - /// from a given source node to a given target node in a directed - /// digraph. + /// from a given source node to a given target node in a digraph. /// /// In fact, this implementation is the specialization of the /// \ref CapacityScaling "successive shortest path" algorithm. /// - /// \tparam Digraph The directed digraph type the algorithm runs on. + /// \tparam Digraph The digraph type the algorithm runs on. + /// The default value is \c ListDigraph. /// \tparam LengthMap The type of the length (cost) map. + /// The default value is Digraph::ArcMap. /// /// \warning Length values should be \e non-negative \e integers. @@ -52,9 +53,10 @@ /// \note For finding node-disjoint paths this algorithm can be used /// with \ref SplitDigraphAdaptor. - /// - /// \author Attila Bernath and Peter Kovacs - - template < typename Digraph, +#ifdef DOXYGEN + template +#else + template < typename Digraph = ListDigraph, typename LengthMap = typename Digraph::template ArcMap > +#endif class Suurballe { @@ -76,5 +78,5 @@ private: - /// \brief Special implementation of the \ref Dijkstra algorithm + /// \brief Special implementation of the Dijkstra algorithm /// for finding shortest paths in the residual network. /// @@ -91,5 +93,5 @@ private: - // The directed digraph the algorithm runs on + // The digraph the algorithm runs on const Digraph &_graph; @@ -121,5 +123,5 @@ _dist(digraph), _pred(pred), _s(s), _t(t) {} - /// \brief Runs the algorithm. Returns \c true if a path is found + /// \brief Run the algorithm. It returns \c true if a path is found /// from the source node to the target node. bool run() { @@ -130,5 +132,5 @@ _proc_nodes.clear(); - // Processing nodes + // Process nodes while (!heap.empty() && heap.top() != _t) { Node u = heap.top(), v; @@ -138,5 +140,5 @@ _proc_nodes.push_back(u); - // Traversing outgoing arcs + // Traverse outgoing arcs for (OutArcIt e(_graph, u); e != INVALID; ++e) { if (_flow[e] == 0) { @@ -160,5 +162,5 @@ } - // Traversing incoming arcs + // Traverse incoming arcs for (InArcIt e(_graph, u); e != INVALID; ++e) { if (_flow[e] == 1) { @@ -184,5 +186,5 @@ if (heap.empty()) return false; - // Updating potentials of processed nodes + // Update potentials of processed nodes Length t_dist = heap.prio(); for (int i = 0; i < int(_proc_nodes.size()); ++i) @@ -195,5 +197,5 @@ private: - // The directed digraph the algorithm runs on + // The digraph the algorithm runs on const Digraph &_graph; // The length map @@ -228,5 +230,5 @@ /// Constructor. /// - /// \param digraph The directed digraph the algorithm runs on. + /// \param digraph The digraph the algorithm runs on. /// \param length The length (cost) values of the arcs. /// \param s The source node. @@ -246,7 +248,7 @@ } - /// \brief Sets the flow map. - /// - /// Sets the flow map. + /// \brief Set the flow map. + /// + /// This function sets the flow map. /// /// The found flow contains only 0 and 1 values. It is the union of @@ -263,7 +265,7 @@ } - /// \brief Sets the potential map. - /// - /// Sets the potential map. + /// \brief Set the potential map. + /// + /// This function sets the potential map. /// /// The potentials provide the dual solution of the underlying @@ -289,12 +291,12 @@ /// @{ - /// \brief Runs the algorithm. - /// - /// Runs the algorithm. + /// \brief Run the algorithm. + /// + /// This function runs the algorithm. /// /// \param k The number of paths to be found. /// - /// \return \c k if there are at least \c k arc-disjoint paths - /// from \c s to \c t. Otherwise it returns the number of + /// \return \c k if there are at least \c k arc-disjoint paths from + /// \c s to \c t in the digraph. Otherwise it returns the number of /// arc-disjoint paths found. /// @@ -313,9 +315,9 @@ } - /// \brief Initializes the algorithm. - /// - /// Initializes the algorithm. + /// \brief Initialize the algorithm. + /// + /// This function initializes the algorithm. void init() { - // Initializing maps + // Initialize maps if (!_flow) { _flow = new FlowMap(_graph); @@ -334,25 +336,25 @@ } - /// \brief Executes the successive shortest path algorithm to find + /// \brief Execute the successive shortest path algorithm to find /// an optimal flow. /// - /// Executes the successive shortest path algorithm to find a - /// minimum cost flow, which is the union of \c k or less + /// This function executes the successive shortest path algorithm to + /// find a minimum cost flow, which is the union of \c k or less /// arc-disjoint paths. /// - /// \return \c k if there are at least \c k arc-disjoint paths - /// from \c s to \c t. Otherwise it returns the number of + /// \return \c k if there are at least \c k arc-disjoint paths from + /// \c s to \c t in the digraph. Otherwise it returns the number of /// arc-disjoint paths found. /// /// \pre \ref init() must be called before using this function. int findFlow(int k = 2) { - // Finding shortest paths + // Find shortest paths _path_num = 0; while (_path_num < k) { - // Running Dijkstra + // Run Dijkstra if (!_dijkstra->run()) break; ++_path_num; - // Setting the flow along the found shortest path + // Set the flow along the found shortest path Node u = _target; Arc e; @@ -370,15 +372,15 @@ } - /// \brief Computes the paths from the flow. - /// - /// Computes the paths from the flow. + /// \brief Compute the paths from the flow. + /// + /// This function computes the paths from the flow. /// /// \pre \ref init() and \ref findFlow() must be called before using /// this function. void findPaths() { - // Creating the residual flow map (the union of the paths not - // found so far) + // Create the residual flow map (the union of the paths not found + // so far) FlowMap res_flow(_graph); - for(ArcIt a(_graph);a!=INVALID;++a) res_flow[a]=(*_flow)[a]; + for(ArcIt a(_graph); a != INVALID; ++a) res_flow[a] = (*_flow)[a]; paths.clear(); @@ -399,5 +401,5 @@ /// \name Query Functions - /// The result of the algorithm can be obtained using these + /// The results of the algorithm can be obtained using these /// functions. /// \n The algorithm should be executed before using them. @@ -405,58 +407,58 @@ /// @{ - /// \brief Returns a const reference to the arc map storing the + /// \brief Return a const reference to the arc map storing the /// found flow. /// - /// Returns a const reference to the arc map storing the flow that - /// is the union of the found arc-disjoint paths. - /// - /// \pre \ref run() or findFlow() must be called before using this - /// function. + /// This function returns a const reference to the arc map storing + /// the flow that is the union of the found arc-disjoint paths. + /// + /// \pre \ref run() or \ref findFlow() must be called before using + /// this function. const FlowMap& flowMap() const { return *_flow; } - /// \brief Returns a const reference to the node map storing the + /// \brief Return a const reference to the node map storing the /// found potentials (the dual solution). /// - /// Returns a const reference to the node map storing the found - /// potentials that provide the dual solution of the underlying - /// minimum cost flow problem. - /// - /// \pre \ref run() or findFlow() must be called before using this - /// function. + /// This function returns a const reference to the node map storing + /// the found potentials that provide the dual solution of the + /// underlying minimum cost flow problem. + /// + /// \pre \ref run() or \ref findFlow() must be called before using + /// this function. const PotentialMap& potentialMap() const { return *_potential; } - /// \brief Returns the flow on the given arc. - /// - /// Returns the flow on the given arc. + /// \brief Return the flow on the given arc. + /// + /// This function returns the flow on the given arc. /// It is \c 1 if the arc is involved in one of the found paths, /// otherwise it is \c 0. /// - /// \pre \ref run() or findFlow() must be called before using this - /// function. + /// \pre \ref run() or \ref findFlow() must be called before using + /// this function. int flow(const Arc& arc) const { return (*_flow)[arc]; } - /// \brief Returns the potential of the given node. - /// - /// Returns the potential of the given node. - /// - /// \pre \ref run() or findFlow() must be called before using this - /// function. + /// \brief Return the potential of the given node. + /// + /// This function returns the potential of the given node. + /// + /// \pre \ref run() or \ref findFlow() must be called before using + /// this function. Length potential(const Node& node) const { return (*_potential)[node]; } - /// \brief Returns the total length (cost) of the found paths (flow). - /// - /// Returns the total length (cost) of the found paths (flow). - /// The complexity of the function is \f$O(e) \f$. - /// - /// \pre \ref run() or findFlow() must be called before using this - /// function. + /// \brief Return the total length (cost) of the found paths (flow). + /// + /// This function returns the total length (cost) of the found paths + /// (flow). The complexity of the function is \f$O(e) \f$. + /// + /// \pre \ref run() or \ref findFlow() must be called before using + /// this function. Length totalLength() const { Length c = 0; @@ -466,23 +468,23 @@ } - /// \brief Returns the number of the found paths. - /// - /// Returns the number of the found paths. - /// - /// \pre \ref run() or findFlow() must be called before using this - /// function. + /// \brief Return the number of the found paths. + /// + /// This function returns the number of the found paths. + /// + /// \pre \ref run() or \ref findFlow() must be called before using + /// this function. int pathNum() const { return _path_num; } - /// \brief Returns a const reference to the specified path. - /// - /// Returns a const reference to the specified path. + /// \brief Return a const reference to the specified path. + /// + /// This function returns a const reference to the specified path. /// /// \param i The function returns the \c i-th path. /// \c i must be between \c 0 and %pathNum()-1. /// - /// \pre \ref run() or findPaths() must be called before using this - /// function. + /// \pre \ref run() or \ref findPaths() must be called before using + /// this function. Path path(int i) const { return paths[i]; Index: test/suurballe_test.cc =================================================================== --- test/suurballe_test.cc (revision 345) +++ test/suurballe_test.cc (revision 346) @@ -29,5 +29,5 @@ using namespace lemon; -// Checks the feasibility of the flow +// Check the feasibility of the flow template bool checkFlow( const Digraph& gr, const FlowMap& flow, @@ -53,5 +53,5 @@ } -// Checks the optimalitiy of the flow +// Check the optimalitiy of the flow template < typename Digraph, typename CostMap, typename FlowMap, typename PotentialMap > @@ -59,5 +59,5 @@ const FlowMap& flow, const PotentialMap& pi ) { - // Checking the Complementary Slackness optimality condition + // Check the "Complementary Slackness" optimality condition TEMPLATE_DIGRAPH_TYPEDEFS(Digraph); bool opt = true; @@ -72,10 +72,10 @@ } -// Checks a path -template < typename Digraph, typename Path > +// Check a path +template bool checkPath( const Digraph& gr, const Path& path, typename Digraph::Node s, typename Digraph::Node t) { - // Checking the Complementary Slackness optimality condition + // Check the "Complementary Slackness" optimality condition TEMPLATE_DIGRAPH_TYPEDEFS(Digraph); Node n = s; @@ -92,5 +92,5 @@ DIGRAPH_TYPEDEFS(ListDigraph); - // Reading the test digraph + // Read the test digraph ListDigraph digraph; ListDigraph::ArcMap length(digraph); @@ -112,5 +112,5 @@ input.close(); - // Finding 2 paths + // Find 2 paths { Suurballe suurballe(digraph, length, source, target); @@ -127,5 +127,5 @@ } - // Finding 3 paths + // Find 3 paths { Suurballe suurballe(digraph, length, source, target); @@ -142,5 +142,5 @@ } - // Finding 5 paths (only 3 can be found) + // Find 5 paths (only 3 can be found) { Suurballe suurballe(digraph, length, source, target);