[ENH] Added functions for k-edge-connected components/subgraphs (netw…

…orkx#2554)

* Initial commit of k-edge-ccs and subgraphs

Added implementation of k-edge-ccs
Added implementation of k-edge-subgraphs
Added tests for both local-cc and subgraph versions.
Added assert to test to verify their difference.

* imported appropriate utils and switched to random_powerlaw_tree_sequence

* Sped up tests. Added new directed and five clique test case

* Fixed docstrings and __init__

Added SeeAlso docstring and added algorithms to toplevel __init__
Fixed author and cleaned docstrings. Removed profiling code.
Fixed spelling error.
Registerd module for doc autogeneration.
Updated bridges.py docstring.

* Fixed doctest section underlines

* removed test main

* Added workaround for classmethod notimplemented and tests

* Fixed k=1 case for directed graphs and increased coverage

doc/reference/algorithms/connectivity.rst

@@ -4,6 +4,13 @@ Connectivity
 
 .. automodule:: networkx.algorithms.connectivity
 
+K-edge-components
+-----------------
+.. automodule:: networkx.algorithms.connectivity.edge_kcomponents
+.. autosummary::
+   :toctree: generated/
+
+   edge_kcomponents
 
 K-node-components
 -----------------

networkx/algorithms/__init__.py

@@ -76,6 +76,8 @@
 from networkx.algorithms.connectivity import average_node_connectivity
 from networkx.algorithms.connectivity import edge_connectivity
 from networkx.algorithms.connectivity import k_components
+from networkx.algorithms.connectivity import k_edge_components
+from networkx.algorithms.connectivity import k_edge_subgraphs
 from networkx.algorithms.connectivity import minimum_edge_cut
 from networkx.algorithms.connectivity import minimum_node_cut
 from networkx.algorithms.connectivity import node_connectivity

networkx/algorithms/bridges.py

@@ -22,7 +22,8 @@ def bridges(G, root=None):
     """Generate all bridges in a graph.
 
     A *bridge* in a graph is an edge whose removal causes the number of
-    connected components of the graph to increase.
+    connected components of the graph to increase.  Equivalently, a bridge is an
+    edge that does not belong to any cycle.
 
     Parameters
     ----------
@@ -53,11 +54,18 @@ def bridges(G, root=None):
 
     Notes
     -----
-    This implementation uses the :func:`networkx.chain_decomposition`
-    function, so it shares its worst-case time complexity, :math:`O(m +
-    n)`, ignoring polylogarithmic factors, where *n* is the number of
-    nodes in the graph and *m* is the number of edges.
+    This is an implementation of the algorithm described in _[1].  An edge is a
+    bridge iff it is not contained in any chain. Chains are found using the
+    :func:`networkx.chain_decomposition` function.
+
+    Ignoring polylogarithmic factors, the worst-case time complexity is the
+    same as the :func:`networkx.chain_decomposition` function,
+    :math:`O(m + n)`, where *n* is the number of nodes in the graph and *m* is
+    the number of edges.
 
+    References
+    ----------
+    .. [1] https://en.wikipedia.org/wiki/Bridge_(graph_theory)#Bridge-Finding_with_Chain_Decompositions
     """
     chains = nx.chain_decomposition(G, root=root)
     chain_edges = set(chain.from_iterable(chains))

networkx/algorithms/components/biconnected.py

@@ -197,6 +197,13 @@ def biconnected_components(G):
     NetworkXNotImplemented :
         If the input graph is not undirected.
 
+    See Also
+    --------
+    k_components : this function is a special case where k=2
+    bridge_components : similar to this function, but is defined using
+        2-edge-connectivity instead of 2-node-connectivity.
+
+
     Examples
     --------
     >>> G = nx.lollipop_graph(5, 1)

networkx/algorithms/connectivity/__init__.py

@@ -2,13 +2,15 @@
 """
 from .connectivity import *
 from .cuts import *
+from .edge_kcomponents import *
 from .kcomponents import *
 from .kcutsets import *
 from .stoerwagner import *
 from .utils import *
 
 __all__ = sum([connectivity.__all__,
                cuts.__all__,
+               edge_kcomponents.__all__,
                kcomponents.__all__,
                kcutsets.__all__,
                stoerwagner.__all__,

networkx/algorithms/connectivity/connectivity.py

@@ -732,6 +732,8 @@ def edge_connectivity(G, s=None, t=None, flow_func=None):
     :meth:`edmonds_karp`
     :meth:`preflow_push`
     :meth:`shortest_augmenting_path`
+    :meth:`k_edge_components`
+    :meth:`k_edge_subgraphs`
 
     References
     ----------