GiNaC (external)

The content on this page was written by AI under human supervision.

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 polylogarithms and, from version 1.8 on, iterated integrals of modular forms to any requested number of digits. BootLoops uses it unmodified as an independent reference evaluator: two small C++ programs ask GiNaC for values, and BootLoops' own evaluators are tested against them.

What it does

GiNaC ("GiNaC is Not a CAS") 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 polylogarithmthe iterated integral 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 G(a, z), with numerics by Vollinga and Weinzierl. The other is the iterated integral of modular formsa repeated integral of Eisenstein series in the variable q = exp(2πiτ); these functions appear in elliptic Feynman integrals such as the equal-mass sunrise. GiNaC provides it as iterated_integral over Eisenstein_kernel and modular_form_kernel objects, added by Walden and Weinzierl.

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 using other algorithms, so 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. GPLEval's default convention for a letter lying on the integration path (shift it to aₖ + i0) is named :ginac because it copies GiNaC's.

Limits. Give ginac_gpl exact integers or fractions (p/q); decimal strings are read only at the working precision. The wrappers pass real inputs with an exact zero imaginary part, since otherwise GiNaC cannot choose a side for a letter on the integration path and the program exits with non-numeric result. The SubTropica wrapper is real-valued only and stops with an error on a non-negligible imaginary part or after its timeout (600 s by default). SubTropica does not compile ginac_gpl itself. It looks for the binary inside the GPLEval package (or at the path in SUBTROPICA_GINAC_GPL) and stops with ginac_gpl CLI not found if it is absent, so build it once first (see Requirements and source).

Examples

A polylogarithm value from Julia. We want an independent value of G(0,1,1; 1) = ζ(3) to 80 digits. 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 (usage: ginac_gpl digits re_z im_z [re_a im_a]...), which prints the real and imaginary parts on two lines. The result is a Complex{BigFloat}; the test asserts that its real part agrees with ζ(3) to better than 10⁻⁶⁰. Later tests in the same file compare GPLEval's own 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 Γ₁(6) modular forms 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, writing 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 = / 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⁻¹⁰⁰.

Multiple zeta values inside SubTropica. We want ζ(1,2) and ζ(3) from GiNaC (Euler's identity says they are equal; SubTropica writes zeta indices in ascending order) and one hyperlogarithm constant at infinity. 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 and the third, the regularized constant of G(0,−1; z) as z → +∞, to match ζ(2) to 60 digits. SubTropica.mzv_bigfloat([2, 1]) throws SubTropicaEvalError because that sum diverges.

Routines

BootLoops adds no code to GiNaC itself. The wrappers that call it:

GPLEval (tools/gpl-eval/GPLEval.jl/)

src/ginac_gpl.cpp → ginac_gpl digits re_z im_z [re_a im_a]... — prints Re and Im of G(a₁,…,aₙ; z) at the requested decimal digits.
gpl_ginac(a, z; digits = 60) — exported Julia function; builds and runs ginac_gpl, returns Complex{BigFloat}.

SubTropica (tools/subtropica/src/hlogexpr.jl; call as SubTropica.<name>)

ginac_gpl_G(letters, z; digits = 70, timeout_s = 600) — real value of G with rational letters through the same binary (path overridable with SUBTROPICA_GINAC_GPL); errors on an imaginary part or a timeout.
mzv_bigfloat(idx; digits = 70) — multiple zeta value in the ascending-sum convention (negative index = alternating sign), as ±G(w; 1); refuses divergent input; cached.
zero_inf_period_ginac(word; digits = 70) — regularized constant term of G(word; z) as z → +∞, by evaluating at several very large z and extrapolating in log z.
zero_inf_period_alg(word, letters; digits = 70) — the same extrapolation for words whose letters are algebraic (complex) numbers, passed to ginac_gpl as real and imaginary parts; returns Complex{BigFloat}; normally called for you by eval_symbolic.

Eichler.jl (upgrades/Eichler.jl/)

ginac-oracle/ginac_oracle.cpp → ginac_oracle [outfile] — evaluates the Γ₁(6) forms e₁, e₂, f₃, f₄ at one fixed τ and the iterated integrals I(f₃), I(1,f₃), I(1,f₄,1,f₃) at three fixed q, all with Digits = 140; writes results.txt or the named file.
ginac-oracle/build.sh [run] — compiles it with pkg-config flags (fallback -lginac -lcln); run also executes it.
gauntlet/ginac_mirror.jl — recomputes the four form values and the three iterated integrals at the two real q with Eichler.jl (ten comparisons against the GiNaC numbers) and writes gauntlet/ginac-comparison.txt with a pass mark at 10⁻¹⁰⁰.

GiNaC is also a build dependency of the Kira reducer in Kira-stack.

Used on this site

The Grassmannian string integral — GiNaC values of hyperlogarithm constants, through SubTropica's zero_inf_period_ginac, were the reference numbers for the entry-by-entry check of the integration engine's table (ancillary note THEOREM_W5 on that page).

Requirements and source

C++ with CLN; on Debian or Ubuntu apt install libginac-dev pkg-config plus g++ is enough for the wrappers to build. Iterated integrals of modular forms need GiNaC 1.8 or later. Project site www.ginac.de, license GPL-2.0 or later; BootLoops does not redistribute it. The two bridge programs are distributed as source only and are compiled on your machine; a compiled ginac_gpl or ginac_oracle binary links GiNaC and CLN and is therefore covered by the GPL. References: Bauer, Frink, Kreckel, arXiv:cs/0004015; Vollinga, Weinzierl, arXiv:hep-ph/0410259 (polylogarithm numerics); Walden, Weinzierl, arXiv:2010.05271 (modular forms).

The wrappers are in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai), released under the MIT license (third-party components such as GiNaC keep their own licenses), 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/. GPLEval compiles ginac_gpl on first use; to build it 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)

Tests: python3 selftest.py in tools/gpl-eval/ (if the library is missing the GiNaC comparisons are skipped with a warning and the other tests still run); python3 selftest.py in tools/subtropica/, whose GiNaC comparisons run only when both the HyperFLINT engine and the ginac_gpl binary are present; and ginac-oracle/build.sh run then julia --project=. gauntlet/ginac_mirror.jl in upgrades/Eichler.jl/.

← back to the tools index