1#############################################################################
2##
3##  ToricVarieties.gd         ToricVarieties package
4##
5##  Copyright 2011- 2016, Sebastian Gutsche, TU Kaiserslautern
6##                        Martin Bies,       ITP Heidelberg
7##
8#! @Chapter Toric Varieties
9##
10#############################################################################
11
12#################################
13##
14## Global Variable
15##
16#################################
17
18DeclareGlobalVariable( "TORIC_VARIETIES" );
19
20#################################
21##
22#! @Section Toric variety: Category and Representations
23##
24#################################
25
26#! @Description
27#!  Checks if an object is a toric variety.
28#! @Returns true or false
29#! @Arguments M
30DeclareCategory( "IsToricVariety",
31                 IsObject );
32
33#! @Description
34#!  The <A>GAP</A> category of toric varieties.
35#! @Arguments object
36DeclareCategory( "IsCategoryOfToricVarieties",
37                 IsHomalgCategory );
38
39#! @Description
40#!  This is a dummy to get immediate methods triggered at some times. It never has a value.
41#! @Returns a ring
42#! @Arguments vari
43DeclareAttribute( "twitter",
44                  IsToricVariety );
45
46#################################
47##
48#! @Section Properties
49##
50#################################
51
52#! @Description
53#!  Checks if the toric variety <A>vari</A> is a normal variety.
54#! @Returns true or false
55#! @Arguments vari
56DeclareProperty( "IsNormalVariety",
57                  IsToricVariety );
58
59#! @Description
60#!  Checks if the toric variety <A>vari</A> is an affine variety.
61#! @Returns true or false
62#! @Arguments vari
63DeclareProperty( "IsAffine",
64                 IsToricVariety );
65
66#! @Description
67#!  Checks if the toric variety <A>vari</A> is a projective variety.
68#! @Returns true or false
69#! @Arguments vari
70DeclareProperty( "IsProjective",
71                 IsToricVariety );
72
73#! @Description
74#!  Checks if the toric variety <A>vari</A> is smooth.
75#! @Returns true or false
76#! @Arguments vari
77DeclareProperty( "IsSmooth",
78                 IsToricVariety );
79
80#! @Description
81#!  Checks if the toric variety <A>vari</A> is complete.
82#! @Returns true or false
83#! @Arguments vari
84DeclareProperty( "IsComplete",
85                 IsToricVariety );
86
87#! @Description
88#!  Checks if the toric variety <A>vari</A> has a torus factor.
89#! @Returns true or false
90#! @Arguments vari
91DeclareProperty( "HasTorusfactor",
92                 IsToricVariety );
93
94#! @Description
95#!  Checks if the toric variety <A>vari</A> has no torus factor.
96#! @Returns true or false
97#! @Arguments vari
98DeclareProperty( "HasNoTorusfactor",
99                 IsToricVariety );
100
101#! @Description
102#!  Checks if the toric variety <A>vari</A> has an orbifold, which is, in the toric case, equivalent to the
103#! simpliciality of the fan.
104#! @Returns true or false
105#! @Arguments vari
106DeclareProperty( "IsOrbifold",
107                 IsToricVariety );
108
109#! @Description
110#!  Checks if the toric variety <A>vari</A> is simplicial. This is a convenience method equivalent to
111#! IsOrbifold.
112#! @Returns true or false
113#! @Arguments vari
114DeclareProperty( "IsSimplicial",
115                 IsToricVariety );
116
117#################################
118##
119#! @Section Attributes
120##
121#################################
122
123#! @Description
124#!  Returns a torus invariant affine open covering of the variety <A>vari</A>. The affine open cover is computed out of the
125#!  cones of the fan.
126#! @Returns a list
127#! @Arguments vari
128DeclareAttribute( "AffineOpenCovering",
129                  IsToricVariety );
130
131#! @Description
132#!  Returns the Cox ring of the variety <A>vari</A>. The actual method requires
133#!  a string with a name for the variables. A method for computing the Cox ring without
134#!  a variable given is not implemented. You will get an error.
135#! @Returns a ring
136#! @Arguments vari
137DeclareAttribute( "CoxRing",
138                  IsToricVariety );
139
140#! @Description
141#!  Returns a list of the variables of the cox ring of the variety <A>vari</A>.
142#! @Returns a list
143#! @Arguments vari
144DeclareAttribute( "ListOfVariablesOfCoxRing",
145                  IsToricVariety );
146
147#! @Description
148#!  Returns the class group of the variety <A>vari</A> as factor of a free module.
149#! @Returns a module
150#! @Arguments vari
151DeclareAttribute( "ClassGroup",
152                  IsToricVariety );
153
154#! @Description
155#!  Returns the subgroup of the Weil divisor group of the variety <A>vari</A> generated by the torus invariant prime divisors.
156#!  This is always a finitely generated free module over the integers.
157#! @Returns a module
158#! @Arguments vari
159DeclareAttribute( "TorusInvariantDivisorGroup",
160                  IsToricVariety );
161
162#! @Description
163#!  Returns a map which maps an element of the character group into the torus invariant Weil group of the variety <A>vari</A>.
164#!  This has to be viewed as a help method to compute divisor classes.
165#! @Returns a morphism
166#! @Arguments vari
167DeclareAttribute( "MapFromCharacterToPrincipalDivisor",
168                  IsToricVariety );
169
170#! @Description
171#!  Returns a map which maps a Weil divisor into the class group.
172#! @Returns a morphism
173#! @Arguments vari
174DeclareAttribute( "MapFromWeilDivisorsToClassGroup",
175                  IsToricVariety );
176
177#! @Description
178#!  Returns the dimension of the variety <A>vari</A>.
179#! @Returns an integer
180#! @Arguments vari
181DeclareAttribute( "Dimension",
182                  IsToricVariety );
183
184#! @Description
185#!  Returns the dimension of the torus factor of the variety <A>vari</A>.
186#! @Returns an integer
187#! @Arguments vari
188DeclareAttribute( "DimensionOfTorusfactor",
189                  IsToricVariety );
190
191#! @Description
192#!  Returns the coordinate ring of the torus of the variety <A>vari</A>. This is by default done with the variables
193#!  <A>x1</A> to <A>xn</A> where <A>n</A> is the dimension of the variety. To use a different set of variables, a convenience method
194#!  is provided and described in the <A>methods</A> section.
195#! @Returns a ring
196#! @Arguments vari
197DeclareAttribute( "CoordinateRingOfTorus",
198                  IsToricVariety );
199
200#! @Description
201#!  Returns the list of variables in the coordinate ring of the torus of the variety <A>vari</A>.
202#! @Returns a list
203#! @Arguments vari
204DeclareAttribute( "ListOfVariablesOfCoordinateRingOfTorus",
205                  IsToricVariety );
206
207#! @Description
208#!  If the variety <A>vari</A> is a product of 2 or more varieties, the list contains those varieties.
209#!  If it is not a product or at least not generated as a product, the list only contains the variety itself.
210#! @Returns a list
211#! @Arguments vari
212DeclareAttribute( "IsProductOf",
213                  IsToricVariety );
214
215#! @Description
216#!  The method returns the character lattice of the variety <A>vari</A>, computed as the containing grid of the
217#!  underlying convex object, if it exists.
218#! @Returns a module
219#! @Arguments vari
220DeclareAttribute( "CharacterLattice",
221                  IsToricVariety );
222
223#! @Description
224#!  The method returns a list of the torus invariant prime divisors of the variety <A>vari</A>.
225#! @Returns a list
226#! @Arguments vari
227DeclareAttribute( "TorusInvariantPrimeDivisors",
228                  IsToricVariety );
229
230#! @Description
231#!  Returns the irrelevant ideal of the Cox ring of the variety <A>vari</A>.
232#! @Returns an ideal
233#! @Arguments vari
234DeclareAttribute( "IrrelevantIdeal",
235                  IsToricVariety );
236
237#! @Description
238#!  Returns the Stanley-Reißner ideal of the Cox ring of the variety <A>vari</A>.
239#! @Returns an ideal
240#! @Arguments vari
241DeclareAttribute( "SRIdeal",
242                 IsToricVariety );
243
244#! @Description
245#!  The method returns the quotient morphism from the variety of the Cox ring to the variety <A>vari</A>.
246#! @Returns a morphism
247#! @Arguments vari
248DeclareAttribute( "MorphismFromCoxVariety",
249                  IsToricVariety );
250
251#! @Description
252#!  The method returns the Cox variety of the variety <A>vari</A>.
253#! @Returns a variety
254#! @Arguments vari
255DeclareAttribute( "CoxVariety",
256                  IsToricVariety );
257
258#! @Description
259#!  Returns the fan of the variety <A>vari</A>. This is set by default.
260#! @Returns a fan
261#! @Arguments vari
262DeclareAttribute( "FanOfVariety",
263                  IsToricVariety );
264
265#! @Description
266#!  Returns the the group of Cartier divisors of the variety <A>vari</A> as a subgroup of the divisor group.
267#! @Returns a module
268#! @Arguments vari
269DeclareAttribute( "CartierTorusInvariantDivisorGroup",
270                  IsToricVariety );
271
272#! @Description
273#!   Returns the Picard group of the variety <A>vari</A> as factor of a free module.
274#! @Returns a module
275#! @Arguments vari
276DeclareAttribute( "PicardGroup",
277                  IsToricVariety );
278
279#! @Description
280#!   Returns the name of the variety <A>vari</A> if it has one and it is known or can be computed.
281#! @Returns a string
282#! @Arguments vari
283DeclareAttribute( "NameOfVariety",
284                  IsToricVariety );
285
286#! @Description
287#!  This method returns a f. p. graded <A>S</A>-module (<A>S</A> being the Cox ring of the variety), such that the sheafification of
288#!  this module is the Zariski cotangent sheaf of <A>vari</A>.
289#! @Returns a f.p. graded <A>S</A>-module
290#! @Arguments vari
291DeclareAttribute( "ZariskiCotangentSheaf",
292                  IsToricVariety );
293
294#! @Description
295#!  This method returns a f. p. graded <A>S</A>-module (<A>S</A> being the Cox ring of the variety), such that the sheafification of
296#!  this module is the cotangent sheaf of <A>vari</A>.
297#! @Returns a f.p. graded <A>S</A>-module
298#! @Arguments vari
299DeclareAttribute( "CotangentSheaf",
300                  IsToricVariety );
301
302#! @Description
303#!  This method computes the Euler characteristic of <A>vari</A>.
304#! @Returns a non-negative integer
305#! @Arguments vari
306DeclareAttribute( "EulerCharacteristic",
307                  IsToricVariety );
308
309#################################
310##
311#! @Section Methods
312##
313#################################
314
315#! @Description
316#!  The method returns the underlying sheaf of the variety <A>vari</A>.
317#! @Returns a sheaf
318#! @Arguments vari
319DeclareOperation( "UnderlyingSheaf",
320                  [ IsToricVariety ] );
321
322#! @Description
323#!  Computes the coordinate ring of the torus of the variety <A>vari</A> with the variables <A>vars</A>.
324#!  The argument <A>vars</A> need to be a list of strings with length dimension or two times dimension.
325#! @Returns a ring
326#! @Arguments vari, vars
327DeclareOperation( "CoordinateRingOfTorus",
328                  [ IsToricVariety, IsList ] );
329
330DeclareOperation( "CoordinateRingOfTorus",
331                  [ IsToricVariety, IsStringRep ] );
332
333#! @Description
334#!  Computes the categorial product of the varieties <A>vari1</A> and <A>vari2</A>.
335#! @Returns a variety
336#! @Arguments vari1, vari2
337DeclareOperation( "\*",
338                  [ IsToricVariety, IsToricVariety ] );
339
340#! @Description
341#!  Computes the rational function corresponding to the character grid element <A>elem</A> or to the list of
342#!  integers <A>elem</A>. This computation needs to know the coordinate ring of the torus of the variety <A>vari</A>. By
343#!  default this ring is introduced with variables <A>x1</A> to <A>xn</A> where <A>n</A> is the dimension of the variety. If
344#!  different variables should be used, then <A>CoordinateRingOfTorus</A> has to be set accordingly before calling this method.
345#! @Returns a homalg element
346#! @Arguments elem, vari
347DeclareOperation( "CharacterToRationalFunction",
348                  [ IsHomalgElement, IsToricVariety ] );
349
350DeclareOperation( "CharacterToRationalFunction",
351                  [ IsList, IsToricVariety ] );
352
353#! @Description
354#!  Computes the Cox ring of the variety <A>vari</A>. <A>vars</A> needs to be a string. We allow for two
355#! different formats. Either, it is a string which does not contain ",". Then this string will be index and
356#! the resulting strings are then used as names for the variables of the Cox ring. Alternatively, one can also
357#! use a string containing ",". In this case, a "," is considered as separator and one can provide individual
358#! names for all variables of the Cox ring.
359#! @Returns a ring
360#! @Arguments vari, vars
361DeclareOperation( "CoxRing",
362                  [ IsToricVariety, IsList ] );
363
364#! @Description
365#!  Returns a list of the currently defined Divisors of the toric variety.
366#! @Returns a list
367#! @Arguments vari
368DeclareOperation( "WeilDivisorsOfVariety",
369                  [ IsToricVariety ] );
370
371#! @Description
372#!  Returns the fan of the variety <A>vari</A>. This is a rename for FanOfVariety.
373#! @Returns a fan
374#! @Arguments vari
375DeclareOperation( "Fan",
376                  [ IsToricVariety ] );
377
378#! @Description
379#!
380#! @Arguments vari
381DeclareOperation( "Factors",
382                  [ IsToricVariety ] );
383
384#! @Description
385#!
386#! @Arguments vari, p
387DeclareOperation( "BlowUpOnIthMinimalTorusOrbit",
388                  [ IsToricVariety, IsInt ] );
389
390#! @Description
391#!
392DeclareGlobalFunction( "ZariskiCotangentSheafViaEulerSequence" );
393
394#! @Description
395#!
396DeclareGlobalFunction( "ZariskiCotangentSheafViaPoincareResidueMap" );
397
398#! @Description
399#!
400#! @Arguments vari, p
401DeclareOperation( "ithBettiNumber",
402                  [ IsToricVariety, IsInt ] );
403
404#! @Description
405#!
406#! @Arguments vari, p
407DeclareOperation( "NrOfqRationalPoints",
408                  [ IsToricVariety, IsInt ] );
409
410#################################
411##
412#! @Section Constructors
413##
414#################################
415
416#! @Description
417#!
418#! @Arguments vari
419DeclareOperation( "ToricVariety",
420                  [ IsToricVariety ] );
421
422
423## I guess that this is a convenience method which internally turn the list into a convex object.
424#! @Description
425#!
426#! @Arguments vari
427DeclareOperation( "ToricVariety",
428                  [ IsList ] );
429
430#! @Description
431#!  Creates a toric variety out of the convex object <A>conv</A>.
432#! @Returns a variety
433#! @Arguments conv
434DeclareOperation( "ToricVariety",
435                  [ IsConvexObject ] );
436
437#! @Description
438#! Creates a toric variety from a list <A>rays</A> of ray generators and cones <A>cones</A>.
439#! Beyond the functionality of the other methods, this constructor allows to assign specific
440#! gradings to the homogeneous variables of the Cox ring.
441#! With respect to the order in which the rays appear in the list <A>rays</A>, we assign gradings
442#! as provided by the third argument <A>degree_list</A> . The latter is a list of integers.
443#! @Returns a variety
444#! @Arguments rays, cones, degree_list
445DeclareOperation( "ToricVariety",
446                  [ IsList, IsList, IsList ] );
447
448#! @Description
449#! Creates a toric variety from a list <A>rays</A> of ray generators and cones <A>cones</A>.
450#! Beyond the functionality of the other methods, this constructor allows to assign specific
451#! gradings and homogeneous variable names to the ray generators of this toric variety.
452#! With respect to the order in which the rays appear in the list <A>rays</A>, we assign gradings
453#! and variable names as provided by the third and fourth argument. These are the list of gradings
454#! <A>degree_list</A> and the list of variables names <A>var_list</A>. The former is a list of
455#! integers and the latter a list of strings.
456#! @Returns a variety
457#! @Arguments rays, cones, degree_list, var_list
458DeclareOperation( "ToricVariety",
459                  [ IsList, IsList, IsList, IsList ] );
460
461DeclareOperation( "DeriveToricVarietiesFromGrading",
462                  [ IsList, IsBool ] );
463
464#! @Description
465#! Given a $\mathbb{Z}^n$-grading of a polynomial ring, this method computes all toric varieties, which are
466#! normal and have no-torus factor and whose Cox ring obeys the given $\mathbb{Z}^n$-grading.
467#! @Returns a list of toric varieties
468#! @Arguments a list of lists of integers
469DeclareOperation( "ToricVarietiesFromGrading",
470                  [ IsList ] );
471
472#! @Description
473#! Given a $\mathbb{Z}^n$-grading of a polynomial ring, this method computes a toric variety, which is
474#! normal and has no-torus factor and whose Cox ring obeys the given $\mathbb{Z}^n$-grading.
475#! @Returns a toric variety
476#! @Arguments a list of lists of integers
477DeclareOperation( "ToricVarietyFromGrading",
478                  [ IsList ] );
479