Repository: networkx/networkx

Issue:
Can't verify if minimum_st_node_cut actually works correctly or not
Hi. I've been trying to determine the affect capacity has on cuts in a DiGraph playing with different graph shapes and capacity values. Maybe I'm completely off base, but I've scoured the Internet for small graph min cut samples (from university courses) with examples but have yet to successfully cut the same nodes/edges.

My work is on another system, so I'll include a hand produced example in-line. The graph is based on the following, look under "Practice": http://www.mathcs.emory.edu/~cheung/Courses/323/Syllabus/NetFlow/max-flow-min-cut.html

```
import networkx as nx # NetworkX v1.10
...
G = nx.DiGraph()
G.add_edge("s", "a", capacity=8)
G.add_edge("s", "b", capacity=7)
G.add_edge("s", "c", capacity=4)

G.add_edge("a", "b", capacity=2)
G.add_edge("b", "c", capacity=5)

G.add_edge("a", "d", capacity=3)
G.add_edge("b", "e", capacity=6)
G.add_edge("c", "f", capacity=2)

G.add_edge("a", "e", capacity=9)
G.add_edge("c", "e", capacity=7)

G.add_edge("d", "t", capacity=9)
G.add_edge("e", "t", capacity=5)
G.add_edge("f", "t", capacity=8)

cut_nodes = nx.algorithms.connectivity.minimum_node_cut(G, "s", "t")
print "Cut nodes: " + str(cut_nodes)
# Always produces cuts for d, f, e

cut_edges = nx.algorithms.connectivity.minimum_edge_cut(G, "s", "t")
print "Cut edges: " + str(cut_edges)
# Always produces cuts for d->t, f->t, e->t
```

The Emory course explaination indicates that a->d, e->t, c->f should be the cut edges by capacity.

I've played with simplier graphs and the capacities never seem to affect the results.



Discussion:
I believe it is the minimum_cut function is the one you are looking for. Actually, using it produced the results you are expecting. Here is how I used it for your example.

```
cut_weight, partitions = nx.minimum_cut(G, "s", "t")
print "cut edges capacity " + str(cut_weight) # The total weigh of edge_cut
# Produces 10
print "Set of nodes in the 's' partition: " + str(partitions[0]) # Set of nodes in the partition containing s
# Produces ['a', 'c', 'b', 'e', 's']
print "Set of nodes in the 't' partition: " + str(partitions[1]) # Set of nodes in the partition containing t
# Produces (['d', 't', 'f'])
edge_cut_list = [] # edge_cut is simply the edges between both partitions computed by the following nested loop.
for p1_node in partitions[0]:
    for p2_node in partitions[1]:
        if G.has_edge(p1_node,p2_node):
            edge_cut_list.append((p1_node,p2_node))
print "Edges of the cut: " + str(edge_cut_list)
# Produces the expected result: [('a', 'd'), ('c', 'f'), ('e', 't')]
```

Thanks. I've been playing with this so much that I had a hard time producing an example that I could manually migrate into this post. In my original issue I used minimum_node_cut and minimum_edge_cut, but I get the same non-capacity results with minimum_node_st_cut and minimum_edge_st_cut. Why would I think of them as considernig capacity? From the minimum_edge_st_cut documentation(https://networkx.github.io/documentation/latest/_modules/networkx/algorithms/connectivity/cuts.html#minimum_st_node_cut):

 "G : NetworkX graph Edges of the graph are expected to have an attribute called 'capacity'. If this attribute is not present, the edge is considered to have infinite capacity."

I see now that minimum_edge_cut, minimum_node_cut and minimum_node_st_cut are all clear about cardinality, but the above documentation note confused me. I was originally looking at minimum_cut only, but the convenience of the node and edge cuts from the other methods lured me in their direction.

BTW, I've played with minimum_cut this morning and the results look reasonable. I came up with a bit of logic to determine the cut nodes, however and thought there would be a better way to do it. (instead of looking at each node for each cut edge to determine if node 1 or 2 is the source or target and add the appropriate node to a cut set) 

The use of an aux and residual network with minimum_cut doesn't respect capacity. e.g. it looks like if you simply call minimum_cut with a build_auxiliary_edge_connectivity with/without a residual network, the returned partitions do not reflect the capacity weigthing.

Is this correct?

cut_weight, partitions = nx.algorithms.connectivity.minimum_cut(G, "s", "t")

H = nx.algorithms.connectivity.build_auxiliary_edge_connectivity(G)
R = nx.algorithms.flow.build_residual_network(H, "capacity")
cut_weight, partitions = nx.algorithms.connectivity.minimum_cut(G, "s", "t", residual=R)

Simply having the aux and residual networks present seems to break support for capacity. Maybe I'm using them wrong or don't understand how its supposed to be used.

I am not really familiar with auxillary, and residual network so my response might be late for that. But when I figure something out I shall let you as soon as I can.

I've noticed that sometimes the function **minimum_edge_cut( digraphA)** return a empty **set([])** in my examples. So would be glad to know if you guys know is this correct ? For a weakly connected DiGraph more than 2 nodes, an edge cut should always exist. So may be the minimum_edge_cut should never return an empty set().


Resolving patch:
diff --git a/networkx/algorithms/connectivity/cuts.py b/networkx/algorithms/connectivity/cuts.py
--- a/networkx/algorithms/connectivity/cuts.py
+++ b/networkx/algorithms/connectivity/cuts.py
@@ -28,14 +28,12 @@ def minimum_st_edge_cut(G, s, t, flow_func=None, auxiliary=None,
 
     This function returns the set of edges of minimum cardinality that,
     if removed, would destroy all paths among source and target in G.
-    Edge weights are not considered
+    Edge weights are not considered. See :meth:`minimum_cut` for
+    computing minimum cuts considering edge weights.
 
     Parameters
     ----------
     G : NetworkX graph
-        Edges of the graph are expected to have an attribute called
-        'capacity'. If this attribute is not present, the edge is
-        considered to have infinite capacity.
 
     s : node
         Source node for the flow.


Test patch: