Ellipticus

Ellipticus (from "elliptic" with the Latin ending -icus, "belonging to") computes 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 other iterated integrals on an elliptic curve to a requested number of digits. It is meant for Feynman integrals controlled by an elliptic curve, and every value comes back with evidence, produced during the run, that its digits are right. The package is written by BootLoops in Python; the kernels and iterated integrals of its $q$-seriespower series in $\bar q=e^{2\pi i\tau}$, where $\tau$ is the ratio of the two periods of the curve part are written from the paper of C. Bogner, S. Müller-Stach and S. Weinzierl (arXiv:1907.01251).

What it does

When a Feynman integral is controlled by an elliptic curve, as for the two-loop sunrise with three different masses, its answer is written in elliptic multiple polylogarithms and related iterated integrals on the curve. Fitting an exact formula by an integer-relation search (PSLQ), or checking a proposed one, needs these functions to many digits with a trustworthy error statement. Ellipticus supplies them for any curve given exactly, modular or not. The modular case, where the kernels are modular forms, belongs to Eichler.

The input is an exact curve or a one-parameter family $y^2=F(x;z)$, cubic or quartic in $x$ with coefficients rational in $z$, with a word of integration letters, an evaluation point and a precision. Every number in the input is an exact rational (an integer, a Fraction or a string). A float is refused with an error, because a rounded coefficient defines a different curve.

The evidence returned with a value depends on how the value was computed:

Ellipticus has five parts. The main part, 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 $$

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. march works in three steps.

The other four parts are the following.

Ellipticus has these limits:

Related tools: GPLEval covers ordinary polylogarithms. Wayfinder transports a stored differential equation; Ellipticus builds its own. Famhar evaluates whole families and sends elliptic blocks to Ellipticus. Nestor is the quadrature used as the reference in the checks.

Examples

The self-test and the reference comparison. With the package set up (see Requirements), run both from the package directory tools/ellipticus/:

python3 selftest.py
python3 battery.py

The self-test prints four PASS lines in about fifteen seconds. battery.py is the longer comparison (about twenty seconds) against reference values included in fixtures/battery/. It writes a JSON summary to the file named by ELLIPTICUS_BATTERY_OUT and exits nonzero on any failure.

A quartic period (selftest.py). The real-oval period of $y^2=(1-x^2)(1-x^2/4)$ equals $4K(1/4)$ in the parameter convention $m=k^2=1/4$. Coefficients are exact and in descending powers of $x$:

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)

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. The last line 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 is $F(x;z)=x^2(x+1)^2-zx$ on the window $[1/4,1/2]$, evaluated here at $z=1/5$ to 40 digits. The coefficients are strings in the parameter, descending in $x$:

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']

polyform() returns the exact $5\times5$ system for $(I_0,I_1,I_2)$ and the two boundary states. Under 'kernels' are $I_0(1/5)$, $I_1(1/5)$, $I_2(1/5)$, the first beginning 0.6271461255. Under 'words' is 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.

At $z=0$ this family is the perfect square $x^2(x+1)^2$, as the start of the transport requires. A letter that lies on the transport path is a singularity of the extended system. Choose waypoints (waypoints=[...]) around it, or expect the run to stop.

Routines

The front end is imported with from ellipticus import ..., with tools/ on PYTHONPATH.

FunctionWhat it returns
MomentFamily(coeffs_x_desc, window, kmax, param)A cubic or quartic family with an exact window
.polyform()The exact extended system as integer polynomial data (n, Den, NumM, den_factors)
.eval_words(words, endpoints, dps, waypoints)Moments, boundary states and words at each endpoint, keyed by endpoint
QuarticCurve(coeffs)One exact quartic
.roots(dps), .real_ovals(dps), .tau_from_oval(dps)The roots, the real ovals and the parameter $\tau$ of the curve
.period_oval(dps, oval), .cycle_moments(ks, dps, oval)The period and the moments $\oint x^k\,dx/y$ of a real oval
.cycle_pair_contour(pair, ks, dps)A cycle around a complex-conjugate root pair, counterclockwise, principal branch at the base point
evaluate(verb, dps, extra), shared_digits(a, b)value, shared_digits, lo, hi from verb(dps) at two precisions; the comparison it uses
sunrise_frame(t, m1, m2, m3, mu)The curve data of the unequal-mass sunrise at a kinematic point
exact(v)The exact-input check that refuses floats

The $q$-series part is imported with from ellipticus import qengine.

FunctionWhat it returns
qengine.g_n_certified(n, z, tau, dps)$g^{(n)}(z,\tau)$ with its proven tail bound, as (value, bound); near the edge, the measured difference of the two routes
qengine.g_tail_bound(n, z, tau, J)The bound alone, for truncation order J
qengine.sunrise_E0(t, masses_sq, dps), qengine.sunrise_J(t, masses_sq, dps)$E^{(0)}$ and $J^{(0)}$ at Euclidean $t$ for exact squared masses, each as (value, certified_bound, diagnostics)
qengine.sunrise_equal_mass_control(t, dps)The same calculation at equal masses, compared with the classical route
qengine.tau_word_frame(qC, z1, z2, z3, Nq)The frame (itint.Frame in vendor/) on which shuffle-regularized $\tau$-iterated words are set up

The modules of ellred (from ellipticus import ellred) and of gmtel are listed under MEMBERS in GUIDE.md. The lower-level names of extend and march are listed in __init__.py.

Used on this site

Requirements

Source and references

The code is tools/ellipticus/ in the BootLoops repository. The error bounds and the checks are BootLoops code.

ReferenceWhat it supplies
C. Bogner, S. Müller-Stach and S. Weinzierl, arXiv:1907.01251The Kronecker–Eisenstein kernels, the $\tau$-iterated integrals and the unequal-mass sunrise formulas
L. Adams and S. Weinzierl, arXiv:1704.08895The notation of the kernels and of the $\tau$-iterated integrals
F. Brown and A. Levin, arXiv:1110.6917The definition of elliptic multiple polylogarithms
J. Broedel, C. Duhr, F. Dulat and L. Tancredi, arXiv:1712.07089; with B. Penante, arXiv:1803.10256Elliptic multiple polylogarithms as iterated integrals on the curve
C. Koutschan, "A Fast Approach to Creative Telescoping", arXiv:1004.3314; earlier work of D. Zeilberger and F. ChyzakCreative telescoping, the method of gmtel

vendor/itint.py reads the notation of the supplementary Maple file of arXiv:1907.01251. The file itself is not in the package.

Other public programs evaluate the same functions. GiNaC evaluates these integrals (M. Walden and S. Weinzierl, arXiv:2010.05271; Duhr, Lorkowski, Marzucca, Mauch and Weinzierl, arXiv:2602.09956). IterInt evaluates iterated integrals in general (G. Baur and C. Duhr, arXiv:2606.02744).

← back to the tools index