mjo/cone/nonnegative_orthant.py

   1 r"""
   2 The nonnegative orthant in `\mathbb{Z}^{n}`. I'm sick and tired of
   3 typing it.
   4 """
   5
   6 from sage.all import *
   7
   8 def nonnegative_orthant(n, lattice=None):
   9     r"""
  10     The nonnegative orthant in ``n`` dimensions.
  11
  12     INPUT:
  13
  14       - ``n`` -- the dimension of the ambient space.
  15
  16       - ``lattice`` -- (default: ``None``) an ambient lattice of rank ``n``
  17                        to be passed to the :func:`Cone` constructor.
  18
  19     OUTPUT:
  20
  21     The convex cone having ``n`` standard basis vectors as its
  22     generators. Each generating ray will have the integer ring as its
  23     base ring.
  24
  25     If a ``lattice`` was specified, then the resulting cone will live in
  26     that lattice unless its rank is incompatible with the dimension
  27     ``n`` (in which case a ``ValueError`` is raised).
  28
  29     SETUP::
  30
  31         sage: from mjo.cone.nonnegative_orthant import nonnegative_orthant
  32
  33     EXAMPLES::
  34
  35         sage: nonnegative_orthant(3).rays()
  36         N(1, 0, 0),
  37         N(0, 1, 0),
  38         N(0, 0, 1)
  39         in 3-d lattice N
  40
  41     TESTS:
  42
  43     We can construct the trivial cone as the nonnegative orthant in a
  44     trivial vector space::
  45
  46         sage: nonnegative_orthant(0)
  47         0-d cone in 0-d lattice N
  48
  49     The nonnegative orthant is a proper cone::
  50
  51         sage: set_random_seed()
  52         sage: n = ZZ.random_element(10)
  53         sage: K = nonnegative_orthant(n)
  54         sage: K.is_proper()
  55         True
  56
  57     If a ``lattice`` was given, it is actually used::
  58
  59         sage: L = ToricLattice(3, 'M')
  60         sage: nonnegative_orthant(3, lattice=L)
  61         3-d cone in 3-d lattice M
  62
  63     Unless the rank of the lattice disagrees with ``n``::
  64
  65         sage: L = ToricLattice(1, 'M')
  66         sage: nonnegative_orthant(3, lattice=L)
  67         Traceback (most recent call last):
  68         ...
  69         ValueError: lattice rank=1 and dimension n=3 are incompatible
  70
  71     """
  72     if lattice is None:
  73         lattice = ToricLattice(n)
  74
  75     if lattice.rank() != n:
  76         raise ValueError('lattice rank=%d and dimension n=%d are incompatible'
  77                          %
  78                          (lattice.rank(), n))
  79
  80     I = identity_matrix(ZZ,n)
  81     return Cone(I.rows(), lattice)