COIN-OR::LEMON - Graph Library

Ticket #47: suurb2_613d47d29dc3.patch

File suurb2_613d47d29dc3.patch, 15.5 KB (added by Peter Kovacs, 16 years ago)
  • lemon/suurballe.h

    # HG changeset patch
    # User Peter Kovacs <kpeter@inf.elte.hu>
    # Date 1225231827 -3600
    # Node ID 613d47d29dc30cc4b2aa702eba457ece24c799d9
    # Parent  39ff10276621ccdf7d74451efba324da4253b626
    Minor doc improvements related to Suurballe (#47)
    
    diff --git a/lemon/suurballe.h b/lemon/suurballe.h
    a b  
    3333  /// \addtogroup shortest_path
    3434  /// @{
    3535
    36   /// \brief Implementation of an algorithm for finding arc-disjoint
    37   /// paths between two nodes having minimum total length.
     36  /// \brief Algorithm for finding arc-disjoint paths between two nodes
     37  /// having minimum total length.
    3838  ///
    3939  /// \ref lemon::Suurballe "Suurballe" implements an algorithm for
    4040  /// finding arc-disjoint paths having minimum total length (cost)
    41   /// from a given source node to a given target node in a directed
    42   /// digraph.
     41  /// from a given source node to a given target node in a digraph.
    4342  ///
    4443  /// In fact, this implementation is the specialization of the
    4544  /// \ref CapacityScaling "successive shortest path" algorithm.
    4645  ///
    47   /// \tparam Digraph The directed digraph type the algorithm runs on.
     46  /// \tparam Digraph The digraph type the algorithm runs on.
     47  /// The default value is \c ListDigraph.
    4848  /// \tparam LengthMap The type of the length (cost) map.
     49  /// The default value is <tt>Digraph::ArcMap<int></tt>.
    4950  ///
    5051  /// \warning Length values should be \e non-negative \e integers.
    5152  ///
    5253  /// \note For finding node-disjoint paths this algorithm can be used
    5354  /// with \ref SplitDigraphAdaptor.
    54   ///
    55   /// \author Attila Bernath and Peter Kovacs
    56 
    57   template < typename Digraph,
     55#ifdef DOXYGEN
     56  template <typename Digraph, typename LengthMap>
     57#else
     58  template < typename Digraph = ListDigraph,
    5859             typename LengthMap = typename Digraph::template ArcMap<int> >
     60#endif
    5961  class Suurballe
    6062  {
    6163    TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
     
    7577
    7678  private:
    7779
    78     /// \brief Special implementation of the \ref Dijkstra algorithm
     80    /// \brief Special implementation of the Dijkstra algorithm
    7981    /// for finding shortest paths in the residual network.
    8082    ///
    8183    /// \ref ResidualDijkstra is a special implementation of the
     
    9092
    9193    private:
    9294
    93       // The directed digraph the algorithm runs on
     95      // The digraph the algorithm runs on
    9496      const Digraph &_graph;
    9597
    9698      // The main maps
     
    120122        _graph(digraph), _flow(flow), _length(length), _potential(potential),
    121123        _dist(digraph), _pred(pred), _s(s), _t(t) {}
    122124
    123       /// \brief Runs the algorithm. Returns \c true if a path is found
     125      /// \brief Run the algorithm. It returns \c true if a path is found
    124126      /// from the source node to the target node.
    125127      bool run() {
    126128        HeapCrossRef heap_cross_ref(_graph, Heap::PRE_HEAP);
     
    129131        _pred[_s] = INVALID;
    130132        _proc_nodes.clear();
    131133
    132         // Processing nodes
     134        // Process nodes
    133135        while (!heap.empty() && heap.top() != _t) {
    134136          Node u = heap.top(), v;
    135137          Length d = heap.prio() + _potential[u], nd;
     
    137139          heap.pop();
    138140          _proc_nodes.push_back(u);
    139141
    140           // Traversing outgoing arcs
     142          // Traverse outgoing arcs
    141143          for (OutArcIt e(_graph, u); e != INVALID; ++e) {
    142144            if (_flow[e] == 0) {
    143145              v = _graph.target(e);
     
    159161            }
    160162          }
    161163
    162           // Traversing incoming arcs
     164          // Traverse incoming arcs
    163165          for (InArcIt e(_graph, u); e != INVALID; ++e) {
    164166            if (_flow[e] == 1) {
    165167              v = _graph.source(e);
     
    183185        }
    184186        if (heap.empty()) return false;
    185187
    186         // Updating potentials of processed nodes
     188        // Update potentials of processed nodes
    187189        Length t_dist = heap.prio();
    188190        for (int i = 0; i < int(_proc_nodes.size()); ++i)
    189191          _potential[_proc_nodes[i]] += _dist[_proc_nodes[i]] - t_dist;
     
    194196
    195197  private:
    196198
    197     // The directed digraph the algorithm runs on
     199    // The digraph the algorithm runs on
    198200    const Digraph &_graph;
    199201    // The length map
    200202    const LengthMap &_length;
     
    227229    ///
    228230    /// Constructor.
    229231    ///
    230     /// \param digraph The directed digraph the algorithm runs on.
     232    /// \param digraph The digraph the algorithm runs on.
    231233    /// \param length The length (cost) values of the arcs.
    232234    /// \param s The source node.
    233235    /// \param t The target node.
     
    245247      delete _dijkstra;
    246248    }
    247249
    248     /// \brief Sets the flow map.
     250    /// \brief Set the flow map.
    249251    ///
    250     /// Sets the flow map.
     252    /// This function sets the flow map.
    251253    ///
    252254    /// The found flow contains only 0 and 1 values. It is the union of
    253255    /// the found arc-disjoint paths.
     
    262264      return *this;
    263265    }
    264266
    265     /// \brief Sets the potential map.
     267    /// \brief Set the potential map.
    266268    ///
    267     /// Sets the potential map.
     269    /// This function sets the potential map.
    268270    ///
    269271    /// The potentials provide the dual solution of the underlying
    270272    /// minimum cost flow problem.
     
    288290
    289291    /// @{
    290292
    291     /// \brief Runs the algorithm.
     293    /// \brief Run the algorithm.
    292294    ///
    293     /// Runs the algorithm.
     295    /// This function runs the algorithm.
    294296    ///
    295297    /// \param k The number of paths to be found.
    296298    ///
    297     /// \return \c k if there are at least \c k arc-disjoint paths
    298     /// from \c s to \c t. Otherwise it returns the number of
     299    /// \return \c k if there are at least \c k arc-disjoint paths from
     300    /// \c s to \c t in the digraph. Otherwise it returns the number of
    299301    /// arc-disjoint paths found.
    300302    ///
    301303    /// \note Apart from the return value, <tt>s.run(k)</tt> is just a
     
    312314      return _path_num;
    313315    }
    314316
    315     /// \brief Initializes the algorithm.
     317    /// \brief Initialize the algorithm.
    316318    ///
    317     /// Initializes the algorithm.
     319    /// This function initializes the algorithm.
    318320    void init() {
    319       // Initializing maps
     321      // Initialize maps
    320322      if (!_flow) {
    321323        _flow = new FlowMap(_graph);
    322324        _local_flow = true;
     
    333335                                        _source, _target );
    334336    }
    335337
    336     /// \brief Executes the successive shortest path algorithm to find
     338    /// \brief Execute the successive shortest path algorithm to find
    337339    /// an optimal flow.
    338340    ///
    339     /// Executes the successive shortest path algorithm to find a
    340     /// minimum cost flow, which is the union of \c k or less
     341    /// This function executes the successive shortest path algorithm to
     342    /// find a minimum cost flow, which is the union of \c k or less
    341343    /// arc-disjoint paths.
    342344    ///
    343     /// \return \c k if there are at least \c k arc-disjoint paths
    344     /// from \c s to \c t. Otherwise it returns the number of
     345    /// \return \c k if there are at least \c k arc-disjoint paths from
     346    /// \c s to \c t in the digraph. Otherwise it returns the number of
    345347    /// arc-disjoint paths found.
    346348    ///
    347349    /// \pre \ref init() must be called before using this function.
    348350    int findFlow(int k = 2) {
    349       // Finding shortest paths
     351      // Find shortest paths
    350352      _path_num = 0;
    351353      while (_path_num < k) {
    352         // Running Dijkstra
     354        // Run Dijkstra
    353355        if (!_dijkstra->run()) break;
    354356        ++_path_num;
    355357
    356         // Setting the flow along the found shortest path
     358        // Set the flow along the found shortest path
    357359        Node u = _target;
    358360        Arc e;
    359361        while ((e = _pred[u]) != INVALID) {
     
    369371      return _path_num;
    370372    }
    371373
    372     /// \brief Computes the paths from the flow.
     374    /// \brief Compute the paths from the flow.
    373375    ///
    374     /// Computes the paths from the flow.
     376    /// This function computes the paths from the flow.
    375377    ///
    376378    /// \pre \ref init() and \ref findFlow() must be called before using
    377379    /// this function.
    378380    void findPaths() {
    379       // Creating the residual flow map (the union of the paths not
    380       // found so far)
     381      // Create the residual flow map (the union of the paths not found
     382      // so far)
    381383      FlowMap res_flow(_graph);
    382       for(ArcIt a(_graph);a!=INVALID;++a) res_flow[a]=(*_flow)[a];
     384      for(ArcIt a(_graph); a != INVALID; ++a) res_flow[a] = (*_flow)[a];
    383385
    384386      paths.clear();
    385387      paths.resize(_path_num);
     
    398400    /// @}
    399401
    400402    /// \name Query Functions
    401     /// The result of the algorithm can be obtained using these
     403    /// The results of the algorithm can be obtained using these
    402404    /// functions.
    403405    /// \n The algorithm should be executed before using them.
    404406
    405407    /// @{
    406408
    407     /// \brief Returns a const reference to the arc map storing the
     409    /// \brief Return a const reference to the arc map storing the
    408410    /// found flow.
    409411    ///
    410     /// Returns a const reference to the arc map storing the flow that
    411     /// is the union of the found arc-disjoint paths.
     412    /// This function returns a const reference to the arc map storing
     413    /// the flow that is the union of the found arc-disjoint paths.
    412414    ///
    413     /// \pre \ref run() or findFlow() must be called before using this
    414     /// function.
     415    /// \pre \ref run() or \ref findFlow() must be called before using
     416    /// this function.
    415417    const FlowMap& flowMap() const {
    416418      return *_flow;
    417419    }
    418420
    419     /// \brief Returns a const reference to the node map storing the
     421    /// \brief Return a const reference to the node map storing the
    420422    /// found potentials (the dual solution).
    421423    ///
    422     /// Returns a const reference to the node map storing the found
    423     /// potentials that provide the dual solution of the underlying
    424     /// minimum cost flow problem.
     424    /// This function returns a const reference to the node map storing
     425    /// the found potentials that provide the dual solution of the
     426    /// underlying minimum cost flow problem.
    425427    ///
    426     /// \pre \ref run() or findFlow() must be called before using this
    427     /// function.
     428    /// \pre \ref run() or \ref findFlow() must be called before using
     429    /// this function.
    428430    const PotentialMap& potentialMap() const {
    429431      return *_potential;
    430432    }
    431433
    432     /// \brief Returns the flow on the given arc.
     434    /// \brief Return the flow on the given arc.
    433435    ///
    434     /// Returns the flow on the given arc.
     436    /// This function returns the flow on the given arc.
    435437    /// It is \c 1 if the arc is involved in one of the found paths,
    436438    /// otherwise it is \c 0.
    437439    ///
    438     /// \pre \ref run() or findFlow() must be called before using this
    439     /// function.
     440    /// \pre \ref run() or \ref findFlow() must be called before using
     441    /// this function.
    440442    int flow(const Arc& arc) const {
    441443      return (*_flow)[arc];
    442444    }
    443445
    444     /// \brief Returns the potential of the given node.
     446    /// \brief Return the potential of the given node.
    445447    ///
    446     /// Returns the potential of the given node.
     448    /// This function returns the potential of the given node.
    447449    ///
    448     /// \pre \ref run() or findFlow() must be called before using this
    449     /// function.
     450    /// \pre \ref run() or \ref findFlow() must be called before using
     451    /// this function.
    450452    Length potential(const Node& node) const {
    451453      return (*_potential)[node];
    452454    }
    453455
    454     /// \brief Returns the total length (cost) of the found paths (flow).
     456    /// \brief Return the total length (cost) of the found paths (flow).
    455457    ///
    456     /// Returns the total length (cost) of the found paths (flow).
    457     /// The complexity of the function is \f$ O(e) \f$.
     458    /// This function returns the total length (cost) of the found paths
     459    /// (flow). The complexity of the function is \f$ O(e) \f$.
    458460    ///
    459     /// \pre \ref run() or findFlow() must be called before using this
    460     /// function.
     461    /// \pre \ref run() or \ref findFlow() must be called before using
     462    /// this function.
    461463    Length totalLength() const {
    462464      Length c = 0;
    463465      for (ArcIt e(_graph); e != INVALID; ++e)
     
    465467      return c;
    466468    }
    467469
    468     /// \brief Returns the number of the found paths.
     470    /// \brief Return the number of the found paths.
    469471    ///
    470     /// Returns the number of the found paths.
     472    /// This function returns the number of the found paths.
    471473    ///
    472     /// \pre \ref run() or findFlow() must be called before using this
    473     /// function.
     474    /// \pre \ref run() or \ref findFlow() must be called before using
     475    /// this function.
    474476    int pathNum() const {
    475477      return _path_num;
    476478    }
    477479
    478     /// \brief Returns a const reference to the specified path.
     480    /// \brief Return a const reference to the specified path.
    479481    ///
    480     /// Returns a const reference to the specified path.
     482    /// This function returns a const reference to the specified path.
    481483    ///
    482484    /// \param i The function returns the \c i-th path.
    483485    /// \c i must be between \c 0 and <tt>%pathNum()-1</tt>.
    484486    ///
    485     /// \pre \ref run() or findPaths() must be called before using this
    486     /// function.
     487    /// \pre \ref run() or \ref findPaths() must be called before using
     488    /// this function.
    487489    Path path(int i) const {
    488490      return paths[i];
    489491    }
  • test/suurballe_test.cc

    diff --git a/test/suurballe_test.cc b/test/suurballe_test.cc
    a b  
    2828
    2929using namespace lemon;
    3030
    31 // Checks the feasibility of the flow
     31// Check the feasibility of the flow
    3232template <typename Digraph, typename FlowMap>
    3333bool checkFlow( const Digraph& gr, const FlowMap& flow,
    3434                typename Digraph::Node s, typename Digraph::Node t,
     
    5252  return true;
    5353}
    5454
    55 // Checks the optimalitiy of the flow
     55// Check the optimalitiy of the flow
    5656template < typename Digraph, typename CostMap,
    5757           typename FlowMap, typename PotentialMap >
    5858bool checkOptimality( const Digraph& gr, const CostMap& cost,
    5959                      const FlowMap& flow, const PotentialMap& pi )
    6060{
    61   // Checking the Complementary Slackness optimality condition
     61  // Check the "Complementary Slackness" optimality condition
    6262  TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
    6363  bool opt = true;
    6464  for (ArcIt e(gr); e != INVALID; ++e) {
     
    7171  return opt;
    7272}
    7373
    74 // Checks a path
    75 template < typename Digraph, typename Path >
     74// Check a path
     75template <typename Digraph, typename Path>
    7676bool checkPath( const Digraph& gr, const Path& path,
    7777                typename Digraph::Node s, typename Digraph::Node t)
    7878{
    79   // Checking the Complementary Slackness optimality condition
     79  // Check the "Complementary Slackness" optimality condition
    8080  TEMPLATE_DIGRAPH_TYPEDEFS(Digraph);
    8181  Node n = s;
    8282  for (int i = 0; i < path.length(); ++i) {
     
    9191{
    9292  DIGRAPH_TYPEDEFS(ListDigraph);
    9393
    94   // Reading the test digraph
     94  // Read the test digraph
    9595  ListDigraph digraph;
    9696  ListDigraph::ArcMap<int> length(digraph);
    9797  Node source, target;
     
    111111    run();
    112112  input.close();
    113113
    114   // Finding 2 paths
     114  // Find 2 paths
    115115  {
    116116    Suurballe<ListDigraph> suurballe(digraph, length, source, target);
    117117    check(suurballe.run(2) == 2, "Wrong number of paths");
     
    126126            "Wrong path");
    127127  }
    128128
    129   // Finding 3 paths
     129  // Find 3 paths
    130130  {
    131131    Suurballe<ListDigraph> suurballe(digraph, length, source, target);
    132132    check(suurballe.run(3) == 3, "Wrong number of paths");
     
    141141            "Wrong path");
    142142  }
    143143
    144   // Finding 5 paths (only 3 can be found)
     144  // Find 5 paths (only 3 can be found)
    145145  {
    146146    Suurballe<ListDigraph> suurballe(digraph, length, source, target);
    147147    check(suurballe.run(5) == 3, "Wrong number of paths");