sagemathgh-38299: graphs: add implementation of slice decomposition v…

…ia an extended LexBFS algorithm

    
<!-- ^ Please provide a concise and informative title. -->
<!-- ^ Don't put issue numbers in the title, do this in the PR
description below. -->
<!-- ^ For example, instead of "Fixes sagemath#12345" use "Introduce new method
to calculate 1 + 2". -->
<!-- v Describe your changes below in detail. -->
<!-- v Why is this change required? What problem does it solve? -->
<!-- v If this PR resolves an open issue, please link to it here. For
example, "Fixes sagemath#12345". -->

This PR implements a new graph decomposition: slice decomposition.
Precise definition and a description of the algorithm can be found in
[TCHP2008 (section 3.2 & 3.3)](https://arxiv.org/pdf/0710.3901v3).

I implemented a new method (only for undirected graphs) called
`slice_decomposition`. It returns a new class `SliceDecompostion`, with
methods to retrieve the information about the computed slice
decomposition.
The code is in a new file:
`graph_decompositions/slice_decomposition.pyx`.

 The actual computation is done with a new function called
`extended_lex_BFS` which only works for undirected graphs. It is very
close to the previous `lex_BFS_fast_short_digraph` from
`traversals.pyx`, the difference being that the new function works with
the `CGraph` directly (no conversion needed to `short_digraph` anymore)
and it computes more information (lexicographic labels and length of
x-slices). The complexity of the two algorithms are the same.
 So I removed `lex_BFS_fast_short_digraph` from `traversals.pyx` and
used `extended_lex_BFS` instead for the "fast" version of the `lex_BFS`
method.

I took the opportunity to factorize the code between `lex_BFS` ("slow"
version), `lex_DFS`, `lex_UP` and `lex_DOWN`
in `traversals.pyx`: there is no more conversion to `short_digraph` and
they all call the same common function
(remark: i was not able to put the doc in common, so there is still some
repetition between the doc of these methods)


### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

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

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - sagemath#12345: short description why this is a dependency -->
<!-- - sagemath#34567: ... -->
    
URL: sagemath#38299
Reported by: cyrilbouvier
Reviewer(s): cyrilbouvier, David Coudert

src/doc/en/reference/graphs/index.rst

@@ -98,6 +98,7 @@ Libraries of algorithms
    sage/graphs/graph_decompositions/bandwidth
    sage/graphs/graph_decompositions/cutwidth
    sage/graphs/graph_decompositions/graph_products
+   sage/graphs/graph_decompositions/slice_decomposition
    sage/graphs/graph_decompositions/modular_decomposition
    sage/graphs/graph_decompositions/clique_separators
    sage/graphs/convexity_properties

src/doc/en/reference/references/index.rst

@@ -6405,7 +6405,7 @@ REFERENCES:
 
 .. [TCHP2008] Marc Tedder, Derek Corneil, Michel Habib and Christophe Paul,
               *Simple, linear-time modular decomposition*, 2008.
-              :arxiv:`0710.3901`.
+              :arxiv:`0710.3901v3`.
 
 .. [Tee1997] Tee, Garry J. "Continuous branches of inverses of the 12
              Jacobi elliptic functions for real

src/sage/graphs/graph.py

@@ -10200,6 +10200,7 @@ def bipartite_double(self, extended=False):
     from sage.graphs.graph_decompositions.clique_separators import atoms_and_clique_separators
     from sage.graphs.graph_decompositions.bandwidth import bandwidth
     from sage.graphs.graph_decompositions.cutwidth import cutwidth
+    from sage.graphs.graph_decompositions.slice_decomposition import slice_decomposition
     matching_polynomial = LazyImport('sage.graphs.matchpoly', 'matching_polynomial', at_startup=True)
     from sage.graphs.cliquer import all_max_clique as cliques_maximum
     from sage.graphs.cliquer import all_cliques

src/sage/graphs/graph_decompositions/slice_decomposition.pxd

@@ -0,0 +1,17 @@
+from libcpp.vector cimport vector
+
+from sage.structure.sage_object cimport SageObject
+from sage.graphs.base.c_graph cimport CGraph
+
+cdef void extended_lex_BFS(
+        CGraph cg, vector[int] &sigma, vector[int] *sigma_inv,
+        int initial_v_int, vector[int] *pred, vector[size_t] *xslice_len,
+        vector[vector[int]] *lex_label) except *
+
+cdef class SliceDecomposition(SageObject):
+    cdef tuple sigma
+    cdef dict sigma_inv
+    cdef vector[size_t] xslice_len
+    cdef dict lex_label
+    cdef object _graph_class
+    cdef object _underlying_graph