Eichler

Eichler is BootLoops' library for the special functions that replace polylogarithms when a Feynman integral is controlled by an elliptic curve, a K3 or Calabi–Yau manifold, or a genus-two curve. You give it a curve, a modular form or a differential operator and a working precision. It returns periods, iterated integrals of modular forms (Eichler integrals, after Martin Eichler), Dirichlet $L$-values and transported solutions of differential equations, each as an interval that provably contains the true value. The core is the Julia package Eichler.jl. The directory tools/eichler/ holds three Python parts that are described here too: the theta9 and mirror6 scripts and the genus2 module (eichler.genus2), which identifies a genus-two curve from its invariants. The separate Python package empl_eval (elliptic iterated integrals from an exact curve) is covered here as well.

What it does

Past the polylogarithmic case, a Feynman integral is built from periods of a curve (integrals of $dx/y$ around closed cycles on $y^2=P(x)$, $P$ a cubic or quartic), the period ratio $\tau$, 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 in $\tau$, and repeated $\tau$-integrals of those. An integer-relation search (PSLQ) that turns a high-precision value into an exact formula needs these functions to many correct digits and a finite list of candidate constants; Eichler.jl supplies both, in ball arithmeticinterval arithmetic in which every number carries a rigorous error radius; here the Arb library inside FLINT throughout (Arb).

The modular layer is built for $\Gamma_1(6)$, the curve of the equal-mass two-loop sunrise. It inverts the Hauptmodul $t(\tau)$ (the modular function that equals the kinematic variable $p^2/m^2$) to the nome $q=e^{2\pi i\tau}$ by interval Newton iteration and holds the kernel forms as $q$-series with proved tail bounds. Words in these kernels (ordered lists, one kernel per repeated integration) are integrated to any depth, and the sunrise is assembled to all orders in $\varepsilon$. The curve layer computes the periods of a quartic with exact coefficients two independent ways (contour quadrature with the square-root branch fixed explicitly, and complete-elliptic-integral/AGM formulas) and carries a validated Taylor-series transport engine for any Fuchsian operator. The variation-of-parameters layer moves the solution of an inhomogeneous elliptic system from the cusp $q\to0$ to an interior point as $c_1+c_2\tau$ plus an Eichler integral of the source, fitting $c_1,c_2$ from reference values. The constants layer evaluates Dirichlet $L$-values for any primitive odd real character (conductor 3 gives $L(\chi_{-3},2)$, conductor 4 gives Catalan's constant) and returns named constant vectors at a cusp or an interior point.

The Calabi–Yau layer takes 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 at $z=0$ and builds the Frobenius basis there (a power series plus partners carrying powers of $\log z$) with exact rational coefficients. From it the layer evaluates periods, their derivatives and the mirror map at any point, transporting along a path you supply. The equal-mass banana operators at two, three and four loops are built in, as are the four K3 and Calabi–Yau operators of post-Minkowskian black-hole scattering (arXiv:2401.07899). The genus-two layer takes $y^2=f(x)$ of degree 5 or 6, computes the $2\times2$ period matrix by certified quadrature, and wraps FLINT's acb_theta for theta constants, Igusa invariants and Rosenhain and Thomae branch-point data. Two script sets in tools/eichler/ sit on top of these layers. 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$) and writes them as JSON for a later integer-relation search. mirror6 takes any D-finite operator with a point of maximal unipotent monodromy and 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 obtained from it by Lambert-series inversion, with an integrality verdict for each.

The third part of tools/eichler/, the genus2 module (imported as eichler.genus2; SymPy and mpmath, no Sage), decides which genus-two curve sits behind a set of high-precision numbers. It computes the Clebsch and Igusa–Clebsch invariants of a binary sextic and carries out Mestre's reconstruction of a curve from its invariants, both checked exactly against SageMath's published test values. It arbitrates between candidate sextics by comparing their absolute invariants, together with those of the curves obtained from each by a Richelot isogeny, against reference numerics at about 340 digits, with no integer-relation step anywhere. It also carries an exact point search on a conic over a quadratic number field, the step Mestre's construction ends with, and two templates meant to be adapted rather than run as they are. One lays out an integer-relation recognition run together with its controls: a known algebraic number inserted on purpose that must be recovered, a random number of the same size that must give nothing, and a repeat at a second precision whose relations must match the first. The other transports a differential equation with Wayfinder from an exact rational base point, because a base point given as a decimal spoils a later integer-relation search while a dyadic or rational one does not.

Every public function of Eichler.jl returns a ball whose truncation, quadrature and transport errors are bounded by proved inequalities, with two stated exceptions. Inside the convergence disk at $z=0$ the Calabi–Yau series use an empirical tail estimate (transport outside the disk is rigorous), and paths around singularities are the caller's choice. siegel_transport, the genus-two analogue of the elliptic transport, is a placeholder that raises SiegelNotImplemented. On one core, NUMERICS-RESULTS.md lists about 11 s for the sunrise through $\varepsilon^7$ at 100 digits and 60 to 100 s at 500 digits, seconds for a period by quadrature, milliseconds by AGM.

empl_eval handles other curves, in Python with mpmath. The input is an exact family $y^2=F(x;z)$ (cubic or quartic in $x$, rational in $z$), an exact window $[x_1,x_2]$, a word of $d\log$ letters ending in a moment kernel $I_k(z)=\int_{x_1}^{x_2}x^k\,dx/\sqrt F$, a point and a digit count. It builds the differential system for the moments exactly and integrates it by adaptive Taylor steps, raising an error if a step's tail bound is violated. It also evaluates Kronecker–Eisenstein kernels $g^{(n)}(z,\tau)$ with a proved tail bound, the unequal-mass sunrise at order $\varepsilon^0$ (conventions of arXiv:1907.01251), and periods and cycle moments of an exact quartic. Inputs must be exact rationals; floats are refused. Two subpackages extend it: ellred reduces one-variable elliptic integrals $\int R(x)\,dx/\sqrt{P(x)}$ ($P$ cubic or quartic, $R$ rational) to Legendre $F$, $E$, $\Pi$ and Carlson forms, each reduction checked against direct quadrature, and gmtel derives the exact Picard–Fuchs operator of a K3 pencil's periods from a Weierstrass model by Gauss–Manin creative telescoping, returning the certificate alongside the operator.

Examples

The equal-mass sunrise (package README): 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 an independent evaluation 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$; 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 an independent 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.

A quartic period with empl_eval (empl_eval/selftest.py): the real-oval period of $y^2=(1-x^2)(1-x^2/4)$, equal to $4K(1/4)$.

from fractions import Fraction
from empl_eval import QuarticCurve
dps = 50
cur = QuarticCurve([Fraction(1, 4), 0, Fraction(-5, 4), 0, 1])
v1, m1 = cur.period_oval(dps, oval=0)

Coefficients are exact and descending. v1 is $\oint dx/y$ around the oval on $(-1,1)$ at 50 digits and m1 records the route taken ("legendre_K"); the self-test requires agreement with 4*mp.ellipk(1/4) and with an independent quadrature to within 8 digits of the working precision.

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 the self-test checks against SageMath. mestre_xyz converts them to Mestre's three coordinates and mestre_conic_matrix gives the conic whose rational points, when it has any, lead to a model of the curve through mestre_cijk and curve_from_parametrization; finding such a point over a quadratic field is what conic_fast.py does. Keep the inputs exact: pass SymPy integers or rationals as igusa_clebsch returns them, since plain Python integers would be divided in floating point inside mestre_xyz.

Routines

Eichler.jl: modular layer and sunrise

• Gamma16(prec, N), kernel(G, name) — the $\Gamma_1(6)$ layer with kernel $q$-series to order N; one kernel by name.
• tau_from_t, nome, nome_from_t, nome_and_log_from_t, hauptmodul_point — maps between $t$, $\tau$ and $q$, the inverse certified by interval Newton.
• iterated_integral(letters), iterated_integral_value(letters, q, logq) — iterated Eichler integral of a word, as a series or evaluated with a rigorous remainder.
• sunrise2(G, t; J), sunrise4(G, t; J), sunrise_boundary_constants(prec, J), eps_coeff(S, k) — the sunrise in $d=2-2\varepsilon$ and $4-2\varepsilon$, its cusp constants, one order of the result.

Eichler.jl: curves and elliptic transport

• QuarticCurve(coeffs, prec), period_quadrature(C, pair), curve_periods(C) — certified roots; a period by contour quadrature around a root pair; $(\psi_1,\psi_2)$ by AGM formulas.
• frobenius_transport_acm, picard_fuchs_residual_acm, abel_image, third_kind_G — transport, residual check, Abel image and third-kind period for the built-in parent-curve family.
• EllipticSector, tau_map, eichler_transport, vop_assemble, vop_fit_constants, vop_quadrature — sector descriptor, $\tau(t)$, cusp-regularized transport of a source series, assembly of $c_1+c_2\tau+\int S$, the fit of $(c_1,c_2)$, a certified quadrature fallback; MultiEllipticSector, multi_eichler_transport, multi_vop_assemble do the same for several curves at once.

Eichler.jl: Calabi–Yau operators

• PFOperator(prec, coeffs), theta_form, pf_from_theta, banana_pf(nloops; prec) — an operator from exact coefficients, its $\theta$-form and back, the banana operators for 2, 3, 4 loops.
• mum_frobenius_basis, period_vector, period_matrix, period_matrix_certified, mirror_map — Frobenius basis at $z=0$, periods and derivatives at a point (optionally along path), the mirror map.
• CYSector, cy_transport(sec, source, z_start, z_end) — inhomogeneous transport between two points.
• pm_k3_legendre, pm_cy3_4F3, pm_k3_apery, pm_cy3_hadamard, pm_all_periods, frobenius_basis, frobenius_wronskian, holo_period_closed, pf_residual — the four post-Minkowskian operators and their periods.

Eichler.jl: constants

• chi_minus(N), dirichlet_L(chi, s, prec), clausen — the odd real character mod $N$ as a value vector, its $L$-values through the Hurwitz zeta function (dirichlet_L(chi_minus(4), 2, prec) is Catalan's constant), Clausen values.
• cusp_dictionary(prec; maxweight, conductors), interior_dictionary(s, t, prec), eisenstein_constants, cusp_constant_E_k_chi — name/value lists of constants (powers of $\pi$, logarithms, zeta and $L$-values, polylogarithms at sixth roots of unity; periods and the third-kind period at an interior point) whose midpoints go straight into an integer-relation search; Eisenstein constant terms at the cusps of $\Gamma_0(N)$ for $N=3,4,6$.

Eichler.jl: genus two

• HyperellipticCurve, hyper_big_period_matrix, period_matrix(C), abel_jacobi — the curve, its period matrices, the Abel–Jacobi map.
• siegel_theta, siegel_theta_all, siegel_char, igusa_invariants, igusa_clebsch, igusa_absolute, rosenhain_from_tau, thomae_sextic — theta constants, invariants and branch points through FLINT.
• siegel_rauch_de, siegel_gauss_manin, Genus2Sector — derivatives of $\tau$ with respect to a branch point and along a one-parameter family, and the family descriptor; siegel_transport is the placeholder noted above.

tools/eichler: theta9, mirror6 and the package self-test (Python and Julia)

• python3 selftest.py [--outdir <scratch>], run from tools/eichler/ — every part's tests in one command: the mirror6 control described below, the genus2 checks, a check that mirror6/run_l6.py refuses without its operator file, and theta9 reported as skipped (it has no self-test of its own); about two seconds. Everything written goes under --outdir, else under $EICHLER_WORK, else into a temporary directory.
• python3 theta9/theta9_stub.py --label L --tau "t11re,t11im,t12re,t12im,t22re,t22im" [--g 2] [--prec-bits 320] [--tau-rad 1e-48] --outdir DIR, or with --pi-json FILE:key --gram-json FILE:key in place of --tau — writes OBSERVABLES_<label>_cand<k>.json with the certified squared even theta constants, ratios and pair products and their consistency checks; it runs theta9_theta.jl (julia --project=<Eichler.jl project> theta9_theta.jl in.txt out.json) in the project named by EICHLER_PROJECT.
• theta9/theta9_frame.py, theta9/theta9_copair.py, theta9/theta9_scan.py, theta9/theta9_cert_residuals.py — a marked-frame period point to a list of candidate period matrices; two-precision and reference-value agreement checks (reference values in theta9/fixtures/); 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 for mirror6 (the quintic operator and Rødland's operator, which has two such points, against published mirror-map and instanton numbers; 28 boolean checks, under a second); mirror6/mirror6.py is the importable engine.
• python3 mirror6/run_l6.py --l6 PATH --outdir DIR — the fingerprint run at both special points of an order-6 operator file that is not included in the repository; it refuses with a message without that file and runs only after the control has passed.

empl_eval (Python)

• MomentFamily(coeffs_x_desc, window, kmax, param) with .polyform() and .eval_words(words, endpoints, dps, waypoints=None) — the moment-system engine (moment_system, analytic_seed_series, System underneath).
• QuarticCurve(coeffs) with .period_oval, .cycle_moments, .cycle_pair_contour, .real_ovals; sunrise_frame; exact — the exact-curve period layer.
• qengine.g_n_certified(n, z, tau, dps), qengine.g_tail_bound, qengine.sunrise_E0(t, masses_sq, dps), qengine.sunrise_J, qengine.sunrise_equal_mass_control(t, dps), qengine.tau_word_frame, qengine.tau_words — a Kronecker–Eisenstein kernel returned with its proved bound, the bound alone, the unequal-mass sunrise at $\varepsilon^0$ and its equal-mass check, the frame and evaluation of $\tau$-iterated words.
• evaluate(verb, dps, extra=20), shared_digits(a, b) — run a callable at two precisions and report the shared digits.
• ellred (from empl_eval import ellred; modules ellred_engine, ellred_cubic, ellred_reduce, ellred_1r2c, ellred_carlson, ellred_kernels, ell_normal), PYTHONPATH=<tools dir> python3 -m empl_eval.ellred.derive_atoms — Legendre/Carlson reduction of one-variable elliptic integrals (quartic chart and $F$/$E$/$\Pi$ atoms, cubic moments, an $x$-space reducer, a Carlson-route cross-check); the script re-derives and verifies the closed-form atoms.
• gmtel (famgen_pf_routeA, famgen_pf_routeB, famgen_common), python3 tools/empl_eval/gmtel/gmtel_selftest.py [--pilot] — exact Picard–Fuchs operators of K3 pencil periods by the geometric telescoper and by a series-annihilator fit, and the check of both routes against the packaged reference operator (FAMGEN_L5, FAMGEN_TOOLS override the defaults).
• PYTHONPATH=<tools dir> python3 -m empl_eval.selftest, python3 -m empl_eval.battery [--pilot] — self-test and the longer reference comparison (results written to the file named by EMPL_BATTERY_OUT).

eichler.genus2: identifying a genus-two curve (Python; tools/eichler/genus2/, formerly the separate genus2kit package)

• mestre_port (from eichler.genus2 import mestre_port with tools/ on PYTHONPATH, or import mestre_port from the directory) — transvect(f, g, k), clebsch_ABCD(f6), clebsch_to_igusa(A, B, C, D), igusa_clebsch(f6), mestre_xyz(I2, I4, I6, I10), mestre_conic_matrix(x, y, z), mestre_cijk(x, y, z), curve_from_parametrization(x, y, z, F1, F2, F3, tvar): transvectants, Clebsch and Igusa–Clebsch invariants of a binary sextic in the module's symbols X, Y, and Mestre's conic, cubic and curve reconstruction; run as a script it prints its values beside SageMath's documented ones.
• invariant_harness.py — python3 genus2/invariant_harness.py with G2KIT_TRUE_JSON (or EICHLER_GENUS2_TRUE_JSON) naming your reference file, {"leg1": {"rosenhain": [three complex strings]}} at roughly 370 digits; arbitration between candidate sextics by absolute invariants and the Richelot orbit at 340-digit working precision, with a two-frame self-check and a deliberately mismatched control built in. Without the variable it stops and prints the required file layout.
• conic_fast.py — python3 genus2/conic_fast.py runs the worked example in exact arithmetic over $\mathbb{Q}(\sqrt{409})$: congruence diagonalization of the conic's matrix and a point search, writing conic_point.json or conic_obstruction.json to the current directory.
• pslq_law_template.py, exact_transport_driver.py — the two templates: the integer-relation recognition run with its inserted-element, random-number and second-precision controls, which imports a period pipeline you provide and stops with a message without it; and python3 exact_transport_driver.py <re> <im> <tag> [dps] [column], transport with Wayfinder from the exact base point whose real and imaginary parts are given as fractions n/d, which imports a system class (monodromy_transport.L5System) that you replace with your own.
• selftest.py — python3 genus2/selftest.py from tools/eichler/ (or python3 selftest.py in the directory) runs the four checks: invariants and Mestre conic against the SageMath values, the conic example with its diagonalization re-checked exactly, and the two templates' refusals. Scratch goes under $EICHLER_WORK when set.

Used on this site

• Sunrise — the $\Gamma_1(6)$ modular forms, Eichler integrals and cusp boundary constants of the closed form.
• gg → Zγ — the general Dirichlet-$L$ constant list for the conductor-4 curve, where Catalan's constant is the weight-two generator.
• Banana — K3 period transport through the logarithmic tower with cy_transport.
• Three-loop light-by-light — the $\Gamma_1(6)$ layer for the sunrise master integral inside this diagram.

Requirements and source

Eichler.jl needs Julia 1.11 or newer with Arblib.jl (FLINT/Arb) and Nemo.jl; the committed Manifest.toml pins the tested dependencies (Pkg.instantiate()), and julia --project=. -e 'using Pkg; Pkg.test()' runs the tests. It lives at upgrades/Eichler.jl/ in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai), released under the MIT license; the optional comparison program against GiNaC in the same directory is compiled from source with its build.sh and needs GiNaC and CLN installed separately. The theta9 and mirror6 scripts are at tools/eichler/ (Python 3 with mpmath; mirror6 needs gmpy2; theta9 also runs Julia in the Eichler.jl project, set with EICHLER_PROJECT, default upgrades/Eichler.jl); the genus2 module is at tools/eichler/genus2/ (Python 3 with sympy and mpmath; import eichler.genus2 with tools/ on PYTHONPATH). One command, python3 selftest.py --outdir <scratch> from tools/eichler/, runs the mirror6 control, the genus2 checks and the run_l6.py refusal check and reports theta9, which has no self-test of its own, as skipped; python3 genus2/selftest.py runs the genus2 checks alone. empl_eval is Python 3 with mpmath and sympy (gmtel also needs python-flint and numpy), at tools/empl_eval/ (import with tools/ on PYTHONPATH; self-test PYTHONPATH=<tools dir> python3 -m empl_eval.selftest, reference comparison python3 -m empl_eval.battery).

← back to the tools index