Minor doc improvements related to Suurballe (#47)
authorPeter Kovacs <kpeter@inf.elte.hu>
Tue, 28 Oct 2008 23:10:27 +0100 (2008-10-28)
changeset 3467f26c4b32651
parent 345 2f64c4a692a8
child 347 85820a499b76
Minor doc improvements related to Suurballe (#47)
lemon/suurballe.h
test/suurballe_test.cc
     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");