passagemath-graphs 10.5.10__cp39-cp39-macosx_14_0_arm64.whl → 10.5.43__cp39-cp39-macosx_14_0_arm64.whl

sage/graphs/connectivity.pyx

@@ -56,6 +56,7 @@ Here is what the module can do:
     :meth:`is_triconnected` | Check whether the graph is triconnected.
     :meth:`spqr_tree` | Return a SPQR-tree representing the triconnected components of the graph.
     :meth:`spqr_tree_to_graph` | Return the graph represented by the SPQR-tree `T`.
+    :meth:`minimal_separators` | Return an iterator over the minimal separators of ``G``.
 
 Methods
 -------
@@ -76,7 +77,7 @@ from sage.misc.superseded import deprecation
 from sage.sets.disjoint_set cimport DisjointSet
 
 
-def is_connected(G):
+def is_connected(G, forbidden_vertices=None):
     """
     Check whether the (di)graph is connected.
 
@@ -86,6 +87,9 @@ def is_connected(G):
 
     - ``G`` -- the input graph
 
+    - ``forbidden_vertices`` -- list (default: ``None``); set of vertices to
+      avoid during the search
+
     .. SEEALSO::
 
         - :meth:`~Graph.is_biconnected`
@@ -101,6 +105,10 @@ def is_connected(G):
         sage: G.add_edge(0,3)
         sage: is_connected(G)
         True
+        sage: is_connected(G, forbidden_vertices=[3])
+        False
+        sage: is_connected(G, forbidden_vertices=[1])
+        True
         sage: D = DiGraph({0: [1, 2], 1: [2], 3: [4, 5], 4: [5]})
         sage: is_connected(D)
         False
@@ -128,15 +136,30 @@ def is_connected(G):
     if not G.order():
         return True
 
+    forbidden = None if forbidden_vertices is None else set(forbidden_vertices)
+
     try:
-        return G._backend.is_connected()
+        return G._backend.is_connected(forbidden_vertices=forbidden)
     except AttributeError:
-        v = next(G.vertex_iterator())
-        conn_verts = list(G.depth_first_search(v, ignore_direction=True))
-        return len(conn_verts) == G.num_verts()
+        # Search for a vertex in G that is not forbidden
+        if forbidden:
+            for v in G:
+                if v not in forbidden:
+                    break
+            else:
+                # The empty graph is connected, so the graph with only forbidden
+                # vertices is also connected
+                return True
+        else:
+            v = next(G.vertex_iterator())
+        n = len(forbidden)
+        for _ in G.depth_first_search(v, ignore_direction=True,
+                                      forbidden_vertices=forbidden):
+            n += 1
+        return n == G.num_verts()
 
 
-def connected_components(G, sort=None, key=None):
+def connected_components(G, sort=None, key=None, forbidden_vertices=None):
     """
     Return the list of connected components.
 
@@ -158,6 +181,9 @@ def connected_components(G, sort=None, key=None):
       vertex as its one argument and returns a value that can be used for
       comparisons in the sorting algorithm (we must have ``sort=True``)
 
+    - ``forbidden_vertices`` -- list (default: ``None``); set of vertices to
+      avoid during the search
+
     EXAMPLES::
 
         sage: from sage.graphs.connectivity import connected_components
@@ -172,6 +198,15 @@ def connected_components(G, sort=None, key=None):
         sage: connected_components(D, sort=True, key=lambda x: -x)
         [[3, 2, 1, 0], [6, 5, 4]]
 
+    Connected components in a graph with forbidden vertices::
+
+        sage: G = graphs.PathGraph(5)
+        sage: connected_components(G, sort=True, forbidden_vertices=[2])
+        [[0, 1], [3, 4]]
+        sage: connected_components(G, sort=True,
+        ....:     forbidden_vertices=G.neighbor_iterator(2, closed=True))
+        [[0], [4]]
+
     TESTS:
 
     If ``G`` is not a Sage graph, an error is raised::
@@ -210,18 +245,19 @@ def connected_components(G, sort=None, key=None):
     if (not sort) and key:
         raise ValueError('sort keyword is False, yet a key function is given')
 
-    cdef set seen = set()
+    cdef set seen = set(forbidden_vertices) if forbidden_vertices else set()
     cdef list components = []
     for v in G:
         if v not in seen:
-            c = connected_component_containing_vertex(G, v, sort=sort, key=key)
+            c = connected_component_containing_vertex(G, v, sort=sort, key=key,
+                                                      forbidden_vertices=seen)
             seen.update(c)
             components.append(c)
     components.sort(key=lambda comp: -len(comp))
     return components
 
 
-def connected_components_number(G):
+def connected_components_number(G, forbidden_vertices=None):
     """
     Return the number of connected components.
 
@@ -229,6 +265,9 @@ def connected_components_number(G):
 
     - ``G`` -- the input graph
 
+    - ``forbidden_vertices`` -- list (default: ``None``); set of vertices to
+      avoid during the search
+
     EXAMPLES::
 
         sage: from sage.graphs.connectivity import connected_components_number
@@ -240,6 +279,8 @@ def connected_components_number(G):
         sage: D = DiGraph({0: [1, 3], 1: [2], 2: [3], 4: [5, 6], 5: [6]})
         sage: connected_components_number(D)
         2
+        sage: connected_components_number(D, forbidden_vertices=[1, 3])
+        3
 
     TESTS:
 
@@ -251,19 +292,29 @@ def connected_components_number(G):
         ...
         TypeError: the input must be a Sage graph
     """
-    return len(connected_components(G, sort=False))
+    return len(connected_components(G, sort=False,
+                                    forbidden_vertices=forbidden_vertices))
 
 
-def connected_components_subgraphs(G):
+def connected_components_subgraphs(G, forbidden_vertices=None):
     """
     Return a list of connected components as graph objects.
 
+    INPUT:
+
+    - ``G`` -- the input graph
+
+    - ``forbidden_vertices`` -- list (default: ``None``); set of vertices to
+      avoid during the search
+
     EXAMPLES::
 
         sage: from sage.graphs.connectivity import connected_components_subgraphs
         sage: G = Graph({0: [1, 3], 1: [2], 2: [3], 4: [5, 6], 5: [6]})
         sage: L = connected_components_subgraphs(G)
         sage: graphs_list.show_graphs(L)                                                # needs sage.plot
+        sage: L = connected_components_subgraphs(G, forbidden_vertices=[1, 3])
+        sage: graphs_list.show_graphs(L)                                                # needs sage.plot
         sage: D = DiGraph({0: [1, 3], 1: [2], 2: [3], 4: [5, 6], 5: [6]})
         sage: L = connected_components_subgraphs(D)
         sage: graphs_list.show_graphs(L)                                                # needs sage.plot
@@ -284,10 +335,13 @@ def connected_components_subgraphs(G):
     if not isinstance(G, GenericGraph):
         raise TypeError("the input must be a Sage graph")
 
-    return [G.subgraph(c, inplace=False) for c in connected_components(G, sort=False)]
+    return [G.subgraph(c, inplace=False)
+            for c in connected_components(G, sort=False,
+                                          forbidden_vertices=forbidden_vertices)]
 
 
-def connected_component_containing_vertex(G, vertex, sort=None, key=None):
+def connected_component_containing_vertex(G, vertex, sort=None, key=None,
+                                          forbidden_vertices=None):
     """
     Return a list of the vertices connected to vertex.
 
@@ -295,7 +349,7 @@ def connected_component_containing_vertex(G, vertex, sort=None, key=None):
 
     - ``G`` -- the input graph
 
-    - ``v`` -- the vertex to search for
+    - ``vertex`` -- the vertex to search for
 
     - ``sort`` -- boolean (default: ``None``); if ``True``, vertices inside the
       component are sorted according to the default ordering
@@ -308,6 +362,9 @@ def connected_component_containing_vertex(G, vertex, sort=None, key=None):
       vertex as its one argument and returns a value that can be used for
       comparisons in the sorting algorithm (we must have ``sort=True``)
 
+    - ``forbidden_vertices`` -- list (default: ``None``); set of vertices to
+      avoid during the search. The start ``vertex`` cannot be in this set.
+
     EXAMPLES::
 
         sage: from sage.graphs.connectivity import connected_component_containing_vertex
@@ -316,6 +373,8 @@ def connected_component_containing_vertex(G, vertex, sort=None, key=None):
         [0, 1, 2, 3]
         sage: G.connected_component_containing_vertex(0, sort=True)
         [0, 1, 2, 3]
+        sage: G.connected_component_containing_vertex(0, sort=True, forbidden_vertices=[1, 3])
+        [0]
         sage: D = DiGraph({0: [1, 3], 1: [2], 2: [3], 4: [5, 6], 5: [6]})
         sage: connected_component_containing_vertex(D, 0, sort=True)
         [0, 1, 2, 3]
@@ -370,22 +429,33 @@ def connected_component_containing_vertex(G, vertex, sort=None, key=None):
     if (not sort) and key:
         raise ValueError('sort keyword is False, yet a key function is given')
 
+    forbidden = None if forbidden_vertices is None else list(forbidden_vertices)
+
     try:
-        c = list(G._backend.depth_first_search(vertex, ignore_direction=True))
+        c = list(G._backend.depth_first_search(vertex, ignore_direction=True,
+                                               forbidden_vertices=forbidden))
     except AttributeError:
-        c = list(G.depth_first_search(vertex, ignore_direction=True))
+        c = list(G.depth_first_search(vertex, ignore_direction=True,
+                                      forbidden_vertices=forbidden))
 
     if sort:
         return sorted(c, key=key)
     return c
 
 
-def connected_components_sizes(G):
+def connected_components_sizes(G, forbidden_vertices=None):
     """
     Return the sizes of the connected components as a list.
 
     The list is sorted from largest to lower values.
 
+    INPUT:
+
+    - ``G`` -- the input graph
+
+    - ``forbidden_vertices`` -- list (default: ``None``); set of vertices to
+      avoid during the search
+
     EXAMPLES::
 
         sage: from sage.graphs.connectivity import connected_components_sizes
@@ -401,6 +471,13 @@ def connected_components_sizes(G):
         [2, 1]
         [3]
         [3]
+        sage: G = graphs.PathGraph(5)
+        sage: G.connected_components_sizes()
+        [5]
+        sage: G.connected_components_sizes(forbidden_vertices=[1])
+        [3, 1]
+        sage: G.connected_components_sizes(forbidden_vertices=[1, 3])
+        [1, 1, 1]
 
     TESTS:
 
@@ -417,7 +494,8 @@ def connected_components_sizes(G):
         raise TypeError("the input must be a Sage graph")
 
     # connected components are sorted from largest to smallest
-    return [len(cc) for cc in connected_components(G, sort=False)]
+    return [len(cc) for cc in connected_components(G, sort=False,
+                                                   forbidden_vertices=forbidden_vertices)]
 
 
 def blocks_and_cut_vertices(G, algorithm='Tarjan_Boost', sort=False, key=None):
@@ -1186,6 +1264,104 @@ def is_cut_vertex(G, u, weak=False):
     return is_vertex_cut(G, [u], weak=weak)
 
 
+def minimal_separators(G, forbidden_vertices=None):
+    r"""
+    Return an iterator over the minimal separators of ``G``.
+
+    A separator in a graph is a set of vertices whose removal increases the
+    number of connected components. In other words, a separator is a vertex
+    cut. This method implements the algorithm proposed in [BBC2000]_.
+    It computes the set `S` of minimal separators of a graph in `O(n^3)` time
+    per separator, and so overall in `O(n^3 |S|)` time.
+
+    .. WARNING::
+
+        Note that all separators are recorded during the execution of the
+        algorithm and so the memory consumption of this method might be huge.
+
+    INPUT:
+
+    - ``G`` -- an undirected graph
+
+    - ``forbidden_vertices`` -- list (default: ``None``); set of vertices to
+      avoid during the search
+
+    EXAMPLES::
+
+        sage: P = graphs.PathGraph(5)
+        sage: sorted(sorted(sep) for sep in P.minimal_separators())
+        [[1], [2], [3]]
+        sage: C = graphs.CycleGraph(6)
+        sage: sorted(sorted(sep) for sep in C.minimal_separators())
+        [[0, 2], [0, 3], [0, 4], [1, 3], [1, 4], [1, 5], [2, 4], [2, 5], [3, 5]]
+        sage: sorted(sorted(sep) for sep in C.minimal_separators(forbidden_vertices=[0]))
+        [[2], [3], [4]]
+        sage: sorted(sorted(sep) for sep in (P + C).minimal_separators())
+        [[1], [2], [3], [5, 7], [5, 8], [5, 9], [6, 8],
+         [6, 9], [6, 10], [7, 9], [7, 10], [8, 10]]
+        sage: sorted(sorted(sep) for sep in (P + C).minimal_separators(forbidden_vertices=[10]))
+        [[1], [2], [3], [6], [7], [8]]
+
+        sage: G = graphs.RandomGNP(10, .3)
+        sage: all(G.is_vertex_cut(sep) for sep in G.minimal_separators())
+        True
+
+    TESTS::
+
+        sage: list(Graph().minimal_separators())
+        []
+        sage: list(Graph(1).minimal_separators())
+        []
+        sage: list(Graph(2).minimal_separators())
+        []
+        sage: from sage.graphs.connectivity import minimal_separators
+        sage: list(minimal_separators(DiGraph()))
+        Traceback (most recent call last):
+        ...
+        ValueError: the input must be an undirected graph
+    """
+    from sage.graphs.graph import Graph
+    if not isinstance(G, Graph):
+        raise ValueError("the input must be an undirected graph")
+
+    if forbidden_vertices is not None and G.order() >= 3:
+        # Build the subgraph with active vertices
+        G = G.subgraph(set(G).difference(forbidden_vertices), immutable=True)
+
+    if G.order() < 3:
+        return
+    if not G.is_connected():
+        for cc in G.connected_components(sort=False):
+            if len(cc) > 2:
+                yield from minimal_separators(G.subgraph(cc))
+        return
+
+    # Initialization - identify separators needing further inspection
+    cdef list to_explore = []
+    for v in G:
+        # iterate over the connected components of G \ N[v]
+        for comp in G.connected_components(sort=False, forbidden_vertices=G.neighbor_iterator(v, closed=True)):
+            # The vertex boundary of comp in G is a separator
+            nh = G.vertex_boundary(comp)
+            if nh:
+                to_explore.append(frozenset(nh))
+
+    # Generation of all minimal separators
+    cdef set separators = set()
+    while to_explore:
+        sep = to_explore.pop()
+        if sep in separators:
+            continue
+        yield set(sep)
+        separators.add(sep)
+        for v in sep:
+            # iterate over the connected components of G \ sep \ N(v)
+            for comp in G.connected_components(sort=False, forbidden_vertices=sep.union(G.neighbor_iterator(v))):
+                nh = G.vertex_boundary(comp)
+                if nh:
+                    to_explore.append(frozenset(nh))
+
+
 def edge_connectivity(G,
                       value_only=True,
                       implementation=None,