gh-35864: Return connected subgraphs with exactly k vertices
    
Fixes #35857 -- This PR adds a parameter to
`connected_subgraph_iterator` so it returns only the subgraphs of order
k.
- Added an optional parameter 'exactly_k' to connected_subgraph_iterator
- when exactly_k is True return only graphs of size k.
- As the connected subgraphs are built up one vertex at a time
(basically a DFS) we don't lose much if we are looking for subgraphs
that are small in comparison to the original graph.

<!-- Please provide a concise, informative and self-explanatory title.
-->
<!-- Don't put issue numbers in the title. Put it in the Description
below. -->
<!-- For example, instead of "Fixes #12345", use "Add a new method to
multiply two integers" -->

### 📚 Description

<!-- Describe your changes here in detail. -->
<!-- Why is this change required? What problem does it solve? -->
<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes #12345". -->
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. It should be `[x]` not `[x
]`. -->

- [x] The title is concise, informative, and self-explanatory.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [x] I have created tests covering the changes.
- [x] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on
- #12345: short description why this is a dependency
- #34567: ...
-->

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: #35864
Reported by: deinst
Reviewer(s): David Coudert

Author: Release Manager

src/sage/graphs/base/static_dense_graph.pyx

@@ -745,7 +745,8 @@ def connected_full_subgraphs(G, edges_only=False, labels=False,
 
 
 def connected_subgraph_iterator(G, k=None, bint vertices_only=False,
-                                edges_only=False, labels=False, induced=True):
+                                edges_only=False, labels=False, induced=True,
+                                exactly_k=False):
     r"""
     Return an terator over the induced connected subgraphs of order at most `k`.
 
@@ -783,6 +784,10 @@ def connected_subgraph_iterator(G, k=None, bint vertices_only=False,
       connected sub(di)graph only or also non-induced sub(di)graphs.
       This parameter can be set to ``False`` for simple (di)graphs only.
 
+    - ``exactly_k`` -- boolean (default: ``False``); ``True`` if we only
+      return graphs of order `k`, ``False`` if we return graphs of order
+      at most `k`.
+
     EXAMPLES::
 
         sage: G = DiGraph([(1, 2), (2, 3), (3, 4), (4, 2)])
@@ -811,6 +816,8 @@ def connected_subgraph_iterator(G, k=None, bint vertices_only=False,
          Subgraph of (): Digraph on 1 vertex,
          Subgraph of (): Digraph on 2 vertices,
          Subgraph of (): Digraph on 1 vertex]
+        sage: list(G.connected_subgraph_iterator(k=3, vertices_only=True, exactly_k=True))
+        [[1, 2, 3], [1, 2, 4], [2, 3, 4]]
         sage: list(G.connected_subgraph_iterator(k=2, vertices_only=True))
         [[1], [1, 2], [2], [2, 3], [2, 4], [3], [3, 4], [4]]
 
@@ -921,14 +928,15 @@ def connected_subgraph_iterator(G, k=None, bint vertices_only=False,
         sig_check()
 
         vertices = [int_to_vertex[u]]
-        if vertices_only:
-            yield vertices
-        else:
-            H = G.subgraph(vertices)
-            if edges_only:
-                yield H.edges(sort=False, labels=labels)
+        if not exactly_k or mk == 1:
+            if vertices_only:
+                yield vertices
             else:
-                yield H
+                H = G.subgraph(vertices)
+                if edges_only:
+                    yield H.edges(sort=False, labels=labels)
+                else:
+                    yield H
 
         # We initialize the loop with vertices u in current, {u+1, ..., n-1}
         # in left, and N(u) in boundary
@@ -970,45 +978,46 @@ def connected_subgraph_iterator(G, k=None, bint vertices_only=False,
                 # We yield that new subset
                 vertices = [int_to_vertex[a] for a in range(u, n)
                             if bitset_in(stack.rows[level], a)]
-                if vertices_only:
-                    yield vertices
-                else:
-                    H = G.subgraph(vertices)
-                    if induced:
-                        if edges_only:
-                            yield H.edges(sort=False, labels=labels)
-                        else:
-                            yield H
+                if not exactly_k or bitset_len(current) == mk - 1:
+                    if vertices_only:
+                        yield vertices
                     else:
-                        # We use a decomposition into biconnected components to
-                        # work on smaller graphs.
-                        if H.is_directed():
-                            blocks = H.to_undirected().blocks_and_cut_vertices()[0]
-                        else:
-                            blocks = H.blocks_and_cut_vertices()[0]
-                        if len(blocks) == 1:
-                            # H is strongly connected or biconnected
-                            yield from connected_full_subgraphs(H, edges_only=edges_only,
-                                                                labels=labels)
+                        H = G.subgraph(vertices)
+                        if induced:
+                            if edges_only:
+                                yield H.edges(sort=False, labels=labels)
+                            else:
+                                yield H
                         else:
-                            L = []
-                            for bloc in blocks:
-                                if len(bloc) == 2:
-                                    bb = [[e] for e in H.edge_boundary(bloc, bloc, labels=labels)]
-                                    if len(bb) == 2:
-                                        # H is directed with edges (u, v) and (v, u)
-                                        bb.append(H.edge_boundary(bloc, bloc, labels=labels))
-                                    L.append(bb)
-                                else:
-                                    L.append(connected_full_subgraphs(H.subgraph(vertices=bloc),
-                                                                      edges_only=True, labels=labels))
-
-                            for edges in product(*L):
-                                good_edges = flatten(edges, ltypes=list)
-                                if edges_only:
-                                    yield list(good_edges)
-                                else:
-                                    yield H.subgraph(vertices=H, edges=good_edges)
+                            # We use a decomposition into biconnected components to
+                            # work on smaller graphs.
+                            if H.is_directed():
+                                blocks = H.to_undirected().blocks_and_cut_vertices()[0]
+                            else:
+                                blocks = H.blocks_and_cut_vertices()[0]
+                            if len(blocks) == 1:
+                                # H is strongly connected or biconnected
+                                yield from connected_full_subgraphs(H, edges_only=edges_only,
+                                                                    labels=labels)
+                            else:
+                                L = []
+                                for bloc in blocks:
+                                    if len(bloc) == 2:
+                                        bb = [[e] for e in H.edge_boundary(bloc, bloc, labels=labels)]
+                                        if len(bb) == 2:
+                                            # H is directed with edges (u, v) and (v, u)
+                                            bb.append(H.edge_boundary(bloc, bloc, labels=labels))
+                                        L.append(bb)
+                                    else:
+                                        L.append(connected_full_subgraphs(H.subgraph(vertices=bloc),
+                                                                          edges_only=True, labels=labels))
+
+                                for edges in product(*L):
+                                    good_edges = flatten(edges, ltypes=list)
+                                    if edges_only:
+                                        yield list(good_edges)
+                                    else:
+                                        yield H.subgraph(vertices=H, edges=good_edges)
 
             else:
                 # We cannot extend the current subset, either due to a lack of