Package: lefschetz-family
lefschetz-familyDescriptionThis Sage package provides a means of efficiently computing periods of complex projective hypersurfaces and elliptic surfaces over $\mathbb P^1$ with certified rigorous precision bounds.
It implements the methods described inhttps://arxiv.org/abs/2306.05263.
Here is a runtime benchmark for various examples:Variety (generic)Time (on 10 M1 cores)Elliptic curve10 secondsQuartic curve8 minutesCubic surface3 minutesQuartic surface1 hour*Cubic threefold7 hours**for holomorphic periodsThis package is a successor to thenumperiodspackage by Pierre Lairez. It contains files taken from this package, that have sometimes been slightly modified to accomodate for new usage.How to installIn a terminal, runsage -pip install git+https://github.com/mkauers/ore_algebra.git
sage -pip install lefschetz-familyorsage -pip install --user git+https://github.com/mkauers/ore_algebra.git
sage -pip install --user lefschetz-familyAlternatively, install theore_alegbrapackage (available athttps://github.com/mkauers/ore_algebra), then download this repository and add the path to the main folder to yoursys.path.RequirementsSage 9.0 and above is recommended. Furthermore, this package has the following dependencies:Ore Algebra.Thedelaunay-triangulationpackage from PyPI.UsageHypersurfaceThe first step is to define the polynomial $P$ defining the projective hypersurface $X=V(P)$. For instance, the following gives the Fermat elliptic curve:R.<X,Y,Z>=PolynomialRing(QQ)P=X**3+Y**3+Z**3Then the following creates an object representing the hypersurface:fromlefschetz_familyimportHypersurfaceX=Hypersurface(P)The period matrix of $X$ is the simply given by:X.period_matrixThe module automatically uses available cores for computing numerical integrations and braids of roots. For this, the sage session needs to be made aware of the available cores. This can be done by adding the following line of code before launching the computation (replace10by the number of cores you want to use).os.environ["SAGE_NUM_THREADS"]='10'Seethe computation of the periods of the Fermat quartic surfacefor a detailed usage example.Copy-paste ready examplesThe Fermat elliptic curveos.environ["SAGE_NUM_THREADS"]='10'fromlefschetz_familyimportHypersurfaceR.<X,Y,Z>=PolynomialRing(QQ)P=X**3+Y**3+Z**3X=Hypersurface(P,nbits=1500)X.period_matrixA quartic K3 surface of Picard rank 3This one should take around 1 hour to compute, provided your computer has access to 10 cores.os.environ["SAGE_NUM_THREADS"]='10'fromlefschetz_familyimportHypersurfaceR.<W,X,Y,Z>=PolynomialRing(QQ)P=(2*X*Y^2*Z+3*X^2*Z^2+5*X*Y*Z^2-2*X*Z^3+2*Y*Z^3+Z^4+X^3*W-3*X^2*Y*W-X*Y^2*W+Y^3*W-2*X^2*Z*W-2*Y^2*Z*W-2*X*Z^2*W+2*Y*Z^2*W-X^2*W^2-X*Y*W^2-2*Y^2*W^2-2*X*Z*W^2+2*Y*W^3-W^4)*2+X^4-Y^4+Z^4-W^4fibration=[vector(ZZ,[10,-8,-2,7]),vector(ZZ,[1,-1,5,10]),vector(ZZ,[-5,7,7,10])]X=Hypersurface(P,nbits=1200,fibration=fibration)periods=X.holomorphic_periods_modificationfromlefschetz_family.numperiods.integerRelationsimportIntegerRelationsIR=IntegerRelations(X.holomorphic_periods_modification)# this is the rank of the transcendental latticetranscendental_rank=X.holomorphic_periods_modification.nrows()-IR.basis.rank()# The Picard rank is thusprint("Picard rank:",22-transcendental_rank)OptionsThe objectHypersurfacecan be called with several options:method("voronoi"by default/"delaunay"/"delaunay_dual"): the method used for computing a basis of homotopy.voronoiuses integration along paths in the voronoi graph of the critical points;delaunayuses integration along paths along the delaunay triangulation of the critical points;delaunay_dualpaths are along the segments connecting the barycenter of a triangle of the Delaunay triangulation to the middle of one of its edges. In practice,delaunayis more efficient for low dimension and low order varieties (such as degree 3 curves and surfaces, and degree 4 curves). This gain in performance is however hindered in higher dimensions because of the algebraic complexity of the critical points (which are defined as roots of high order polynomials, with very large integer coefficients)."delaunay"method is not working for nownbits(positive integer,400by default): the number of bits of precision used as input for the computations. If a computation fails to recover the integral  monodromy matrices, you should try to increase this precision. The output precision seems to be roughly linear with respect to the input precision.debug(boolean,Falseby default): whether coherence checks should be done earlier rather than late. We recommend setting to true only if the computation failed in normal mode.PropertiesThe objectHypersurfacehas several properties.
Fibration related properties, in positive dimension:fibration: a list of independant hyperplanes defining the iterative pencils. The first two element of the list generate the pencil used for the fibration.critical_values: the list critical values  of that map.basepoint: the basepoint of the fibration (i.e. a non critical value).fiber: the fiber above the basepoint as aHypersurfaceobject.fundamental_group: the class computing representants of the fundamental group of $\mathbb P^1$ punctured at the critical values.paths: the list of simple loops around each point ofcritical_values. When this is called, the ordering ofcritical_valueschanges so that the composition of these loops is the loop around infinity.family: the one parameter family corresponding to the fibration.Homology related properties:monodromy_matrices: the matrices of the monodromy action ofpathson $H_{n-1}(X_b)$.vanishing_cycles: the vanshing cycles at each point ofcritical_valuesalongpaths.thimbles: the thimbles of $H_n(Y,Y_b)$. They are represented by a starting cycle in $H_n(Y_b)$ and a loop in $\mathbb C$ avoidingcritical_valuesand pointed atbasepoint.kernel_boundary: linear combinations of thimbles with empty boundary.extensions: integer linear combinations of thimbles with vanishing boundary.infinity_loops: extensions around the loop at infinity.homology_modification: a basis of $H_n(Y)$.intersection_product_modification: the intersection product of $H_n(Y)$.fibre_class: the class of the fibre in $H_n(Y)$.section: the class of a section in $H_n(Y)$.thimble_extensions: couples(t, T)such thatTis the homology class in $H_n(Y)$ representing the extension of a thimble $\Delta \in H_{n-1}(X_b, X_{bb'})$ over all of $\mathbb P^1$, with $\delta\Delta =$t. Futhermore, thets define a basis of the image of the boundary map $\delta$.invariant: the intersection ofsectionwith the fibre above the basepoint, as a cycle in $H_{n-2}({X_b}_{b'})$.exceptional_divisors: the exceptional cycles coming from the modification $Y\to X$, given in the basishomology_modification.homology: a basis of $H_n(X)$, given as its embedding in $H_2(Y)$.intersection_product: the intersection product of $H_n(X)$.lift: a map taking a linear combination of thimbles with zero boundary (i.e. an element of $\ker\left(\delta:H_n(Y, Y_b)\to H_{n-1}(Y_b)\right)$) and returning the homology class of its lift in $H_2(Y)$, in the basishomology_modification.lift_modification: a map taking an element of $H_n(Y)$ given by its coordinates inhomology_modification, and returning its homology class in $H_n(X)$ in the basishomology.Cohomology related properties:cohomology: a basis of $PH^n(X)$, represented by the numerators of the rational fractions.holomorphic_forms: the indices of the forms incohomologythat form a basis of holomorphic forms.picard_fuchs_equation(i): the picard fuchs equation of the parametrization of i-th element ofcohomologyby the fibrationPeriod related propertiesperiod_matrix: the period matrix of $X$ in the aforementioned baseshomologyandcohomology, as well as the cohomology class of the linear section in even dimensionperiod_matrix_modification: the period matrix of the modification $Y$ in the aforementioned baseshomology_modificationandcohomologyholomorphic_periods: the periods ofholomorphic_formsin the basishomology.holomorphic_periods_modification: the periods of the pushforwards ofholomorphic_formsin the basishomology_modification.Miscellaneous properties:P: the defining equation of $X$.dim: the dimension of $X$.degree: the degree of $X$.ctx: the options of $X$, see related section above.The computation of the exceptional divisors can be costly, and is not always necessary. For example, the Picard rank of a quartic surface can be recovered withholomorphic_periods_modificationalone.EllipticSurfaceUsageThe defining equation for the elliptic surface should be given as a univariate polynomial over a trivariate polynomial ring. The coefficients should be homogeneous of degree $3$.R.<X,Y,Z>=PolynomialRing(QQ)S.<t>=PolynomialRing(R)P=X^2*Y+Y^2*Z+Z^2*X+t*X*Y*ZThen the following creates an object representing the hypersurface:fromlefschetz_familyimportEllipticSurfaceX=EllipticSurface(P)Copy-paste ready examplesNew rank records for elliptic curves having rational torsion, $\mathbb Z/2\mathbb Z$We recover the result of Section 9 ofNew rank records for elliptic curves having rational torsionby Noam D. Elkies and Zev Klagsbrun.os.environ["SAGE_NUM_THREADS"]='10'fromlefschetz_familyimportEllipticSurfaceR.<X,Y,Z>=QQ[]S.<t>=R[]U.<u>=S[]A=(u^8-18*u^6+163*u^4-1152*u^2+4096)*t^4+(3*u^7-35*u^5-120*u^3+1536*u)*t^3+(u^8-13*u^6+32*u^4-152*u^2+1536)*t^2+(u^7+3*u^5-156*u^3+672*u)*t+(3*u^6-33*u^4+112*u^2-80)B1=(u^2+u-8)*t+(-u+2)B3=(u^2-u-8)*t+(u^2+u-10)B5=(u^2-7*u+8)*t+(-u^2+u+2)B7=(u^2+5*u+8)*t+(u^2+3*u+2)B2=-B1(t=-t,u=-u)B4=-B3(t=-t,u=-u)B6=-B5(t=-t,u=-u)B8=-B7(t=-t,u=-u)P=-Y^2*Z+X^3+2*A*X^2*Z+product([B1,B2,B3,B4,B5,B6,B7,B8])*X*Z^2surface=EllipticSurface(P(5),nbits=1000)surface.mordell_weilK3 surfaces and sphere packingsThis example recovers the result ofK3 surfaces and sphere packingsby Tetsuji Shioda.os.environ["SAGE_NUM_THREADS"]='10'fromlefschetz_familyimportEllipticSurfaceR.<X,Y,Z>=PolynomialRing(QQ)S.<t>=PolynomialRing(R)# you may modify these parametersalpha=3beta=5n=3P=-Z*Y**2*t^n+X**3*t^n-3*alpha*X*Z**2*t**n+(t**(2*n)+1-2*beta*t**n)*Z^3surface=EllipticSurface(P,nbits=1500)# this is the Mordell-Weil latticesurface.mordell_weil_lattice# these are the types of the singular fibresfort,_,ninsurface.types:print(t+str(n)iftin['I','I*']elset)OptionsThe options are the same as those forHypersurface(see above).PropertiesThe objectEllipticSurfacehas several properties.
Fibration related properties, in positive dimension:critical_values: the list critical values  of that map.basepoint: the basepoint of the fibration (i.e. a non critical value).fiber: the fiber above the basepoint as aLefschetzFamilyobject.paths: the list of simple loops around each point ofcritical_points. When this is called, the ordering ofcritical_pointschanges so that the composition of these loops is the loop around infinity.family: the one parameter family corresponding to the fibration.Homology related properties:extensions: the extensions of the fibration.extensions_morsification: the extensions of the morsification of the fibration.homology: the homology of $X$.singular_components: a list of lists of combinations of thimbles of the morsification, such that the elements ofsingular_components[i]form a basis of the singular components of the fibre abovecritical_values[i]. To get their coordinates in the basishomology, useX.lift(X.singular_components[i][j]).fibre_class: the class of the fibre inhomology.section: the class of the zero section inhomology.intersection_product: the intersection matrix of the surface in the basishomology.morsify: a map taking a combination of extensions and returning its coordinates on the basis of thimbles of the morsification.lift: a map taking a combination of thimbles of the morsification with empty boundary and returning its class inhomology.types:types[i]is the type of the fibre abovecritical_values[i]. It is given as a triplet, M, nuwheretis the letter of the type of the fibre ('I','II', etc.),Mis the $\operatorname{SL}_2(\mathbb Z)$ matrices so thatM**(-1)*monodromy_matrices[i]*Mis the representative $M_T$ of the monodromy class (see Table 1. of the paper), andnuis the multiplicity of the fibre in the cases wheretis'I'or'I*'(otherwisenuis1).Cohomology related properties:holomorphic_forms: a basis of rational functions $f(t)$ such that $f(t) \operatorname{Res}\frac{\Omega_2}{P_t}\wedge\mathrm dt$ is a holomorphic form of $S$.picard_fuchs_equations: the list of the Picard-Fuchs equations of the holomorphic forms mentionned previously.Period related properties:period_matrix: the holomorphic periods of $X$ in the basesself.homologyandself.holomorphic_forms.effective_periods: the holomorphic periods $X$ in the basesself.effective_latticeandself.holomorphic_formsSublattices of homology. Unless stated otherwise, lattices are given by the coordinates of a basis of the lattice in the basishomology:effective_lattice: The lattice of effective cycles of $X$, consisting of the concatenation ofextensions,singular_components,fibre_classandsection.neron_severi: the Néron-Severi group of $X$.trivial: the trivial lattice.essential_lattice: the essential lattice.mordell_weil: the Mordell-Weil group of $X$, described as the quotient moduleneron_severi/trivial.mordell_weil_lattice: the intersection matrix of the Mordell-Weil lattice of $X$.Miscellaneous properties:ctx: the options of $X$, see related section above.ContactFor any question, bug or remark, please contacteric.pichon@polytechnique.edu.RoadmapNear future milestones:Encapsulate integration step in its own classCertified computation of the exceptional divisorsSaving time on differential operator by precomputing cache before parallelizationComputing periods of elliptic fibrations.Removing dependency onnumperiods.Middle term goals include:Making Delaunay triangulation functional againHaving own implementation of 2D voronoi graphs/Delaunay triangulationLong term goals include:Tackling cubic threefolds.Generic code for all dimensions.Computing periods of singular varieties.Computing periods of complete intersections.Computing periods of weighted projective hypersurfaces, notably double covers of $\mathbb P^2$ ramified along a cubic.Other directions include:Computation of homology through braid groups instead of monodromy of differential operators.Project statusThis project is actively being developped.