Ellipticus

The content on this page was written by AI under human supervision.

Ellipticus, from "elliptic" with the Latin ending -icus, "belonging to": a certified evaluator for elliptic polylogarithms. It computes elliptic multiple polylogarithms and other iterated integrals on an elliptic curve to a requested number of digits. The input is an exact curve or a one-parameter family of curves $y^2=F(x;z)$, cubic or quartic in $x$ with coefficients rational in $z$, together with a word of integration letters, an evaluation point and a precision. "Certified" means that every value comes back with evidence produced during the run that its digits are right to that precision. Where a value comes from a truncated $q$-series the evidence is a proven bound on the dropped tail; where it comes from transporting a differential equation it is a per-step estimate of the discarded Taylor tail that stops the run with an error when it is too large (fail-closed, not a proven bound); and the wrapper evaluate adds agreement between two working precisions and, where two methods exist, between the methods. The package is written by BootLoops in Python.

What it does

When a Feynman integral is controlled by an elliptic curve rather than by rational functions, as for the two-loop sunrise with three different masses, its answer is written in elliptic multiple polylogarithmsiterated integrals whose kernels live on an elliptic curve (equivalently on a torus) instead of being rational functions with simple poles; the elliptic analogue of ordinary polylogarithms and related iterated integrals on the curve. Turning a high-precision number into an exact formula by an integer-relation search (PSLQ), or checking a proposed formula against an independent value, needs these functions to many digits with a trustworthy error statement. Ellipticus supplies them for any curve given exactly, without requiring the curve to be modular; the modular case, where the kernels are modular forms, belongs to Eichler.

The main engine, march, works with the window moments of a family and with words built on them. For an exact window $[x_1,x_2]$ the moments are

$$ I_k(z) \;=\; \int_{x_1}^{x_2} \frac{x^k\,dx}{\sqrt{F(x;z)}}\,, \qquad k=0,1,2,\dots $$

and a word $[a_w,\dots,a_2,(\mathrm{mom},k)]$ stands for the iterated integral of the letters $d\log(z-a_j)$, outermost first, ending on $I_k$, taken from the base point $z=0$ to the evaluation point; the notation is general, but this version evaluates words with at most one letter over the moment. Ellipticus builds the exact first-order differential system that the moments satisfy in $z$ (an inhomogeneous Picard–Fuchs systemthe linear differential equations in the family parameter obeyed by period-like integrals of the curve) by polynomial algebra alone, with no integration-by-parts reduction. It then extends the system by the letters of the requested words and integrates it from $z=0$ to the requested points by adaptive Taylor steps. At $z=0$ the family must degenerate to a perfect square or a square times a linear factor, so that the starting values are exact series. Every step estimates the discarded Taylor tail from the last three computed terms, with the step held to a tenth of the distance to the nearest singularity or letter, and stops with an error if the estimate exceeds $10^{-(\text{working digits}-8)}$; this is a fail-closed check, not a proven remainder bound. Singular points of the system are passed by detours through complex waypoints.

A second engine, qengine, evaluates the Kronecker–Eisenstein kernels $g^{(n)}(z,\tau)$ and iterated integrals of them in $\tau$ as $q$-series with a proven bound on the dropped tail; g_n_certified returns the value together with that bound. Near the edge of the region where the series converges it switches to a theta-function route and certifies by agreement of the two routes instead, returning the measured difference as the bound. The same engine carries the closed forms of the unequal-mass two-loop sunrise at order $\varepsilon^0$, $E^{(0)}(t)$ and $J^{(0)}(t)$, in the conventions of Bogner, Müller-Stach and Weinzierl, at any Euclidean $t$, with the equal-mass case as an independent classical check. A third layer, curve, handles one exact quartic: its roots and real ovals, the periods $\oint dx/y$ by complete elliptic integrals (Legendre/AGM) and by quadrature, the cycle moments $\oint x^k\,dx/y$, and cycles around a complex-conjugate pair of roots with the square-root branch tracked explicitly. Two further parts are included in the package. ellred reduces a one-variable elliptic integral $\int R(x)\,dx/\sqrt{P(x)}$, with $P$ cubic or quartic and $R$ rational, to Legendre's $F$, $E$, $\Pi$ plus algebraic terms, with a Carlson-form route as a cross-check and every reduction compared with direct quadrature. gmtel derives the exact Picard–Fuchs operator of a K3 pencil's periods from a Weierstrass model by the Gauss–Manin connection and creative telescoping, and returns the telescoping certificate beside the operator.

Inputs are exact rationals everywhere (integers, Fractions or strings); a float is refused with an error at the interface, because a rounded coefficient defines a different curve. The working precision is passed on every call and the ambient mpmath precision is never left changed. The wrapper evaluate runs any of the package's calls at two precisions and reports the number of digits they share. Limits: the $d\log z$ letter (a letter at $a=0$) is allowed only in the outermost position, where it is regularized; words with more than one $d\log$ letter over the moment, and starting bases other than the $z=0$ chart, raise NotImplementedError in this version rather than return a guess; transport onto a singular endpoint is not bridged: the step control shrinks toward it and the march stops on its assertion (an AssertionError, not NotImplementedError). Words in modular forms for $\Gamma_1(6)$ with interval enclosures go to Eichler; the equal-mass kite's $\overline{E}$ functions are not implemented here.

Examples

Run the self-test and the reference comparison. From tools/ellipticus/:

python3 selftest.py
python3 battery.py

The self-test prints four PASS lines in about fifteen seconds: quartic periods by the Legendre route against quadrature and against the closed form $4K(1/4)$; the differential system built for the bundled demonstration quartic matching a stored exact copy string for string; the march moments against independent quadrature in $x$; and the Kronecker–Eisenstein kernel by three routes with the tail bound covering the measured truncation error, plus the equal-mass sunrise check. battery.py is the longer comparison (about twenty seconds) against independent reference values included in fixtures/battery/: moments and words of two synthetic families against quadrature of the defining integrals, a half-period against $2K(1/4)$ and cycle moments against quadrature, complex-pair contour cycles against a branch-cut segment integral, the unequal-mass sunrise against stored reference points, and every ellred reduction class against quadrature. It writes a JSON summary to the file named by ELLIPTICUS_BATTERY_OUT and exits nonzero on any failure; add --pilot for a quick low-precision pass.

A quartic period (selftest.py): the real-oval period of $y^2=(1-x^2)(1-x^2/4)$, which equals $4K(1/4)$ in the parameter convention $m=k^2=1/4$.

from fractions import Fraction
from ellipticus import QuarticCurve, evaluate
cur = QuarticCurve([Fraction(1, 4), 0, Fraction(-5, 4), 0, 1])
v, meta = cur.period_oval(50, oval=0)
evaluate(lambda dps: cur.period_oval(dps, oval=0)[0], 30)

Coefficients are exact and in descending powers of $x$. v is $\oint dx/y$ around the oval on $(-1,1)$ at 50 digits, beginning 6.7430014192, and meta records the route taken ('legendre_K') and the modulus used; the self-test requires agreement with 4*mp.ellipk(1/4) to within 8 digits of the 50 requested (its independent quadrature check runs on other quartics). The last line is the two-precision wrapper: it runs the call at 30 and at 50 digits and returns a dictionary with value, lo, hi and shared_digits, the number of digits on which the two runs agree.

Moments and a word on a family (the demonstration family of selftest.py): $F(x;z)=x^2(x+1)^2-zx$ on the window $[1/4,1/2]$, evaluated at $z=1/5$ to 40 digits.

from fractions import Fraction
from ellipticus import MomentFamily
fam = MomentFamily(['1', '2', '1', '-z', '0'], window=(Fraction(1, 4), Fraction(1, 2)), kmax=2, param='z')
pf  = fam.polyform()
res = fam.eval_words([[('mom', 0)], [-1, ('mom', 1)]], [Fraction(1, 5)], 40)
res['1/5']['kernels'], res['1/5']['words']

The coefficients are strings in the parameter, descending in $x$; at $z=0$ this family is the perfect square $x^2(x+1)^2$, which is what makes it a valid starting chart. polyform() returns the exact $5\times5$ system for $(I_0,I_1,I_2)$ and the two boundary states as integer polynomial data (n, Den, NumM, and den_factors, the denominator factors from which the transport reads the singular points), the object the self-test compares with its stored copy. eval_words transports from $z=0$ to each endpoint in the list and returns a dictionary keyed by endpoint; under 'kernels' are $I_0(1/5)$, $I_1(1/5)$, $I_2(1/5)$, the first beginning 0.6271461255, and under 'words' the value of $\int_0^{1/5} d\log(z+1)\, I_1(z)$, beginning 0.0362504723. Direct quadrature of the defining integrals reproduces all four numbers; that comparison, on this family and on a cubic one, is what the reference comparison automates. A letter that lies on the transport path is a singularity of the extended system, so choose waypoints (waypoints=[...]) around it or expect the step control to stop.

Routines

Front end (from ellipticus import ... with tools/ on PYTHONPATH)

Kronecker–Eisenstein kernels and the sunrise (from ellipticus import qengine)

ellred: reduction to standard elliptic integrals (from ellipticus import ellred)

gmtel: Picard–Fuchs operators of K3 pencils

Tests and environment

Used on this site

Requirements and source

Python 3.10 or newer with mpmath, sympy and python-flint (gmtel also needs numpy). Nothing is compiled; the supporting Kronecker–Eisenstein and sunrise engines are included under vendor/ and the reference data under fixtures/. Run python3 selftest.py and python3 battery.py from tools/ellipticus/. The code is tools/ellipticus/ in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai), released under the MIT license.

Conventions and credit: the Kronecker–Eisenstein kernels and $\tau$-iterated integrals follow C. Bogner, S. Müller-Stach and S. Weinzierl (arXiv:1907.01251) and L. Adams and S. Weinzierl (arXiv:1704.08895); elliptic multiple polylogarithms in the sense of F. Brown and A. Levin (arXiv:1110.6917) and of J. Broedel, C. Duhr, F. Dulat, B. Penante and L. Tancredi (arXiv:1712.07089, arXiv:1803.10256); independent numerics were compared with the GiNaC implementation of M. Walden and S. Weinzierl (arXiv:2010.05271) where it applies. The certification layers are BootLoops'. Related pages: Eichler (modular forms, their iterated integrals and Calabi–Yau periods in interval arithmetic), GPLEval (ordinary polylogarithms), Wayfinder (transport of a stored differential equation; Ellipticus builds its own), Famhar (whole-family evaluation, which sends elliptic blocks here), Nestor (the quadrature used as the independent reference).

← back to the tools index