okstra 0.107.2 → 0.109.0

package/runtime/python/okstra_vendor/networkx/algorithms/components/biconnected.py

@@ -0,0 +1,394 @@
+"""Biconnected components and articulation points."""
+
+from itertools import chain
+
+import networkx as nx
+from networkx.utils.decorators import not_implemented_for
+
+__all__ = [
+    "biconnected_components",
+    "biconnected_component_edges",
+    "is_biconnected",
+    "articulation_points",
+]
+
+
+@not_implemented_for("directed")
+@nx._dispatchable
+def is_biconnected(G):
+    """Returns True if the graph is biconnected, False otherwise.
+
+    A graph is biconnected if, and only if, it cannot be disconnected by
+    removing only one node (and all edges incident on that node).  If
+    removing a node increases the number of disconnected components
+    in the graph, that node is called an articulation point, or cut
+    vertex.  A biconnected graph has no articulation points.
+
+    Parameters
+    ----------
+    G : NetworkX Graph
+        An undirected graph.
+
+    Returns
+    -------
+    biconnected : bool
+        True if the graph is biconnected, False otherwise.
+
+    Raises
+    ------
+    NetworkXNotImplemented
+        If the input graph is not undirected.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(4)
+    >>> print(nx.is_biconnected(G))
+    False
+    >>> G.add_edge(0, 3)
+    >>> print(nx.is_biconnected(G))
+    True
+
+    See Also
+    --------
+    biconnected_components
+    articulation_points
+    biconnected_component_edges
+    is_strongly_connected
+    is_weakly_connected
+    is_connected
+    is_semiconnected
+
+    Notes
+    -----
+    The algorithm to find articulation points and biconnected
+    components is implemented using a non-recursive depth-first-search
+    (DFS) that keeps track of the highest level that back edges reach
+    in the DFS tree.  A node `n` is an articulation point if, and only
+    if, there exists a subtree rooted at `n` such that there is no
+    back edge from any successor of `n` that links to a predecessor of
+    `n` in the DFS tree.  By keeping track of all the edges traversed
+    by the DFS we can obtain the biconnected components because all
+    edges of a bicomponent will be traversed consecutively between
+    articulation points.
+
+    References
+    ----------
+    .. [1] Hopcroft, J.; Tarjan, R. (1973).
+       "Efficient algorithms for graph manipulation".
+       Communications of the ACM 16: 372–378. doi:10.1145/362248.362272
+
+    """
+    bccs = biconnected_components(G)
+    try:
+        bcc = next(bccs)
+    except StopIteration:
+        # No bicomponents (empty graph?)
+        return False
+    try:
+        next(bccs)
+    except StopIteration:
+        # Only one bicomponent
+        return len(bcc) == len(G)
+    else:
+        # Multiple bicomponents
+        return False
+
+
+@not_implemented_for("directed")
+@nx._dispatchable
+def biconnected_component_edges(G):
+    """Returns a generator of lists of edges, one list for each biconnected
+    component of the input graph.
+
+    Biconnected components are maximal subgraphs such that the removal of a
+    node (and all edges incident on that node) will not disconnect the
+    subgraph.  Note that nodes may be part of more than one biconnected
+    component.  Those nodes are articulation points, or cut vertices.
+    However, each edge belongs to one, and only one, biconnected component.
+
+    Notice that by convention a dyad is considered a biconnected component.
+
+    Parameters
+    ----------
+    G : NetworkX Graph
+        An undirected graph.
+
+    Returns
+    -------
+    edges : generator of lists
+        Generator of lists of edges, one list for each bicomponent.
+
+    Raises
+    ------
+    NetworkXNotImplemented
+        If the input graph is not undirected.
+
+    Examples
+    --------
+    >>> G = nx.barbell_graph(4, 2)
+    >>> print(nx.is_biconnected(G))
+    False
+    >>> bicomponents_edges = list(nx.biconnected_component_edges(G))
+    >>> len(bicomponents_edges)
+    5
+    >>> G.add_edge(2, 8)
+    >>> print(nx.is_biconnected(G))
+    True
+    >>> bicomponents_edges = list(nx.biconnected_component_edges(G))
+    >>> len(bicomponents_edges)
+    1
+
+    See Also
+    --------
+    is_biconnected,
+    biconnected_components,
+    articulation_points,
+
+    Notes
+    -----
+    The algorithm to find articulation points and biconnected
+    components is implemented using a non-recursive depth-first-search
+    (DFS) that keeps track of the highest level that back edges reach
+    in the DFS tree.  A node `n` is an articulation point if, and only
+    if, there exists a subtree rooted at `n` such that there is no
+    back edge from any successor of `n` that links to a predecessor of
+    `n` in the DFS tree.  By keeping track of all the edges traversed
+    by the DFS we can obtain the biconnected components because all
+    edges of a bicomponent will be traversed consecutively between
+    articulation points.
+
+    References
+    ----------
+    .. [1] Hopcroft, J.; Tarjan, R. (1973).
+           "Efficient algorithms for graph manipulation".
+           Communications of the ACM 16: 372–378. doi:10.1145/362248.362272
+
+    """
+    yield from _biconnected_dfs(G, components=True)
+
+
+@not_implemented_for("directed")
+@nx._dispatchable
+def biconnected_components(G):
+    """Returns a generator of sets of nodes, one set for each biconnected
+    component of the graph
+
+    Biconnected components are maximal subgraphs such that the removal of a
+    node (and all edges incident on that node) will not disconnect the
+    subgraph. Note that nodes may be part of more than one biconnected
+    component.  Those nodes are articulation points, or cut vertices.  The
+    removal of articulation points will increase the number of connected
+    components of the graph.
+
+    Notice that by convention a dyad is considered a biconnected component.
+
+    Parameters
+    ----------
+    G : NetworkX Graph
+        An undirected graph.
+
+    Returns
+    -------
+    nodes : generator
+        Generator of sets of nodes, one set for each biconnected component.
+
+    Raises
+    ------
+    NetworkXNotImplemented
+        If the input graph is not undirected.
+
+    Examples
+    --------
+    >>> G = nx.lollipop_graph(5, 1)
+    >>> print(nx.is_biconnected(G))
+    False
+    >>> bicomponents = list(nx.biconnected_components(G))
+    >>> len(bicomponents)
+    2
+    >>> G.add_edge(0, 5)
+    >>> print(nx.is_biconnected(G))
+    True
+    >>> bicomponents = list(nx.biconnected_components(G))
+    >>> len(bicomponents)
+    1
+
+    You can generate a sorted list of biconnected components, largest
+    first, using sort.
+
+    >>> G.remove_edge(0, 5)
+    >>> [len(c) for c in sorted(nx.biconnected_components(G), key=len, reverse=True)]
+    [5, 2]
+
+    If you only want the largest connected component, it's more
+    efficient to use max instead of sort.
+
+    >>> Gc = max(nx.biconnected_components(G), key=len)
+
+    To create the components as subgraphs use:
+    ``(G.subgraph(c).copy() for c in biconnected_components(G))``
+
+    See Also
+    --------
+    is_biconnected
+    articulation_points
+    biconnected_component_edges
+    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.
+
+    Notes
+    -----
+    The algorithm to find articulation points and biconnected
+    components is implemented using a non-recursive depth-first-search
+    (DFS) that keeps track of the highest level that back edges reach
+    in the DFS tree.  A node `n` is an articulation point if, and only
+    if, there exists a subtree rooted at `n` such that there is no
+    back edge from any successor of `n` that links to a predecessor of
+    `n` in the DFS tree.  By keeping track of all the edges traversed
+    by the DFS we can obtain the biconnected components because all
+    edges of a bicomponent will be traversed consecutively between
+    articulation points.
+
+    References
+    ----------
+    .. [1] Hopcroft, J.; Tarjan, R. (1973).
+           "Efficient algorithms for graph manipulation".
+           Communications of the ACM 16: 372–378. doi:10.1145/362248.362272
+
+    """
+    for comp in _biconnected_dfs(G, components=True):
+        yield set(chain.from_iterable(comp))
+
+
+@not_implemented_for("directed")
+@nx._dispatchable
+def articulation_points(G):
+    """Yield the articulation points, or cut vertices, of a graph.
+
+    An articulation point or cut vertex is any node whose removal (along with
+    all its incident edges) increases the number of connected components of
+    a graph.  An undirected connected graph without articulation points is
+    biconnected. Articulation points belong to more than one biconnected
+    component of a graph.
+
+    Notice that by convention a dyad is considered a biconnected component.
+
+    Parameters
+    ----------
+    G : NetworkX Graph
+        An undirected graph.
+
+    Yields
+    ------
+    node
+        An articulation point in the graph.
+
+    Raises
+    ------
+    NetworkXNotImplemented
+        If the input graph is not undirected.
+
+    Examples
+    --------
+
+    >>> G = nx.barbell_graph(4, 2)
+    >>> print(nx.is_biconnected(G))
+    False
+    >>> len(list(nx.articulation_points(G)))
+    4
+    >>> G.add_edge(2, 8)
+    >>> print(nx.is_biconnected(G))
+    True
+    >>> len(list(nx.articulation_points(G)))
+    0
+
+    See Also
+    --------
+    is_biconnected
+    biconnected_components
+    biconnected_component_edges
+
+    Notes
+    -----
+    The algorithm to find articulation points and biconnected
+    components is implemented using a non-recursive depth-first-search
+    (DFS) that keeps track of the highest level that back edges reach
+    in the DFS tree.  A node `n` is an articulation point if, and only
+    if, there exists a subtree rooted at `n` such that there is no
+    back edge from any successor of `n` that links to a predecessor of
+    `n` in the DFS tree.  By keeping track of all the edges traversed
+    by the DFS we can obtain the biconnected components because all
+    edges of a bicomponent will be traversed consecutively between
+    articulation points.
+
+    References
+    ----------
+    .. [1] Hopcroft, J.; Tarjan, R. (1973).
+           "Efficient algorithms for graph manipulation".
+           Communications of the ACM 16: 372–378. doi:10.1145/362248.362272
+
+    """
+    seen = set()
+    for articulation in _biconnected_dfs(G, components=False):
+        if articulation not in seen:
+            seen.add(articulation)
+            yield articulation
+
+
+@not_implemented_for("directed")
+def _biconnected_dfs(G, components=True):
+    # depth-first search algorithm to generate articulation points
+    # and biconnected components
+    visited = set()
+    for start in G:
+        if start in visited:
+            continue
+        discovery = {start: 0}  # time of first discovery of node during search
+        low = {start: 0}
+        root_children = 0
+        visited.add(start)
+        edge_stack = []
+        stack = [(start, start, iter(G[start]))]
+        edge_index = {}
+        while stack:
+            grandparent, parent, children = stack[-1]
+            try:
+                child = next(children)
+                if grandparent == child:
+                    continue
+                if child in visited:
+                    if discovery[child] <= discovery[parent]:  # back edge
+                        low[parent] = min(low[parent], discovery[child])
+                        if components:
+                            edge_index[parent, child] = len(edge_stack)
+                            edge_stack.append((parent, child))
+                else:
+                    low[child] = discovery[child] = len(discovery)
+                    visited.add(child)
+                    stack.append((parent, child, iter(G[child])))
+                    if components:
+                        edge_index[parent, child] = len(edge_stack)
+                        edge_stack.append((parent, child))
+
+            except StopIteration:
+                stack.pop()
+                if len(stack) > 1:
+                    if low[parent] >= discovery[grandparent]:
+                        if components:
+                            ind = edge_index[grandparent, parent]
+                            yield edge_stack[ind:]
+                            del edge_stack[ind:]
+
+                        else:
+                            yield grandparent
+                    low[grandparent] = min(low[parent], low[grandparent])
+                elif stack:  # length 1 so grandparent is root
+                    root_children += 1
+                    if components:
+                        ind = edge_index[grandparent, parent]
+                        yield edge_stack[ind:]
+                        del edge_stack[ind:]
+        if not components:
+            # root node is articulation point if it has more than 1 child
+            if root_children > 1:
+                yield start

package/runtime/python/okstra_vendor/networkx/algorithms/components/connected.py

@@ -0,0 +1,282 @@
+"""Connected components."""
+
+import networkx as nx
+from networkx.utils.decorators import not_implemented_for
+
+from ...utils import arbitrary_element
+
+__all__ = [
+    "number_connected_components",
+    "connected_components",
+    "is_connected",
+    "node_connected_component",
+]
+
+
+@not_implemented_for("directed")
+@nx._dispatchable
+def connected_components(G):
+    """Generate connected components.
+
+    The connected components of an undirected graph partition the graph into
+    disjoint sets of nodes. Each of these sets induces a subgraph of graph
+    `G` that is connected and not part of any larger connected subgraph.
+
+    A graph is connected (:func:`is_connected`) if, for every pair of distinct
+    nodes, there is a path between them. If there is a pair of nodes for
+    which such path does not exist, the graph is not connected (also referred
+    to as "disconnected").
+
+    A graph consisting of a single node and no edges is connected.
+    Connectivity is undefined for the null graph (graph with no nodes).
+
+    Parameters
+    ----------
+    G : NetworkX graph
+       An undirected graph
+
+    Yields
+    ------
+    comp : set
+       A set of nodes in one connected component of the graph.
+
+    Raises
+    ------
+    NetworkXNotImplemented
+        If G is directed.
+
+    Examples
+    --------
+    Generate a sorted list of connected components, largest first.
+
+    >>> G = nx.path_graph(4)
+    >>> nx.add_path(G, [10, 11, 12])
+    >>> [len(c) for c in sorted(nx.connected_components(G), key=len, reverse=True)]
+    [4, 3]
+
+    If you only want the largest connected component, it's more
+    efficient to use max instead of sort.
+
+    >>> largest_cc = max(nx.connected_components(G), key=len)
+
+    To create the induced subgraph of each component use:
+
+    >>> S = [G.subgraph(c).copy() for c in nx.connected_components(G)]
+
+    See Also
+    --------
+    number_connected_components
+    is_connected
+    number_weakly_connected_components
+    number_strongly_connected_components
+
+    Notes
+    -----
+    This function is for undirected graphs only. For directed graphs, use
+    :func:`strongly_connected_components` or
+    :func:`weakly_connected_components`.
+
+    The algorithm is based on a Breadth-First Search (BFS) traversal and its
+    time complexity is $O(n + m)$, where $n$ is the number of nodes and $m$ the
+    number of edges in the graph.
+
+    """
+    seen = set()
+    n = len(G)  # must be outside the loop to avoid performance hit with graph views
+    for v in G:
+        if v not in seen:
+            c = _plain_bfs(G, n - len(seen), v)
+            seen.update(c)
+            yield c
+
+
+@not_implemented_for("directed")
+@nx._dispatchable
+def number_connected_components(G):
+    """Returns the number of connected components.
+
+    The connected components of an undirected graph partition the graph into
+    disjoint sets of nodes. Each of these sets induces a subgraph of graph
+    `G` that is connected and not part of any larger connected subgraph.
+
+    A graph is connected (:func:`is_connected`) if, for every pair of distinct
+    nodes, there is a path between them. If there is a pair of nodes for
+    which such path does not exist, the graph is not connected (also referred
+    to as "disconnected").
+
+    A graph consisting of a single node and no edges is connected.
+    Connectivity is undefined for the null graph (graph with no nodes).
+
+    Parameters
+    ----------
+    G : NetworkX graph
+       An undirected graph.
+
+    Returns
+    -------
+    n : integer
+       Number of connected components
+
+    Raises
+    ------
+    NetworkXNotImplemented
+        If G is directed.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (1, 2), (5, 6), (3, 4)])
+    >>> nx.number_connected_components(G)
+    3
+
+    See Also
+    --------
+    connected_components
+    is_connected
+    number_weakly_connected_components
+    number_strongly_connected_components
+
+    Notes
+    -----
+    This function is for undirected graphs only. For directed graphs, use
+    :func:`number_strongly_connected_components` or
+    :func:`number_weakly_connected_components`.
+
+    The algorithm is based on a Breadth-First Search (BFS) traversal and its
+    time complexity is $O(n + m)$, where $n$ is the number of nodes and $m$ the
+    number of edges in the graph.
+
+    """
+    return sum(1 for _ in connected_components(G))
+
+
+@not_implemented_for("directed")
+@nx._dispatchable
+def is_connected(G):
+    """Returns True if the graph is connected, False otherwise.
+
+    A graph is connected if, for every pair of distinct nodes, there is a
+    path between them. If there is a pair of nodes for which such path does
+    not exist, the graph is not connected (also referred to as "disconnected").
+
+    A graph consisting of a single node and no edges is connected.
+    Connectivity is undefined for the null graph (graph with no nodes).
+
+    Parameters
+    ----------
+    G : NetworkX Graph
+       An undirected graph.
+
+    Returns
+    -------
+    connected : bool
+      True if the graph is connected, False otherwise.
+
+    Raises
+    ------
+    NetworkXNotImplemented
+        If G is directed.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(4)
+    >>> print(nx.is_connected(G))
+    True
+
+    See Also
+    --------
+    is_strongly_connected
+    is_weakly_connected
+    is_semiconnected
+    is_biconnected
+    connected_components
+
+    Notes
+    -----
+    This function is for undirected graphs only. For directed graphs, use
+    :func:`is_strongly_connected` or :func:`is_weakly_connected`.
+
+    The algorithm is based on a Breadth-First Search (BFS) traversal and its
+    time complexity is $O(n + m)$, where $n$ is the number of nodes and $m$ the
+    number of edges in the graph.
+
+    """
+    n = len(G)
+    if n == 0:
+        raise nx.NetworkXPointlessConcept(
+            "Connectivity is undefined for the null graph."
+        )
+    return len(next(connected_components(G))) == n
+
+
+@not_implemented_for("directed")
+@nx._dispatchable
+def node_connected_component(G, n):
+    """Returns the set of nodes in the component of graph containing node n.
+
+    A connected component is a set of nodes that induces a subgraph of graph
+    `G` that is connected and not part of any larger connected subgraph.
+
+    A graph is connected (:func:`is_connected`) if, for every pair of distinct
+    nodes, there is a path between them. If there is a pair of nodes for
+    which such path does not exist, the graph is not connected (also referred
+    to as "disconnected").
+
+    A graph consisting of a single node and no edges is connected.
+    Connectivity is undefined for the null graph (graph with no nodes).
+
+    Parameters
+    ----------
+    G : NetworkX Graph
+       An undirected graph.
+
+    n : node label
+       A node in G
+
+    Returns
+    -------
+    comp : set
+       A set of nodes in the component of G containing node n.
+
+    Raises
+    ------
+    NetworkXNotImplemented
+        If G is directed.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (1, 2), (5, 6), (3, 4)])
+    >>> nx.node_connected_component(G, 0)  # nodes of component that contains node 0
+    {0, 1, 2}
+
+    See Also
+    --------
+    connected_components
+
+    Notes
+    -----
+    This function is for undirected graphs only.
+
+    The algorithm is based on a Breadth-First Search (BFS) traversal and its
+    time complexity is $O(n + m)$, where $n$ is the number of nodes and $m$ the
+    number of edges in the graph.
+
+    """
+    return _plain_bfs(G, len(G), n)
+
+
+def _plain_bfs(G, n, source):
+    """A fast BFS node generator"""
+    adj = G._adj
+    seen = {source}
+    nextlevel = [source]
+    while nextlevel:
+        thislevel = nextlevel
+        nextlevel = []
+        for v in thislevel:
+            for w in adj[v]:
+                if w not in seen:
+                    seen.add(w)
+                    nextlevel.append(w)
+            if len(seen) == n:
+                return seen
+    return seen