173 lines
6.8 KiB
Python
173 lines
6.8 KiB
Python
"""Functions for finding chains in a graph."""
|
||
|
||
import networkx as nx
|
||
from networkx.utils import not_implemented_for
|
||
|
||
__all__ = ["chain_decomposition"]
|
||
|
||
|
||
@not_implemented_for("directed")
|
||
@not_implemented_for("multigraph")
|
||
@nx._dispatchable
|
||
def chain_decomposition(G, root=None):
|
||
"""Returns the chain decomposition of a graph.
|
||
|
||
The *chain decomposition* of a graph with respect a depth-first
|
||
search tree is a set of cycles or paths derived from the set of
|
||
fundamental cycles of the tree in the following manner. Consider
|
||
each fundamental cycle with respect to the given tree, represented
|
||
as a list of edges beginning with the nontree edge oriented away
|
||
from the root of the tree. For each fundamental cycle, if it
|
||
overlaps with any previous fundamental cycle, just take the initial
|
||
non-overlapping segment, which is a path instead of a cycle. Each
|
||
cycle or path is called a *chain*. For more information, see [1]_.
|
||
|
||
Parameters
|
||
----------
|
||
G : undirected graph
|
||
|
||
root : node (optional)
|
||
A node in the graph `G`. If specified, only the chain
|
||
decomposition for the connected component containing this node
|
||
will be returned. This node indicates the root of the depth-first
|
||
search tree.
|
||
|
||
Yields
|
||
------
|
||
chain : list
|
||
A list of edges representing a chain. There is no guarantee on
|
||
the orientation of the edges in each chain (for example, if a
|
||
chain includes the edge joining nodes 1 and 2, the chain may
|
||
include either (1, 2) or (2, 1)).
|
||
|
||
Raises
|
||
------
|
||
NodeNotFound
|
||
If `root` is not in the graph `G`.
|
||
|
||
Examples
|
||
--------
|
||
>>> G = nx.Graph([(0, 1), (1, 4), (3, 4), (3, 5), (4, 5)])
|
||
>>> list(nx.chain_decomposition(G))
|
||
[[(4, 5), (5, 3), (3, 4)]]
|
||
|
||
Notes
|
||
-----
|
||
The worst-case running time of this implementation is linear in the
|
||
number of nodes and number of edges [1]_.
|
||
|
||
References
|
||
----------
|
||
.. [1] Jens M. Schmidt (2013). "A simple test on 2-vertex-
|
||
and 2-edge-connectivity." *Information Processing Letters*,
|
||
113, 241–244. Elsevier. <https://doi.org/10.1016/j.ipl.2013.01.016>
|
||
|
||
"""
|
||
|
||
def _dfs_cycle_forest(G, root=None):
|
||
"""Builds a directed graph composed of cycles from the given graph.
|
||
|
||
`G` is an undirected simple graph. `root` is a node in the graph
|
||
from which the depth-first search is started.
|
||
|
||
This function returns both the depth-first search cycle graph
|
||
(as a :class:`~networkx.DiGraph`) and the list of nodes in
|
||
depth-first preorder. The depth-first search cycle graph is a
|
||
directed graph whose edges are the edges of `G` oriented toward
|
||
the root if the edge is a tree edge and away from the root if
|
||
the edge is a non-tree edge. If `root` is not specified, this
|
||
performs a depth-first search on each connected component of `G`
|
||
and returns a directed forest instead.
|
||
|
||
If `root` is not in the graph, this raises :exc:`KeyError`.
|
||
|
||
"""
|
||
# Create a directed graph from the depth-first search tree with
|
||
# root node `root` in which tree edges are directed toward the
|
||
# root and nontree edges are directed away from the root. For
|
||
# each node with an incident nontree edge, this creates a
|
||
# directed cycle starting with the nontree edge and returning to
|
||
# that node.
|
||
#
|
||
# The `parent` node attribute stores the parent of each node in
|
||
# the DFS tree. The `nontree` edge attribute indicates whether
|
||
# the edge is a tree edge or a nontree edge.
|
||
#
|
||
# We also store the order of the nodes found in the depth-first
|
||
# search in the `nodes` list.
|
||
H = nx.DiGraph()
|
||
nodes = []
|
||
for u, v, d in nx.dfs_labeled_edges(G, source=root):
|
||
if d == "forward":
|
||
# `dfs_labeled_edges()` yields (root, root, 'forward')
|
||
# if it is beginning the search on a new connected
|
||
# component.
|
||
if u == v:
|
||
H.add_node(v, parent=None)
|
||
nodes.append(v)
|
||
else:
|
||
H.add_node(v, parent=u)
|
||
H.add_edge(v, u, nontree=False)
|
||
nodes.append(v)
|
||
# `dfs_labeled_edges` considers nontree edges in both
|
||
# orientations, so we need to not add the edge if it its
|
||
# other orientation has been added.
|
||
elif d == "nontree" and v not in H[u]:
|
||
H.add_edge(v, u, nontree=True)
|
||
else:
|
||
# Do nothing on 'reverse' edges; we only care about
|
||
# forward and nontree edges.
|
||
pass
|
||
return H, nodes
|
||
|
||
def _build_chain(G, u, v, visited):
|
||
"""Generate the chain starting from the given nontree edge.
|
||
|
||
`G` is a DFS cycle graph as constructed by
|
||
:func:`_dfs_cycle_graph`. The edge (`u`, `v`) is a nontree edge
|
||
that begins a chain. `visited` is a set representing the nodes
|
||
in `G` that have already been visited.
|
||
|
||
This function yields the edges in an initial segment of the
|
||
fundamental cycle of `G` starting with the nontree edge (`u`,
|
||
`v`) that includes all the edges up until the first node that
|
||
appears in `visited`. The tree edges are given by the 'parent'
|
||
node attribute. The `visited` set is updated to add each node in
|
||
an edge yielded by this function.
|
||
|
||
"""
|
||
while v not in visited:
|
||
yield u, v
|
||
visited.add(v)
|
||
u, v = v, G.nodes[v]["parent"]
|
||
yield u, v
|
||
|
||
# Check if the root is in the graph G. If not, raise NodeNotFound
|
||
if root is not None and root not in G:
|
||
raise nx.NodeNotFound(f"Root node {root} is not in graph")
|
||
|
||
# Create a directed version of H that has the DFS edges directed
|
||
# toward the root and the nontree edges directed away from the root
|
||
# (in each connected component).
|
||
H, nodes = _dfs_cycle_forest(G, root)
|
||
|
||
# Visit the nodes again in DFS order. For each node, and for each
|
||
# nontree edge leaving that node, compute the fundamental cycle for
|
||
# that nontree edge starting with that edge. If the fundamental
|
||
# cycle overlaps with any visited nodes, just take the prefix of the
|
||
# cycle up to the point of visited nodes.
|
||
#
|
||
# We repeat this process for each connected component (implicitly,
|
||
# since `nodes` already has a list of the nodes grouped by connected
|
||
# component).
|
||
visited = set()
|
||
for u in nodes:
|
||
visited.add(u)
|
||
# For each nontree edge going out of node u...
|
||
edges = ((u, v) for u, v, d in H.out_edges(u, data="nontree") if d)
|
||
for u, v in edges:
|
||
# Create the cycle or cycle prefix starting with the
|
||
# nontree edge.
|
||
chain = list(_build_chain(H, u, v, visited))
|
||
yield chain
|