Merge c4cd144 into 715c03b

doc/source/reference/algorithms.flow.rst

@@ -4,28 +4,48 @@ Flows
 
 .. automodule:: networkx.algorithms.flow
 
+
+Maximum Flow
+------------
+.. autosummary::
+   :toctree: generated/
+
+   maximum_flow
+   maximum_flow_value
+   minimum_cut
+   minimum_cut_value
+
+
+Edmonds-Karp
+------------
+.. autosummary::
+   :toctree: generated/
+
+   edmonds_karp
+
+
 Ford-Fulkerson
 --------------
 .. autosummary::
    :toctree: generated/
 
-   max_flow
-   min_cut
    ford_fulkerson
-   ford_fulkerson_flow
-   ford_fulkerson_flow_and_auxiliary
+
+
+Shortest Augmenting Path
+------------------------
+.. autosummary::
+   :toctree: generated/
+
    shortest_augmenting_path
-   shortest_augmenting_path_value
-   shortest_augmenting_path_flow
+
 
 Preflow-Push
 ------------
 .. autosummary::
    :toctree: generated/
 
    preflow_push
-   preflow_push_value
-   preflow_push_flow
 
 Network Simplex
 ---------------

networkx/algorithms/__init__.py

@@ -51,5 +51,5 @@
 import networkx.algorithms.tree 
 
 from networkx.algorithms.bipartite import projected_graph,project,is_bipartite
-from networkx.algorithms.isomorphism import is_isomorphic,could_be_isomorphic,\
-    fast_could_be_isomorphic,faster_could_be_isomorphic
+from networkx.algorithms.isomorphism import (is_isomorphic,could_be_isomorphic,
+    fast_could_be_isomorphic, faster_could_be_isomorphic)

networkx/algorithms/connectivity/connectivity.py

@@ -201,7 +201,7 @@ def local_node_connectivity(G, s, t, aux_digraph=None, mapping=None):
         H, mapping = _aux_digraph_node_connectivity(G)
     else:
         H = aux_digraph
-    return nx.max_flow(H,'%sB' % mapping[s], '%sA' % mapping[t])
+    return nx.maximum_flow_value(H,'%sB' % mapping[s], '%sA' % mapping[t])
 
 def node_connectivity(G, s=None, t=None):
     r"""Returns node connectivity for a graph or digraph G.
@@ -460,7 +460,7 @@ def local_edge_connectivity(G, u, v, aux_digraph=None):
         H = _aux_digraph_edge_connectivity(G)
     else:
         H = aux_digraph
-    return nx.max_flow(H, u, v)
+    return nx.maximum_flow_value(H, u, v)
 
 def edge_connectivity(G, s=None, t=None):
     r"""Returns the edge connectivity of the graph or digraph G.

networkx/algorithms/connectivity/cuts.py

@@ -68,11 +68,11 @@ def minimum_st_edge_cut(G, s, t, capacity='capacity'):
     >>> G.add_edge('e','y', capacity = 3.0)
     >>> sorted(nx.minimum_edge_cut(G, 'x', 'y'))
     [('c', 'y'), ('x', 'b')]
-    >>> nx.min_cut(G, 'x', 'y')
+    >>> nx.minimum_cut_value(G, 'x', 'y')
     3.0
     """
     try:
-        flow, H = nx.ford_fulkerson_flow_and_auxiliary(G, s, t, capacity=capacity)
+        H = nx.ford_fulkerson(G, s, t, capacity=capacity)
         cutset = set()
         # Compute reachable nodes from source in the residual network
         reachable = set(nx.single_source_shortest_path(H,s))

networkx/algorithms/flow/__init__.py

@@ -1,12 +1,21 @@
-from . import maxflow, mincost, capacity_scaling, network_simplex, preflow_push, shortest_augmenting_path
+from . import (maxflow, mincost, edmonds_karp, ford_fulkerson, preflow_push,
+    shortest_augmenting_path, capacity_scaling, network_simplex)
 
-__all__ = sum([maxflow.__all__, mincost.__all__, capacity_scaling.__all__,
-               network_simplex.__all__, preflow_push.__all__,
-               shortest_augmenting_path.__all__], [])
+__all__ = sum([maxflow.__all__,
+                mincost.__all__,
+                edmonds_karp.__all__,
+                ford_fulkerson.__all__,
+                preflow_push.__all__,
+                shortest_augmenting_path.__all__,
+                capacity_scaling.__all__,
+                network_simplex.__all__,
+            ], [])
 
 from .maxflow import *
 from .mincost import *
-from .capacity_scaling import *
-from .network_simplex import *
+from .edmonds_karp import *
+from .ford_fulkerson import *
 from .preflow_push import *
 from .shortest_augmenting_path import *
+from .capacity_scaling import *
+from .network_simplex import *

networkx/algorithms/flow/edmonds_karp.py

@@ -0,0 +1,218 @@
+# -*- coding: utf-8 -*-
+"""
+Edmonds-Karp algorithm for maximum flow problems.
+"""
+
+__author__ = """ysitu <ysitu@users.noreply.github.com>"""
+# Copyright (C) 2014 ysitu <ysitu@users.noreply.github.com>
+# All rights reserved.
+# BSD license.
+
+import networkx as nx
+from networkx.algorithms.flow.utils import *
+
+__all__ = ['edmonds_karp']
+
+
+def edmonds_karp_core(R, s, t, cutoff):
+    """Implementation of the Edmonds-Karp algorithm.
+    """
+    R_node = R.node
+    R_pred = R.pred
+    R_succ = R.succ
+
+    inf = float('inf')
+    def augment(path):
+        """Augment flow along a path from s to t.
+        """
+        # Determine the path residual capacity.
+        flow = inf
+        it = iter(path)
+        u = next(it)
+        for v in it:
+            attr = R_succ[u][v]
+            flow = min(flow, attr['capacity'] - attr['flow'])
+            u = v
+        # Augment flow along the path.
+        it = iter(path)
+        u = next(it)
+        for v in it:
+            R_succ[u][v]['flow'] += flow
+            R_succ[v][u]['flow'] -= flow
+            u = v
+        return flow
+
+    def bidirectional_bfs():
+        """Bidirectional breadth-first search for an augmenting path.
+        """
+        pred = {s: None}
+        q_s = [s]
+        succ = {t: None}
+        q_t = [t]
+        while True:
+            q = []
+            if len(q_s) <= len(q_t):
+                for u in q_s:
+                    for v, attr in R_succ[u].items():
+                        if v not in pred and attr['flow'] < attr['capacity']:
+                            pred[v] = u
+                            if v in succ:
+                                return v, pred, succ
+                            q.append(v)
+                if not q:
+                    return None, None, None
+                q_s = q
+            else:
+                for u in q_t:
+                    for v, attr in R_pred[u].items():
+                        if v not in succ and attr['flow'] < attr['capacity']:
+                            succ[v] = u
+                            if v in pred:
+                                return v, pred, succ
+                            q.append(v)
+                if not q:
+                    return None, None, None
+                q_t = q
+
+    # Look for shortest augmenting paths using breadth-first search.
+    flow_value = 0
+    while True:
+        v, pred, succ = bidirectional_bfs()
+        if pred is None:
+            break
+        path = [v]
+        # Trace a path from s to v.
+        u = v
+        while u != s:
+            u = pred[u]
+            path.append(u)
+        path.reverse()
+        # Trace a path from v to t.
+        u = v
+        while u != t:
+            u = succ[u]
+            path.append(u)
+        flow_value += augment(path)
+
+    return flow_value
+
+
+def edmonds_karp_impl(G, s, t, capacity, cutoff):
+    """Implementation of the Edmonds-Karp algorithm.
+    """
+    R = build_residual_network(G, s, t, capacity)
+
+    if cutoff is None:
+        cutoff = float('inf')
+    R.graph['flow_value'] = edmonds_karp_core(R, s, t, cutoff)
+
+    return R
+
+
+def edmonds_karp(G, s, t, capacity='capacity', value_only=False, cutoff=None):
+    """Find a maximum single-commodity flow using the Edmonds-Karp algorithm.
+
+    This function returns the residual network resulting after computing
+    the maximum flow. See below for details about the conventions
+    NetworkX uses for defining residual networks.
+
+    This algorithm has a running time of `O(n m^2)` for `n` nodes and `m`
+    edges.
+
+
+    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.
+
+    t : node
+        Sink node for the flow.
+
+    capacity : string
+        Edges of the graph G are expected to have an attribute capacity
+        that indicates how much flow the edge can support. If this
+        attribute is not present, the edge is considered to have
+        infinite capacity. Default value: 'capacity'.
+
+    value_only : bool
+        If True compute only the value of the maximum flow. This parameter
+        will be ignored by this algorithm because it is not applicable.
+
+    cutoff : integer, float
+        If specified, the algorithm will terminate when the flow value reaches
+        or exceeds the cutoff. In this case, it may be unable to immediately
+        determine a minimum cut. Default value: None.
+
+    Returns
+    -------
+    R : NetworkX DiGraph
+        Residual network after computing the maximum flow.
+
+    Raises
+    ------
+    NetworkXError
+        The algorithm does not support MultiGraph and MultiDiGraph. If
+        the input graph is an instance of one of these two classes, a
+        NetworkXError is raised.
+
+    NetworkXUnbounded
+        If the graph has a path of infinite capacity, the value of a
+        feasible flow on the graph is unbounded above and the function
+        raises a NetworkXUnbounded.
+
+    See also
+    --------
+    :meth:`maximum_flow`
+    :meth:`minimum_cut`
+    :meth:`ford_fulkerson`
+    :meth:`preflow_push`
+    :meth:`shortest_augmenting_path`
+
+    Notes
+    -----
+    The residual network :samp:`R` from an input graph :samp:`G` has the
+    same nodes as :samp:`G`. :samp:`R` is a DiGraph that contains a pair
+    of edges :samp:`(u, v)` and :samp:`(v, u)` iff :samp:`(u, v)` is not a
+    self-loop, and at least one of :samp:`(u, v)` and :samp:`(v, u)` exists
+    in :samp:`G`.
+
+    For each edge :samp:`(u, v)` in :samp:`R`, :samp:`R[u][v]['capacity']`
+    is equal to the capacity of :samp:`(u, v)` in :samp:`G` if it exists
+    in :samp:`G` or zero otherwise. If the capacity is infinite,
+    :samp:`R[u][v]['capacity']` will have a high arbitrary finite value
+    that does not affect the solution of the problem. This value is stored in
+    :samp:`R.graph['inf']`. For each edge :samp:`(u, v)` in :samp:`R`,
+    :samp:`R[u][v]['flow']` represents the flow function of :samp:`(u, v)` and
+    satisfies :samp:`R[u][v]['flow'] == -R[v][u]['flow']`.
+
+    The flow value, defined as the total flow into :samp:`t`, the sink, is
+    stored in :samp:`R.graph['flow_value']`.
+
+    Examples
+    --------
+    >>> import networkx as nx
+    >>> G = nx.DiGraph()
+    >>> G.add_edge('x','a', capacity=3.0)
+    >>> G.add_edge('x','b', capacity=1.0)
+    >>> G.add_edge('a','c', capacity=3.0)
+    >>> G.add_edge('b','c', capacity=5.0)
+    >>> G.add_edge('b','d', capacity=4.0)
+    >>> G.add_edge('d','e', capacity=2.0)
+    >>> G.add_edge('c','y', capacity=2.0)
+    >>> G.add_edge('e','y', capacity=3.0)
+    >>> R = nx.edmonds_karp(G, 'x', 'y')
+    >>> flow_value = nx.maximum_flow_value(G, 'x', 'y')
+    >>> flow_value
+    3.0
+    >>> flow_value == R.graph['flow_value']
+    True
+
+    """
+    R = edmonds_karp_impl(G, s, t, capacity, cutoff)
+    R.graph['algorithm'] = 'edmonds_karp'
+    return R