Getting started

We provide a pre-compiled Mathematica interface for most Linux systems, both for double precision and the quad precision. Once downloaded, just make the file executable through

# for double precision
$ chmod +x handyG-double
# for quad precision
$ chmod +x handyG-quad

and load it into Mathematica

(* for double precision *)
Install["handyG-double"]
(* for quad precision *)
Install["handyG-quad"]

Obtaining the code

The code can be downloaded from this page in compressed form or cloned using the git command

$ git clone https://gitlab.com/mule-tools/handyG.git

This will download handyG into a subfolder called handyg. Within this folder

$ git pull

can be used to update handyG.

Installation using meson and ninja (recommended)

handyG can most easily be build with meson and ninja. You can install these through your system’s package manager or pip if you have not already

$ pip install meson ninja

Once you have these tools, you can run

$ meson setup build        # Configures handyG
$ ninja -C build           # Compiles the library
$ ninja -C build test      # Performs checks (optional)
$ ninja -C build install   # Installs library into prefix (optional)

This will compile handyG in the subfolder build (you can choose any name).

During the configuration step (meson setup) you can provide a number of options

install handyG to a non-standard path (recommended)
$ meson setup build --prefix /path/to/installation/folder
perform dynamic linking (produces libhandyg.so rather than libhandyg.a)
$ meson setup build --default-library shared
Use quadruple precision (128 bits) rather than double precision (64 bits)
$ meson setup build -Dreal=128
Compile Mathematica interface (requires mathematica to be installed or mocked)
$ meson setup build -Dmcc=true
Compile GiNaC interface (testing only, requires GiNaC to be installed)
$ meson setup build -Dginac=true
Build handyG with debug symbols (testing and debugging only)
$ meson setup build --buildtype=debug

You can of course mix and match these options. For further details, see the meson manual

Installing using make

The code follows the conventional installation scheme

./configure  # Look for compilers and make a guess at
             # necessary flags
make all     # Compiles the library
make check   # Performs a variety of checks (optional)
make install # Installs library into prefix (optional)

handyG has a Mathematica interface (activate with --with-mcc) and a GiNaC interface (activate with --with-ginac) that can be activated by supplying the necessary flags to ./configure. The latter is only used for testing purposes and is not actually required for running. Another important flag is --quad which enables quadruple precision in Fortran. Note that this will slow down handyG, so that it should only be used if double-precision is indeed not enough.

The compilation process creates the following results

libhandyg.a the handyG library

handyg.mod the module files for Fortran 90

geval a binary file for quick-and-dirty evaluation

handyG the Mathematica interface

Usage in Fortran

handyG is written with Fortran in mind. We provide a module handyg.mod containing the following objects

prec
the working precision as a Fortran kind. This is read-only, the code needs to be reconfigured for a change to take effect. Note that this does not necessarily increase the result’s precision without also changing the next options.
inum

a datatype to handle $\io^\pm$-prescription (see Section 3.4).
clearcache

handyG caches a certain number of classical polylogarithms (see Section 3.5). This resets the cache (in a Monte Carlo this should be called at every phase space point).
G

the main interface for generalised polylogarithms.

The following code calculates five GPLs (see paper for details)

PROGRAM gtest
  use handyG
  complex(kind=prec) :: res(5), x, weights(4)
  call clearcache

  x = 0.3 ! the parameter

  ! flat form with integers
  res(1) = G((/ 1, 2, 1 /))

  ! very flat form for real numbers using F2003 arrays
  res(2) = G([ 1., 0., 0.5, real(x)])
  ! this is equivalent to the flat expression
  res(2) = G([ 1., 0., 0.5 ], real(x))
  ! or in condesed form
  res(2) = G((/1, 2/), (/ 1., 0.5 /), real(x))

  ! flat form with complex arguments
  weights = [(1.,0.), (0.,0.), (0.5,0.), (!.,1.) ]
  res(3) = G(weights, x)

  ! flat form with explicit i0-prescription
  res(4) = G([inum(1.,+1),inum(0,+1),inum(5,+1)], &
                    inum(1/x,di0))
  res(5) = G([inum(1.,-1),inum(0,+1),inum(5,+1)],&
                    inum(1/x,di0))
  ! this is equivalent to
  res(5) = G((/1,2/),[inum(1.,-1),inum(5,+1)], &
                    inum(1/x,+1))

  do i =1,5
    write(*,900) i, real(res(i)), aimag(res(i))
  enddo
900 FORMAT("res(",I1,") = ",F9.6,"+",F9.6,"i")
END PROGRAM gtest

The easiest way to compile code is with pkg-config. Assuming handyG has been installed with make install, the example program example.f90 can be compiled as (assuming you are using GFortran)

$ gfortran -o example example.f90 \
       `pkg-config --cflags --libs handyg`
$ ./example
res(1) = -0.822467+ 0.000000i
res(2) =  0.128388+ 0.000000i
res(3) = -0.003748+ 0.003980i
res(4) = -0.961279+-0.662888i
res(5) = -0.961279+ 0.662888i

If pkg-config is not avaible and/or for non-standard installations it might be necessary to specify the search paths

$ gfortran -o example example.f90 \
>     -I/absolute/path/to/handyg -fdefault-real-8 \
>     -L/absolute/path/to/handyg -lhandyg

Usage in Mathematica

We have interfaced our code to Mathematica using Wolfram’s MathLink interface. Below we show how to calculate the functions above in Mathematica, again, assuming that the code was installed with make install

Install["handyg"];
x=0.3;
res[1] = G[1,2,1]
res[2] = G[1,0,1/2,x]
res[3] = G[1,0,1/2,1+I,x]
res[4] = G[SubPlus[1],5,1/x]
res[5] = G[SubMinus[1],5,1/x]

Using SubPlus and SubMinus the side of the branch cut can be specified. In Mathematica, this can be entered using ctrl _ followed by + or -. When using handyG in Mathematica, keep in mind that it uses Fortran which means that computations are performed with fixed precision.