sagemathgh-41245: Add Caterpillar() graph generator

The [caterpillar trees](https://en.wikipedia.org/wiki/Caterpillar_tree)
form a well-known graph class but they currently cannot be easily
generated using Sage despite the fact that a caterpillar can be
succinctly described using its left-to-right degree sequence or (even
more succinctly) its [spine](https://arxiv.org/pdf/1810.11744).

This PR adds a function to generate a caterpillar given its spine, e.g.
`Caterpillar([2,1,1])` is [this
graph](https://houseofgraphs.org/graphs/54336) named $T_{4,3,3}$ after
its degree sequence. I opted to use spines instead of degree sequences
because it leads to a simpler implementation.

I think it's worth to have this in Sage because it allows users to
quickly obtain some common graphs by simply entering a list of numbers.
While the graph generation process is fairly trivial, [producing nice
embeddings of
caterpillars](https://stackoverflow.com/questions/68791175/how-to-draw-
caterpillar-trees-in-networkx-beautifully) is not.

### 📝 Checklist

- [x] I have created tests covering the changes.
- [ ] I have updated the documentation and checked the documentation
preview.

URL: sagemath#41245
Reported by: Lennard Hofmann
Reviewer(s): David Coudert

Author: Release Manager

build/pkgs/configure/checksums.ini

@@ -1,3 +1,3 @@
 tarball=configure-VERSION.tar.gz
-sha1=8b7aba4104cd77481cfc7602c26382d1788ecd2e
-sha256=99c4fd081a93073924a90d7b8af2dbb6fe23d8b4602115511fa1399080667023
+sha1=ea19ffc13676a6e4cc14c10fe88e624189463476
+sha256=148e79af8007b4bfe47bfad90db4bc048302e0e8382218496f0642ba105d10c4

build/pkgs/configure/package-version.txt

@@ -1 +1 @@
-4119163dc533ea5446f33e48918fd637a8e856e2
+78052986eb87204ac91589ff1019367598f7d014

src/sage/graphs/generators/trees.pyx

@@ -274,6 +274,102 @@ def FibonacciTree(n):
     return T
 
 
+def Caterpillar(spine):
+    r"""
+    Return the caterpillar tree with given spine sequence.
+
+    A caterpillar tree consists of leaves attached to a path (the "spine").
+
+    INPUT:
+
+    - ``spine`` -- list of nonnegative integers in the form
+       `[a_1, a_2, \dots, a_n]`, where `a_i` is the number of leaves adjacent
+       to the `i`-th vertex on the spine (except for the first and last vertex,
+       which have `a_1 + 1` and `a_n + 1` leaf-neighbors, respectively)
+
+    OUTPUT:
+
+    A caterpillar tree of diameter `n+1` on `n + 2 + \sum_{i=1}^n a_i` vertices,
+    `n` of which are not leaves.
+
+    PLOTTING: Upon construction, the position dictionary is filled to override
+    the spring-layout algorithm if the returned graph does not have too many
+    vertices. The spine vertices are positioned on a straight line together
+    with two leaves at its ends. Every edge in the drawing has unit length.
+
+    EXAMPLES:
+
+    Caterpillars with all-zero spine sequence are paths::
+
+        sage: graphs.Caterpillar([]).is_isomorphic(graphs.PathGraph(2))
+        True
+        sage: graphs.Caterpillar([0]).is_isomorphic(graphs.PathGraph(3))
+        True
+        sage: graphs.Caterpillar([0, 0]).is_isomorphic(graphs.PathGraph(4))
+        True
+
+    Caterpillars with singleton spine are stars::
+
+        sage: graphs.Caterpillar([1]).is_isomorphic(graphs.StarGraph(3))
+        True
+        sage: graphs.Caterpillar([2]).is_isomorphic(graphs.StarGraph(4))
+        True
+        sage: graphs.Caterpillar([3]).is_isomorphic(graphs.StarGraph(5))
+        True
+
+    Distinct spine sequences can yield isomorphic caterpillars::
+
+        sage: graphs.Caterpillar([1,1,2]).is_isomorphic(graphs.Caterpillar([2,1,1]))
+        True
+
+    TESTS:
+
+    Generated graphs have diameter ``len(spine) + 1``::
+
+        sage: graphs.Caterpillar([7]).diameter()
+        2
+        sage: graphs.Caterpillar([2,2,2,2]).diameter()
+        5
+        sage: graphs.Caterpillar([0,1,1,0]).diameter()
+        5
+    """
+    spine = list(spine)
+    cdef int spine_len = len(spine)
+    cdef int n_vertices = spine_len + 2 + sum(spine)
+    T = Graph(n_vertices, name=f"Caterpillar({','.join(map(str, spine))})")
+
+    # add spine
+    for i in range(spine_len - 1):
+        T._backend.add_edge(i, i + 1, None, False)
+
+    # add a leaf at both ends of the spine
+    T._backend.add_edge(spine_len + 1, 0, None, False)
+    if spine:
+        T._backend.add_edge(spine_len - 1, spine_len, None, False)
+
+    # add leaves
+    cdef int v = spine_len + 2
+    for i, d in enumerate(spine):
+        for j in range(d):
+            T._backend.add_edge(i, v + j, None, False)
+        v += d
+
+    # add embedding
+    cdef int max_leaves = max(spine, default=0)
+    if (spine_len < 10 and max_leaves < 3) or (spine_len < 6 and max_leaves < 7):
+        T._pos = {spine_len + 1: (-1, 0), spine_len: (spine_len, 0)}
+        radius = 0.3
+        v = spine_len + 2
+        for x, d in enumerate(spine):
+            T._pos[x] = (x, 0)
+            mid = v + d // 2
+            T._line_embedding(range(v, mid), first=(x - radius, 1), last=(x + radius, 1))
+            T._line_embedding(range(mid, v + d), first=(x - radius, -1), last=(x + radius, -1))
+            v += d
+
+    return T
+
+
 def RandomLobster(n, p, q, seed=None):
     r"""
     Return a random lobster.

src/sage/graphs/graph_generators.py

@@ -383,6 +383,7 @@ def wrap_name(x):
 __append_to_doc(
     ["BalancedTree",
      "FibonacciTree",
+     "Caterpillar",
      "RandomLobster",
      "RandomTree",
      "RandomTreePowerlaw",
@@ -2880,6 +2881,7 @@ def quadrangulations(self, order, minimum_degree=None, minimum_connectivity=None
     BalancedTree = staticmethod(gen_trees.BalancedTree)
     FibonacciTree = staticmethod(gen_trees.FibonacciTree)
     nauty_gentreeg = staticmethod(gen_trees.nauty_gentreeg)
+    Caterpillar = staticmethod(gen_trees.Caterpillar)
     RandomLobster = staticmethod(gen_trees.RandomLobster)
     RandomTreePowerlaw = staticmethod(gen_trees.RandomTreePowerlaw)
     RandomTree = staticmethod(gen_trees.RandomTree)