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:

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:

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:

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:

Routines

A program that calls the library uses these names from its documented interface:

NameWhat 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_divergencesGlobal 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

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.

ReferenceWhat it supplies
D. Chicherin, V. Sotnikov and S. Zoia, PentagonFunctions-cppThe source code of the library
D. Chicherin and V. Sotnikov, arXiv:2009.07803The massless functions
D. Chicherin, V. Sotnikov and S. Zoia, arXiv:2110.10111The planar one-mass functions
Abreu, Chicherin, Ita, Page, Sotnikov, Tschernow and Zoia, arXiv:2306.15431The full one-mass set
arXiv:2602.18185The decay-channel set

← back to the tools index