passagemath-graphs 10.5.43__cp39-cp39-musllinux_1_2_aarch64.whl

sage/graphs/generators/families.py

@@ -0,0 +1,4749 @@
+# sage_setup: distribution = sagemath-graphs
+r"""
+Various families of graphs
+
+The methods defined here appear in :mod:`sage.graphs.graph_generators`.
+"""
+
+# ****************************************************************************
+#       Copyright (C) 2006 Robert L. Miller <rlmillster@gmail.com>
+#                          Emily A. Kirkman
+#                     2009 Michael C. Yurko <myurko@gmail.com>
+#                     2016 Rowan Schrecker <rowan.schrecker@hertford.ox.ac.uk>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
+from copy import copy
+from math import sin, cos, pi
+from sage.graphs.graph import Graph
+from itertools import combinations
+import subprocess
+
+
+def JohnsonGraph(n, k):
+    r"""
+    Return the Johnson graph with parameters `n, k`.
+
+    Johnson graphs are a special class of undirected graphs defined from systems
+    of sets. The vertices of the Johnson graph `J(n,k)` are the `k`-element
+    subsets of an `n`-element set; two vertices are adjacent when they meet in a
+    `(k-1)`-element set. See the :wikipedia:`Johnson_graph` for more
+    information.
+
+    EXAMPLES:
+
+    The Johnson graph is a Hamiltonian graph::
+
+        sage: g = graphs.JohnsonGraph(7, 3)
+        sage: g.is_hamiltonian()                                                        # needs sage.numerical.mip
+        True
+
+    Every Johnson graph is vertex transitive::
+
+        sage: g = graphs.JohnsonGraph(6, 4)
+        sage: g.is_vertex_transitive()                                                  # needs sage.groups
+        True
+
+    The complement of the Johnson graph `J(n,2)` is isomorphic to the Kneser
+    Graph `K(n,2)`.  In particular the complement of `J(5,2)` is isomorphic to
+    the Petersen graph.::
+
+        sage: g = graphs.JohnsonGraph(5,2)
+        sage: g.complement().is_isomorphic(graphs.PetersenGraph())
+        True
+    """
+
+    g = Graph(name="Johnson graph with parameters "+str(n)+","+str(k))
+    from sage.combinat.subset import Set, Subsets
+
+    S = Set(range(n))
+    g.add_vertices(Subsets(S, k))
+
+    for sub in Subsets(S, k-1):
+        elem_left = S - sub
+        for i in elem_left:
+            for j in elem_left:
+                if j <= i:
+                    continue
+                g.add_edge(sub + Set([i]), sub + Set([j]))
+
+    return g
+
+
+def KneserGraph(n, k):
+    r"""
+    Return the Kneser Graph with parameters `n, k`.
+
+    The Kneser Graph with parameters `n,k` is the graph
+    whose vertices are the `k`-subsets of `[0,1,\dots,n-1]`, and such
+    that two vertices are adjacent if their corresponding sets
+    are disjoint.
+
+    For example, the Petersen Graph can be defined
+    as the Kneser Graph with parameters `5,2`.
+
+    EXAMPLES::
+
+        sage: KG = graphs.KneserGraph(5,2)
+        sage: sorted(KG.vertex_iterator(), key=str)
+        [{1, 2}, {1, 3}, {1, 4}, {1, 5}, {2, 3}, {2, 4}, {2, 5},
+         {3, 4}, {3, 5}, {4, 5}]
+        sage: P = graphs.PetersenGraph()
+        sage: P.is_isomorphic(KG)
+        True
+
+    TESTS::
+
+        sage: KG = graphs.KneserGraph(0,0)
+        Traceback (most recent call last):
+        ...
+        ValueError: Parameter n should be a strictly positive integer
+        sage: KG = graphs.KneserGraph(5,6)
+        Traceback (most recent call last):
+        ...
+        ValueError: Parameter k should be a strictly positive integer inferior to n
+    """
+
+    if n <= 0:
+        raise ValueError("Parameter n should be a strictly positive integer")
+    if k <= 0 or k > n:
+        raise ValueError("Parameter k should be a strictly positive integer inferior to n")
+
+    g = Graph(name="Kneser graph with parameters {},{}".format(n, k))
+
+    from sage.combinat.subset import Subsets
+    S = Subsets(n, k)
+    if 2 * k > n:
+        g.add_vertices(S)
+
+    s0 = S.underlying_set()    # {1,2,...,n}
+    for s in S:
+        for t in Subsets(s0.difference(s), k):
+            g.add_edge(s, t)
+
+    return g
+
+
+def FurerGadget(k, prefix=None):
+    r"""
+    Return a Furer gadget of order ``k`` and their coloring.
+
+    Construct the Furer gadget described in [CFI1992]_,
+    a graph composed by a middle layer of `2^(k-1)` nodes
+    and two sets of nodes `(a_0, ... , a_{k-1})` and
+    `(b_0, ... , b_{k-1})`.
+    Each node in the middle is connected to either `a_i` or `b_i`,
+    for each i in [0,k[.
+    To read about the complete construction, see [CFI1992]_.
+    The returned coloring colors the middle section with one color, and
+    then each pair `(a_i, b_i)` with another color.
+    Since this method is mainly used to create Furer gadgets for the
+    Cai-Furer-Immerman construction, returning gadgets that don't
+    always have the same vertex labels is important, that's why there is
+    a parameter to manually set a prefix to be appended to each vertex label.
+
+    INPUT:
+
+    - ``k`` -- the order of the returned Furer gadget, greater than 0
+
+    - ``prefix`` -- prefix of to be appended to each vertex label,
+      so as to individualise the returned Furer gadget; must be comparable for
+      equality and hashable
+
+    OUTPUT:
+
+    - ``G`` -- the Furer gadget of order ``k``
+
+    - ``coloring`` -- list of list of vertices, representing the
+      partition induced by the coloring of ``G``'s vertices
+
+    EXAMPLES:
+
+    Furer gadget of order 3, without any prefix. ::
+
+        sage: G, p = graphs.FurerGadget(3)
+        sage: sorted(G, key=str)
+        [(), (0, 'a'), (0, 'b'), (0, 1), (0, 2),
+         (1, 'a'), (1, 'b'), (1, 2), (2, 'a'), (2, 'b')]
+        sage: sorted(G.edge_iterator(), key=str)
+        [((), (0, 'b'), None), ((), (1, 'b'), None),
+         ((), (2, 'b'), None), ((0, 'b'), (1, 2), None),
+         ((0, 1), (0, 'a'), None), ((0, 1), (1, 'a'), None),
+         ((0, 1), (2, 'b'), None), ((0, 2), (0, 'a'), None),
+         ((0, 2), (1, 'b'), None), ((0, 2), (2, 'a'), None),
+         ((1, 2), (1, 'a'), None), ((1, 2), (2, 'a'), None)]
+
+    Furer gadget of order 3, with a prefix. ::
+
+        sage: G, p = graphs.FurerGadget(3, 'Prefix')
+        sage: sorted(G, key=str)
+        [('Prefix', ()), ('Prefix', (0, 'a')), ('Prefix', (0, 'b')),
+         ('Prefix', (0, 1)), ('Prefix', (0, 2)), ('Prefix', (1, 'a')),
+         ('Prefix', (1, 'b')), ('Prefix', (1, 2)), ('Prefix', (2, 'a')),
+         ('Prefix', (2, 'b'))]
+        sage: sorted(G.edge_iterator(), key=str)
+        [(('Prefix', ()), ('Prefix', (0, 'b')), None),
+         (('Prefix', ()), ('Prefix', (1, 'b')), None),
+         (('Prefix', ()), ('Prefix', (2, 'b')), None),
+         (('Prefix', (0, 'b')), ('Prefix', (1, 2)), None),
+         (('Prefix', (0, 1)), ('Prefix', (0, 'a')), None),
+         (('Prefix', (0, 1)), ('Prefix', (1, 'a')), None),
+         (('Prefix', (0, 1)), ('Prefix', (2, 'b')), None),
+         (('Prefix', (0, 2)), ('Prefix', (0, 'a')), None),
+         (('Prefix', (0, 2)), ('Prefix', (1, 'b')), None),
+         (('Prefix', (0, 2)), ('Prefix', (2, 'a')), None),
+         (('Prefix', (1, 2)), ('Prefix', (1, 'a')), None),
+         (('Prefix', (1, 2)), ('Prefix', (2, 'a')), None)]
+    """
+    from itertools import repeat as rep, chain
+    if k <= 0:
+        raise ValueError("The order of the Furer gadget must be greater than zero")
+    G = Graph()
+    V_a = list(enumerate(rep('a', k)))
+    V_b = list(enumerate(rep('b', k)))
+    if prefix is not None:
+        V_a = list(zip(rep(prefix, k), V_a))
+        V_b = list(zip(rep(prefix, k), V_b))
+    G.add_vertices(V_a)
+    G.add_vertices(V_b)
+    powerset = list(chain.from_iterable(combinations(range(k), r) for r in range(0, k + 1, 2)))
+    if prefix is not None:
+        G.add_edges(chain.from_iterable([((prefix, s), (prefix, (i, 'a'))) for i in s] for s in powerset))
+        G.add_edges(chain.from_iterable([((prefix, s), (prefix, (i, 'b'))) for i in range(k) if i not in s] for s in powerset))
+    else:
+        G.add_edges(chain.from_iterable([(s, (i, 'a')) for i in s] for s in powerset))
+        G.add_edges(chain.from_iterable([(s, (i, 'b')) for i in range(k) if i not in s] for s in powerset))
+    partition = []
+    for i in range(k):
+        partition.append([V_a[i], V_b[i]])
+    if prefix is not None:
+        powerset = [(prefix, s) for s in powerset]
+    partition.append(powerset)
+    return G, partition
+
+
+def CaiFurerImmermanGraph(G, twisted=False):
+    r"""
+    Return the a Cai-Furer-Immerman graph from `G`, possibly a twisted
+    one, and a partition of its nodes.
+
+    A Cai-Furer-Immerman graph from/on `G` is a graph created by
+    applying the transformation described in [CFI1992]_ on a graph
+    `G`, that is substituting every vertex v in `G` with a
+    Furer gadget `F(v)` of order d equal to the degree of the vertex,
+    and then substituting every edge `(v,u)` in `G`
+    with a pair of edges, one connecting the two "a" nodes of
+    `F(v)` and `F(u)` and the other their two "b" nodes.
+    The returned coloring of the vertices is made by the union of the
+    colorings of each single Furer gadget, individualised for each
+    vertex of `G`.
+    To understand better what these "a" and "b" nodes are, see the
+    documentation on  Furer gadgets.
+
+    Furthermore, this method can apply what is described in the paper
+    mentioned above as a "twist" on an edge, that is taking only one of
+    the pairs of edges introduced in the new graph and swap two of their
+    extremes, making each edge go from an "a" node to a "b" node.
+    This is only doable if the original graph G is connected.
+
+    A CaiFurerImmerman graph on a graph with no balanced vertex
+    separators smaller than s and its twisted version
+    cannot be distinguished by k-WL for any k < s.
+
+    INPUT:
+
+    - ``G`` -- an undirected graph on which to construct the
+      Cai-Furer-Immerman graph
+
+    - ``twisted`` -- a boolean indicating if the version to construct
+      is a twisted one or not
+
+    OUTPUT:
+
+    - ``H`` -- the Cai-Furer-Immerman graph on ``G``
+
+    - ``coloring`` -- list of list of vertices, representing the
+      partition induced by the coloring on ``H``
+
+    EXAMPLES:
+
+    CaiFurerImmerman graph with no balanced vertex separator smaller
+    than 2 ::
+
+        sage: G = graphs.CycleGraph(4)
+        sage: CFI, p = graphs.CaiFurerImmermanGraph(G)
+        sage: sorted(CFI, key=str)
+        [(0, ()), (0, (0, 'a')), (0, (0, 'b')), (0, (0, 1)), (0, (1, 'a')),
+         (0, (1, 'b')), (1, ()), (1, (0, 'a')), (1, (0, 'b')), (1, (0, 1)),
+         (1, (1, 'a')), (1, (1, 'b')), (2, ()), (2, (0, 'a')), (2, (0, 'b')),
+         (2, (0, 1)), (2, (1, 'a')), (2, (1, 'b')), (3, ()), (3, (0, 'a')),
+         (3, (0, 'b')), (3, (0, 1)), (3, (1, 'a')), (3, (1, 'b'))]
+        sage: sorted(CFI.edge_iterator(), key=str)
+        [((0, ()), (0, (0, 'b')), None),
+         ((0, ()), (0, (1, 'b')), None),
+         ((0, (0, 'a')), (1, (0, 'a')), None),
+         ((0, (0, 'b')), (1, (0, 'b')), None),
+         ((0, (0, 1)), (0, (0, 'a')), None),
+         ((0, (0, 1)), (0, (1, 'a')), None),
+         ((0, (1, 'a')), (3, (0, 'a')), None),
+         ((0, (1, 'b')), (3, (0, 'b')), None),
+         ((1, ()), (1, (0, 'b')), None),
+         ((1, ()), (1, (1, 'b')), None),
+         ((1, (0, 1)), (1, (0, 'a')), None),
+         ((1, (0, 1)), (1, (1, 'a')), None),
+         ((1, (1, 'a')), (2, (0, 'a')), None),
+         ((1, (1, 'b')), (2, (0, 'b')), None),
+         ((2, ()), (2, (0, 'b')), None),
+         ((2, ()), (2, (1, 'b')), None),
+         ((2, (0, 1)), (2, (0, 'a')), None),
+         ((2, (0, 1)), (2, (1, 'a')), None),
+         ((2, (1, 'a')), (3, (1, 'a')), None),
+         ((2, (1, 'b')), (3, (1, 'b')), None),
+         ((3, ()), (3, (0, 'b')), None),
+         ((3, ()), (3, (1, 'b')), None),
+         ((3, (0, 1)), (3, (0, 'a')), None),
+         ((3, (0, 1)), (3, (1, 'a')), None)]
+    """
+    isConnected = G.is_connected()
+    newG = Graph()
+    total_partition = []
+    edge_index = {}
+    for v in G:
+        Fk, p = FurerGadget(G.degree(v), v)
+        total_partition += p
+        newG = newG.union(Fk)
+        edge_index[v] = 0
+    for v, u in G.edge_iterator(labels=False):
+        i = edge_index[v]
+        edge_index[v] += 1
+        j = edge_index[u]
+        edge_index[u] += 1
+        edge_va = (v, (i, 'a'))
+        edge_vb = (v, (i, 'b'))
+        edge_ua = (u, (j, 'a'))
+        edge_ub = (u, (j, 'b'))
+        if isConnected and twisted:
+            temp = edge_ua
+            edge_ua = edge_ub
+            edge_ub = temp
+            isConnected = False
+        newG.add_edge(edge_va, edge_ua)
+        newG.add_edge(edge_vb, edge_ub)
+    if twisted and G.is_connected():
+        s = " twisted"
+    else:
+        s = ""
+    newG.name("CaiFurerImmerman" + s + " graph constructed from a " + G.name())
+    return newG, total_partition
+
+
+def EgawaGraph(p, s):
+    r"""
+    Return the Egawa graph with parameters `p`, `s`.
+
+    Egawa graphs are a peculiar family of graphs devised by Yoshimi
+    Egawa in  [Ega1981]_ .
+    The Shrikhande graph is a special case of this family of graphs,
+    with parameters `(1,0)`.
+    All the graphs in this family are not recognizable by 1-WL
+    (Weisfeiler Lehamn algorithm of the first order) and 2-WL, that is
+    their orbits are not correctly returned by k-WL for k lower than 3.
+
+    Furthermore, all the graphs in this family are distance-regular, but
+    they are not distance-transitive if `p \neq 0`.
+
+    The Egawa graph with parameters `(0, s)` is isomorphic to the
+    Hamming graph with parameters `(s, 4)`, when the underlying
+    set of the Hamming graph is `[0,1,2,3]`
+
+    INPUT:
+
+    - ``p`` -- power to which the graph named `Y` in the reference
+      provided above will be raised
+
+    - ``s`` -- power to which the graph named `X` in the reference
+      provided above will be raised
+
+    OUTPUT:
+
+    - ``G`` -- the Egawa graph with parameters (p,s)
+
+    EXAMPLES:
+
+    Every Egawa graph is distance regular.  ::
+
+        sage: g = graphs.EgawaGraph(1, 2)
+        sage: g.is_distance_regular()
+        True
+
+    An Egawa graph with parameters (0,s) is isomorphic to the Hamming
+    graph with parameters (s, 4).  ::
+
+        sage: g = graphs.EgawaGraph(0, 4)
+        sage: g.is_isomorphic(graphs.HammingGraph(4,4))
+        True
+    """
+    from sage.graphs.generators.basic import CompleteGraph
+    from itertools import product, chain, repeat
+    g = Graph(name="Egawa Graph with parameters " + str(p) + "," + str(s), multiedges=False)
+    X = CompleteGraph(4)
+    Y = Graph('O?Wse@UgqqT_LUebWkbT_')
+    g.add_vertices(product(*chain(repeat(Y, p), repeat(X, s))))
+    for v in g:
+        for i in range(p):
+            prefix = v[:i]
+            suffix = v[i+1:]
+            for el in Y.neighbor_iterator(v[i]):
+                u = prefix + (el,) + suffix
+                g.add_edge(v, u)
+        for i in range(p, s + p):
+            prefix = v[:i]
+            suffix = v[i+1:]
+            for el in X:
+                if el == v[i]:
+                    continue
+                u = prefix + (el,) + suffix
+                g.add_edge(v, u)
+    return g
+
+
+def HammingGraph(n, q, X=None):
+    r"""
+    Return the Hamming graph with parameters `n`, `q` over `X`.
+
+    Hamming graphs are graphs over the cartesian product of n copies
+    of `X`, where `q = |X|`, where the vertices, labelled with the
+    corresponding tuple in `X^n`, are connected if the Hamming distance
+    between their labels is 1. All Hamming graphs are regular,
+    vertex-transitive and distance-regular.
+
+    Hamming graphs with parameters `(1,q)` represent the complete graph
+    with q vertices over the set `X`.
+
+    INPUT:
+
+    - ``n`` -- power to which ``X`` will be raised to provide vertices
+      for the Hamming graph
+
+    - ``q`` -- cardinality of ``X``
+
+    - ``X`` -- list of labels representing the vertices of the underlying graph
+      the Hamming graph will be based on; if ``None`` (or left unused), the
+      list `[0, ... , q-1]` will be used
+
+    OUTPUT:
+
+    - ``G`` -- the Hamming graph with parameters `(n,q,X)`
+
+    EXAMPLES:
+
+    Every Hamming graph is distance-regular, regular and vertex-transitive::
+
+        sage: g = graphs.HammingGraph(3, 7)
+        sage: g.is_distance_regular()
+        True
+        sage: g.is_regular()
+        True
+        sage: g.is_vertex_transitive()                                                  # needs sage.groups
+        True
+
+    A Hamming graph with parameters `(1,q)` is isomorphic to the
+    Complete graph with parameter `q`::
+
+        sage: g = graphs.HammingGraph(1, 23)
+        sage: g.is_isomorphic(graphs.CompleteGraph(23))
+        True
+
+    If a parameter `q` is provided which is not equal to `X`'s
+    cardinality, an exception is raised::
+
+        sage: X = ['a','b','c','d','e']
+        sage: g = graphs.HammingGraph(2, 3, X)
+        Traceback (most recent call last):
+        ...
+        ValueError: q must be the cardinality of X
+
+    REFERENCES:
+
+    For a more accurate description, see the following wikipedia page:
+    :wikipedia:`Hamming_graph`
+    """
+    from itertools import product, repeat
+    if not X:
+        X = list(range(q))
+    if q != len(X):
+        raise ValueError("q must be the cardinality of X")
+    g = Graph(name="Hamming Graph with parameters " + str(n) + "," + str(q), multiedges=False)
+    g.add_vertices(product(*repeat(X, n)))
+    for v in g:
+        for i in range(n):
+            prefix = v[:i]
+            suffix = v[i+1:]
+            for el in X:
+                if el == v[i]:
+                    continue
+                u = prefix + (el,) + suffix
+                g.add_edge(v, u)
+    return g
+
+
+def BalancedTree(r, h):
+    r"""
+    Return the perfectly balanced tree of height `h \geq 1`,
+    whose root has degree `r \geq 2`.
+
+    The number of vertices of this graph is
+    `1 + r + r^2 + \cdots + r^h`, that is,
+    `\frac{r^{h+1} - 1}{r - 1}`. The number of edges is one
+    less than the number of vertices.
+
+    INPUT:
+
+    - ``r`` -- positive integer `\geq 2`; the degree of the root node
+
+    - ``h`` -- positive integer `\geq 1`; the height of the balanced tree
+
+    OUTPUT:
+
+    The perfectly balanced tree of height `h \geq 1` and whose root has
+    degree `r \geq 2`.
+
+    EXAMPLES:
+
+    A balanced tree whose root node has degree `r = 2`, and of height
+    `h = 1`, has order 3 and size 2::
+
+        sage: G = graphs.BalancedTree(2, 1); G
+        Balanced tree: Graph on 3 vertices
+        sage: G.order()
+        3
+        sage: G.size()
+        2
+        sage: r = 2; h = 1
+        sage: v = 1 + r
+        sage: v; v - 1
+        3
+        2
+
+    Plot a balanced tree of height 5, whose root node has degree `r = 3`::
+
+        sage: G = graphs.BalancedTree(3, 5)
+        sage: G.plot()                          # long time                             # needs sage.plot
+        Graphics object consisting of 728 graphics primitives
+
+    A tree is bipartite. If its vertex set is finite, then it is planar. ::
+
+        sage: # needs networkx
+        sage: r = randint(2, 5); h = randint(1, 7)
+        sage: T = graphs.BalancedTree(r, h)
+        sage: T.is_bipartite()
+        True
+        sage: T.is_planar()                                                             # needs planarity
+        True
+        sage: v = (r^(h + 1) - 1) / (r - 1)
+        sage: T.order() == v
+        True
+        sage: T.size() == v - 1
+        True
+
+    TESTS:
+
+    Normally we would only consider balanced trees whose root node
+    has degree `r \geq 2`, but the construction degenerates
+    gracefully::
+
+        sage: graphs.BalancedTree(1, 10)
+        Balanced tree: Graph on 11 vertices
+
+    Similarly, we usually want the tree must have height `h \geq 1`
+    but the algorithm also degenerates gracefully here::
+
+        sage: graphs.BalancedTree(3, 0)
+        Balanced tree: Graph on 1 vertex
+
+    The construction is the same as the one of networkx::
+
+        sage: # needs networkx
+        sage: import networkx
+        sage: r = randint(2, 4); h = randint(1, 5)
+        sage: T = graphs.BalancedTree(r, h)
+        sage: N = Graph(networkx.balanced_tree(r, h), name="Balanced tree")
+        sage: T.is_isomorphic(N)
+        True
+    """
+    # Compute the number of vertices per level of the tree
+    order = [r**l for l in range(h + 1)]
+    # Compute the first index of the vertices of a level
+    begin = [0]
+    begin.extend(begin[-1] + val for val in order)
+    # The number of vertices of the tree is the first index of level h + 1
+    T = Graph(begin[-1], name="Balanced tree")
+
+    # Add edges of the r-ary tree
+    for level in range(h):
+        start = begin[level + 1]
+        for u in range(begin[level], begin[level + 1]):
+            T.add_edges((u, v) for v in range(start, start + r))
+            start += r
+    return T
+
+
+def BarbellGraph(n1, n2):
+    r"""
+    Return a barbell graph with `2 n_1 + n_2` nodes.
+
+    The argument `n_1` must be greater than or equal to 2.
+
+    A barbell graph is a basic structure that consists of a path graph
+    of order `n_2` connecting two complete graphs of order `n_1` each.
+
+    INPUT:
+
+    - ``n1`` -- integer `\geq 2`; the order of each of the two
+      complete graphs
+
+    - ``n2`` -- nonnegative integer; the order of the path graph
+      connecting the two complete graphs
+
+    OUTPUT:
+
+    A barbell graph of order `2*n_1 + n_2`. A :exc:`ValueError` is
+    returned if `n_1 < 2` or `n_2 < 0`.
+
+    PLOTTING:
+
+    Upon construction, the position dictionary is filled to
+    override the spring-layout algorithm. By convention, each barbell
+    graph will be displayed with the two complete graphs in the
+    lower-left and upper-right corners, with the path graph connecting
+    diagonally between the two. Thus the `n_1`-th node will be drawn at a
+    45 degree angle from the horizontal right center of the first
+    complete graph, and the `n_1 + n_2 + 1`-th node will be drawn 45
+    degrees below the left horizontal center of the second complete graph.
+
+    EXAMPLES:
+
+    Construct and show a barbell graph ``Bar = 4``, ``Bells = 9``::
+
+        sage: g = graphs.BarbellGraph(9, 4); g
+        Barbell graph: Graph on 22 vertices
+        sage: g.show()                          # long time                             # needs sage.plot
+
+    An `n_1 \geq 2`, `n_2 \geq 0` barbell graph has order `2*n_1 + n_2`. It
+    has the complete graph on `n_1` vertices as a subgraph. It also has
+    the path graph on `n_2` vertices as a subgraph. ::
+
+        sage: n1 = randint(2, 2*10^2)
+        sage: n2 = randint(0, 2*10^2)
+        sage: g = graphs.BarbellGraph(n1, n2)
+        sage: v = 2*n1 + n2
+        sage: g.order() == v
+        True
+        sage: K_n1 = graphs.CompleteGraph(n1)
+        sage: P_n2 = graphs.PathGraph(n2)
+
+        sage: # needs sage.modules
+        sage: s_K = g.subgraph_search(K_n1, induced=True)
+        sage: s_P = g.subgraph_search(P_n2, induced=True)
+        sage: K_n1.is_isomorphic(s_K)
+        True
+        sage: P_n2.is_isomorphic(s_P)
+        True
+
+    TESTS::
+
+        sage: n1, n2 = randint(3, 10), randint(0, 10)
+        sage: g = graphs.BarbellGraph(n1, n2)
+        sage: g.num_verts() == 2 * n1 + n2
+        True
+        sage: g.num_edges() == 2 * binomial(n1, 2) + n2 + 1                             # needs sage.symbolic
+        True
+        sage: g.is_connected()
+        True
+        sage: g.girth() == 3
+        True
+
+    The input `n_1` must be `\geq 2`::
+
+        sage: graphs.BarbellGraph(1, randint(0, 10^6))
+        Traceback (most recent call last):
+        ...
+        ValueError: invalid graph description, n1 should be >= 2
+        sage: graphs.BarbellGraph(randint(-10^6, 1), randint(0, 10^6))
+        Traceback (most recent call last):
+        ...
+        ValueError: invalid graph description, n1 should be >= 2
+
+    The input `n_2` must be `\geq 0`::
+
+        sage: graphs.BarbellGraph(randint(2, 10^6), -1)
+        Traceback (most recent call last):
+        ...
+        ValueError: invalid graph description, n2 should be >= 0
+        sage: graphs.BarbellGraph(randint(2, 10^6), randint(-10^6, -1))
+        Traceback (most recent call last):
+        ...
+        ValueError: invalid graph description, n2 should be >= 0
+        sage: graphs.BarbellGraph(randint(-10^6, 1), randint(-10^6, -1))
+        Traceback (most recent call last):
+        ...
+        ValueError: invalid graph description, n1 should be >= 2
+    """
+    # sanity checks
+    if n1 < 2:
+        raise ValueError("invalid graph description, n1 should be >= 2")
+    if n2 < 0:
+        raise ValueError("invalid graph description, n2 should be >= 0")
+
+    G = Graph(name="Barbell graph")
+    G.add_clique(list(range(n1)))
+    G.add_path(list(range(n1 - 1, n1 + n2 + 1)))
+    G.add_clique(list(range(n1 + n2, n1 + n2 + n1)))
+
+    G._circle_embedding(list(range(n1)), shift=1, angle=pi/4)
+    G._line_embedding(list(range(n1, n1 + n2)), first=(2, 2), last=(n2 + 1, n2 + 1))
+    G._circle_embedding(list(range(n1 + n2, n1 + n2 + n1)), center=(n2 + 3, n2 + 3), angle=5*pi/4)
+    return G
+
+
+def LollipopGraph(n1, n2):
+    r"""
+    Return a lollipop graph with `n_1 + n_2` nodes.
+
+    A lollipop graph is a path graph (order `n_2`) connected to a complete
+    graph (order `n_1`). (A barbell graph minus one of the bells).
+
+    PLOTTING: Upon construction, the position dictionary is filled to
+    override the spring-layout algorithm. By convention, the complete
+    graph will be drawn in the lower-left corner with the `n_1`-th node
+    at a 45 degree angle above the right horizontal center of the
+    complete graph, leading directly into the path graph.
+
+    EXAMPLES:
+
+    Construct and show a lollipop graph Candy = 13, Stick = 4::
+
+        sage: g = graphs.LollipopGraph(13,4); g
+        Lollipop graph: Graph on 17 vertices
+        sage: g.show()                          # long time                             # needs sage.plot
+
+    TESTS::
+
+        sage: n1, n2 = randint(3, 10), randint(0, 10)
+        sage: g = graphs.LollipopGraph(n1, n2)
+        sage: g.num_verts() == n1 + n2
+        True
+        sage: g.num_edges() == binomial(n1, 2) + n2                                     # needs sage.symbolic
+        True
+        sage: g.is_connected()
+        True
+        sage: g.girth() == 3
+        True
+        sage: graphs.LollipopGraph(n1, 0).is_isomorphic(graphs.CompleteGraph(n1))
+        True
+        sage: graphs.LollipopGraph(0, n2).is_isomorphic(graphs.PathGraph(n2))
+        True
+        sage: graphs.LollipopGraph(0, 0).is_isomorphic(graphs.EmptyGraph())
+        True
+
+    The input `n_1` must be `\geq 0`::
+
+        sage: graphs.LollipopGraph(-1, randint(0, 10^6))
+        Traceback (most recent call last):
+        ...
+        ValueError: invalid graph description, n1 should be >= 0
+
+    The input `n_2` must be `\geq 0`::
+
+        sage: graphs.LollipopGraph(randint(2, 10^6), -1)
+        Traceback (most recent call last):
+        ...
+        ValueError: invalid graph description, n2 should be >= 0
+    """
+    # sanity checks
+    if n1 < 0:
+        raise ValueError("invalid graph description, n1 should be >= 0")
+    if n2 < 0:
+        raise ValueError("invalid graph description, n2 should be >= 0")
+
+    G = Graph(n1 + n2, name="Lollipop graph")
+    G.add_clique(list(range(n1)))
+    G.add_path(list(range(n1, n1 + n2)))
+    if n1 * n2 > 0:
+        G.add_edge(n1 - 1, n1)
+    if n1 == 1:
+        G.set_pos({0: (0, 0)})
+    else:
+        G._circle_embedding(list(range(n1)), shift=1, angle=pi/4)
+    G._line_embedding(list(range(n1, n1 + n2)), first=(2, 2), last=(n2 + 1, n2 + 1))
+    return G
+
+
+def TadpoleGraph(n1, n2):
+    r"""
+    Return a tadpole graph with `n_1 + n_2` nodes.
+
+    A tadpole graph is a path graph (order `n_2`) connected to a cycle graph
+    (order `n_1`).
+
+    PLOTTING: Upon construction, the position dictionary is filled to override
+    the spring-layout algorithm. By convention, the cycle graph will be drawn
+    in the lower-left corner with the `n_1`-th node at a 45 degree angle above
+    the right horizontal center of the cycle graph, leading directly into the
+    path graph.
+
+    EXAMPLES:
+
+    Construct and show a tadpole graph Cycle = 13, Stick = 4::
+
+        sage: g = graphs.TadpoleGraph(13, 4); g
+        Tadpole graph: Graph on 17 vertices
+        sage: g.show()                          # long time                             # needs sage.plot
+
+    TESTS::
+
+        sage: n1, n2 = randint(3, 10), randint(0, 10)
+        sage: g = graphs.TadpoleGraph(n1, n2)
+        sage: g.num_verts() == n1 + n2
+        True
+        sage: g.num_edges() == n1 + n2
+        True
+        sage: g.girth() == n1
+        True
+        sage: graphs.TadpoleGraph(n1, 0).is_isomorphic(graphs.CycleGraph(n1))
+        True
+
+    The input `n_1` must be `\geq 3`::
+
+        sage: graphs.TadpoleGraph(2, randint(0, 10^6))
+        Traceback (most recent call last):
+        ...
+        ValueError: invalid graph description, n1 should be >= 3
+
+    The input `n_2` must be `\geq 0`::
+
+        sage: graphs.TadpoleGraph(randint(2, 10^6), -1)
+        Traceback (most recent call last):
+        ...
+        ValueError: invalid graph description, n2 should be >= 0
+    """
+    # sanity checks
+    if n1 < 3:
+        raise ValueError("invalid graph description, n1 should be >= 3")
+    if n2 < 0:
+        raise ValueError("invalid graph description, n2 should be >= 0")
+
+    G = Graph(n1 + n2, name="Tadpole graph")
+    G.add_cycle(list(range(n1)))
+    G.add_path(list(range(n1, n1 + n2)))
+    if n1 * n2 > 0:
+        G.add_edge(n1 - 1, n1)
+    G._circle_embedding(list(range(n1)), shift=1, angle=pi/4)
+    G._line_embedding(list(range(n1, n1 + n2)), first=(2, 2), last=(n2 + 1, n2 + 1))
+    return G
+
+
+def AztecDiamondGraph(n):
+    """
+    Return the Aztec Diamond graph of order ``n``.
+
+    See the :wikipedia:`Aztec_diamond` for more information.
+
+    EXAMPLES::
+
+        sage: graphs.AztecDiamondGraph(2)
+        Aztec Diamond graph of order 2
+
+        sage: [graphs.AztecDiamondGraph(i).num_verts() for i in range(8)]
+        [0, 4, 12, 24, 40, 60, 84, 112]
+
+        sage: [graphs.AztecDiamondGraph(i).num_edges() for i in range(8)]
+        [0, 4, 16, 36, 64, 100, 144, 196]
+
+        sage: G = graphs.AztecDiamondGraph(3)
+        sage: sum(1 for p in G.perfect_matchings())
+        64
+    """
+    from sage.graphs.generators.basic import Grid2dGraph
+    if n:
+        N = 2 * n
+        G = Grid2dGraph(N, N)
+        H = G.subgraph([(i, j) for i in range(N) for j in range(N)
+                        if i - n <= j <= n + i and
+                        n - 1 - i <= j <= 3 * n - i - 1])
+    else:
+        H = Graph()
+    H.rename('Aztec Diamond graph of order {}'.format(n))
+    return H
+
+
+def DipoleGraph(n):
+    r"""
+    Return a dipole graph with `n` edges.
+
+    A dipole graph is a multigraph consisting of 2 vertices connected with `n`
+    parallel edges.
+
+    EXAMPLES:
+
+    Construct and show a dipole graph with 13 edges::
+
+        sage: g = graphs.DipoleGraph(13); g
+        Dipole graph: Multi-graph on 2 vertices
+        sage: g.show()                          # long time                             # needs sage.plot
+
+    TESTS::
+
+        sage: n = randint(0, 10)
+        sage: g = graphs.DipoleGraph(n)
+        sage: g.num_verts() == 2
+        True
+        sage: g.num_edges() == n
+        True
+        sage: g.is_connected() == (n > 0)
+        True
+        sage: g.diameter() == (1 if n > 0 else infinity)
+        True
+
+    The input ``n`` must be `\geq 0`::
+
+        sage: graphs.DipoleGraph(-randint(1, 10))
+        Traceback (most recent call last):
+        ...
+        ValueError: invalid graph description, n should be >= 0
+    """
+    # sanity checks
+    if n < 0:
+        raise ValueError("invalid graph description, n should be >= 0")
+
+    return Graph([[0, 1], [(0, 1)]*n], name="Dipole graph", multiedges=True)
+
+
+def BubbleSortGraph(n):
+    r"""
+    Return the bubble sort graph `B(n)`.
+
+    The vertices of the bubble sort graph are the set of permutations
+    on `n` symbols. Two vertices are adjacent if one can be obtained
+    from the other by swapping the labels in the `i`-th and `(i+1)`-th
+    positions for `1 \leq i \leq n-1`. In total, `B(n)` has order
+    `n!`. Swapping two labels as described previously corresponds to
+    multiplying on the right the permutation corresponding to the node
+    by an elementary transposition in the
+    :class:`~sage.groups.perm_gps.permgroup_named.SymmetricGroup`.
+
+    The bubble sort graph is the underlying graph of the
+    :meth:`~sage.geometry.polyhedron.library.Polytopes.permutahedron`.
+
+    INPUT:
+
+    - ``n`` -- positive integer. The number of symbols to permute
+
+    OUTPUT:
+
+    The bubble sort graph `B(n)` on `n` symbols. If `n < 1`, a
+    :exc:`ValueError` is returned.
+
+    EXAMPLES::
+
+        sage: g = graphs.BubbleSortGraph(4); g
+        Bubble sort: Graph on 24 vertices
+        sage: g.plot()                          # long time                             # needs sage.plot
+        Graphics object consisting of 61 graphics primitives
+
+    The bubble sort graph on `n = 1` symbol is the trivial graph `K_1`::
+
+        sage: graphs.BubbleSortGraph(1)
+        Bubble sort: Graph on 1 vertex
+
+    If `n \geq 1`, then the order of `B(n)` is `n!`::
+
+        sage: n = randint(1, 8)
+        sage: g = graphs.BubbleSortGraph(n)
+        sage: g.order() == factorial(n)
+        True
+
+    .. SEEALSO::
+
+        * :meth:`~sage.geometry.polyhedron.library.Polytopes.permutahedron`
+
+    TESTS:
+
+    Input ``n`` must be positive::
+
+        sage: graphs.BubbleSortGraph(0)
+        Traceback (most recent call last):
+        ...
+        ValueError: Invalid number of symbols to permute, n should be >= 1
+        sage: graphs.BubbleSortGraph(randint(-10^6, 0))
+        Traceback (most recent call last):
+        ...
+        ValueError: Invalid number of symbols to permute, n should be >= 1
+
+    AUTHORS:
+
+    - Michael Yurko (2009-09-01)
+    """
+    # sanity checks
+    if n < 1:
+        raise ValueError(
+            "Invalid number of symbols to permute, n should be >= 1")
+    if n == 1:
+        from sage.graphs.generators.basic import CompleteGraph
+        return Graph(CompleteGraph(n), name="Bubble sort")
+    from sage.combinat.permutation import Permutations
+    # create set from which to permute
+    label_set = [str(i) for i in range(1, n + 1)]
+    d = {}
+    # iterate through all vertices
+    for v in Permutations(label_set):
+        v = list(v)  # So we can easily mutate it
+        tmp_dict = {}
+        # add all adjacencies
+        for i in range(n - 1):
+            # swap entries
+            v[i], v[i + 1] = v[i + 1], v[i]
+            # add new vertex
+            new_vert = ''.join(v)
+            tmp_dict[new_vert] = None
+            # swap back
+            v[i], v[i + 1] = v[i + 1], v[i]
+        # add adjacency dict
+        d[''.join(v)] = tmp_dict
+    return Graph(d, name="Bubble sort")
+
+
+def chang_graphs():
+    r"""
+    Return the three Chang graphs.
+
+    Three of the four strongly regular graphs of parameters `(28,12,6,4)` are
+    called the Chang graphs. The fourth is the line graph of `K_8`. For more
+    information about the Chang graphs, see the :wikipedia:`Chang_graphs` or
+    https://www.win.tue.nl/~aeb/graphs/Chang.html.
+
+    EXAMPLES: check that we get 4 non-isomorphic s.r.g.'s with the
+    same parameters::
+
+        sage: chang_graphs = graphs.chang_graphs()
+        sage: K8 = graphs.CompleteGraph(8)
+        sage: T8 = K8.line_graph()
+        sage: four_srg = chang_graphs + [T8]
+        sage: for g in four_srg:
+        ....:     print(g.is_strongly_regular(parameters=True))
+        (28, 12, 6, 4)
+        (28, 12, 6, 4)
+        (28, 12, 6, 4)
+        (28, 12, 6, 4)
+        sage: from itertools import combinations
+        sage: for g1,g2 in combinations(four_srg,2):
+        ....:     assert not g1.is_isomorphic(g2)
+
+    Construct the Chang graphs by Seidel switching::
+
+        sage: c3c5 = graphs.CycleGraph(3).disjoint_union(graphs.CycleGraph(5))
+        sage: c8 = graphs.CycleGraph(8)
+        sage: s = [K8.subgraph_search(c8).edges(sort=False),                            # needs sage.modules
+        ....:      [(0,1,None),(2,3,None),(4,5,None),(6,7,None)],
+        ....:      K8.subgraph_search(c3c5).edges(sort=False)]
+        sage: [T8.seidel_switching(x, inplace=False).is_isomorphic(G)                   # needs sage.modules
+        ....:  for x, G in zip(s, chang_graphs)]
+        [True, True, True]
+    """
+    g1 = Graph("[}~~EebhkrRb_~SoLOIiAZ?LBBxDb?bQcggjHKEwoZFAaiZ?Yf[?dxb@@tdWGkwn",
+               loops=False, multiedges=False)
+    g2 = Graph("[~z^UipkkZPr_~Y_LOIiATOLBBxPR@`acoojBBSoWXTaabN?Yts?Yji_QyioClXZ",
+               loops=False, multiedges=False)
+    g3 = Graph(r"[~~vVMWdKFpV`^UGIaIERQ`\DBxpA@g`CbGRI`AxICNaFM[?fM\?Ytj@CxrGGlYt",
+               loops=False, multiedges=False)
+    return [g1, g2, g3]
+
+
+def CirculantGraph(n, adjacency):
+    r"""
+    Return a circulant graph with `n` nodes.
+
+    A circulant graph has the property that the vertex `i` is connected
+    with the vertices `i+j` and `i-j` for each `j` in ``adjacency``.
+
+    INPUT:
+
+    -  ``n`` -- number of vertices in the graph
+
+    -  ``adjacency`` -- the list of `j` values
+
+    PLOTTING: Upon construction, the position dictionary is filled to
+    override the spring-layout algorithm. By convention, each circulant
+    graph will be displayed with the first (0) node at the top, with
+    the rest following in a counterclockwise manner.
+
+    Filling the position dictionary in advance adds `O(n)` to the
+    constructor.
+
+    .. SEEALSO::
+
+        * :meth:`~sage.graphs.generic_graph.GenericGraph.is_circulant`
+          -- checks whether a (di)graph is circulant, and/or returns
+          all possible sets of parameters.
+
+    EXAMPLES: Compare plotting using the predefined layout and
+    networkx::
+
+        sage: # needs networkx
+        sage: import networkx
+        sage: n = networkx.cycle_graph(23)
+        sage: spring23 = Graph(n)
+        sage: posdict23 = graphs.CirculantGraph(23,2)
+        sage: spring23.show()                   # long time
+        sage: posdict23.show()  # long time
+
+    We next view many cycle graphs as a Sage graphics array. First we
+    use the ``CirculantGraph`` constructor, which fills in
+    the position dictionary::
+
+        sage: # needs sage.plot
+        sage: g = []
+        sage: j = []
+        sage: for i in range(9):
+        ....:     k = graphs.CirculantGraph(i+4, i+1)
+        ....:     g.append(k)
+        sage: for i in range(3):
+        ....:     n = []
+        ....:     for m in range(3):
+        ....:         n.append(g[3*i + m].plot(vertex_size=50, vertex_labels=False))
+        ....:     j.append(n)
+        sage: G = graphics_array(j)
+        sage: G.show()                          # long time
+
+    Compare to plotting with the spring-layout algorithm::
+
+        sage: # needs networkx sage.plot
+        sage: g = []
+        sage: j = []
+        sage: for i in range(9):
+        ....:     spr = networkx.cycle_graph(i+3)
+        ....:     k = Graph(spr)
+        ....:     g.append(k)
+        sage: for i in range(3):
+        ....:  n = []
+        ....:  for m in range(3):
+        ....:      n.append(g[3*i + m].plot(vertex_size=50, vertex_labels=False))
+        ....:  j.append(n)
+        sage: G = graphics_array(j)
+        sage: G.show()                          # long time
+
+    Passing a 1 into adjacency should give the cycle.
+
+    ::
+
+        sage: graphs.CirculantGraph(6,1) == graphs.CycleGraph(6)
+        True
+        sage: graphs.CirculantGraph(7,[1,3]).edges(sort=True, labels=false)
+        [(0, 1),
+        (0, 3),
+        (0, 4),
+        (0, 6),
+        (1, 2),
+        (1, 4),
+        (1, 5),
+        (2, 3),
+        (2, 5),
+        (2, 6),
+        (3, 4),
+        (3, 6),
+        (4, 5),
+        (5, 6)]
+    """
+    if not isinstance(adjacency, list):
+        adjacency = [adjacency]
+
+    G = Graph(n, name="Circulant graph (" + str(adjacency) + ")")
+    G._circle_embedding(list(range(n)))
+
+    for v in G:
+        G.add_edges([(v, (v + j) % n) for j in adjacency])
+
+    return G
+
+
+def CubeGraph(n, embedding=1):
+    r"""
+    Return the `n`-cube graph, also called the hypercube in `n` dimensions.
+
+    The hypercube in `n` dimension is build upon the binary strings on `n` bits,
+    two of them being adjacent if they differ in exactly one bit. Hence, the
+    distance between two vertices in the hypercube is the Hamming distance.
+
+    INPUT:
+
+    - ``n`` -- integer; the dimension of the cube graph
+
+    - ``embedding`` -- integer (default: `1`); two embeddings of the `n`-cube
+      are available:
+
+      - ``1`` -- the `n`-cube is projected inside a regular `2n`-gonal polygon by
+        a skew orthogonal projection. See the :wikipedia:`Hypercube` for more
+        details.
+
+      - ``2`` -- orthogonal projection of the `n`-cube. This orientation shows
+        columns of independent vertices such that the neighbors of a vertex are
+        located in the columns on the left and on the right. The number of
+        vertices in each column represents rows in Pascal's triangle. See for
+        instance the :wikipedia:`10-cube` for more details.
+
+      - ``3`` -- oblique projection of the `n`-cube. Oblique projection involves
+        aligning one face parallel to the viewer and projecting at a specified
+        angle, maintaining equal size for edges parallel to one axis while
+        applying fixed foreshortening to others. This method simplifies the
+        representation of a four-dimensional hypercube onto a two-dimensional
+        plane, offering a geometrically consistent visualization.
+
+      - ``None`` or ``O`` -- no embedding is provided
+
+    EXAMPLES:
+
+    The distance between `0100110` and `1011010` is `5`, as expected::
+
+        sage: g = graphs.CubeGraph(7)
+        sage: g.distance('0100110','1011010')
+        5
+
+    Plot several `n`-cubes in a Sage Graphics Array::
+
+        sage: # needs sage.plot
+        sage: g = []
+        sage: j = []
+        sage: for i in range(6):
+        ....:  k = graphs.CubeGraph(i+1)
+        ....:  g.append(k)
+        ...
+        sage: for i in range(2):
+        ....:  n = []
+        ....:  for m in range(3):
+        ....:      n.append(g[3*i + m].plot(vertex_size=50, vertex_labels=False))
+        ....:  j.append(n)
+        ...
+        sage: G = graphics_array(j)
+        sage: G.show(figsize=[6,4])             # long time
+
+    Use the plot options to display larger `n`-cubes::
+
+        sage: g = graphs.CubeGraph(9, embedding=1)
+        sage: g.show(figsize=[12,12],vertex_labels=False, vertex_size=20)       # long time, needs sage.plot
+        sage: g = graphs.CubeGraph(9, embedding=2)
+        sage: g.show(figsize=[12,12],vertex_labels=False, vertex_size=20)       # long time, needs sage.plot
+        sage: g = graphs.CubeGraph(9, embedding=3)
+        sage: g.show(figsize=[12,12],vertex_labels=False, vertex_size=20)       # long time, needs sage.plot
+
+    AUTHORS:
+
+    - Robert Miller
+    - David Coudert
+    """
+    if embedding == 1 or embedding == 3:
+        # construct recursively the adjacency dict and the embedding
+        theta = float(pi/n)
+        if embedding == 3 and n > 2:
+            theta = float(pi/(2*n-2))
+
+        d = {'': []}
+        dn = {}
+        p = {'': (float(0), float(0))}
+        pn = {}
+
+        for i in range(n):
+            ci = float(cos(i*theta))
+            si = float(sin(i*theta))
+            for v, e in d.items():
+                v0 = v + '0'
+                v1 = v + '1'
+                l0 = [v1]
+                l1 = [v0]
+                for m in e:
+                    l0.append(m + '0')
+                    l1.append(m + '1')
+                dn[v0] = l0
+                dn[v1] = l1
+                x, y = p[v]
+                pn[v0] = (x, y)
+                pn[v1] = (x + ci, y + si)
+            d, dn = dn, {}
+            p, pn = pn, {}
+
+        # construct the graph
+        G = Graph(d, format='dict_of_lists', pos=p, name="%d-Cube" % n)
+
+    else:
+        # construct recursively the adjacency dict
+        d = {'': []}
+        dn = {}
+
+        for i in range(n):
+            for v, e in d.items():
+                v0 = v + '0'
+                v1 = v + '1'
+                l0 = [v1]
+                l1 = [v0]
+                for m in e:
+                    l0.append(m + '0')
+                    l1.append(m + '1')
+                dn[v0] = l0
+                dn[v1] = l1
+            d, dn = dn, {}
+
+        # construct the graph
+        G = Graph(d, name="%d-Cube" % n, format='dict_of_lists')
+
+        if embedding == 2:
+            # Orthogonal projection
+            s = '0'*n
+            L = [[] for _ in range(n + 1)]
+            for u, d in G.breadth_first_search(s, report_distance=True):
+                L[d].append(u)
+
+            p = G._circle_embedding(list(range(2*n)), radius=(n + 1)//2, angle=pi, return_dict=True)
+            for i in range(n + 1):
+                y = p[i][1] / 1.5
+                G._line_embedding(L[i], first=(i, y), last=(i, -y), return_dict=False)
+
+    return G
+
+
+def GoethalsSeidelGraph(k, r):
+    r"""
+    Return the graph `\text{Goethals-Seidel}(k,r)`.
+
+    The graph `\text{Goethals-Seidel}(k,r)` comes from a construction presented
+    in Theorem 2.4 of [GS1970]_. It relies on a :func:`(v,k)-BIBD
+    <sage.combinat.designs.bibd.balanced_incomplete_block_design>` with `r`
+    blocks and a
+    :func:`~sage.combinat.matrices.hadamard_matrix.hadamard_matrix` of order
+    `r+1`. The result is a
+    :func:`sage.graphs.strongly_regular_db.strongly_regular_graph` on `v(r+1)`
+    vertices with degree `k=(n+r-1)/2`.
+
+    It appears under this name in Andries Brouwer's `database of strongly
+    regular graphs <https://www.win.tue.nl/~aeb/graphs/srg/srgtab.html>`__.
+
+    INPUT:
+
+    - ``k``, ``r`` -- integers
+
+    .. SEEALSO::
+
+        - :func:`~sage.graphs.strongly_regular_db.is_goethals_seidel`
+
+    EXAMPLES::
+
+        sage: graphs.GoethalsSeidelGraph(3,3)                                           # needs sage.combinat sage.modules
+        Graph on 28 vertices
+        sage: graphs.GoethalsSeidelGraph(3,3).is_strongly_regular(parameters=True)      # needs sage.combinat sage.modules
+        (28, 15, 6, 10)
+    """
+    from sage.combinat.designs.bibd import balanced_incomplete_block_design
+    from sage.combinat.matrices.hadamard_matrix import hadamard_matrix
+    from sage.matrix.constructor import Matrix
+    from sage.matrix.constructor import block_matrix
+
+    v = (k-1)*r + 1
+    n = v*(r + 1)
+
+    # N is the (v times b) incidence matrix of a bibd
+    N = balanced_incomplete_block_design(v, k).incidence_matrix()
+
+    # L is a (r+1 times r) matrix, where r is the row sum of N
+    L = hadamard_matrix(r + 1).submatrix(0, 1)
+    L = [Matrix(C).transpose() for C in L.columns()]
+    zero = Matrix(r + 1, 1, [0]*(r + 1))
+
+    # For every row of N, we replace the 0s with a column of zeros, and we
+    # replace the ith 1 with the ith column of L. The result is P.
+    P = []
+    for row in N:
+        Ltmp = L[:]
+        P.append([Ltmp.pop(0) if i else zero
+                  for i in row])
+
+    P = block_matrix(P)
+
+    # The final graph
+    PP = P*P.transpose()
+    for i in range(n):
+        PP[i, i] = 0
+
+    G = Graph(PP, format='seidel_adjacency_matrix')
+    return G
+
+
+def DorogovtsevGoltsevMendesGraph(n):
+    """
+    Construct the `n`-th generation of the Dorogovtsev-Goltsev-Mendes
+    graph.
+
+    EXAMPLES::
+
+        sage: G = graphs.DorogovtsevGoltsevMendesGraph(8)                               # needs networkx
+        sage: G.size()                                                                  # needs networkx
+        6561
+
+    REFERENCE:
+
+    - [1] Dorogovtsev, S. N., Goltsev, A. V., and Mendes, J.
+      F. F., Pseudofractal scale-free web, Phys. Rev. E 066122
+      (2002).
+    """
+    import networkx
+    return Graph(networkx.dorogovtsev_goltsev_mendes_graph(n),
+                 name="Dorogovtsev-Goltsev-Mendes Graph, %d-th generation" % n)
+
+
+def FoldedCubeGraph(n):
+    r"""
+    Return the folded cube graph of order `2^{n-1}`.
+
+    The folded cube graph on `2^{n-1}` vertices can be obtained from a cube
+    graph on `2^n` vertices by merging together opposed
+    vertices. Alternatively, it can be obtained from a cube graph on
+    `2^{n-1}` vertices by adding an edge between opposed vertices. This
+    second construction is the one produced by this method.
+
+    See the :wikipedia:`Folded_cube_graph` for more information.
+
+    EXAMPLES:
+
+    The folded cube graph of order five is the Clebsch graph::
+
+        sage: fc = graphs.FoldedCubeGraph(5)
+        sage: clebsch = graphs.ClebschGraph()
+        sage: fc.is_isomorphic(clebsch)
+        True
+    """
+    if n < 1:
+        raise ValueError("The value of n must be at least 2")
+
+    g = CubeGraph(n - 1)
+    g.name("Folded Cube Graph")
+
+    # Complementing the binary word
+    def complement(x):
+        x = x.replace('0', 'a')
+        x = x.replace('1', '0')
+        x = x.replace('a', '1')
+        return x
+
+    for x in g:
+        if x[0] == '0':
+            g.add_edge(x, complement(x))
+
+    return g
+
+
+def FriendshipGraph(n):
+    r"""
+    Return the friendship graph `F_n`.
+
+    The friendship graph is also known as the Dutch windmill graph. Let
+    `C_3` be the cycle graph on 3 vertices. Then `F_n` is constructed by
+    joining `n \geq 1` copies of `C_3` at a common vertex. If `n = 1`,
+    then `F_1` is isomorphic to `C_3` (the triangle graph). If `n = 2`,
+    then `F_2` is the butterfly graph, otherwise known as the bowtie
+    graph. For more information, see the :wikipedia:`Friendship_graph`.
+
+    INPUT:
+
+    - ``n`` -- positive integer; the number of copies of `C_3` to use in
+      constructing `F_n`
+
+    OUTPUT:
+
+    - The friendship graph `F_n` obtained from `n` copies of the cycle
+      graph `C_3`.
+
+    .. SEEALSO::
+
+        - :meth:`GraphGenerators.ButterflyGraph`
+
+    EXAMPLES:
+
+    The first few friendship graphs. ::
+
+        sage: # needs sage.plot
+        sage: A = []; B = []
+        sage: for i in range(9):
+        ....:     g = graphs.FriendshipGraph(i + 1)
+        ....:     A.append(g)
+        sage: for i in range(3):
+        ....:     n = []
+        ....:     for j in range(3):
+        ....:         n.append(A[3*i + j].plot(vertex_size=20, vertex_labels=False))
+        ....:     B.append(n)
+        sage: G = graphics_array(B)
+        sage: G.show()                          # long time
+
+    For `n = 1`, the friendship graph `F_1` is isomorphic to the cycle
+    graph `C_3`, whose visual representation is a triangle. ::
+
+        sage: G = graphs.FriendshipGraph(1); G
+        Friendship graph: Graph on 3 vertices
+        sage: G.show()                          # long time                             # needs sage.plot
+        sage: G.is_isomorphic(graphs.CycleGraph(3))
+        True
+
+    For `n = 2`, the friendship graph `F_2` is isomorphic to the
+    butterfly graph, otherwise known as the bowtie graph. ::
+
+        sage: G = graphs.FriendshipGraph(2); G
+        Friendship graph: Graph on 5 vertices
+        sage: G.is_isomorphic(graphs.ButterflyGraph())
+        True
+
+    If `n \geq 2`, then the friendship graph `F_n` has `2n + 1` vertices
+    and `3n` edges. It has radius 1, diameter 2, girth 3, and
+    chromatic number 3. Furthermore, `F_n` is planar and Eulerian. ::
+
+        sage: n = randint(2, 10^3)
+        sage: G = graphs.FriendshipGraph(n)
+        sage: G.order() == 2*n + 1
+        True
+        sage: G.size() == 3*n
+        True
+        sage: G.radius()
+        1
+        sage: G.diameter()
+        2
+        sage: G.girth()
+        3
+        sage: G.chromatic_number()                                                      # needs cliquer
+        3
+        sage: G.is_planar()                                                             # needs planarity
+        True
+        sage: G.is_eulerian()
+        True
+
+    TESTS:
+
+    The input ``n`` must be a positive integer. ::
+
+        sage: graphs.FriendshipGraph(randint(-10^5, 0))
+        Traceback (most recent call last):
+        ...
+        ValueError: n must be a positive integer
+    """
+    # sanity checks
+    if n < 1:
+        raise ValueError("n must be a positive integer")
+    # construct the friendship graph
+    if n == 1:
+        from sage.graphs.generators.basic import CycleGraph
+        G = CycleGraph(3)
+        G.name("Friendship graph")
+        return G
+    # build the edges and position dictionaries
+    N = 2 * n + 1           # order of F_n
+    center = 2 * n
+    G = Graph(N, name="Friendship graph")
+    for i in range(0, N - 1, 2):
+        G.add_cycle([center, i, i + 1])
+    G.set_pos({center: (0, 0)})
+    G._circle_embedding(list(range(N - 1)), radius=1)
+    return G
+
+
+def FuzzyBallGraph(partition, q):
+    r"""
+    Construct a Fuzzy Ball graph with the integer partition
+    ``partition`` and ``q`` extra vertices.
+
+    Let `q` be an integer and let `m_1,m_2,...,m_k` be a set of positive
+    integers.  Let `n=q+m_1+...+m_k`.  The Fuzzy Ball graph with partition
+    `m_1,m_2,...,m_k` and `q` extra vertices is the graph constructed from the
+    graph `G=K_n` by attaching, for each `i=1,2,...,k`, a new vertex `a_i` to
+    `m_i` distinct vertices of `G`.
+
+    For given positive integers `k` and `m` and nonnegative
+    integer `q`, the set of graphs ``FuzzyBallGraph(p, q)`` for
+    all partitions `p` of `m` with `k` parts are cospectral with
+    respect to the normalized Laplacian.
+
+    EXAMPLES::
+
+        sage: F = graphs.FuzzyBallGraph([3,1],2)
+        sage: F.adjacency_matrix(vertices=list(F))                                      # needs sage.modules
+        [0 0 1 1 1 0 0 0]
+        [0 0 0 0 0 1 0 0]
+        [1 0 0 1 1 1 1 1]
+        [1 0 1 0 1 1 1 1]
+        [1 0 1 1 0 1 1 1]
+        [0 1 1 1 1 0 1 1]
+        [0 0 1 1 1 1 0 1]
+        [0 0 1 1 1 1 1 0]
+
+    Pick positive integers `m` and `k` and a nonnegative integer `q`.
+    All the FuzzyBallGraphs constructed from partitions of `m` with
+    `k` parts should be cospectral with respect to the normalized
+    Laplacian::
+
+        sage: m = 4; q = 2; k = 2
+        sage: g_list = [graphs.FuzzyBallGraph(p,q)                                      # needs sage.combinat sage.modules
+        ....:           for p in Partitions(m, length=k)]
+        sage: set(g.laplacian_matrix(normalized=True,   # long time (7s on sage.math, 2011), needs sage.combinat sage.modules
+        ....:                        vertices=list(g)).charpoly()
+        ....:     for g in g_list)
+        {x^8 - 8*x^7 + 4079/150*x^6 - 68689/1350*x^5 + 610783/10800*x^4
+          - 120877/3240*x^3 + 1351/100*x^2 - 931/450*x}
+    """
+    from sage.graphs.generators.basic import CompleteGraph
+    if len(partition) < 1:
+        raise ValueError("partition must be a nonempty list of positive integers")
+    n = q + sum(partition)
+    g = CompleteGraph(n)
+    curr_vertex = 0
+    for e, p in enumerate(partition):
+        g.add_edges([(curr_vertex + i, 'a{0}'.format(e + 1)) for i in range(p)])
+        curr_vertex += p
+    return g
+
+
+def FibonacciTree(n):
+    r"""
+    Return the graph of the Fibonacci Tree `F_{i}` of order `n`.
+
+    The Fibonacci tree `F_{i}` is recursively defined as the tree
+    with a root vertex and two attached child trees `F_{i-1}` and
+    `F_{i-2}`, where `F_{1}` is just one vertex and `F_{0}` is empty.
+
+    INPUT:
+
+    - ``n`` -- the recursion depth of the Fibonacci Tree
+
+    EXAMPLES::
+
+        sage: g = graphs.FibonacciTree(3)                                               # needs sage.libs.pari
+        sage: g.is_tree()                                                               # needs sage.libs.pari
+        True
+
+    ::
+
+        sage: l1 = [ len(graphs.FibonacciTree(_)) + 1 for _ in range(6) ]               # needs sage.libs.pari
+        sage: l2 = list(fibonacci_sequence(2,8))                                        # needs sage.libs.pari
+        sage: l1 == l2                                                                  # needs sage.libs.pari
+        True
+
+    AUTHORS:
+
+    - Harald Schilly and Yann Laigle-Chapuy (2010-03-25)
+    """
+    T = Graph(name="Fibonacci-Tree-%d" % n)
+    if n == 1:
+        T.add_vertex(0)
+    if n < 2:
+        return T
+
+    from sage.combinat.combinat import fibonacci_sequence
+    F = list(fibonacci_sequence(n + 2))
+    s = 1.618 ** (n / 1.618 - 1.618)
+    pos = {}
+
+    def fib(level, node, y):
+        pos[node] = (node, y)
+        if level < 2:
+            return
+        level -= 1
+        y -= s
+        diff = F[level]
+        T.add_edge(node, node - diff)
+        if level == 1:  # only one child
+            pos[node - diff] = (node, y)
+            return
+        T.add_edge(node, node + diff)
+        fib(level, node - diff, y)
+        fib(level - 1, node + diff, y)
+
+    T.add_vertices(range(sum(F[:-1])))
+    fib(n, F[n + 1] - 1, 0)
+    T.set_pos(pos)
+
+    return T
+
+
+def GeneralizedPetersenGraph(n, k):
+    r"""
+    Return a generalized Petersen graph with `2n` nodes. The variables
+    `n`, `k` are integers such that `n>2` and `0<k\leq\lfloor(n-1)`/`2\rfloor`
+
+    For `k=1` the result is a graph isomorphic to the circular ladder graph
+    with the same `n`. The regular Petersen Graph has `n=5` and `k=2`.
+    Other named graphs that can be described using this notation include
+    the Desargues graph and the Möbius-Kantor graph.
+
+    INPUT:
+
+    - ``n`` -- the number of nodes is `2*n`
+
+    - ``k`` -- integer (`0<k\leq\lfloor(n-1)`/`2\rfloor`); decides
+      how inner vertices are connected
+
+    PLOTTING: Upon construction, the position dictionary is filled to
+    override the spring-layout algorithm. By convention, the generalized
+    Petersen graphs are displayed as an inner and outer cycle pair, with
+    the first n nodes drawn on the outer circle. The first (0) node is
+    drawn at the top of the outer-circle, moving counterclockwise after that.
+    The inner circle is drawn with the (n)th node at the top, then
+    counterclockwise as well.
+
+    EXAMPLES: For `k=1` the resulting graph will be isomorphic to a circular
+    ladder graph. ::
+
+        sage: g = graphs.GeneralizedPetersenGraph(13,1)
+        sage: g2 = graphs.CircularLadderGraph(13)
+        sage: g.is_isomorphic(g2)
+        True
+
+    The Desargues graph::
+
+        sage: g = graphs.GeneralizedPetersenGraph(10,3)
+        sage: g.girth()
+        6
+        sage: g.is_bipartite()
+        True
+
+    AUTHORS:
+
+    - Anders Jonsson (2009-10-15)
+    """
+    if n < 3:
+        raise ValueError("n must be larger than 2")
+    if k < 1 or k > (n - 1) // 2:
+        raise ValueError("k must be in 1<= k <=floor((n-1)/2)")
+    G = Graph(2 * n, name="Generalized Petersen graph (n='+str(n)+',k="+str(k)+")")
+    for i in range(n):
+        G.add_edge(i, (i+1) % n)
+        G.add_edge(i, i+n)
+        G.add_edge(i+n, n + (i+k) % n)
+    G._circle_embedding(list(range(n)), radius=1, angle=pi/2)
+    G._circle_embedding(list(range(n, 2*n)), radius=.5, angle=pi/2)
+    return G
+
+
+def IGraph(n, j, k):
+    r"""
+    Return an I-graph with `2n` nodes.
+
+    The I-Graph family as been proposed in [BCMS1988]_ as a generalization of
+    the generalized Petersen graphs.  The variables `n`, `j`, `k` are integers
+    such that `n > 2` and `0 < j, k \leq \lfloor (n - 1) / 2 \rfloor`.
+    When `j = 1` the resulting graph is isomorphic to the generalized Petersen
+    graph with the same `n` and `k`.
+
+    INPUT:
+
+    - ``n`` -- the number of nodes is `2 * n`
+
+    - ``j`` -- integer such that `0 < j \leq \lfloor (n-1) / 2 \rfloor`
+      determining how outer vertices are connected
+
+    - ``k`` -- integer such that `0 < k \leq \lfloor (n-1) / 2 \rfloor`
+      determining how inner vertices are connected
+
+    PLOTTING: Upon construction, the position dictionary is filled to override
+    the spring-layout algorithm. By convention, the I-graphs are displayed as an
+    inner and outer cycle pair, with the first n nodes drawn on the outer
+    circle.  The first (0) node is drawn at the top of the outer-circle, moving
+    counterclockwise after that. The inner circle is drawn with the (n)th node
+    at the top, then counterclockwise as well.
+
+    EXAMPLES:
+
+    When `j = 1` the resulting graph will be isomorphic to a generalized
+    Petersen graph::
+
+        sage: g = graphs.IGraph(7,1,2)
+        sage: g2 = graphs.GeneralizedPetersenGraph(7,2)
+        sage: g.is_isomorphic(g2)
+        True
+
+    The IGraph with parameters `(n, j, k)` is isomorphic to the IGraph with
+    parameters `(n, k, j)`::
+
+        sage: g = graphs.IGraph(7, 2, 3)
+        sage: h = graphs.IGraph(7, 3, 2)
+        sage: g.is_isomorphic(h)
+        True
+
+    TESTS::
+
+        sage: graphs.IGraph(1, 1, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: n must be larger than 2
+        sage: graphs.IGraph(3, 0, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: j must be in 1 <= j <= floor((n - 1) / 2)
+        sage: graphs.IGraph(3, 33, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: j must be in 1 <= j <= floor((n - 1) / 2)
+        sage: graphs.IGraph(3, 1, 0)
+        Traceback (most recent call last):
+        ...
+        ValueError: k must be in 1 <= k <= floor((n - 1) / 2)
+        sage: graphs.IGraph(3, 1, 3)
+        Traceback (most recent call last):
+        ...
+        ValueError: k must be in 1 <= k <= floor((n - 1) / 2)
+    """
+    if n < 3:
+        raise ValueError("n must be larger than 2")
+    if j < 1 or j > (n - 1) // 2:
+        raise ValueError("j must be in 1 <= j <= floor((n - 1) / 2)")
+    if k < 1 or k > (n - 1) // 2:
+        raise ValueError("k must be in 1 <= k <= floor((n - 1) / 2)")
+
+    G = Graph(2 * n, name="I-graph (n={}, j={}, k={})".format(n, j, k))
+    for i in range(n):
+        G.add_edge(i, (i + j) % n)
+        G.add_edge(i, i + n)
+        G.add_edge(i + n, n + (i + k) % n)
+    G._circle_embedding(list(range(n)), radius=1, angle=pi/2)
+    G._circle_embedding(list(range(n, 2 * n)), radius=.5, angle=pi/2)
+    return G
+
+
+def DoubleGeneralizedPetersenGraph(n, k):
+    r"""
+    Return a double generalized Petersen graph with `4n` nodes.
+
+    The double generalized Petersen graphs is a family of graphs proposed in
+    [ZF2012]_ as a variant of generalized Petersen graphs.  The variables `n`,
+    `k` are integers such that `n > 2` and `0 < k \leq \lfloor (n-1) / 2
+    \rfloor`.
+
+    INPUT:
+
+    - ``n`` -- the number of nodes is `4 * n`
+
+    - ``k`` -- integer such that `0 < k \leq \lfloor (n-1) / 2 \rfloor`
+      determining how vertices on second and third inner rims are connected
+
+    PLOTTING: Upon construction, the position dictionary is filled to override
+    the spring-layout algorithm. By convention, the double generalized Petersen
+    graphs are displayed as 4 cocentric cycles, with the first n nodes drawn on
+    the outer circle.  The first (0) node is drawn at the top of the
+    outer-circle, moving counterclockwise after that. The second circle is drawn
+    with the (n)th node at the top, then counterclockwise as well. The tird
+    cycle is drawn with the (2n)th node at the top, then counterclockwise.  And
+    the fourth cycle is drawn with the (3n)th node at the top, then again
+    counterclockwise.
+
+    EXAMPLES:
+
+    When `n` is even the resulting graph will be isomorphic to a double
+    generalized Petersen graph with `k' = n / 2 - k`::
+
+        sage: g = graphs.DoubleGeneralizedPetersenGraph(10, 2)
+        sage: g2 = graphs.DoubleGeneralizedPetersenGraph(10, 3)
+        sage: g.is_isomorphic(g2)
+        True
+
+    TESTS::
+
+        sage: graphs.DoubleGeneralizedPetersenGraph(1, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: n must be larger than 2
+        sage: graphs.DoubleGeneralizedPetersenGraph(3, 0)
+        Traceback (most recent call last):
+        ...
+        ValueError: k must be in 1 <= k <= floor((n - 1) / 2)
+        sage: graphs.DoubleGeneralizedPetersenGraph(3, 3)
+        Traceback (most recent call last):
+        ...
+        ValueError: k must be in 1 <= k <= floor((n - 1) / 2)
+    """
+    if n < 3:
+        raise ValueError("n must be larger than 2")
+    if k < 1 or k > (n - 1) // 2:
+        raise ValueError("k must be in 1 <= k <= floor((n - 1) / 2)")
+
+    G = Graph(4 * n, name="Double generalized Petersen graph (n={}, k={})".format(n, k))
+    for i in range(n):
+        G.add_edge(i, (i + 1) % n)
+        G.add_edge(i + 3 * n, (i + 1) % n + 3 * n)
+        G.add_edge(i, i + n)
+        G.add_edge(i + 2 * n, i + 3 * n)
+        G.add_edge(i + n, (i + k) % n + 2 * n)
+        G.add_edge(i + 2 * n, (i + k) % n + n)
+    G._circle_embedding(list(range(n)), radius=3, angle=pi/2)
+    G._circle_embedding(list(range(n, 2 * n)), radius=2, angle=pi/2)
+    G._circle_embedding(list(range(2 * n, 3 * n)), radius=1.5, angle=pi/2)
+    G._circle_embedding(list(range(3 * n, 4 * n)), radius=0.5, angle=pi/2)
+    return G
+
+
+def RoseWindowGraph(n, a, r):
+    r"""
+    Return a rose window graph with `2n` nodes.
+
+    The rose window graphs is a family of tetravalant graphs introduced in
+    [Wilson2008]_. The parameters `n`, `a` and `r` are integers such that
+    `n > 2`, `1 \leq a, r < n`, and `r \neq n / 2`.
+
+    INPUT:
+
+    - ``n`` -- the number of nodes is `2 * n`
+
+    - ``a`` -- integer such that `1 \leq a < n` determining a-spoke edges
+
+    - ``r`` -- integer such that `1 \leq r < n` and `r \neq n / 2` determining
+      how inner vertices are connected
+
+    PLOTTING: Upon construction, the position dictionary is filled to override
+    the spring-layout algorithm. By convention, the rose window graphs are
+    displayed as an inner and outer cycle pair, with the first `n` nodes drawn
+    on the outer circle. The first (0) node is drawn at the top of the
+    outer-circle, moving counterclockwise after that. The inner circle is drawn
+    with the (`n`)th node at the top, then counterclockwise as well. Vertices in
+    the outer circle are connected in the circular manner, vertices in the inner
+    circle are connected when their label have difference `r \pmod{n}`. Vertices
+    on the outer rim are connected with the vertices on the inner rim when they
+    are at the same position and when they are `a` apart.
+
+    EXAMPLES:
+
+    The vertices of a rose window graph have all degree 4::
+
+        sage: G = graphs.RoseWindowGraph(5, 1, 2)
+        sage: all(G.degree(u) == 4 for u in G)
+        True
+
+    The smallest rose window graph as parameters `(3, 2, 1)`::
+
+        sage: G = graphs.RoseWindowGraph(3, 2, 1)
+        sage: all(G.degree(u) == 4 for u in G)
+        True
+
+    TESTS::
+
+        sage: graphs.RoseWindowGraph(1, 1, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: n must be larger than 2
+        sage: graphs.RoseWindowGraph(6, 0, 2)
+        Traceback (most recent call last):
+        ...
+        ValueError: a must be an integer such that 1 <= a < n
+        sage: graphs.RoseWindowGraph(6, 6, 2)
+        Traceback (most recent call last):
+        ...
+        ValueError: a must be an integer such that 1 <= a < n
+        sage: graphs.RoseWindowGraph(6, 3, 0)
+        Traceback (most recent call last):
+        ...
+        ValueError: r must be an integer such that 1 <= r < n
+        sage: graphs.RoseWindowGraph(6, 3, 6)
+        Traceback (most recent call last):
+        ...
+        ValueError: r must be an integer such that 1 <= r < n
+        sage: graphs.RoseWindowGraph(6, 3, 3)
+        Traceback (most recent call last):
+        ...
+        ValueError: r must be different than n / 2
+    """
+    if n < 3:
+        raise ValueError("n must be larger than 2")
+    if a < 1 or a >= n:
+        raise ValueError("a must be an integer such that 1 <= a < n")
+    if r < 1 or r >= n:
+        raise ValueError("r must be an integer such that 1 <= r < n")
+    if r == n / 2:
+        raise ValueError("r must be different than n / 2")
+
+    G = Graph(2 * n, name="rose window graph (n={}, a={}, r={})".format(n, a, r))
+    for i in range(n):
+        G.add_edge(i, (i + 1) % n)
+        G.add_edge(i, i + n)
+        G.add_edge((i + a) % n, i + n)
+        G.add_edge(i + n, (i + r) % n + n)
+    G._circle_embedding(list(range(n)), radius=1, angle=pi/2)
+    G._circle_embedding(list(range(n, 2 * n)), radius=0.5, angle=pi/2)
+    return G
+
+
+def TabacjnGraph(n, a, b, r):
+    r"""
+    Return a Tabačjn graph with `2n` nodes.
+
+    The Tabačjn graphs is a family of pentavalent bicirculants graphs proposed
+    in [AHKOS2014]_ as a generalization of generalized Petersen graphs. The
+    parameters `n`, `a`, `b`, `r` are integers such that `n \geq 3`, `1 \leq a,
+    b, r \leq n - 1`, with `a \neq b` and `r \neq n / 2`.
+
+    INPUT:
+
+    - ``n`` -- the number of nodes is `2 * n`
+
+    - ``a`` -- integer such that `0 < a < n` and `a \neq b`, that determines
+      a-spoke edges
+
+    - ``b`` -- integer such that `0 < b < n` and `b \neq a`, that determines
+      b-spoke edges
+
+    - ``r`` -- integer such that `0 < r < n` and `r \neq n/2` determining how
+      inner vertices are connected
+
+    PLOTTING: Upon construction, the position dictionary is filled to override
+    the spring-layout algorithm. By convention, the rose window graphs are
+    displayed as an inner and outer cycle pair, with the first `n` nodes drawn
+    on the outer circle. The first (0) node is drawn at the top of the
+    outer-circle, moving counterclockwise after that. The inner circle is drawn
+    with the (`n`)th node at the top, then counterclockwise as well. Vertices in
+    the outer circle are connected in the circular manner, vertices in the inner
+    circle are connected when their label have difference `r \pmod{n}`. Vertices
+    on the outer rim are connected with the vertices on the inner rim when they
+    are at the same position and when they are `a` and `b` apart.
+
+    EXAMPLES::
+
+        sage: G = graphs.TabacjnGraph(3, 1, 2, 1)
+        sage: G.degree()
+        [5, 5, 5, 5, 5, 5]
+        sage: G.is_isomorphic(graphs.CompleteGraph(6))
+        True
+        sage: G = graphs.TabacjnGraph(6, 1, 5, 2)
+        sage: I = graphs.IcosahedralGraph()
+        sage: G.is_isomorphic(I)
+        True
+
+    TESTS::
+
+        sage: graphs.TabacjnGraph(1, 1, 1, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: n must be larger than 2
+        sage: graphs.TabacjnGraph(3, 0, 1, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: a must be an integer such that 1 <= a < n
+        sage: graphs.TabacjnGraph(3, 3, 1, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: a must be an integer such that 1 <= a < n
+        sage: graphs.TabacjnGraph(3, 1, 0, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: b must be an integer such that 1 <= b < n
+        sage: graphs.TabacjnGraph(3, 1, 3, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: b must be an integer such that 1 <= b < n
+        sage: graphs.TabacjnGraph(3, 1, 1, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: a must be different than b
+        sage: graphs.TabacjnGraph(3, 1, 2, 0)
+        Traceback (most recent call last):
+        ...
+        ValueError: r must be an integer such that 1 <= r < n
+        sage: graphs.TabacjnGraph(3, 1, 2, 3)
+        Traceback (most recent call last):
+        ...
+        ValueError: r must be an integer such that 1 <= r < n
+        sage: graphs.TabacjnGraph(4, 1, 2, 2)
+        Traceback (most recent call last):
+        ...
+        ValueError: r must be different than n / 2
+    """
+    if n < 3:
+        raise ValueError("n must be larger than 2")
+    if a < 1 or a >= n:
+        raise ValueError("a must be an integer such that 1 <= a < n")
+    if b < 1 or b >= n:
+        raise ValueError("b must be an integer such that 1 <= b < n")
+    if a == b:
+        raise ValueError("a must be different than b")
+    if r < 1 or r >= n:
+        raise ValueError("r must be an integer such that 1 <= r < n")
+    if r == n/2:
+        raise ValueError("r must be different than n / 2")
+
+    G = Graph(2 * n, name="Tabačjn graph (n={}, a={}, b={}, r={})".format(n, a, b, r))
+    for i in range(n):
+        G.add_edge(i, (i + 1) % n)
+        G.add_edge(i, i + n)
+        G.add_edge(i + n, n + (i + r) % n)
+        G.add_edge(i, (i + a) % n + n)
+        G.add_edge(i, (i + b) % n + n)
+    G._circle_embedding(list(range(n)), radius=1, angle=pi/2)
+    G._circle_embedding(list(range(n, 2 * n)), radius=0.5, angle=pi/2)
+    return G
+
+
+def HararyGraph(k, n):
+    r"""
+    Return the Harary graph on `n` vertices and connectivity `k`, where
+    `2 \leq k < n`.
+
+    A `k`-connected graph `G` on `n` vertices requires the minimum degree
+    `\delta(G)\geq k`, so the minimum number of edges `G` should have is
+    `\lceil kn/2\rceil`. Harary graphs achieve this lower bound, that is,
+    Harary graphs are minimal `k`-connected graphs on `n` vertices.
+
+    The construction provided uses the method CirculantGraph.  For more
+    details, see the book [West2001]_ or the `MathWorld article on
+    Harary graphs <http://mathworld.wolfram.com/HararyGraph.html>`_.
+
+    EXAMPLES:
+
+    Harary graphs `H_{k,n}`::
+
+        sage: h = graphs.HararyGraph(5,9); h
+        Harary graph 5, 9: Graph on 9 vertices
+        sage: h.order()
+        9
+        sage: h.size()
+        23
+        sage: h.vertex_connectivity()                                                   # needs sage.numerical.mip
+        5
+
+    TESTS:
+
+    Connectivity of some Harary graphs::
+
+        sage: n = 10
+        sage: for k in range(2,n):                                                      # needs sage.numerical.mip
+        ....:     g = graphs.HararyGraph(k,n)
+        ....:     if k != g.vertex_connectivity():
+        ....:        print("Connectivity of Harary graphs not satisfied.")
+    """
+    if k < 2:
+        raise ValueError("Connectivity parameter k should be at least 2.")
+    if k >= n:
+        raise ValueError("Number of vertices n should be greater than k.")
+
+    if k % 2 == 0:
+        G = CirculantGraph(n, list(range(1, k//2 + 1)))
+    else:
+        if n % 2 == 0:
+            G = CirculantGraph(n, list(range(1, (k - 1)//2 + 1)))
+            for i in range(n):
+                G.add_edge(i, (i + n//2) % n)
+        else:
+            G = HararyGraph(k - 1, n)
+            for i in range((n - 1)//2 + 1):
+                G.add_edge(i, (i + (n - 1)//2) % n)
+    G.name('Harary graph {0}, {1}'.format(k, n))
+    return G
+
+
+def HyperStarGraph(n, k):
+    r"""
+    Return the hyper-star graph `HS(n, k)`.
+
+    The vertices of the hyper-star graph are the set of binary strings of length
+    `n` which contain `k` 1s. Two vertices, `u` and `v`, are adjacent only if
+    `u` can be obtained from `v` by swapping the first bit with a different
+    symbol in another position. For instance, vertex ``'011100'`` of `HS(6, 3)`
+    is adjacent to vertices ``'101100'``, ``'110100'`` and ``'111000'``.
+    See [LKOL2002]_ for more details.
+
+    INPUT:
+
+    - ``n`` -- nonnegative integer; length of the binary strings
+
+    - ``k`` -- nonnegative integer; number of 1s per binary string
+
+    EXAMPLES::
+
+        sage: g = graphs.HyperStarGraph(6,3)
+        sage: sorted(g.neighbors('011100'))
+        ['101100', '110100', '111000']
+        sage: g.plot()                          # long time                             # needs sage.plot
+        Graphics object consisting of 51 graphics primitives
+
+    TESTS::
+
+        sage: graphs.HyperStarGraph(-1, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameters n and k must be nonnegative integers satisfying n >= k >= 0
+        sage: graphs.HyperStarGraph(1, -1)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameters n and k must be nonnegative integers satisfying n >= k >= 0
+        sage: graphs.HyperStarGraph(1, 2)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameters n and k must be nonnegative integers satisfying n >= k >= 0
+
+    AUTHORS:
+
+    - Michael Yurko (2009-09-01)
+    """
+    if n < 0 or k < 0 or k > n:
+        raise ValueError("parameters n and k must be nonnegative integers "
+                         "satisfying n >= k >= 0")
+    if not n:
+        adj = {}
+    elif not k:
+        adj = {'0'*n: []}
+    elif k == n:
+        adj = {'1'*n: []}
+    else:
+        from sage.data_structures.bitset import Bitset
+        adj = dict()
+        # We consider the strings of n bits with k 1s and starting with a 0
+        for c in combinations(range(1, n), k):
+            u = str(Bitset(c, capacity=n))
+            L = []
+            c = list(c)
+            # The neighbors of u are all the strings obtained by swapping a 1
+            # with the first bit (0)
+            for i in range(k):
+                one = c[i]
+                c[i] = 0
+                L.append(str(Bitset(c, capacity=n)))
+                c[i] = one
+            adj[u] = L
+
+    return Graph(adj, format='dict_of_lists', name="HS(%d,%d)" % (n, k))
+
+
+def LCFGraph(n, shift_list, repeats):
+    r"""
+    Return the cubic graph specified in LCF notation.
+
+    LCF (Lederberg-Coxeter-Fruchte) notation is a concise way of describing
+    cubic Hamiltonian graphs. The way a graph is constructed is as
+    follows. Since there is a Hamiltonian cycle, we first create a cycle on `n`
+    nodes. The variable ``shift_list`` = `[s_0, s_1, ..., s_{k-1}]` describes
+    edges to be created by the following scheme: for each `i \in \{0, 1, \dots,
+    k-1\}`, connect vertex `i` to vertex `(i + s_i) \pmod{n}`. Then, ``repeats``
+    specifies the number of times to repeat this process, where on the `j`-th
+    repeat we connect vertex `(i + j k) \pmod{n}` to vertex `(i + j k + s_i)
+    \pmod{n}`.
+
+    For more details, see the :wikipedia:`LCF_notation` and [Fru1977]_,
+    [Gru2003]_ pp. 357-365, and [Led1965]_.
+
+    INPUT:
+
+    -  ``n`` -- the number of nodes
+
+    -  ``shift_list`` -- a list of integer shifts mod `n`
+
+    - ``repeats`` -- the number of times to repeat the process
+
+    EXAMPLES::
+
+        sage: G = graphs.LCFGraph(4, [2,-2], 2)                                         # needs networkx
+        sage: G.is_isomorphic(graphs.TetrahedralGraph())                                # needs networkx
+        True
+
+    ::
+
+        sage: G = graphs.LCFGraph(20, [10,7,4,-4,-7,10,-4,7,-7,4], 2)                   # needs networkx
+        sage: G.is_isomorphic(graphs.DodecahedralGraph())                               # needs networkx
+        True
+
+    ::
+
+        sage: G = graphs.LCFGraph(14, [5,-5], 7)                                        # needs networkx
+        sage: G.is_isomorphic(graphs.HeawoodGraph())                                    # needs networkx
+        True
+
+    The largest cubic nonplanar graph of diameter three::
+
+        sage: # needs networkx
+        sage: G = graphs.LCFGraph(20, [-10,-7,-5,4,7,-10,-7,-4,5,7,
+        ....:                          -10,-7,6,-5,7,-10,-7,5,-6,7], 1)
+        sage: G.degree()
+        [3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3]
+        sage: G.diameter()
+        3
+        sage: G.show()                          # long time                             # needs sage.plot
+
+    PLOTTING: LCF Graphs are plotted as an `n`-cycle with edges in the
+    middle, as described above.
+    """
+    import networkx
+    G = Graph(networkx.LCF_graph(n, shift_list, repeats), name="LCF Graph")
+    G._circle_embedding(list(range(n)), radius=1, angle=pi/2)
+    return G
+
+
+def MycielskiGraph(k=1, relabel=True):
+    r"""
+    Return the `k`-th Mycielski Graph.
+
+    The graph `M_k` is triangle-free and has chromatic number
+    equal to `k`. These graphs show, constructively, that there
+    are triangle-free graphs with arbitrarily high chromatic
+    number.
+
+    The Mycielski graphs are built recursively starting with
+    `M_0`, an empty graph; `M_1`, a single vertex graph; and `M_2`
+    is the graph `K_2`.  `M_{k+1}` is then built from `M_k`
+    as follows:
+
+    If the vertices of `M_k` are `v_1,\ldots,v_n`, then the
+    vertices of `M_{k+1}` are
+    `v_1,\ldots,v_n,w_1,\ldots,w_n,z`. Vertices `v_1,\ldots,v_n`
+    induce a copy of `M_k`. Vertices `w_1,\ldots,w_n` are an
+    independent set. Vertex `z` is adjacent to all the
+    `w_i`-vertices. Finally, vertex `w_i` is adjacent to vertex
+    `v_j` iff `v_i` is adjacent to `v_j`.
+
+    For more details, see the :wikipedia:`Mycielskian`.
+
+    INPUT:
+
+    - ``k`` -- number of steps in the construction process
+
+    - ``relabel`` -- relabel the vertices so their names are the integers
+      ``range(n)`` where ``n`` is the number of vertices in the graph
+
+    EXAMPLES:
+
+    The Mycielski graph `M_k` is triangle-free and has chromatic
+    number equal to `k`. ::
+
+        sage: g = graphs.MycielskiGraph(5)
+        sage: g.is_triangle_free()
+        True
+        sage: g.chromatic_number()                                                      # needs cliquer
+        5
+
+    The graphs `M_4` is (isomorphic to) the Grotzsch graph. ::
+
+        sage: g = graphs.MycielskiGraph(4)
+        sage: g.is_isomorphic(graphs.GrotzschGraph())
+        True
+    """
+    g = Graph()
+    g.name("Mycielski Graph " + str(k))
+
+    if k < 0:
+        raise ValueError("parameter k must be a nonnegative integer")
+
+    if k == 0:
+        return g
+
+    if k == 1:
+        g.add_vertex(0)
+        return g
+
+    if k == 2:
+        g.add_edge(0, 1)
+        return g
+
+    g0 = MycielskiGraph(k - 1)
+    g = MycielskiStep(g0)
+    g.name("Mycielski Graph " + str(k))
+    if relabel:
+        g.relabel()
+
+    return g
+
+
+def MycielskiStep(g):
+    r"""
+    Perform one iteration of the Mycielski construction.
+
+    See the documentation for ``MycielskiGraph`` which uses this
+    method. We expose it to all users in case they may find it
+    useful.
+
+    EXAMPLE. One iteration of the Mycielski step applied to the
+    5-cycle yields a graph isomorphic to the Grotzsch graph ::
+
+        sage: g = graphs.CycleGraph(5)
+        sage: h = graphs.MycielskiStep(g)
+        sage: h.is_isomorphic(graphs.GrotzschGraph())
+        True
+    """
+    # Make a copy of the input graph g
+    gg = copy(g)
+
+    # rename a vertex v of gg as (1,v)
+    renamer = {v: (1, v) for v in g}
+    gg.relabel(renamer)
+
+    # add the w vertices to gg as (2,v)
+    wlist = [(2, v) for v in g]
+    gg.add_vertices(wlist)
+
+    # add the z vertex as (0,0)
+    gg.add_vertex((0, 0))
+
+    # add the edges from z to w_i
+    gg.add_edges([((0, 0), (2, v)) for v in g])
+
+    # make the v_i w_j edges
+    for v in g:
+        gg.add_edges([((1, v), (2, vv)) for vv in g.neighbors(v)])
+
+    return gg
+
+
+def NKStarGraph(n, k):
+    r"""
+    Return the `(n,k)`-star graph.
+
+    The vertices of the `(n,k)`-star graph are the set of all arrangements of
+    `n` symbols into labels of length `k`. There are two adjacency rules for the
+    `(n,k)`-star graph. First, two vertices are adjacent if one can be obtained
+    from the other by swapping the first symbol with another symbol. Second, two
+    vertices are adjacent if one can be obtained from the other by swapping the
+    first symbol with an external symbol (a symbol not used in the original
+    label).
+
+    INPUT:
+
+    -  ``n`` -- integer; number of symbols
+
+    -  ``k`` -- integer; length of the labels of the vertices
+
+    EXAMPLES::
+
+        sage: g = graphs.NKStarGraph(4,2)
+        sage: g.plot()                          # long time                             # needs sage.plot
+        Graphics object consisting of 31 graphics primitives
+
+    REFERENCES:
+
+    [CC1995]_
+
+    AUTHORS:
+
+    - Michael Yurko (2009-09-01)
+    """
+    from sage.combinat.permutation import Arrangements
+    # set from which to permute
+    set = [str(i) for i in range(1, n + 1)]
+    # create dict
+    d = {}
+    for v in Arrangements(set, k):
+        v = list(v)  # So we can easily mutate it
+        tmp_dict = {}
+        # add edges of dimension i
+        for i in range(1, k):
+            # swap 0th and ith element
+            v[0], v[i] = v[i], v[0]
+            # convert to str and add to list
+            vert = "".join(v)
+            tmp_dict[vert] = None
+            # swap back
+            v[0], v[i] = v[i], v[0]
+        # add other edges
+        tmp_bit = v[0]
+        for i in set:
+            # check if external
+            if i not in v:
+                v[0] = i
+                # add edge
+                vert = "".join(v)
+                tmp_dict[vert] = None
+            v[0] = tmp_bit
+        d["".join(v)] = tmp_dict
+    return Graph(d, name="(%d,%d)-star" % (n, k))
+
+
+def NStarGraph(n):
+    r"""
+    Return the `n`-star graph.
+
+    The vertices of the `n`-star graph are the set of permutations on `n`
+    symbols. There is an edge between two vertices if their labels differ
+    only in the first and one other position.
+
+    INPUT:
+
+    -  ``n`` -- integer; number of symbols
+
+    EXAMPLES::
+
+        sage: g = graphs.NStarGraph(4)
+        sage: g.plot()                          # long time                             # needs sage.plot
+        Graphics object consisting of 61 graphics primitives
+
+    REFERENCES:
+
+    [AHK1994]_
+
+    AUTHORS:
+
+    - Michael Yurko (2009-09-01)
+    """
+    from sage.combinat.permutation import Permutations
+    # set from which to permute
+    set = [str(i) for i in range(1, n + 1)]
+    # create dictionary of lists
+    # vertices are adjacent if the first element is swapped with the ith element
+    d = {}
+    for v in Permutations(set):
+        v = list(v)  # So we can easily mutate it
+        tmp_dict = {}
+        for i in range(1, n):
+            if v[0] != v[i]:
+                # swap 0th and ith element
+                v[0], v[i] = v[i], v[0]
+                # convert to str and add to list
+                vert = "".join(v)
+                tmp_dict[vert] = None
+                # swap back
+                v[0], v[i] = v[i], v[0]
+        d["".join(v)] = tmp_dict
+    return Graph(d, name="%d-star" % n)
+
+
+def OddGraph(n):
+    r"""
+    Return the Odd Graph with parameter `n`.
+
+    The Odd Graph with parameter `n` is defined as the
+    Kneser Graph with parameters `2n-1,n-1`.
+    Equivalently, the Odd Graph is the graph whose vertices
+    are the `n-1`-subsets of `[0,1,\dots,2(n-1)]`, and such
+    that two vertices are adjacent if their corresponding sets
+    are disjoint.
+
+    For example, the Petersen Graph can be defined
+    as the Odd Graph with parameter `3`.
+
+    EXAMPLES::
+
+        sage: OG = graphs.OddGraph(3)
+        sage: sorted(OG.vertex_iterator(), key=str)
+        [{1, 2}, {1, 3}, {1, 4}, {1, 5}, {2, 3}, {2, 4}, {2, 5},
+         {3, 4}, {3, 5}, {4, 5}]
+        sage: P = graphs.PetersenGraph()
+        sage: P.is_isomorphic(OG)
+        True
+
+    TESTS::
+
+        sage: KG = graphs.OddGraph(1)
+        Traceback (most recent call last):
+        ...
+        ValueError: Parameter n should be an integer strictly greater than 1
+    """
+    if n <= 1:
+        raise ValueError("Parameter n should be an integer strictly greater than 1")
+    g = KneserGraph(2*n - 1, n - 1)
+    g.name("Odd Graph with parameter %s" % n)
+    return g
+
+
+def PaleyGraph(q):
+    r"""
+    Paley graph with `q` vertices.
+
+    Parameter `q` must be the power of a prime number and congruent
+    to 1 mod 4.
+
+    EXAMPLES::
+
+        sage: G = graphs.PaleyGraph(9); G                                               # needs sage.rings.finite_rings
+        Paley graph with parameter 9: Graph on 9 vertices
+        sage: G.is_regular()                                                            # needs sage.rings.finite_rings
+        True
+
+    A Paley graph is always self-complementary::
+
+        sage: G.is_self_complementary()                                                 # needs sage.rings.finite_rings
+        True
+
+    TESTS:
+
+    Wrong parameter::
+
+        sage: graphs.PaleyGraph(6)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameter q must be a prime power
+        sage: graphs.PaleyGraph(3)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameter q must be congruent to 1 mod 4
+    """
+    from sage.rings.finite_rings.integer_mod import mod
+    from sage.rings.finite_rings.finite_field_constructor import FiniteField
+    from sage.arith.misc import is_prime_power
+    if not is_prime_power(q):
+        raise ValueError("parameter q must be a prime power")
+    if not mod(q, 4) == 1:
+        raise ValueError("parameter q must be congruent to 1 mod 4")
+    g = Graph([FiniteField(q, 'a'), lambda i, j: (i - j).is_square()],
+              loops=False, name="Paley graph with parameter {}".format(q))
+    return g
+
+
+def PasechnikGraph(n):
+    r"""
+    Pasechnik strongly regular graph on `(4n-1)^2` vertices.
+
+    A strongly regular graph with parameters of the orthogonal array graph
+    :func:`~sage.graphs.graph_generators.GraphGenerators.OrthogonalArrayBlockGraph`,
+    also known as pseudo Latin squares graph `L_{2n-1}(4n-1)`, constructed from
+    a skew Hadamard matrix of order `4n` following [Pas1992]_.
+
+    .. SEEALSO::
+
+        - :func:`~sage.graphs.strongly_regular_db.is_orthogonal_array_block_graph`
+
+    EXAMPLES::
+
+        sage: graphs.PasechnikGraph(4).is_strongly_regular(parameters=True)             # needs sage.combinat sage.modules
+        (225, 98, 43, 42)
+        sage: graphs.PasechnikGraph(5).is_strongly_regular(parameters=True)     # long time, needs sage.combinat sage.modules
+        (361, 162, 73, 72)
+        sage: graphs.PasechnikGraph(9).is_strongly_regular(parameters=True)  # not tested
+        (1225, 578, 273, 272)
+
+    TESTS::
+
+        sage: graphs.PasechnikGraph(0)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameter n must be >= 1
+    """
+    if n < 1:
+        raise ValueError("parameter n must be >= 1")
+    from sage.combinat.matrices.hadamard_matrix import skew_hadamard_matrix
+    from sage.matrix.constructor import identity_matrix
+    H = skew_hadamard_matrix(4 * n)
+    M = H[1:].T[1:] - identity_matrix(4 * n - 1)
+    G = Graph(M.tensor_product(M.T), format='seidel_adjacency_matrix')
+    G.relabel()
+    G.name("Pasechnik Graph_{}".format(n))
+    return G
+
+
+def SquaredSkewHadamardMatrixGraph(n):
+    r"""
+    Pseudo-`OA(2n,4n-1)`-graph from a skew Hadamard matrix of order `4n`.
+
+    A strongly regular graph with parameters of the orthogonal array graph
+    :func:`~sage.graphs.graph_generators.GraphGenerators.OrthogonalArrayBlockGraph`,
+    also known as pseudo Latin squares graph `L_{2n}(4n-1)`, constructed from a
+    skew Hadamard matrix of order `4n`, due to Goethals and Seidel, see
+    [BL1984]_.
+
+    .. SEEALSO::
+
+        - :func:`~sage.graphs.strongly_regular_db.is_orthogonal_array_block_graph`
+
+    EXAMPLES::
+
+        sage: # needs sage.combinat sage.modules
+        sage: G = graphs.SquaredSkewHadamardMatrixGraph(4)
+        sage: G.is_strongly_regular(parameters=True)
+        (225, 112, 55, 56)
+        sage: G = graphs.SquaredSkewHadamardMatrixGraph(5)
+        sage: G.is_strongly_regular(parameters=True)    # long time
+        (361, 180, 89, 90)
+        sage: G = graphs.SquaredSkewHadamardMatrixGraph(9)
+        sage: G.is_strongly_regular(parameters=True)    # not tested
+        (1225, 612, 305, 306)
+
+    TESTS::
+
+        sage: graphs.SquaredSkewHadamardMatrixGraph(0)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameter n must be >= 1
+    """
+    if n < 1:
+        raise ValueError("parameter n must be >= 1")
+    from sage.combinat.matrices.hadamard_matrix import skew_hadamard_matrix
+    from sage.matrix.constructor import identity_matrix, matrix
+    idm = identity_matrix(4 * n - 1)
+    e = matrix([1] * (4 * n - 1))
+    H = skew_hadamard_matrix(4 * n)
+    M = H[1:].T[1:] - idm
+    s = M.tensor_product(M.T) - idm.tensor_product(e.T * e - idm)
+    G = Graph(s, format='seidel_adjacency_matrix')
+    G.relabel()
+    G.name("skewhad^2_{}".format(n))
+    return G
+
+
+def SwitchedSquaredSkewHadamardMatrixGraph(n):
+    r"""
+    A strongly regular graph in Seidel switching class of
+    :meth:`~sage.graphs.graph_generators.GraphGenerators.SquaredSkewHadamardMatrixGraph`.
+
+    A strongly regular graph in the :meth:`Seidel switching
+    <Graph.seidel_switching>` class of the disjoint union of a 1-vertex graph
+    and the one produced by :func:`Pseudo-L_{2n}(4n-1)
+    <sage.graphs.graph_generators.GraphGenerators.SquaredSkewHadamardMatrixGraph>`
+
+    In this case, the other possible parameter set of a strongly regular graph
+    in the Seidel switching class of the latter graph (see [BH2012]_) coincides
+    with the set of parameters of the complement of the graph returned by this
+    function.
+
+    .. SEEALSO::
+
+        - :func:`~sage.graphs.strongly_regular_db.is_switch_skewhad`
+
+    EXAMPLES::
+
+        sage: # needs sage.combinat sage.modules
+        sage: g = graphs.SwitchedSquaredSkewHadamardMatrixGraph(4)
+        sage: g.is_strongly_regular(parameters=True)
+        (226, 105, 48, 49)
+        sage: from sage.combinat.designs.twographs import twograph_descendant
+        sage: twograph_descendant(g, 0).is_strongly_regular(parameters=True)
+        (225, 112, 55, 56)
+        sage: gc = g.complement()
+        sage: twograph_descendant(gc, 0).is_strongly_regular(parameters=True)
+        (225, 112, 55, 56)
+
+    TESTS::
+
+        sage: graphs.SwitchedSquaredSkewHadamardMatrixGraph(0)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameter n must be >= 1
+    """
+    G = SquaredSkewHadamardMatrixGraph(n).complement()
+    G.add_vertex((4 * n - 1)**2)
+    G.seidel_switching(list(range((4 * n - 1) * (2 * n - 1))))
+    G.name("switch skewhad^2+*_" + str(n))
+    return G
+
+
+def HanoiTowerGraph(pegs, disks, labels=True, positions=True):
+    r"""
+    Return the graph whose vertices are the states of the
+    Tower of Hanoi puzzle, with edges representing legal moves between states.
+
+    INPUT:
+
+    - ``pegs`` -- the number of pegs in the puzzle, 2 or greater
+    - ``disks`` -- the number of disks in the puzzle, 1 or greater
+    - ``labels`` -- (default: ``True``) if ``True`` the graph contains
+      more meaningful labels, see explanation below.  For large instances,
+      turn off labels for much faster creation of the graph.
+    - ``positions`` -- (default: ``True``) if ``True`` the graph contains
+      layout information.  This creates a planar layout for the case
+      of three pegs.  For large instances, turn off layout information
+      for much faster creation of the graph.
+
+    OUTPUT:
+
+    The Tower of Hanoi puzzle has a certain number of identical pegs
+    and a certain number of disks, each of a different radius.
+    Initially the disks are all on a single peg, arranged
+    in order of their radii, with the largest on the bottom.
+
+    The goal of the puzzle is to move the disks to any other peg,
+    arranged in the same order.  The one constraint is that the
+    disks resident on any one peg must always be arranged with larger
+    radii lower down.
+
+    The vertices of this graph represent all the possible states
+    of this puzzle.  Each state of the puzzle is a tuple with length
+    equal to the number of disks, ordered by largest disk first.
+    The entry of the tuple is the peg where that disk resides.
+    Since disks on a given peg must go down in size as we go
+    up the peg, this totally describes the state of the puzzle.
+
+    For example ``(2,0,0)`` means the large disk is on peg 2, the
+    medium disk is on peg 0, and the small disk is on peg 0
+    (and we know the small disk must be above the medium disk).
+    We encode these tuples as integers with a base equal to
+    the number of pegs, and low-order digits to the right.
+
+    Two vertices are adjacent if we can change the puzzle from
+    one state to the other by moving a single disk.  For example,
+    ``(2,0,0)`` is adjacent to ``(2,0,1)`` since we can move
+    the small disk off peg 0 and onto (the empty) peg 1.
+    So the solution to a 3-disk puzzle (with at least
+    two pegs) can be expressed by the shortest path between
+    ``(0,0,0)`` and ``(1,1,1)``.  For more on this representation
+    of the graph, or its properties, see [AD2010]_.
+
+    For greatest speed we create graphs with integer vertices,
+    where we encode the tuples as integers with a base equal
+    to the number of pegs, and low-order digits to the right.
+    So for example, in a 3-peg puzzle with 5 disks, the
+    state ``(1,2,0,1,1)`` is encoded as
+    `1\ast 3^4 + 2\ast 3^3 + 0\ast 3^2 + 1\ast 3^1 + 1\ast 3^0 = 139`.
+
+    For smaller graphs, the labels that are the tuples are informative,
+    but slow down creation of the graph.  Likewise computing layout
+    information also incurs a significant speed penalty. For maximum
+    speed, turn off labels and layout and decode the
+    vertices explicitly as needed.  The
+    :meth:`sage.rings.integer.Integer.digits`
+    with the ``padsto`` option is a quick way to do this, though you
+    may want to reverse the list that is output.
+
+    .. SEEALSO::
+
+        - :meth:`~sage.graphs.generators.families.GeneralizedSierpinskiGraph`
+
+    PLOTTING:
+
+    The layout computed when ``positions = True`` will
+    look especially good for the three-peg case, when the graph is known
+    to be planar.  Except for two small cases on 4 pegs, the graph is
+    otherwise not planar, and likely there is a better way to layout
+    the vertices.
+
+    EXAMPLES:
+
+    A classic puzzle uses 3 pegs.  We solve the 5 disk puzzle using
+    integer labels and report the minimum number of moves required.
+    Note that `3^5-1` is the state where all 5 disks
+    are on peg 2. ::
+
+        sage: H = graphs.HanoiTowerGraph(3, 5, labels=False, positions=False)
+        sage: H.distance(0, 3^5-1)
+        31
+
+    A slightly larger instance. ::
+
+        sage: H = graphs.HanoiTowerGraph(4, 6, labels=False, positions=False)
+        sage: H.num_verts()
+        4096
+        sage: H.distance(0, 4^6-1)
+        17
+
+    For a small graph, labels and layout information can be useful.
+    Here we explicitly list a solution as a list of states. ::
+
+        sage: H = graphs.HanoiTowerGraph(3, 3, labels=True, positions=True)
+        sage: H.shortest_path((0,0,0), (1,1,1))
+        [(0, 0, 0), (0, 0, 1), (0, 2, 1), (0, 2, 2), (1, 2, 2), (1, 2, 0), (1, 1, 0), (1, 1, 1)]
+
+    Some facts about this graph with `p` pegs and `d` disks:
+
+    - only automorphisms are the "obvious" ones -- renumber the pegs
+    - chromatic number is less than or equal to `p`
+    - independence number is `p^{d-1}`
+
+    ::
+
+        sage: H = graphs.HanoiTowerGraph(3, 4, labels=False, positions=False)
+        sage: H.automorphism_group().is_isomorphic(SymmetricGroup(3))                   # needs sage.groups
+        True
+        sage: H.chromatic_number()                              # needs cliquer
+        3
+        sage: len(H.independent_set()) == 3^(4-1)
+        True
+
+    TESTS:
+
+    It is an error to have just one peg (or less). ::
+
+        sage: graphs.HanoiTowerGraph(1, 5)
+        Traceback (most recent call last):
+        ...
+        ValueError: Pegs for Tower of Hanoi graph should be two or greater (not 1)
+
+    It is an error to have zero disks (or less). ::
+
+        sage: graphs.HanoiTowerGraph(2, 0)
+        Traceback (most recent call last):
+        ...
+        ValueError: Disks for Tower of Hanoi graph should be one or greater (not 0)
+
+    AUTHOR:
+
+    - Rob Beezer, (2009-12-26), with assistance from Su Doree
+    """
+    # sanitize input
+    from sage.rings.integer import Integer
+    pegs = Integer(pegs)
+    if pegs < 2:
+        raise ValueError("Pegs for Tower of Hanoi graph should be two or greater (not %d)" % pegs)
+    disks = Integer(disks)
+    if disks < 1:
+        raise ValueError("Disks for Tower of Hanoi graph should be one or greater (not %d)" % disks)
+
+    # Each state of the puzzle is a tuple with length
+    # equal to the number of disks, ordered by largest disk first
+    # The entry of the tuple is the peg where that disk resides
+    # Since disks on a given peg must go down in size as we go
+    # up the peg, this totally describes the puzzle
+    # We encode these tuples as integers with a base equal to
+    # the number of pegs, and low-order digits to the right
+
+    # complete graph on number of pegs when just a single disk
+    edges = [[i, j] for i in range(pegs) for j in range(i + 1, pegs)]
+
+    nverts = 1
+    for d in range(2, disks+1):
+        prevedges = edges      # remember subgraph to build from
+        nverts = pegs*nverts   # pegs^(d-1)
+        edges = []
+
+        # Take an edge, change its two states in the same way by adding
+        # a large disk to the bottom of the same peg in each state
+        # This is accomplished by adding a multiple of pegs^(d-1)
+        for p in range(pegs):
+            largedisk = p*nverts
+            for anedge in prevedges:
+                edges.append([anedge[0] + largedisk, anedge[1] + largedisk])
+
+        # Two new states may only differ in the large disk
+        # being the only disk on two different pegs, thus
+        # otherwise being a common state with one less disk
+        # We construct all such pairs of new states and add as edges
+        from sage.combinat.subset import Subsets
+        for state in range(nverts):
+            emptypegs = list(range(pegs))
+            reduced_state = state
+            for i in range(d-1):
+                apeg = reduced_state % pegs
+                if apeg in emptypegs:
+                    emptypegs.remove(apeg)
+                reduced_state = reduced_state//pegs
+            for freea, freeb in Subsets(emptypegs, 2):
+                edges.append([freea*nverts + state, freeb*nverts + state])
+
+    H = Graph({}, loops=False, multiedges=False)
+    H.add_edges(edges)
+
+    # Making labels and/or computing positions can take a long time,
+    # relative to just constructing the edges on integer vertices.
+    # We try to minimize coercion overhead, but need Sage
+    # Integers in order to use digits() for labels.
+    # Getting the digits with custom code was no faster.
+    # Layouts are circular (symmetric on the number of pegs)
+    # radiating outward to the number of disks (radius)
+    # Algorithm uses some combination of alternate
+    # clockwise/counterclockwise placements, which
+    # works well for three pegs (planar layout)
+    #
+    if labels or positions:
+        mapping = {}
+        pos = {}
+        a = Integer(-1)
+        one = Integer(1)
+        if positions:
+            radius_multiplier = 1 + 1/sin(pi/pegs)
+            sine = []
+            cosine = []
+            for i in range(pegs):
+                angle = 2*i*pi/float(pegs)
+                sine.append(sin(angle))
+                cosine.append(cos(angle))
+        for i in range(pegs**disks):
+            a += one
+            state = a.digits(base=pegs, padto=disks)
+            if labels:
+                state.reverse()
+                mapping[i] = tuple(state)
+                state.reverse()
+            if positions:
+                locx = 0.0
+                locy = 0.0
+                radius = 1.0
+                parity = -1.0
+                for index in range(disks):
+                    p = state[index]
+                    radius *= radius_multiplier
+                    parity *= -1.0
+                    locx_temp = cosine[p]*locx - parity*sine[p]*locy + radius*cosine[p]
+                    locy_temp = parity*sine[p]*locx + cosine[p]*locy - radius*parity*sine[p]
+                    locx = locx_temp
+                    locy = locy_temp
+                pos[i] = (locx, locy)
+        # set positions, then relabel (not vice versa)
+        if positions:
+            H.set_pos(pos)
+        if labels:
+            H.relabel(mapping)
+
+    return H
+
+
+def line_graph_forbidden_subgraphs():
+    r"""
+    Return the 9 forbidden subgraphs of a line graph.
+
+    See the :wikipedia:`Line_graph` for more information.
+
+    The graphs are returned in the ordering given by the Wikipedia
+    drawing, read from left to right and from top to bottom.
+
+    EXAMPLES::
+
+        sage: graphs.line_graph_forbidden_subgraphs()
+        [Claw graph: Graph on 4 vertices,
+        Graph on 6 vertices,
+        Graph on 6 vertices,
+        Graph on 5 vertices,
+        Graph on 6 vertices,
+        Graph on 6 vertices,
+        Graph on 6 vertices,
+        Graph on 6 vertices,
+        Graph on 5 vertices]
+    """
+    from sage.graphs.graph import Graph
+    from sage.graphs.generators.basic import ClawGraph
+    graphs = [ClawGraph()]
+
+    graphs.append(Graph({
+                0: [1, 2, 3],
+                1: [2, 3],
+                4: [2],
+                5: [3]
+                }))
+
+    graphs.append(Graph({
+                0: [1, 2, 3, 4],
+                1: [2, 3, 4],
+                3: [4],
+                2: [5]
+                }))
+
+    graphs.append(Graph({
+                0: [1, 2, 3],
+                1: [2, 3],
+                4: [2, 3]
+                }))
+
+    graphs.append(Graph({
+                0: [1, 2, 3],
+                1: [2, 3],
+                4: [2],
+                5: [3, 4]
+                }))
+
+    graphs.append(Graph({
+                0: [1, 2, 3, 4],
+                1: [2, 3, 4],
+                3: [4],
+                5: [2, 0, 1]
+                }))
+
+    graphs.append(Graph({
+                5: [0, 1, 2, 3, 4],
+                0: [1, 4],
+                2: [1, 3],
+                3: [4]
+                }))
+
+    graphs.append(Graph({
+                1: [0, 2, 3, 4],
+                3: [0, 4],
+                2: [4, 5],
+                4: [5]
+                }))
+
+    graphs.append(Graph({
+                0: [1, 2, 3],
+                1: [2, 3, 4],
+                2: [3, 4],
+                3: [4]
+                }))
+
+    return graphs
+
+
+def petersen_family(generate=False):
+    r"""
+    Return the Petersen family.
+
+    The Petersen family is a collection of 7 graphs which are the forbidden
+    minors of the linklessly embeddable graphs. For more information see the
+    :wikipedia:`Petersen_family`.
+
+    INPUT:
+
+    - ``generate`` -- boolean; whether to generate the family from the
+      `\Delta-Y` transformations. When set to ``False`` (default) a hardcoded
+      version of the graphs (with a prettier layout) is returned.
+
+    EXAMPLES::
+
+        sage: graphs.petersen_family()
+        [Petersen graph: Graph on 10 vertices,
+         Complete graph: Graph on 6 vertices,
+         Multipartite Graph with set sizes [3, 3, 1]: Graph on 7 vertices,
+         Graph on 8 vertices,
+         Graph on 9 vertices,
+         Graph on 7 vertices,
+         Graph on 8 vertices]
+
+    The two different inputs generate the same graphs::
+
+        sage: F1 = graphs.petersen_family(generate=False)
+        sage: F2 = graphs.petersen_family(generate=True)                                # needs sage.modules
+        sage: F1 = [g.canonical_label().graph6_string() for g in F1]
+        sage: F2 = [g.canonical_label().graph6_string() for g in F2]                    # needs sage.modules
+        sage: set(F1) == set(F2)                                                        # needs sage.modules
+        True
+    """
+    from sage.graphs.generators.smallgraphs import PetersenGraph
+    if not generate:
+        from sage.graphs.generators.basic import CompleteGraph, \
+             CompleteBipartiteGraph, CompleteMultipartiteGraph
+        l = [PetersenGraph(), CompleteGraph(6),
+             CompleteMultipartiteGraph([3, 3, 1])]
+        g = CompleteBipartiteGraph(4, 4)
+        g.delete_edge(0, 4)
+        g.name("")
+        l.append(g)
+        g = Graph('HKN?Yeb')
+        g._circle_embedding([1, 2, 4, 3, 0, 5])
+        g._circle_embedding([6, 7, 8], radius=.6, shift=1.25)
+        l.append(g)
+        g = Graph('Fs\\zw')
+        g._circle_embedding([1, 2, 3])
+        g._circle_embedding([4, 5, 6], radius=.7)
+        g._pos[0] = (0, 0)
+        l.append(g)
+        g = Graph('GYQ[p{')
+        g._circle_embedding([1, 4, 6, 0, 5, 7, 3], shift=0.25)
+        g._pos[2] = (0, 0)
+        l.append(g)
+        return l
+
+    def DeltaYTrans(G, triangle):
+        """
+        Apply a Delta-Y transformation to a given triangle of G.
+        """
+        a, b, c = triangle
+        G = G.copy()
+        G.delete_edges([(a, b), (b, c), (c, a)])
+        v = G.order()
+        G.add_edges([(a, v), (b, v), (c, v)])
+        return G.canonical_label()
+
+    def YDeltaTrans(G, v):
+        """
+        Apply a Y-Delta transformation to a given vertex v of G.
+        """
+        G = G.copy()
+        a, b, c = G.neighbors(v)
+        G.delete_vertex(v)
+        G.add_cycle([a, b, c])
+        return G.canonical_label()
+
+    # We start from the Petersen Graph, and apply Y-Delta transform
+    # for as long as we generate new graphs.
+    P = PetersenGraph()
+
+    l = set([])
+    l_new = [P.canonical_label().graph6_string()]
+
+    while l_new:
+        g = l_new.pop(0)
+        if g in l:
+            continue
+        l.add(g)
+        g = Graph(g)
+        # All possible Delta-Y transforms
+        for t in g.subgraph_search_iterator(Graph({1: [2, 3], 2: [3]}), return_graphs=False):
+            l_new.append(DeltaYTrans(g, t).graph6_string())
+        # All possible Y-Delta transforms
+        for v in g:
+            if g.degree(v) == 3:
+                l_new.append(YDeltaTrans(g, v).graph6_string())
+
+    return [Graph(x) for x in l]
+
+
+def SierpinskiGasketGraph(n):
+    """
+    Return the Sierpinski Gasket graph of generation `n`.
+
+    All vertices but 3 have valence 4.
+
+    INPUT:
+
+    - ``n`` -- integer
+
+    OUTPUT:
+
+    a graph `S_n` with `3 (3^{n-1}+1)/2` vertices and
+    `3^n` edges, closely related to the famous Sierpinski triangle
+    fractal.
+
+    All these graphs have a triangular shape, and three special
+    vertices at top, bottom left and bottom right. These are the only
+    vertices of valence 2, all the other ones having valence 4.
+
+    The graph `S_1` (generation `1`) is a triangle.
+
+    The graph `S_{n+1}` is obtained from the disjoint union of
+    three copies A,B,C of `S_n` by identifying pairs of vertices:
+    the top vertex of A with the bottom left vertex of B,
+    the bottom right vertex of B with the top vertex of C,
+    and the bottom left vertex of C with the bottom right vertex of A.
+
+    .. PLOT::
+
+        sphinx_plot(graphs.SierpinskiGasketGraph(4).plot(vertex_labels=False))
+
+    .. SEEALSO::
+
+        - :meth:`~sage.graphs.generators.families.HanoiTowerGraph`. There is
+          another family of graphs called Sierpinski graphs, where all vertices
+          but 3 have valence 3. They are available using
+          ``graphs.HanoiTowerGraph(3, n)``.
+        - :meth:`~sage.graphs.generators.families.GeneralizedSierpinskiGraph`
+
+    EXAMPLES::
+
+        sage: # needs sage.modules
+        sage: s4 = graphs.SierpinskiGasketGraph(4); s4
+        Graph on 42 vertices
+        sage: s4.size()
+        81
+        sage: s4.degree_histogram()
+        [0, 0, 3, 0, 39]
+        sage: s4.is_hamiltonian()
+        True
+
+    REFERENCES:
+
+    [LLWC2011]_
+    """
+    from sage.modules.free_module_element import vector
+    from sage.rings.rational_field import QQ
+
+    if n <= 0:
+        raise ValueError('n should be at least 1')
+
+    def next_step(triangle_list):
+        # compute the next subdivision
+        resu = []
+        for a, b, c in triangle_list:
+            ab = (a + b) / 2
+            bc = (b + c) / 2
+            ac = (a + c) / 2
+            resu += [(a, ab, ac), (ab, b, bc), (ac, bc, c)]
+        return resu
+
+    tri_list = [list(vector(QQ, u) for u in [(0, 0), (0, 1), (1, 0)])]
+    for k in range(n - 1):
+        tri_list = next_step(tri_list)
+    dg = Graph()
+    dg.add_edges([(tuple(a), tuple(b)) for a, b, c in tri_list])
+    dg.add_edges([(tuple(b), tuple(c)) for a, b, c in tri_list])
+    dg.add_edges([(tuple(c), tuple(a)) for a, b, c in tri_list])
+    dg.set_pos({(x, y): (x + y / 2, y * 3 / 4)
+                for (x, y) in dg})
+    dg.relabel()
+    return dg
+
+
+def GeneralizedSierpinskiGraph(G, k, stretch=None):
+    r"""
+    Return the generalized Sierpinski graph of `G` of dimension `k`.
+
+    Generalized Sierpinski graphs have been introduced in [GKP2011]_ to
+    generalize the notion of Sierpinski graphs [KM1997]_.
+
+    Given a graph `G = (V, E)` of order `n` and a parameter `k`, the generalized
+    Sierpinski graph of `G` of dimension `k`, denoted by `S(G, k)`, can be
+    constructed recursively from `G` as follows. `S(G, 1)` is isomorphic to
+    `G`. To construct `S(G, k)` for `k > 1`, copy `n` times `S(G, k - 1)`, once
+    per vertex `u \in V`, and add `u` at the beginning of the labels of each
+    vertex in the copy of `S(G, k - 1)` corresponding to vertex `u`. Then for
+    any edge `\{u, v\} \in E`, add an edge between vertex `(u, v, \ldots, v)`
+    and vertex `(v, u, \ldots, u)`.
+
+    INPUT:
+
+    - ``G`` -- a sage Graph
+
+    - ``k`` -- integer; the dimension
+
+    - ``stretch`` -- integer (default: ``None``); stretching factor used to
+      determine the positions of the vertices of the output graph. By default
+      (``None``), this value is set to twice the maximum Euclidean distance
+      between the vertices of `G`. This parameter is used only when the vertices
+      of `G` have positions.
+
+    .. SEEALSO::
+
+        - :meth:`~sage.graphs.generators.families.SierpinskiGasketGraph`
+        - :meth:`~sage.graphs.generators.families.HanoiTowerGraph`
+
+    EXAMPLES:
+
+    The generalized Sierpinski graph of dimension 1 of any graph `G`
+    is isomorphic to `G`::
+
+        sage: G = graphs.RandomGNP(10, .5)
+        sage: S = graphs.GeneralizedSierpinskiGraph(G, 1)
+        sage: S.is_isomorphic(G)
+        True
+
+    When `G` is a clique of order 3, the generalized Sierpinski graphs
+    of `G` are isomorphic to Hanoi Tower graphs::
+
+        sage: k = randint(1, 5)
+        sage: S = graphs.GeneralizedSierpinskiGraph(graphs.CompleteGraph(3), k)         # needs sage.modules
+        sage: H = graphs.HanoiTowerGraph(3, k)
+        sage: S.is_isomorphic(H)                                                        # needs sage.modules
+        True
+
+    The generalized Sierpinski graph of dimension `k` of any graph `G` with `n`
+    vertices and `m` edges has `n^k` vertices and `m\sum_{i=0}^{k-1}n^i` edges::
+
+        sage: # needs sage.modules
+        sage: n = randint(2, 6)
+        sage: k = randint(1, 5)
+        sage: G = graphs.RandomGNP(n, .5)
+        sage: m = G.size()
+        sage: S = graphs.GeneralizedSierpinskiGraph(G, k)
+        sage: S.order() == n**k
+        True
+        sage: S.size() == m*sum([n**i for i in range(k)])
+        True
+        sage: G = graphs.CompleteGraph(n)
+        sage: S = graphs.GeneralizedSierpinskiGraph(G, k)
+        sage: S.order() == n**k
+        True
+        sage: S.size() == (n*(n - 1)/2)*sum([n**i for i in range(k)])
+        True
+
+    The positions of the vertices of the output graph are determined from the
+    positions of the vertices of `G`, if any::
+
+        sage: G = graphs.HouseGraph()
+        sage: G.get_pos() is not None
+        True
+        sage: H = graphs.GeneralizedSierpinskiGraph(G, 2)                               # needs sage.symbolic
+        sage: H.get_pos() is not None                                                   # needs sage.symbolic
+        True
+        sage: G = Graph([(0, 1)])
+        sage: G.get_pos() is not None
+        False
+        sage: H = graphs.GeneralizedSierpinskiGraph(G, 2)                               # needs sage.symbolic
+        sage: H.get_pos() is not None                                                   # needs sage.symbolic
+        False
+
+    .. PLOT::
+
+        sphinx_plot(graphs.GeneralizedSierpinskiGraph(graphs.HouseGraph(), 2).plot(vertex_labels=False))
+
+    TESTS::
+
+        sage: # needs sage.modules
+        sage: graphs.GeneralizedSierpinskiGraph(Graph(), 3)
+        Generalized Sierpinski Graph of Graph on 0 vertices of dimension 3: Graph on 0 vertices
+        sage: graphs.GeneralizedSierpinskiGraph(Graph(1), 3).vertices(sort=False)
+        [(0, 0, 0)]
+        sage: G = graphs.GeneralizedSierpinskiGraph(Graph(2), 3)
+        sage: G.order(), G.size()
+        (8, 0)
+        sage: graphs.GeneralizedSierpinskiGraph("foo", 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameter G must be a Graph
+        sage: graphs.GeneralizedSierpinskiGraph(Graph(), 0)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameter k must be >= 1
+    """
+    if not isinstance(G, Graph):
+        raise ValueError("parameter G must be a Graph")
+    if k < 1:
+        raise ValueError("parameter k must be >= 1")
+    loops = G.allows_loops()
+    multiedges = G.allows_multiple_edges()
+
+    def rec(H, kk):
+        if kk == 1:
+            return H
+        I = Graph(loops=loops, multiedges=multiedges)
+        # add one copy of H per vertex of G
+        for i in G:
+            J = H.relabel(perm={u: (i,) + u for u in H}, inplace=False)
+            I.add_vertices(J)
+            I.add_edges(J.edge_iterator(labels=False, sort_vertices=False))
+        # For each edge {u, v} of G, add edge {(u, v, ..., v), (v, u, ..., u)}
+        l = len(next(H.vertex_iterator()))
+        for u, v in G.edges(sort=True, labels=False):
+            I.add_edge((u,) + (v,)*l, (v,) + (u,)*l)
+        return rec(I, kk - 1)
+
+    H = G.relabel(perm={u: (u,) for u in G}, inplace=False)
+    if H and k > 1:
+        H = rec(H, k)
+    H.name("Generalized Sierpinski Graph of {} of dimension {}".format(G, k))
+
+    # If the vertices of G have positions, we set the positions of vertices of H
+    pos = G.get_pos()
+    if pos:
+        if stretch is None:
+            # Find the geometric diameter
+            from sage.modules.free_module_element import vector
+            L = [vector(p) for p in pos.values()]
+            stretch = 2 * max((u - v).norm() for u, v in combinations(L, 2))
+
+        H.set_pos({u: (sum(pos[x][0]*stretch**(k-i) for i, x in enumerate(u)),
+                       sum(pos[y][1]*stretch**(k-i) for i, y in enumerate(u)))
+                   for u in H})
+    return H
+
+
+def WheelGraph(n):
+    """
+    Return a Wheel graph with `n` nodes.
+
+    A Wheel graph is a basic structure where one node is connected to all other
+    nodes and those (outer) nodes are connected cyclically.
+
+    PLOTTING: Upon construction, the position dictionary is filled to override
+    the spring-layout algorithm. By convention, each wheel graph will be
+    displayed with the first (0) node in the center, the second node at the top,
+    and the rest following in a counterclockwise manner.
+
+    With the wheel graph, we see that it doesn't take a very large `n` at all
+    for the spring-layout to give a counter-intuitive display. (See Graphics
+    Array examples below).
+
+    EXAMPLES:
+
+    We view many wheel graphs with a Sage Graphics Array, first with this
+    constructor (i.e., the position dictionary filled)::
+
+        sage: # needs sage.plot
+        sage: g = []
+        sage: j = []
+        sage: for i in range(9):
+        ....:  k = graphs.WheelGraph(i+3)
+        ....:  g.append(k)
+        ...
+        sage: for i in range(3):
+        ....:  n = []
+        ....:  for m in range(3):
+        ....:      n.append(g[3*i + m].plot(vertex_size=50, vertex_labels=False))
+        ....:  j.append(n)
+        ...
+        sage: G = graphics_array(j)
+        sage: G.show()                          # long time
+
+    Next, using the spring-layout algorithm::
+
+        sage: # needs networkx sage.plot
+        sage: import networkx
+        sage: g = []
+        sage: j = []
+        sage: for i in range(9):
+        ....:  spr = networkx.wheel_graph(i+3)
+        ....:  k = Graph(spr)
+        ....:  g.append(k)
+        ...
+        sage: for i in range(3):
+        ....:  n = []
+        ....:  for m in range(3):
+        ....:      n.append(g[3*i + m].plot(vertex_size=50, vertex_labels=False))
+        ....:  j.append(n)
+        ...
+        sage: G = graphics_array(j)
+        sage: G.show()                          # long time
+
+    Compare the plotting::
+
+        sage: # needs networkx sage.plot
+        sage: n = networkx.wheel_graph(23)
+        sage: spring23 = Graph(n)
+        sage: posdict23 = graphs.WheelGraph(23)
+        sage: spring23.show()                   # long time
+        sage: posdict23.show()  # long time
+    """
+    from sage.graphs.generators.basic import CycleGraph
+    if n < 4:
+        G = CycleGraph(n)
+    else:
+        G = CycleGraph(n-1)
+        G.relabel(perm=list(range(1, n)), inplace=True)
+        G.add_edges([(0, i) for i in range(1, n)])
+        G._pos[0] = (0, 0)
+    G.name("Wheel graph")
+    return G
+
+
+def WindmillGraph(k, n):
+    r"""
+    Return the Windmill graph `Wd(k, n)`.
+
+    The windmill graph `Wd(k, n)` is an undirected graph constructed for `k \geq
+    2` and `n \geq 2` by joining `n` copies of the complete graph `K_k` at a
+    shared vertex. It has `(k-1)n+1` vertices and `nk(k-1)/2` edges, girth 3 (if
+    `k > 2`), radius 1 and diameter 2. It has vertex connectivity 1 because its
+    central vertex is an articulation point; however, like the complete graphs
+    from which it is formed, it is `(k-1)`-edge-connected. It is trivially
+    perfect and a block graph.
+
+    .. SEEALSO::
+
+        - :wikipedia:`Windmill_graph`
+        - :meth:`GraphGenerators.StarGraph`
+        - :meth:`GraphGenerators.FriendshipGraph`
+
+    EXAMPLES:
+
+    The Windmill graph `Wd(2, n)` is a star graph::
+
+        sage: n = 5
+        sage: W = graphs.WindmillGraph(2, n)
+        sage: W.is_isomorphic( graphs.StarGraph(n) )
+        True
+
+    The Windmill graph `Wd(3, n)` is the Friendship graph `F_n`::
+
+        sage: n = 5
+        sage: W = graphs.WindmillGraph(3, n)
+        sage: W.is_isomorphic( graphs.FriendshipGraph(n) )
+        True
+
+    The Windmill graph `Wd(3, 2)` is the Butterfly graph::
+
+        sage: W = graphs.WindmillGraph(3, 2)
+        sage: W.is_isomorphic( graphs.ButterflyGraph() )
+        True
+
+    The Windmill graph `Wd(k, n)` has chromatic number `k`::
+
+        sage: n,k = 5,6
+        sage: W = graphs.WindmillGraph(k, n)
+        sage: W.chromatic_number() == k                         # needs cliquer
+        True
+
+    TESTS:
+
+    Giving too small parameters::
+
+        sage: graphs.WindmillGraph(1, 2)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameters k and n must be >= 2
+        sage: graphs.WindmillGraph(2, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameters k and n must be >= 2
+    """
+    if k < 2 or n < 2:
+        raise ValueError('parameters k and n must be >= 2')
+
+    if k == 2:
+        from sage.graphs.generators.basic import StarGraph
+        G = StarGraph(n)
+    else:
+        sector = 2*pi/n
+        slide = 1/sin(sector/4)
+
+        pos_dict = {}
+        for i in range(0, k):
+            x = float(cos(i*pi/(k-2)))
+            y = float(sin(i*pi/(k-2))) + slide
+            pos_dict[i] = (x, y)
+
+        G = Graph()
+        pos = {0: [0, 0]}
+        for i in range(n):
+            V = list(range(i*(k - 1) + 1, (i + 1)*(k - 1) + 1))
+            G.add_clique([0]+V)
+            for j, v in enumerate(V):
+                x, y = pos_dict[j]
+                xv = x*cos(i*sector) - y*sin(i*sector)
+                yv = x*sin(i*sector) + y*cos(i*sector)
+                pos[v] = [xv, yv]
+
+        G.set_pos(pos)
+
+    G.name("Windmill graph Wd({}, {})".format(k, n))
+    return G
+
+
+def trees(vertices):
+    r"""
+    Return a generator of the distinct trees on a fixed number of vertices.
+
+    INPUT:
+
+    - ``vertices`` -- the size of the trees created
+
+    OUTPUT:
+
+    A generator which creates an exhaustive, duplicate-free listing
+    of the connected free (unlabeled) trees with ``vertices`` number
+    of vertices.  A tree is a graph with no cycles.
+
+    ALGORITHM:
+
+    Uses an algorithm that generates each new tree
+    in constant time.  See the documentation for, and implementation
+    of, the :mod:`sage.graphs.trees` module, including a citation.
+
+    EXAMPLES:
+
+    We create an iterator, then loop over its elements. ::
+
+        sage: tree_iterator = graphs.trees(7)
+        sage: for T in tree_iterator:
+        ....:     print(T.degree_sequence())
+        [2, 2, 2, 2, 2, 1, 1]
+        [3, 2, 2, 2, 1, 1, 1]
+        [3, 2, 2, 2, 1, 1, 1]
+        [4, 2, 2, 1, 1, 1, 1]
+        [3, 3, 2, 1, 1, 1, 1]
+        [3, 3, 2, 1, 1, 1, 1]
+        [4, 3, 1, 1, 1, 1, 1]
+        [3, 2, 2, 2, 1, 1, 1]
+        [4, 2, 2, 1, 1, 1, 1]
+        [5, 2, 1, 1, 1, 1, 1]
+        [6, 1, 1, 1, 1, 1, 1]
+
+    The number of trees on the first few vertex counts.
+    This is sequence A000055 in Sloane's OEIS. ::
+
+        sage: [len(list(graphs.trees(i))) for i in range(0, 15)]
+        [1, 1, 1, 1, 2, 3, 6, 11, 23, 47, 106, 235, 551, 1301, 3159]
+    """
+    from sage.graphs.trees import TreeIterator
+    return iter(TreeIterator(vertices))
+
+
+def nauty_gentreeg(options='', debug=False):
+    r"""
+    Return a generator which creates non-isomorphic trees from nauty's gentreeg
+    program.
+
+    INPUT:
+
+    - ``options`` -- string (default: ``""``); a string passed to ``gentreeg``
+      as if it was run at a system command line. At a minimum, you *must* pass
+      the number of vertices you desire. Sage expects the graphs to be in
+      nauty's "sparse6" format, do not set an option to change this default or
+      results will be unpredictable.
+
+    - ``debug`` -- boolean (default: ``False``); if ``True`` the first line of
+      ``gentreeg``'s output to standard error is captured and the first call to
+      the generator's ``next()`` function will return this line as a string. A
+      line leading with ">A" indicates a successful initiation of the program
+      with some information on the arguments, while a line beginning with ">E"
+      indicates an error with the input.
+
+    The possible options, obtained as output of ``gentreeg -help``::
+
+           n            : the number of vertices. Must be in range 1..128
+        res/mod         : only generate subset res out of subsets 0..mod-1
+          -D<int>       : an upper bound for the maximum degree
+          -Z<int>:<int> : bounds on the diameter
+          -q            : suppress auxiliary output
+
+    Options which cause ``gentreeg`` to use an output format different than the
+    sparse6 format are not listed above (-p, -l, -u) as they will confuse the
+    creation of a Sage graph. The res/mod option can be useful when using the
+    output in a routine run several times in parallel.
+
+    OUTPUT:
+
+    A generator which will produce the graphs as Sage graphs. These will be
+    simple graphs: no loops, no multiple edges, no directed edges.
+
+    .. SEEALSO::
+
+        :meth:`trees` -- another generator of trees
+
+    EXAMPLES:
+
+    The generator can be used to construct trees for testing, one at a time
+    (usually inside a loop). Or it can be used to create an entire list all at
+    once if there is sufficient memory to contain it::
+
+        sage: # needs nauty
+        sage: gen = graphs.nauty_gentreeg("4")
+        sage: next(gen)
+        Graph on 4 vertices
+        sage: next(gen)
+        Graph on 4 vertices
+        sage: next(gen)
+        Traceback (most recent call last):
+        ...
+        StopIteration
+
+    The number of trees on the first few vertex counts. This agrees with
+    :oeis:`A000055`::
+
+        sage: [len(list(graphs.nauty_gentreeg(str(i)))) for i in range(1, 15)]          # needs nauty
+        [1, 1, 1, 2, 3, 6, 11, 23, 47, 106, 235, 551, 1301, 3159]
+
+    The ``debug`` switch can be used to examine ``gentreeg``'s reaction to the
+    input in the ``options`` string.  We illustrate success. (A failure will be
+    a string beginning with ">E".)  Passing the "-q" switch to ``gentreeg`` will
+    suppress the indicator of a successful initiation, and so the first returned
+    value might be an empty string if ``debug`` is ``True``::
+
+        sage: # needs nauty
+        sage: gen = graphs.nauty_gentreeg("4", debug=True)
+        sage: print(next(gen))
+        >A ...gentreeg ...
+        sage: gen = graphs.nauty_gentreeg("4 -q", debug=True)
+        sage: next(gen)
+        ''
+
+    TESTS:
+
+    The number `n` of vertices must be in range 1..128::
+
+        sage: # needs nauty
+        sage: list(graphs.nauty_gentreeg("0", debug=False))
+        Traceback (most recent call last):
+        ...
+        ValueError: wrong format of parameter options
+        sage: list(graphs.nauty_gentreeg("0", debug=True))
+        ['>E gentreeg: n must be in the range 1..128\n']
+        sage: list(graphs.nauty_gentreeg("200", debug=True))
+        ['>E gentreeg: n must be in the range 1..128\n']
+
+    Wrong input::
+
+        sage: # needs nauty
+        sage: list(graphs.nauty_gentreeg("3 -x", debug=False))
+        Traceback (most recent call last):
+        ...
+        ValueError: wrong format of parameter options
+        sage: list(graphs.nauty_gentreeg("3 -x", debug=True))
+        ['>E Usage: ...gentreeg [-D#] [-Z#:#] [-ulps] [-q] n... [res/mod] ...
+        sage: list(graphs.nauty_gentreeg("3", debug=True))
+        ['>A ...gentreeg ...\n', Graph on 3 vertices]
+    """
+    import shlex
+    from sage.features.nauty import NautyExecutable
+    gen_path = NautyExecutable("gentreeg").absolute_filename()
+    sp = subprocess.Popen(shlex.quote(gen_path) + " {0}".format(options), shell=True,
+                          stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                          stderr=subprocess.PIPE, close_fds=True,
+                          encoding='latin-1')
+    msg = sp.stderr.readline()
+    if debug:
+        yield msg
+    elif msg.startswith('>E'):
+        raise ValueError('wrong format of parameter options')
+    gen = sp.stdout
+    while True:
+        try:
+            s = next(gen)
+        except StopIteration:
+            # Exhausted list of graphs from nauty geng
+            return
+        G = Graph(s[:-1], format='sparse6', loops=False, multiedges=False)
+        yield G
+
+
+def RingedTree(k, vertex_labels=True):
+    r"""
+    Return the ringed tree on k-levels.
+
+    A ringed tree of level `k` is a binary tree with `k` levels (counting
+    the root as a level), in which all vertices at the same level are connected
+    by a ring.
+
+    More precisely, in each layer of the binary tree (i.e. a layer is the set of
+    vertices `[2^i...2^{i+1}-1]`) two vertices `u,v` are adjacent if `u=v+1` or
+    if `u=2^i` and `v=2^{i+1}-1`.
+
+    Ringed trees are defined in [CFHM2013]_.
+
+    INPUT:
+
+    - ``k`` -- the number of levels of the ringed tree
+
+    - ``vertex_labels`` -- boolean; whether to label vertices as binary words
+      (default) or as integers
+
+    EXAMPLES::
+
+        sage: # needs networkx
+        sage: G = graphs.RingedTree(5)
+        sage: P = G.plot(vertex_labels=False, vertex_size=10)                           # needs sage.plot
+        sage: P.show()                          # long time                             # needs sage.plot
+        sage: G.vertices(sort=True)
+        ['', '0', '00', '000', '0000', '0001', '001', '0010', '0011', '01',
+         '010', '0100', '0101', '011', '0110', '0111', '1', '10', '100',
+         '1000', '1001', '101', '1010', '1011', '11', '110', '1100', '1101',
+         '111', '1110', '1111']
+
+    TESTS::
+
+        sage: G = graphs.RingedTree(-1)
+        Traceback (most recent call last):
+        ...
+        ValueError: The number of levels must be >= 1.
+        sage: G = graphs.RingedTree(5, vertex_labels=False)                             # needs networkx
+        sage: G.vertices(sort=True)                                                     # needs networkx
+        [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17,
+        18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30]
+    """
+    if k < 1:
+        raise ValueError('The number of levels must be >= 1.')
+
+    # Creating the Balanced tree, which contains most edges already
+    g = BalancedTree(2, k - 1)
+    g.name('Ringed Tree on ' + str(k) + ' levels')
+
+    # We consider edges layer by layer
+    for i in range(1, k):
+        vertices = list(range(2**(i) - 1, 2**(i + 1) - 1))
+
+        # Add the missing edges
+        g.add_cycle(vertices)
+
+        # And set the vertices' positions
+        radius = i if i <= 1 else 1.5**i
+        shift = -2**(i - 2) + .5 if i > 1 else 0
+        g._circle_embedding(vertices, radius=radius, shift=shift)
+
+    # Specific position for the central vertex
+    g._pos[0] = (0, 0.2)
+
+    # Relabel vertices as binary words
+    if not vertex_labels:
+        return g
+
+    vertices = ['']
+    for i in range(k - 1):
+        for j in range(2**(i) - 1, 2**(i + 1) - 1):
+            v = vertices[j]
+            vertices.append(v + '0')
+            vertices.append(v + '1')
+
+    g.relabel(vertices)
+
+    return g
+
+
+def MathonPseudocyclicMergingGraph(M, t):
+    r"""
+    Mathon's merging of classes in a pseudo-cyclic 3-class association scheme.
+
+    Construct strongly regular graphs from p.97 of [BL1984]_.
+
+    INPUT:
+
+    - ``M`` -- the list of matrices in a pseudo-cyclic 3-class association scheme;
+      the identity matrix must be the first entry
+
+    - ``t`` -- integer; the number of the graph, from 0 to 2
+
+    .. SEEALSO::
+
+        - :func:`~sage.graphs.strongly_regular_db.is_muzychuk_S6`
+
+    TESTS::
+
+        sage: from sage.graphs.generators.families import MathonPseudocyclicMergingGraph as mer
+        sage: from sage.graphs.generators.smallgraphs import _EllipticLinesProjectivePlaneScheme as ES
+
+        sage: # long time, needs sage.libs.gap
+        sage: G = mer(ES(3), 0)
+        sage: G.is_strongly_regular(parameters=True)
+        (784, 243, 82, 72)
+        sage: G = mer(ES(3), 1)
+        sage: G.is_strongly_regular(parameters=True)
+        (784, 270, 98, 90)
+        sage: G = mer(ES(3), 2)
+        sage: G.is_strongly_regular(parameters=True)
+        (784, 297, 116, 110)
+        sage: G = mer(ES(2), 2)
+        Traceback (most recent call last):
+        ...
+        AssertionError...
+
+        sage: # needs sage.libs.gap
+        sage: M = ES(3)
+        sage: M = [M[1],M[0],M[2],M[3]]
+        sage: G = mer(M, 2)
+        Traceback (most recent call last):
+        ...
+        AssertionError...
+    """
+    from sage.graphs.graph import Graph
+    from sage.matrix.constructor import identity_matrix
+    assert len(M) == 4
+    assert M[0] == identity_matrix(M[0].nrows())
+    A = sum(x.tensor_product(x) for x in M[1:])
+    if t > 0:
+        A += sum(x.tensor_product(M[0]) for x in M[1:])
+    if t > 1:
+        A += sum(M[0].tensor_product(x) for x in M[1:])
+    return Graph(A)
+
+
+def MathonPseudocyclicStronglyRegularGraph(t, G=None, L=None):
+    r"""
+    Return a strongly regular graph on `(4t+1)(4t-1)^2` vertices from
+    [Mat1978]_.
+
+    Let `4t-1` be a prime power, and `4t+1` be such that there exists
+    a strongly regular graph `G` with parameters `(4t+1,2t,t-1,t)`. In
+    particular, `4t+1` must be a sum of two squares [Mat1978]_. With
+    this input, Mathon [Mat1978]_ gives a construction of a strongly regular
+    graph with parameters `(4 \mu + 1, 2 \mu, \mu-1, \mu)`, where
+    `\mu =  t(4t(4t-1)-1)`. The construction is optionally parametrised by an
+    a skew-symmetric Latin square of order `4t+1`, with entries in
+    `-2t,...,-1,0,1,...,2t`.
+
+    Our implementation follows a description given in [ST1981]_.
+
+    INPUT:
+
+    - ``t`` -- positive integer
+
+    - ``G`` -- if ``None`` (default), try to construct the necessary graph
+      with parameters `(4t+1,2t,t-1,t)`, otherwise use the user-supplied one,
+      with vertices labelled from `0` to `4t`.
+
+    - ``L`` -- if ``None`` (default), construct a necessary skew Latin square,
+      otherwise use the user-supplied one. Here non-isomorphic Latin squares
+      -- one constructed from `Z/9Z`, and the other from `(Z/3Z)^2` --
+      lead to non-isomorphic graphs.
+
+    .. SEEALSO::
+
+        - :func:`~sage.graphs.strongly_regular_db.is_mathon_PC_srg`
+
+    EXAMPLES:
+
+    Using default ``G`` and ``L``. ::
+
+        sage: from sage.graphs.generators.families import MathonPseudocyclicStronglyRegularGraph
+        sage: G = MathonPseudocyclicStronglyRegularGraph(1); G                          # needs database_graphs sage.modules sage.rings.finite_rings
+        Mathon's PC SRG on 45 vertices: Graph on 45 vertices
+        sage: G.is_strongly_regular(parameters=True)                                    # needs database_graphs sage.modules sage.rings.finite_rings
+        (45, 22, 10, 11)
+
+    Supplying ``G`` and ``L`` (constructed from the automorphism group
+    of ``G``). The entries of L can't be tested directly because
+    there's some unpredictability in the way that GAP chooses a
+    representative in ``NormalSubgroups()``, the function that
+    underlies our own
+    :meth:`~sage.groups.perm_gps.permgroup.PermutationGroup_generic.normal_subgroups`
+    method::
+
+        sage: # needs sage.groups sage.libs.gap sage.rings.finite_rings
+        sage: G = graphs.PaleyGraph(9)
+        sage: a = G.automorphism_group(partition=[sorted(G)])
+        sage: it = (x for x in a.normal_subgroups() if x.order() == 9)
+        sage: subg = next(iter(it))
+        sage: r = [matrix(libgap.PermutationMat(libgap(z), 9).sage())
+        ....:      for z in subg]
+        sage: ff = list(map(lambda y: (y[0]-1,y[1]-1),
+        ....:          Permutation(map(lambda x: 1+r.index(x^-1), r)).cycle_tuples()[1:]))
+        sage: L = sum(i*(r[a]-r[b]) for i,(a,b) in zip(range(1,len(ff)+1), ff))
+        sage: G.relabel(range(9))
+        sage: G3x3 = graphs.MathonPseudocyclicStronglyRegularGraph(2, G=G, L=L)
+        sage: G3x3.is_strongly_regular(parameters=True)
+        (441, 220, 109, 110)
+        sage: G3x3.automorphism_group(algorithm='bliss').order()  # optional - bliss
+        27
+        sage: G9 = graphs.MathonPseudocyclicStronglyRegularGraph(2)
+        sage: G9.is_strongly_regular(parameters=True)
+        (441, 220, 109, 110)
+        sage: G9.automorphism_group(algorithm='bliss').order()  # optional - bliss
+        9
+
+    TESTS::
+
+        sage: graphs.MathonPseudocyclicStronglyRegularGraph(5)                          # needs sage.modules
+        Traceback (most recent call last):
+        ...
+        ValueError: 21  must be a sum of two squares!...
+    """
+    from sage.rings.finite_rings.finite_field_constructor import FiniteField as GF
+    from sage.rings.integer_ring import ZZ
+    from sage.matrix.constructor import matrix, block_matrix, \
+        ones_matrix, identity_matrix
+    from sage.arith.misc import two_squares
+    p = 4*t + 1
+    try:
+        x = two_squares(p)
+    except ValueError:
+        raise ValueError(str(p)+" must be a sum of two squares!")
+    if G is None:
+        from sage.graphs.strongly_regular_db import strongly_regular_graph as SRG
+        G = SRG(p, 2*t, t - 1)
+        G.relabel(range(p))
+    if L is None:
+        from sage.matrix.constructor import circulant
+        L = circulant(list(range(2 * t + 1)) + list(range(-2 * t, 0)))
+    q = 4*t - 1
+    K = GF(q, prefix='x')
+    K_pairs = set(frozenset([x, -x]) for x in K)
+    K_pairs.discard(frozenset([0]))
+    a = [None]*(q-1)    # order the non-0 elements of K as required
+    for i, (x, y) in enumerate(K_pairs):
+        a[i] = x
+        a[-i-1] = y
+    a.append(K(0))      # and append the 0 of K at the end
+    P = [matrix(ZZ, q, q, lambda i, j: 1 if a[j] == a[i] + b else 0)
+         for b in a]
+    g = K.primitive_element()
+    F = sum(P[a.index(g**(2*i))] for i in range(1, 2*t))
+    E = matrix(ZZ, q, q, lambda i, j: 0 if (a[j] - a[0]).is_square() else 1)
+
+    def B(m):
+        I = identity_matrix(q)
+        J = ones_matrix(q)
+        if m == 0:
+            def f(i, j):
+                if i == j:
+                    return 0 * I
+                elif (a[j] - a[i]).is_square():
+                    return I + F
+                else:
+                    return J - F
+        elif m < 2*t:
+            def f(i, j):
+                return F * P[a.index(g**(2*m) * (a[i] + a[j]))]
+        elif m == 2*t:
+            def f(i, j):
+                return E * P[i]
+        return block_matrix(q, q, [f(i, j) for i in range(q) for j in range(q)])
+
+    def Acon(i, j):
+        J = ones_matrix(q**2)
+        if i == j:
+            return B(0)
+        if L[i, j] > 0:
+            if G.has_edge(i, j):
+                return B(L[i, j])
+            return J - B(L[i, j])
+        if G.has_edge(i, j):
+            return B(-L[i, j]).T
+        return J - B(-L[i, j]).T
+
+    A = Graph(block_matrix(p, p, [Acon(i, j) for i in range(p) for j in range(p)]))
+    A.name("Mathon's PC SRG on " + str(p*q**2) + " vertices")
+    A.relabel()
+    return A
+
+
+def TuranGraph(n, r):
+    r"""
+    Return the Turan graph with parameters `n, r`.
+
+    Turan graphs are complete multipartite graphs with `n` vertices and `r`
+    subsets, denoted `T(n,r)`, with the property that the sizes of the subsets
+    are as close to equal as possible. The graph `T(n,r)` will have `n \pmod r`
+    subsets of size `\lfloor n/r \rfloor` and `r - (n \pmod r)` subsets of size
+    `\lceil n/r \rceil`. See the :wikipedia:`Turan_graph` for more information.
+
+    INPUT:
+
+    - ``n`` -- integer; the number of vertices in the graph
+
+    - ``r`` -- integer; the number of partitions of the graph
+
+    EXAMPLES:
+
+    The Turan graph is a complete multipartite graph::
+
+        sage: g = graphs.TuranGraph(13, 4)
+        sage: k = graphs.CompleteMultipartiteGraph([3,3,3,4])
+        sage: g.is_isomorphic(k)
+        True
+
+    The Turan graph `T(n,r)` has `\frac{(r-1)(n^2-s^2)}{2r} + \frac{s(s-1)}{2}`
+    edges, where `s = n \mod r` (:issue:`34249`)::
+
+        sage: n = 12
+        sage: r = 8
+        sage: g = graphs.TuranGraph(n, r)
+        sage: def count(n, r):
+        ....:     s = n % r
+        ....:     return (r - 1) * (n**2 - s**2) / (2*r) + s*(s - 1)/2
+        sage: g.size() == count(n, r)
+        True
+        sage: n = randint(3, 100)
+        sage: r = randint(2, n - 1)
+        sage: g = graphs.TuranGraph(n, r)
+        sage: g.size() == count(n, r)
+        True
+
+    TESTS::
+
+        sage: g = graphs.TuranGraph(3,6)
+        Traceback (most recent call last):
+        ...
+        ValueError: input parameters must satisfy "1 < r < n"
+    """
+    if n < 1 or n < r or r < 1:
+        raise ValueError('input parameters must satisfy "1 < r < n"')
+
+    from sage.graphs.generators.basic import CompleteMultipartiteGraph
+
+    p = n // r
+    s = n % r
+    vertex_sets = [p]*(r - s) + [p + 1]*s
+
+    g = CompleteMultipartiteGraph(vertex_sets)
+    g.name('Turan Graph with n: {}, r: {}'.format(n, r))
+
+    return g
+
+
+def MuzychukS6Graph(n, d, Phi='fixed', Sigma='fixed', verbose=False):
+    r"""
+    Return a strongly regular graph of S6 type from [Muz2007]_ on
+    `n^d((n^d-1)/(n-1)+1)` vertices.
+
+    The construction depends upon a number of parameters, two of them, `n` and
+    `d`, mandatory, and `\Phi` and `\Sigma` mappings defined in [Muz2007]_.
+    These graphs have parameters `(mn^d, n^{d-1}(m-1) - 1,\mu - 2,\mu)`, where
+    `\mu=\frac{n^{d-1}-1}{n-1}n^{d-1}` and `m:=\frac{n^d-1}{n-1}+1`.
+
+    Some details on `\Phi` and `\Sigma` are as follows.  Let `L` be the
+    complete graph on `M:=\{0,..., m-1\}` with the matching
+    `\{(2i,2i+1) | i=0,...,m/2\}` removed.
+    Then one arbitrarily chooses injections `\Phi_i`
+    from the edges of `L` on `i \in M` into sets of parallel classes of affine
+    `d`-dimensional designs; our implementation uses the designs of hyperplanes
+    in `d`-dimensional affine geometries over `GF(n)`. Finally, for each edge
+    `ij` of `L` one arbitrarily chooses bijections `\Sigma_{ij}` between
+    `\Phi_i` and `\Phi_j`. More details, in particular how these choices lead
+    to non-isomorphic graphs, are in [Muz2007]_.
+
+    INPUT:
+
+    - ``n`` -- integer; a prime power
+
+    - ``d`` -- integer; must be odd if `n` is odd
+
+    - ``Phi`` is an optional parameter of the construction; it must be either
+
+      - ``'fixed'`` -- this will generate fixed default `\Phi_i`, for `i \in M`, or
+
+      - ``'random'`` -- `\Phi_i` are generated at random, or
+
+      - A dictionary describing the functions `\Phi_i`; for `i \in M`,
+        Phi[(i, T)] in `M`, for each edge T of `L` on `i`.
+        Also, each `\Phi_i` must be injective.
+
+    - ``Sigma`` is an optional parameter of the construction; it must be either
+
+      - ``'fixed'`` -- this will generate a fixed default `\Sigma`, or
+
+      - ``'random'`` -- `\Sigma` is generated at random
+
+    - ``verbose`` -- boolean (default: ``False``); if ``True``, print progress
+      information
+
+    .. SEEALSO::
+
+        - :func:`~sage.graphs.strongly_regular_db.is_muzychuk_S6`
+
+    .. TODO::
+
+        Implement the possibility to explicitly supply the parameter `\Sigma`
+        of the construction.
+
+    EXAMPLES::
+
+        sage: # needs sage.combinat sage.modules sage.rings.finite_rings
+        sage: graphs.MuzychukS6Graph(3, 3).is_strongly_regular(parameters=True)
+        (378, 116, 34, 36)
+        sage: phi = {(2,(0,2)):0, (1,(1,3)):1, (0,(0,3)):1, (2,(1,2)):1,
+        ....:        (1,(1,2)):0, (0,(0,2)):0, (3,(0,3)):0, (3,(1,3)):1}
+        sage: graphs.MuzychukS6Graph(2, 2, Phi=phi).is_strongly_regular(parameters=True)
+        (16, 5, 0, 2)
+
+    TESTS::
+
+        sage: # needs sage.modules
+        sage: graphs.MuzychukS6Graph(2,2,Phi='random',Sigma='random').is_strongly_regular(parameters=True)              # needs sage.rings.finite_rings
+        (16, 5, 0, 2)
+        sage: graphs.MuzychukS6Graph(3,3,Phi='random',Sigma='random').is_strongly_regular(parameters=True)              # needs sage.rings.finite_rings
+        (378, 116, 34, 36)
+        sage: graphs.MuzychukS6Graph(3,2)
+        Traceback (most recent call last):
+        ...
+        AssertionError: n must be even or d must be odd
+        sage: graphs.MuzychukS6Graph(6,2)
+        Traceback (most recent call last):
+        ...
+        AssertionError: n must be a prime power
+        sage: graphs.MuzychukS6Graph(3,1)
+        Traceback (most recent call last):
+        ...
+        AssertionError: d must be at least 2
+        sage: graphs.MuzychukS6Graph(3,3,Phi=42)                                        # needs sage.rings.finite_rings
+        Traceback (most recent call last):
+        ...
+        AssertionError: Phi must be a dictionary or 'random' or 'fixed'
+        sage: graphs.MuzychukS6Graph(3,3,Sigma=42)                                      # needs sage.rings.finite_rings
+        Traceback (most recent call last):
+        ...
+        ValueError: Sigma must be 'random' or 'fixed'
+    """
+    # TO DO: optimise
+    #        add option to return phi, sigma? generate phi, sigma from seed? (int say?)
+
+    from sage.combinat.designs.block_design import ProjectiveGeometryDesign
+    from sage.misc.prandom import randrange
+    from sage.misc.functional import is_even
+    from sage.arith.misc import is_prime_power
+    from sage.graphs.generators.basic import CompleteGraph
+    from sage.rings.finite_rings.finite_field_constructor import GF
+    from sage.matrix.special import ones_matrix
+    from sage.matrix.constructor import matrix
+    from sage.rings.rational_field import QQ
+    from sage.rings.integer_ring import ZZ
+    from time import time
+
+    assert d > 1, 'd must be at least 2'
+    assert is_even(n * (d-1)), 'n must be even or d must be odd'
+    assert is_prime_power(n), 'n must be a prime power'
+    t = time()
+
+    # build L, L_i and the design
+    m = int((n**d - 1)/(n - 1) + 1)  # from m = p + 1, p = (n^d-1) / (n-1)
+    L = CompleteGraph(m)
+    L.delete_edges([(2 * x, 2 * x + 1) for x in range(m // 2)])
+    L_i = [L.edges_incident(x, labels=False) for x in range(m)]
+    Design = ProjectiveGeometryDesign(d, d-1, GF(n, 'a'), point_coordinates=False)
+    projBlocks = Design.blocks()
+    atInf = projBlocks[-1]
+    Blocks = [[x for x in block if x not in atInf] for block in projBlocks[:-1]]
+    if verbose:
+        print('finished preamble at %f (+%f)' % (time() - t, time() - t))
+    t1 = time()
+
+    # sort the hyperplanes into parallel classes
+    ParClasses = [Blocks]
+    while ParClasses[0]:
+        nextHyp = ParClasses[0].pop()
+        for C in ParClasses[1:]:
+            listC = sum(C, [])
+            for x in nextHyp:
+                if x in listC:
+                    break
+            else:
+                C.append(nextHyp)
+                break
+        else:
+            ParClasses.append([nextHyp])
+    del ParClasses[0]
+    if verbose:
+        print('finished ParClasses at %f (+%f)' % (time() - t, time() - t1))
+    t1 = time()
+
+    # build E^C_j
+    E = {}
+    v = ZZ(n**d)
+    k = ZZ(n**(d-1))
+    ones = ones_matrix(v)
+    ones_v = ones/v
+    for C in ParClasses:
+        EC = matrix(QQ, v)
+        for line in C:
+            for i, j in combinations(line, 2):
+                EC[i, j] = EC[j, i] = 1/k
+        EC -= ones_v
+        E[tuple(C[0])] = EC
+    if verbose:
+        print('finished E at %f (+%f)' % (time() - t, time() - t1))
+    t1 = time()
+
+    # handle Phi
+    if Phi == 'random':
+        Phi = {}
+        for x in range(m):
+            temp = list(range(len(ParClasses)))
+            for line in L_i[x]:
+                rand = randrange(0, len(temp))
+                Phi[(x, line)] = temp.pop(rand)
+    elif Phi == 'fixed':
+        Phi = {(x, line): val for x in range(m) for val, line in enumerate(L_i[x])}
+    else:
+        assert isinstance(Phi, dict), \
+               "Phi must be a dictionary or 'random' or 'fixed'"
+        assert set(Phi.keys()) == set([(x, line) for x in range(m) for line in L_i[x]]), \
+               'each Phi_i must have domain L_i'
+        for x in range(m):
+            assert m - 2 == len(set([val for (key, val) in Phi.items() if key[0] == x])), \
+                   'each phi_i must be injective'
+        for val in Phi.values():
+            assert val in range(m - 1), \
+                   'codomain should be {0,..., (n^d - 1)/(n - 1) - 1}'
+    phi = {(x, line): ParClasses[Phi[(x, line)]] for x in range(m) for line in L_i[x]}
+    if verbose:
+        print('finished phi at %f (+%f)' % (time() - t, time() - t1))
+    t1 = time()
+
+    # handle sigma
+    sigma = {}
+    if Sigma == 'random':
+        for x in range(m):
+            for line in L_i[x]:
+                [i, j] = line
+                temp = phi[(j, line)][:]
+                for hyp in phi[(i, line)]:
+                    rand = randrange(0, len(temp))
+                    sigma[(i, j, tuple(hyp))] = temp[rand]
+                    sigma[(j, i, tuple(temp[rand]))] = hyp
+                    del temp[rand]
+    elif Sigma == 'fixed':
+        for x in range(m):
+            for line in L_i[x]:
+                [i, j] = line
+                temp = phi[(j, line)][:]
+                for hyp in phi[(i, line)]:
+                    val = temp.pop()
+                    sigma[(i, j, tuple(hyp))] = val
+                    sigma[(j, i, tuple(val))] = hyp
+    else:
+        raise ValueError("Sigma must be 'random' or 'fixed'")
+    if verbose:
+        print('finished sigma at %f (+%f)' % (time() - t, time() - t1))
+    t1 = time()
+
+    # build V
+    edges = []  # how many? *m^2*n^2
+    for (i, j) in L.edges(sort=True, labels=False):
+        for hyp in phi[(i, (i, j))]:
+            for x in hyp:
+                newEdges = [((i, x), (j, y))
+                            for y in sigma[(i, j, tuple(hyp))]]
+                edges.extend(newEdges)
+    if verbose:
+        print('finished edges at %f (+%f)' % (time() - t, time() - t1))
+    t1 = time()
+    V = Graph(edges)
+    if verbose:
+        print('finished V at %f (+%f)' % (time() - t, time() - t1))
+    t1 = time()
+
+    # build D_i, F_i and A_i
+    D_i = [0]*m
+    for x in range(m):
+        D_i[x] = sum([E[tuple(phi[x, line][0])] for line in L_i[x]])
+    F_i = [1 - D_i[x] - ones_v for x in range(m)]
+    # as the sum of (1/v)*J_\Omega_i, D_i, F_i is identity
+    A_i = [(v-k)*ones_v - k*F_i[x] for x in range(m)]
+    #   we know A_i = k''*(1/v)*J_\Omega_i + r''*D_i + s''*F_i,
+    #   and (k'', s'', r'') = (v - k, 0, -k)
+    if verbose:
+        print('finished D, F and A at %f (+%f)' % (time() - t, time() - t1))
+    t1 = time()
+
+    # add the edges of the graph of B to V
+    for i in range(m):
+        V.add_edges([((i, x), (i, y)) for x in range(v)
+                     for y in range(v) if not A_i[i][(x, y)]])
+
+    V.name('Muzychuk S6 graph with parameters ('+str(n)+','+str(d)+')')
+    if verbose:
+        print('finished at %f (+%f)' % ((time() - t), time() - t1))
+    return V
+
+
+def CubeConnectedCycle(d):
+    r"""
+    Return the cube-connected cycle of dimension `d`.
+
+    The cube-connected cycle of order `d` is the `d`-dimensional hypercube
+    with each of its vertices replaced by a cycle of length `d`. This graph has
+    order `d \times 2^d`.
+    The construction is as follows:
+    Construct vertex `(x,y)` for `0 \leq x < 2^d`, `0 \leq y < d`.
+    For each vertex, `(x,y)`, add an edge between it and `(x, (y-1) \mod d))`,
+    `(x,(y+1) \mod d)`, and `(x \oplus 2^y, y)`, where `\oplus` is the bitwise
+    xor operator.
+
+    For `d=1` and `2`, the cube-connected cycle graph contains self-loops or
+    multiple edges between a pair of vertices, but for all other `d`, it is
+    simple.
+
+    INPUT:
+
+    - ``d`` -- positive integer; the dimension of the desired hypercube as well
+      as the length of the cycle to be placed at each vertex of the
+      `d`-dimensional hypercube
+
+    EXAMPLES:
+
+    The order of the graph is `d \times 2^d` ::
+
+        sage: d = 3
+        sage: g = graphs.CubeConnectedCycle(d)
+        sage: len(g) == d*2**d
+        True
+
+    The diameter of cube-connected cycles for `d > 3` is
+    `2d + \lfloor \frac{d}{2} \rfloor - 2` ::
+
+        sage: d = 4
+        sage: g = graphs.CubeConnectedCycle(d)
+        sage: g.diameter() == 2*d+d//2-2
+        True
+
+    All vertices have degree `3` when `d > 1` ::
+
+        sage: g = graphs.CubeConnectedCycle(5)
+        sage: all(g.degree(v) == 3 for v in g)
+        True
+
+    TESTS::
+
+        sage: g = graphs.CubeConnectedCycle(0)
+        Traceback (most recent call last):
+        ...
+        ValueError: the dimension d must be greater than 0
+    """
+    if d < 1:
+        raise ValueError('the dimension d must be greater than 0')
+
+    G = Graph(name="Cube-Connected Cycle of dimension {}".format(d))
+
+    if d == 1:
+        G.allow_loops(True)
+        # only d = 1 requires loops
+        G.add_edges([((0, 0), (0, 1)), ((0, 0), (0, 0)), ((0, 1), (0, 1))])
+        return G
+
+    if d == 2:
+        # only d = 2 require multiple edges
+        G.allow_multiple_edges(True)
+        G.add_edges([((0, 0), (0, 1)), ((0, 0), (0, 1)), ((0, 0), (1, 0)),
+                     ((0, 1), (2, 1)), ((1, 0), (1, 1)), ((1, 0), (1, 1)),
+                     ((1, 1), (3, 1)), ((2, 0), (2, 1)), ((2, 0), (2, 1)),
+                     ((2, 0), (3, 0)), ((3, 0), (3, 1)), ((3, 0), (3, 1))])
+        return G
+
+    for x in range(1 << d):
+        G.add_cycle([(x, y) for y in range(d)])
+
+    for x, y in G:
+        G.add_edge((x, y), (x ^ (1 << y), y))
+
+    return G
+
+
+def StaircaseGraph(n):
+    r"""
+    Return a staircase graph with `2n` nodes
+
+    For `n \geq 3`, the staircase graph of order `2n` is the graph obtained
+    from the ladder graph of order `2n - 2`, i.e., ``graphs.LadderGraph(n - 1)``
+    by introducing two new nodes `2n - 2` and `2n - 1`, and then joining the
+    node `2n - 2` with `0` and `n - 1`, the node `2n - 1` with `n - 2` and
+    `2n - 3`, and the nodes `2n - 2` and `2n - 1` with each other.
+
+    Note that ``graphs.StaircaseGraph(4)`` is also known as the ``Bicorn
+    graph``. It is the only brick that has a unique `b`-invariant edge.
+
+    PLOTTING:
+
+    Upon construction, the position dictionary is filled to override
+    the spring-layout algorithm. By convention, each staircase graph will be
+    displayed horizontally, with the first `n - 1` nodes displayed from left to
+    right on the top horizontal line, the second `n - 1` nodes displayed from
+    left to right on the middle horizontal line, and the last two nodes
+    displayed at the bottom two corners.
+
+    INPUT:
+
+    - ``n`` -- an integer at least 3; number of nodes is `2n`
+
+    OUTPUT:
+
+    - ``G`` -- a staircase graph of order `2n`; note that a
+      :class:`ValueError` is returned if `n < 3`
+
+    EXAMPLES:
+
+    Construct and show a staircase graph with 10 nodes::
+
+        sage: g = graphs.StaircaseGraph(5)
+        sage: g.show()                          # long time                             # needs sage.plot
+
+    Construct and show the Bicorn graph. Note that the edge `(1, 4)` is the
+    unique `b`-invariant edge::
+
+        sage: bicornGraph = graphs.StaircaseGraph(4)
+        sage: bicornGraph.show()                # long time                             # needs sage.plot
+
+    Create several staircase graphs in a Sage graphics array::
+
+        sage: # needs sage.plots
+        sage: g = []
+        sage: j = []
+        sage: for i in range(9):
+        ....:    k = graphs.StaircaseGraph(i+3)
+        ....:    g.append(k)
+        sage: for i in range(3):
+        ....:    n = []
+        ....:    for m in range(3):
+        ....:        n.append(g[3*i + m].plot(vertex_size=50 - 4*(3*i+m), vertex_labels=False))
+        ....:    j.append(n)
+        sage: G = graphics_array(j)
+        sage: G.show()                          # long time
+
+    TESTS:
+
+    The input parameter must be an integer that is at least 3::
+
+        sage: G = graphs.StaircaseGraph(2)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameter n must be at least 3
+
+    REFERENCES:
+
+    - [LM2024]_
+
+    .. SEEALSO::
+
+        :meth:`~sage.graphs.graph_generators.GraphGenerators.LadderGraph`
+
+    AUTHORS:
+
+    - Janmenjaya Panda (2024-06-09)
+    """
+    if n < 3:
+        raise ValueError("parameter n must be at least 3")
+
+    pos_dict = {
+        0: (0, 1),
+        n - 2: (n, 1),
+        2*n - 2: (0, -1),
+        2*n - 1: (n, -1)
+    }
+
+    edges = [
+        (0, n - 1),
+        (0, 2*n - 2),
+        (n - 2, 2*n - 3),
+        (n - 2, 2*n - 1),
+        (n - 1, 2*n - 2),
+        (2*n - 3, 2*n - 1),
+        (2*n - 2, 2*n - 1)
+    ]
+
+    for v in range(1, n - 2):
+        pos_dict[v] = (v + 1, 1)
+        edges.append((v, v + n - 1))
+
+    for v in range(n - 1, 2*n - 2):
+        pos_dict[v] = (v - n + 2, 0)
+
+    G = Graph(2 * n, pos=pos_dict, name="Staircase graph")
+    G.add_edges(edges)
+    G.add_path(list(range(n - 1)))
+    G.add_path(list(range(n - 1, 2*n - 2)))
+    return G
+
+
+def BiwheelGraph(n):
+    r"""
+    Return a biwheel graph with `2n` nodes
+
+    For `n \geq 4`, the biwheel graph of order `2n` is the planar
+    bipartite graph obtained from the cycle graph of order `2n - 2`, i.e.,
+    ``graphs.CycleGraph(2*n - 2)`` (called the `rim` of the biwheel graph) by
+    introducing two new nodes `2n - 2` and `2n - 1` (called the *hubs* of the
+    biwheel graph), and then joining the node `2n - 2` with the odd indexed
+    nodes up to `2n - 3` and joining the node `2n - 1` with the even indexed
+    nodes up to `2n - 4`.
+
+    PLOTTING:
+
+    Upon construction, the position dictionary is filled to override
+    the spring-layout algorithm. By convention, each biwheel graph will be
+    displayed with the first (0) node at the right if `n` is even or
+    otherwise at an angle `\pi / (2n - 2)` with respect to the origin, with the
+    rest of the nodes up to `2n - 3` following in a counterclockwise manner.
+    Note that the last two nodes, i.e., the hubs `2n - 2` and `2n - 1` will
+    be displayed at the coordinates `(-1/3, 0)` and `(1/3, 0)` respectively.
+
+    INPUT:
+
+    - ``n`` -- an integer at least 4; number of nodes is `2n`
+
+    OUTPUT:
+
+    - ``G`` -- a biwheel graph of order `2n`; note that a
+      :class:`ValueError` is returned if `n < 4`
+
+    EXAMPLES:
+
+    Construct and show a biwheel graph with 10 nodes::
+
+        sage: g = graphs.BiwheelGraph(5)
+        sage: g.show()                          # long time                             # needs sage.plot
+        sage: g.is_planar()                                     # needs planarity
+        True
+        sage: g.is_bipartite()
+        True
+
+    Create several biwheel graphs in a Sage graphics array::
+
+        sage: # needs sage.plots
+        sage: g = []
+        sage: j = []
+        sage: for i in range(9):
+        ....:    k = graphs.BiwheelGraph(i+4)
+        ....:    g.append(k)
+        sage: for i in range(3):
+        ....:    n = []
+        ....:    for m in range(3):
+        ....:        n.append(g[3*i + m].plot(vertex_size=50 - 4*(3*i+m), vertex_labels=False))
+        ....:    j.append(n)
+        sage: G = graphics_array(j)
+        sage: G.show()                          # long time
+
+    TESTS:
+
+    The input parameter must be an integer that is at least 4::
+
+        sage: G = graphs.BiwheelGraph(3)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameter n must be at least 4
+
+    REFERENCES:
+
+    - [LM2024]_
+
+    .. SEEALSO::
+
+        :meth:`~sage.graphs.graph_generators.GraphGenerators.WheelGraph`,
+        :meth:`~sage.graphs.graph_generators.GraphGenerators.TruncatedBiwheelGraph`
+
+    AUTHORS:
+
+    - Janmenjaya Panda (2024-06-09)
+    """
+    if n < 4:
+        raise ValueError("parameter n must be at least 4")
+
+    angle_param = 0
+
+    if n % 2:
+        from math import pi
+        angle_param = pi / (2*n - 2)
+
+    G = Graph(2 * n, name="Biwheel graph")
+    pos_dict = G._circle_embedding(list(range(2*n - 2)), angle=angle_param, return_dict=True)
+    edges = []
+
+    from sage.rings.rational_field import QQ
+    pos_dict[2*n - 2] = (-QQ((1, 3)), 0)
+    pos_dict[2*n - 1] = (QQ((1, 3)), 0)
+
+    for i in range(2*n - 2):
+        if i % 2 == 0:
+            edges += [(i, 2*n - 1)]
+        else:
+            edges += [(i, 2*n - 2)]
+
+    G.set_pos(pos_dict)
+    G.add_cycle(list(range(2*n - 2)))
+    G.add_edges(edges)
+    return G
+
+
+def TruncatedBiwheelGraph(n):
+    r"""
+    Return a truncated biwheel graph with `2n` nodes
+
+    For `n \geq 3`, the truncated biwheel graph of order `2n` is the graph
+    obtained from the path graph of order `2n - 2`, i.e.,
+    ``graphs.PathGraph(2*n - 2)`` by introducing two new nodes `2n - 2` and
+    `2n - 1`, and then joining the node `2n - 2` with the odd indexed nodes
+    up to `2n - 3`, joining the node `2n - 1` with the even indexed nodes up to
+    `2n - 4` and adding the edges `(0, 2n - 2)` and `(2n - 3, 2n - 1)`.
+
+    PLOTTING:
+
+    Upon construction, the position dictionary is filled to override the
+    spring-layout algorithm. By convention, each truncated biwheel graph will
+    be displayed horizontally, with the first `2n - 2` nodes displayed from
+    left to right on the middle horizontal line and the nodes `2n - 2` and
+    `2n - 1` displayed at the top and the bottom central positions
+    respectively.
+
+    INPUT:
+
+    - ``n`` -- an integer at least 3; number of nodes is `2n`
+
+    OUTPUT:
+
+    - ``G`` -- a truncated biwheel graph of order `2n`; note that a
+      :class:`ValueError` is returned if `n < 3`
+
+    EXAMPLES:
+
+    Construct and show a truncated biwheel graph with 10 nodes::
+
+        sage: g = graphs.TruncatedBiwheelGraph(5)
+        sage: g.show()                          # long time                             # needs sage.plot
+
+    Create several truncated biwheel graphs in a Sage graphics array::
+
+        sage: # needs sage.plots
+        sage: g = []
+        sage: j = []
+        sage: for i in range(9):
+        ....:    k = graphs.TruncatedBiwheelGraph(i+3)
+        ....:    g.append(k)
+        sage: for i in range(3):
+        ....:    n = []
+        ....:    for m in range(3):
+        ....:        n.append(g[3*i + m].plot(vertex_size=50 - 4*(3*i+m), vertex_labels=False))
+        ....:    j.append(n)
+        sage: G = graphics_array(j)
+        sage: G.show()                          # long time
+
+    TESTS:
+
+    The input parameter must be an integer that is at least 3::
+
+        sage: G = graphs.TruncatedBiwheelGraph(2)
+        Traceback (most recent call last):
+        ...
+        ValueError: parameter n must be at least 3
+
+    REFERENCES:
+
+    - [LM2024]_
+
+    .. SEEALSO::
+
+        :meth:`~sage.graphs.graph_generators.GraphGenerators.WheelGraph`,
+        :meth:`~sage.graphs.graph_generators.GraphGenerators.BiwheelGraph`
+
+    AUTHORS:
+
+    - Janmenjaya Panda (2024-06-09)
+    """
+    if n < 3:
+        raise ValueError("parameter n must be at least 3")
+
+    pos_dict = {2*n - 2: (0, n), 2*n - 1: (0, -n)}
+    edges = [(0, 2*n - 2), (2*n - 3, 2*n - 1)]
+
+    for v in range(2*n - 2):
+        pos_dict[v] = (2*(v-n) + 3, 0)
+        if v % 2 == 0:
+            edges += [(v, 2*n - 1)]
+        else:
+            edges += [(v, 2*n - 2)]
+
+    G = Graph(2 * n, pos=pos_dict, name="Truncated biwheel graph")
+    G.add_path(list(range(2*n - 2)))
+    G.add_edges(edges)
+
+    return G