[FTheoryTools] First steps towards hypersurface models

experimental/FTheoryTools/docs/doc.main

@@ -3,5 +3,6 @@
       "introduction.md",
       "weierstrass.md",
       "tate.md",
+      "hypersurface.md",
    ],
 ]

experimental/FTheoryTools/docs/src/hypersurface.md

@@ -0,0 +1,133 @@
+```@meta
+CurrentModule = Oscar
+```
+
+# 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``.
+
+[Reference Klevers F-theory on toric hypersurfaces...]
+
+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:
+```@docs
+hypersurface_model(base::AbstractNormalToricVariety; completeness_check::Bool = true)
+hypersurface_model(base::AbstractNormalToricVariety, fiber_ambient_space::AbstractNormalToricVariety, D1::ToricDivisorClass, D2::ToricDivisorClass; completeness_check::Bool = true)
+```
+
+### A toric scheme as base space
+
+For the same reasons as above, the toric base must be complete. Similar to toric varieties as
+bases, we can use the optional argument `completeness_check = false` to switch off the
+expensive completeness check. The following examples demonstrate this:
+```@docs
+hypersurface_model(base::ToricCoveredScheme; completeness_check::Bool = true)
+hypersurface_model(base::ToricCoveredScheme, fiber_ambient_space::ToricCoveredScheme, D1::ToricDivisorClass, D2::ToricDivisorClass; completeness_check::Bool = true)
+```
+
+### A (covered) scheme as base space
+
+This functionality does not yet exist.
+
+### Base space not specified
+
+This functionality does not yet exist.
+
+### Standard constructions
+
+We provide convenient constructions of hypersurface models over
+famous base spaces. Currently, we support the following:
+```@docs
+hypersurface_model_over_projective_space(d::Int)
+hypersurface_model_over_hirzebruch_surface(r::Int)
+hypersurface_model_over_del_pezzo_surface(b::Int)
+```
+
+
+## Attributes
+
+### Basic attributes
+
+For all hypersurface models -- irrespective over whether the base is toric or not -- we support
+the following attributes:
+```@docs
+hypersurface_equation(h::HypersurfaceModel)
+```
+One can also decide to specify a custom hypersurface equation:
+```@docs
+set_hypersurface_equation(h::HypersurfaceModel,, p::MPolyRingElem)
+```
+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:
+```@docs
+base_space(h::HypersurfaceModel)
+ambient_space(h::HypersurfaceModel)
+fiber_ambient_space(h::HypersurfaceModel)
+```
+The following method allows to tell if the base/ambient space is auxiliary or not:
+```@docs
+base_fully_specified(h::HypersurfaceModel)
+```
+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](http://www.thofma.com/Hecke.jl/dev/features/macros/).
+
+
+### Advanced attributes

experimental/FTheoryTools/src/FTheoryTools.jl

@@ -12,6 +12,11 @@ include("TateModels/properties.jl")
 include("TateModels/auxiliary.jl")
 include("TateModels/methods.jl")
 
+include("HypersurfaceModels/constructors.jl")
+include("HypersurfaceModels/attributes.jl")
+include("HypersurfaceModels/properties.jl")
+include("HypersurfaceModels/methods.jl")
+
 include("standard_constructions.jl")
 
 include("LiteratureTateModels/constructors.jl")

experimental/FTheoryTools/src/HypersurfaceModels/attributes.jl

@@ -0,0 +1,240 @@
+###################################################################
+###################################################################
+# 1: Attributes that work the same tor toric and non-toric settings
+###################################################################
+###################################################################
+
+
+#####################################################
+# 1.1 Hypersurface equation
+#####################################################
+
+@doc raw"""
+    hypersurface_equation(h::HypersurfaceModel)
+
+Return the hypersurface equation.
+
+```jldoctest
+julia> h = hypersurface_model_over_projective_space(2)
+Hypersurface model over a concrete base
+
+julia> hypersurface_equation(h);
+```
+"""
+hypersurface_equation(h::HypersurfaceModel) = h.hypersurface_equation
+
+
+#####################################################
+# 1.2 Base, ambient space and fiber ambient space
+#####################################################
+
+@doc raw"""
+    base_space(h::HypersurfaceModel)
+
+Return the base space of the hypersurface model.
+
+```jldoctest
+julia> h = hypersurface_model_over_projective_space(2)
+Hypersurface model over a concrete base
+
+julia> base_space(h)
+Scheme of a toric variety with fan spanned by RayVector{QQFieldElem}[[1, 0], [0, 1], [-1, -1]]
+```
+"""
+function base_space(h::HypersurfaceModel)
+  base_fully_specified(h) || @vprint :HypersurfaceModel 1 "Base space was not fully specified. Returning AUXILIARY base space.\n"
+  return h.base_space
+end
+
+
+@doc raw"""
+    ambient_space(h::HypersurfaceModel)
+
+Return the ambient space of the hypersurface model.
+
+```jldoctest
+julia> h = hypersurface_model_over_projective_space(2)
+Hypersurface model over a concrete base
+
+julia> ambient_space(h)
+Scheme of a toric variety with fan spanned by RayVector{QQFieldElem}[[1, 0, 0, 3], [0, 1, 0, 0], [-1, -1, 0, 0], [0, 0, -1, 1//3], [0, 0, 1, -1//2], [0, 0, 0, 1]]
+```
+"""
+function ambient_space(h::HypersurfaceModel)
+  base_fully_specified(h) || @vprint :HypersurfaceModel 1 "Base space was not fully specified. Returning AUXILIARY ambient space.\n"
+  return h.ambient_space
+end
+
+
+@doc raw"""
+    fiber_ambient_space(HypersurfaceModel)
+
+Return the fiber ambient space of the hypersurface model.
+
+```jldoctest
+julia> h = hypersurface_model_over_projective_space(2)
+Hypersurface model over a concrete base
+
+julia> fiber_ambient_space(h)
+Scheme of a toric variety with fan spanned by RayVector{QQFieldElem}[[-1, 1//3], [1, -1//2], [0, 1]]
+```
+"""
+fiber_ambient_space(h::HypersurfaceModel) = h.fiber_ambient_space
+
+
+
+
+#=
+###################################################################
+###################################################################
+# 2: Attributes that currently only works in toric settings
+###################################################################
+###################################################################
+
+
+#####################################################
+# 2.1 Calabi-Yau hypersurface
+#####################################################
+
+@doc raw"""
+    calabi_yau_hypersurface(t::GlobalTateModel)
+
+Return the Calabi-Yau hypersurface in the toric ambient space
+which defines the global Tate model.
+
+```jldoctest
+julia> t = literature_tate_model(arxiv_id = "1109.3454", equ_nr = "3.5")
+Global Tate model over a not fully specified base -- SU(5)xU(1) restricted Tate model based on arxiv paper 1109.3454 (equ. 3.5)
+
+julia> calabi_yau_hypersurface(t)
+Closed subvariety of a normal toric variety
+```
+"""
+@attr ClosedSubvarietyOfToricVariety function calabi_yau_hypersurface(t::GlobalTateModel)
+  @req typeof(base_space(t)) <: ToricCoveredScheme "Calabi-Yau hypersurface currently only supported for toric varieties/schemes as base space"
+  base_fully_specified(t) || @vprint :GlobalTateModel 1 "Base space was not fully specified. Returning hypersurface in AUXILIARY ambient space.\n"
+  return closed_subvariety_of_toric_variety(underlying_toric_variety(ambient_space(t)), [tate_polynomial(t)])
+end
+
+
+#####################################################
+# 2.2 Turn a Tate into a Weierstrass model
+#####################################################
+
+@doc raw"""
+    global_weierstrass_model(t::GlobalTateModel)
+
+Return the global Weierstrass model which is equivalent to the given Tate model.
+
+```jldoctest
+julia> t = literature_tate_model(arxiv_id = "1109.3454", equ_nr = "3.5")
+Global Tate model over a not fully specified base -- SU(5)xU(1) restricted Tate model based on arxiv paper 1109.3454 (equ. 3.5)
+
+julia> global_weierstrass_model(t)
+Global Weierstrass model over a not fully specified base
+```
+"""
+@attr GlobalWeierstrassModel function global_weierstrass_model(t::GlobalTateModel)
+  @req typeof(base_space(t)) <: ToricCoveredScheme "Conversion of global Tate model into global Weierstrass model is currently only supported for toric varieties/schemes as base space"
+  b2 = 4 * tate_section_a2(t) + tate_section_a1(t)^2
+  b4 = 2 * tate_section_a4(t) + tate_section_a1(t) * tate_section_a3(t)
+  b6 = 4 * tate_section_a6(t) + tate_section_a3(t)^2
+  f = - 1//48 * (b2^2 - 24 * b4)
+  g = 1//864 * (b2^3 - 36 * b2 * b4 + 216 * b6)
+  S = cox_ring(ambient_space(t))
+  x, y, z = gens(S)[ngens(S)-2:ngens(S)]
+  ring_map = hom(parent(f), S, gens(S)[1:ngens(parent(f))])
+  pw = x^3 - y^2 + ring_map(f)*x*z^4 + ring_map(g)*z^6
+  model = GlobalWeierstrassModel(f, g, pw, base_space(t), ambient_space(t))
+  set_attribute!(model, :base_fully_specified, base_fully_specified(t))
+  return model
+end
+
+
+#####################################################
+# 2.3 Discriminant and singular loci
+#####################################################
+
+@doc raw"""
+    discriminant(t::GlobalTateModel)
+
+Return the discriminant of the global Tate model.
+
+```jldoctest
+julia> t = literature_tate_model(arxiv_id = "1109.3454", equ_nr = "3.5")
+Global Tate model over a not fully specified base -- SU(5)xU(1) restricted Tate model based on arxiv paper 1109.3454 (equ. 3.5)
+
+julia> discriminant(t);
+```
+"""
+@attr MPolyRingElem function discriminant(t::GlobalTateModel)
+  @req typeof(base_space(t)) <: ToricCoveredScheme "Discriminant of global Tate model is currently only supported for toric varieties/schemes as base space"
+  return discriminant(global_weierstrass_model(t))
+end
+
+
+@doc raw"""
+    singular_loci(t::GlobalTateModel)
+
+Return the singular loci of the global Tate model, along with the order of
+vanishing of ``(f, g, \Delta)``` at each locus and the refined Tate fiber type.
+
+For the time being, we either explicitly or implicitly focus on toric varieties
+as base spaces. Explicitly, in case the user provides such a variety as base space,
+and implicitly, in case we work over a non-fully specified base. This has the
+advantage that we can "filter out" trivial singular loci.
+
+Specifically, recall that every closed subvariety of a simplicial toric variety is
+of the form ``V(I)``, where ``I`` is a homogeneous ideal of the Cox ring. Let ``B``
+be the irrelevant ideal of this toric variety. Then, by proposition 5.2.6. of
+[CLS11](@cite), ``V(I)`` is trivial/empty iff ``B^l \subseteq I`` for a suitable ``l \geq 0``.
+This can be checked by checking if the saturation ``I:B^\infty`` is the ideal generated by ``1``.
+
+By treating a non-fully specified base space implicitly as a toric space, we can extend this
+result straightforwardly to this situation also. This is the reason for constructing this
+auxiliary base space.
+
+Let us demonstrate the functionality by computing the singular loci of a Type ``III`` Tate model
+[KMSS11](@cite). In this case, we  will consider Global Tate model over a non-fully specified base.
+The Tate sections are factored as follows:
+- ``a_1 = a_{11} w^1``,
+- ``a_2 = a_{21} w^1``,
+- ``a_3 = a_{31} w^1``,
+- ``a_4 = a_{41} w^1``,
+- ``a_6 = a_{62} w^2``.
+For this factorization, we expect a singularity of Kodaira type ``III`` over the divisor
+``W = {w = 0}``, as desired. So this should be one irreducible component of the discriminant. Moreover,
+we should find that the discriminant vanishes to order 3 on ``W = {w = 0}``, while the Weierstrass
+sections ``f`` and ``g`` vanish to orders 1 and 2, respectively. Let us verify this.
+
+```jldoctest
+julia> auxiliary_base_ring, (a11, a21, a31, a41, a62, w) = QQ["a10", "a21", "a32", "a43", "a65", "w"];
+
+julia> a1 = a11 * w;
+
+julia> a2 = a21 * w;
+
+julia> a3 = a31 * w;
+
+julia> a4 = a41 * w;
+
+julia> a6 = a62 * w^2;
+
+julia> ais = [a1, a2, a3, a4, a6];
+
+julia> t = global_tate_model(ais, auxiliary_base_ring, 3)
+Global Tate model over a not fully specified base
+
+julia> length(singular_loci(t))
+2
+
+julia> singular_loci(t)[2]
+(ideal(w), (1, 2, 3), "III")
+```
+"""
+@attr Vector{<:Tuple{<:MPolyIdeal{<:MPolyRingElem}, Tuple{Int64, Int64, Int64}, String}} function singular_loci(t::GlobalTateModel)
+  @req typeof(base_space(t)) <: ToricCoveredScheme "Singular loci of global Tate model currently only supported for toric varieties/schemes as base space"
+  return singular_loci(global_weierstrass_model(t))
+end
+
+=#