TMDlib2 and TMDplotter: a platform for 3D hadron structure studies

A common library, TMDlib2, for Transverse-Momentum-Dependent distributions (TMDs) and unintegrated parton distributions (uPDFs) is described, which allows for easy access of commonly used TMDs and uPDFs, providing a three-dimensional (3D) picture of the partonic structure of hadrons. The tool TMDplotter allows for web-based plotting of distributions implemented in TMDlib2, together with collinear pdfs as available in LHAPDF.


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 µ, 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]. Such descriptions are successful for sufficiently inclusive processes, like inclusive deep-inelastic lepton-hadron scattering (DIS).
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 [38,39], 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 [40,41] and LHAPDF [42]. 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 Sec. 2, we give the main elements of the library framework. In Sec. 3 we emphasize the new features of TMDlib2 compared to the previous version. In Sec. 4 we provide the essential documentation. We summarize in Sec. 5.

2 The TMDlib framework
The TMDlib library and its new version TMDlib2 consider momentum weighted TMD parton distributions xA j (x, k t , µ) 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 µ [4]. Besides, the library also contains integrated TMDs obtained from the integration over k t , as follows In Fig. 1 (left), we show an example of integrated TMD obtained with TMDplotter for the PB-NLO-HERAI+II-2018-set1 [43], 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 [44]. 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 [45] with the corresponding collinear distribution of MMHT2014 [46]. 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. [22], with small-x resummation of logarithmic accuracy (α s ln x) m to all orders m in α s . Perturbative calculations of the matching coefficients at finite order have recently been carried out through N 3 LO in Refs. [47,48]. Other aspects of the relationship between integrated TMDs and collinear PDFs are studied e.g. in [19,25,26,[49][50][51][52]. We refer the reader to the overview [4], and references therein, for further discussions of this topic.
In TMDlib2 the densities are defined more generally as momentum weighted distributions xA(x,x, k t , µ), where x,x are the (positive and negative) light-cone longitudinal momentum fractions [49,[52][53][54]. In some of the applicationsx is set explicitly to zero, while in other casesx = 0 means that it is implicitly integrated over.

Grids and Interpolation
Since the analytic calculation of TMDs as a function of the longitudinal momentum fraction x (we neglectx in the following), the transverse momentum k t and the scale µ 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 µ is used for PB and CCFM-type TMDs. Pavia Interpolation based on Lagrange polynomials of degree three, performed through APFEL++ [55,56].
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 Tab. 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.

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 [57]    is applied if the parameter variations are orthogonal or the Monte Carlo method providing Monte Carlo replicas [58,59]. 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. [43]).

TMDplotter
TMDlib provides also a web-based application for plotting TMD distributions -TMDplotter, plotting tools for collinear pdfs are available under e.g. [60] or [61]. 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 [43] at µ = 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).

New features
Having described in Sec. 2 the general framework of the TMDlib library, we here stress the main new features of TMDlib2 compared with the previous version [38] 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 [38]. 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; 8 • 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.

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 [42], and the ROOT data analysis framework library [62] (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.

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 Tab. 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.

Initialization in Fortran
TMDinit(iset) To initialize the dataset specified by its identifier iset.

TMDset(iset)
To switch to the dataset iset.

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 Λ QCD .

TMDgetOrderAlphaS()
Returns the perturbative order of α 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.
Returns the maximum value of the energy scale µ (in GeV) , (µ 2 (in 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.

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 Tab. 1.

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: /local/share/tmdlib> ls test test.info test_0000.dat 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: 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

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.