passagemath-graphs 10.5.43__cp39-cp39-musllinux_1_2_aarch64.whl

sage/topology/simplicial_complex_examples.py

@@ -0,0 +1,1692 @@
+# sage_setup: distribution = sagemath-graphs
+# sage.doctest: needs sage.graphs
+"""
+Examples of simplicial complexes
+
+There are two main types: manifolds and examples related to graph
+theory.
+
+For manifolds, there are functions defining the `n`-sphere for any
+`n`, the torus, `n`-dimensional real projective space for any `n`, the
+complex projective plane, surfaces of arbitrary genus, and some other
+manifolds, all as simplicial complexes.
+
+Aside from surfaces, this file also provides functions for
+constructing some other simplicial complexes: the simplicial complex
+of not-`i`-connected graphs on `n` vertices, the matching complex on n
+vertices, the chessboard complex for an `n` by `i` chessboard, and
+others.  These provide examples of large simplicial complexes; for
+example, ``simplicial_complexes.NotIConnectedGraphs(7, 2)`` has over a
+million simplices.
+
+All of these examples are accessible by typing
+``simplicial_complexes.NAME``, where ``NAME`` is the name of the example.
+
+- :func:`BarnetteSphere`
+- :func:`BrucknerGrunbaumSphere`
+- :func:`ChessboardComplex`
+- :func:`ComplexProjectivePlane`
+- :func:`DunceHat`
+- :func:`FareyMap`
+- :func:`GenusSix`
+- :func:`K3Surface`
+- :func:`KleinBottle`
+- :func:`MatchingComplex`
+- :func:`MooreSpace`
+- :func:`NotIConnectedGraphs`
+- :func:`PoincareHomologyThreeSphere`
+- :func:`QuaternionicProjectivePlane`
+- :func:`RandomComplex`
+- :func:`RandomTwoSphere`
+- :func:`RealProjectivePlane`
+- :func:`RealProjectiveSpace`
+- :func:`RudinBall`
+- :func:`ShiftedComplex`
+- :func:`Simplex`
+- :func:`Sphere`
+- :func:`SumComplex`
+- :func:`SurfaceOfGenus`
+- :func:`Torus`
+- :func:`ZieglerBall`
+
+You can also get a list by typing ``simplicial_complexes.`` and hitting the
+:kbd:`Tab` key.
+
+EXAMPLES::
+
+    sage: S = simplicial_complexes.Sphere(2) # the 2-sphere
+    sage: S.homology()                                                                  # needs sage.modules
+    {0: 0, 1: 0, 2: Z}
+    sage: simplicial_complexes.SurfaceOfGenus(3)
+    Triangulation of an orientable surface of genus 3
+    sage: M4 = simplicial_complexes.MooreSpace(4)
+    sage: M4.homology()                                                                 # needs sage.modules
+    {0: 0, 1: C4, 2: 0}
+    sage: simplicial_complexes.MatchingComplex(6).homology()                            # needs sage.modules
+    {0: 0, 1: Z^16, 2: 0}
+
+TESTS::
+
+    sage: from sage.topology.simplicial_complex_examples import PseudoQuaternionicProjectivePlane
+    sage: H = PseudoQuaternionicProjectivePlane()                                       # needs sage.groups
+    doctest:warning...:
+    DeprecationWarning: PseudoQuaternionicProjectivePlane is deprecated.
+    Please use sage.topology.simplicial_complex_examples.QuaternionicProjectivePlane instead.
+    See https://github.com/sagemath/sage/issues/34568 for details.
+"""
+
+from .simplicial_complex import SimplicialComplex
+from sage.structure.unique_representation import UniqueRepresentation
+# Below we define a function Simplex to construct a simplex as a
+# simplicial complex. We also need to use actual simplices as
+# simplices, hence:
+from .simplicial_complex import Simplex as TrueSimplex
+from sage.sets.set import Set
+from sage.misc.functional import is_even
+from sage.combinat.subset import Subsets
+import sage.misc.prandom as random
+from sage.misc.superseded import deprecated_function_alias
+
+# Miscellaneous utility functions.
+
+# The following two functions can be used to generate the facets for
+# the corresponding examples in sage.homology.examples. These take a
+# few seconds to run, so the actual examples have the facets
+# hard-coded. Thus the following functions are not currently used in
+# the Sage library.
+
+
+def facets_for_RP4():
+    """
+    Return the list of facets for a minimal triangulation of 4-dimensional
+    real projective space.
+
+    We use vertices numbered 1 through 16, define two facets, and define
+    a certain subgroup `G` of the symmetric group `S_{16}`. Then the set
+    of all facets is the `G`-orbit of the two given facets.
+
+    See the description in Example 3.12 in Datta [Dat2007]_.
+
+    EXAMPLES::
+
+        sage: from sage.topology.simplicial_complex_examples import facets_for_RP4
+        sage: A = facets_for_RP4()   # long time (1 or 2 seconds)
+        sage: SimplicialComplex(A) == simplicial_complexes.RealProjectiveSpace(4) # long time
+        True
+    """
+    # Define the group:
+    from sage.groups.perm_gps.permgroup import PermutationGroup
+    g1 = '(2, 7)(4, 10)(5, 6)(11, 12)'
+    g2 = '(1, 2, 3, 4, 5, 10)(6, 8, 9)(11, 12, 13, 14, 15, 16)'
+    G = PermutationGroup([g1, g2])
+    # Define the two simplices:
+    t1 = (1, 2, 4, 5, 11)
+    t2 = (1, 2, 4, 11, 13)
+    # Apply the group elements to the simplices:
+    facets = []
+    for g in G:
+        d = g.dict()
+        for t in [t1, t2]:
+            new = tuple([d[j] for j in t])
+            if new not in facets:
+                facets.append(new)
+    return facets
+
+
+def facets_for_K3():
+    """
+    Return the facets for a minimal triangulation of the K3 surface.
+
+    This is a pure simplicial complex of dimension 4 with 16
+    vertices and 288 facets. The facets are obtained by constructing a
+    few facets and a permutation group `G`, and then computing the
+    `G`-orbit of those facets.
+
+    See Casella and Kühnel in [CK2001]_ and Spreer and Kühnel [SK2011]_;
+    the construction here uses the labeling from Spreer and Kühnel.
+
+    EXAMPLES::
+
+        sage: from sage.topology.simplicial_complex_examples import facets_for_K3
+        sage: A = facets_for_K3()   # long time (a few seconds)
+        sage: SimplicialComplex(A) == simplicial_complexes.K3Surface()  # long time
+        True
+    """
+    from sage.groups.perm_gps.permgroup import PermutationGroup
+    G = PermutationGroup([[(1, 3, 8, 4, 9, 16, 15, 2, 14, 12, 6, 7, 13, 5, 10)],
+                         [(1, 11, 16), (2, 10, 14), (3, 12, 13), (4, 9, 15), (5, 7, 8)]])
+    return ([tuple([g(i) for i in (1, 2, 3, 8, 12)]) for g in G] +
+            [tuple([g(i) for i in (1, 2, 5, 8, 14)]) for g in G])
+
+
+def matching(A, B):
+    r"""
+    List of maximal matchings between the sets ``A`` and ``B``.
+
+    A matching is a set of pairs `(a, b) \in A \times B` where each `a` and
+    `b` appears in at most one pair.  A maximal matching is one which is
+    maximal with respect to inclusion of subsets of `A \times B`.
+
+    INPUT:
+
+    - ``A``, ``B`` -- list, tuple, or indeed anything which can be
+      converted to a set
+
+    EXAMPLES::
+
+        sage: from sage.topology.simplicial_complex_examples import matching
+        sage: matching([1, 2], [3, 4])
+        [{(1, 3), (2, 4)}, {(1, 4), (2, 3)}]
+        sage: matching([0, 2], [0])
+        [{(0, 0)}, {(2, 0)}]
+    """
+    answer = []
+    if len(A) == 0 or len(B) == 0:
+        return [set()]
+    for v in A:
+        for w in B:
+            for M in matching(set(A).difference([v]), set(B).difference([w])):
+                new = M.union([(v, w)])
+                if new not in answer:
+                    answer.append(new)
+    return answer
+
+
+class UniqueSimplicialComplex(SimplicialComplex, UniqueRepresentation):
+    """
+    This combines :class:`SimplicialComplex` and
+    :class:`UniqueRepresentation`. It is intended to be used to make
+    standard examples of simplicial complexes unique. See :issue:`13566`.
+
+    INPUT:
+
+    - the inputs are the same as for a :class:`SimplicialComplex`,
+      with one addition and two exceptions. The exceptions are that
+      ``is_mutable`` and ``is_immutable`` are ignored: all instances
+      of this class are immutable. The addition:
+
+    - ``name`` -- string (optional); the string representation for this complex
+
+    EXAMPLES::
+
+        sage: from sage.topology.simplicial_complex_examples import UniqueSimplicialComplex
+        sage: SimplicialComplex([[0, 1]]) is SimplicialComplex([[0, 1]])
+        False
+        sage: UniqueSimplicialComplex([[0, 1]]) is UniqueSimplicialComplex([[0, 1]])
+        True
+        sage: UniqueSimplicialComplex([[0, 1]])
+        Simplicial complex with vertex set (0, 1) and facets {(0, 1)}
+        sage: UniqueSimplicialComplex([[0, 1]], name='The 1-simplex')
+        The 1-simplex
+    """
+    @staticmethod
+    def __classcall__(self, maximal_faces=None, name=None, **kwds):
+        """
+        TESTS::
+
+            sage: from sage.topology.simplicial_complex_examples import UniqueSimplicialComplex
+            sage: UniqueSimplicialComplex([[1, 2, 3], [0, 1, 3]]) is UniqueSimplicialComplex([(1, 2, 3), (0, 1, 3)])
+            True
+            sage: X = UniqueSimplicialComplex([[1, 2, 3], [0, 1, 3]])
+            sage: X is UniqueSimplicialComplex(X)
+            True
+
+        Testing ``from_characteristic_function``::
+
+            sage: UniqueSimplicialComplex(from_characteristic_function=(lambda x: sum(x) <= 4, range(5)))
+            Simplicial complex with vertex set (0, 1, 2, 3, 4) and facets {(0, 4), (0, 1, 2), (0, 1, 3)}
+        """
+        char_fcn = kwds.get('from_characteristic_function', None)
+        if char_fcn:
+            kwds['from_characteristic_function'] = (char_fcn[0], tuple(char_fcn[1]))
+        if maximal_faces:
+            # Test to see if maximal_faces is a cell complex or another
+            # object which can be converted to a simplicial complex:
+            C = None
+            if isinstance(maximal_faces, SimplicialComplex):
+                C = maximal_faces
+            else:
+                try:
+                    C = maximal_faces._simplicial_()
+                except AttributeError:
+                    if not isinstance(maximal_faces, (list, tuple, Simplex)):
+                        # Convert it into a list (in case it is an iterable)
+                        maximal_faces = list(maximal_faces)
+            if C is not None:
+                maximal_faces = C.facets()
+            # Now convert maximal_faces to a tuple of tuples, so that it is hashable.
+            maximal_faces = tuple(tuple(mf) for mf in maximal_faces)
+        return super().__classcall__(self, maximal_faces, name=name, **kwds)
+
+    def __init__(self, maximal_faces=None, name=None, **kwds):
+        """
+        TESTS::
+
+            sage: from sage.topology.simplicial_complex_examples import UniqueSimplicialComplex
+            sage: UniqueSimplicialComplex([[1, 2, 3], [0, 1, 3]], is_mutable=True).is_mutable()
+            False
+        """
+        if 'is_mutable' in kwds:
+            del kwds['is_mutable']
+        if 'is_immutable' in kwds:
+            del kwds['is_immutable']
+        self._name = name
+        SimplicialComplex.__init__(self, maximal_faces=maximal_faces, is_mutable=False, **kwds)
+
+    def _repr_(self):
+        """
+        Print representation.
+
+        If the argument ``name`` was specified when defining the
+        complex, use that. Otherwise, use the print representation
+        from the class :class:`SimplicialComplex`.
+
+        TESTS::
+
+            sage: from sage.topology.simplicial_complex_examples import UniqueSimplicialComplex
+            sage: UniqueSimplicialComplex([[0, 1]])
+            Simplicial complex with vertex set (0, 1) and facets {(0, 1)}
+            sage: UniqueSimplicialComplex([[0, 1]], name='Joe')
+            Joe
+        """
+        if self._name:
+            return self._name
+        return SimplicialComplex._repr_(self)
+
+# Now the functions that produce the actual examples...
+
+
+def Sphere(n):
+    """
+    A minimal triangulation of the `n`-dimensional sphere.
+
+    INPUT:
+
+    - ``n`` -- positive integer
+
+    EXAMPLES::
+
+        sage: simplicial_complexes.Sphere(2)
+        Minimal triangulation of the 2-sphere
+        sage: simplicial_complexes.Sphere(5).homology()                                 # needs sage.modules
+        {0: 0, 1: 0, 2: 0, 3: 0, 4: 0, 5: Z}
+        sage: [simplicial_complexes.Sphere(n).euler_characteristic() for n in range(6)]
+        [2, 0, 2, 0, 2, 0]
+        sage: [simplicial_complexes.Sphere(n).f_vector() for n in range(6)]
+        [[1, 2],
+         [1, 3, 3],
+         [1, 4, 6, 4],
+         [1, 5, 10, 10, 5],
+         [1, 6, 15, 20, 15, 6],
+         [1, 7, 21, 35, 35, 21, 7]]
+    """
+    S = TrueSimplex(n+1)
+    facets = tuple(S.faces())
+    return UniqueSimplicialComplex(facets,
+                                   name='Minimal triangulation of the {}-sphere'.format(n))
+
+
+def Simplex(n):
+    """
+    An `n`-dimensional simplex, as a simplicial complex.
+
+    INPUT:
+
+    - ``n`` -- nonnegative integer
+
+    OUTPUT: the simplicial complex consisting of the `n`-simplex
+    on vertices `(0, 1, ..., n)` and all of its faces.
+
+    EXAMPLES::
+
+        sage: simplicial_complexes.Simplex(3)
+        The 3-simplex
+        sage: simplicial_complexes.Simplex(5).euler_characteristic()
+        1
+    """
+    return UniqueSimplicialComplex([TrueSimplex(n)],
+                                   name='The {}-simplex'.format(n))
+
+
+def Torus():
+    r"""
+    A minimal triangulation of the torus.
+
+    This is a simplicial complex with 7 vertices, 21 edges and 14
+    faces. It is the unique triangulation of the torus with 7
+    vertices, and has been found by Möbius in 1861.
+
+    This is also the combinatorial structure of the Császár
+    polyhedron (see :wikipedia:`Császár_polyhedron`).
+
+    EXAMPLES::
+
+        sage: T = simplicial_complexes.Torus()
+        sage: T.homology(1)                                                             # needs sage.modules
+        Z x Z
+        sage: T.f_vector()
+        [1, 7, 21, 14]
+
+    TESTS::
+
+        sage: T.flip_graph().is_isomorphic(graphs.HeawoodGraph())
+        True
+
+    REFERENCES:
+
+    - [Lut2002]_
+    """
+    return UniqueSimplicialComplex([[0, 1, 2], [1, 2, 4], [1, 3, 4], [1, 3, 6],
+                                    [0, 1, 5], [1, 5, 6], [2, 3, 5], [2, 4, 5],
+                                    [2, 3, 6], [0, 2, 6], [0, 3, 4], [0, 3, 5],
+                                    [4, 5, 6], [0, 4, 6]],
+                                   name='Minimal triangulation of the torus')
+
+
+def RealProjectivePlane():
+    """
+    A minimal triangulation of the real projective plane.
+
+    EXAMPLES::
+
+        sage: P = simplicial_complexes.RealProjectivePlane()
+        sage: Q = simplicial_complexes.ProjectivePlane()
+        sage: P == Q
+        True
+
+        sage: # needs sage.modules
+        sage: P.cohomology(1)
+        0
+        sage: P.cohomology(2)
+        C2
+        sage: P.cohomology(1, base_ring=GF(2))
+        Vector space of dimension 1 over Finite Field of size 2
+        sage: P.cohomology(2, base_ring=GF(2))
+        Vector space of dimension 1 over Finite Field of size 2
+    """
+    return UniqueSimplicialComplex([[0, 1, 2], [0, 2, 3], [0, 1, 5], [0, 4, 5],
+                                    [0, 3, 4], [1, 2, 4], [1, 3, 4], [1, 3, 5],
+                                    [2, 3, 5], [2, 4, 5]],
+                                   name='Minimal triangulation of the real projective plane')
+
+
+ProjectivePlane = RealProjectivePlane
+
+
+def KleinBottle():
+    """
+    A minimal triangulation of the Klein bottle, as presented for example
+    in Davide Cervone's thesis [Cer1994]_.
+
+    EXAMPLES::
+
+        sage: simplicial_complexes.KleinBottle()
+        Minimal triangulation of the Klein bottle
+    """
+    return UniqueSimplicialComplex([[2, 3, 7], [1, 2, 3], [1, 3, 5], [1, 5, 7],
+                                    [1, 4, 7], [2, 4, 6], [1, 2, 6], [1, 6, 0],
+                                    [1, 4, 0], [2, 4, 0], [3, 4, 7], [3, 4, 6],
+                                    [3, 5, 6], [5, 6, 0], [2, 5, 0], [2, 5, 7]],
+                                   name='Minimal triangulation of the Klein bottle')
+
+
+def SurfaceOfGenus(g, orientable=True):
+    """
+    A surface of genus `g`.
+
+    INPUT:
+
+    - ``g`` -- nonnegative integer; the desired genus
+
+    - ``orientable`` -- boolean (default: ``True``); if
+      ``True``, return an orientable surface, and if ``False``,
+      return a non-orientable surface.
+
+    In the orientable case, return a sphere if `g` is zero, and
+    otherwise return a `g`-fold connected sum of a torus with itself.
+
+    In the non-orientable case, raise an error if `g` is zero.  If
+    `g` is positive, return a `g`-fold connected sum of a
+    real projective plane with itself.
+
+    EXAMPLES::
+
+        sage: simplicial_complexes.SurfaceOfGenus(2)
+        Triangulation of an orientable surface of genus 2
+        sage: simplicial_complexes.SurfaceOfGenus(1, orientable=False)
+        Triangulation of a non-orientable surface of genus 1
+    """
+    if g == 0:
+        if not orientable:
+            raise ValueError("no non-orientable surface of genus zero")
+        else:
+            return Sphere(2)
+    if orientable:
+        T = Torus()
+    else:
+        T = RealProjectivePlane()
+    S = T
+    for i in range(g-1):
+        S = S.connected_sum(T)
+    if orientable:
+        name_str = 'Triangulation of an orientable surface of genus {}'
+    else:
+        name_str = 'Triangulation of a non-orientable surface of genus {}'
+
+    return UniqueSimplicialComplex(S, name=name_str.format(g))
+
+
+def MooreSpace(q):
+    r"""
+    Triangulation of the mod `q` Moore space.
+
+    INPUT:
+
+    - ``q`` -- integer; at least 2
+
+    This is a simplicial complex with simplices of dimension 0, 1,
+    and 2, such that its reduced homology is isomorphic to
+    `\\ZZ/q\\ZZ` in dimension 1, zero otherwise.
+
+    If `q=2`, this is the real projective plane.  If `q>2`, then
+    construct it as follows: start with a triangle with vertices
+    1, 2, 3.  We take a `3q`-gon forming a `q`-fold cover of the
+    triangle, and we form the resulting complex as an
+    identification space of the `3q`-gon.  To triangulate this
+    identification space, put `q` vertices `A_0`, ..., `A_{q-1}`,
+    in the interior, each of which is connected to 1, 2, 3 (two
+    facets each: `[1, 2, A_i]`, `[2, 3, A_i]`).  Put `q` more
+    vertices in the interior: `B_0`, ..., `B_{q-1}`, with facets
+    `[3, 1, B_i]`, `[3, B_i, A_i]`, `[1, B_i, A_{i+1}]`, `[B_i,
+    A_i, A_{i+1}]`.  Then triangulate the interior polygon with
+    vertices `A_0`, `A_1`, ..., `A_{q-1}`.
+
+    EXAMPLES::
+
+        sage: simplicial_complexes.MooreSpace(2)
+        Minimal triangulation of the real projective plane
+        sage: simplicial_complexes.MooreSpace(3).homology()[1]                          # needs sage.modules
+        C3
+        sage: simplicial_complexes.MooreSpace(4).suspension().homology()[2]             # needs sage.modules
+        C4
+        sage: simplicial_complexes.MooreSpace(8)
+        Triangulation of the mod 8 Moore space
+    """
+    if q <= 1:
+        raise ValueError("the mod q Moore space is only defined if q is at least 2")
+    if q == 2:
+        return RealProjectivePlane()
+    facets = []
+    for i in range(q):
+        Ai = "A" + str(i)
+        Aiplus = "A" + str((i+1) % q)
+        Bi = "B" + str(i)
+        facets.append([1, 2, Ai])
+        facets.append([2, 3, Ai])
+        facets.append([3, 1, Bi])
+        facets.append([3, Bi, Ai])
+        facets.append([1, Bi, Aiplus])
+        facets.append([Bi, Ai, Aiplus])
+    for i in range(1, q-1):
+        Ai = "A" + str(i)
+        Aiplus = "A" + str((i+1) % q)
+        facets.append(["A0", Ai, Aiplus])
+    return UniqueSimplicialComplex(facets,
+                                   name='Triangulation of the mod {} Moore space'.format(q))
+
+
+def ComplexProjectivePlane():
+    """
+    A minimal triangulation of the complex projective plane.
+
+    This was constructed by Kühnel and Banchoff [KB1983]_.
+
+    EXAMPLES::
+
+        sage: C = simplicial_complexes.ComplexProjectivePlane()
+        sage: C.f_vector()
+        [1, 9, 36, 84, 90, 36]
+        sage: C.homology(2)                                                             # needs sage.modules
+        Z
+        sage: C.homology(4)                                                             # needs sage.modules
+        Z
+    """
+    return UniqueSimplicialComplex(
+        [[1, 2, 4, 5, 6], [2, 3, 5, 6, 4], [3, 1, 6, 4, 5],
+         [1, 2, 4, 5, 9], [2, 3, 5, 6, 7], [3, 1, 6, 4, 8],
+         [2, 3, 6, 4, 9], [3, 1, 4, 5, 7], [1, 2, 5, 6, 8],
+         [3, 1, 5, 6, 9], [1, 2, 6, 4, 7], [2, 3, 4, 5, 8],
+         [4, 5, 7, 8, 9], [5, 6, 8, 9, 7], [6, 4, 9, 7, 8],
+         [4, 5, 7, 8, 3], [5, 6, 8, 9, 1], [6, 4, 9, 7, 2],
+         [5, 6, 9, 7, 3], [6, 4, 7, 8, 1], [4, 5, 8, 9, 2],
+         [6, 4, 8, 9, 3], [4, 5, 9, 7, 1], [5, 6, 7, 8, 2],
+         [7, 8, 1, 2, 3], [8, 9, 2, 3, 1], [9, 7, 3, 1, 2],
+         [7, 8, 1, 2, 6], [8, 9, 2, 3, 4], [9, 7, 3, 1, 5],
+         [8, 9, 3, 1, 6], [9, 7, 1, 2, 4], [7, 8, 2, 3, 5],
+         [9, 7, 2, 3, 6], [7, 8, 3, 1, 4], [8, 9, 1, 2, 5]],
+        name='Minimal triangulation of the complex projective plane')
+
+
+def QuaternionicProjectivePlane():
+    r"""
+    Return a pure simplicial complex of dimension 8 with 490 facets.
+
+    .. WARNING::
+
+        This was proven to be a triangulation of the projective plane
+        `HP^2` over the ring of quaternions by Gorodkov in 2016 [Gor2016]_.
+
+    This simplicial complex has the same homology as `HP^2`. Its
+    automorphism group is isomorphic to the alternating group `A_5`
+    and acts transitively on vertices.
+
+    This is defined here using the description in [BK1992]_. This
+    article deals with three different triangulations. This procedure
+    returns the only one which has a transitive group of automorphisms.
+
+    EXAMPLES::
+
+        sage: HP2 = simplicial_complexes.QuaternionicProjectivePlane(); HP2             # needs sage.groups
+        Simplicial complex with 15 vertices and 490 facets
+        sage: HP2.f_vector()                                                            # needs sage.groups
+        [1, 15, 105, 455, 1365, 3003, 4515, 4230, 2205, 490]
+
+    Checking its automorphism group::
+
+        sage: HP2.automorphism_group().is_isomorphic(AlternatingGroup(5))               # needs sage.groups
+        True
+    """
+    from sage.groups.perm_gps.permgroup import PermutationGroup
+    P = [(1, 2, 3, 4, 5), (6, 7, 8, 9, 10), (11, 12, 13, 14, 15)]
+    S = [(1, 6, 11), (2, 15, 14), (3, 13, 8), (4, 7, 5), (9, 12, 10)]
+    start_list = [
+        (1, 2, 3, 6, 8, 11, 13, 14, 15),    # A
+        (1, 3, 6, 8, 9, 10, 11, 12, 13),    # B
+        (1, 2, 6, 9, 10, 11, 12, 14, 15),   # C
+        (1, 2, 3, 4, 7, 9, 12, 14, 15),     # D
+        (1, 2, 4, 7, 9, 10, 12, 13, 14),    # E
+        (1, 2, 6, 8, 9, 10, 11, 14, 15),    # F
+        (1, 2, 3, 4, 5, 6, 9, 11, 13),      # G
+        (1, 3, 5, 6, 8, 9, 10, 11, 12),     # H
+        (1, 3, 5, 6, 7, 8, 9, 10, 11),      # I
+        (1, 2, 3, 4, 5, 7, 10, 12, 15),     # J
+        (1, 2, 3, 7, 8, 10, 12, 13, 14),    # K
+        (2, 5, 6, 7, 8, 9, 10, 13, 14),     # M
+
+        (3, 4, 6, 7, 11, 12, 13, 14, 15),   # L
+        (3, 4, 6, 7, 10, 12, 13, 14, 15)]   # N
+    return UniqueSimplicialComplex([[g(index) for index in tup]
+                                    for tup in start_list
+                                    for g in PermutationGroup([P, S])])
+
+
+PseudoQuaternionicProjectivePlane = deprecated_function_alias(34568, QuaternionicProjectivePlane)
+
+
+def PoincareHomologyThreeSphere():
+    """
+    A triangulation of the Poincaré homology 3-sphere.
+
+    This is a manifold whose integral homology is identical to the
+    ordinary 3-sphere, but it is not simply connected. In particular,
+    its fundamental group is the binary icosahedral group, which has
+    order 120. The triangulation given here has 16 vertices and is
+    due to Björner and Lutz [BL2000]_.
+
+    EXAMPLES::
+
+        sage: S3 = simplicial_complexes.Sphere(3)
+        sage: Sigma3 = simplicial_complexes.PoincareHomologyThreeSphere()
+        sage: S3.homology() == Sigma3.homology()                                        # needs sage.modules
+        True
+        sage: Sigma3.fundamental_group().cardinality()  # long time                     # needs sage.groups
+        120
+    """
+    return UniqueSimplicialComplex(
+        [[1, 2, 4, 9], [1, 2, 4, 15], [1, 2, 6, 14], [1, 2, 6, 15],
+         [1, 2, 9, 14], [1, 3, 4, 12], [1, 3, 4, 15], [1, 3, 7, 10],
+         [1, 3, 7, 12], [1, 3, 10, 15], [1, 4, 9, 12], [1, 5, 6, 13],
+         [1, 5, 6, 14], [1, 5, 8, 11], [1, 5, 8, 13], [1, 5, 11, 14],
+         [1, 6, 13, 15], [1, 7, 8, 10], [1, 7, 8, 11], [1, 7, 11, 12],
+         [1, 8, 10, 13], [1, 9, 11, 12], [1, 9, 11, 14], [1, 10, 13, 15],
+         [2, 3, 5, 10], [2, 3, 5, 11], [2, 3, 7, 10], [2, 3, 7, 13],
+         [2, 3, 11, 13], [2, 4, 9, 13], [2, 4, 11, 13], [2, 4, 11, 15],
+         [2, 5, 8, 11], [2, 5, 8, 12], [2, 5, 10, 12], [2, 6, 10, 12],
+         [2, 6, 10, 14], [2, 6, 12, 15], [2, 7, 9, 13], [2, 7, 9, 14],
+         [2, 7, 10, 14], [2, 8, 11, 15], [2, 8, 12, 15], [3, 4, 5, 14],
+         [3, 4, 5, 15], [3, 4, 12, 14], [3, 5, 10, 15], [3, 5, 11, 14],
+         [3, 7, 12, 13], [3, 11, 13, 14], [3, 12, 13, 14], [4, 5, 6, 7],
+         [4, 5, 6, 14], [4, 5, 7, 15], [4, 6, 7, 11], [4, 6, 10, 11],
+         [4, 6, 10, 14], [4, 7, 11, 15], [4, 8, 9, 12], [4, 8, 9, 13],
+         [4, 8, 10, 13], [4, 8, 10, 14], [4, 8, 12, 14], [4, 10, 11, 13],
+         [5, 6, 7, 13], [5, 7, 9, 13], [5, 7, 9, 15], [5, 8, 9, 12],
+         [5, 8, 9, 13], [5, 9, 10, 12], [5, 9, 10, 15], [6, 7, 11, 12],
+         [6, 7, 12, 13], [6, 10, 11, 12], [6, 12, 13, 15], [7, 8, 10, 14],
+         [7, 8, 11, 15], [7, 8, 14, 15], [7, 9, 14, 15], [8, 12, 14, 15],
+         [9, 10, 11, 12], [9, 10, 11, 16], [9, 10, 15, 16], [9, 11, 14, 16],
+         [9, 14, 15, 16], [10, 11, 13, 16], [10, 13, 15, 16],
+         [11, 13, 14, 16], [12, 13, 14, 15], [13, 14, 15, 16]],
+        name='Triangulation of the Poincare homology 3-sphere')
+
+
+def RealProjectiveSpace(n):
+    r"""
+    A triangulation of `\Bold{R}P^n` for any `n \geq 0`.
+
+    INPUT:
+
+    - ``n`` -- integer; the dimension of the real projective space
+      to construct
+
+    The first few cases are pretty trivial:
+
+    - `\Bold{R}P^0` is a point.
+
+    - `\Bold{R}P^1` is a circle, triangulated as the boundary of a
+      single 2-simplex.
+
+    - `\Bold{R}P^2` is the real projective plane, here given its
+      minimal triangulation with 6 vertices, 15 edges, and 10
+      triangles.
+
+    - `\Bold{R}P^3`: any triangulation has at least 11 vertices by
+      a result of Walkup [Wal1970]_; this function returns a
+      triangulation with 11 vertices, as given by Lutz [Lut2005]_.
+
+    - `\Bold{R}P^4`: any triangulation has at least 16 vertices by
+      a result of Walkup; this function returns a triangulation
+      with 16 vertices as given by Lutz; see also Datta [Dat2007]_,
+      Example 3.12.
+
+    - `\Bold{R}P^n`: Lutz has found a triangulation of
+      `\Bold{R}P^5` with 24 vertices, but it does not seem to have
+      been published.  Kühnel [Kuh1987]_ has described a triangulation of
+      `\Bold{R}P^n`, in general, with `2^{n+1}-1` vertices; see
+      also Datta, Example 3.21.  This triangulation is presumably
+      not minimal, but it seems to be the best in the published
+      literature as of this writing.  So this function returns it
+      when `n > 4`.
+
+    ALGORITHM: For `n < 4`, these are constructed explicitly by
+    listing the facets.  For `n = 4`, this is constructed by
+    specifying 16 vertices, two facets, and a certain subgroup `G`
+    of the symmetric group `S_{16}`.  Then the set of all facets
+    is the `G`-orbit of the two given facets.  This is implemented
+    here by explicitly listing all of the facets; the facets
+    can be computed by the function :func:`~sage.homology.simplicial_complex.facets_for_RP4`, but
+    running the function takes a few seconds.
+
+    For `n > 4`, the construction is as follows: let `S` denote
+    the simplicial complex structure on the `n`-sphere given by
+    the first barycentric subdivision of the boundary of an
+    `(n+1)`-simplex.  This has a simplicial antipodal action: if
+    `V` denotes the vertices in the boundary of the simplex, then
+    the vertices in its barycentric subdivision `S` correspond to
+    nonempty proper subsets `U` of `V`, and the antipodal action
+    sends any subset `U` to its complement.  One can show that
+    modding out by this action results in a triangulation for
+    `\Bold{R}P^n`.  To find the facets in this triangulation, find
+    the facets in `S`.  These are identified in pairs to form
+    `\Bold{R}P^n`, so choose a representative from each pair: for
+    each facet in `S`, replace any vertex in `S` containing 0 with
+    its complement.
+
+    Of course these complexes increase in size pretty quickly as
+    `n` increases.
+
+    EXAMPLES::
+
+        sage: P3 = simplicial_complexes.RealProjectiveSpace(3)
+        sage: P3.f_vector()
+        [1, 11, 51, 80, 40]
+        sage: P3.homology()                                                             # needs sage.modules
+        {0: 0, 1: C2, 2: 0, 3: Z}
+        sage: P4 = simplicial_complexes.RealProjectiveSpace(4)
+        sage: P4.f_vector()
+        [1, 16, 120, 330, 375, 150]
+        sage: P4.homology() # long time
+        {0: 0, 1: C2, 2: 0, 3: C2, 4: 0}
+        sage: P5 = simplicial_complexes.RealProjectiveSpace(5)  # long time (44s on sage.math, 2012)
+        sage: P5.f_vector()  # long time
+        [1, 63, 903, 4200, 8400, 7560, 2520]
+
+    The following computation can take a long time -- over half an
+    hour. ::
+
+        sage: P5.homology()  # not tested
+        {0: 0, 1: C2, 2: 0, 3: C2, 4: 0, 5: Z}
+        sage: simplicial_complexes.RealProjectiveSpace(2).dimension()
+        2
+        sage: P3.dimension()
+        3
+        sage: P4.dimension() # long time
+        4
+        sage: P5.dimension() # long time
+        5
+    """
+    if n == 0:
+        return Simplex(0)
+    if n == 1:
+        return Sphere(1)
+    if n == 2:
+        return RealProjectivePlane()
+    if n == 3:
+        # Minimal triangulation found by Walkup and given
+        # explicitly by Lutz
+        return UniqueSimplicialComplex(
+            [[1, 2, 3, 7], [1, 4, 7, 9], [2, 3, 4, 8], [2, 5, 8, 10],
+             [3, 6, 7, 10], [1, 2, 3, 11], [1, 4, 7, 10], [2, 3, 4, 11],
+             [2, 5, 9, 10], [3, 6, 8, 9], [1, 2, 6, 9], [1, 4, 8, 9],
+             [2, 3, 7, 8], [2, 6, 9, 10], [3, 6, 9, 10], [1, 2, 6, 11],
+             [1, 4, 8, 10], [2, 4, 6, 10], [3, 4, 5, 9], [4, 5, 6, 7],
+             [1, 2, 7, 9], [1, 5, 6, 8], [2, 4, 6, 11], [3, 4, 5, 11],
+             [4, 5, 6, 11], [1, 3, 5, 10], [1, 5, 6, 11], [2, 4, 8, 10],
+             [3, 4, 8, 9], [4, 5, 7, 9], [1, 3, 5, 11], [1, 5, 8, 10],
+             [2, 5, 7, 8], [3, 5, 9, 10], [4, 6, 7, 10], [1, 3, 7, 10],
+             [1, 6, 8, 9], [2, 5, 7, 9], [3, 6, 7, 8], [5, 6, 7, 8]],
+            name='Minimal triangulation of RP^3')
+    if n == 4:
+        return UniqueSimplicialComplex(
+            [(1, 3, 8, 12, 13), (2, 7, 8, 13, 16), (4, 8, 9, 12, 14),
+             (2, 6, 10, 12, 16), (5, 7, 9, 10, 13), (1, 2, 7, 8, 15),
+                (1, 3, 9, 11, 16), (5, 6, 8, 13, 16), (1, 3, 8, 11, 13),
+                (3, 4, 10, 13, 15), (4, 6, 9, 12, 15), (2, 4, 6, 11, 13),
+                (2, 3, 9, 12, 16), (1, 6, 9, 12, 15), (2, 5, 10, 11, 12),
+                (1, 7, 8, 12, 15), (2, 6, 9, 13, 16), (1, 5, 9, 11, 15),
+                (4, 9, 10, 13, 14), (2, 7, 8, 15, 16), (2, 3, 9, 12, 14),
+                (1, 6, 7, 10, 14), (2, 5, 10, 11, 15), (1, 2, 4, 13, 14),
+                (1, 6, 10, 14, 16), (2, 6, 9, 12, 16), (1, 3, 9, 12, 16),
+                (4, 5, 7, 11, 16), (5, 9, 10, 11, 15), (3, 5, 8, 12, 14),
+                (5, 6, 9, 13, 16), (5, 6, 9, 13, 15), (1, 3, 4, 10, 16),
+                (1, 6, 10, 12, 16), (2, 4, 6, 9, 13), (2, 4, 6, 9, 12),
+                (1, 2, 4, 11, 13), (7, 9, 10, 13, 14), (1, 7, 8, 12, 13),
+                (4, 6, 7, 11, 12), (3, 4, 6, 11, 13), (1, 5, 6, 9, 15),
+                (1, 6, 7, 14, 15), (2, 3, 7, 14, 15), (2, 6, 10, 11, 12),
+                (5, 7, 9, 10, 11), (1, 2, 4, 5, 14), (3, 5, 10, 13, 15),
+                (3, 8, 9, 12, 14), (5, 9, 10, 13, 15), (2, 6, 8, 13, 16),
+                (1, 2, 7, 13, 14), (1, 7, 10, 12, 13), (3, 4, 6, 13, 15),
+                (4, 9, 10, 13, 15), (2, 3, 10, 12, 16), (1, 2, 5, 14, 15),
+                (2, 6, 8, 10, 11), (1, 3, 10, 12, 13), (4, 8, 9, 12, 15),
+                (1, 3, 8, 9, 11), (4, 6, 7, 12, 15), (1, 8, 9, 11, 15),
+                (4, 5, 8, 14, 16), (1, 2, 8, 11, 13), (3, 6, 8, 11, 13),
+                (3, 6, 8, 11, 14), (3, 5, 8, 12, 13), (3, 7, 9, 11, 14),
+                (4, 6, 9, 13, 15), (2, 3, 5, 10, 12), (4, 7, 8, 15, 16),
+                (1, 2, 7, 14, 15), (3, 7, 9, 11, 16), (3, 6, 7, 14, 15),
+                (2, 6, 8, 11, 13), (4, 8, 9, 10, 14), (1, 4, 10, 13, 14),
+                (4, 8, 9, 10, 15), (2, 7, 9, 13, 16), (1, 6, 9, 12, 16),
+                (2, 3, 7, 9, 14), (4, 8, 10, 15, 16), (1, 5, 9, 11, 16),
+                (1, 5, 6, 14, 15), (5, 7, 9, 11, 16), (4, 5, 7, 11, 12),
+                (5, 7, 10, 11, 12), (2, 3, 10, 15, 16), (1, 2, 7, 8, 13),
+                (1, 6, 7, 10, 12), (1, 3, 10, 12, 16), (7, 9, 10, 11, 14),
+                (1, 7, 10, 13, 14), (1, 2, 4, 5, 11), (3, 4, 6, 7, 11),
+                (1, 6, 7, 12, 15), (1, 3, 4, 10, 13), (1, 4, 10, 14, 16),
+                (2, 4, 6, 11, 12), (5, 6, 8, 14, 16), (3, 5, 6, 8, 13),
+                (3, 5, 6, 8, 14), (1, 2, 8, 11, 15), (1, 4, 5, 14, 16),
+                (2, 3, 7, 15, 16), (8, 9, 10, 11, 14), (1, 3, 4, 11, 16),
+                (6, 8, 10, 14, 16), (8, 9, 10, 11, 15), (1, 3, 4, 11, 13),
+                (2, 4, 5, 12, 14), (2, 4, 9, 13, 14), (3, 4, 7, 11, 16),
+                (3, 6, 7, 11, 14), (3, 8, 9, 11, 14), (2, 8, 10, 11, 15),
+                (1, 3, 8, 9, 12), (4, 5, 7, 8, 16), (4, 5, 8, 12, 14),
+                (2, 4, 9, 12, 14), (6, 8, 10, 11, 14), (3, 5, 6, 13, 15),
+                (1, 4, 5, 11, 16), (3, 5, 6, 14, 15), (2, 4, 5, 11, 12),
+                (4, 5, 7, 8, 12), (1, 8, 9, 12, 15), (5, 7, 8, 13, 16),
+                (2, 3, 5, 12, 14), (3, 5, 10, 12, 13), (6, 7, 10, 11, 12),
+                (5, 7, 9, 13, 16), (6, 7, 10, 11, 14), (5, 7, 10, 12, 13),
+                (1, 2, 5, 11, 15), (1, 5, 6, 9, 16), (5, 7, 8, 12, 13),
+                (4, 7, 8, 12, 15), (2, 3, 5, 10, 15), (2, 6, 8, 10, 16),
+                (3, 4, 10, 15, 16), (1, 5, 6, 14, 16), (2, 3, 5, 14, 15),
+                (2, 3, 7, 9, 16), (2, 7, 9, 13, 14), (3, 4, 6, 7, 15),
+                (4, 8, 10, 14, 16), (3, 4, 7, 15, 16), (2, 8, 10, 15, 16)],
+            name='Minimal triangulation of RP^4')
+    if n >= 5:
+        # Use the construction given by Datta in Example 3.21.
+        V = set(range(0, n+2))
+        S = Sphere(n).barycentric_subdivision()
+        X = S.facets()
+        facets = set()
+        for f in X:
+            new = []
+            for v in f:
+                if 0 in v:
+                    new.append(tuple(V.difference(v)))
+                else:
+                    new.append(v)
+            facets.add(tuple(new))
+        return UniqueSimplicialComplex(list(facets),
+                                       name='Triangulation of RP^{}'.format(n))
+
+
+def K3Surface():
+    """
+    Return a minimal triangulation of the K3 surface.
+
+    This is a pure simplicial complex of dimension 4 with 16 vertices
+    and 288 facets. It was constructed by Casella and Kühnel
+    in [CK2001]_. The construction here uses the labeling from
+    Spreer and Kühnel [SK2011]_.
+
+    EXAMPLES::
+
+        sage: K3 = simplicial_complexes.K3Surface(); K3
+        Minimal triangulation of the K3 surface
+        sage: K3.f_vector()
+        [1, 16, 120, 560, 720, 288]
+
+    This simplicial complex is implemented just by listing all 288
+    facets. The list of facets can be computed by the function
+    :func:`~sage.homology.simplicial_complex.facets_for_K3`, but running the function takes a few
+    seconds.
+    """
+    return UniqueSimplicialComplex(
+        [(2, 10, 13, 15, 16), (2, 8, 11, 15, 16), (2, 5, 7, 8, 10),
+         (1, 9, 11, 13, 14), (1, 2, 8, 10, 12), (1, 3, 5, 6, 11),
+            (1, 5, 6, 9, 12), (1, 2, 6, 13, 16), (1, 4, 10, 13, 14),
+            (1, 9, 10, 14, 15), (2, 4, 7, 8, 12), (3, 4, 6, 10, 12),
+            (1, 6, 7, 8, 9), (3, 4, 5, 7, 15), (1, 7, 12, 15, 16),
+            (4, 5, 7, 13, 16), (5, 8, 11, 12, 15), (2, 4, 7, 12, 14),
+            (1, 4, 5, 14, 16), (2, 5, 6, 10, 11), (1, 6, 8, 12, 14),
+            (5, 8, 9, 14, 16), (5, 10, 11, 12, 13), (2, 4, 8, 9, 12),
+            (7, 9, 12, 15, 16), (1, 2, 6, 9, 15), (1, 5, 14, 15, 16),
+            (2, 3, 4, 5, 9), (6, 8, 10, 11, 15), (1, 5, 8, 10, 12),
+            (1, 3, 7, 9, 10), (6, 7, 8, 9, 13), (1, 2, 9, 11, 15),
+            (2, 8, 11, 14, 16), (2, 4, 5, 13, 16), (1, 4, 8, 13, 15),
+            (4, 7, 8, 10, 11), (2, 3, 9, 11, 14), (2, 3, 4, 9, 13),
+            (2, 8, 10, 12, 13), (1, 2, 4, 11, 15), (2, 3, 9, 11, 15),
+            (3, 5, 10, 13, 15), (3, 4, 5, 9, 11), (6, 10, 13, 15, 16),
+            (8, 10, 11, 15, 16), (6, 7, 11, 13, 15), (1, 5, 7, 15, 16),
+            (4, 5, 7, 9, 15), (3, 4, 6, 7, 16), (2, 3, 11, 14, 16),
+            (3, 4, 9, 11, 13), (1, 2, 5, 14, 15), (2, 3, 9, 13, 14),
+            (1, 2, 5, 13, 16), (2, 3, 7, 8, 12), (2, 9, 11, 12, 14),
+            (1, 9, 11, 15, 16), (4, 6, 9, 14, 16), (1, 4, 9, 13, 14),
+            (1, 2, 3, 12, 16), (8, 11, 12, 14, 15), (2, 4, 11, 12, 14),
+            (1, 4, 10, 12, 13), (1, 2, 6, 7, 13), (1, 3, 6, 10, 11),
+            (1, 6, 8, 9, 12), (1, 4, 5, 6, 14), (3, 9, 10, 12, 15),
+            (5, 8, 11, 12, 16), (5, 9, 10, 14, 15), (3, 9, 12, 15, 16),
+            (3, 6, 8, 14, 15), (2, 4, 9, 10, 16), (5, 8, 9, 13, 15),
+            (2, 3, 6, 9, 15), (6, 11, 12, 14, 16), (2, 3, 10, 13, 15),
+            (2, 8, 9, 10, 13), (3, 4, 8, 11, 13), (3, 4, 5, 7, 13),
+            (5, 7, 8, 10, 14), (4, 12, 13, 14, 15), (6, 7, 10, 14, 16),
+            (5, 10, 11, 13, 14), (3, 4, 7, 13, 16), (6, 8, 9, 12, 13),
+            (1, 3, 4, 10, 14), (2, 4, 6, 11, 12), (1, 7, 9, 10, 14),
+            (4, 6, 8, 13, 14), (4, 9, 10, 11, 16), (3, 7, 8, 10, 16),
+            (5, 7, 9, 15, 16), (1, 7, 9, 11, 14), (6, 8, 10, 15, 16),
+            (5, 8, 9, 10, 14), (7, 8, 10, 14, 16), (2, 6, 7, 9, 11),
+            (7, 9, 10, 13, 15), (3, 6, 7, 10, 12), (2, 4, 6, 10, 11),
+            (4, 5, 8, 9, 11), (1, 2, 3, 8, 16), (3, 7, 9, 10, 12),
+            (1, 2, 6, 8, 14), (3, 5, 6, 13, 15), (1, 5, 6, 12, 14),
+            (2, 5, 7, 14, 15), (1, 5, 10, 11, 12), (3, 7, 8, 10, 11),
+            (1, 2, 6, 14, 15), (1, 2, 6, 8, 16), (7, 9, 10, 12, 15),
+            (3, 4, 6, 8, 14), (3, 7, 13, 14, 16), (2, 5, 7, 8, 14),
+            (6, 7, 9, 10, 14), (2, 3, 7, 12, 14), (4, 10, 12, 13, 14),
+            (2, 5, 6, 11, 13), (4, 5, 6, 7, 16), (1, 3, 12, 13, 16),
+            (1, 4, 11, 15, 16), (1, 3, 4, 6, 10), (1, 10, 11, 12, 13),
+            (6, 9, 11, 12, 14), (1, 4, 7, 8, 15), (5, 8, 9, 10, 13),
+            (1, 2, 5, 7, 15), (1, 7, 12, 13, 16), (3, 11, 13, 14, 16),
+            (1, 2, 5, 7, 13), (4, 7, 8, 9, 15), (1, 5, 6, 10, 11),
+            (6, 7, 10, 13, 15), (3, 4, 7, 14, 15), (7, 11, 13, 14, 16),
+            (3, 4, 10, 12, 14), (3, 6, 8, 10, 16), (2, 7, 8, 14, 16),
+            (2, 3, 4, 5, 13), (5, 8, 12, 13, 15), (4, 6, 9, 13, 14),
+            (2, 4, 5, 6, 12), (1, 3, 7, 8, 9), (8, 11, 12, 14, 16),
+            (1, 7, 12, 13, 15), (8, 12, 13, 14, 15), (2, 8, 9, 12, 13),
+            (4, 6, 10, 12, 15), (2, 8, 11, 14, 15), (2, 6, 9, 11, 12),
+            (8, 9, 10, 11, 16), (2, 3, 6, 13, 15), (2, 3, 12, 15, 16),
+            (1, 3, 5, 9, 12), (2, 5, 6, 9, 12), (2, 10, 12, 13, 14),
+            (2, 6, 13, 15, 16), (2, 3, 11, 15, 16), (3, 5, 6, 8, 15),
+            (2, 4, 5, 9, 12), (5, 6, 8, 11, 15), (6, 8, 12, 13, 14),
+            (1, 2, 3, 8, 12), (1, 4, 7, 8, 11), (3, 5, 7, 14, 15),
+            (3, 5, 7, 13, 14), (1, 7, 10, 11, 14), (6, 7, 11, 12, 15),
+            (3, 4, 6, 7, 12), (1, 2, 4, 7, 11), (6, 9, 10, 14, 16),
+            (4, 10, 12, 15, 16), (5, 6, 7, 12, 16), (3, 9, 11, 13, 14),
+            (5, 9, 14, 15, 16), (4, 5, 6, 7, 12), (1, 3, 9, 10, 15),
+            (4, 7, 8, 9, 12), (5, 9, 10, 13, 15), (1, 3, 8, 13, 16),
+            (2, 9, 12, 13, 14), (6, 7, 10, 12, 15), (2, 6, 8, 14, 15),
+            (3, 5, 6, 8, 11), (3, 4, 7, 12, 14), (1, 3, 10, 14, 15),
+            (7, 11, 12, 13, 16), (3, 11, 12, 13, 16), (3, 4, 5, 8, 15),
+            (2, 4, 7, 8, 10), (2, 4, 7, 14, 15), (1, 2, 10, 12, 16),
+            (1, 6, 8, 13, 16), (1, 7, 8, 13, 15), (3, 9, 11, 15, 16),
+            (4, 6, 10, 11, 15), (2, 4, 11, 14, 15), (1, 3, 8, 9, 12),
+            (1, 3, 6, 14, 15), (2, 4, 5, 6, 10), (1, 4, 9, 14, 16),
+            (5, 7, 9, 12, 16), (1, 3, 7, 10, 11), (7, 8, 9, 13, 15),
+            (3, 5, 10, 14, 15), (1, 4, 10, 12, 16), (3, 4, 5, 8, 11),
+            (1, 2, 6, 7, 9), (1, 3, 11, 12, 13), (1, 5, 7, 13, 16),
+            (5, 7, 10, 11, 14), (2, 10, 12, 15, 16), (3, 6, 7, 10, 16),
+            (1, 2, 5, 8, 10), (4, 10, 11, 15, 16), (5, 8, 10, 12, 13),
+            (3, 6, 8, 10, 11), (4, 5, 7, 9, 12), (6, 7, 11, 12, 16),
+            (3, 5, 9, 11, 16), (8, 9, 10, 14, 16), (3, 4, 6, 8, 16),
+            (1, 10, 11, 13, 14), (2, 9, 10, 13, 16), (1, 2, 5, 8, 14),
+            (2, 4, 5, 10, 16), (1, 2, 7, 9, 11), (1, 3, 5, 6, 9),
+            (5, 7, 11, 13, 14), (3, 5, 10, 13, 14), (2, 4, 8, 9, 10),
+            (4, 11, 12, 14, 15), (2, 3, 7, 14, 16), (3, 4, 8, 13, 16),
+            (6, 7, 9, 11, 14), (5, 6, 11, 13, 15), (4, 5, 6, 14, 16),
+            (3, 4, 8, 14, 15), (4, 5, 8, 9, 15), (1, 4, 8, 11, 13),
+            (5, 6, 12, 14, 16), (2, 3, 10, 12, 14), (1, 2, 5, 10, 16),
+            (2, 5, 7, 10, 11), (2, 6, 7, 11, 13), (1, 4, 5, 10, 16),
+            (2, 6, 8, 15, 16), (2, 3, 10, 12, 15), (7, 11, 12, 13, 15),
+            (1, 3, 8, 11, 13), (4, 8, 9, 10, 11), (1, 9, 14, 15, 16),
+            (1, 3, 6, 9, 15), (6, 9, 12, 13, 14), (2, 3, 10, 13, 14),
+            (2, 5, 7, 11, 13), (2, 3, 5, 6, 13), (4, 6, 8, 13, 16),
+            (6, 7, 9, 10, 13), (5, 8, 12, 14, 16), (4, 6, 9, 13, 16),
+            (5, 8, 9, 11, 16), (2, 3, 5, 6, 9), (1, 3, 5, 11, 12),
+            (3, 7, 8, 9, 12), (4, 6, 11, 12, 15), (3, 5, 9, 12, 16),
+            (5, 11, 12, 13, 15), (1, 3, 4, 6, 14), (3, 5, 11, 12, 16),
+            (1, 5, 8, 12, 14), (4, 8, 13, 14, 15), (1, 3, 7, 8, 11),
+            (6, 9, 10, 13, 16), (2, 4, 9, 13, 16), (1, 6, 7, 8, 13),
+            (1, 4, 12, 13, 15), (2, 4, 7, 10, 11), (1, 4, 9, 11, 13),
+            (6, 7, 11, 14, 16), (1, 4, 9, 11, 16), (1, 4, 12, 15, 16),
+            (1, 2, 4, 7, 15), (2, 3, 7, 8, 16), (1, 4, 5, 6, 10)],
+        name='Minimal triangulation of the K3 surface')
+
+
+def BarnetteSphere():
+    r"""
+    Return Barnette's triangulation of the 3-sphere.
+
+    This is a pure simplicial complex of dimension 3 with 8
+    vertices and 19 facets, which is a non-polytopal triangulation
+    of the 3-sphere. It was constructed by Barnette in
+    [Bar1970]_. The construction here uses the labeling from De
+    Loera, Rambau and Santos [DLRS2010]_. Another reference is chapter
+    III.4 of Ewald [Ewa1996]_.
+
+    EXAMPLES::
+
+        sage: BS = simplicial_complexes.BarnetteSphere(); BS
+        Barnette's triangulation of the 3-sphere
+        sage: BS.f_vector()
+        [1, 8, 27, 38, 19]
+
+    TESTS:
+
+    Checks that this is indeed the same Barnette Sphere as the one
+    given on page 87 of [Ewa1996]_.::
+
+        sage: BS2 = SimplicialComplex([[1, 2, 3, 4], [3, 4, 5, 6], [1, 2, 5, 6],
+        ....:                          [1, 2, 4, 7], [1, 3, 4, 7], [3, 4, 6, 7],
+        ....:                          [3, 5, 6, 7], [1, 2, 5, 7], [2, 5, 6, 7],
+        ....:                          [2, 4, 6, 7], [1, 2, 3, 8], [2, 3, 4, 8],
+        ....:                          [3, 4, 5, 8], [4, 5, 6, 8], [1, 2, 6, 8],
+        ....:                          [1, 5, 6, 8], [1, 3, 5, 8], [2, 4, 6, 8],
+        ....:                          [1, 3, 5, 7]])
+        sage: BS.is_isomorphic(BS2)
+        True
+    """
+    return UniqueSimplicialComplex([(1, 2, 4, 5), (2, 3, 5, 6), (1, 3, 4, 6),
+                                    (1, 2, 3, 7), (4, 5, 6, 7), (1, 2, 4, 7),
+                                    (2, 4, 5, 7), (2, 3, 5, 7), (3, 5, 6, 7),
+                                    (3, 1, 6, 7), (1, 6, 4, 7), (1, 2, 3, 8),
+                                    (4, 5, 6, 8), (1, 2, 5, 8), (1, 4, 5, 8),
+                                    (2, 3, 6, 8), (2, 5, 6, 8), (3, 1, 4, 8),
+                                    (3, 6, 4, 8)],
+                                   name="Barnette's triangulation of the 3-sphere")
+
+
+def BrucknerGrunbaumSphere():
+    r"""
+    Return Bruckner and Grunbaum's triangulation of the 3-sphere.
+
+    This is a pure simplicial complex of dimension 3 with 8
+    vertices and 20 facets, which is a non-polytopal triangulation
+    of the 3-sphere. It appeared first in [Br1910]_ and was studied in
+    [GrS1967]_.
+
+    It is defined here as the link of any vertex in the unique minimal
+    triangulation of the complex projective plane, see chapter 4 of
+    [Kuh1995]_.
+
+    EXAMPLES::
+
+        sage: BGS = simplicial_complexes.BrucknerGrunbaumSphere(); BGS
+        Bruckner and Grunbaum's triangulation of the 3-sphere
+        sage: BGS.f_vector()
+        [1, 8, 28, 40, 20]
+    """
+    # X = ComplexProjectivePlane().link([9])
+    # return UniqueSimplicialComplex(X.facets(),
+    #                                name="Bruckner and Grunbaum's triangulation of the 3-sphere")
+    return UniqueSimplicialComplex(ComplexProjectivePlane().link([9]),
+                                   name="Bruckner and Grunbaum's triangulation of the 3-sphere")
+
+###############################################################
+# examples from graph theory:
+
+
+def NotIConnectedGraphs(n, i):
+    """
+    The simplicial complex of all graphs on `n` vertices which are
+    not `i`-connected.
+
+    Fix an integer `n>0` and consider the set of graphs on `n`
+    vertices.  View each graph as its set of edges, so it is a
+    subset of a set of size `n` choose 2.  A graph is
+    `i`-connected if, for any `j<i`, if any `j` vertices are
+    removed along with the edges emanating from them, then the
+    graph remains connected.  Now fix `i`: it is clear that if `G`
+    is not `i`-connected, then the same is true for any graph
+    obtained from `G` by deleting edges. Thus the set of all
+    graphs which are not `i`-connected, viewed as a set of subsets
+    of the `n` choose 2 possible edges, is closed under taking
+    subsets, and thus forms a simplicial complex.  This function
+    produces that simplicial complex.
+
+    INPUT:
+
+    - ``n``, ``i`` -- nonnegative integers with `i` at most `n`
+
+    See Dumas et al. [DHSW2003]_ for information on computing its homology
+    by computer, and see Babson et al. [BBLSW1999]_ for theory.  For
+    example, Babson et al. show that when `i=2`, the reduced homology of
+    this complex is nonzero only in dimension `2n-5`, where it is
+    free abelian of rank `(n-2)!`.
+
+    EXAMPLES::
+
+        sage: NICG52 = simplicial_complexes.NotIConnectedGraphs(5, 2)
+        sage: NICG52.f_vector()
+        [1, 10, 45, 120, 210, 240, 140, 20]
+        sage: NICG52.homology(5).ngens()                                                # needs sage.modules
+        6
+    """
+    G_list = range(1, n+1)
+    G_vertices = Set(G_list)
+    E_list = []
+    for w in G_list:
+        for v in range(1, w):
+            E_list.append((v, w))
+    E = Set(E_list)
+    facets = []
+    i_minus_one_sets = list(G_vertices.subsets(size=i-1))
+    for A in i_minus_one_sets:
+        G_minus_A = G_vertices.difference(A)
+        for B in G_minus_A.subsets():
+            if len(B) > 0 and len(B) < len(G_minus_A):
+                C = G_minus_A.difference(B)
+                facet = E
+                for v in B:
+                    for w in C:
+                        bad_edge = (min(v, w), max(v, w))
+                        facet = facet.difference(Set([bad_edge]))
+                facets.append(facet)
+    return UniqueSimplicialComplex(facets, name='Simplicial complex of not {}-connected graphs on {} vertices'.format(i, n))
+
+
+def MatchingComplex(n):
+    """
+    The matching complex of graphs on `n` vertices.
+
+    Fix an integer `n>0` and consider a set `V` of `n` vertices.
+    A 'partial matching' on `V` is a graph formed by edges so that
+    each vertex is in at most one edge.  If `G` is a partial
+    matching, then so is any graph obtained by deleting edges from
+    `G`.  Thus the set of all partial matchings on `n` vertices,
+    viewed as a set of subsets of the `n` choose 2 possible edges,
+    is closed under taking subsets, and thus forms a simplicial
+    complex called the 'matching complex'.  This function produces
+    that simplicial complex.
+
+    INPUT:
+
+    - ``n`` -- positive integer
+
+    See Dumas et al. [DHSW2003]_ for information on computing its homology
+    by computer, and see Wachs [Wac2003]_ for an expository article about
+    the theory.  For example, the homology of these complexes seems to
+    have only mod 3 torsion, and this has been proved for the
+    bottom non-vanishing homology group for the matching complex `M_n`.
+
+    EXAMPLES::
+
+        sage: M = simplicial_complexes.MatchingComplex(7)
+        sage: H = M.homology(); H                                                       # needs sage.modules
+        {0: 0, 1: C3, 2: Z^20}
+        sage: H[2].ngens()                                                              # needs sage.modules
+        20
+        sage: M8 = simplicial_complexes.MatchingComplex(8)
+        sage: M8.homology(2)                    # long time (6s on sage.math, 2012), needs sage.modules
+        Z^132
+    """
+    G_vertices = Set(range(1, n+1))
+    facets = []
+    if is_even(n):
+        half = int(n/2)
+        half_n_sets = list(G_vertices.subsets(size=half))
+    else:
+        half = int((n-1)/2)
+        half_n_sets = list(G_vertices.subsets(size=half))
+    for X in half_n_sets:
+        Xcomp = G_vertices.difference(X)
+        if is_even(n):
+            if 1 in X:
+                A = X
+                B = Xcomp
+            else:
+                A = Xcomp
+                B = X
+            for M in matching(A, B):
+                facet = []
+                for pair in M:
+                    facet.append(tuple(sorted(pair)))
+                    facets.append(facet)
+        else:
+            for w in Xcomp:
+                if 1 in X or (w == 1 and 2 in X):
+                    A = X
+                    B = Xcomp.difference([w])
+                else:
+                    B = X
+                    A = Xcomp.difference([w])
+                for M in matching(A, B):
+                    facet = []
+                    for pair in M:
+                        facet.append(tuple(sorted(pair)))
+                    facets.append(facet)
+    return UniqueSimplicialComplex(facets, name='Matching complex on {} vertices'.format(n))
+
+
+def ChessboardComplex(n, i):
+    r"""
+    The chessboard complex for an `n \times i` chessboard.
+
+    Fix integers `n, i > 0` and consider sets `V` of `n` vertices
+    and `W` of `i` vertices.  A 'partial matching' between `V` and
+    `W` is a graph formed by edges `(v, w)` with `v \in V` and `w
+    \in W` so that each vertex is in at most one edge.  If `G` is
+    a partial matching, then so is any graph obtained by deleting
+    edges from `G`.  Thus the set of all partial matchings on `V`
+    and `W`, viewed as a set of subsets of the `n+i` choose 2
+    possible edges, is closed under taking subsets, and thus forms
+    a simplicial complex called the 'chessboard complex'.  This
+    function produces that simplicial complex.  (It is called the
+    chessboard complex because such graphs also correspond to ways
+    of placing rooks on an `n` by `i` chessboard so that none of
+    them are attacking each other.)
+
+    INPUT:
+
+    - ``n``, ``i`` -- positive integers
+
+    See Dumas et al. [DHSW2003]_ for information on computing its homology
+    by computer, and see Wachs [Wac2003]_ for an expository article about
+    the theory.
+
+    EXAMPLES::
+
+        sage: C = simplicial_complexes.ChessboardComplex(5, 5)
+        sage: C.f_vector()
+        [1, 25, 200, 600, 600, 120]
+        sage: simplicial_complexes.ChessboardComplex(3, 3).homology()                   # needs sage.modules
+        {0: 0, 1: Z x Z x Z x Z, 2: 0}
+    """
+    A = range(n)
+    B = range(i)
+    E_dict = {}
+    index = 0
+    for v in A:
+        for w in B:
+            E_dict[(v, w)] = index
+            index += 1
+    facets = []
+    for M in matching(A, B):
+        facet = []
+        for pair in M:
+            facet.append(E_dict[pair])
+        facets.append(facet)
+    return UniqueSimplicialComplex(facets, name='Chessboard complex for an {}x{} chessboard'.format(n, i))
+
+
+def RandomComplex(n, d, p=0.5):
+    """
+    A random `d`-dimensional simplicial complex on `n` vertices.
+
+    INPUT:
+
+    - ``n`` -- number of vertices
+
+    - ``d`` -- dimension of the complex
+
+    - ``p`` -- floating point number between 0 and 1 (default: 0.5)
+
+    A random `d`-dimensional simplicial complex on `n` vertices,
+    as defined for example by Meshulam and Wallach [MW2009]_, is
+    constructed as follows: take `n` vertices and include all of
+    the simplices of dimension strictly less than `d`, and then for each
+    possible simplex of dimension `d`, include it with probability `p`.
+
+    EXAMPLES::
+
+        sage: X = simplicial_complexes.RandomComplex(6, 2); X
+        Random 2-dimensional simplicial complex on 6 vertices
+        sage: len(list(X.vertices()))
+        6
+
+    If `d` is too large (if `d+1 > n`, so that there are no
+    `d`-dimensional simplices), then return the simplicial complex
+    with a single `(n+1)`-dimensional simplex::
+
+        sage: simplicial_complexes.RandomComplex(6, 12)
+        The 5-simplex
+    """
+    if d+1 > n:
+        return Simplex(n-1)
+    else:
+        vertices = range(n)
+        facets = Subsets(vertices, d).list()
+        maybe = Subsets(vertices, d+1)
+        facets.extend([f for f in maybe if random.random() <= p])
+        return UniqueSimplicialComplex(facets,
+                                       name='Random {}-dimensional simplicial complex on {} vertices'.format(d, n))
+
+
+def SumComplex(n, A):
+    r"""
+    The sum complexes of Linial, Meshulam, and Rosenthal [LMR2010]_.
+
+    If `k+1` is the cardinality of `A`, then this returns a
+    `k`-dimensional simplicial complex `X_A` with vertices
+    `\ZZ/(n)`, and facets given by all `k+1`-tuples `(x_0, x_1,
+    ..., x_k)` such that the sum `\sum x_i` is in `A`. See the
+    paper by Linial, Meshulam, and Rosenthal [LMR2010]_, in which
+    they prove various results about these complexes; for example,
+    if `n` is prime, then `X_A` is rationally acyclic, and if in
+    addition `A` forms an arithmetic progression in `\ZZ/(n)`,
+    then `X_A` is `\ZZ`-acyclic. Throughout their paper, they
+    assume that `n` and `k` are relatively prime, but the
+    construction makes sense in general.
+
+    In addition to the results from the cited paper, these
+    complexes can have large torsion, given the number of
+    vertices; for example, if `n=10`, and `A=\{0, 1, 2, 3, 6\}`, then
+    `H_3(X_A)` is cyclic of order 2728, and there is a
+    4-dimensional complex on 13 vertices with `H_3` having a
+    cyclic summand of order
+
+    .. MATH::
+
+        706565607945 = 3 \cdot 5 \cdot 53 \cdot 79 \cdot 131
+        \cdot 157 \cdot 547.
+
+    See the examples.
+
+    INPUT:
+
+    - ``n`` -- positive integer
+
+    - ``A`` -- a subset of `\ZZ/(n)`
+
+    EXAMPLES::
+
+        sage: S = simplicial_complexes.SumComplex(10, [0, 1, 2, 3, 6]); S
+        Sum complex on vertices Z/10Z associated to {0, 1, 2, 3, 6}
+        sage: S.homology()                                                              # needs sage.modules
+        {0: 0, 1: 0, 2: 0, 3: C2728, 4: 0}
+        sage: factor(2728)
+        2^3 * 11 * 31
+
+        sage: S = simplicial_complexes.SumComplex(11, [0, 1, 3]); S
+        Sum complex on vertices Z/11Z associated to {0, 1, 3}
+        sage: S.homology(1)                                                             # needs sage.modules
+        C23
+        sage: S = simplicial_complexes.SumComplex(11, [0, 1, 2, 3, 4, 7]); S
+        Sum complex on vertices Z/11Z associated to {0, 1, 2, 3, 4, 7}
+        sage: S.homology()                      # long time                             # needs sage.modules
+        {0: 0, 1: 0, 2: 0, 3: 0, 4: C645679, 5: 0}
+        sage: factor(645679)
+        23 * 67 * 419
+
+        sage: S = simplicial_complexes.SumComplex(13, [0, 1, 3]); S
+        Sum complex on vertices Z/13Z associated to {0, 1, 3}
+        sage: S.homology(1)                                                             # needs sage.modules
+        C159
+        sage: factor(159)
+        3 * 53
+        sage: S = simplicial_complexes.SumComplex(13, [0, 1, 2, 5]); S
+        Sum complex on vertices Z/13Z associated to {0, 1, 2, 5}
+        sage: S.homology()                      # long time                             # needs sage.modules
+        {0: 0, 1: 0, 2: C146989209, 3: 0}
+        sage: factor(1648910295)
+        3^2 * 5 * 53 * 521 * 1327
+        sage: S = simplicial_complexes.SumComplex(13, [0, 1, 2, 3, 5]); S
+        Sum complex on vertices Z/13Z associated to {0, 1, 2, 3, 5}
+        sage: S.homology()                      # long time                             # needs sage.modules
+        {0: 0, 1: 0, 2: 0, 3: C3 x C237 x C706565607945, 4: 0}
+        sage: factor(706565607945)                                                      # needs sage.libs.pari
+        3 * 5 * 53 * 79 * 131 * 157 * 547
+
+        sage: S = simplicial_complexes.SumComplex(17, [0, 1, 4]); S
+        Sum complex on vertices Z/17Z associated to {0, 1, 4}
+        sage: S.homology(1)                                                             # needs sage.modules
+        C140183
+        sage: factor(140183)
+        103 * 1361
+        sage: S = simplicial_complexes.SumComplex(19, [0, 1, 4]); S
+        Sum complex on vertices Z/19Z associated to {0, 1, 4}
+        sage: S.homology(1)                                                             # needs sage.modules
+        C5670599
+        sage: factor(5670599)
+        11 * 191 * 2699
+        sage: S = simplicial_complexes.SumComplex(31, [0, 1, 4]); S
+        Sum complex on vertices Z/31Z associated to {0, 1, 4}
+        sage: S.homology(1)                     # long time                             # needs sage.modules
+        C5 x C5 x C5 x C5 x C26951480558170926865
+        sage: factor(26951480558170926865)                                              # needs sage.libs.pari
+        5 * 311 * 683 * 1117 * 11657 * 1948909
+    """
+    from sage.rings.finite_rings.integer_mod_ring import Integers
+    Zn = Integers(n)
+    A = frozenset([Zn(x) for x in A])
+    facets = []
+    for f in Set(Zn).subsets(len(A)):
+        if sum(f) in A:
+            facets.append(tuple(f))
+    return UniqueSimplicialComplex(facets, name='Sum complex on vertices Z/{}Z associated to {}'.format(n, Set(A)))
+
+
+def RandomTwoSphere(n):
+    r"""
+    Return a random triangulation of the 2-dimensional sphere with `n`
+    vertices.
+
+    INPUT:
+
+    - ``n`` -- integer
+
+    OUTPUT:
+
+    A random triangulation of the sphere chosen uniformly among
+    the *rooted* triangulations on `n` vertices. Because some
+    triangulations have nontrivial automorphism groups, this may
+    not be equal to the uniform distribution among unrooted
+    triangulations.
+
+    ALGORITHM:
+
+    The algorithm is taken from [PS2006]_, section 2.1.
+
+    Starting from a planar tree (represented by its contour as a
+    sequence of vertices), one first performs local closures, until no
+    one is possible. A local closure amounts to replace in the cyclic
+    contour word a sequence ``in1, in2, in3, lf, in3`` by
+    ``in1, in3``. After all local closures are done, one has reached
+    the partial closure, as in [PS2006]_, figure 5 (a).
+
+    Then one has to perform complete closure by adding two more
+    vertices, in order to reach the situation of [PS2006]_, figure 5
+    (b). For this, it is necessary to find inside the final contour
+    one of the two subsequences ``lf, in, lf``.
+
+    At every step of the algorithm, newly created triangles are added
+    in a simplicial complex.
+
+    This algorithm is implemented in
+    :meth:`~sage.graphs.generators.random.RandomTriangulation`, which
+    creates an embedded graph. The triangles of the simplicial
+    complex are recovered from this embedded graph.
+
+    EXAMPLES::
+
+        sage: G = simplicial_complexes.RandomTwoSphere(6); G
+        Simplicial complex with vertex set (0, 1, 2, 3, 4, 5) and 8 facets
+        sage: G.homology()                                                              # needs sage.modules
+        {0: 0, 1: 0, 2: Z}
+        sage: G.is_pure()
+        True
+        sage: fg = G.flip_graph(); fg
+        Graph on 8 vertices
+        sage: fg.is_planar() and fg.is_regular(3)               # needs planarity
+        True
+    """
+    from sage.graphs.generators.random import RandomTriangulation
+
+    graph = RandomTriangulation(n)
+
+    graph = graph.relabel(inplace=False)
+    triangles = [(u, v, w) for u, L in graph._embedding.items()
+                 for v, w in zip(L, L[1:] + [L[0]]) if u < v and u < w]
+
+    return SimplicialComplex(triangles, maximality_check=False)
+
+
+def ShiftedComplex(generators):
+    r"""
+    Return the smallest shifted simplicial complex containing ``generators``
+    as faces.
+
+    Let `V` be a set of vertices equipped with a total order.  The
+    'componentwise partial ordering' on k-subsets of `V` is defined as
+    follows: if `A = \{a_1 < \cdots < a_k\}` and `B = \{b_1 < \cdots < b_k\}`,
+    then `A \leq_C B` iff `a_i \leq b_i` for all `i`.  A simplicial complex
+    `X` on vertex set `[n]` is *shifted* if its faces form an order ideal
+    under the componentwise partial ordering, i.e., if `B \in X` and
+    `A \leq_C B` then `A \in X`.  Shifted complexes of dimension 1 are also
+    known as threshold graphs.
+
+    .. NOTE::
+
+        This method assumes that `V` consists of positive integers
+        with the natural ordering.
+
+    INPUT:
+
+    - ``generators`` -- list of generators of the order ideal, which may
+      be lists, tuples or simplices
+
+    EXAMPLES::
+
+        sage: # needs sage.combinat
+        sage: X = simplicial_complexes.ShiftedComplex([Simplex([1, 6]), (2, 4), [8]])
+        sage: sorted(X.facets())
+        [(1, 2), (1, 3), (1, 4), (1, 5), (1, 6), (2, 3), (2, 4), (7,), (8,)]
+        sage: X = simplicial_complexes.ShiftedComplex([[2, 3, 5]])
+        sage: sorted(X.facets())
+        [(1, 2, 3), (1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5), (2, 3, 4), (2, 3, 5)]
+        sage: X = simplicial_complexes.ShiftedComplex([[1, 3, 5], [2, 6]])
+        sage: sorted(X.facets())
+        [(1, 2, 3), (1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5), (1, 6), (2, 6)]
+    """
+    from sage.combinat.partition import Partitions
+    Facets = []
+    for G in generators:
+        G = sorted(G, reverse=True)
+        L = len(G)
+        for k in range(L * (L+1) // 2, sum(G) + 1):
+            for P in Partitions(k, length=L, max_slope=-1, outer=G):
+                Facets.append(list(reversed(P)))
+    return SimplicialComplex(Facets)
+
+
+def RudinBall():
+    r"""
+    Return the non-shellable ball constructed by Rudin.
+
+    This complex is a non-shellable triangulation of the 3-ball
+    with 14 vertices and 41 facets, constructed by Rudin in
+    [Rud1958]_.
+
+    EXAMPLES::
+
+        sage: R = simplicial_complexes.RudinBall(); R
+        Rudin ball
+        sage: R.f_vector()
+        [1, 14, 66, 94, 41]
+        sage: R.homology()                                                              # needs sage.modules
+        {0: 0, 1: 0, 2: 0, 3: 0}
+        sage: R.is_cohen_macaulay()                                                     # needs sage.modules
+        True
+    """
+    return UniqueSimplicialComplex(
+        [[1, 9, 2, 5], [1, 10, 2, 5], [1, 10, 5, 11], [1, 10, 7, 11], [1, 13, 5, 11],
+         [1, 13, 7, 11], [2, 10, 3, 6], [2, 11, 3, 6], [2, 11, 6, 12], [2, 11, 8, 12],
+         [2, 14, 6, 12], [2, 14, 8, 12], [3, 11, 4, 7], [3, 12, 4, 7], [3, 12, 5, 9],
+         [3, 12, 7, 9], [3, 13, 5, 9], [3, 13, 7, 9], [4, 9, 1, 8], [4, 9, 6, 10],
+         [4, 9, 8, 10], [4, 12, 1, 8], [4, 14, 6, 10], [4, 14, 8, 10], [9, 10, 2, 5],
+         [9, 10, 2, 6], [9, 10, 5, 11], [9, 10, 11, 12], [9, 13, 5, 11], [10, 11, 3, 6],
+         [10, 11, 3, 7], [10, 11, 6, 12], [10, 14, 6, 12], [11, 12, 4, 7], [11, 12, 4, 8],
+         [11, 12, 7, 9], [11, 13, 7, 9], [12, 9, 1, 5], [12, 9, 1, 8], [12, 9, 8, 10],
+         [12, 14, 8, 10]],
+        name="Rudin ball"
+    )
+
+
+def ZieglerBall():
+    r"""
+    Return the non-shellable ball constructed by Ziegler.
+
+    This complex is a non-shellable triangulation of the 3-ball
+    with 10 vertices and 21 facets, constructed by Ziegler in
+    [Zie1998]_ and the smallest such complex known.
+
+    EXAMPLES::
+
+        sage: Z = simplicial_complexes.ZieglerBall(); Z
+        Ziegler ball
+        sage: Z.f_vector()
+        [1, 10, 38, 50, 21]
+        sage: Z.homology()                                                              # needs sage.modules
+        {0: 0, 1: 0, 2: 0, 3: 0}
+        sage: Z.is_cohen_macaulay()                                                     # needs sage.modules
+        True
+    """
+
+    return UniqueSimplicialComplex(
+        [[1, 2, 3, 4], [1, 2, 5, 6], [1, 5, 6, 9], [2, 5, 6, 0], [3, 6, 7, 8], [4, 5, 7, 8],
+         [2, 3, 6, 7], [1, 6, 2, 9], [2, 6, 7, 0], [3, 2, 4, 8], [4, 1, 3, 7], [3, 4, 7, 8],
+         [1, 2, 4, 9], [2, 7, 3, 0], [3, 2, 6, 8], [4, 1, 5, 7], [4, 1, 8, 5], [1, 4, 8, 9],
+         [2, 3, 1, 0], [1, 8, 5, 9], [2, 1, 5, 0]],
+        name="Ziegler ball")
+
+
+def DunceHat():
+    r"""
+    Return the minimal triangulation of the dunce hat given by Hachimori
+    [Hac2016]_.
+
+    This is a standard example of a space that is contractible
+    but not collapsible.
+
+    EXAMPLES::
+
+        sage: D = simplicial_complexes.DunceHat(); D
+        Minimal triangulation of the dunce hat
+        sage: D.f_vector()
+        [1, 8, 24, 17]
+        sage: D.homology()                                                              # needs sage.modules
+        {0: 0, 1: 0, 2: 0}
+        sage: D.is_cohen_macaulay()                                                     # needs sage.modules
+        True
+    """
+    return UniqueSimplicialComplex(
+        [[1, 3, 5], [2, 3, 5], [2, 4, 5], [1, 2, 4], [1, 3, 4], [3, 4, 8],
+         [1, 2, 8], [1, 7, 8], [1, 2, 7], [2, 3, 7], [3, 6, 7], [1, 3, 6],
+         [1, 5, 6], [4, 5, 6], [4, 6, 8], [6, 7, 8], [2, 3, 8]],
+        name="Minimal triangulation of the dunce hat")
+
+
+def FareyMap(p):
+    r"""
+    Return a discrete surface associated with `PSL(2, \GF(p))`.
+
+    INPUT:
+
+    - ``p`` -- a prime number
+
+    The vertices are the nonzero pairs `(x,y)` in `\GF(p)^2` modulo
+    the identification of `(-x, -y)` with `(x,y)`.
+
+    The triangles are the images of the base triangle ((1,0),(0,1),(1,1))
+    under the action of `PSL(2, \GF(p))`.
+
+    For `p = 3`, the result is a tetrahedron, for `p = 5` an icosahedron,
+    and for `p = 7` a triangulation of the Klein quartic of genus `3`.
+
+    As a Riemann surface, this is the quotient of the upper half plane
+    by the principal congruence subgroup `\Gamma(p)`.
+
+    EXAMPLES::
+
+        sage: S5 = simplicial_complexes.FareyMap(5); S5                                 # needs sage.groups
+        Simplicial complex with 12 vertices and 20 facets
+        sage: S5.automorphism_group().cardinality()                                     # needs sage.groups
+        120
+
+        sage: S7 = simplicial_complexes.FareyMap(7); S7                                 # needs sage.groups
+        Simplicial complex with 24 vertices and 56 facets
+        sage: S7.f_vector()                                                             # needs sage.groups
+        [1, 24, 84, 56]
+
+    REFERENCES:
+
+    - [ISS2019] Ioannis Ivrissimtzis, David Singerman and James Strudwick,
+      *From Farey Fractions to the Klein Quartic and Beyond*.
+      :arxiv:`1909.08568`
+    """
+    from sage.combinat.permutation import Permutation
+    from sage.groups.perm_gps.permgroup import PermutationGroup
+    from sage.matrix.constructor import matrix
+    from sage.modules.free_module_element import vector
+    from sage.rings.finite_rings.finite_field_constructor import GF
+    from sage.libs.gap.libgap import libgap
+
+    def normalise(pair):
+        x, y = pair
+        if x != 0 and p - x < x:
+            return ((-x) % p, (-y) % p)
+        elif x == 0 and p - y < y:
+            return (0, (-y) % p)
+        return (x, y)
+
+    points = [(x, y) for x in range(p) for y in range(p)
+              if (x, y) != (0, 0) and
+              (x != 0 and p - x >= x or (x == 0 and p - y >= y))]
+    convert = {pt: i + 1 for i, pt in enumerate(points)}
+
+    F = GF(p)
+    S = matrix(F, 2, 2, [0, -1, 1, 0])
+    T = matrix(F, 2, 2, [1, 1, 0, 1])
+    perm_S = Permutation([convert[normalise(S * vector(pt))]
+                          for pt in points])
+    perm_T = Permutation([convert[normalise(T * vector(pt))]
+                          for pt in points])
+    group = PermutationGroup([perm_S, perm_T])
+    triangle = [convert[normalise(pt)] for pt in [(1, 0), (0, 1), (1, 1)]]
+    triangle = libgap.Set(triangle)
+    triangles = libgap.Orbit(group, triangle, libgap.OnSets).sage()
+    return SimplicialComplex(triangles)
+
+
+def GenusSix():
+    """
+    Return a triangulated surface of genus 6.
+
+    This is triangulated with 12 vertices, 66 edges and 44 faces. Each
+    vertex is neighbour to all other vertices.
+
+    It appears as number `58` in the classification of Altshuler,
+    Bokowski and Schuchert in [ABS96]_, where it is the unique surface
+    with the largest symmetry group, of order 12. This article refers
+    for this surface to Ringel.
+
+    EXAMPLES::
+
+        sage: S = simplicial_complexes.GenusSix()
+        sage: S.automorphism_group().cardinality()                                      # needs sage.groups
+        12
+        sage: S.betti()                                                                 # needs sage.modules
+        {0: 1, 1: 12, 2: 1}
+        sage: S.f_vector()
+        [1, 12, 66, 44]
+
+    REFERENCES:
+
+    .. [ABS96] Amos Altshule, Jürgen Bokowski and Peter Schuchert,
+               *Neighborly 2-Manifolds with 12 Vertices*,
+               Journal of Combinatorial Theory, Series A, 75, 148-162 (1996),
+               :doi:`10.1006/jcta.1996.0069`
+    """
+    L = ["014", "018", "023", "027", "036", "049",
+         "056", "05b", "07a", "08a", "09b",
+         "125", "126", "137", "139", "147", "15a",
+         "16b", "18b", "19a", "23b", "248",
+         "24a", "258", "269", "279", "2ab", "345",
+         "34b", "35a", "367", "389", "38a",
+         "459", "46a", "46b", "478", "568", "579",
+         "57b", "67a", "689", "78b", "9ab"]
+    return SimplicialComplex([list(w) for w in L])