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 support@gap-system.org.
Rather than sketch the theory of toric varieties, we refer to [JV02] and [Ful93] for details. However, we briefly describe some terminology and notation.
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).
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
).
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.
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.
generated by GAPDoc2HTML