Eichler

Eichler evaluates periods (integrals of $dx/y$ around closed cycles of the curve), iterated integrals of modular formsfunctions of $\tau$ on the upper half-plane that transform with a fixed weight under a congruence subgroup of SL(2,ℤ); they play the part that rational $d\log$ kernels play for polylogarithms (Eichler integrals, after Martin Eichler), Dirichlet $L$-valuesvalues at integer points of an $L$-series built from a periodic arithmetic character and transported solutions of differential equations. For elliptic curves, K3 and Calabi–Yau manifolds and genus-two curves these functions replace polylogarithms in Feynman integrals, and Eichler.jl returns each as an interval that provably contains the true value. Eichler.jl, the Julia core, was written for BootLoops from the formulas of Luise Adams and Stefan Weinzierl (arXiv:1704.08895) and the papers below; the Python module genus2 contains translated SageMath code.

Where it comes from

Luise Adams and Stefan Weinzierl wrote the equal-mass sunrise to all orders as iterated integrals of modular forms, and Eichler.jl is new code for their formulas. GiNaC, with the elliptic functions of Moritz Walden and Stefan Weinzierl (arXiv:2010.05271), already evaluates these integrals in floating point. Eichler.jl adds a proved error bound on each of these values and uses GiNaC as a cross-check. Some parts of Eichler come from other people's code or data.

Part of EichlerSourceAuthors
Translated routines and their test values: the invariants and Mestre's reconstruction in genus2/mestre_port.pymestre.py and invariants.py in SageMathFlorian Bouyer and Marco Streng; Nick Alexander; with Sabrina Kunzweiler, Gareth Ma and Giacomo Pope
Translated lines: Mestre's coordinates and conic matrix in genus2/conic_fast.pymestre.pyBouyer and Streng, with Kunzweiler, Ma and Pope
Calls that follow their code: the six transvectant calls of igusa_clebsch in Eichler.jlg2_covariants.c in FLINTJean Kieffer
Library calls: theta constants and invariants in Eichler.jl and theta9FLINT's acb_theta, through Arblib.jlJean Kieffer; algorithm by Noam D. Elkies and Jean Kieffer
Formula from their data: the relation that defines third_kind_GDiffRelationsEllipticFunctions.m in the Zenodo record doi:10.5281/zenodo.14733100Matteo Becchetti, Federico Coro, Christoph Nega, Lorenzo Tancredi and Fabian Wagner
New code for the mathematics of the papers listed below: the rest of EichlerSource and referencesCode by Claude

Please cite the authors' papers and programs when you use these parts. Eichler is not affiliated with or endorsed by the authors of SageMath, FLINT or GiNaC.

What it does

Past the polylogarithmic case, a Feynman integral is built from periods of a curve $y^2=P(x)$ ($P$ a cubic or quartic), the period ratio $\tau$, modular forms in $\tau$, and repeated $\tau$-integrals of those. An integer-relation search (PSLQ) for an exact formula needs these functions to many correct digits and a finite list of candidate constants.

You give Eichler.jl a curve, a modular form or a differential operator and a working precision. It works in ball arithmeticinterval arithmetic in which every number carries a rigorous error radius; here the Arb library inside FLINT throughout (Arb) and has six layers:

tools/eichler/ holds three Python parts. The last bullet covers the two templates inside genus2:

Every public function of Eichler.jl returns a ball whose truncation, quadrature and transport errors are bounded by proved inequalities, with the first two exceptions below. Eichler has these limits:

Ellipticus is the separate package for elliptic iterated integrals on a curve given only by an exact equation, with no modular parametrization assumed.

Examples

The equal-mass sunrise (package README). With the package set up (see Requirements), in the Julia project upgrades/Eichler.jl/: the $\Gamma_1(6)$ layer at 768 bits with $q$-series to order 700, then the sunrise in $d=4-2\varepsilon$ at $p^2/m^2=-1$ through $\varepsilon^7$.

using Eichler, Arblib
G = Gamma16(768, 700)                       # Γ₁(6) layer at 768 bits, q-order 700
S4 = sunrise4(G, Acb(-1; prec=768); J=10)   # sunrise, d=4-2ε, ε⁻²..ε⁷, certified

S4 is an EpsSeries with leading power $\varepsilon^{-2}$, and eps_coeff(S4, k) returns the coefficient of $\varepsilon^k$ as a complex ball. A sunrise with $+i0$ propagators is $-S_{111}$ in the conventions of docs/conventions.md. At 768 bits the enclosures carry roughly 135 correct digits per order, and the test suite compares this call with a separately computed value good to about 126 digits.

Periods of the three-loop banana (test/test_cy_transport.jl):

prec = 400
L3 = banana_pf(3; prec = prec)
frob = mum_frobenius_basis(L3, prec; nterms = 120)
z = Acb(1//100; prec)
Π = period_vector(L3, z, prec; frob = frob)

L3 is the order-3 operator with singularities at $0$, $1/16$, $1/4$, and the holomorphic solution in frob starts $1+4z+28z^2+256z^3+\dots$ (the Domb numbers), checked term by term in the test. Π holds $(\varpi_0,\varpi_1,\varpi_2)$ at $z=1/100$, with $\varpi_0$ compared against a separately computed 48-digit value. Outside the disk $|z|\lt1/16$, pass path = [...] to period_matrix or build a CYSector with an interior base point, as the four-loop test does.

Invariants of a genus-two curve with eichler.genus2 (genus2/selftest.py): the Igusa–Clebsch invariants of $y^2=x^6+x^5+x^4+x^2+2$, then the first step of Mestre's reconstruction. Run with tools/ on PYTHONPATH.

from eichler.genus2 import mestre_port as g2

X, Y = g2.X, g2.Y                                        # the module's two homogeneous variables
f = X**6 + X**5*Y + X**4*Y**2 + X**2*Y**4 + 2*Y**6       # the sextic, homogenized
I2, I4, I6, I10 = g2.igusa_clebsch(f)                    # (-496, 6220, -955932, -1111784)
x, y, z = g2.mestre_xyz(I2, I4, I6, I10)
L = g2.mestre_conic_matrix(x, y, z)                      # symmetric 3x3 matrix of Mestre's conic

igusa_clebsch returns $(I_2,I_4,I_6,I_{10})$ as exact SymPy numbers, here the integers that the self-test checks against SageMath's values. mestre_xyz converts them to Mestre's three coordinates, and mestre_conic_matrix gives the conic. Its rational points, when it has any, lead to a model of the curve through mestre_cijk and curve_from_parametrization; conic_fast.py finds such a point over a quadratic field. Keep the inputs exact: pass SymPy integers or rationals, as igusa_clebsch returns them. Plain Python integers would be divided in floating point inside mestre_xyz.

Routines

The Julia module is loaded with using Eichler.

FunctionWhat it returns
Gamma16(prec, N), kernelThe $\Gamma_1(6)$ layer with kernel $q$-series to order N; one kernel by name
tau_from_t, nome_from_tMaps from $t$ to $\tau$ and $q$, certified by interval Newton
iterated_integral, iterated_integral_valueThe iterated Eichler integral of a word, as a series or as a value with a rigorous remainder
sunrise2, sunrise4, sunrise_boundary_constants, eps_coeffThe sunrise in $d=2-2\varepsilon$ and $4-2\varepsilon$, its cusp constants, one order of the result
QuarticCurve, period_quadrature, curve_periodsCertified roots; a period by contour quadrature around a root pair; $(\psi_1,\psi_2)$ by AGM formulas
abel_image, third_kind_GAbel image and third-kind period for the built-in parent-curve family
EllipticSector, eichler_transport, vop_assemble, vop_fit_constantsSector descriptor, transport of a source series, assembly of $c_1+c_2\tau+\int S$, the fit of $(c_1,c_2)$; MultiEllipticSector for several curves
PFOperator, banana_pfAn operator from exact coefficients; the banana operators for 2, 3 and 4 loops
mum_frobenius_basis, period_vector, period_matrix, mirror_mapFrobenius basis at $z=0$; periods and derivatives at a point, optionally along path; the mirror map
CYSector, cy_transportInhomogeneous transport between two points
pm_k3_legendre, pm_cy3_4F3, pm_k3_apery, pm_cy3_hadamardThe four post-Minkowskian operators; pm_all_periods gives their periods
chi_minus, dirichlet_L, clausenThe odd real character mod $N$, its $L$-values, Clausen values; dirichlet_L(chi_minus(4), 2, prec) is Catalan's constant
cusp_dictionary, interior_dictionaryName and value lists of constants for an integer-relation search, at a cusp or an interior point
eisenstein_constantsEisenstein constant terms at the cusps of $\Gamma_0(N)$ for $N=3,4,6$
HyperellipticCurve, period_matrix(C), abel_jacobiThe genus-two curve, its period matrix, the Abel–Jacobi map
siegel_theta, igusa_invariants, igusa_clebsch, rosenhain_from_tau, thomae_sexticTheta constants, invariants and branch points through FLINT
siegel_rauch_de, siegel_gauss_maninDerivatives of $\tau$ with respect to a branch point and along a one-parameter family

The cusp lists hold powers of $\pi$, logarithms, zeta and $L$-values and polylogarithms at sixth roots of unity. The interior lists hold periods and the third-kind period. The other exports are listed in src/Eichler.jl.

The scripts are in tools/eichler/, and the paths below are relative to that directory.

CommandWhat it does
python3 theta9/theta9_stub.py --label L --tau "..." --outdir DIRWrites OBSERVABLES_<label>_cand<k>.json: the certified squared even theta constants, ratios and pair products, with their consistency checks
theta9/theta9_frame.py, theta9/theta9_copair.pyCandidate period matrices from a marked-frame period point; agreement checks at two precisions and with the values in theta9/fixtures/
theta9/theta9_scan.py, theta9/theta9_cert_residuals.pyAn integer-relation scan of the theta ratios using lockpick; certified residual enclosures of the relations found
python3 mirror6/run_control.py --outdir <scratch>The positive control: the quintic operator and Rødland's operator against published mirror-map and instanton numbers, 28 boolean checks
python3 mirror6/run_l6.py --l6 PATH --outdir DIRThe run at both special points of the order-6 operator file; it runs only after the control has passed
python3 genus2/invariant_harness.pyArbitrates between candidate sextics, with a two-frame self-check and a deliberately mismatched control built in
python3 genus2/conic_fast.pyRuns the worked example over $\mathbb{Q}(\sqrt{409})$ and writes conic_point.json or conic_obstruction.json to the current directory
python3 exact_transport_driver.py <re> <im> <tag> [dps] [column]Template, run inside genus2/: transport from the base point whose real and imaginary parts are given as fractions n/d

--tau takes the string "t11re,t11im,t12re,t12im,t22re,t22im"; --pi-json FILE:key --gram-json FILE:key may replace it. The options --g, --prec-bits and --tau-rad set the genus, the precision and the uncertainty in $\tau$. mirror6/mirror6.py is the importable engine. It obtains the instanton-type numbers from the series by Lambert-series inversion, each with an integrality verdict.

invariant_harness.py reads the reference file named by G2KIT_TRUE_JSON (or EICHLER_GENUS2_TRUE_JSON): a JSON file whose leg1 entry holds rosenhain, three complex strings at roughly 370 digits. Without the variable it stops and prints the required layout.

pslq_law_template.py lays out an integer-relation run with three controls. An algebraic number inserted on purpose must be recovered, a random number of the same size must give nothing, and a repeat at a second precision must give the same relations. exact_transport_driver.py transports a differential equation with Wayfinder from an exact rational base point. A base point given as a decimal spoils a later integer-relation search; a dyadic or rational one does not.

The genus2 module is loaded with from eichler.genus2 import mestre_port, with tools/ on PYTHONPATH, or with import mestre_port from its directory. Run as a script, mestre_port.py prints its values beside SageMath's documented ones.

FunctionWhat it returns
transvect, clebsch_ABCD, clebsch_to_igusa, igusa_clebschTransvectants, and the Clebsch and Igusa–Clebsch invariants of a binary sextic in the module's symbols X, Y
mestre_xyz, mestre_conic_matrix, mestre_cijkMestre's coordinates, conic and cubic
curve_from_parametrization(x, y, z, F1, F2, F3, tvar)The reconstructed curve

Used on this site

Requirements

Source and references

The code is upgrades/Eichler.jl/ and tools/eichler/ in the BootLoops repository. tools/eichler/NOTICE carries the SageMath authors' notice for mestre_port.py. The licenses of the parts are listed on the credits page.

ReferenceWhat it supplies
L. Adams and S. Weinzierl, arXiv:1704.08895; L. Adams, C. Bogner and S. Weinzierl, arXiv:1504.03255Iterated integrals of modular forms, the all-orders sunrise and the conventions
M. Walden and S. Weinzierl, arXiv:2010.05271; GiNaCThe earlier public evaluation of these iterated integrals, in floating point; the cross-check
T. Ahmed, E. Chaubey, M. Kaur and S. Maggio, arXiv:2402.07311The non-planar two-loop family
M. Becchetti, F. Coro, C. Nega, L. Tancredi and F. J. Wagner, arXiv:2502.00118; Zenodo doi:10.5281/zenodo.14733100The validation data and the relation that defines third_kind_G
K. Bönisch, F. Fischbach, A. Klemm, C. Nega and R. Safari, arXiv:2008.10574; S. Pögel, X. Wang and S. Weinzierl, arXiv:2212.08908The banana Calabi–Yau periods
A. Klemm, C. Nega, B. Sauer and J. Plefka, arXiv:2401.07899The four K3 and Calabi–Yau operators of post-Minkowskian scattering
J. Kieffer, arXiv:2203.02000; N. D. Elkies and J. Kieffer, arXiv:2505.22382; FLINTThe genus-two theta functions (acb_theta) and g2_covariants.c
F. Johansson, Arb, arXiv:1611.02831; Arblib.jl by M. Kaluba, J. Dahne and contributors; Nemo, arXiv:1705.06134The ball arithmetic and the exact arithmetic
F. Bouyer and M. Streng, mestre.py; N. Alexander, invariants.py; with S. Kunzweiler, G. Ma and G. Pope; in SageMathThe code that mestre_port.py translates, and its test values
J.-F. Mestre, Progr. Math. 94 (1991) 313; K. Lauter and T. Yang, J. Number Theory 131 (2011) 936The reconstruction and its conventions
J. Igusa, Ann. Math. 72 (1960) 612The invariants
P. Candelas, X. de la Ossa, P. Green and L. Parkes, Nucl. Phys. B 359 (1991) 21The mirror map and instanton numbers
D. van Straten, arXiv:1704.00164; Almkvist, van Enckevort, van Straten and Zudilin, arXiv:math/0507430; Bönisch et al., arXiv:2203.09426The published numbers that the mirror6 control reproduces
P. Molin and C. Neurohr, arXiv:1707.07249An earlier public program, hcperiods, for certified period matrices of hyperelliptic curves

← back to the tools index