Ticket #7601: trac_7601.patch

sage/graphs/graph.py

@@ -3254 +3254 @@
             v = pv
         return B, C
 
+    def edge_connectivity(self,value_only=True,use_edge_labels=True, vertices=False):
+        r"""
+        Returns the edge connectivity of the graph
+        ( cf. http://en.wikipedia.org/wiki/Connectivity_(graph_theory) )
+    
+        INPUT:
+    
+
+        - ``value_only`` (boolean) --
+            - When set to ``True`` ( default ), only the value is returned.
+            - When set to ``False`` , both the value and a minimum edge cut
+              are returned.
+
+        - ``use_edge_labels`` (boolean) 
+            
+            - 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 ) 
+
+            - when set to ``False``, each edge has weight `1`. 
+
+        - ``vertices`` (boolean)
+
+            - When set to ``True``, also returns the two sets of
+              vertices that are disconnected by the cut. Implies
+              ``value_only=False``.
+            
+            The default value of this parameter is ``False``.
+    
+        EXAMPLE:
+
+        A basic application on the PappusGraph()
+        
+           sage: g = graphs.PappusGraph()
+           sage: g.edge_connectivity() # optional - requires Glpk or COIN-OR/CBC
+           3.0
+
+        The edge connectivity of a complete graph ( and of a random graph )
+        is its minimum degree, and one of the two parts of the bipartition
+        is reduced to only one vertex. The cutedges isomorphic to a
+        Star graph ::
+
+           sage: g = graphs.CompleteGraph(5)
+           sage: [ value, edges, [ setA, setB ]] = g.edge_connectivity(vertices=True) # optional - requires Glpk or COIN-OR/CBC
+           sage: print value                                                          # optional - requires Glpk or COIN-OR/CBC
+           4.0
+           sage: len(setA) == 1 or len(setB) == 1                                     # optional - requires Glpk or COIN-OR/CBC
+           True
+           sage: cut = Graph()
+           sage: cut.add_edges(edges)                                                 # optional - requires Glpk or COIN-OR/CBC
+           sage: cut.is_isomorphic(graphs.StarGraph(4))                               # optional - requires Glpk or COIN-OR/CBC
+           True
+
+        Even if obviously in any graph we know that the edge connectivity
+        is less than the minimum degree of the graph::
+
+           sage: g = graphs.RandomGNP(10,.3)
+           sage: min(g.degree()) >= g.edge_connectivity()                             # optional - requires Glpk or COIN-OR/CBC
+           True
+
+        If we build a tree then assign to its edges a random value, the 
+        minimum cut will be the edge with minimum value::
+
+           sage: g = graphs.RandomGNP(15,.5)
+           sage: tree = Graph()
+           sage: tree.add_edges(g.min_spanning_tree())
+           sage: for u,v in tree.edge_iterator(labels=None):
+           ...        tree.set_edge_label(u,v,random())
+           sage: minimum = min([l for u,v,l in tree.edge_iterator()])                 # optional - requires Glpk or COIN-OR/CBC
+           sage: [value, [(u,v,l)]] = tree.edge_connectivity(value_only=False)        # optional - requires Glpk or COIN-OR/CBC
+           sage: l == minimum                                                         # optional - requires Glpk or COIN-OR/CBC
+           True
+        """
+        g=self
+
+        if vertices:
+            value_only=False
+        
+        if use_edge_labels: 
+            weight=lambda x: 1 if x==None else x 
+        else: 
+            weight=lambda x: 1 
+
+        if g.is_directed():
+            reorder_edge = lambda x,y : (x,y)
+        else:
+            reorder_edge = lambda x,y : (x,y) if x<= y else (y,x)    
+
+        from sage.numerical.mip import MixedIntegerLinearProgram
+
+        p = MixedIntegerLinearProgram(maximization=False)
+
+        in_set = p.new_variable(dim=2)
+        in_cut = p.new_variable(dim=1)
+
+
+        # A vertex has to be in some set
+        for v in g:
+            p.add_constraint(in_set[0][v]+in_set[1][v],max=1,min=1)
+
+        # There is no empty set
+        p.add_constraint(sum([in_set[1][v] for v in g]),min=1)
+        p.add_constraint(sum([in_set[0][v] for v in g]),min=1)
+
+        if g.is_directed():
+            # There is no edge from set 0 to set 1 which
+            # is not in the cut
+            for (u,v) in g.edge_iterator(labels=None):
+                p.add_constraint(in_set[0][u] + in_set[1][v] - in_cut[(u,v)], max = 1)
+        else:
+
+            # Two adjacent vertices are in different sets if and only if
+            # the edge between them is in the cut
+    
+            for (u,v) in g.edge_iterator(labels=None):
+                p.add_constraint(in_set[0][u]+in_set[1][v]-in_cut[reorder_edge(u,v)],max=1)
+                p.add_constraint(in_set[1][u]+in_set[0][v]-in_cut[reorder_edge(u,v)],max=1)
+
+    
+        p.set_binary(in_set)
+        p.set_binary(in_cut)
+
+        p.set_objective(sum([weight(l ) * in_cut[reorder_edge(u,v)] for (u,v,l ) in g.edge_iterator()]))
+
+        if value_only:
+            return p.solve(objective_only=True)
+        else:
+            val = [p.solve()]
+
+            in_cut = p.get_values(in_cut)
+            in_set = p.get_values(in_set)
+
+            edges = []
+            for (u,v,l) in g.edge_iterator():
+                if in_cut[reorder_edge(u,v)] == 1:
+                    edges.append((u,v,l))
+                    
+            val.append(edges)
+            
+            if vertices:
+                a = []
+                b = []
+                for v in g:
+                    if in_set[0][v] == 1:
+                        a.append(v)
+                    else:
+                        b.append(v)
+                val.append([a,b])
+
+            return val
+
     ### Vertex handlers
 
     def add_vertex(self, name=None):