Tutorial: Toric geometry in OSCAR¶

Author: Martin Bies

1 Affine toric varieties¶

Any geometry course (analytic geometry, algebraic geometry and of course toric geometry too) begins with the study of affine varieties/schemes. So we first recall that affine toric varieties are encoded by rational polyhedral cones.

Specifically, let us state theorem 1.2.18 of the book Toric Varieties by David Cox, John Little and Hal Schenck:

Let $\sigma \subseteq N_{\mathbb{R}} \cong \mathbb{R}^n$ be a rational polyhedral cone with semigroup $S_\sigma = \sigma^\vee \cap M$. Then the associated affine toric variety $U_\sigma$ is given by

$$ U_\sigma = \mathrm{Spec} \left(\mathbb{C} \left[ S_\sigma \right]\right) = \mathrm{Spec} \left(\mathbb{C} \left[ \sigma^\vee \cap M \right]\right) \, .$$

In particular, it holds

$$\mathrm{dim}( U_\sigma ) = n \, \Leftrightarrow \, \text{the torus of $U_\sigma$ is } T_N = N \otimes_{\mathbb{Z}} \mathbb{C}^\ast \, \Leftrightarrow \, \sigma \text{ is strongly convex.}$$

As per usual, we focus on strongy convex polyhedral cones $\sigma$, so that $T_N$ is the algebraic torus of $U_\sigma$.

1.1 Constructing affine toric varieties¶

1.2 Properties and attributes¶

The cone $\sigma$ encodes a lot of information about the affine toric variety $U_\sigma$. In the background, OSCAR conducts such investigations in polyhedral geometry with Polymake (cf. https://polymake.org/doku.php/start). This allows us to access a lot of properties of affine toric varieties. Here are a few examples

We can also look for polynomials that cut out this affine variety in $\mathbb{C}^k$ for a suitable integer $k$. The ideal, which cuts out the affine variety in question is nothing but the toric ideal. We compute it as follows:

This means, that the variety antv is nothing but $\mathbb{C}^2$. Here is a more interesting example:

So in $\mathbb{C}^3$ with coordinate ring $\mathbb{C}[ x_1, x_2, x_3 ]$ we are looking at the variety $X = V( - x_1 x_2 + x_3^2 )$. This is a rather classical example of a simplicial, affine toric variety.

2 The projective space¶

More general toric varieties are constructed by providing not only one strongly convex polyhedral cone, but a collection of "compatible" cones. Such a collection is termed a (strongly convex polyhedral) fan.

We give details on how to create fans and the corresponding toric varieties in section 3 of this tutorial. In this section however, we demonstrate the existing functionality in OSCAR by studying the projective space. Specifically, let us focus on the projective space $\mathbb{P}^2$.

2.1 Constructing the projective space¶

We construct the projective space as follows:

As you can notice, upon creation a lot of information on this space is already known.

Notice that the constructor expects us to state as first argument NormalToricVariety. This is to tell OSCAR that we want the projective space as a toric variety.

This is a design decision that was taken after careful consideration. Namely, the projective space could in principle be constructed as a scheme (with an arbitrary coefficient ring) or merely as a space parametrized by homogeneous coordinates. Depending on which of these perspectives is desired, specializes algorithms may be available. As of February 2023, there are many specialized toric algorithms. So in this regard, providing NormalToricVariety as the first argument ensures that we can perform a large number of computations.

2.2 Properties and attributes¶

We can check for properties by invoking "is_" followed by the property that we want to compute. Here are a few examples:

An exception to this rule is the torus factor. Namely, since the terminology is to ask for "having a torus factor", we have to invoke:

A basic attribute that we would like to access is the dimension of the space:

The next interesting class of attributes concerns the divisors on toric varieties. Let us turn to them next.

2.3 The groups of Weil and Cartier divisors¶

The group of the torus-invariant Weil divisors $\mathrm{Div}_T(\mathbb{P}^2)$ can be accessed as follows:

Of course, we can map torus-invariant Weil divisors to the class group $\mathrm{Cl}( \mathbb{P}^2 )$:

To see the mapping prescription, we can access the matrix of this map:

This means, that there are 3 torus-invariant Weil divisors $D_1$, $D_2$, $D_3$ for $\mathbb{P}^2$ (each corresponding to a ray in the fan of $\mathbb{P}^2$). The map to the class group assigns to each of the 3 torus-invariant Weil divisors the same divisor class, i.e. $[D_1] = [D_2] = [D_3]$. Or put differently, the Weil divisors $D_1$, $D_2$, $D_3$ are linearly equivalent: $D_1 \sim D_2 \sim D_3$.

Of course, we can also use this information to find the Class group $\mathrm{Cl} ( \mathbb{P}^2 )$:

Similarly, we want to understand how the group of torus-invariant Cartier divisors $\mathrm{Div}_T(\mathbb{P}^2)$ map to the Picard group:

With this, we can also find the Picard group $\mathrm{Pic} ( \mathbb{P}^2 )$ of the projective space:

Recall that $\mathbb{P}^2$ is smooth. Therefore, the notion of the torus-invariant Cartier divisors and of the torus-invariant Weil divisors coincide. Indeed, we can see this by considering the map from the torus-invariant Cartier divisors to the torus-invariant Weil divisors:

At times, it will be interesting to find a torus-invariant Weil divisor $D$ that represents a certain divisor class. This is possible because $f_1$ is surjective:

Hence, for every $x \in \mathrm{Cl}(\mathbb{P}^2)$, there is a $y \in \mathrm{Div}_T(\mathbb{P}^2)$ with $f_1(y) = x$. We can compute such preimages:

Alternatively, we can even find the preinverse of $f_1$ directly:

This functionality is particularly useful in the context of line bundles on toric varieties, i.e. the elements of the Picard group $\mathrm{Pic}(\mathbb{P}^2)$. We will study line bundles momentarily.

We complete this section by briefly mentioning the character lattice $N(\mathbb{P}^2)$. Since $\mathbb{P}^2$ has no torus factor, there is a short exact sequence:

$$0 \to N(\mathbb{P}^2) \hookrightarrow \mathrm{Div}_T( \mathbb{P}^2 ) \twoheadrightarrow \mathrm{Cl} ( \mathbb{P}^2 ) \to 0.$$

The map $N(\mathbb{P}^2) \hookrightarrow \mathrm{Div}_T( \mathbb{P}^2 )$ can be computed as follows:

The columns of this matrix are the ray generators of the fan of the projective space $\mathbb{P}^2$.

2.4 Divisor classes¶

Let us now create a torus-invariant Weil divisor on the projective space $\mathbb{P}^2$. From the study of toric divisors above, we recall that the group of torus-invariant Weil divisors has 3 generators $D_1$, $D_2$ and $D_3$. Hence, the most general torus-invariant Weil divisor is of the form $a_1 D_1 + a_2 D_2 + a_3 D_3$ with $a_1, a_2, a_3 \in \mathbb{Z}$. The constructor for toric divisors on $\mathbb{P}^2$ expects the list $[a_1, a_2, a_3]$ as its second argument.

Let us now create the torusinvariant Weil divisor $D = 1 D_1 + 2 D_2 + 3 D_3$:

We support various properties and attributes for such a divisor:

In particular we can compute the divsior class associated to this divisor:

The task of finding a divisor in this divisor class is exactly the question of inverting the map $f_1$ introduced above. This is handled behind the scenes with the following command:

Note that $D_2$ and $D$ are not identical:

We can see this explicitly, by asking for the coefficients of $D_2$:

However, $D \sim D_2$. This is the case since $D - D_2$ is a principal divisor:

So, as expected $[D] = [D_2]$.

2.5 Line bundles¶

Line bundles are the elements of the Picard group $\mathrm{Pic}( \mathbb{P}^2 )$. They are created similarly to Weil divisor. Let us first demonstrate how we can compute the Picard group $\mathrm{Pic}(\mathbb{P}^2)$ in OSCAR:

Hence, this group has a single generator $G = \mathcal{O}_{\mathbb{P}^2}(1)$ and every element in this group is of the form $G^a = G \otimes \dots \otimes G = \mathcal{O}_{\mathbb{P}^2}(a)$ with $a \in \mathbb{Z}$. Therefore, the constructor for line bundles on the projective space expects $[a]$ as input. For instance, the following creates the line bundle $\mathcal{L} = \mathcal{O}_{\mathbb{P}^2}(1)$:

Again, various properties and attributes are supported for line bundles. For example, we can check if a line bundle is the trivial line bundle (i.e. the zero element in the Picard group):

Other properties are accessed by computing a divisor (class) corresponding to the line bundle in question (i.e. inverting the map $\mathrm{CDiv}( \mathbb{P}^2 ) \to \mathrm{Pic}( \mathbb{P}^2 )$):

Among others, ampleness of a line bundle is checked by checking it for the underlying divisor:

Another example is the degree of the line bundle:

2.6 Line bundle cohomology with cohomCalg¶

To compute line bundle cohomology, we use the cohomCalg algorithm (cf. https://github.com/BenjaminJurke/cohomCalg). It is executed as follows:

This means that $h^0( \mathbb{P}^2, \mathcal{L} ) = 3$ and $h^1( \mathbb{P}^2, \mathcal{L} ) = h^2( \mathbb{P}^2, \mathcal{L} ) = 0$. This result is of course well-known to the experts. This functionality works as long as the variety in question is either (smooth and complete) or (simplicial and projective).

Of course, we can also compute just some of the line bundle cohomologies. For instance, the following finds $h^0( \mathbb{P}^2, \mathcal{L} )$:

The Cox ring of the toric variety is very important. It is the algebraic counterpart to the structure sheaf $\mathcal{O}_{\mathbb{P}^2}$:

As such, it comes at no surprise that a basis of the global sections of line bundles can be found from the homogeneous components of the Cox ring. An alternative methods exists via Laurent monomials. Both options are available within OSCAR:

For convenience, the default is to use the homogeneous components. That is:

2.7 The fan¶

We now come back to constructing more general toric varieties. As mentioned above, this in general relies on the construction of a fan consisting of strongly convex polyhedral cones. This polyhedral geometry is the backbone for many computations in toric geometry. In particular, OSCAR knows the fan of the projective space $\mathbb{P}^2$:

You can plot this fan by invoking the command visualize(f). This will (most likely) open a separate window with an illustration of the fan. Alternatively, we can investigate the fan in more details by computing its rays and maximal cones:

Indeed, this is the famous fan of the projective space $\mathbb{P}^2$.

3 Constructing more general toric varieties¶

3.1 $\mathbb{P}^2$ from its fan¶

We now want to demonstrate how a toric variety can be created from a fan. As we have gained familarity with the projective space in the previous sections, it is natural to exemplify the operations on the projective space $\mathbb{P}^2$. For this, we proceed as follows:

When created in this way, the variety "knows" less information than by using the standard constructor projective_space()", as demonstrated in the previous section. The reason is that by providing the fan, we can construct all sorts of toric varieties. But we can of course compute the necessary information to convince ourselves that this indeed is the projective space $\mathbb{P}^2$:

3.2 Del Pezzo surfaces¶

We provide a constructor for del Pezzo surfaces. For instance, we can issue:

To demonstrate that the line bundle cohomology computations also work in such more general settings, let us construct a toric line bundle and compute its sheaf cohomology dimensions:

It is worth recalling that we can find a basis of the global sections. However, a basis for the higher sheaf cohomologies cannot (yet) be computed with OSCAR.

3.3 Hirzebruch surfaces¶

Similarly, we can also construct Hirzebruch surfaces:

3.4 Toric blowups¶

By means of a star subdivision, one can conduct a toric blowup. The relevant functionality is available in OSCAR. To this end let us look at the projective space anew:

Let us now perform a blowup of the locus $V( x_1, x_2 )$. This is done as follows:

The number "1" selects the maximal cone of the fan of $\mathbb{P}^2$ which we divide by the star subdivision. The string "e" defines the name for the new homogeneous coordinate of the toric variety. Here we have the following correspondence between ray generators and homogeneous variables: \begin{align} x_1 &\leftrightarrow [1,0] \,\\ x_2 &\leftrightarrow [0,1] \,\\ x_3 &\leftrightarrow [-1,-1] \,. \end{align} The blowup thus requires a star subdivision of the cone $C = \mathrm{Span}_{\mathbb{Z}_{\geq 0}} \left\{ [1,0], [0,1]\right\}$. To this end, we first compute the sum of the generators of $C$. This is a new ray generator: $$e \leftrightarrow [1,1] \,,$$ which we use to define the cones which maximally subdivide $C$, namely: $$C_1 = \mathrm{Span}_{\mathbb{Z}_{\geq 0}} \left\{ [1,0], [1,1]\right\} \, , \qquad C_2 = \mathrm{Span}_{\mathbb{Z}_{\geq 0}} \left\{ [1,1], [0,1]\right\} \, .$$ Let us see that this is indeed the case for the above computed toric space $B\mathbb{P}^2$:

So we notice the new ray $[1,1]$. To find the new cones $C_1$ and $C_2$, we issue the following:

So indeed, the last two cones are the expected new cones. The first two are the cones that exist for the fan of $\mathbb{P}^2$ and were not changed.

The variable $e$ we can see most prominently in the Cox ring:

It is instructive to look at the following alternative grading of the Cox ring (and we order the variables in ascending order): $$\begin{array}{ccc|c} x_1 & x_2 & x_3 & e \\ \hline 1 & 1 & 1 & 0 \\ 1 & 1 & 0 & -1 \end{array}$$ In the first line you notice the ordinary grading of the Cox ring of $\mathbb{P}^2$. The second line corresonds to the toric blowup that has been conducted. The $-1$ for $e$ tells us that this is the homogeneous coordinate introduced to resemble the blowup $\mathbb{P}^1$. The 1 for $x_1$ and $x_2$ tells us that this blowup added a $\mathbb{P}^1$ at the locus $\{ x_1 = x_2 = 0\}$ in $\mathbb{P}^2$. In other words, in $B\mathbb{P}^2$, $x_1$ and $x_2$ cannot vanish simultaneously: $$\{ [x_1 : x_2 : x_3 : e] \in B\mathbb{P}^2 | x_1 = x_2 = 0\} = \emptyset \, .$$ It is instructive to recall that the generators of the Stanley-Reisner ideal encode exactly which homogeneous variables cannot vanish simultaneously:

This means that $\emptyset = V( x_2, x_1 ) \subseteq B \mathbb{P}^2$ and $\emptyset = V( x_3, e ) \subset B \mathbb{P}^2$.

Along these lines, we can also see that the locus $V(e) \subset B\mathbb{P}^2$ is a $\mathbb{P}^1$. Namely, from the Stanley-Reisner ideal we learn that $x_3$ and $e$ cannot vanish simultaneously. So $x_3 \neq 0$ and we can rescale it to $1$. This rescaling effectively eliminates the 2nd line in the grading of the Cox ring and leaves us with $$\begin{array}{ccc|c} x_1 & x_2 \\ \hline 1 & 1 \end{array}$$ So we notice, that the variables $x_1$ and $x_2$ each enjoy the standard grading $(1,1)$. Also, since $x_1 x_2 \in I_{\text{SR}}( B\mathbb{P}^2 )$, it holds $\emptyset = V( x_2, x_1 ) \subset B \mathbb{P}^2$. This implies $V( e ) \cong \mathbb{P}^1_{[x_1 \colon x_2]}$.

3.5 Cartesian products¶

It is also possible to compute Cartesian products of toric varieties. Here is an example:

Notice that the set of variables "xx*" correspond to the $\mathbb{P}^2$ factor, and the remaining variables are the homogeneous coordinates of the Hirzebruch surface $\mathbb{F}_2$.

3.6 Triangulations¶

Triangulations of polytopes open an entire arena for creating families of toric varieties whose properties are often related to one-another in interesting ways. A prominent example along these lines is the Kreuzer-Skarke database (cf. http://hep.itp.tuwien.ac.at/~kreuzer/CY/). Another popular example is the conifold transition, which we now use to demonstrate triangulation functionality in OSCAR:

If desired, you can look at $P$ by invoking visualize(P). The polyhedron $P$ admits exactly two fine, regular, star triangulations. These were used to create the toric varieties $v_1$ and $v_2$. We now study these two varieties:

If we repeat these line with $v_2$, then the only difference is:

So in a sence, the transition from $v_1$ to $v_2$ means that the roles of ($x_2$, $x_4$) and ($x_1$, $x_3$) are exchanged. Indeed, the conifold transition means to first perform a deformation which shrinks an algebraic cycle to zero. This leads to a conifold singularity which is subsequently resolved by blowing up another algebraic cycle.

3.7 Benchmarking an involved triangulation computation¶

Triangulations are a topic that features prominently in applied mathematics, e.g. in string theory. The following code was used in a recent string theory publication (https://arxiv.org/abs/2205.00008):

In a nutshell, this code computes all fine regular star triangulations of the polyhedron fac1, computes the Stanley-Reisner of the associated toric varieties and then intersects these ideals. As such, it finds the intersection theory that is common to this family of toric varieties.

The code for fac1 and fac4 will likely execute within a few seconds. For the polyhedrons fac2 or fac3, the task is much more involved and will likely take a few minutes. This is why in the above code, we fixed the choice of polyhedron to fac1. Brave users may which to challenge their computer a bit by altering that choice to fac2 or fac3. The computations should still complete on most private computers within a few minutes.

To benchmark the execution time of the function involved_triangulation, and thus provide comparision to other computer systems, we can execute the following:

You might find it interesting to compare your executation time to the following result:

• Execution time: 267.974ms,
• 358874 allocations (13.91 MiB).

This result was obtained on March 7, 2023 by runnning the OSCAR (see the beginning of this notebook for the version) with Julia 1.7.3 on a TUXEDO InfinityBook Pro 14 v4 with Intel Core i7-Quad-Core, 32GB RAM and operating system Ubuntu 20.04.5 LTS.

3.8 Turning off input checks¶

OSCAR aims for a broad user audience. As such, input is usually checked for consistency. This comes at the expense of loosing a bit of performance and possibly modifying the input data (if needed), e.g. shuffling it. In the toric settings, such shufflings of e.g. the order of rays can be undesirable.

It is possible to switch off such input checks when creating toric varieties. However, it must be emphasized that then it is the user's responsibility to provide sane input.

As an example, the following lines are executed internally to create the del Pezzo surface $dP_3$:

Notice the non_redundant = true entry in the constructor for NormalToricVariety. This switches off the input check by informing OSCAR that we (= the users) made sure that there is no redundancy in the input. It is encouraged to use this functionality with care and only after checking the input carefully.

To continue with the above example, we would like to see that this is indeed a del Pezzo surface. This can be seen directly from the fan - the three last rays correspond to the star subdivision of the 3 maximal cones of $\mathbb{P}^2$ - or by studying the properties of the variety in more detail. We opt for the latter and first assign suitable variable names:

It is also convenient to make a (valid!) standard choice for the grading of the cox ring. Namely, this must be such that the grading matrix corresponds to the map from the character lattice to the torus-invariant Weil divisor group. It is not too hard to verify that the following is a valid choice:

When executing del_pezzo_surface(3) more properties are set by OSCAR. But that put aside, the above are the internal steps of the constructor.

With that said, the following should identify this space as the del Pezzo surface $dP_3$:

4 Advanced topics¶

4.1 Vanishing sets¶

For (smooth, complete) and (simplicial, projective) toric varieties, it is possible to find a unified description for all line bundles for which a certain cohomology class vanishes. This set is then referred to as a vanishing set.

The first description of this approach can be found in appendix B of https://arxiv.org/pdf/1802.08860.pdf. The corresponding functionality is available in Oscar.

We begin by demonstrating this for the projective space $\mathbb{P}^2$, for which the vanishing sets are well-known. Namely: \begin{align} V^0( \mathbb{P}^2 ) &= \{ \mathcal{L} \in \mathrm{Pic}(\mathbb{P}^2) | h^0(\mathbb{P}^2, \mathcal{L}) = 0\} = \{ \mathcal{L} \in \mathrm{Pic}(\mathbb{P}^2) | \mathrm{deg}( \mathcal{L} ) < 0 \} \, , \\ V^1( \mathbb{P}^2 ) &= \{ \mathcal{L} \in \mathrm{Pic}(\mathbb{P}^2) | h^1(\mathbb{P}^2, \mathcal{L}) = 0\} = \mathrm{Pic}(\mathbb{P}^2) \, , \\ V^2( \mathbb{P}^2 ) &= \{ \mathcal{L} \in \mathrm{Pic}(\mathbb{P}^2) | h^2(\mathbb{P}^2, \mathcal{L}) = 0\} = \{ \mathcal{L} \in \mathrm{Pic}(\mathbb{P}^2) | \mathrm{deg}( \mathcal{L} ) > -2 \}\, . \end{align} Let us recompute this with OSCAR:

We are thus looking at $C = \mathrm{Span}_{\mathbb{Z}_{\geq 0}}(1) \}$. This cone is a subset of $\mathrm{Pic}( \mathbb{P}^2)$ and the vanishing set is its complement, that is: $$V^0( \mathbb{P}^2 ) = \{ \mathcal{L} \in \mathrm{Pic}(\mathbb{P}^2) | h^0(\mathbb{P}^2, \mathcal{L}) = 0\} = \{ \mathcal{L} \in \mathrm{Pic}(\mathbb{P}^2) | \mathcal{L} ) \notin C \} \, .$$ It is readily verified that this indeed matches the above expectation.

Recall that $V^1( \mathbb{P}^2 ) = \mathrm{Pic}(\mathbb{P}^2)$. This we can see quickly:

This list of polyhedra is empty. In other words, the vanishing set is the complement of the empty set in $\mathrm{Pic}( \mathbb{P}^2 )$, which is nothing but the entire Picard group.

Let us now look at the vanishing set for $h^2$:

We are thus looking at $P_3 = \{-3\} + \mathrm{Span}_{\mathbb{Z}_{\geq 0}} \{-1\}$. Its complement is $V^2( \mathbb{P}^2 )$, which matches our expectation.

Recall that we constructed a line bundle $\mathcal{L}$ on $\mathbb{P}^2$ above:

Its cohomologies are:

So $L$ is not $V^0( \mathbb{P}^2 )$ but in $V^1( \mathbb{P}^2 )$ and $V^2( \mathbb{P}^2 )$:

4.2 Intersection theory¶

Intersection theory for toric varieties is well-understood and the Chow ring under good control. For a good example, let us consider the del Pezzo surface $dP_2$:

Recall that this constructors invokes standard names for the homogeneous coordinates. This we can see upon execution of the Cox ring:

We now recall the toric ideal-variety correspondence from proposition 5.2.7 in the book "Toric Varieties" by David Cox, Hal Schenk and John Little:

Let $X_\Sigma$ be a simplicial toric variety. Then there is a bijective correspondence $$ \{ \text{ closed subvarieties of $X_\Sigma$ } \} \leftrightarrow \{ \text{ radical homogeneous ideals $I \subseteq B(\Sigma) \subseteq S$} \} \, .$$ In this expression $B(\Sigma)$ is the irrelevant ideal. For instance, for $\mathrm{dP}_2$ we have:

Consequently, for every radical homogeneous ideal $I \subseteq B(\Sigma) \subseteq S$, we find a closed subvariety $V( I ) \subseteq X_\Sigma$ and every closed subvariety of a simplicial toric variety $X_\Sigma$ arises in this way.

An algebraic cycle is a formal linear sum of such closed subvarieties. Modulo rational equivalence, the algebraic cycles furnish the Chow ring. We can compute this ring as follows in OSCAR:

There are several ways to create a rational equivalence class of an algebraic cycle. Here is one way to create such an object:

So $ac$ is represented by an algebraic cycle which in turn is given by a formal linear sum of the closed subvarieties $V(x_3)$, $V(e_1)$ and $V(e_2)$, namely $6 V(x_3) + 1 V( e_1 ) + 7 V( e_2 )$.

Intersections of rational equivalence classes can be computed in OSCAR:

If we only care about topological intersection numbers, then the intersection form suffices:

Note that this is obtained upon normalization with the volume form: