# 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

b

class GenericGraph(GenericGraph_pyx): 
3028  3028  represented by a list of edges. 
3029  3029  
3030  3030  A minimum edge cut between two vertices `s` and `t` of self 
3031   is a set `U` of edges of minimum weight such that the graph 
3032   obtained by removing `U` from self is disconnected. 
 3031  is a set `A` of edges of minimum weight such that the graph 
 3032  obtained by removing `A` from self is disconnected. 
3033  3033  ( cf. http://en.wikipedia.org/wiki/Cut_%28graph_theory%29 ) 
3034  3034  
3035  3035  INPUT: 
3036  3036  
3037    ``s``  source vertex 
3038    ``t``  sink vertex 
3039    ``value_only``  boolean (default: True). When set to 
 3037   ``s``  source vertex 
 3038   ``t``  sink vertex 
 3039   ``value_only``  boolean (default: True). When set to 
3040  3040  True, only the weight of a minimum cut is returned. 
3041  3041  Otherwise, a list of edges of a minimum cut is also returned. 
3042    ``use_edge_labels``  boolean (default: False). When set to 
 3042   ``use_edge_labels``  boolean (default: False). When set to 
3043  3043  True, computes a weighted minimum cut where each edge has 
3044  3044  a weight defined by its label (if an edge has no label, `1` 
3045  3045  is assumed). Otherwise, each edge has weight `1`. 
3046    ``vertices``  boolean (default: False). When set to True, 
 3046   ``vertices``  boolean (default: False). When set to True, 
3047  3047  also returns the two sets of vertices that are disconnected by 
3048  3048  the cut. Implies ``value_only=False``. 
3049  3049  
3050  3050  OUTPUT: 
3051  3051  
3052   real number or tuple, depending on the arguments given 
 3052  real number or tuple, depending on the given arguments 
3053  3053  (examples are given below) 
3054  3054  
3055  3055  EXAMPLES: 
… 
… 
class GenericGraph(GenericGraph_pyx): 
3077  3077  
3078  3078  The two sides of the edge cut are obviously shorter paths:: 
3079  3079  
3080   sage: value,edges,[set1,set2] = g.edge_cut(0, 14, use_edge_labels=True, vertices=True) # optional  requires Glpk or COINOR/CBC 
3081   sage: g.subgraph(set1).is_isomorphic(graphs.PathGraph(len(set1))) # optional  requires Glpk or COINOR/CBC 
3082   True 
3083   sage: g.subgraph(set2).is_isomorphic(graphs.PathGraph(len(set2))) # optional  requires Glpk or COINOR/CBC 
3084   True 
3085   sage: len(set1) + len(set2) == g.order() # optional  requires Glpk or COINOR/CBC 
 3080  sage: value,edges,[set1,set2] = g.edge_cut(0, 14, use_edge_labels=True, vertices=True) # optional  requires GLPK or COINOR/CBC 
 3081  sage: g.subgraph(set1).is_isomorphic(graphs.PathGraph(len(set1))) # optional  requires GLPK or COINOR/CBC 
 3082  True 
 3083  sage: g.subgraph(set2).is_isomorphic(graphs.PathGraph(len(set2))) # optional  requires GLPK or COINOR/CBC 
 3084  True 
 3085  sage: len(set1) + len(set2) == g.order() # optional  requires GLPK or COINOR/CBC 
3086  3086  True 
3087  3087  """ 
3088  3088  from sage.numerical.mip import MixedIntegerLinearProgram 
… 
… 
class GenericGraph(GenericGraph_pyx): 
3160  3160  
3161  3161  INPUT: 
3162  3162  
3163    ``value_only``  boolean (default: True). When set to 
 3163   ``value_only``  boolean (default: True). When set to 
3164  3164  True, only the size of the minimum cut is returned 
3165    ``vertices``  boolean (default: False). When set to 
 3165   ``vertices``  boolean (default: False). When set to 
3166  3166  True, also returns the two sets of vertices that 
3167  3167  are disconnected by the cut. Implies ``value_only`` 
3168  3168  set to False. 
3169  3169  
3170  3170  OUTPUT: 
3171  3171  
3172   real number or tuple, depending on the arguments given 
 3172  real number or tuple, depending on the given arguments 
3173  3173  (examples are given below) 
3174  3174  
3175  3175  EXAMPLE: 
3176  3176  
3177   A basic application in a Pappus graph:: 
 3177  A basic application in the Pappus graph:: 
3178  3178  
3179  3179  sage: g = graphs.PappusGraph() 
3180   sage: g.vertex_cut(1, 16, value_only=True) # optional  requires Glpk or COINOR/CBC 
 3180  sage: g.vertex_cut(1, 16, value_only=True) # optional  requires GLPK or COINOR/CBC 
3181  3181  3.0 
3182  3182  
3183  3183  In the bipartite complete graph `K_{2,8}`, a cut between the two 
3184  3184  vertices in the size `2` part consists of the other `8` vertices:: 
3185  3185  
3186  3186  sage: g = graphs.CompleteBipartiteGraph(2, 8) 
3187   sage: [value, vertices] = g.vertex_cut(0, 1, value_only=False) # optional  requires Glpk or COINOR/CBC 
3188   sage: print value # optional  requires Glpk or COINOR/CBC 
 3187  sage: [value, vertices] = g.vertex_cut(0, 1, value_only=False) # optional  requires GLPK or COINOR/CBC 
 3188  sage: print value # optional  requires GLPK or COINOR/CBC 
3189  3189  8.0 
3190   sage: vertices == range(2,10) # optional  requires Glpk or COINOR/CBC 
 3190  sage: vertices == range(2,10) # optional  requires GLPK or COINOR/CBC 
3191  3191  True 
3192  3192  
3193  3193  Clearly, in this case the two sides of the cut are singletons :: 
3194  3194  
3195   sage: [value, vertices, [set1, set2]] = g.vertex_cut(0,1, vertices=True) # optional  requires Glpk or COINOR/CBC 
3196   sage: len(set1) == 1 # optional  requires Glpk or COINOR/CBC 
3197   True 
3198   sage: len(set2) == 1 # optional  requires Glpk or COINOR/CBC 
 3195  sage: [value, vertices, [set1, set2]] = g.vertex_cut(0,1, vertices=True) # optional  requires GLPK or COINOR/CBC 
 3196  sage: len(set1) == 1 # optional  requires GLPK or COINOR/CBC 
 3197  True 
 3198  sage: len(set2) == 1 # optional  requires GLPK or COINOR/CBC 
3199  3199  True 
3200  3200  """ 
3201  3201  from sage.numerical.mip import MixedIntegerLinearProgram 
… 
… 
class GenericGraph(GenericGraph_pyx): 
3264  3264  by a list of vertices. 
3265  3265  
3266  3266  A minimum vertex cover of a graph is a set `S` of 
3267   its vertices such that each edge is incident to at least 
 3267  vertices such that each edge is incident to at least 
3268  3268  one element of `S`, and such that `S` is of minimum 
3269  3269  cardinality. 
3270  3270  ( cf. http://en.wikipedia.org/wiki/Vertex_cover ) 
diff git a/sage/graphs/graph.py b/sage/graphs/graph.py
a

b

class Graph(GenericGraph): 
2737  2737  
2738  2738  def _gomory_hu_tree(self, vertices=None): 
2739  2739  r""" 
2740   Returns the GomoryHu tree associated to self (private function) 
 2740  Returns a GomoryHu tree associated to self. 
2741  2741  
2742   This function is the privatre counterpart of ``gomory_hu_tree``, 
2743   with the difference that it accepts an optional argument 
 2742  This function is the private counterpart of ``gomory_hu_tree()``, 
 2743  with the difference that it has an optional argument 
2744  2744  needed for recursive computations, which the user is not 
2745   interested in defining by himself. 
 2745  interested in defining himself. 
2746  2746  
2747   See the documentation of ``gomory_hu_tree`` for more information. 
 2747  See the documentation of ``gomory_hu_tree()`` for more information. 
2748  2748  
2749  2749  INPUT: 
2750  2750  
2751    ``vertices``  a set of ''real'' vertices, as opposed to the 
 2751   ``vertices``  a set of "real" vertices, as opposed to the 
2752  2752  fakes one introduced during the computations. This variable is 
2753   useful for the algorithm, and I see no reason for the user to 
2754   change it. 
 2753  useful for the algorithm and for recursion purposes. 
2755  2754  
2756  2755  EXAMPLE: 
2757  2756  
2758   This function is actually tested in ``gomory_hu_tree``, this 
2759   example is only present to have a doctest coverage of 100% 
 2757  This function is actually tested in ``gomory_hu_tree()``, this 
 2758  example is only present to have a doctest coverage of 100%. 
2760  2759  
2761  2760  sage: g = graphs.PetersenGraph() 
2762  2761  sage: t = g._gomory_hu_tree() # optional  requires GLPK or CBC 
2763   
2764  2762  """ 
2765  2763  from sage.sets.set import Set 
2766  2764  
… 
… 
class Graph(GenericGraph): 
2800  2798  # Take any two vertices 
2801  2799  u,v = vertices[0:2] 
2802  2800  
2803   # flow = connectivity between u and v 
2804   # edges = min cut 
2805   # sets1, sets2 = the two sides of the edge cut 
 2801  # Recovers the following values 
 2802  # flow is the connectivity between u and v 
 2803  # edges of a min cut 
 2804  # sets1, sets2 are the two sides of the edge cut 
2806  2805  flow,edges,[set1,set2] = self.edge_cut(u, v, use_edge_labels=True, vertices=True) 
2807  2806  
2808  2807  # One graph for each part of the previous one 
… 
… 
class Graph(GenericGraph): 
2856  2855  
2857  2856  def gomory_hu_tree(self): 
2858  2857  r""" 
2859   Returns the GomoryHu tree associated to self. 
 2858  Returns a GomoryHu tree of self. 
2860  2859  
2861   Given a tree `T` with labelled edges representing capacities, it is very 
 2860  Given a tree `T` with labeled edges representing capacities, it is very 
2862  2861  easy to determine the maximal flow between any pair of vertices : 
2863  2862  it is the minimal label on the edges of the unique path between them. 
2864  2863  
2865   Given a graph `G`, the GomoryHu tree `T` of `G`, is a tree 
 2864  Given a graph `G`, a GomoryHu tree `T` of `G` is a tree 
2866  2865  with the same set of vertices, and such that the maximal flow 
2867   between any two vertices is the same in `G` and in `T`. 
 2866  between any two vertices is the same in `G` as in `T`. 
2868  2867  (see http://en.wikipedia.org/wiki/Gomory%E2%80%93Hu_tree) 
 2868  Note that, in general, a graph admits more than one GomoryHu 
 2869  tree. 
2869  2870  
2870  2871  OUTPUT: 
2871  2872  
… 
… 
class Graph(GenericGraph): 
2897  2898  sage: all([ t.flow(u,v) == g.flow(u,v) for u,v in Subsets( g.vertices(), 2 ) ]) # optional  requires GLPK or CBC 
2898  2899  True 
2899  2900  
2900   Just to make sure, let's check the same is true for two vertices 
 2901  Just to make sure, we can check that the same is true for two vertices 
2901  2902  in a random graph:: 
2902  2903  
2903  2904  sage: g = graphs.RandomGNP(20,.3) 