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:

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:

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

CommandWhat it does
GPLEval.jl/bin/gpl_eval.jlEvaluates a basis of symbol words; takes --alphabet, --basis, --point, --prec (bits) and --out
GPLEval.jl/deps/setup.jlLinks 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.

FunctionWhat 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

Requirements

Source and references

The code is in tools/gpl-eval/ in the BootLoops repository. GUIDE.md there lists the credits.

ReferenceWhat it supplies
J. Vollinga and S. Weinzierl, "Numerical evaluation of multiple polylogarithms", hep-ph/0410259The 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. WeinzierlThe values returned by gpl_ginac
A. B. Goncharov, math/0103059The multiple polylogarithms
E. Remiddi and J. A. M. Vermaseren, hep-ph/9905237The harmonic polylogarithms and their compressed notation
F. Johansson, Arb, arXiv:1611.02831; Arblib.jl by M. Kaluba, J. Dahne and contributorsThe ball arithmetic
Ajjath A H, E. Chaubey and H.-S. Shao, arXiv:2312.16966The 39 on-path words of one test

← back to the tools index