1. Introduction
  
  
  1.1 Introduction to the toric package
  
  This  manual describes the toric package for working with toric varieties in
  GAP.  Toric  varieties  can be dealt with more easily than general varieties
  since  often  times  questions  about a toric variety can be reformulated in
  terms  of  combinatorial  geometry.  Some  coding theory commands related to
  toric  varieties  are  contained in the error-correcting codes GUAVA package
  (for  example,  the  command ToricCode). We refer to the GUAVA manual [CM08]
  and the expository paper [JV02] for more details.
  
  The  toric  package  also  contains  several  commands  unrelated  to  toric
  varieties  (mostly  for  list manipulations). These will not be described in
  this documention but they are briefly documented in the lib/util.gd file.
  
  toric  is implemented in the GAP language, and runs on any system supporting
  GAP4.3 and above. The toric package is loaded with the command
  
   gap> LoadPackage( "toric" );   Please  send  bug  reports,  suggestions  and  other comments about toric to
  mailto:support@gap-system.org.
  
  
  1.2 Introduction to constructing toric varieties
  
  Rather  than  sketch  the  theory of toric varieties, we refer to [JV02] and
  [Ful93]  for  details.  However,  we  briefly  describe some terminology and
  notation.
  
  
  1.2-1 Generalities
  
  Let  F  denote  a  field  and  R=F [x_1,...,x_n] be a ring in n variables. A
  binomial equation in R is one of the form
  
  
       x_1^{k_1}...x_n^{k_n}=x_1^{\ell_1}...x_n^{\ell_n},
  
  
  where  k_i >= 0, ell_j >= 0 are integers. A binomial variety is a subvariety
  of  affine n-space A_F^n defined by a finite set of binomial equations (such
  a  variety  need  not  be  normal). A typical ``toric variety'' is binomial,
  though they will be introduced via an a priori independent construction. The
  basic  idea of the construction is to replace each such binomial equation as
  above  by  a relation in a semigroup contained in a lattice and replace R by
  the  ``group  algebra''  of  this  semigroup. By the way, a toric variety is
  always normal (see for example, [Ful93], page 29).
  
  
  1.2-2 Basic combinatorial geometry constructions
  
  Let Q denote the field of rational numbers and Z denote the set of integers.
  Let n>1 denote an integer.
  
  Let   $V=Q^n$   having  basis  f_1=(1,0,...,0),  ...,  f_n=(0,...,0,1).  Let
  L_0=Z^nsubset  V be the standard lattice in V. We identify V and L_0otimes_Z
  Q. We use < , > to denote the (standard) inner product on V. Let
  
  
       L_0^*={\rm Hom}(L_0,Z)=\{ v\in V\ |\ \langle v,w \rangle \in Z, \
       \forall w\in L_0\}
  
  
  denote  the dual lattice, so (fixing the standard basis e_1^*,...,e_n^* dual
  to the f_1,...,f_n) L_0^* may be identified with Z^n.
  
  A cone in V is a set sigma of the form
  
  
       \sigma=\{a_1v_1+...+a_mv_m\ |\ a_i\geq 0\}\subset V,
  
  
  where  v_1,...,v_m in V is a given collection of vectors, called (semigroup)
  generators  of  sigma.  A  rational  cone is one where v_1,...,v_m in L_0. A
  strongly convex cone is one which contains no lines through the origin.
  
    By  abuse  of  terminology, from now on a cone of L_0 is a strongly convex
  rational cone. 
  
  A  face  of a cone sigma is either sigma itself or a subset of the form Hcap
  sigma,  where H is a codimension one subspace of V which intersects the cone
  non-trivially  and such that the cone is contained in exactly one of the two
  half-spaces  determined by H. A ray (or edge) of a cone is a one-dimensional
  face.  Typically,  cones  are  represented  in  toric by the list of vectors
  defining  their rays. The dimension of a cone is the dimension of the vector
  space  it  spans. The toric package can test if a given vector is in a given
  cone (see InsideCone).
  
  If sigma is a cone then the dual cone is defined by
  
  
       \sigma^* =\{w \in L_0^*\otimes Q \ |\ \langle v,w \rangle \geq 0,\
       \forall v\in \sigma\}.
  
  
  The  toric  package can test if a vector is in the dual of a given cone (see
  InDualCone).
  
  Associate to the dual cone sigma^* is the semigroup
  
  
       S_\sigma =\sigma^*\cap L_0^* =\{w\in L_0^* \ |\ \langle v,w\rangle
       \geq 0,\ \forall v\in \sigma\}.
  
  
  Though  L_0^*  has  $n$ generators as a lattice, typically S_sigma will have
  more  than  n  generators  as  a  semigroup. The toric package can compute a
  minimal     list     of     semigroup    generators    of    S_sigma    (see
  DualSemigroupGenerators).
  
  A  fan is a collection of cones which ``fit together'' well. A fan in L_0 is
  a  set Delta=sigma of rational strongly convex cones in V= L_0 otimes Q such
  that
  
  --    if  sigma in Delta and tau subset sigma is a face of sigma then tau in
        Delta,
  
  --    if sigma_1, sigma_2 in Delta then the intersection sigma_1 cap sigma_2
        is a face of both sigma_1 and sigma_2 (and hence belongs to Delta).
  
  In particular, the face of a cone in a fan is a cone is the fan.
  
  If V is the (set-theoretic) union of the cones in Delta then we call the fan
  complete.  We  shall assume that all fans are finite. A fan is determined by
  its list of maximal cones.
  
  Notation: A fan Delta is represented in toric as a set of maximal cones. For
  example,  if  Delta  is  the  fan  with  maximal cones sigma_1=Q_+* f_1+Q_+*
  (-f_1+f_2),    sigma_2=Q_+*    (-f_1+f_2)+Q_+*    (-f_1-f_2),   sigma_3=Q_+*
  (-f_1-f_2)+Q_+*      f_1,      then      Delta     is     represented     by
  [[[1,0],[-1,1]],[[-1,1],[-1,-1]],[[-1,-1],[1,0]]].
  
  The  toric  package can compute all cones in a fan of a given dimension (see
  ConesOfFan).  Moreover,  toric  can compute the set of all normal vectors to
  the faces (i.e., hyperplanes) of a cone (see Faces).
  
  The  star  of a cone sigma in a fan Delta is the set Delta_sigma of cones in
  Delta  containing  sigma as a face. The toric package can compute stars (see
  ToricStar).
  
  
  1.2-3 Basic affine toric variety constructions
  
  Let
  
  
       R_\sigma = F [S_\sigma]
  
  
  denote  the  ``group algebra'' of this semigroup. It is a finitely generated
  commutative  F-algebra.  It is in fact integrally closed ([Ful93], page 29).
  We  may  interprete  R_sigma  as  a subring of R=F [x_1,...,x_n] as follows:
  First, identify each e_i^* with the variable x_i. If S_sigma is generated as
  a  semigroup by vectors of the form ell_1 e_1^*+...+ell_n e_n^*, where ell_i
  is  an  integer,  then  its image in R is generated by monomials of the form
  x_1^ell_1dots  x_n^ell_n.  The  toric  package  can compute these generating
  monomials  (see  EmbeddingAffineToricVariety).  See Lemma 2.14 in [JV02] for
  more details. This embedding can also be used to resolve singularities - see
  section 5 of [JV02] for more details.
  
  Let
  
  
       U_\sigma={\rm Spec}\ R_\sigma.
  
  
  This defines an affine toric variety (associated to sigma). It is known that
  the coordinate ring R_sigma of the affine toric variety U_sigma has the form
  R_sigma  =  F[x_1,...,x_n]/J,  where  J  is  an ideal. The toric package can
  compute generators of this ideal (see IdealAffineToricVariety).
  
  Roughly  speaking, the toric variety X(Delta) associated to the fan Delta is
  given        by        a       collection       of       affine       pieces
  $U_{\sigma_1},U_{\sigma_2},\dots,U_{\sigma_d}$   which   ``glue''   together
  (where  Delta  =  sigma_i).  The affine pieces are given by the zero sets of
  polynomial equations in some affine spaces and the gluings are given by maps
  phi_i,j  : U_sigma_i -> U_sigma_j which are defined by ratios of polynomials
  on  open  subsets  of the $U_{\sigma_i}$. The toric package does not compute
  these gluings or work directly with these (non-affine) varieties X(Delta).
  
  A  cone  sigma subset V is said to be nonsingular if it is generated by part
  of  a  basis  for  the  lattice  L_0.  A  fan  Delta  of cones is said to be
  nonsingular  if  all  its cones are nonsingular. It is known that U_sigma is
  nonsingular  if  and  only  if  sigma  is  nonsingular  (Proposition  2.1 in
  [Ful93]).
  
  Example:      In      three      dimensions,      consider     the     cones
  sigma_epsilon_1,epsilon_2,epsilon_3,i,j     generated     by     (epsilon_1*
  1,epsilon_2*  1,epsilon_3*  1) and the standard basis vectors f_i,f_j, where
  epsilon_i=pm  1  and  1<=  inot=  j<= 3. There are 8 cones per octant, for a
  total  of  64  cones.  Let Delta denote the fan in V=Q^3 determined by these
  maximal cones. The toric variety X(Delta) is nonsingular.
  
  
  1.2-4 Riemann-Roch spaces and related constructions
  
  Although  the  toric package does not work directly with the toric varieties
  X(Delta),  it  can  compute  objects associated with it. For example, it can
  compute  the  Euler  characteristic (see EulerCharacteristic), Betti numbers
  (see  BettiNumberToric),  and  the  number  of  GF(q)-rational  points  (see
  CardinalityOfToricVariety) of X(Delta),  provided Delta is nonsingular.
  
  For  an  algebraic  variety X the group of Weil divisors on X is the abelian
  group  Div(X) generated (additively) by the irreducible subvarieties of X of
  codimension  1. For a toric variety X(Delta) with dense open torus T, a Weil
  divisor  D  is T-invariant if D=T* D. The group of T-invariant Weil divisors
  is denoted TDiv(X). This is finitely generated by an explicitly given finite
  set  of  divisors D_1,...,D_r which correspond naturally to certain cones in
  Delta  (see  [Ful93]  for  details).  In particular, we may represent such a
  divisor D in TDiv(X) by an k-tuple (d_1,...,d_k) of integers.
  
  Let  Delta  denote a fan in V=Q^n with rays (or edges) tau_i, 1<= i<= k, and
  let  v_i  denote  the  first  lattice  point  on  tau_i.  Associated  to the
  T-invariant Weil divisor D=d_1D_1+...+d_kD_k, is the polytope
  
  
       P_D = \{ x=(x_1,...,x_n)\ |\ \langle x,v_i \rangle \geq -d_i, \
       \forall 1 \leq i \leq k\}.
  
  
  The  toric package can compute P_D (see DivisorPolytope), as well as the set
  of    all    lattice    points    contained    in    this    polytope   (see
  DivisorPolytopeLatticePoints).  Also  associated  to  the  T-invariant  Weil
  divisor  D=d_1D_1+...+d_kD_k,  is  the  Riemann-Roch  space, L(D). This is a
  space of functions on X(Delta) whose zeros and poles are ``controlled'' by D
  (for  a more precise definition, see [Ful93]). The toric package can compute
  a  basis  for  L(D)  (see RiemannRochBasis),  provided Delta is complete and
  nonsingular.