passagemath-polyhedra 10.6.37__cp314-cp314-musllinux_1_2_x86_64.whl

sage/geometry/cone_catalog.py

@@ -0,0 +1,847 @@
+# sage_setup: distribution = sagemath-polyhedra
+r"""
+Catalog of common polyhedral convex cones
+
+This module provides shortcut functions, grouped under the
+globally-available ``cones`` prefix, to create some common cones:
+
+- The downward-monotone cone,
+- The nonnegative orthant,
+- The rearrangement cone of order ``p``,
+- The Schur cone,
+- The trivial cone.
+
+At the moment, only convex rational polyhedral cones are
+supported---specifically, those cones that can be built using the
+:func:`Cone` constructor. As a result, each shortcut method can be
+passed either an ambient dimension ``ambient_dim``, or a toric
+``lattice`` (from which the dimension can be inferred) to determine
+the ambient space.
+
+Here are some typical usage examples::
+
+    sage: cones.downward_monotone(3).rays()
+    N( 1,  0,  0),
+    N( 1,  1,  0),
+    N( 1,  1,  1),
+    N(-1, -1, -1)
+    in 3-d lattice N
+
+::
+
+    sage: cones.nonnegative_orthant(2).rays()
+    N(1, 0),
+    N(0, 1)
+    in 2-d lattice N
+
+::
+
+    sage: cones.rearrangement(2,2).rays()
+    N( 1,  0),
+    N( 1, -1),
+    N(-1,  1)
+    in 2-d lattice N
+
+::
+
+    sage: cones.schur(3).rays()
+    N(1, -1,  0),
+    N(0,  1, -1)
+    in 3-d lattice N
+
+::
+
+    sage: cones.trivial(3).rays()
+    Empty collection
+    in 3-d lattice N
+
+To specify some other lattice, pass it as an argument to the function::
+
+    sage: K = cones.nonnegative_orthant(3)
+    sage: cones.schur(lattice=K.dual().lattice())
+    2-d cone in 3-d lattice M
+
+For more information about these cones, see the documentation for the
+individual functions and the references therein.
+"""
+
+#
+# WARNING:
+#
+# Don't import anything into global scope here. If you do, it will
+# show up in the cones.<tab> list, and that list should contain only
+# the top-level non-underscore functions defined in this module.
+#
+
+
+def _preprocess_args(ambient_dim, lattice):
+    r"""
+    Preprocess arguments for cone-constructing functions.
+
+    Each cone-constructing function in this module performs some
+    preprocessing on its ``ambient_dim`` and ``lattice`` arguments to
+    ensure that they both wind up defined and compatible with one
+    another. In particular, the ``ambient_dim`` can be inferred from
+    a ``lattice`` and a default lattice can be chosen based on an
+    ``ambient_dim``. Both can be specified so long as the rank of
+    the ``lattice`` matches the ``ambient_dim``; it is an error
+    if the two numbers are different.
+
+    Since each function performs exactly the same steps,
+
+    - Check that either ``ambient_dim`` or ``lattice`` was given,
+    - Infer the ``ambient_dim`` from the ``lattice`` if ``lattice``
+      was given and ``ambient_dim`` was not,
+    - Use the default ``lattice`` if ``ambient_dim`` was given and
+      ``lattice`` was not,
+    - Ensure that the rank of the ``lattice`` equals ``ambient_dim``,
+
+    we collect them here.
+
+    INPUT:
+
+    - ``ambient_dim`` -- nonnegative integer; the dimension of the
+      ambient space in which the cone will live
+
+    - ``lattice`` -- a toric lattice; the lattice in which the cone
+      will live
+
+    OUTPUT:
+
+    A pair ``(ambient_dim, lattice)`` containing the processed
+    arguments. Both are guaranteed to be defined (that is, not
+    ``None``) and the rank of the ``lattice`` will equal
+    ``ambient_dim``.
+
+    EXAMPLES:
+
+    If the ``lattice`` argument is ``None``, then the default lattice
+    with rank equal to ``ambient_dim`` will be used::
+
+        sage: from sage.geometry.cone_catalog import _preprocess_args
+        sage: _preprocess_args(3, None)
+        (3, 3-d lattice N)
+
+    If the ``ambient_dim`` argument is ``None``, then the rank of the
+    ``lattice`` will be used as the ambient dimension::
+
+        sage: from sage.geometry.cone_catalog import _preprocess_args
+        sage: _preprocess_args(None, ToricLattice(3))
+        (3, 3-d lattice N)
+
+    So long as the rank of ``lattice`` equals ``ambient_dim``, it is
+    not an error for both to be defined::
+
+        sage: from sage.geometry.cone_catalog import _preprocess_args
+        sage: _preprocess_args(3, ToricLattice(3))
+        (3, 3-d lattice N)
+
+    .. NOTE::
+
+        The two error conditions are tested in the cone-constructing
+        functions themselves, which introduces some duplication but
+        serves to ensure that ``_preprocess_args()`` is actually called
+        in each such function.
+    """
+    from sage.geometry.toric_lattice import ToricLattice
+
+    if ambient_dim is None and lattice is None:
+        raise ValueError("either the ambient dimension or the lattice "
+                         "must be specified")
+
+    if ambient_dim is None:
+        ambient_dim = lattice.rank()
+
+    if lattice is None:
+        lattice = ToricLattice(ambient_dim)
+
+    if lattice.rank() != ambient_dim:
+        raise ValueError("lattice rank=%d and ambient_dim=%d "
+                         "are incompatible" % (lattice.rank(), ambient_dim))
+
+    return (ambient_dim, lattice)
+
+
+def downward_monotone(ambient_dim=None, lattice=None):
+    r"""
+    The downward-monotone cone in ``ambient_dim`` dimensions, or
+    living in ``lattice``.
+
+    The elements of the downward-monotone cone are vectors whose
+    components are arranged in non-increasing order. Vectors whose
+    entries are arranged in the reverse (non-decreasing) order are
+    sometimes called isotone vectors, and are used in statistics
+    for isotonic regression.
+
+    The downward-monotone cone is the dual of the Schur cone. It
+    is also often referred to as the downward-monotone cone.
+
+    INPUT:
+
+    - ``ambient_dim`` -- nonnegative integer (default: ``None``); the
+      dimension of the ambient space
+
+    - ``lattice`` -- a toric lattice (default: ``None``); the lattice in
+      which the cone will live
+
+    If ``ambient_dim`` is omitted, then it will be inferred from the
+    rank of ``lattice``. If the ``lattice`` is omitted, then the
+    default lattice of rank ``ambient_dim`` will be used.
+
+    A :exc:`ValueError` is raised if neither ``ambient_dim`` nor
+    ``lattice`` are specified. It is also a :exc:`ValueError` to
+    specify both ``ambient_dim`` and ``lattice`` unless the rank of
+    ``lattice`` is equal to ``ambient_dim``.
+
+    OUTPUT:
+
+    A :class:`~sage.geometry.cone.ConvexRationalPolyhedralCone` living
+    in ``lattice`` whose elements' entries are arranged in
+    nonincreasing order. Each generating ray has the integer ring as
+    its base ring.
+
+    A :exc:`ValueError` can be raised if the inputs are incompatible
+    or insufficient. See the INPUT documentation for details.
+
+    .. SEEALSO::
+
+        :func:`schur`
+
+    REFERENCES:
+
+    - [GS2010]_, Section 3.1
+
+    - [Niez1998]_, Example 2.2
+
+    EXAMPLES:
+
+    The entries of the elements of the downward-monotone cone are in
+    non-increasing order::
+
+        sage: ambient_dim = ZZ.random_element(10)
+        sage: K = cones.downward_monotone(ambient_dim)
+        sage: all( x[i] >= x[i + 1]
+        ....:      for i in range(ambient_dim - 1)
+        ....:      for x in K.rays() )
+        True
+        sage: x = K.random_element()
+        sage: all( x[i] >= x[i + 1] for i in range(ambient_dim - 1) )
+        True
+
+    A nontrivial downward-monotone cone is solid but not proper,
+    since it contains both the vector of all ones and its negation;
+    that, however, is the only subspace it contains::
+
+        sage: ambient_dim = ZZ.random_element(1,10)
+        sage: K = cones.downward_monotone(ambient_dim)
+        sage: K.is_solid()
+        True
+        sage: K.is_proper()
+        False
+        sage: K.lineality()
+        1
+
+    The dual of the downward-monotone cone is the Schur cone
+    [GS2010]_ that induces the majorization preordering::
+
+        sage: ambient_dim = ZZ.random_element(10)
+        sage: K = cones.downward_monotone(ambient_dim).dual()
+        sage: J = cones.schur(ambient_dim, K.lattice())
+        sage: K.is_equivalent(J)
+        True
+
+    TESTS:
+
+    We can construct the trivial cone as the downward-monotone cone
+    in a trivial vector space::
+
+        sage: cones.downward_monotone(0)
+        0-d cone in 0-d lattice N
+
+    If a ``lattice`` was given, it is actually used::
+
+        sage: L = ToricLattice(3, 'M')
+        sage: cones.downward_monotone(lattice=L)
+        3-d cone in 3-d lattice M
+
+    Unless the rank of the lattice disagrees with ``ambient_dim``::
+
+        sage: L = ToricLattice(1, 'M')
+        sage: cones.downward_monotone(3, lattice=L)
+        Traceback (most recent call last):
+        ...
+        ValueError: lattice rank=1 and ambient_dim=3 are incompatible
+
+    We also get an error if no arguments are given::
+
+        sage: cones.downward_monotone()
+        Traceback (most recent call last):
+        ...
+        ValueError: either the ambient dimension or the lattice must
+        be specified
+    """
+    from sage.geometry.cone import Cone
+    from sage.matrix.constructor import matrix
+    from sage.rings.integer_ring import ZZ
+
+    ambient_dim, lattice = _preprocess_args(ambient_dim, lattice)
+
+    # The generators for this cone are mentioned in Niezgoda's
+    # Example 2.2 if you don't want to compute them yourself.
+    G = matrix.identity(ZZ, ambient_dim)
+    for i in range(1, ambient_dim):
+        G.add_multiple_of_row(i, i - 1, 1)
+
+    if G.nrows() > 0:
+        # Special case for when the ambient space is trivial.
+        G = G.insert_row(ambient_dim, -1*G.row(-1))
+
+    return Cone(G.rows(), lattice)
+
+
+def nonnegative_orthant(ambient_dim=None, lattice=None):
+    r"""
+    The nonnegative orthant in ``ambient_dim`` dimensions, or living
+    in ``lattice``.
+
+    The nonnegative orthant consists of all componentwise-nonnegative
+    vectors. It is the convex-conic hull of the standard basis.
+
+    INPUT:
+
+    - ``ambient_dim`` -- nonnegative integer (default: ``None``); the
+      dimension of the ambient space
+
+    - ``lattice`` -- a toric lattice (default: ``None``); the lattice in
+      which the cone will live
+
+    If ``ambient_dim`` is omitted, then it will be inferred from the
+    rank of ``lattice``. If the ``lattice`` is omitted, then the
+    default lattice of rank ``ambient_dim`` will be used.
+
+    A :exc:`ValueError` is raised if neither ``ambient_dim`` nor
+    ``lattice`` are specified. It is also a :exc:`ValueError` to
+    specify both ``ambient_dim`` and ``lattice`` unless the rank of
+    ``lattice`` is equal to ``ambient_dim``.
+
+    OUTPUT:
+
+    A :class:`~sage.geometry.cone.ConvexRationalPolyhedralCone` living
+    in ``lattice`` and having ``ambient_dim`` standard basis vectors
+    as its generators. Each generating ray has the integer ring as its
+    base ring.
+
+    A :exc:`ValueError` can be raised if the inputs are incompatible
+    or insufficient. See the INPUT documentation for details.
+
+    REFERENCES:
+
+    - Chapter 2 in [BV2009]_ (Examples 2.4, 2.14, and 2.23 in particular)
+
+    EXAMPLES::
+
+        sage: cones.nonnegative_orthant(3).rays()
+        N(1, 0, 0),
+        N(0, 1, 0),
+        N(0, 0, 1)
+        in 3-d lattice N
+
+    TESTS:
+
+    We can construct the trivial cone as the nonnegative orthant in a
+    trivial vector space::
+
+        sage: cones.nonnegative_orthant(0)
+        0-d cone in 0-d lattice N
+
+    The nonnegative orthant is a proper cone::
+
+        sage: ambient_dim = ZZ.random_element(10)
+        sage: K = cones.nonnegative_orthant(ambient_dim)
+        sage: K.is_proper()
+        True
+
+    If a ``lattice`` was given, it is actually used::
+
+        sage: L = ToricLattice(3, 'M')
+        sage: cones.nonnegative_orthant(lattice=L)
+        3-d cone in 3-d lattice M
+
+    Unless the rank of the lattice disagrees with ``ambient_dim``::
+
+        sage: L = ToricLattice(1, 'M')
+        sage: cones.nonnegative_orthant(3, lattice=L)
+        Traceback (most recent call last):
+        ...
+        ValueError: lattice rank=1 and ambient_dim=3 are incompatible
+
+    We also get an error if no arguments are given::
+
+        sage: cones.nonnegative_orthant()
+        Traceback (most recent call last):
+        ...
+        ValueError: either the ambient dimension or the lattice must
+        be specified
+    """
+    from sage.geometry.cone import Cone
+    from sage.matrix.constructor import matrix
+    from sage.rings.integer_ring import ZZ
+
+    ambient_dim, lattice = _preprocess_args(ambient_dim, lattice)
+
+    I = matrix.identity(ZZ, ambient_dim)
+    return Cone(I.rows(), lattice)
+
+
+def rearrangement(p, ambient_dim=None, lattice=None):
+    r"""
+    The rearrangement cone of order ``p`` in ``ambient_dim``
+    dimensions, or living in ``lattice``.
+
+    The rearrangement cone of order ``p`` in ``ambient_dim``
+    dimensions consists of all vectors of length ``ambient_dim``
+    whose smallest ``p`` components sum to a nonnegative number.
+
+    For example, the rearrangement cone of order one has its single
+    smallest component nonnegative. This implies that all components
+    are nonnegative, and that therefore the rearrangement cone of
+    order one is the nonnegative orthant in its ambient space.
+
+    When ``p`` and ``ambient_dim`` are equal, all components of the
+    cone's elements must sum to a nonnegative number. In other
+    words, the rearrangement cone of order ``ambient_dim`` is a
+    half-space.
+
+    INPUT:
+
+    - ``p`` -- nonnegative integer; the number of components to
+      "rearrange", between ``1`` and ``ambient_dim`` inclusive
+
+    - ``ambient_dim`` -- nonnegative integer (default: ``None``); the
+      dimension of the ambient space
+
+    - ``lattice`` -- a toric lattice (default: ``None``); the lattice in
+      which the cone will live
+
+    If ``ambient_dim`` is omitted, then it will be inferred from the
+    rank of ``lattice``. If the ``lattice`` is omitted, then the
+    default lattice of rank ``ambient_dim`` will be used.
+
+    A :exc:`ValueError` is raised if neither ``ambient_dim`` nor
+    ``lattice`` are specified. It is also a :exc:`ValueError` to
+    specify both ``ambient_dim`` and ``lattice`` unless the rank of
+    ``lattice`` is equal to ``ambient_dim``.
+
+    It is also a :exc:`ValueError` to specify a non-integer ``p``.
+
+    OUTPUT:
+
+    A :class:`~sage.geometry.cone.ConvexRationalPolyhedralCone`
+    representing the rearrangement cone of order ``p`` living in
+    ``lattice``, with ambient dimension ``ambient_dim``. Each
+    generating ray has the integer ring as its base ring.
+
+    A :exc:`ValueError` can be raised if the inputs are incompatible
+    or insufficient. See the INPUT documentation for details.
+
+    ALGORITHM:
+
+    Suppose that the ambient space is of dimension `n`. The extreme
+    directions of the rearrangement cone for `1 \le p \le n-1` are
+    given by [Jeong2017]_ Theorem 5.2.3. When `2 \le p \le n-2` (that
+    is, if we ignore `p = 1` and `p = n-1`), they consist of
+
+    - the standard basis `\left\{e_{1},e_{2},\ldots,e_{n}\right\}` for
+      the ambient space, and
+
+    - the `n` vectors `\left(1,1,\ldots,1\right)^{T} - pe_{i}` for
+      `i = 1,2,\ldots,n`.
+
+    Special cases are then given for `p = 1` and `p = n-1` in the
+    theorem. However in SageMath we don't need conically-independent
+    extreme directions. We only need a generating set, because the
+    :func:`Cone` function will eliminate any redundant generators. And
+    one can easily verify that the special-case extreme directions for
+    `p = 1` and `p = n-1` are contained in the conic hull of the `2n`
+    generators just described. The half space resulting from `p = n`
+    is also covered by this set of generators, so for all valid `p` we
+    simply take the conic hull of those `2n` vectors.
+
+    REFERENCES:
+
+    - [GJ2016]_, Section 4
+
+    - [HS2010]_, Example 2.21
+
+    - [Jeong2017]_, Section 5.2
+
+    EXAMPLES:
+
+    The rearrangement cones of order one are nonnegative orthants::
+
+        sage: orthant = cones.nonnegative_orthant(6)
+        sage: cones.rearrangement(1,6).is_equivalent(orthant)
+        True
+
+    When ``p`` and ``ambient_dim`` are equal, the rearrangement cone
+    is a half-space, so we expect its lineality to be one less than
+    ``ambient_dim`` because it will contain a hyperplane but is not
+    the entire space::
+
+        sage: cones.rearrangement(5,5).lineality()
+        4
+
+    Jeong's Proposition 5.2.1 [Jeong2017]_ states that all rearrangement
+    cones are proper when ``p`` is less than ``ambient_dim``::
+
+        sage: all( cones.rearrangement(p, ambient_dim).is_proper()
+        ....:              for ambient_dim in range(10)
+        ....:              for p in range(1, ambient_dim) )
+        True
+
+    Jeong's Corollary 5.2.4 [Jeong2017]_ states that if `p = n-1` in
+    an `n`-dimensional ambient space, then the Lyapunov rank of the
+    rearrangement cone is `n`, and that for all other `p > 1` its
+    Lyapunov rank is one::
+
+        sage: all( cones.rearrangement(p, ambient_dim).lyapunov_rank()
+        ....:      ==
+        ....:      ambient_dim
+        ....:              for ambient_dim in range(2, 10)
+        ....:              for p in [ ambient_dim-1 ] )
+        True
+        sage: all( cones.rearrangement(p, ambient_dim).lyapunov_rank() == 1
+        ....:              for ambient_dim in range(3, 10)
+        ....:              for p in range(2, ambient_dim-1) )
+        True
+
+    TESTS:
+
+    Jeong's Proposition 5.2.1 [Jeong2017]_ states that rearrangement
+    cones are permutation-invariant::
+
+        sage: ambient_dim = ZZ.random_element(2,10).abs()
+        sage: p = ZZ.random_element(1, ambient_dim)
+        sage: K = cones.rearrangement(p, ambient_dim)
+        sage: P = SymmetricGroup(ambient_dim).random_element().matrix()                 # needs sage.groups
+        sage: all(K.contains(P*r) for r in K)                                           # needs sage.groups
+        True
+
+    The smallest ``p`` components of every element of the rearrangement
+    cone should sum to a nonnegative number. In other words, the
+    generators really are what we think they are::
+
+        sage: def _has_rearrangement_property(v, p):
+        ....:     return sum( sorted(v)[0:p] ) >= 0
+        sage: all(
+        ....:   _has_rearrangement_property(
+        ....:     cones.rearrangement(p, ambient_dim).random_element(),
+        ....:     p
+        ....:   )
+        ....:   for ambient_dim in range(2, 10)
+        ....:   for p in range(1, ambient_dim+1)
+        ....: )
+        True
+
+    The rearrangement cone of order ``p`` is, almost by definition,
+    contained in the rearrangement cone of order ``p + 1``::
+
+        sage: ambient_dim = ZZ.random_element(2,10)
+        sage: p = ZZ.random_element(1, ambient_dim)
+        sage: K1 = cones.rearrangement(p, ambient_dim)
+        sage: K2 = cones.rearrangement(p+1, ambient_dim)
+        sage: all( x in K2 for x in K1 )
+        True
+
+    Jeong's Proposition 5.2.1 [Jeong2017]_ states that the rearrangement
+    cone of order ``p`` is linearly isomorphic to the rearrangement
+    cone of order ``ambient_dim - p`` when ``p`` is less than
+    ``ambient_dim``::
+
+        sage: ambient_dim = ZZ.random_element(2,10)
+        sage: p = ZZ.random_element(1, ambient_dim)
+        sage: K1 = cones.rearrangement(p, ambient_dim)
+        sage: K2 = cones.rearrangement(ambient_dim-p, ambient_dim)
+        sage: Mp = ((1/p)*matrix.ones(QQ, ambient_dim)
+        ....:    - matrix.identity(QQ, ambient_dim))
+        sage: Cone( (Mp*K2.rays()).columns() ).is_equivalent(K1)
+        True
+
+    The order ``p`` should be an integer between ``1`` and
+    ``ambient_dim``, inclusive::
+
+        sage: cones.rearrangement(0,3)
+        Traceback (most recent call last):
+        ...
+        ValueError: order p=0 should be an integer between 1 and
+        ambient_dim=3, inclusive
+        sage: cones.rearrangement(5,3)
+        Traceback (most recent call last):
+        ...
+        ValueError: order p=5 should be an integer between 1 and
+        ambient_dim=3, inclusive
+        sage: cones.rearrangement(3/2, 3)
+        Traceback (most recent call last):
+        ...
+        ValueError: order p=3/2 should be an integer between 1 and
+        ambient_dim=3, inclusive
+
+    If a ``lattice`` was given, it is actually used::
+
+        sage: L = ToricLattice(3, 'M')
+        sage: cones.rearrangement(2, 3, lattice=L)
+        3-d cone in 3-d lattice M
+
+    Unless the rank of the lattice disagrees with ``ambient_dim``::
+
+        sage: L = ToricLattice(1, 'M')
+        sage: cones.rearrangement(2, 3, lattice=L)
+        Traceback (most recent call last):
+        ...
+        ValueError: lattice rank=1 and ambient_dim=3 are incompatible
+
+    We also get an error if neither the ambient dimension nor lattice
+    are specified::
+
+        sage: cones.rearrangement(3)
+        Traceback (most recent call last):
+        ...
+        ValueError: either the ambient dimension or the lattice must
+        be specified
+    """
+    from sage.geometry.cone import Cone
+    from sage.matrix.constructor import matrix
+    from sage.rings.integer_ring import ZZ
+
+    ambient_dim, lattice = _preprocess_args(ambient_dim, lattice)
+
+    if p < 1 or p > ambient_dim or p not in ZZ:
+        raise ValueError("order p=%s should be an integer between 1 "
+                         "and ambient_dim=%d, inclusive" % (p, ambient_dim))
+
+    I = matrix.identity(ZZ, ambient_dim)
+    M = matrix.ones(ZZ, ambient_dim) - p * I
+    G = matrix.identity(ZZ, ambient_dim).rows() + M.rows()
+    return Cone(G, lattice=lattice)
+
+
+def schur(ambient_dim=None, lattice=None):
+    r"""
+    The Schur cone in ``ambient_dim`` dimensions, or living
+    in ``lattice``.
+
+    The Schur cone in `n` dimensions induces the majorization
+    preordering on the ambient space. If `\left\{e_{1}, e_{2}, \ldots,
+    e_{n}\right\}` is the standard basis for the space, then its
+    generators are `\left\{e_{i} - e_{i+1}\ |\ 1 \le i \le
+    n-1\right\}`. Its dual is the downward monotone cone.
+
+    INPUT:
+
+    - ``ambient_dim`` -- nonnegative integer (default: ``None``); the
+      dimension of the ambient space
+
+    - ``lattice`` -- a toric lattice (default: ``None``); the lattice in
+      which the cone will live
+
+    If ``ambient_dim`` is omitted, then it will be inferred from the
+    rank of ``lattice``. If the ``lattice`` is omitted, then the
+    default lattice of rank ``ambient_dim`` will be used.
+
+    A :exc:`ValueError` is raised if neither ``ambient_dim`` nor
+    ``lattice`` are specified. It is also a :exc:`ValueError` to
+    specify both ``ambient_dim`` and ``lattice`` unless the rank of
+    ``lattice`` is equal to ``ambient_dim``.
+
+    OUTPUT:
+
+    A :class:`~sage.geometry.cone.ConvexRationalPolyhedralCone`
+    representing the Schur cone living in ``lattice``, with ambient
+    dimension ``ambient_dim``.  Each generating ray has the integer
+    ring as its base ring.
+
+    A :exc:`ValueError` can be raised if the inputs are incompatible
+    or insufficient. See the INPUT documentation for details.
+
+    .. SEEALSO::
+
+        :func:`downward_monotone`
+
+    REFERENCES:
+
+    - [GS2010]_, Section 3.1
+
+    - [IS2005]_, Example 7.3
+
+    - [SS2016]_, Example 7.4
+
+    EXAMPLES:
+
+    Verify the claim [SS2016]_ that the maximal angle between any two
+    generators of the Schur cone and the nonnegative orthant in
+    dimension five is `\left(3/4\right)\pi`::
+
+        sage: # needs sage.rings.number_field
+        sage: P = cones.schur(5)
+        sage: Q = cones.nonnegative_orthant(5)
+        sage: G = ( g.change_ring(QQbar).normalized() for g in P )
+        sage: H = ( h.change_ring(QQbar).normalized() for h in Q )
+        sage: actual = max(arccos(u.inner_product(v)) for u in G for v in H)            # needs sage.symbolic
+        sage: expected = 3*pi/4                                                         # needs sage.symbolic
+        sage: abs(actual - expected).n() < 1e-12                                        # needs sage.symbolic
+        True
+
+    The dual of the Schur cone is the downward-monotone cone
+    [GS2010]_, whose elements' entries are in non-increasing order::
+
+        sage: ambient_dim = ZZ.random_element(10)
+        sage: K = cones.schur(ambient_dim).dual()
+        sage: J = cones.downward_monotone(ambient_dim, K.lattice())
+        sage: K.is_equivalent(J)
+        True
+
+    TESTS:
+
+    We get the trivial cone when ``ambient_dim`` is zero::
+
+        sage: cones.schur(0).is_trivial()
+        True
+
+    The Schur cone induces the majorization preordering, as in Iusem
+    and Seeger's [IS2005]_ Example 7.3 or Niezgoda's [Niez1998]_
+    Example 2.2::
+
+        sage: ambient_dim = ZZ.random_element(10)
+        sage: V = VectorSpace(QQ, ambient_dim)
+        sage: rearrange = lambda z: V(sorted(z.list(),reverse=True))
+        sage: def majorized_by(x, y):
+        ....:     x = rearrange(x)
+        ....:     y = rearrange(y)
+        ....:     return (all(sum(x[0:i]) <= sum(y[0:i])
+        ....:                 for i in range(x.degree()-1))
+        ....:             and sum(x) == sum(y))
+        sage: S = cones.schur(ambient_dim)
+        sage: majorized_by(V.zero(), S.random_element())
+        True
+        sage: x = V.random_element()
+        sage: y = V.random_element()
+        sage: majorized_by(x,y) == ((rearrange(y) - rearrange(x)) in S)
+        True
+
+    If a ``lattice`` was given, it is actually used::
+
+        sage: L = ToricLattice(3, 'M')
+        sage: cones.schur(3, lattice=L)
+        2-d cone in 3-d lattice M
+
+    Unless the rank of the lattice disagrees with ``ambient_dim``::
+
+        sage: L = ToricLattice(1, 'M')
+        sage: cones.schur(3, lattice=L)
+        Traceback (most recent call last):
+        ...
+        ValueError: lattice rank=1 and ambient_dim=3 are incompatible
+
+    We also get an error if no arguments are given::
+
+        sage: cones.schur()
+        Traceback (most recent call last):
+        ...
+        ValueError: either the ambient dimension or the lattice must
+        be specified
+    """
+    from sage.geometry.cone import Cone
+    from sage.matrix.constructor import matrix
+    from sage.rings.integer_ring import ZZ
+
+    ambient_dim, lattice = _preprocess_args(ambient_dim, lattice)
+
+    def _f(i, j):
+        if i == j:
+            return 1
+        elif j - i == 1:
+            return -1
+        else:
+            return 0
+
+    # The "max" below catches the trivial case where ambient_dim == 0.
+    S = matrix(ZZ, max(0, ambient_dim-1), ambient_dim, _f)
+
+    return Cone(S.rows(), lattice)
+
+
+def trivial(ambient_dim=None, lattice=None):
+    r"""
+    The trivial cone with no nonzero generators in ``ambient_dim``
+    dimensions, or living in ``lattice``.
+
+    INPUT:
+
+    - ``ambient_dim`` -- nonnegative integer (default: ``None``); the
+      dimension of the ambient space
+
+    - ``lattice`` -- a toric lattice (default: ``None``); the lattice in
+      which the cone will live
+
+    If ``ambient_dim`` is omitted, then it will be inferred from the
+    rank of ``lattice``. If the ``lattice`` is omitted, then the
+    default lattice of rank ``ambient_dim`` will be used.
+
+    A :exc:`ValueError` is raised if neither ``ambient_dim`` nor
+    ``lattice`` are specified. It is also a :exc:`ValueError` to
+    specify both ``ambient_dim`` and ``lattice`` unless the rank of
+    ``lattice`` is equal to ``ambient_dim``.
+
+    OUTPUT:
+
+    A :class:`~sage.geometry.cone.ConvexRationalPolyhedralCone`
+    representing the trivial cone with no nonzero generators living in
+    ``lattice``, with ambient dimension ``ambient_dim``.
+
+    A :exc:`ValueError` can be raised if the inputs are incompatible
+    or insufficient. See the INPUT documentation for details.
+
+    EXAMPLES:
+
+    Construct the trivial cone, containing only the origin, in three
+    dimensions::
+
+        sage: cones.trivial(3)
+        0-d cone in 3-d lattice N
+
+    If a ``lattice`` is given, the trivial cone will live in that
+    lattice::
+
+        sage: L = ToricLattice(3, 'M')
+        sage: cones.trivial(3, lattice=L)
+        0-d cone in 3-d lattice M
+
+    TESTS:
+
+    We can construct the trivial cone in a trivial ambient space::
+
+        sage: cones.trivial(0)
+        0-d cone in 0-d lattice N
+
+    An error is raised if the rank of the lattice disagrees with
+    ``ambient_dim``::
+
+        sage: L = ToricLattice(1, 'M')
+        sage: cones.trivial(3, lattice=L)
+        Traceback (most recent call last):
+        ...
+        ValueError: lattice rank=1 and ambient_dim=3 are incompatible
+
+    We also get an error if no arguments are given::
+
+        sage: cones.trivial()
+        Traceback (most recent call last):
+        ...
+        ValueError: either the ambient dimension or the lattice must
+        be specified
+    """
+    from sage.geometry.cone import Cone
+
+    ambient_dim, lattice = _preprocess_args(ambient_dim, lattice)
+
+    return Cone([], lattice)