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 Eichler | Source | Authors |
|---|---|---|
Translated routines and their test values: the invariants and Mestre's reconstruction in genus2/mestre_port.py | mestre.py and invariants.py in SageMath | Florian 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.py | mestre.py | Bouyer and Streng, with Kunzweiler, Ma and Pope |
Calls that follow their code: the six transvectant calls of igusa_clebsch in Eichler.jl | g2_covariants.c in FLINT | Jean Kieffer |
Library calls: theta constants and invariants in Eichler.jl and theta9 | FLINT's acb_theta, through Arblib.jl | Jean Kieffer; algorithm by Noam D. Elkies and Jean Kieffer |
Formula from their data: the relation that defines third_kind_G | DiffRelationsEllipticFunctions.m in the Zenodo record doi:10.5281/zenodo.14733100 | Matteo Becchetti, Federico Coro, Christoph Nega, Lorenzo Tancredi and Fabian Wagner |
| New code for the mathematics of the papers listed below: the rest of Eichler | Source and references | Code 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:
- Modular. For $\Gamma_1(6)$, the curve of the equal-mass two-loop sunrise. The Hauptmodul $t(\tau)$ (the modular function that equals $p^2/m^2$) is inverted to the nome $q=e^{2\pi i\tau}$ by interval Newton iteration. The kernel forms are $q$-series with proved tail bounds, and words in them (ordered lists, one kernel per repeated integration) are integrated to any depth. The sunrise is assembled from them to all orders in $\varepsilon$.
- Curves. Periods of a quartic with exact coefficients, by contour quadrature and by complete-elliptic-integral (AGM) formulas, and a validated Taylor-series transport for any Fuchsian operator.
- Variation of parameters. The solution of an inhomogeneous elliptic system, moved from the cusp $q\to0$ to an interior point as $c_1+c_2\tau$ plus an Eichler integral of the source, with $c_1,c_2$ fitted from reference values.
- Constants. Dirichlet $L$-values for any primitive odd real character (conductor 3 gives $L(\chi_{-3},2)$, conductor 4 gives Catalan's constant), and named constant vectors at a cusp or an interior point.
- Calabi–Yau. For a Picard–Fuchs operatorthe linear differential operator in the kinematic variable that annihilates the period; order 2 for an elliptic curve, 3 for a K3 surface, 4 for a Calabi–Yau threefold of any order with a point of maximal unipotent monodromy (MUM point) at $z=0$: the Frobenius basis there, with exact rational coefficients. The basis is a power series plus partners carrying powers of $\log z$. From it come periods, their derivatives and the mirror map at any point, along a path you supply. The equal-mass banana operators at two, three and four loops and the four K3 and Calabi–Yau operators of post-Minkowskian black-hole scattering (arXiv:2401.07899) are built in.
- Genus two. For $y^2=f(x)$ of degree 5 or 6: the $2\times2$ period matrix by certified quadrature, and theta constants, Igusa invariants and Rosenhain and Thomae branch-point data through FLINT's
acb_theta.
tools/eichler/ holds three Python parts. The last bullet covers the two templates inside genus2:
theta9. Evaluates the squared genus-two theta constants and their ratios and pair products at a given period matrix as certified balls, optionally propagating a stated uncertainty in $\tau$.mirror6. For any D-finite operator with a MUM point, computes in exact rational arithmetic the logarithmic Frobenius chain, the mirror map $q(z)$ and its inverse, the Yukawa-type structure series and the instanton-type numbers.genus2. Decides which genus-two curve is behind a set of high-precision numbers.invariant_harness.pycompares the absolute invariants of candidate sextics, and of the curves obtained from each by a Richelot isogeny, with reference numerics at about 340 digits, with no integer-relation step.- Templates in
genus2. Two files,pslq_law_template.pyandexact_transport_driver.py, are templates to adapt, not to run as they are.
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:
- Inside the convergence disk at $z=0$ the Calabi–Yau series use an empirical tail estimate. Transport outside the disk is rigorous.
- Paths around singularities are the caller's choice.
siegel_transport, the genus-two analogue of the elliptic transport, is not implemented and raisesSiegelNotImplemented.theta9has no self-test of its own, andmirror6/run_l6.pyneeds an operator file that is not included in the repository.pslq_law_template.pyimports a period pipeline that you provide and stops with a message without it.exact_transport_driver.pyimports a system class (monodromy_transport.L5System) that you replace with your own.
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.
| Function | What it returns |
|---|---|
Gamma16(prec, N), kernel | The $\Gamma_1(6)$ layer with kernel $q$-series to order N; one kernel by name |
tau_from_t, nome_from_t | Maps from $t$ to $\tau$ and $q$, certified by interval Newton |
iterated_integral, iterated_integral_value | The iterated Eichler integral of a word, as a series or as a value with a rigorous remainder |
sunrise2, sunrise4, sunrise_boundary_constants, eps_coeff | The sunrise in $d=2-2\varepsilon$ and $4-2\varepsilon$, its cusp constants, one order of the result |
QuarticCurve, period_quadrature, curve_periods | Certified roots; a period by contour quadrature around a root pair; $(\psi_1,\psi_2)$ by AGM formulas |
abel_image, third_kind_G | Abel image and third-kind period for the built-in parent-curve family |
EllipticSector, eichler_transport, vop_assemble, vop_fit_constants | Sector 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_pf | An operator from exact coefficients; the banana operators for 2, 3 and 4 loops |
mum_frobenius_basis, period_vector, period_matrix, mirror_map | Frobenius basis at $z=0$; periods and derivatives at a point, optionally along path; the mirror map |
CYSector, cy_transport | Inhomogeneous transport between two points |
pm_k3_legendre, pm_cy3_4F3, pm_k3_apery, pm_cy3_hadamard | The four post-Minkowskian operators; pm_all_periods gives their periods |
chi_minus, dirichlet_L, clausen | The odd real character mod $N$, its $L$-values, Clausen values; dirichlet_L(chi_minus(4), 2, prec) is Catalan's constant |
cusp_dictionary, interior_dictionary | Name and value lists of constants for an integer-relation search, at a cusp or an interior point |
eisenstein_constants | Eisenstein constant terms at the cusps of $\Gamma_0(N)$ for $N=3,4,6$ |
HyperellipticCurve, period_matrix(C), abel_jacobi | The genus-two curve, its period matrix, the Abel–Jacobi map |
siegel_theta, igusa_invariants, igusa_clebsch, rosenhain_from_tau, thomae_sextic | Theta constants, invariants and branch points through FLINT |
siegel_rauch_de, siegel_gauss_manin | Derivatives 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.
| Command | What it does |
|---|---|
python3 theta9/theta9_stub.py --label L --tau "..." --outdir DIR | Writes 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.py | Candidate 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.py | An 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 DIR | The run at both special points of the order-6 operator file; it runs only after the control has passed |
python3 genus2/invariant_harness.py | Arbitrates between candidate sextics, with a two-frame self-check and a deliberately mismatched control built in |
python3 genus2/conic_fast.py | Runs 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.
| Function | What it returns |
|---|---|
transvect, clebsch_ABCD, clebsch_to_igusa, igusa_clebsch | Transvectants, and the Clebsch and Igusa–Clebsch invariants of a binary sextic in the module's symbols X, Y |
mestre_xyz, mestre_conic_matrix, mestre_cijk | Mestre's coordinates, conic and cubic |
curve_from_parametrization(x, y, z, F1, F2, F3, tvar) | The reconstructed curve |
Used on this site
- Equal-mass sunrise: evaluated the modular forms on $\Gamma_1(6)$, their Eichler integrals and the Dirichlet $L$-value constants.
- gg → Zγ with exact top-quark mass: the Eichler integral on $\Gamma_0(4)$ and the level-four Dirichlet $L$-values of the boundary data.
- Three-loop equal-mass banana: expansion of the K3 period and the logarithmic solutions at the MUM point, and their continuation in $t$.
- Light-by-light box with a sunrise insertion: periods, modular parameter and Eichler integral of the $\Gamma_1(6)$ sunrise curve at Euclidean virtuality.
- Three-loop banana at the mass threshold: transport of the period system from large momentum to the threshold and once around it.
- Four-loop banana at the mass threshold: transport of the period along the differential equation from the MUM point to the pseudo-threshold $t=0$.
Requirements
- Runs on: Julia 1.11 or newer with Arblib.jl (FLINT/Arb) and Nemo.jl for
Eichler.jl. The scripts need Python 3 with mpmath, plus gmpy2 formirror6and SymPy forgenus2. - Install: in
upgrades/Eichler.jl/runjulia --project=. -e 'using Pkg; Pkg.instantiate()'once; it installs the tested dependencies, which the committedManifest.tomlpins. Start Julia withjulia --project=.to run the examples. Forgenus2, puttools/onPYTHONPATHandimport eichler.genus2. - Self-test, Julia:
julia --project=. -e 'using Pkg; Pkg.test()'. - Self-test, Python:
python3 selftest.py --outdir <scratch>fromtools/eichler/takes about two seconds and ends with a line beginningeichler selftest: ALL PASS. It runs themirror6control, thegenus2checks and therun_l6.pyrefusal check, and reportstheta9as skipped. Its files go under--outdir, else under$EICHLER_WORK, else into a temporary directory.python3 genus2/selftest.pyruns thegenus2checks alone. theta9: also runs Julia in theEichler.jlproject, set withEICHLER_PROJECT(defaultupgrades/Eichler.jl).- Optional: the comparison program against GiNaC in
ginac-oracle/is compiled from source with itsbuild.shand needs GiNaC and CLN installed separately. The validation data of Becchetti, Coro, Nega, Tancredi and Wagner are fetched on demand by a script in the package and are not included.
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.
| Reference | What it supplies |
|---|---|
| L. Adams and S. Weinzierl, arXiv:1704.08895; L. Adams, C. Bogner and S. Weinzierl, arXiv:1504.03255 | Iterated integrals of modular forms, the all-orders sunrise and the conventions |
| M. Walden and S. Weinzierl, arXiv:2010.05271; GiNaC | The earlier public evaluation of these iterated integrals, in floating point; the cross-check |
| T. Ahmed, E. Chaubey, M. Kaur and S. Maggio, arXiv:2402.07311 | The 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.14733100 | The 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.08908 | The banana Calabi–Yau periods |
| A. Klemm, C. Nega, B. Sauer and J. Plefka, arXiv:2401.07899 | The four K3 and Calabi–Yau operators of post-Minkowskian scattering |
| J. Kieffer, arXiv:2203.02000; N. D. Elkies and J. Kieffer, arXiv:2505.22382; FLINT | The 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.06134 | The 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 SageMath | The 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) 936 | The reconstruction and its conventions |
| J. Igusa, Ann. Math. 72 (1960) 612 | The invariants |
| P. Candelas, X. de la Ossa, P. Green and L. Parkes, Nucl. Phys. B 359 (1991) 21 | The 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.09426 | The published numbers that the mirror6 control reproduces |
| P. Molin and C. Neurohr, arXiv:1707.07249 | An earlier public program, hcperiods, for certified period matrices of hyperelliptic curves |