# HG changeset patch
# User Alexandre Blondin Masse < alexandre.blondin.masse at gmail.com>
# Date 1268436328 3600
# Node ID 68925297a11a25f476055d3d6fb2dee8af169286
# Parent b0881d4b8428102cd7e0aa8238061f2cae119666
#7288 Minor doc and comments fixes
diff git a/sage/graphs/generic_graph.py b/sage/graphs/generic_graph.py
 a/sage/graphs/generic_graph.py
+++ b/sage/graphs/generic_graph.py
@@ 3028,28 +3028,28 @@ class GenericGraph(GenericGraph_pyx):
represented by a list of edges.
A minimum edge cut between two vertices `s` and `t` of self
 is a set `U` of edges of minimum weight such that the graph
 obtained by removing `U` from self is disconnected.
+ is a set `A` of edges of minimum weight such that the graph
+ obtained by removing `A` from self is disconnected.
( cf. http://en.wikipedia.org/wiki/Cut_%28graph_theory%29 )
INPUT:
  ``s``  source vertex
  ``t``  sink vertex
  ``value_only``  boolean (default: True). When set to
+  ``s``  source vertex
+  ``t``  sink vertex
+  ``value_only``  boolean (default: True). When set to
True, only the weight of a minimum cut is returned.
Otherwise, a list of edges of a minimum cut is also returned.
  ``use_edge_labels``  boolean (default: False). When set to
+  ``use_edge_labels``  boolean (default: False). When set to
True, computes a weighted minimum cut where each edge has
a weight defined by its label (if an edge has no label, `1`
is assumed). Otherwise, each edge has weight `1`.
  ``vertices``  boolean (default: False). When set to True,
+  ``vertices``  boolean (default: False). When set to True,
also returns the two sets of vertices that are disconnected by
the cut. Implies ``value_only=False``.
OUTPUT:
 real number or tuple, depending on the arguments given
+ real number or tuple, depending on the given arguments
(examples are given below)
EXAMPLES:
@@ 3077,12 +3077,12 @@ class GenericGraph(GenericGraph_pyx):
The two sides of the edge cut are obviously shorter paths::
 sage: value,edges,[set1,set2] = g.edge_cut(0, 14, use_edge_labels=True, vertices=True) # optional  requires Glpk or COINOR/CBC
 sage: g.subgraph(set1).is_isomorphic(graphs.PathGraph(len(set1))) # optional  requires Glpk or COINOR/CBC
 True
 sage: g.subgraph(set2).is_isomorphic(graphs.PathGraph(len(set2))) # optional  requires Glpk or COINOR/CBC
 True
 sage: len(set1) + len(set2) == g.order() # optional  requires Glpk or COINOR/CBC
+ sage: value,edges,[set1,set2] = g.edge_cut(0, 14, use_edge_labels=True, vertices=True) # optional  requires GLPK or COINOR/CBC
+ sage: g.subgraph(set1).is_isomorphic(graphs.PathGraph(len(set1))) # optional  requires GLPK or COINOR/CBC
+ True
+ sage: g.subgraph(set2).is_isomorphic(graphs.PathGraph(len(set2))) # optional  requires GLPK or COINOR/CBC
+ True
+ sage: len(set1) + len(set2) == g.order() # optional  requires GLPK or COINOR/CBC
True
"""
from sage.numerical.mip import MixedIntegerLinearProgram
@@ 3160,42 +3160,42 @@ class GenericGraph(GenericGraph_pyx):
INPUT:
  ``value_only``  boolean (default: True). When set to
+  ``value_only``  boolean (default: True). When set to
True, only the size of the minimum cut is returned
  ``vertices``  boolean (default: False). When set to
+  ``vertices``  boolean (default: False). When set to
True, also returns the two sets of vertices that
are disconnected by the cut. Implies ``value_only``
set to False.
OUTPUT:
 real number or tuple, depending on the arguments given
+ real number or tuple, depending on the given arguments
(examples are given below)
EXAMPLE:
 A basic application in a Pappus graph::
+ A basic application in the Pappus graph::
sage: g = graphs.PappusGraph()
 sage: g.vertex_cut(1, 16, value_only=True) # optional  requires Glpk or COINOR/CBC
+ sage: g.vertex_cut(1, 16, value_only=True) # optional  requires GLPK or COINOR/CBC
3.0
In the bipartite complete graph `K_{2,8}`, a cut between the two
vertices in the size `2` part consists of the other `8` vertices::
sage: g = graphs.CompleteBipartiteGraph(2, 8)
 sage: [value, vertices] = g.vertex_cut(0, 1, value_only=False) # optional  requires Glpk or COINOR/CBC
 sage: print value # optional  requires Glpk or COINOR/CBC
+ sage: [value, vertices] = g.vertex_cut(0, 1, value_only=False) # optional  requires GLPK or COINOR/CBC
+ sage: print value # optional  requires GLPK or COINOR/CBC
8.0
 sage: vertices == range(2,10) # optional  requires Glpk or COINOR/CBC
+ sage: vertices == range(2,10) # optional  requires GLPK or COINOR/CBC
True
Clearly, in this case the two sides of the cut are singletons ::
 sage: [value, vertices, [set1, set2]] = g.vertex_cut(0,1, vertices=True) # optional  requires Glpk or COINOR/CBC
 sage: len(set1) == 1 # optional  requires Glpk or COINOR/CBC
 True
 sage: len(set2) == 1 # optional  requires Glpk or COINOR/CBC
+ sage: [value, vertices, [set1, set2]] = g.vertex_cut(0,1, vertices=True) # optional  requires GLPK or COINOR/CBC
+ sage: len(set1) == 1 # optional  requires GLPK or COINOR/CBC
+ True
+ sage: len(set2) == 1 # optional  requires GLPK or COINOR/CBC
True
"""
from sage.numerical.mip import MixedIntegerLinearProgram
@@ 3264,7 +3264,7 @@ class GenericGraph(GenericGraph_pyx):
by a list of vertices.
A minimum vertex cover of a graph is a set `S` of
 its vertices such that each edge is incident to at least
+ vertices such that each edge is incident to at least
one element of `S`, and such that `S` is of minimum
cardinality.
( cf. http://en.wikipedia.org/wiki/Vertex_cover )
diff git a/sage/graphs/graph.py b/sage/graphs/graph.py
 a/sage/graphs/graph.py
+++ b/sage/graphs/graph.py
@@ 2737,30 +2737,28 @@ class Graph(GenericGraph):
def _gomory_hu_tree(self, vertices=None):
r"""
 Returns the GomoryHu tree associated to self (private function)
+ Returns a GomoryHu tree associated to self.
 This function is the privatre counterpart of ``gomory_hu_tree``,
 with the difference that it accepts an optional argument
+ This function is the private counterpart of ``gomory_hu_tree()``,
+ with the difference that it has an optional argument
needed for recursive computations, which the user is not
 interested in defining by himself.
+ interested in defining himself.
 See the documentation of ``gomory_hu_tree`` for more information.
+ See the documentation of ``gomory_hu_tree()`` for more information.
INPUT:
  ``vertices``  a set of ''real'' vertices, as opposed to the
+  ``vertices``  a set of "real" vertices, as opposed to the
fakes one introduced during the computations. This variable is
 useful for the algorithm, and I see no reason for the user to
 change it.
+ useful for the algorithm and for recursion purposes.
EXAMPLE:
 This function is actually tested in ``gomory_hu_tree``, this
 example is only present to have a doctest coverage of 100%
+ This function is actually tested in ``gomory_hu_tree()``, this
+ example is only present to have a doctest coverage of 100%.
sage: g = graphs.PetersenGraph()
sage: t = g._gomory_hu_tree() # optional  requires GLPK or CBC

"""
from sage.sets.set import Set
@@ 2800,9 +2798,10 @@ class Graph(GenericGraph):
# Take any two vertices
u,v = vertices[0:2]
 # flow = connectivity between u and v
 # edges = min cut
 # sets1, sets2 = the two sides of the edge cut
+ # Recovers the following values
+ # flow is the connectivity between u and v
+ # edges of a min cut
+ # sets1, sets2 are the two sides of the edge cut
flow,edges,[set1,set2] = self.edge_cut(u, v, use_edge_labels=True, vertices=True)
# One graph for each part of the previous one
@@ 2856,16 +2855,18 @@ class Graph(GenericGraph):
def gomory_hu_tree(self):
r"""
 Returns the GomoryHu tree associated to self.
+ Returns a GomoryHu tree of self.
 Given a tree `T` with labelled edges representing capacities, it is very
+ Given a tree `T` with labeled edges representing capacities, it is very
easy to determine the maximal flow between any pair of vertices :
it is the minimal label on the edges of the unique path between them.
 Given a graph `G`, the GomoryHu tree `T` of `G`, is a tree
+ Given a graph `G`, a GomoryHu tree `T` of `G` is a tree
with the same set of vertices, and such that the maximal flow
 between any two vertices is the same in `G` and in `T`.
+ between any two vertices is the same in `G` as in `T`.
(see http://en.wikipedia.org/wiki/Gomory%E2%80%93Hu_tree)
+ Note that, in general, a graph admits more than one GomoryHu
+ tree.
OUTPUT:
@@ 2897,7 +2898,7 @@ class Graph(GenericGraph):
sage: all([ t.flow(u,v) == g.flow(u,v) for u,v in Subsets( g.vertices(), 2 ) ]) # optional  requires GLPK or CBC
True
 Just to make sure, let's check the same is true for two vertices
+ Just to make sure, we can check that the same is true for two vertices
in a random graph::
sage: g = graphs.RandomGNP(20,.3)