PentagonFunctions-cpp (external)
PentagonFunctions-cpp (called PentagonFunctions++ by its authors) is public C++ software by D. Chicherin, V. Sotnikov and S. Zoia that evaluates pentagon functionsthe transcendental functions of weight 1 to 4 in which every two-loop five-point master integral can be expressed, for five massless particles or for four massless and one massive numerically. Given a kinematic point and a list of functions, it returns their complex values in double, quadruple or octuple precision. BootLoops builds it from the released source without changes and uses it only as a reference against which its own two-loop five-point results are checked.
Where it comes from
The library is the work of Chicherin, Sotnikov and Zoia. The massless functions are defined in a paper by Chicherin and Sotnikov, and the planar one-mass functions in a paper by Chicherin, Sotnikov and Zoia. The full one-mass set is defined in a paper by Abreu, Chicherin, Ita, Page, Sotnikov, Tschernow and Zoia. These papers and the paper that defines the decay-channel set are listed under Source and references.
BootLoops adds no code of its own around the library and carries no patch. It calls the library from short C++ programs written against the documented interface. A two-loop five-point quantity computed with the BootLoops tools must reproduce the library's value at a test point before it is accepted. The library's values are never used as input to a BootLoops fit or derivation.
Please cite the authors' papers when you use the library. BootLoops is not affiliated with or endorsed by the authors.
What it does
Two-loop scattering amplitudes for five particles (all massless, or four massless and one massive) can be written as rational coefficients times a fixed, finite set of special functions, the pentagon functions. The library evaluates those functions at a given point. Three sets can be enabled at build time:
m0: fully massless kinematics.m1: one external mass in a 2→3 production channel, planar and non-planar.m1_decay: one external mass in a 1→4 decay channel.
The input point is the list of adjacent two-particle Mandelstam invariants$s_{ij}=(p_i+p_j)^2$ for neighboring external momenta; five numbers for massless kinematics, six for the one-mass sets, where the first entry is the squared mass $p_1^2$. Each invariant is divided by the squared dimensional-regularization scale, so that the entries are dimensionless and, ideally, of order one. A function is addressed by its weightthe transcendental weight, the number of iterated integrations in the function; a logarithm has weight 1 and a dilogarithm weight 2 and one or two labels, and the output is one complex number per function.
Weights 1 and 2 are computed from closed expressions in logarithms and dilogarithms. Weights 3 and 4 are computed by a one-dimensional numerical integration. Its default tolerance is no larger than the rounding error of the number type.
Number types are double and, in a build with the high-precision option, the types dd_real (about 32 digits) and qd_real (about 64 digits) of the qd library. At the test suite's one-mass reference point, BootLoops compared eight functions of weights 1 to 4 with the 70-digit values stored there. They agreed to 13–17 digits in double, 29–31 in dd_real and 60–65 in qd_real. Expect roughly that from each type.
The library has these limits:
- No error bound. Results are numerical values at working precision, without a proven error bound.
- Physical region only. Functions are evaluated only in the physical scattering region defined in the papers.
- Parity. Functions take Mandelstam invariants only, so sign changes of parity-odd functions under parity or odd permutations are left to the user.
- Normalization. The parity-odd normalization differs between the planar and the full one-mass papers. Do not mix the two in one calculation.
- Scope. The library computes the sets of functions it contains and nothing else. It does not evaluate general polylogarithms.
Examples
Build with extended precision and run the library's tests. With meson, ninja and qd in place (see Requirements), run in the library's source directory, following its README:
meson setup build -D prefix=$HOME/local -D high-precision=true cd build ninja install ninja test
ninja install compiles the enabled sets and installs the headers, the shared library, PentagonFunctions.pc and a Mathematica package under the prefix. ninja test runs the library's test programs (test_w12, test_m1_w12, test_m1_full, test_m1_decay and so on, plus _HP/_VHP variants in a high-precision build). Each program compares fresh evaluations with reference values in tests/targets_*.hpp and reports pass or fail.
Evaluate massless pentagon functions in double precision. The library's own program examples/example_simple.cpp, built automatically as build/examples/example_simple, shows the whole interface. Its central lines (omissions marked // ...):
using namespace PentagonFunctions;
// ...
using T = double;
// ...
constexpr KinType KT = KinType::m0;
// ...
std::vector<FunID<KT>> needed_functions = {
{1,1,1}, {1,3,1}, {1,2,10},
{2,1,3}, {2,2,1},
{3,3}, {3,17}, {3,111},
{4,17}, {4,122}, {4,436}, {4,466}, {4,472},
};
// ...
std::vector<FunctionObjectType<T,KT>> function_evaluators;
// ...
for (auto f : needed_functions) {
function_evaluators.push_back(f.get_evaluator<T>());
std::cout << f << "\n";
}
// ...
constexpr size_t n_vars = Kin<T,KT>::Nvis;
std::array<T,n_vars> sij = {
169.00000000000000000000000000000000000000000000000000000000000024,
-127.03554269209390121978365556633554285695735563298040778575769793,
33.796369695873051618118516726995190978444086393722898206354653227,
34.135578250263955969284362230088631173450982210677708512608176643,
-112.93867208272743252147419350392861691229747936905042006487121976,
};
// ...
Kin<T,KT> k(sij);
// ...
for (size_t i = 0; i < function_evaluators.size(); ++i) {
auto ri = function_evaluators.at(i)(k);
std::cout << needed_functions.at(i) << " = " << ri << "\n";
}
Each FunID<KT> in the list names one function by its indices. The evaluators are built once from that list, before any point is evaluated. Calling an evaluator on the point k (Nvis is 5 here) returns a std::complex<T>, printed after the function's label.
The same program can be changed in two ways:
- Extended precision. Put
dd_realorqd_realin place ofdouble. On x86, bracket the evaluations with qd'sfpu_fix_start/fpu_fix_end. - One-mass set.
KinType::m1selects it, with six invariants per point and two indices for weight-1 and weight-2 functions. The file includes a commented one-mass point to try.
Compile your own program against an installed copy. With $PF the install prefix, $QD the qd prefix and myprog.cpp your source file, BootLoops compiles and runs such a program with:
export PKG_CONFIG_PATH=$PF/lib/x86_64-linux-gnu/pkgconfig:$PF/lib/pkgconfig:$QD/lib/pkgconfig
g++ -O2 -std=c++17 myprog.cpp -o myprog \
$(pkg-config --cflags --libs PentagonFunctions Li2++ qd)
export LD_LIBRARY_PATH=$(pkg-config --variable=libdir PentagonFunctions):$QD/lib:$LD_LIBRARY_PATH
./myprog
The source file can #include "FunctionID.h" directly, since --cflags supplies that directory. Linking has two pitfalls:
- Private dependencies.
PentagonFunctions.pclists Li2++ (the dilogarithm library) and qd only as private dependencies. A dynamic link that namesPentagonFunctionsalone fails with undefinedLi2pp::symbols, so name all three packages. - Run-time search path. The installed libraries carry no run-time search path, so
LD_LIBRARY_PATHmust cover both the install's library directory and qd's.
Routines
A program that calls the library uses these names from its documented interface:
| Name | What it is |
|---|---|
FunID<KinType> (header FunctionID.h) | Identifies one pentagon function by its indices; KinType is m0, m1 or m1_decay |
FunID<KinType>::get_evaluator<T>() | Returns the callable evaluator (FunctionObjectType<T,KinType>) for double, dd_real or qd_real |
Kin<T,KinType> (header Kin.h) | A kinematic point built from an array of Nvis normalized invariants (5 for m0, 6 for the one-mass sets) |
IntegrationTolerance<T> | Global variable: the stopping tolerance of the weight-3 and weight-4 numerical integration for type T |
always_switch_to_HP_for_sqrt_divergences | Global boolean (default true in high-precision builds): when true, certain non-planar one-mass functions switch locally to higher precision near integrable square-root singularities |
The library also installs a Mathematica package (PentagonFunctions.m). A separate Python interface by G. De Laurentis can be installed with pip as pentagon-functions. BootLoops calls the C++ interface.
Requirements
- Runs on: a C++17 compiler (the README recommends
g++; Apple Clang is not expected to work), meson 0.58 or newer and ninja. Both meson and ninja can be installed withpip. Li2++ is fetched automatically as a meson subproject. - Install:
meson setup build -D prefix=$HOME/local -D high-precision=true, thenninja installinbuild.$HOME/localis the install prefix. To leave out a set of functions add, for example,-D m1_decay_set=disabled. - Extended precision: install the qd library first and make it visible through
PKG_CONFIG_PATHandLD_LIBRARY_PATH. - Build without qd:
src/PhaseSpaceGen.cppincludes the qd headers unconditionally, so ahigh-precision=falsebuild on a machine without qd fails to compile. BootLoops builds version 4.0 withhigh-precision=trueagainst a local qd 2.3.24, which avoids the problem without touching the source. - Self-test:
ninja testfrom the build directory.
Source and references
The BootLoops repository does not bundle the library. The repository's external-software catalog lists the library as obtained from its authors' repository and used unmodified.
| Reference | What it supplies |
|---|---|
| D. Chicherin, V. Sotnikov and S. Zoia, PentagonFunctions-cpp | The source code of the library |
| D. Chicherin and V. Sotnikov, arXiv:2009.07803 | The massless functions |
| D. Chicherin, V. Sotnikov and S. Zoia, arXiv:2110.10111 | The planar one-mass functions |
| Abreu, Chicherin, Ita, Page, Sotnikov, Tschernow and Zoia, arXiv:2306.15431 | The full one-mass set |
| arXiv:2602.18185 | The decay-channel set |