GiNaC (external)

GiNaC is a public C++ library for symbolic computation by Christian Bauer, Alexander Frink, Richard Kreckel and the GiNaC group. Besides exact algebra it evaluates multiple polylogarithmsthe iterated integrals G(a₁,…,aₙ; z) = ∫₀^z dt/(t−a₁) G(a₂,…,aₙ; t) with "letters" aᵢ; the function class most one- and two-loop Feynman integrals evaluate to and, from version 1.8 on, iterated integrals of modular formsrepeated integrals of Eisenstein series in the variable q = exp(2πiτ); these functions appear in elliptic Feynman integrals such as the equal-mass sunrise to any requested number of digits. BootLoops uses it unmodified as an external reference: two small C++ programs ask GiNaC for values, and the BootLoops evaluators are tested against those values.

Where it comes from

GiNaC ("GiNaC is Not a CAS") is the work of Christian Bauer, Alexander Frink, Richard Kreckel and the GiNaC group. Its numerical evaluation of multiple polylogarithms is by Jens Vollinga and Stefan Weinzierl. Its iterated integrals of modular forms were added by Moritz Walden and Stefan Weinzierl. BootLoops adds no code to GiNaC and does not include it. The BootLoops wrappers call GiNaC's public interface and read back its numbers.

PartSourceAuthors
The library: symbolic expressions and exact arithmeticwww.ginac.de, arXiv:cs/0004015Bauer, Frink, Kreckel and the GiNaC group
The multiple polylogarithm G(a, z)arXiv:hep-ph/0410259Vollinga and Weinzierl
The iterated integrals of modular forms: iterated_integral, Eisenstein_kernel, modular_form_kernelarXiv:2010.05271Walden and Weinzierl
The wrappers that call GiNaC: ginac_gpl, gpl_ginac, ginac_oracle and the SubTropica functionstools/gpl-eval/, upgrades/Eichler.jl/ and tools/subtropica/ in the BootLoops repositoryWritten for BootLoops

Please cite the authors' papers when you use GiNaC. BootLoops is not affiliated with or endorsed by the GiNaC authors.

What it does

GiNaC lets a C++ program build and manipulate symbolic expressions, with exact rational arithmetic through the CLN number library, polynomial algebra, series and differentiation. It also evaluates special functions numerically at a precision set by the global variable Digits. Two of those functions matter here. One is the multiple polylogarithm G(a, z). The other is the iterated integral of modular forms, which GiNaC provides as iterated_integral over Eisenstein_kernel and modular_form_kernel objects.

In BootLoops GiNaC is a second opinion, never the source of a result. Production values come from GPLEval for polylogarithms and Eichler for integrals of modular forms, both of which return intervals with proven error bounds. A GiNaC value is a floating-point number at the requested precision with no bound attached.

GiNaC was written by other authors and is other code. Two steps of GPLEval use the same published algorithm as GiNaC, that of Vollinga and Weinzierl (arXiv:hep-ph/0410259): the removal of trailing zerosa polylogarithm whose last letters are zero is rewritten by shuffle identities, so that powers of log z appear explicitly and the Hölder convolutionan identity that turns a polylogarithm at a larger argument into a sum of products of polylogarithms at smaller arguments. Agreement to 60 or 100 digits makes a shared mistake in conventions or branch choices unlikely.

GPLEval and SubTropica reach GiNaC through one small command-line program, ginac_gpl. Eichler.jl has a separate one for modular forms, ginac_oracle. GPLEval's default convention for a letter lying on the integration path (shift it to $a_k + i0$) is named :ginac because it copies GiNaC's. GiNaC is also a build dependency of the Kira reducer in Kira-stack.

The wrappers have these limits:

Examples

A polylogarithm value from Julia. We want GiNaC's value of $G(0,1,1;1)=\zeta(3)$ to 80 digits. With GiNaC installed (see Requirements), start Julia from the package directory tools/gpl-eval/ with julia --project=GPLEval.jl. From GPLEval's test suite:

using GPLEval
gg = gpl_ginac([0, 1, 1], 1; digits = 80)

The first call compiles src/ginac_gpl.cpp into src/ginac_gpl with g++ (the repository carries only the source) and runs it. The result is a Complex{BigFloat}, and the test asserts that its real part agrees with $\zeta(3)$ to better than $10^{-60}$. Later tests in the same file compare GPLEval's gpl against gpl_ginac at random rational points, including points with a letter on the path from 0 to $z$.

Checking Eichler.jl against GiNaC. We want GiNaC's values for the $\Gamma_1(6)$ modular forms (modular forms of level 6) and a confirmation that Eichler.jl reproduces them. From upgrades/Eichler.jl/:

ginac-oracle/build.sh run
julia --project=. gauntlet/ginac_mirror.jl

The first command compiles the C++ program and runs it. It writes results.txt in the same folder: the GiNaC version, Digits = 140, the kernel definitions (for example E1K1 = Eisenstein_kernel(1,6,1,-3,1,1)) and each value as Re = and Im = lines. The second evaluates the same objects in Eichler.jl at 512 bits and writes gauntlet/ginac-comparison.txt, one line per comparison, such as

e1 = E1(tau;chi0,chi1): |Eichler - GiNaC| = 3.908802148549627e-155  (<1e-100: true)

A false at the end of a line means the two implementations differ by more than $10^{-100}$.

Multiple zeta values inside SubTropica. We want $\zeta(1,2)$ and $\zeta(3)$ from GiNaC, and the constant term of one polylogarithm at infinity. A multiple zeta valuea nested sum ζ(n₁,…,nᵣ) over ordered positive integers, the generalization of ζ(n) to several indices is written here with its indices in ascending order, and Euler's identity says the two values are equal. From SubTropica's tests:

SubTropica.mzv_bigfloat([1, 2]; digits=70)
SubTropica.mzv_bigfloat([3]; digits=70)
SubTropica.zero_inf_period_ginac(["0", "-1"]; digits=70)

Each returns a BigFloat. The tests require the first two to share at least 60 digits. They require the third, the regularized constant of $G(0,-1;z)$ as $z\to+\infty$, to match $\zeta(2)$ to 60 digits. SubTropica.mzv_bigfloat([2, 1]) throws SubTropicaEvalError because that sum diverges.

Routines

The wrappers are two C++ programs with their scripts, and five Julia functions.

CommandWhat it does
ginac_gpl digits re_z im_z [re_a im_a]...Prints the real and imaginary parts of $G(a_1,\dots,a_n;z)$ on two lines, at the requested decimal digits
ginac-oracle/build.sh [run]Compiles ginac_oracle.cpp with pkg-config flags; run also executes it
ginac_oracle [outfile]Evaluates four modular forms and three iterated integrals with Digits = 140; writes results.txt or the named file
julia --project=. gauntlet/ginac_mirror.jlRecomputes ten of those values with Eichler.jl and writes gauntlet/ginac-comparison.txt

ginac_gpl is built from src/ginac_gpl.cpp in tools/gpl-eval/GPLEval.jl/. build.sh and ginac_mirror.jl are run from upgrades/Eichler.jl/. build.sh leaves the ginac_oracle program in ginac-oracle/, beside ginac_oracle.cpp.

ginac_oracle evaluates the $\Gamma_1(6)$ forms $e_1$, $e_2$, $f_3$, $f_4$ at one fixed $\tau$. It evaluates the iterated integrals $I(f_3)$, $I(1,f_3)$ and $I(1,f_4,1,f_3)$ at three fixed $q$. ginac_mirror.jl compares the four form values and the three integrals at the two real $q$, with a pass mark at $10^{-100}$.

FunctionWhat it returns
gpl_ginac(a, z; digits)GiNaC's $G(a;z)$ as Complex{BigFloat}; exported by GPLEval; builds ginac_gpl if needed and runs it
SubTropica.ginac_gpl_G(letters, z; digits, timeout_s)The real value of $G$ with rational letters, through the same binary
SubTropica.mzv_bigfloat(idx; digits)A multiple zeta value in the ascending-sum convention (a negative index means an alternating sign); refuses divergent input
SubTropica.zero_inf_period_ginac(word; digits)The regularized constant term of $G(\mathrm{word};z)$ as $z\to+\infty$, extrapolated in $\log z$ from several very large $z$
SubTropica.zero_inf_period_alg(word, letters; digits)The same constant for algebraic (complex) letters, as Complex{BigFloat}; normally called for you by eval_symbolic

gpl_ginac is defined in tools/gpl-eval/GPLEval.jl/src/ginac_bridge.jl, and the SubTropica functions in tools/subtropica/src/hlogexpr.jl.

Used on this site

Requirements

To build ginac_gpl by hand, for example so that SubTropica can find it, run from tools/gpl-eval/:

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

GiNaC is at www.ginac.de. The wrappers are in the BootLoops repository, at tools/gpl-eval/GPLEval.jl/src/ginac_bridge.jl and ginac_gpl.cpp, tools/subtropica/src/hlogexpr.jl, and upgrades/Eichler.jl/ginac-oracle/. The licenses of GiNaC and of the wrappers are listed on the credits page.

ReferenceWhat it supplies
C. Bauer, A. Frink and R. Kreckel, arXiv:cs/0004015; www.ginac.deThe GiNaC library
J. Vollinga and S. Weinzierl, arXiv:hep-ph/0410259The numerical evaluation of multiple polylogarithms in GiNaC
M. Walden and S. Weinzierl, arXiv:2010.05271The iterated integrals of modular forms in GiNaC

← back to the tools index