# Hypersurface models

## Introduction

A hypersurface model describes a particular form of an elliptic fibration. For now, we consider such models in toric settings only, that is we restrict to a toric base space $B$ and assume that the generic fiber is a hypersurface in a 2-dimensional toric fiber ambient space $F$.

In addition, we shall assume that the first two homogeneous coordinates of $F$ transform in the divisor classes $D_1$ and $D_2$ over the base $B$ of the elliptic fibration. The remaining coordinates of $F$ are assumed to transform in the trivial bundle over $B$. See Denis Klevers, Damian Kaloni Mayorga Pena, Paul-Konstantin Oehlmann, Hernan Piragua, Jonas Reuter (2015) for more details.

Given this set of information, it is possible to compute a toric ambient space $A$ for the elliptic fibration. The elliptic fibration is then a hypersurface in this toric space $A$. Furthermore, since we assume that this fibration is Calabi-Yau, it is clear that the hypersurface equation is a (potentially very special) section of the $\overline{K}_A$. This hypersurface equation completes the information required about a hypersurface model.

## Constructors

We aim to provide support for hypersurface models over the following bases:

- a toric variety,
- a toric scheme,
- a (covered) scheme.

[Often, one also wishes to obtain information about a hypersurface model without explicitly specifying the base space. Also for this application, we provide support.]

Finally, we provide support for some standard constructions.

Before we detail these constructors, we must comment on the constructors over toric base spaces. Namely, in order to construct a hypersurface model, we first have to construct the ambient space in question. For a toric base, one way to achieve this is by means of triangulations. However, this is a rather time consuming and computationally challenging task, which leads to a huge number of ambient spaces. Even more, typically one wishes to only pick one of thees many ambient spaces. For instance, a common and often appropriate choice is a toric ambient space which contains the toric base space in a manifest way.

To circumvent this very demanding computation, our constructors operate in the opposite direction. That is, they begin by extracting the rays and maximal cones of the chosen toric base space. Subsequently, those rays and cones are extended to form one of the many toric ambient spaces. This proves hugely superior in performance than going through the triangulation task of enumerating all possible toric ambient spaces. One downside of this strategy is that the so-constructed ambient space need not be smooth.

### A toric variety as base space

We require that the provided toric base space is complete. This is a technical limitation as of now. The functionality of OSCAR only allows us to compute a section basis (or a finite subset thereof) for complete toric varieties. In the future, this could be extended.

Completeness is an expensive check. Therefore, we provide an optional argument which one can use to disable this check if desired. To this end, one passes the optional argument `completeness_check = false`

as last argument to the constructor. The following examples demonstrate this:

`hypersurface_model`

— Method`hypersurface_model(base::NormalToricVariety; completeness_check::Bool = true)`

Construct a hypersurface model. This constructor takes $\mathbb{P}^{2,3,1}$ as fiber ambient space with coordinates $[x:y:z]$ and ensures that $x$ transforms as $2 \overline{K}_{B_3}$ and $y$ as $3 \overline{K}_{B_3}$.

**Examples**

```
julia> base = projective_space(NormalToricVariety, 2)
Normal, non-affine, smooth, projective, gorenstein, fano, 2-dimensional toric variety without torusfactor
julia> hypersurface_model(base; completeness_check = false)
Hypersurface model over a concrete base
```

`hypersurface_model`

— Method`hypersurface_model(base::NormalToricVariety, fiber_ambient_space::NormalToricVariety, D1::ToricDivisorClass, D2::ToricDivisorClass; completeness_check::Bool = true)`

Construct a hypersurface model, for which the user can specify a fiber ambient space as well as divisor classes of the toric base space, in which the first two homogeneous coordinates of the fiber ambient space transform.

**Examples**

```
julia> base = projective_space(NormalToricVariety, 2)
Normal, non-affine, smooth, projective, gorenstein, fano, 2-dimensional toric variety without torusfactor
julia> fiber_ambient_space = weighted_projective_space(NormalToricVariety, [2,3,1])
Normal, non-affine, simplicial, projective, 2-dimensional toric variety without torusfactor
julia> set_coordinate_names(fiber_ambient_space, ["x", "y", "z"])
julia> D1 = 2 * anticanonical_divisor_class(base)
Divisor class on a normal toric variety
julia> D2 = 3 * anticanonical_divisor_class(base)
Divisor class on a normal toric variety
julia> hypersurface_model(base, fiber_ambient_space, D1, D2; completeness_check = false)
Hypersurface model over a concrete base
```

### A (covered) scheme as base space

This functionality does not yet exist.

### Base space not specified

This method constructs a hypersurface model over a base space, where this base space is not (fully) specified. We currently provide the following constructors:

`hypersurface_model`

— Method`hypersurface_model(auxiliary_base_vars::Vector{String}, auxiliary_base_grading::Matrix{Int64}, d::Int, fiber_ambient_space::NormalToricVariety, D1::Vector{Int64}, D2::Vector{Int64}, p::MPolyRingElem; toric_sample = true)`

This method constructs a hypersurface model over a base space that is not fully specified. In the background, we construct an auxiliary toric base space. This method requires the following information:

- The names of the homogeneous coordinates of the auxiliary toric base space.
- The grading of the Cox ring of the auxiliary toric base space.
- The weights corresponding to the divisor class
`D_1`

of the auxiliary toric base space under which the first fiber coordinate transforms. - The weights corresponding to the divisor class
`D_2`

of the auxiliary toric base space under which the first fiber coordinate transforms. - The dimension of the auxiliary toric base space.
- The fiber ambient space.
- The hypersurface equation.

Note that many studies in the literature use the class of the anticanonical bundle in their analysis. We anticipate this by adding this class as a variable of the auxiliary base space, unless the user already provides this grading. Our convention is that the first grading refers to Kbar and that the homogeneous variable corresponding to this class carries the name "Kbar".

The following example exemplifies this constructor.

**Examples**

```
julia> auxiliary_base_vars = ["a1", "a21", "a32", "a43", "a65", "w"]
6-element Vector{String}:
"a1"
"a21"
"a32"
"a43"
"a65"
"w"
julia> auxiliary_base_grading = [1 2 3 4 6 0; 0 -1 -2 -3 -5 1]
2×6 Matrix{Int64}:
1 2 3 4 6 0
0 -1 -2 -3 -5 1
julia> D1 = [4,0]
2-element Vector{Int64}:
4
0
julia> D2 = [6,0]
2-element Vector{Int64}:
6
0
julia> d = 3
3
julia> fiber_ambient_space = weighted_projective_space(NormalToricVariety, [2,3,1])
Normal, non-affine, simplicial, projective, 2-dimensional toric variety without torusfactor
julia> set_coordinate_names(fiber_ambient_space, ["x", "y", "z"])
julia> auxiliary_ambient_ring, (a1, a21, a32, a43, a65, w, x, y, z) = QQ["a1", "a21", "a32", "a43", "a65", "w", "x", "y", "z"]
(Multivariate polynomial ring in 9 variables over QQ, QQMPolyRingElem[a1, a21, a32, a43, a65, w, x, y, z])
julia> p = x^3 - y^2 - x * y * z * a1 + x^2 * z^2 * a21 * w - y * z^3 * a32 * w^2 + x * z^4 * a43 * w^3 + z^6 * a65 * w^5
-a1*x*y*z + a21*w*x^2*z^2 - a32*w^2*y*z^3 + a43*w^3*x*z^4 + a65*w^5*z^6 + x^3 - y^2
julia> h = hypersurface_model(auxiliary_base_vars, auxiliary_base_grading, d, fiber_ambient_space, D1, D2, p)
Assuming that the first row of the given grading is the grading under Kbar
Hypersurface model over a not fully specified base
julia> h = hypersurface_model(auxiliary_base_vars, auxiliary_base_grading, d, fiber_ambient_space, D1, D2, p; toric_sample = false)
Assuming that the first row of the given grading is the grading under Kbar
Hypersurface model over a not fully specified base
```

### Standard constructions

We provide convenient constructions of hypersurface models over famous base spaces. Currently, we support the following:

`hypersurface_model_over_projective_space`

— Method`hypersurface_model_over_projective_space(d::Int)`

This method constructs a hypersurface model over the projective space.

**Examples**

```
julia> hypersurface_model_over_projective_space(2)
Hypersurface model over a concrete base
```

`hypersurface_model_over_hirzebruch_surface`

— Method`hypersurface_model_over_hirzebruch_surface(r::Int)`

This method constructs a hypersurface model over a Hirzebruch surface.

**Examples**

```
julia> hypersurface_model_over_hirzebruch_surface(1)
Hypersurface model over a concrete base
```

`hypersurface_model_over_del_pezzo_surface`

— Method`hypersurface_model_over_del_pezzo_surface(b::Int)`

This method constructs a hypersurface model over a del-Pezzo surface.

**Examples**

```
julia> hypersurface_model_over_del_pezzo_surface(3)
Hypersurface model over a concrete base
```

## Attributes

### Basic attributes

For all hypersurface models – irrespective over whether the base is toric or not – we support the following attributes:

`hypersurface_equation`

— Method`hypersurface_equation(h::HypersurfaceModel)`

Return the hypersurface equation.

```
julia> h = hypersurface_model_over_projective_space(2)
Hypersurface model over a concrete base
julia> hypersurface_equation(h);
```

One can also decide to specify a custom hypersurface equation:

`set_hypersurface_equation`

— Method`set_hypersurface_equation(h::HypersurfaceModel, p::MPolyRingElem)`

Set the hypersurface equation to a custom value.

```
julia> h = hypersurface_model_over_projective_space(2)
Hypersurface model over a concrete base
julia> R = parent(hypersurface_equation(h));
julia> new_poly = gens(R)[4]^3
x^3
julia> set_hypersurface_equation(h, new_poly);
```

The fiber ambient space can be accessed via

`fiber_ambient_space`

— Method`fiber_ambient_space(HypersurfaceModel)`

Return the fiber ambient space of the hypersurface model.

```
julia> h = hypersurface_model_over_projective_space(2)
Hypersurface model over a concrete base
julia> fiber_ambient_space(h)
Normal, non-affine, simplicial, projective, 2-dimensional toric variety without torusfactor
```

In case the hypersurface model is constructed over a not fully specified base, recall that we construct an auxiliary (toric) base space as well as an auxiliary (toric) ambient space. The (auxiliary) base and ambient space can be accessed with the following functions:

`base_space`

— Method`base_space(h::HypersurfaceModel)`

Return the base space of the hypersurface model.

```
julia> h = hypersurface_model_over_projective_space(2)
Hypersurface model over a concrete base
julia> base_space(h)
Normal, non-affine, smooth, projective, gorenstein, fano, 2-dimensional toric variety without torusfactor
```

`ambient_space`

— Method`ambient_space(h::HypersurfaceModel)`

Return the ambient space of the hypersurface model.

```
julia> h = hypersurface_model_over_projective_space(2)
Hypersurface model over a concrete base
julia> ambient_space(h)
Normal toric variety without torusfactor
```

The following method allows to tell if the base/ambient space is auxiliary or not:

`base_fully_specified`

— Method`base_fully_specified(h::HypersurfaceModel)`

Return `true`

is the hypersurface model has a concrete base space and `false`

otherwise.

```
julia> h = hypersurface_model_over_projective_space(2)
Hypersurface model over a concrete base
julia> base_fully_specified(h)
true
```

The user can decide to get an information whenever an auxiliary base space, auxiliary ambient space or auxiliary hypersurface have been computed. To this end, one invokes `set_verbosity_level(:HypersurfaceModel, 1)`

. More background information is available here.

### Attributes in toric settings

If the base space of the hypersurface model is a toric space, then we also provide a special type for the Calabi-Yau hypersurface:

`calabi_yau_hypersurface`

— Method`calabi_yau_hypersurface(h::HypersurfaceModel)`

Return the Calabi-Yau hypersurface in the toric ambient space which defines the hypersurface model.

```
julia> h = hypersurface_model_over_projective_space(2)
Hypersurface model over a concrete base
julia> calabi_yau_hypersurface(h)
Closed subvariety of a normal toric variety
```

### Attributes based on the corresponding global Tate and Weierstrass models

Currently, we do not provide functionality to convert a hypersurface model into a Weierstrass or global Tate model. Still, for some constructions this might be known or detailed in the literature. If the user wishes, one can then associate a corresponding Weierstrass or global Tate model as follows:

`set_weierstrass_model`

— Method`set_weierstrass_model(h::HypersurfaceModel, w::WeierstrassModel)`

Allows to define the Weierstrass model corresponding to the hypersurface model.

`set_global_tate_model`

— Method`set_global_tate_model(h::HypersurfaceModel, w::GlobalTateModel)`

Allows to define the global Tate model corresponding to the hypersurface model.

These models can then be accessed with the following functions:

`weierstrass_model`

— Method`weierstrass_model(h::HypersurfaceModel)`

Return the Weierstrass model corresponding to the hypersurface model, provided that the latter is known.

`global_tate_model`

— Method`global_tate_model(h::HypersurfaceModel)`

Return the global Tate model corresponding to the hypersurface model, provided that the latter is known.

Provided that the corresponding Weierstrass model is known for a hypersurface model, the following functionality is available. It returns the attribute in question of the corresponding Weierstrass model.

`discriminant`

— Method`discriminant(h::HypersurfaceModel)`

Return the discriminant of the hypersurface model.

`singular_loci`

— Method`singular_loci(h::HypersurfaceModel)`

Return the singular loci of the hypersurface model, along with the order of vanishing of the Weierstrass sections and discriminant $(f, g, \Delta)$` at each locus. Also the refined Tate fiber type is returned.