a
HlX`t@sdZddlZddlmZddlZddlmZddlmZddlm Z ddlm
Z
ddlmZe Zd d
l
mZmZgdZddd
ZdddZdddZdddZdddZdddZdS)z$
Flow based connectivity algorithms
N)
itemgetter)boykov_kolmogorov)dinitz)edmonds_karp)shortest_augmenting_path)build_residual_network)!build_auxiliary_node_connectivity!build_auxiliary_edge_connectivity)average_node_connectivitylocal_node_connectivitynode_connectivitylocal_edge_connectivityedge_connectivityall_pairs_node_connectivityc
Csdurt}durt}n}jdd}durBtdtd} turh d<d d<n4turz d<n"t ur d<nt
ur d<tjdd fi S)
aComputes local node connectivity for nodes s and t.
Local node connectivity for two non adjacent nodes s and t is the
minimum number of nodes that must be removed (along with their incident
edges) to disconnect them.
This is a flow based implementation of node connectivity. We compute the
maximum flow on an auxiliary digraph build from the original input
graph (see below for details).
Parameters

G : NetworkX graph
Undirected graph
s : node
Source node
t : node
Target node
flow_func : function
A function for computing the maximum flow among a pair of nodes.
The function has to accept at least three parameters: a Digraph,
a source node, and a target node. And return a residual network
that follows NetworkX conventions (see :meth:`maximum_flow` for
details). If flow_func is None, the default maximum flow function
(:meth:`edmonds_karp`) is used. See below for details. The choice
of the default function may change from version to version and
should not be relied on. Default value: None.
auxiliary : NetworkX DiGraph
Auxiliary digraph to compute flow based node connectivity. It has
to have a graph attribute called mapping with a dictionary mapping
node names in G and in the auxiliary digraph. If provided
it will be reused instead of recreated. Default value: None.
residual : NetworkX DiGraph
Residual network to compute maximum flow. If provided it will be
reused instead of recreated. Default value: None.
cutoff : integer, float
If specified, the maximum flow algorithm will terminate when the
flow value reaches or exceeds the cutoff. This is only for the
algorithms that support the cutoff parameter: :meth:`edmonds_karp`
and :meth:`shortest_augmenting_path`. Other algorithms will ignore
this parameter. Default value: None.
Returns

K : integer
local node connectivity for nodes s and t
Examples

This function is not imported in the base NetworkX namespace, so you
have to explicitly import it from the connectivity package:
>>> from networkx.algorithms.connectivity import local_node_connectivity
We use in this example the platonic icosahedral graph, which has node
connectivity 5.
>>> G = nx.icosahedral_graph()
>>> local_node_connectivity(G, 0, 6)
5
If you need to compute local connectivity on several pairs of
nodes in the same graph, it is recommended that you reuse the
data structures that NetworkX uses in the computation: the
auxiliary digraph for node connectivity, and the residual
network for the underlying maximum flow computation.
Example of how to compute local node connectivity among
all pairs of nodes of the platonic icosahedral graph reusing
the data structures.
>>> import itertools
>>> # You also have to explicitly import the function for
>>> # building the auxiliary digraph from the connectivity package
>>> from networkx.algorithms.connectivity import build_auxiliary_node_connectivity
...
>>> H = build_auxiliary_node_connectivity(G)
>>> # And the function for building the residual network from the
>>> # flow package
>>> from networkx.algorithms.flow import build_residual_network
>>> # Note that the auxiliary digraph has an edge attribute named capacity
>>> R = build_residual_network(H, "capacity")
>>> result = dict.fromkeys(G, dict())
>>> # Reuse the auxiliary digraph and the residual network by passing them
>>> # as parameters
>>> for u, v in itertools.combinations(G, 2):
... k = local_node_connectivity(G, u, v, auxiliary=H, residual=R)
... result[u][v] = k
...
>>> all(result[u][v] == 5 for u, v in itertools.combinations(G, 2))
True
You can also use alternative flow algorithms for computing node
connectivity. For instance, in dense networks the algorithm
:meth:`shortest_augmenting_path` will usually perform better than
the default :meth:`edmonds_karp` which is faster for sparse
networks with highly skewed degree distributions. Alternative flow
functions have to be explicitly imported from the flow package.
>>> from networkx.algorithms.flow import shortest_augmenting_path
>>> local_node_connectivity(G, 0, 6, flow_func=shortest_augmenting_path)
5
Notes

This is a flow based implementation of node connectivity. We compute the
maximum flow using, by default, the :meth:`edmonds_karp` algorithm (see:
:meth:`maximum_flow`) on an auxiliary digraph build from the original
input graph:
For an undirected graph G having `n` nodes and `m` edges we derive a
directed graph H with `2n` nodes and `2m+n` arcs by replacing each
original node `v` with two nodes `v_A`, `v_B` linked by an (internal)
arc in H. Then for each edge (`u`, `v`) in G we add two arcs
(`u_B`, `v_A`) and (`v_B`, `u_A`) in H. Finally we set the attribute
capacity = 1 for each arc in H [1]_ .
For a directed graph G having `n` nodes and `m` arcs we derive a
directed graph H with `2n` nodes and `m+n` arcs by replacing each
original node `v` with two nodes `v_A`, `v_B` linked by an (internal)
arc (`v_A`, `v_B`) in H. Then for each arc (`u`, `v`) in G we add one arc
(`u_B`, `v_A`) in H. Finally we set the attribute capacity = 1 for
each arc in H.
This is equal to the local node connectivity because the value of
a maximum stflow is equal to the capacity of a minimum stcut.
See also

:meth:`local_edge_connectivity`
:meth:`node_connectivity`
:meth:`minimum_node_cut`
:meth:`maximum_flow`
:meth:`edmonds_karp`
:meth:`preflow_push`
:meth:`shortest_augmenting_path`
References

.. [1] Kammer, Frank and Hanjo Taubig. Graph Connectivity. in Brandes and
Erlebach, 'Network Analysis: Methodological Foundations', Lecture
Notes in Computer Science, Volume 3418, SpringerVerlag, 2005.
http://www.informatik.uniaugsburg.de/thi/personen/kammer/Graph_Connectivity.pdf
NmappingzInvalid auxiliary digraph. flow_funcresidualcutoffT two_phaseBA)default_flow_funcr graphgetnx
NetworkXErrordictrrrrmaximum_flow_value)
Gstr auxiliaryrrHrkwargsr&/Users/cmdms/OneDriveUOB/Development/Projects/2021/samconsensusv3/env/lib/python3.9/sitepackages/networkx/algorithms/connectivity/connectivity.pyr s(
rcsdurdus dur*dur*tddur~dur~vrTtddvrntddtdSrtsdStj}fdd}ntsdStj}j }t
}td }td
}t
tdd\} }
tt  hD](}
d
<t

t fi}
q dD]>\}}

vrfqL
d
<t

t
fi}
qL
S)aReturns node connectivity for a graph or digraph G.
Node connectivity is equal to the minimum number of nodes that
must be removed to disconnect G or render it trivial. If source
and target nodes are provided, this function returns the local node
connectivity: the minimum number of nodes that must be removed to break
all paths from source to target in G.
Parameters

G : NetworkX graph
Undirected graph
s : node
Source node. Optional. Default value: None.
t : node
Target node. Optional. Default value: None.
flow_func : function
A function for computing the maximum flow among a pair of nodes.
The function has to accept at least three parameters: a Digraph,
a source node, and a target node. And return a residual network
that follows NetworkX conventions (see :meth:`maximum_flow` for
details). If flow_func is None, the default maximum flow function
(:meth:`edmonds_karp`) is used. See below for details. The
choice of the default function may change from version
to version and should not be relied on. Default value: None.
Returns

K : integer
Node connectivity of G, or local node connectivity if source
and target are provided.
Examples

>>> # Platonic icosahedral graph is 5nodeconnected
>>> G = nx.icosahedral_graph()
>>> nx.node_connectivity(G)
5
You can use alternative flow algorithms for the underlying maximum
flow computation. In dense networks the algorithm
:meth:`shortest_augmenting_path` will usually perform better
than the default :meth:`edmonds_karp`, which is faster for
sparse networks with highly skewed degree distributions. Alternative
flow functions have to be explicitly imported from the flow package.
>>> from networkx.algorithms.flow import shortest_augmenting_path
>>> nx.node_connectivity(G, flow_func=shortest_augmenting_path)
5
If you specify a pair of nodes (source and target) as parameters,
this function returns the value of local node connectivity.
>>> nx.node_connectivity(G, 3, 7)
5
If you need to perform several local computations among different
pairs of nodes on the same graph, it is recommended that you reuse
the data structures used in the maximum flow computations. See
:meth:`local_node_connectivity` for details.
Notes

This is a flow based implementation of node connectivity. The
algorithm works by solving $O((n\delta1+\delta(\delta1)/2))$
maximum flow problems on an auxiliary digraph. Where $\delta$
is the minimum degree of G. For details about the auxiliary
digraph and the computation of local node connectivity see
:meth:`local_node_connectivity`. This implementation is based
on algorithm 11 in [1]_.
See also

:meth:`local_node_connectivity`
:meth:`edge_connectivity`
:meth:`maximum_flow`
:meth:`edmonds_karp`
:meth:`preflow_push`
:meth:`shortest_augmenting_path`
References

.. [1] AbdolHossein Esfahanian. Connectivity Algorithms.
http://www.cse.msu.edu/~cse835/Papers/Graph_connectivity_revised.pdf
N)Both source and target must be specified.node
not in graph)rrcstjgSN) itertoolschain
from_iterableZpredecessors
successors)vr r&r' neighborsAsz$node_connectivity..neighborscapacityrr#rr)keyr)rrris_directedis_weakly_connectedr,permutationsis_connectedcombinationsr2r rrmindegreerset)r r!r"r iter_funcr2r$Rr%r0Kwxyr&r1r'r
s<Z
r
c
Csrtj}ntj}t}td}td}d\}}dD](\}} t fi7}d7}qHdkr~dSS)a
Returns the average connectivity of a graph G.
The average connectivity `\bar{\kappa}` of a graph G is the average
of local node connectivity over all pairs of nodes of G [1]_ .
.. math::
\bar{\kappa}(G) = \frac{\sum_{u,v} \kappa_{G}(u,v)}{{n \choose 2}}
Parameters

G : NetworkX graph
Undirected graph
flow_func : function
A function for computing the maximum flow among a pair of nodes.
The function has to accept at least three parameters: a Digraph,
a source node, and a target node. And return a residual network
that follows NetworkX conventions (see :meth:`maximum_flow` for
details). If flow_func is None, the default maximum flow function
(:meth:`edmonds_karp`) is used. See :meth:`local_node_connectivity`
for details. The choice of the default function may change from
version to version and should not be relied on. Default value: None.
Returns

K : float
Average node connectivity
See also

:meth:`local_node_connectivity`
:meth:`node_connectivity`
:meth:`edge_connectivity`
:meth:`maximum_flow`
:meth:`edmonds_karp`
:meth:`preflow_push`
:meth:`shortest_augmenting_path`
References

.. [1] Beineke, L., O. Oellermann, and R. Pippert (2002). The average
connectivity of a graph. Discrete mathematics 252(13), 3145.
http://www.sciencedirect.com/science/article/pii/S0012365X01001807
r3r4)rrr6rr)r7r,r9r;r rrr)
r rr?r$r@r%numZdenur0r&r&r'r`s0
rc
Csdur}nt}}r*tj}ntj}ddD}t}jd}td}td} dD]8\}
}t 
fi }
<sr
<qrS)aCompute node connectivity between all pairs of nodes of G.
Parameters

G : NetworkX graph
Undirected graph
nbunch: container
Container of nodes. If provided node connectivity will be computed
only over pairs of nodes in nbunch.
flow_func : function
A function for computing the maximum flow among a pair of nodes.
The function has to accept at least three parameters: a Digraph,
a source node, and a target node. And return a residual network
that follows NetworkX conventions (see :meth:`maximum_flow` for
details). If flow_func is None, the default maximum flow function
(:meth:`edmonds_karp`) is used. See below for details. The
choice of the default function may change from version
to version and should not be relied on. Default value: None.
Returns

all_pairs : dict
A dictionary with node connectivity between all pairs of nodes
in G, or in nbunch if provided.
See also

:meth:`local_node_connectivity`
:meth:`edge_connectivity`
:meth:`local_edge_connectivity`
:meth:`maximum_flow`
:meth:`edmonds_karp`
:meth:`preflow_push`
:meth:`shortest_augmenting_path`
NcSsi]
}iqSr&r&).0nr&r&r'
z/all_pairs_node_connectivity..rr3r4r6)
r>r7r,r9r;r rrrr)
r ZnbunchrZdirectedr?Z all_pairsr$rr@r%rFr0rAr&r&r'rs$'
rc Csdurt}durt}n}td}turHd<dd<n4turZd<n"turld<nturd<tjfiS)a.Returns local edge connectivity for nodes s and t in G.
Local edge connectivity for two nodes s and t is the minimum number
of edges that must be removed to disconnect them.
This is a flow based implementation of edge connectivity. We compute the
maximum flow on an auxiliary digraph build from the original
network (see below for details). This is equal to the local edge
connectivity because the value of a maximum stflow is equal to the
capacity of a minimum stcut (Ford and Fulkerson theorem) [1]_ .
Parameters

G : NetworkX graph
Undirected or directed graph
s : node
Source node
t : node
Target node
flow_func : function
A function for computing the maximum flow among a pair of nodes.
The function has to accept at least three parameters: a Digraph,
a source node, and a target node. And return a residual network
that follows NetworkX conventions (see :meth:`maximum_flow` for
details). If flow_func is None, the default maximum flow function
(:meth:`edmonds_karp`) is used. See below for details. The
choice of the default function may change from version
to version and should not be relied on. Default value: None.
auxiliary : NetworkX DiGraph
Auxiliary digraph for computing flow based edge connectivity. If
provided it will be reused instead of recreated. Default value: None.
residual : NetworkX DiGraph
Residual network to compute maximum flow. If provided it will be
reused instead of recreated. Default value: None.
cutoff : integer, float
If specified, the maximum flow algorithm will terminate when the
flow value reaches or exceeds the cutoff. This is only for the
algorithms that support the cutoff parameter: :meth:`edmonds_karp`
and :meth:`shortest_augmenting_path`. Other algorithms will ignore
this parameter. Default value: None.
Returns

K : integer
local edge connectivity for nodes s and t.
Examples

This function is not imported in the base NetworkX namespace, so you
have to explicitly import it from the connectivity package:
>>> from networkx.algorithms.connectivity import local_edge_connectivity
We use in this example the platonic icosahedral graph, which has edge
connectivity 5.
>>> G = nx.icosahedral_graph()
>>> local_edge_connectivity(G, 0, 6)
5
If you need to compute local connectivity on several pairs of
nodes in the same graph, it is recommended that you reuse the
data structures that NetworkX uses in the computation: the
auxiliary digraph for edge connectivity, and the residual
network for the underlying maximum flow computation.
Example of how to compute local edge connectivity among
all pairs of nodes of the platonic icosahedral graph reusing
the data structures.
>>> import itertools
>>> # You also have to explicitly import the function for
>>> # building the auxiliary digraph from the connectivity package
>>> from networkx.algorithms.connectivity import build_auxiliary_edge_connectivity
>>> H = build_auxiliary_edge_connectivity(G)
>>> # And the function for building the residual network from the
>>> # flow package
>>> from networkx.algorithms.flow import build_residual_network
>>> # Note that the auxiliary digraph has an edge attribute named capacity
>>> R = build_residual_network(H, "capacity")
>>> result = dict.fromkeys(G, dict())
>>> # Reuse the auxiliary digraph and the residual network by passing them
>>> # as parameters
>>> for u, v in itertools.combinations(G, 2):
... k = local_edge_connectivity(G, u, v, auxiliary=H, residual=R)
... result[u][v] = k
>>> all(result[u][v] == 5 for u, v in itertools.combinations(G, 2))
True
You can also use alternative flow algorithms for computing edge
connectivity. For instance, in dense networks the algorithm
:meth:`shortest_augmenting_path` will usually perform better than
the default :meth:`edmonds_karp` which is faster for sparse
networks with highly skewed degree distributions. Alternative flow
functions have to be explicitly imported from the flow package.
>>> from networkx.algorithms.flow import shortest_augmenting_path
>>> local_edge_connectivity(G, 0, 6, flow_func=shortest_augmenting_path)
5
Notes

This is a flow based implementation of edge connectivity. We compute the
maximum flow using, by default, the :meth:`edmonds_karp` algorithm on an
auxiliary digraph build from the original input graph:
If the input graph is undirected, we replace each edge (`u`,`v`) with
two reciprocal arcs (`u`, `v`) and (`v`, `u`) and then we set the attribute
'capacity' for each arc to 1. If the input graph is directed we simply
add the 'capacity' attribute. This is an implementation of algorithm 1
in [1]_.
The maximum flow in the auxiliary network is equal to the local edge
connectivity because the value of a maximum stflow is equal to the
capacity of a minimum stcut (Ford and Fulkerson theorem).
See also

:meth:`edge_connectivity`
:meth:`local_node_connectivity`
:meth:`node_connectivity`
:meth:`maximum_flow`
:meth:`edmonds_karp`
:meth:`preflow_push`
:meth:`shortest_augmenting_path`
References

.. [1] AbdolHossein Esfahanian. Connectivity Algorithms.
http://www.cse.msu.edu/~cse835/Papers/Graph_connectivity_revised.pdf
NrrTr) rr
rrrrrrr) r r!r"rr#rrr$r%r&r&r'rs"
rcCsdurdus dur*dur*tddurdurvrTtddvrntddtdSt}td}td}rltsdStd d
 D}t
} t }
durt}t
D]n}d<z*tt  dfi}Wqt
ydtt  dfi}Yq0qStsdStd
d
 D}durt}D](}tjd}

}
rqؐqS
D](}d<ttfi}qSdS)a=Returns the edge connectivity of the graph or digraph G.
The edge connectivity is equal to the minimum number of edges that
must be removed to disconnect G or render it trivial. If source
and target nodes are provided, this function returns the local edge
connectivity: the minimum number of edges that must be removed to
break all paths from source to target in G.
Parameters

G : NetworkX graph
Undirected or directed graph
s : node
Source node. Optional. Default value: None.
t : node
Target node. Optional. Default value: None.
flow_func : function
A function for computing the maximum flow among a pair of nodes.
The function has to accept at least three parameters: a Digraph,
a source node, and a target node. And return a residual network
that follows NetworkX conventions (see :meth:`maximum_flow` for
details). If flow_func is None, the default maximum flow function
(:meth:`edmonds_karp`) is used. See below for details. The
choice of the default function may change from version
to version and should not be relied on. Default value: None.
cutoff : integer, float
If specified, the maximum flow algorithm will terminate when the
flow value reaches or exceeds the cutoff. This is only for the
algorithms that support the cutoff parameter: e.g., :meth:`edmonds_karp`
and :meth:`shortest_augmenting_path`. Other algorithms will ignore
this parameter. Default value: None.
Returns

K : integer
Edge connectivity for G, or local edge connectivity if source
and target were provided
Examples

>>> # Platonic icosahedral graph is 5edgeconnected
>>> G = nx.icosahedral_graph()
>>> nx.edge_connectivity(G)
5
You can use alternative flow algorithms for the underlying
maximum flow computation. In dense networks the algorithm
:meth:`shortest_augmenting_path` will usually perform better
than the default :meth:`edmonds_karp`, which is faster for
sparse networks with highly skewed degree distributions.
Alternative flow functions have to be explicitly imported
from the flow package.
>>> from networkx.algorithms.flow import shortest_augmenting_path
>>> nx.edge_connectivity(G, flow_func=shortest_augmenting_path)
5
If you specify a pair of nodes (source and target) as parameters,
this function returns the value of local edge connectivity.
>>> nx.edge_connectivity(G, 3, 7)
5
If you need to perform several local computations among different
pairs of nodes on the same graph, it is recommended that you reuse
the data structures used in the maximum flow computations. See
:meth:`local_edge_connectivity` for details.
Notes

This is a flow based implementation of global edge connectivity.
For undirected graphs the algorithm works by finding a 'small'
dominating set of nodes of G (see algorithm 7 in [1]_ ) and
computing local maximum flow (see :meth:`local_edge_connectivity`)
between an arbitrary node in the dominating set and the rest of
nodes in it. This is an implementation of algorithm 6 in [1]_ .
For directed graphs, the algorithm does n calls to the maximum
flow function. This is an implementation of algorithm 8 in [1]_ .
See also

:meth:`local_edge_connectivity`
:meth:`local_node_connectivity`
:meth:`node_connectivity`
:meth:`maximum_flow`
:meth:`edmonds_karp`
:meth:`preflow_push`
:meth:`shortest_augmenting_path`
:meth:`k_edge_components`
:meth:`k_edge_subgraphs`
References

.. [1] AbdolHossein Esfahanian. Connectivity Algorithms.
http://www.cse.msu.edu/~cse835/Papers/Graph_connectivity_revised.pdf
Nr(r)r*)rrr3r4rcss]\}}VqdSr+r&rGrHdr&r&r' rJz$edge_connectivity..rrcss]\}}VqdSr+r&rKr&r&r'rMrJ)Z
start_with)rrrr
rrr7r8r<r=listlenrange
IndexErrorr:Zdominating_setpop)r r!r"rrr$r@r%LnodesrHinodeDr0rBr&r&r'rsRf
**
r)NNNN)NNN)N)NN)NNNN)NNNN)__doc__r,operatorrZnetworkxrZnetworkx.algorithms.flowrrrrrrutilsr r
__all__rr
rrrrr&r&r&r's,
5
D
D
$