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.
| Part | Source | Authors |
|---|---|---|
| The library: symbolic expressions and exact arithmetic | www.ginac.de, arXiv:cs/0004015 | Bauer, Frink, Kreckel and the GiNaC group |
The multiple polylogarithm G(a, z) | arXiv:hep-ph/0410259 | Vollinga and Weinzierl |
The iterated integrals of modular forms: iterated_integral, Eisenstein_kernel, modular_form_kernel | arXiv:2010.05271 | Walden and Weinzierl |
The wrappers that call GiNaC: ginac_gpl, gpl_ginac, ginac_oracle and the SubTropica functions | tools/gpl-eval/, upgrades/Eichler.jl/ and tools/subtropica/ in the BootLoops repository | Written 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:
- Exact input. Give
ginac_gplexact integers or fractions (p/q). Decimal strings are read only at the working precision. - Letters on the path. The wrappers pass real inputs with an exact zero imaginary part. Otherwise GiNaC cannot choose a side for a letter on the integration path, and the program exits with
non-numeric result. - Real values in SubTropica.
ginac_gpl_Gis real-valued only. It stops with an error on a non-negligible imaginary part or when a call exceeds its time limit (timeout_s). - SubTropica does not compile
ginac_gpl. It looks for the binary inside the GPLEval package, or at the path inSUBTROPICA_GINAC_GPL, and stops withginac_gpl CLI not foundif it is absent. Build it once first (see Requirements).
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.
| Command | What 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.jl | Recomputes 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}$.
| Function | What 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
- The hidden sunrise in the energy-energy correlator: the truncated-series evaluation of the iterated integrals of modular forms on that page was checked against GiNaC.
Requirements
- Runs on: a C++ compiler (
g++) with GiNaC and CLN. Iterated integrals of modular forms need GiNaC 1.8 or later. The Julia wrappers also need Julia, set up as on the GPLEval, SubTropica and Eichler pages. - Install: on Debian or Ubuntu
apt install libginac-dev pkg-configplusg++is enough for the wrappers to build. GiNaC is not included in the BootLoops repository. - Build: the two C++ programs come as source only and are compiled on your machine. GPLEval compiles
ginac_gplon first use, andginac-oracle/build.shcompilesginac_oracle. - Self-test, GPLEval:
python3 selftest.pyintools/gpl-eval/. If the library is missing, the GiNaC comparisons are skipped with a warning and the other tests still run. Exit code 0 means a pass or a named skip. - Self-test, SubTropica:
python3 selftest.pyintools/subtropica/. Its GiNaC comparisons run only when both the HyperFLINT engine and theginac_gplbinary are present. A pass ends withsubtropica selftest: PASS (R, F; E per engine availability above). - Self-test, Eichler.jl:
ginac-oracle/build.sh runthenjulia --project=. gauntlet/ginac_mirror.jlinupgrades/Eichler.jl/. The last line printed isALL_AGREE_100_DIGITS = true.
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.
| Reference | What it supplies |
|---|---|
| C. Bauer, A. Frink and R. Kreckel, arXiv:cs/0004015; www.ginac.de | The GiNaC library |
| J. Vollinga and S. Weinzierl, arXiv:hep-ph/0410259 | The numerical evaluation of multiple polylogarithms in GiNaC |
| M. Walden and S. Weinzierl, arXiv:2010.05271 | The iterated integrals of modular forms in GiNaC |