[Lemon-commits] [lemon_svn] athos: r2968 - hugo/trunk/lemon

[Lemon SVN]

Author: athos
Date: Mon Oct  2 16:41:53 2006
New Revision: 2968

Modified:
   hugo/trunk/lemon/hao_orlin.h

Log:
Improved documentation.

Modified: hugo/trunk/lemon/hao_orlin.h
==============================================================================
--- hugo/trunk/lemon/hao_orlin.h	(original)
+++ hugo/trunk/lemon/hao_orlin.h	Mon Oct  2 16:41:53 2006
@@ -40,26 +40,31 @@
 
   /// \ingroup flowalgs
   ///
-  /// \brief %Hao-Orlin algorithm for calculate minimum cut in directed graphs.
+  /// \brief %Hao-Orlin algorithm to find a minimum cut in directed graphs.
   ///
-  /// Hao-Orlin calculates the minimum cut in directed graphs. It
-  /// separates the nodes of the graph into two disjoint sets, 
-  /// \f$ V_{out} \f$ and \f$ V_{in} \f$. This separation is the minimum
-  /// cut if the summary of the edge capacities which source is in
-  /// \f$ V_{out} \f$ and the target is in \f$ V_{in} \f$ is the
-  /// minimum.  The algorithm is a modified push-relabel preflow
-  /// algorithm and it calculates the minimum cut in \f$ O(n^3) \f$
-  /// time. The purpose of such algorithm is testing network
-  /// reliability. For sparse undirected graph you can use the
-  /// algorithm of Nagamochi and Ibaraki which solves the undirected
-  /// problem in \f$ O(ne + n^2 \log(n)) \f$ time and it is implemented in the
-  /// MinCut algorithm class.
+  /// Hao-Orlin calculates a minimum cut in a directed graph \f$
+  /// D=(V,A) \f$. It takes a fixed node \f$ source \in V \f$ and consists
+  /// of two phases: in the first phase it determines a minimum cut
+  /// with \f$ source \f$ on the source-side (i.e. a set \f$ X\subsetneq V
+  /// \f$ with \f$ source \in X \f$ and minimal out-degree) and in the
+  /// second phase it determines a minimum cut with \f$ source \f$ on the
+  /// sink-side (i.e. a set \f$ X\subsetneq V \f$ with \f$ source \notin X \f$
+  /// and minimal out-degree). Obviously, the smaller of these two
+  /// cuts will be a minimum cut of \f$ D \f$. The algorithm is a
+  /// modified push-relabel preflow algorithm and our implementation
+  /// calculates the minimum cut in \f$ O(n^3) \f$ time (we use the
+  /// highest-label rule). The purpose of such an algorithm is testing
+  /// network reliability. For an undirected graph with \f$ n \f$
+  /// nodes and \f$ e \f$ edges you can use the algorithm of Nagamochi
+  /// and Ibaraki which solves the undirected problem in \f$ O(ne +
+  /// n^2 \log(n)) \f$ time: it is implemented in the MinCut algorithm
+  /// class.
   ///
   /// \param _Graph is the graph type of the algorithm.
   /// \param _CapacityMap is an edge map of capacities which should
   /// be any numreric type. The default type is _Graph::EdgeMap<int>.
   /// \param _Tolerance is the handler of the inexact computation. The
-  /// default type for it is Tolerance<typename CapacityMap::Value>.
+  /// default type for this is Tolerance<typename CapacityMap::Value>.
   ///
   /// \author Attila Bernath and Balazs Dezso
 #ifdef DOXYGEN
@@ -478,7 +483,7 @@
     ///
     /// Initializes the internal data structures. It creates
     /// the maps, residual graph adaptor and some bucket structures
-    /// for the algorithm. The \c source node is used as the push-relabel
+    /// for the algorithm. Node \c source  is used as the push-relabel
     /// algorithm's source.
     void init(const Node& source) {
       _source = source;
@@ -526,11 +531,12 @@
     }
 
 
-    /// \brief Calculates the minimum cut with the \c source node
-    /// in the \f$ V_{out} \f$.
+    /// \brief Calculates a minimum cut with \f$ source \f$ on the
+    /// source-side.
     ///
-    /// Calculates the minimum cut with the \c source node
-    /// in the \f$ V_{out} \f$.
+    /// \brief Calculates a minimum cut with \f$ source \f$ on the
+    /// source-side (i.e. a set \f$ X\subsetneq V \f$ with \f$ source \in X
+    /// \f$ and minimal out-degree).
     void calculateOut() {
       for (NodeIt it(*_graph); it != INVALID; ++it) {
         if (it != _source) {
@@ -540,21 +546,23 @@
       }
     }
 
-    /// \brief Calculates the minimum cut with the \c source node
-    /// in the \f$ V_{out} \f$.
+    /// \brief Calculates a minimum cut with \f$ source \f$ on the
+    /// source-side.
     ///
-    /// Calculates the minimum cut with the \c source node
-    /// in the \f$ V_{out} \f$. The \c target is the initial target
+    /// \brief Calculates a minimum cut with \f$ source \f$ on the
+    /// source-side (i.e. a set \f$ X\subsetneq V \f$ with \f$ source \in X
+    /// \f$ and minimal out-degree). The \c target is the initial target
     /// for the push-relabel algorithm.
     void calculateOut(const Node& target) {
       findMinCut(target, true, *_out_res_graph, *_out_current_edge);
     }
 
-    /// \brief Calculates the minimum cut with the \c source node
-    /// in the \f$ V_{in} \f$.
+    /// \brief Calculates a minimum cut with \f$ source \f$ on the
+    /// sink-side.
     ///
-    /// Calculates the minimum cut with the \c source node
-    /// in the \f$ V_{in} \f$.
+    /// \brief Calculates a minimum cut with \f$ source \f$ on the
+    /// sink-side (i.e. a set \f$ X\subsetneq V \f$ with \f$ source \notin X
+    /// \f$ and minimal out-degree).
     void calculateIn() {
       for (NodeIt it(*_graph); it != INVALID; ++it) {
         if (it != _source) {
@@ -564,21 +572,22 @@
       }
     }
 
-    /// \brief Calculates the minimum cut with the \c source node
-    /// in the \f$ V_{in} \f$.
+    /// \brief Calculates a minimum cut with \f$ source \f$ on the
+    /// sink-side.
     ///
-    /// Calculates the minimum cut with the \c source node
-    /// in the \f$ V_{in} \f$. The \c target is the initial target
-    /// for the push-relabel algorithm.
+    /// \brief Calculates a minimum cut with \f$ source \f$ on the
+    /// sink-side (i.e. a set \f$ X\subsetneq V \f$ with \f$ source \notin
+    /// X \f$ and minimal out-degree).  The \c target is the initial
+    /// target for the push-relabel algorithm.
     void calculateIn(const Node& target) {
       findMinCut(target, false, *_in_res_graph, *_in_current_edge);
     }
 
     /// \brief Runs the algorithm.
     ///
-    /// Runs the algorithm. It finds a proper \c source and \c target
-    /// and then calls the \ref init(), \ref calculateOut() and \ref
-    /// calculateIn().
+    /// Runs the algorithm. It finds nodes \c source and \c target
+    /// arbitrarily and then calls \ref init(), \ref calculateOut()
+    /// and \ref calculateIn().
     void run() {
       init();
       for (NodeIt it(*_graph); it != INVALID; ++it) {
@@ -592,8 +601,9 @@
 
     /// \brief Runs the algorithm.
     ///
-    /// Runs the algorithm. It finds a proper \c target and then calls
-    /// the \ref init(), \ref calculateOut() and \ref calculateIn().
+    /// Runs the algorithm. It uses the given \c source node, finds a
+    /// proper \c target and then calls the \ref init(), \ref
+    /// calculateOut() and \ref calculateIn().
     void run(const Node& s) {
       init(s);
       for (NodeIt it(*_graph); it != INVALID; ++it) {
@@ -633,12 +643,13 @@
     }
 
 
-    /// \brief Returns a minimum value cut.
+    /// \brief Returns a minimum cut.
     ///
     /// Sets \c nodeMap to the characteristic vector of a minimum
-    /// value cut. The nodes in \f$ V_{out} \f$ will be set true and
-    /// the nodes in \f$ V_{in} \f$ will be set false. 
-    /// \pre nodeMap should be a bool-valued node-map.
+    /// value cut: it will give a nonempty set \f$ X\subsetneq V \f$
+    /// with minimal out-degree (i.e. \c nodeMap will be true exactly
+    /// for the nodes of \f$ X \f$.  \pre nodeMap should be a
+    /// bool-valued node-map.
     template <typename NodeMap>
     Value minCut(NodeMap& nodeMap) const {
       for (NodeIt it(*_graph); it != INVALID; ++it) {