1 Program summary

Computer for which the program is designed and others on which it is operable: any with standard C++, tested on Linux and Mac OS systems

Programming Language used: C++

High-speed storage required: No

Separate documentation available: No

Other programs used: LHAPDF (version 6) for access to collinear parton distributions, Root (any version \(> 5.30\)) for plotting the results

Download of the program: http://tmdlib.hepforge.org

Unusual features of the program: None

Citation policy: please cite the current version of the manual and the paper(s) related to the parameterization(s).

2 Introduction

The calculation of processes at high energy hadron colliders is based in general on the calculation of a partonic process (matrix element) convoluted with the likelihood to find a parton of specific flavor and momentum fraction at a given scale within the hadrons. If the parton density depends only on the longitudinal momentum fraction x of the hadron’s momentum carried by a parton, and the resolution scale \(\mu \), the processes are described by collinear factorization with the appropriate evolution of the parton densities (PDFs) given by the Dokshitzer–Gribov–Lipatov–Altarelli–Parisi (DGLAP) evolution equations [1,2,3,4,5]. Such descriptions are successful for sufficiently inclusive processes, like inclusive deep-inelastic lepton-hadron scattering (DIS).

In several less inclusive processes, also the transverse momentum of the interacting partons plays an important role, leading to an extension of the collinear factorization theorem to include transverse degrees of freedom. Different factorization theorems for the inclusion of transverse momenta to the parton densities have been developed in the past, leading to so-called Transverse Momentum Dependent (TMD) parton densities and unintegrated parton densities (uPDFs) [6]. These densities provide a 3D imaging of hadron structure, extending the 1D picture given by PDFs. For semi-inclusive processes, like semi-inclusive DIS (SIDIS), Drell-Yan (DY) production and \(e^+e^-\) scattering, TMD factorization has been formulated [7,8,9,10,11,12,13,14,15,16,17,18,19]. The high-energy (small-x limit) factorization was formulated for heavy flavor and heavy boson production in Refs. [20,21,22,23,24,25,26] using unintegrated gluon distributions [27,28,29,30,31,32,33,34,35]. In Refs. [36, 37] the Parton Branching (PB) method was formulated as a way to obtain TMD distributions for all flavours over a wide range of x, transverse momentum \(k_t\), and scale \(\mu \) essentially by solving next-to-leading-order (NLO) DGLAP equations through Sudakov form factors, separating resolvable and non-resolvable branchings via the notion of soft-gluon resolution scale [38, 39], and keeping track of the transverse momenta at each branching.

Since the number of available TMD densities increases very rapidly, and different groups provide different sets, it was necessary to develop a common platform to access the different TMD sets in a common form. In 2014 the first version of TMDlib (version 1) and TMDplotter was released [40, 41], which made several TMD sets available to the community. This library has set a common standard for accessing TMD sets, similar to what was available for collinear parton densities in PDFlib [42, 43] and LHAPDF [44]. TMDlib is a C++ library which provides a framework and an interface to a collection of different uPDF and TMD parameterizations.

In this report, we describe a new version of the TMDlib library, TMDlib2, as well as the associated online plotting tool TMDplotter. TMDlib2 covers all the features present already in the previous version and contains significant new developments, such as the treatment of TMD uncertainties and a more efficient method to include new TMD sets. The report is structured as follows. In Sect. 2, we give the main elements of the library framework. In Sect. 3 we emphasize the new features of TMDlib2 compared to the previous version. In Sect. 4 we provide the essential documentation. We summarize in Sect. 5.

3 The TMDlib framework

The TMDlib library and its new version TMDlib2 consider momentum weighted TMD parton distributions \(x {{\mathcal {A}}}_j (x ,k_t, \mu )\) of flavor j as functions of the parton’s light cone longitudinal momentum fractions x of the hadron’s momentum, the parton’s transverse momentum \(k_t\), and the evolution scale \(\mu \) [6]. Besides, the library also contains integrated TMDs obtained from the integration over \(k_t\), as follows

$$\begin{aligned} x{{\mathcal {A}}}_{int}(x,\mu ) = \int _{k_{t,min}}^{k_{t,max}}d k_t^2 \; x{{\mathcal {A}}}(x,k_t, \mu ) \, , \end{aligned}$$
(1)

In Fig. 1 (left), we show an example of integrated TMD obtained with TMDplotter for the PB-NLO-HERAI+II-2018-set1 [45], in which the integral between \(k_{t,min} =0.01\) and \(k_{t,max} =100\) GeV is compared with the collinear PDF set HERAPDF2.0 [46]. By construction both sets are identical. However, in general, Eq. (1) does not converge to the collinear pdf, which is shown in Fig. 1 (right) comparing the integral between \(k_{t,min} =0.01\) and \(k_{t,max} =100\) GeV of PV17 [47] with the corresponding collinear distribution of MMHT2014 [48]. Several aspects of the relationship between integrated TMDs and collinear PDFs have been investigated in the literature. The matching coefficient between the integrated gluon TMD and the collinear gluon PDF in the MSbar scheme was first computed in the small-x limit in Ref. [24], with small-x resummation of logarithmic accuracy \((\alpha _s \ln x )^m\) to all orders m in \(\alpha _s\). Perturbative calculations of the matching coefficients at finite order have recently been carried out through \(\hbox {N}^3\)LO in Refs. [49, 50]. Other aspects of the relationship between integrated TMDs and collinear PDFs are studied e.g. in [21, 27, 28, 51,52,53,54]. We refer the reader to the overview [6], and references therein, for further discussions of this topic.

In TMDlib2 the densities are defined more generally as momentum weighted distributions \(x{{\mathcal {A}}}(x,{\bar{x}}, k_t, \mu )\), where \(x, {\bar{x}}\) are the (positive and negative) light-cone longitudinal momentum fractions [51, 54,55,56]. In some of the applications \({\bar{x}}\) is set explicitly to zero, while in other cases \({\bar{x}} = 0\) means that it is implicitly integrated over.

Fig. 1
figure 1

Comparison of up-type parton distributions, \(xf(x,\mu )=x{{\mathcal {A}}}_{int}(x,\mu )\) as a function of x at \(\mu =100\) GeV (left): comparison of the integrated distribution PB-NLO-HERAI+II-2018-set1 [45] with HERAPDF2.0 [46]. (right): comparison of integrated distribution PV17 [47] with MMHT2014 [48]

Full size image

3.1 Grids and Interpolation

Since the analytic calculation of TMDs as a function of the longitudinal momentum fraction x (we neglect \({\bar{x}}\) in the following), the transverse momentum \(k_t\) and the scale \(\mu \) is very time consuming and in some cases even not available, the TMDs are saved as grids, and TMDlib provides appropriate tools for interpolation between the grid points (where the type of evolution is indicated):

allFlavPDF

Multidimensional Linear Interpolation in x, \(k_t\) and \(\mu \) is used for PB and CCFM-type TMDs

Pavia

Interpolation based on Lagrange polynomials of degree three, performed through APFEL++ [57, 58]

InterpolationKS

Multidimensional cubic spline interpolation in x, \(k_t\) and \(\mu \), based on GSL implementation, is used for KS-type TMDs (see Table 1)

Table 1 Available uPDF/TMD parton sets in TMDlib
Full size table

The parameterizations of TMDs in TMDlib are explicitly authorized for each distribution by the corresponding authors. A list of presently available TMD sets is given in Table 1. No explicit QCD evolution code is included: the parameterizations are as given in the corresponding references.

The grids of each selected TMD set are read into memory once (the I/O time depends on the size of the grid). Each TMD set is initialized as a separate instance of the TMD class, which is created for each different TMD set, for example for uncertainty sets, or if several different TMD sets are needed for the calculation. The memory consumption of TMDlib is determined by the size of the TMDgrids. Optionally, TMDgrids can be loaded separately, avoiding large memory consumption.

It is the philosophy of TMDlib  that the definition of TMD grids is left free, but a few examples are given: the grids for the PB, CCFM and KS TMD sets are stored in form of text tables, the grids of the Pavia type TMDs are stored and read via the YAML frame. The method of interpolation and the corresponding accuracy of the interpolation is left under control of the authors of the relevant TMD sets.

Fig. 2
figure 2

Transverse momentum distribution \(x{{\mathcal {A}}}(x,k_t,\mu )\) at \(x=0.08\) and \(\mu =100\) GeV obtained with PB-NLO-HERAI+II-2018-set2 [45] (left) and PV17 [47] (right)

Full size image

3.2 Uncertainty TMD sets

The estimation of theoretical uncertainties is an important ingredient for phenomenological applications, and uncertainties from PDFs and TMDs play a central role. The uncertainties of TMDs are estimated usually from the uncertainties of the input parameters or parameterization. There are two different methods commonly used: the Hessian method [59] which is applied if the parameter variations are orthogonal or the Monte Carlo method providing Monte Carlo replicas [60, 61]. The specific prescriptions on how to calculate the uncertainties for a given TMD set should be found in the original publication describing the TMDs.

An example of TMDs with uncertainty band is shown in Fig. 2 for the PB set as well as for the PV17 set. The parameters of intrinsic \(k_t\)- distribution are part of the fit of PV17, while they are not fitted for the PB sets (see discussion in Ref. [45]).

3.3 TMDplotter

TMDlib provides also a web-based application for plotting TMD distributions – TMDplotter, plotting tools for collinear pdfs are available under e.g. [62] or [63]. In Fig. 3 (left) a comparison of the transverse momentum distributions of different TMD sets is shown, and in Fig. 3 (right) the gluon-gluon luminosity calculation for the integrated TMD sets PB-NLO-HERAI+II-2018-set1 [45] at \(\mu =100\) GeV compared with the one obtained from HERAPDF2.0 is shown (the curves obtained from PB-NLO-HERAI+II-2018-set1 and HERAPDF2.0 overlap).

Fig. 3
figure 3

TMDplotter examples: (left) comparison of the transverse momentum distributions of different TMD sets, (right) gluon-gluon luminosity calculation using integrated TMD sets (the curves from PB-NLO-HERAI+II-2018-set1 and HERAPDF2.0 overlap)

Full size image

TMDplotter is available at http://tmdplotter.desy.de/.

4 New features

Having described in Sect. 2 the general framework of the TMDlib library, we here stress the main new features of TMDlib2 compared with the previous version [40] of the library. The most important development concerns the inclusion of many new TMD sets. This is achieved through a new and more efficient method to add input files. The method is flexible enough that it will allow new sets, which may become available in the future, to also be included in a straightforward manner. Another extremely important development of TMDlib2, which plays an essential role in paving the way to systematic TMD phenomenology at colliders and fixed target machines, is that the uncertainties associated with TMD sets are now accessible through the library. This was not the case in the first version [40]. It is the first time that TMD uncertainties become available in a library tool. While uncertainties on collinear PDFs are nowadays available through several different web-based resources, TMDlib2 is at present the unique tool which contains the full existing information on uncertainties on TMD sets, and makes it readily accessible. As such, we expect it to be an essential tool for phenomenological studies of TMDs and comparisons with experimental data.

To sum up, the main new features of TMDlib2 compared to the earlier version of the library are as follows.

  • TMDlib2 makes use of C++ classes, and the different sets corresponding to uncertainty sets or sets corresponding to different parameterizations are read once and initialized as different instances, allowing to load many sets into memory;

  • information about TMD sets is read via YAML from the TMD info files, containing all metadata;

  • including new TMD sets is simplified with the new structure of the input sets;

  • the TMD sets are no longer part of the TMDlib distribution, but can be downloaded via TMDlib-getdata, distributed with TMDlib2.

5 TMDlib documentation

TMDlib is written in C++ , with an interface for access from FORTRAN code. The source code of TMDlib is available from http://tmdlib.hepforge.org/  and can be installed using the standard autotools sequence configure, make, make install, with options to specify the installation path and the location of the LHAPDF PDF library [44], and the ROOT data analysis framework library [64] (which is used optionally for plotting). If ROOT is not found via root-config, the plotting option is disabled. After installation, TMDlib-config gives access to necessary environment variables.

5.1 Description of the program components

5.1.1 Initialization in C++

TMDinit(name)

To initialize the dataset specified by its name name. A complete list of datasets available in the current version of TMDlib with the corresponding name is provided in Table 1

TMDinit(name,irep)

To initialize a given irep replica of the dataset name

TMDinit(iset)

To initialize the dataset specified by its identifier iset

5.1.2 Initialization in Fortran

TMDinit(iset)

To initialize the dataset specified by its identifier iset

TMDset(iset)

To switch to the dataset iset

5.1.3 Access to TMDs in C++

TMDpdf(x, xbar, kt, mu)

Vector double-type function returning an array of 13 variables for QCD parton densities with the values of \(x{{\mathcal {A}}}(x,{{{\bar{x}}}},k_t,\mu )\): at index \(0,\dots ,5\) is \({\bar{t}},\dots ,{\bar{d}}\), at index 6 is the gluon, and at index \(7,\dots ,12\) is \(d,\dots ,t\) densities

TMDpdf(x, xbar, kt, mu, xpq)

Void-type function filling an array of 13 variables, xpq, with the values of \(x{{\mathcal {A}}}(x,{{{\bar{x}}}},k_t,\mu )\): at index \(0,\dots ,5\) is \({\bar{t}},\dots ,{\bar{d}}\), at index 6 is the gluon, and at index \(7,\dots ,12\) is \(d,\dots ,t\) densities

TMDpdf(x, xbar, kt, mu, uval, dval, sea, charm, bottom, gluon, photon)

Void-type function to return \(x{{\mathcal {A}}}(x,{\bar{x}},k_t,\mu )\) at \(x, {\bar{x}}, k_t,\mu \) for valence u-quarks uval, valence d-quarks dval, light sea-quarks s, charm-quarks c, bottom-quarks b, gluons glu and gauge boson photon

TMDpdf(x, xbar, kt, mu, up, ubar, down, dbar, strange, sbar, charm, cbar, bottom, bbar, gluon, photon)

To return \(x{{\mathcal {A}}}(x,{\bar{x}},k_t,\mu )\) at \(x, {\bar{x}}, k_t,\mu \) for the partons up, ubar, down, dbar, strange, sbar, charm, cbar, bottom, bbar, gluon and gauge boson photon (if available)

TMDpdf(x, xbar, kt, mu, up, ubar, down, dbar, strange, sbar, charm, cbar, bottom, bbar, gluon, photon, Z0, W+,W-,higgs)

To return \(x{{\mathcal {A}}}(x,{\bar{x}},k_t,\mu )\) at \(x, {\bar{x}}, k_t,\mu \) for the partons up, ubar, down, dbar, strange, sbar, charm, cbar, bottom, bbar, gluon, the gauge bosons photon, Z0, W+, W- and higgs (if available)

5.2 Access to TMDs in Fortran

TMDpdf(kf,x, xbar, kt, mu, up, ubar, down, dbar, strange, sbar, charm, cbar, bottom, bbar, gluon)

To return \(x{{\mathcal {A}}}(x,{\bar{x}},k_t,\mu )\) at \(x, {\bar{x}}, k_t,\mu \) for the partons up, ubar, down, dbar, strange, sbar, charm, cbar, bottom, bbar, gluon for the hadron flavor kf. (kf is no longer used, only kept for backward compatibility with TMDlib1)

TMDpdfEW(x, xbar, kt, mu, up, ubar, down, dbar, strange, sbar, charm, cbar, bottom, bbar, gluon, photon, Z0, W+,W-, higgs)

To return \(x{{\mathcal {A}}}(x,{\bar{x}},k_t,\mu )\) at \(x, {\bar{x}}, k_t,\mu \) for the partons up, ubar, down, dbar, strange, sbar, charm, cbar, bottom, bbar, gluon, the gauge bosons photon, Z0, W+, W- and higgs (if available)

5.2.1 Callable program components

The program components listed in this section are accessible with the same name in C++ as well as in Fortran.

TMDinfo(dataset)

Accesses information from the info file

TMDgetDesc()

Returns data set description from info file

TMDgetIndex()

Returns index number as a string of data set from info file

TMDgetNumMembers()

Returns number of members of data sets from info file

TMDgetScheme()

Returns evolution scheme of dataset from info file

TMDgetNf()

Returns the number of flavours, \(N_f\), used for the computation of \(\Lambda _{QCD}\)

TMDgetOrderAlphaS()

Returns the perturbative order of \(\alpha _\mathrm {s}\) used in the evolution of the dataset

TMDgetOrderPDF()

Returns the perturbative order of the evolution of the dataset

TMDgetXmin()

Returns the minimum value of the momentum fraction x for which the dataset initialized by TMDinit(name) was determined

TMDgetXmax()

Returns the maximum value of the momentum fraction x for which the dataset initialized by TMDinit(name) was determined

TMDgetQmin() (TMDgetQ2min())

Returns the minimum value of the energy scale \(\mu \) (in GeV), (\(\mu ^2\) (in \(\hbox {GeV}^2\))) for dataset

TMDgetQmax() (TMDgetQ2max())

Returns the maximum value of the energy scale \(\mu \) (in GeV) , (\(\mu ^2\) (in \(\hbox {GeV}^2\))) for dataset

TMDgetExtrapolation_Q2()

Returns the method of extrapolation in scale outside the grid definition as specified in info file

TMDgetExtrapolation_kt()

Returns the method of extrapolation in \(k_t\) outside the grid definition as specified in info file

TMDgetExtrapolation_x()

Returns the method of extrapolation in x outside the grid definition as specified in info file

TMDnumberPDF(name)

Returns the identifier as a value of the associated name of the dataset

TMDstringPDF(index)

Returns the name associated with index of the dataset

5.3 TMDlib calling sequence

In the following simple examples are given to demonstrate how information from the TMD parton densities can be obtained in C++ and Fortran.

  • in C++

    figure a

  • in Fortran (using multiple replicas of the TMD)

    figure b

5.4 Installation of TMD grids

The TMD grid files are no longer automatically distributed with the code package, but have to be installed separately. A list of available TMD parameterizations is given in Table 1.

figure c

5.5 Structure of TMD grids

In TMDlib2 the TMDgrids are stored in directories with the name of a given TMD set which is located in installation_prefix/share/tmdlib/TMDsetName. Every such directory contains info file and grid file(s), for example for a TMD set called test:

figure d

The info file contains general information on the TMDset (inspired by a similar strategy in LHAPDF), as described below, and the file(s) test_0000.dat contains the TMDgrid. If further replicas are available (for example for uncertainties), the files are numbered as test_0000.dat, test_0001.dat,..., with the number of files given by NumMembers as described below.

The info file must contain all the information to initialize and use the TMDgrid:

figure e

The meaning of most entries is obvious from their name, with TMDScheme different structures for the TMD grids can be selected:

PB TMD:

used for the PB TMD series

PB TMD-EW:

used for the PB TMD series including electroweak particles

Pavia TMDs:

used for the PaviaTMD (or similar TMD) series

6 Summary

The authors of this manual set up a collaboration to develop and maintain TMDlib and TMDplotter, respectively a C++ library for handling different parameterizations of uPDFs/ TMDs and a corresponding online plotting tool. The aim is to update these tools with more uPDF/TMD parton sets and new features, as they become available and are developed. TMDlib2 improves on the efficiency of previous versions, allows for simpler C++ interfaces and simplifies the inclusion of new uPDF/TMD sets.