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:
- Proven bound. A value from a truncated $q$-series comes with a proven bound on the dropped tail.
- Tail estimate. A value from transporting a differential equation comes with a per-step estimate of the discarded Taylor tail, and the run stops with an error when the estimate is too large. This check is fail-closed (when it fails, the run raises an error and returns no value) and is not a proven bound.
- Agreement. The wrapper
evaluateruns any call at two working precisions and reports the digits they share. Where two methods exist, the self-test compares them.
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.
- System. It 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.
- Start. The starting values at $z=0$ are exact series. For that, the family must degenerate at $z=0$ to a perfect square or a square times a linear factor.
- Transport. It extends the system by the letters of the requested words and integrates it from $z=0$ by adaptive Taylor steps. Each step is held to a tenth of the distance to the nearest singularity or letter. The discarded tail is estimated from the last three computed terms and must stay below $10^{-(\text{working digits}-8)}$. Singular points are passed by detours through complex waypoints.
The other four parts are the following.
- Series.
qengineevaluates the Kronecker–Eisenstein kernelsthe expansion coefficients of the Kronecker function in its second argument; they are the integration kernels of elliptic polylogarithms on the torus $g^{(n)}(z,\tau)$ and iterated integrals of them in $\tau$ as $q$-series with a proven bound on the dropped tail. 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. It also holds the closed forms of the unequal-mass two-loop sunrise at order $\varepsilon^0$, $E^{(0)}(t)$ and $J^{(0)}(t)$, at any Euclidean $t$, in the conventions of Bogner, Müller-Stach and Weinzierl. - Curve.
curvehandles one exact quartic: its roots and real ovals, the periods $\oint dx/y$ by complete elliptic integrals (Legendre/AGM) and by quadrature, and the cycle moments $\oint x^k\,dx/y$. It also computes cycles around a complex-conjugate pair of roots, with the square-root branch tracked explicitly. - Reduction.
ellredreduces 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. A Carlson-form route is a cross-check, and every reduction is compared with direct quadrature. - Telescoper.
gmtelderives the exact Picard–Fuchs operator of the periods of a K3 pencil (a one-parameter family of K3 surfaces) from a Weierstrass model, by the Gauss–Manin connectionthe differential equations that describe how the periods of a family change with its parameters and creative telescopinga method that finds a differential operator in the parameter whose action on the integrand is an exact derivative, so that the operator annihilates the integral; the exact derivative is the certificate. It returns the telescoping certificate beside the operator. Another route fits the operator to a series through Annihilator.
Ellipticus has these limits:
- The $d\log z$ letter (a letter at $a=0$) is allowed only in the outermost position, where it is regularized.
- The word notation is general, but words with more than one $d\log$ letter over the moment raise
NotImplementedError. So do starting bases other than the $z=0$ chart. No guess is returned. - Transport onto a singular endpoint is not bridged. The steps shrink toward the endpoint and the run stops on an
AssertionError. - Words in modular forms for $\Gamma_1(6)$ with interval enclosures go to Eichler.
- The $\overline{E}$ functions of the equal-mass kite are not implemented.
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.
| Function | What 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.
| Function | What 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
- Unequal-mass sunrise: supplied the cut curve, its period and marked points, and the Kronecker–Eisenstein words as $q_C$-series with error bounds.
Requirements
- Runs on: Python 3.10 or newer with
mpmath,sympyandpython-flint.gmtelalso needsnumpy. - Install: nothing is compiled. Put the
tools/directory onPYTHONPATH. The supporting Kronecker–Eisenstein and sunrise code is included undervendor/and the reference data underfixtures/. - Self-test:
python3 selftest.pyfromtools/ellipticus/ends with a line beginningALL SELFTESTS PASS. From the repository root, runPYTHONPATH=<tools dir> python3 -m ellipticus.selftest. - Reference comparison:
python3 battery.py, or-m ellipticus.batteryfrom the root, ends with a line beginningBATTERY PASS. Add--pilotfor a quick low-precision pass. - Check of ellred:
PYTHONPATH=<tools dir> python3 -m ellipticus.ellred.derive_atomsre-derives the closed-form atoms and verifies them. - Check of gmtel:
python3 tools/ellipticus/gmtel/gmtel_selftest.pyruns both routes against the packaged reference operatorfixtures/gmtel/L5_theta.txtand ends with a line beginningGMTEL SELFTEST PASS. The full run takes minutes;--pilotis the short degeneration check.FAMGEN_L5andFAMGEN_TOOLSoverride the reference file and the location of Annihilator. - Optional:
ELLIPTICUS_CACHEnames a directory for a disk cache of the seed series, which take most of the time of a firstmarchrun.ELLIPTICUS_ARTIFACTS,ELLIPTICUS_W3,ELLIPTICUS_KRON_DIRandELLIPTICUS_ROWS_DIRpoint the package at other copies of its reference values, fixtures and bundled code.
Source and references
The code is tools/ellipticus/ in the BootLoops repository. The error bounds and the checks are BootLoops code.
| Reference | What it supplies |
|---|---|
| C. Bogner, S. Müller-Stach and S. Weinzierl, arXiv:1907.01251 | The Kronecker–Eisenstein kernels, the $\tau$-iterated integrals and the unequal-mass sunrise formulas |
| L. Adams and S. Weinzierl, arXiv:1704.08895 | The notation of the kernels and of the $\tau$-iterated integrals |
| F. Brown and A. Levin, arXiv:1110.6917 | The definition of elliptic multiple polylogarithms |
| J. Broedel, C. Duhr, F. Dulat and L. Tancredi, arXiv:1712.07089; with B. Penante, arXiv:1803.10256 | Elliptic 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. Chyzak | Creative 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).