437-f63ba40a60f4-16f55008c863.patch on Ticket #437 – Attachment – LEMON

doc/groups.dox

# HG changeset patch
# User Peter Kovacs <kpeter@inf.elte.hu>
# Date 1327962254 -3600
# Node ID f63ba40a60f442278dc74a741050b29857a6daa9
# Parent  48e17328c1551cb8196973d6056a04e40e5d624a
Improve module docs and references (#437)

diff --git a/doc/groups.dox b/doc/groups.dox

-                      a
    strongly polynomial \ref klein67primal, \ref goldberg89cyclecanceling.
 In general, \ref NetworkSimplex and \ref CostScaling are the most efficient
 implementations, but the other two algorithms could be faster in special cases.
+implementations, but the other algorithms could be faster in special cases.
 For example, if the total supply and/or capacities are rather small,
 \ref CapacityScaling is usually the fastest algorithm (without effective scaling).
+These classes are intended to be used with integer-valued input data
+(capacities, supply values, and costs), except for \ref CapacityScaling,
+which is capable of handling real-valued arc costs (other numerical
+data are required to be integer).
 */
 /**
 …
 \brief Algorithms for finding minimum mean cycles.
 This group contains the algorithms for finding minimum mean cycles
 \ref clrs01algorithms, \ref amo93networkflows.
+\ref amo93networkflows, \ref karp78characterization.
 The \e minimum \e mean \e cycle \e problem is to find a directed cycle
 of minimum mean length (cost) in a digraph.
 …
 function.
 LEMON contains three algorithms for solving the minimum mean cycle problem:
+- \ref KarpMmc Karp's original algorithm \ref amo93networkflows,
+  \ref dasdan98minmeancycle.
+- \ref KarpMmc Karp's original algorithm \ref karp78characterization.
 - \ref HartmannOrlinMmc Hartmann-Orlin's algorithm, which is an improved
   version of Karp's algorithm \ref dasdan98minmeancycle.
+  version of Karp's algorithm \ref hartmann93finding.
 - \ref HowardMmc Howard's policy iteration algorithm
   \ref dasdan98minmeancycle.
+  \ref dasdan98minmeancycle, \ref dasdan04experimental.
 In practice, the \ref HowardMmc "Howard" algorithm turned out to be by far the
 most efficient one, though the best known theoretical bound on its running

doc/min_cost_flow.dox

diff --git a/doc/min_cost_flow.dox b/doc/min_cost_flow.dox

-                      a
     sup(u) \quad \forall u\in V \f]
 \f[ lower(uv) \leq f(uv) \leq upper(uv) \quad \forall uv\in A \f]
 However if the sum of the supply values is zero, then these two problems
+However, if the sum of the supply values is zero, then these two problems
 are equivalent.
 The \ref min_cost_flow_algs "algorithms" in LEMON support the general
 form, so if you need the equality form, you have to ensure this additional

doc/references.bib

diff --git a/doc/references.bib b/doc/references.bib

-                      a
   key =          {LEMON},
   title =        {{LEMON} -- {L}ibrary for {E}fficient {M}odeling and
                   {O}ptimization in {N}etworks},
+  howpublished = {\url{http://lemon.cs.elte.hu/}},
+  year =         2009
+  howpublished = {\url{http://lemon.cs.elte.hu/}}
+}
 @misc{egres,
 …
   pages =        {309-311}
+}
+@article{hartmann93finding,
+  author =       {Mark Hartmann and James B. Orlin},
+  title =        {Finding minimum cost to time ratio cycles with small
+                  integral transit times},
+  journal =      {Networks},
+  year =         1993,
+  volume =       23,
+  pages =        {567-574}
+}
 @article{dasdan98minmeancycle,
   author =       {Ali Dasdan and Rajesh K. Gupta},
   title =        {Faster Maximum and Minimum Mean Cycle Alogrithms for
 …
   pages =        {889-899}
+}
+@article{dasdan04experimental,
+  author =       {Ali Dasdan},
+  title =        {Experimental analysis of the fastest optimum cycle
+                  ratio and mean algorithms},
+  journal =      {ACM Trans. Des. Autom. Electron. Syst.},
+  year =         2004,
+  volume =       9,
+  issue =        4,
+  pages =        {385-418}
+}
 %%%%% Minimum cost flow algorithms %%%%%

lemon/hartmann_orlin_mmc.h

diff --git a/lemon/hartmann_orlin_mmc.h b/lemon/hartmann_orlin_mmc.h

-                      a
   ///
   /// This class implements the Hartmann-Orlin algorithm for finding
   /// a directed cycle of minimum mean cost in a digraph
   /// \ref amo93networkflows, \ref dasdan98minmeancycle.
+  /// \ref hartmann93finding, \ref dasdan98minmeancycle.
   /// It is an improved version of \ref KarpMmc "Karp"'s original algorithm,
   /// it applies an efficient early termination scheme.
   /// It runs in time O(ne) and uses space O(n<sup>2</sup>+e).

lemon/howard_mmc.h

diff --git a/lemon/howard_mmc.h b/lemon/howard_mmc.h

-                      a
   ///
   /// This class implements Howard's policy iteration algorithm for finding
   /// a directed cycle of minimum mean cost in a digraph
   /// \ref amo93networkflows, \ref dasdan98minmeancycle.
+  /// \ref dasdan98minmeancycle, \ref dasdan04experimental.
   /// This class provides the most efficient algorithm for the
   /// minimum mean cycle problem, though the best known theoretical
   /// bound on its running time is exponential.

lemon/karp_mmc.h

diff --git a/lemon/karp_mmc.h b/lemon/karp_mmc.h

-                      a
   ///
   /// This class implements Karp's algorithm for finding a directed
   /// cycle of minimum mean cost in a digraph
   /// \ref amo93networkflows, \ref dasdan98minmeancycle.
+  /// \ref karp78characterization, \ref dasdan98minmeancycle.
   /// It runs in time O(ne) and uses space O(n<sup>2</sup>+e).
   ///
   /// \tparam GR The type of the digraph the algorithm runs on.

doc/groups.dox

# HG changeset patch
# User Peter Kovacs <kpeter@inf.elte.hu>
# Date 1327962280 -3600
# Node ID 16f55008c8633f73db3183859734c6981a223cf4
# Parent  f63ba40a60f442278dc74a741050b29857a6daa9
Doc improvements for min cost flow algorithms (#437)

diff --git a/doc/groups.dox b/doc/groups.dox

-                      a
    strongly polynomial \ref klein67primal, \ref goldberg89cyclecanceling.
 In general, \ref NetworkSimplex and \ref CostScaling are the most efficient
+implementations, but the other algorithms could be faster in special cases.
+implementations.
+\ref NetworkSimplex is usually the fastest on relatively small graphs (up to
+several thousands of nodes) and on dense graphs, while \ref CostScaling is
+typically more efficient on large graphs (e.g. hundreds of thousands of
+nodes or above), especially if they are sparse.
+However, other algorithms could be faster in special cases.
 For example, if the total supply and/or capacities are rather small,
 \ref CapacityScaling is usually the fastest algorithm (without effective scaling).

lemon/capacity_scaling.h

diff --git a/lemon/capacity_scaling.h b/lemon/capacity_scaling.h

-                      a
   /// \ref edmondskarp72theoretical. It is an efficient dual
   /// solution method.
   ///
+  /// This algorithm is typically slower than \ref CostScaling and
+  /// \ref NetworkSimplex, but in special cases, it can be more
+  /// efficient than them.
+  /// (For more information, see \ref min_cost_flow_algs "the module page".)
+  ///
   /// Most of the parameters of the problem (except for the digraph)
   /// can be given using separate functions, and the algorithm can be
   /// executed using the \ref run() function. If some parameters are not
 …
       return _res_cap[_arc_idb[a]];
+    }
+    /// \brief Return the flow map (the primal solution).
+    /// \brief Copy the flow values (the primal solution) into the
+    /// given map.
     ///
     /// This function copies the flow value on each arc into the given
     /// map. The \c Value type of the algorithm must be convertible to
 …
       return _pi[_node_id[n]];
+    }
+    /// \brief Return the potential map (the dual solution).
+    /// \brief Copy the potential values (the dual solution) into the
+    /// given map.
     ///
     /// This function copies the potential (dual value) of each node
     /// into the given map.

lemon/cost_scaling.h

diff --git a/lemon/cost_scaling.h b/lemon/cost_scaling.h

-                      a
   /// "preflow push-relabel" algorithm for the maximum flow problem.
   ///
   /// In general, \ref NetworkSimplex and \ref CostScaling are the fastest
+  /// implementations available in LEMON for this problem.
+  /// implementations available in LEMON for solving this problem.
+  /// (For more information, see \ref min_cost_flow_algs "the module page".)
   ///
   /// Most of the parameters of the problem (except for the digraph)
   /// can be given using separate functions, and the algorithm can be
 …
       return _res_cap[_arc_idb[a]];
+    }
+    /// \brief Return the flow map (the primal solution).
+    /// \brief Copy the flow values (the primal solution) into the
+    /// given map.
     ///
     /// This function copies the flow value on each arc into the given
     /// map. The \c Value type of the algorithm must be convertible to
 …
       return static_cast<Cost>(_pi[_node_id[n]]);
+    }
+    /// \brief Return the potential map (the dual solution).
+    /// \brief Copy the potential values (the dual solution) into the
+    /// given map.
     ///
     /// This function copies the potential (dual value) of each node
     /// into the given map.

lemon/cycle_canceling.h

diff --git a/lemon/cycle_canceling.h b/lemon/cycle_canceling.h

-                      a
   /// algorithms for finding a \ref min_cost_flow "minimum cost flow"
   /// \ref amo93networkflows, \ref klein67primal,
   /// \ref goldberg89cyclecanceling.
+  /// The most efficent one (both theoretically and practically)
+  /// is the \ref CANCEL_AND_TIGHTEN "Cancel and Tighten" algorithm,
+  /// thus it is the default method.
+  /// It is strongly polynomial, but in practice, it is typically much
+  /// slower than the scaling algorithms and NetworkSimplex.
+  /// The most efficent one is the \ref CANCEL_AND_TIGHTEN
+  /// "Cancel-and-Tighten" algorithm, thus it is the default method.
+  /// It runs in strongly polynomial time, but in practice, it is typically
+  /// orders of magnitude slower than the scaling algorithms and
+  /// \ref NetworkSimplex.
+  /// (For more information, see \ref min_cost_flow_algs "the module page".)
   ///
   /// Most of the parameters of the problem (except for the digraph)
   /// can be given using separate functions, and the algorithm can be
 …
     /// for the \ref run() function.
     ///
     /// \ref CycleCanceling provides three different cycle-canceling
     /// methods. By default, \ref CANCEL_AND_TIGHTEN "Cancel and Tighten"
+    /// methods. By default, \ref CANCEL_AND_TIGHTEN "Cancel-and-Tighten"
     /// is used, which is by far the most efficient and the most robust.
     /// However, the other methods can be selected using the \ref run()
     /// function with the proper parameter.
     enum Method {
       /// A simple cycle-canceling method, which uses the
+      /// \ref BellmanFord "Bellman-Ford" algorithm with limited iteration
+      /// number for detecting negative cycles in the residual network.
+      /// \ref BellmanFord "Bellman-Ford" algorithm for detecting negative
+      /// cycles in the residual network.
+      /// The number of Bellman-Ford iterations is bounded by a successively
+      /// increased limit.
       SIMPLE_CYCLE_CANCELING,
       /// The "Minimum Mean Cycle-Canceling" algorithm, which is a
       /// well-known strongly polynomial method
       /// \ref goldberg89cyclecanceling. It improves along a
       /// \ref min_mean_cycle "minimum mean cycle" in each iteration.
       /// Its running time complexity is O(n<sup>2</sup>m<sup>3</sup>log(n)).
+      /// Its running time complexity is O(n<sup>2</sup>e<sup>3</sup>log(n)).
       MINIMUM_MEAN_CYCLE_CANCELING,
       /// The "Cancel And Tighten" algorithm, which can be viewed as an
+      /// The "Cancel-and-Tighten" algorithm, which can be viewed as an
       /// improved version of the previous method
       /// \ref goldberg89cyclecanceling.
       /// It is faster both in theory and in practice, its running time
       /// complexity is O(n<sup>2</sup>m<sup>2</sup>log(n)).
+      /// complexity is O(n<sup>2</sup>e<sup>2</sup>log(n)).
       CANCEL_AND_TIGHTEN
     };
 …
       return _res_cap[_arc_idb[a]];
+    }
+    /// \brief Return the flow map (the primal solution).
+    /// \brief Copy the flow values (the primal solution) into the
+    /// given map.
     ///
     /// This function copies the flow value on each arc into the given
     /// map. The \c Value type of the algorithm must be convertible to
 …
       return static_cast<Cost>(_pi[_node_id[n]]);
+    }
+    /// \brief Return the potential map (the dual solution).
+    /// \brief Copy the potential values (the dual solution) into the
+    /// given map.
     ///
     /// This function copies the potential (dual value) of each node
     /// into the given map.
 …
+      }
+    }
     // Execute the "Cancel And Tighten" method
+    // Execute the "Cancel-and-Tighten" method
     void startCancelAndTighten() {
       // Constants for the min mean cycle computations
       const double LIMIT_FACTOR = 1.0;

lemon/network_simplex.h

diff --git a/lemon/network_simplex.h b/lemon/network_simplex.h

-                      a
   /// flow problem.
   ///
   /// In general, \ref NetworkSimplex and \ref CostScaling are the fastest
+  /// implementations available in LEMON for this problem.
+  /// implementations available in LEMON for solving this problem.
+  /// (For more information, see \ref min_cost_flow_algs "the module page".)
   /// Furthermore, this class supports both directions of the supply/demand
   /// inequality constraints. For more information, see \ref SupplyType.
   ///
 …
       return _flow[_arc_id[a]];
+    }
+    /// \brief Return the flow map (the primal solution).
+    /// \brief Copy the flow values (the primal solution) into the
+    /// given map.
     ///
     /// This function copies the flow value on each arc into the given
     /// map. The \c Value type of the algorithm must be convertible to
 …
       return _pi[_node_id[n]];
+    }
+    /// \brief Return the potential map (the dual solution).
+    /// \brief Copy the potential values (the dual solution) into the
+    /// given map.
     ///
     /// This function copies the potential (dual value) of each node
     /// into the given map.

Context Navigation

Ticket #437: 437-f63ba40a60f4-16f55008c863.patch

doc/groups.dox

doc/min_cost_flow.dox

doc/references.bib

lemon/hartmann_orlin_mmc.h

lemon/howard_mmc.h

lemon/karp_mmc.h

doc/groups.dox

lemon/capacity_scaling.h

lemon/cost_scaling.h

lemon/cycle_canceling.h

lemon/network_simplex.h

Download in other formats: