GPLEval
GPLEval is a Julia package that evaluates multiple polylogarithmsiterated integrals of the one-forms dt/(t − a), also called Goncharov polylogarithms or GPLs; when every index is 0, 1 or −1 they are the harmonic polylogarithms (HPLs) $G(a_1,\dots,a_n;z)$, harmonic polylogarithms $H(\vec m;z)$ and classical polylogarithms $\mathrm{Li}_n(z)$ to any requested precision. Each value comes back as a complex balla midpoint together with a radius guaranteed to contain the true value; the arithmetic is done by the Arb library through Arblib.jl. Two steps of the evaluation are the published method of Jens Vollinga and Stefan Weinzierl (hep-ph/0410259).
What it does
Multiple polylogarithms are the functions that most Feynman integrals without elliptic geometry evaluate to. GPLEval uses the standard definition, first index outermost:
$$G(a_1,\dots,a_n;z)=\int_0^z \frac{dt}{t-a_1}\,G(a_2,\dots,a_n;t),\qquad G(;z)=1,\qquad G(0,\dots,0;z)=\frac{\log^n z}{n!}\,,$$
so that $G(0,\dots,0,a;z)=-\mathrm{Li}_m(z/a)$ with $m-1$ zeros. The harmonic polylogarithm is $H(\vec m;z)=(-1)^p\,G(\vec a;z)$, where $\vec a$ is the word over $\{0,1,-1\}$ expanded from the compressed notation ($[2,1]\to[0,1,1]$) and $p$ counts the indices equal to $+1$.
BootLoops uses these values when it fits an integral to a combination of such functions (Lockpick) and when it tests the fit at points not used in it (Gatekeeper). Every basis function is needed to hundreds of digits, in the conventions the basis was written in.
The evaluation has these steps:
- Trailing zeros. A word ending in zeros is regularized by shuffle identities, so powers of $\log z$ appear explicitly. The formula is that of Vollinga and Weinzierl.
- On-path indices. If a nonzero index lies on the open segment from $0$ to $z$ (an "on-path" index), the answer depends on which side the contour passes. GPLEval splits the path at a complex midpoint with Chen's path-composition formula for iterated integrals. The
prescriptionkeyword picks the side: the default:ginacmeans $a_k+i0$, matching GiNaC's two-argumentG, so $G(1/2;1)=+i\pi$;:feynmanmeans $a_k-i0$. - Series. Well inside $|z| \lt \min_i|a_i|$ the power series at zero is summed, and a proven bound on the dropped tail is added to the radius.
- Hölder convolution. For larger $|z|$ the word becomes a sum of products of polylogarithms at smaller arguments. The identity is the Hölder convolution of Borwein, Bradley, Broadhurst and Lisonek, as printed by Vollinga and Weinzierl.
With an on-path index, an integration along the real axis would return the principal value without warning. GPLEval therefore tests for on-path indices before it uses any closed form or series.
A value can be checked in two ways: method = :hybrid integrates along a deformed contour with Arb's certified quadrature (depth at most 3), and gpl_ginac asks GiNaC for the same number. GiNaC was written by other authors as separate code; for the trailing zeros and the Hölder convolution it uses the same published algorithm. GiNaC, handyG and FastGPL are public evaluators of the same functions. None of them returns a proven error radius.
GPLEval has these limits:
- The radius is a proven bound on rounding and truncation error, with two exceptions. The
series_onlypath ofevaluate_basisadds an estimated tail term, andmethod = :ginacwraps GiNaC's number without a bound. - Precision is set in bits, not digits:
prec = 256is about 77 decimal digits. - Only letters linear in the integration variable are handled. For elliptic kernels
emplpasses the call through to Eichler. - In the symbol-word interface (the third example below, where a word is a list of letter names), a letter stands for the index $a_i$ (the root of $z-a_i$), not for the argument of a $d\log$.
Examples
The self-test suite. With Julia installed (see Requirements), run from the package directory tools/gpl-eval/:
python3 selftest.py
The wrapper sets up the package environment if needed and runs GPLEval.jl/test/runtests.jl. The suite checks values such as $H(2,1;1)=\zeta(3)$, continuation to $|z|\ge\min|a_i|$ and both $\pm i0$ prescriptions. Where GiNaC is installed it also checks agreement to at least 60 digits at random rational points; otherwise those comparisons are skipped with a warning.
Single values from Julia. As called in the test suite:
using Arblib, GPLEval const PREC = 768 # ≥ 200 decimal digits hpl([2, 1], 1; prec = PREC) # Euler: equals ζ(3) gpl([1//2], 1; prec = PREC) # G(1/2;1) = log(−1) = +iπ, default side gpl([1//2], 1; prec = PREC, prescription=:feynman) # −iπ gpl([0, 1, -1, 1], 1//3; prec = 512) # depth 4 gpl_ginac([0, 1, 1], 1; digits = 80) # GiNaC's G(0,1,1;1) = ζ(3)
The first four calls return an Acb; real(g) and imag(g) are Arb balls and Arblib.radref(real(g)) is the radius. gpl_ginac returns a Complex{BigFloat} without an error bound; on first use it compiles the helper from src/ginac_gpl.cpp.
A basis of symbol words from the command line. With alpha.json
{"letters": {"l0": "0", "l1": "1", "lm1": "-1", "ls": "s+t"}, "zvar": "z"}
and basis.json holding a list of symbol wordssequences of letter names; a word (s₁,…,sₙ) stands for G(a₁,…,aₙ; z) with aᵢ the index of letter sᵢ such as [["l0","l1"], ["l0","l1","lm1"]], run
julia --project=GPLEval.jl GPLEval.jl/bin/gpl_eval.jl \
--alphabet alpha.json --basis basis.json \
--point '{"s":-3,"t":-7,"z":0.5}' --prec 256 --out values.json
Each letter is a Julia expression in the variables of --point and gives that letter's index $a_i$; zvar names the entry that is the upper limit $z$. values.json holds the precision, the point and one entry per word, with re and im as decimal strings and rad, the radius of the real part. Read rad before trusting digits.
Point entries pass through double precision, so use values exact in binary (integers, halves). For other points call evaluate_basis(words, alpha, z, pt; prec = PREC) from Julia with exact rationals and alpha = Dict(:l0 => p -> 0, :l1 => p -> 1, :lm1 => p -> -1), as in the tests.
Routines
| Command | What it does |
|---|---|
GPLEval.jl/bin/gpl_eval.jl | Evaluates a basis of symbol words; takes --alphabet, --basis, --point, --prec (bits) and --out |
GPLEval.jl/deps/setup.jl | Links the Landau Alphabet and Eichler packages into the project; reads LANDAUALPHABET_JL_PATH and EICHLER_JL_PATH if set |
ginac_gpl digits re_z im_z [re_a im_a]... | The helper built from src/ginac_gpl.cpp; prints GiNaC's real and imaginary parts of $G$ |
Without --out the JSON goes to standard output. No compiled ginac_gpl is included.
| Function | What it returns |
|---|---|
gpl(a, z; prec) | $G(a_1,\dots,a_n;z)$ as an Acb; keywords cache, prescription and method |
gpl_hybrid(a, z; prec) | The same value by method = :hybrid; needs $a_1$, $a_2$ and $a_n$ nonzero |
hpl(m, z; prec) | $H(\vec m;z)$ from the compressed vector, or from a word over $\{0,1,-1\}$ with expanded = true |
hpl_expand(m) | The index word of a compressed vector: [2,1] gives [0,1,1] |
li(n, z; prec) | $\mathrm{Li}_n(z)$ as a ball |
analytic_continue(a, z; prec) | $G$ with on-path indices by path splitting, or by contour quadrature with method = :hybrid |
on_path_indices(a, z) | Positions of the on-path indices; takes a Vector{Acb} and an Acb |
GPLCache(prec) | A table of computed sub-words at one precision, passed as cache = |
evaluate_symbol(word, alphabet, z, point; prec) | The value of one word, with $a_i$ the value of alphabet[letter] at point |
evaluate_basis(words, alphabet, z, point; prec) | The values of a list of words, computed with a shared cache |
gpl_ginac(a, z; digits) | GiNaC's $G(a;z)$ as a Complex{BigFloat}; give exact integers or rationals |
empl(kernels, t, sec), empl(kernels, q, logq) | Eichler's certified iterated integral of $q$-series kernels, passed through |
prescription is :ginac (also written :plus_i0) or :feynman (also :minus_i0). method is :auto, :hybrid or :ginac. With series_only = true, evaluate_basis uses Landau Alphabet's cached series, meant for a large basis with $|z| \lt \min|a_i|$. The names re-exported from Landau Alphabet and Eichler are in the export lines of GPLEval.jl/src/GPLEval.jl.
Used on this site
- Massless planar double box: arbitrary-precision evaluation of the harmonic polylogarithms.
- Three-loop ladder: arbitrary-precision evaluation of the polylogarithms and Goncharov words in the fit basis and in the comparison with the published form.
- Polylogarithms: with Arb, evaluates the multiple polylogarithms to arbitrary precision for the checks at points not used in the fits.
Requirements
- Runs on: Julia with the registered packages Arblib and JSON3, plus two packages from the same repository: Landau Alphabet (
tools/landau-alphabet/LandauAlphabet.jl) and Eichler (upgrades/Eichler.jl). GPLEval declares Julia 1.10 or newer; Landau Alphabet and Eichler, which it loads, declare Julia 1.11 or newer. - Install: from
tools/gpl-eval/runjulia --project=GPLEval.jl -e 'import Pkg; Pkg.instantiate()'once (it needs the network).Project.tomlandManifest.tomlare included. On a Julia version other than 1.11 runjulia GPLEval.jl/deps/setup.jl. - Self-test:
python3 selftest.py(Python 3 is needed only for this wrapper), orjulia --project=GPLEval.jl GPLEval.jl/test/runtests.jl. Exit code 0 means a pass, unless the output has a line beginninggpl-eval selftest: SKIPPED: thenjuliaor a dependency was missing and nothing was tested. A nonzero code means a test failed or the Julia environment could not be loaded. - Optional: the GiNaC cross-check needs the GiNaC and CLN C++ libraries,
g++andpkg-config(www.ginac.de). GiNaC is used unmodified, and the helper that links it runs as a separate process. To build the helper by hand:g++ -O2 -std=c++17 -o GPLEval.jl/src/ginac_gpl GPLEval.jl/src/ginac_gpl.cpp $(pkg-config --cflags --libs ginac).
Source and references
The code is in tools/gpl-eval/ in the BootLoops repository. GUIDE.md there lists the credits.
| Reference | What it supplies |
|---|---|
| J. Vollinga and S. Weinzierl, "Numerical evaluation of multiple polylogarithms", hep-ph/0410259 | The removal of trailing zeros and the Hölder convolution |
| C. Bauer, A. Frink and R. Kreckel, GiNaC, cs/0004015; polylogarithms by J. Vollinga and S. Weinzierl | The values returned by gpl_ginac |
| A. B. Goncharov, math/0103059 | The multiple polylogarithms |
| E. Remiddi and J. A. M. Vermaseren, hep-ph/9905237 | The harmonic polylogarithms and their compressed notation |
| F. Johansson, Arb, arXiv:1611.02831; Arblib.jl by M. Kaluba, J. Dahne and contributors | The ball arithmetic |
| Ajjath A H, E. Chaubey and H.-S. Shao, arXiv:2312.16966 | The 39 on-path words of one test |