Table of Contents
TMDlib and TMDplotter: library and plotting tools for
Department of Physics, Southern Methodist University, Dallas, Texas, USA
Transverse-momentum-dependent distributions (TMDs)
are extensions of collinear parton distributions and are important in high-energy physics from both theoretical and phenomenological points of view. In this manual we introduce the library TMDlib , a tool to collect transverse-momentum-dependent parton distribution functions (TMD PDFs) and fragmentation functions (TMD FFs) together with an online plotting tool, TMDplotter. We provide a description of the program components and of the different physical frameworks the user can access via the available parameterisations.
The Quantum Chromodynamics (QCD) interpretation of high-energy particle reactions requires a simultaneous treatment of processes at different energy scales. Factorisation theorems provide the mathematical framework to properly separate the physical regimes. For instance, when two protons collide in a Drell-Yan (DY) event the high-energy partonic cross section is described with a perturbative QCD expansion and the soft physics underlying the structure of the hadrons is treated with parton distribution functions (PDFs), supplemented by QCD evolution. `‘Evolution’', in this context, refers to the scale dependence of parton distributions (and similar non-perturbative objects) that arises in a detailed treatment of factorisation in QCD perturbation theory. A classic example of a consequence of QCD evolution is the violation of Bjorken-scaling in inclusive deep-inelastic lepton-hadron scattering (DIS), predicted by the Dokshitzer-Gribov-Lipatov-Altarelli-Parisi (DGLAP) evolution equations   .
The same basic picture applies to other (semi-)inclusive processes, like semi-inclusive DIS (SIDIS), and annihilation into hadrons. A PDF describes the likelihood for finding a parton of a particular momentum inside an incoming hadron. In processes with observed hadrons in the final state, fragmentation functions (FFs) enter to describe the transition from a partonic state to an observed final-state hadron.
For sufficiently inclusive processes, only the component of parton momentum collinear to the momentum of its parent hadron is relevant at leading power (leading twist) in the hard scale. Factorisation theorems for such processes are traditionally called collinear factorisation theorems. In less inclusive processes, however, sensitivity to the partonic motion transverse to the direction of the parent hadron can become important. In such cases, the PDFs and FFs must carry information about transverse parton momentum in addition to the collinear momentum. One must introduce Transverse-momentum-dependent (TMD) PDFs and FFs and use them in the context of new factorisation theorems, called TMD factorisation theorems. TMD factorisation has been formulated for a number of semi-inclusive processes including SIDIS, DY and annihilation , , , , , , , , , , , , . For particular processes in hadronic collisions, like heavy flavour or heavy boson (including Higgs) production, TMD factorisation has also been formulated in the high-energy (small- ) limit , , ,  . In this context, the functions encoding the hadronic structure are more often referred to as unintegrated parton distribution functions (uPDFs), see e.g. Refs. , , , , , , , ,  .
The presence of a large variety of TMD factorisation and evolution frameworks complicates efforts to compare different TMD PDF/FF and uPDF parameterisations. In some cases, the differences arise because different formalisms employ similar TMD concepts, but are tailored to specific physical applications. An example is the difference between the Collins-Soper-Sterman (CSS) style of TMD factorisation compared with the high-energy TMD factorisation style. The former is designed for semi-inclusive processes differential in a particular physical transverse momentum and with a finite and non-zero ratio between the hard scale and the overall energy. The latter (high-energy TMD factorisation) is designed for the limit of a fixed hard scale and very high energies. Moreover, within each category there are also competing subcategories of approaches. For instances, the detailed phenomenological methods that employ a CSS-style of approach in Refs.         are rather different.
TMDlib is a tool to make easier phenomenological comparisons of different uPDFs and TMDs.
In this section, we briefly describe two different commonly-used frameworks for factorisation and evolution of parton distributions. Specifically, we discuss TMD and high-energy factorisation theorems and evolution equations.
When one hard scale enters a high-energy process (like the invariant mass of the exchanged virtual photon in DIS) and the relevant transverse momenta are integrated over, one applies collinear factorisation to separate the hard partonic physics from the soft hadronic physics. When sensitivity to intrinsic transverse momentum is important, one must go beyond the collinear framework to factorise perturbative and non-perturbative dynamics. For example, this is the case in processes with observed transverse momenta in the final states, like SIDIS and DY lepton pair production at low transverse momentum. In these cases the low transverse momentum provides greater access to novel QCD dynamics as compared to the collinear case. If the observable transverse momenta are much larger than , then often the cross section may be expressed entirely in collinear factorisation, though supplemented by transverse momentum resummation.
Feynman rules allow for a decomposition of the cross section into a contraction of hadronic and leptonic tensors. Where applicable, factorisation theorems separate
non-perturbative and hard contributions within the hadronic tensor. In the TMD case, distribution and fragmentation functions are introduced, whose properties depend on the polarisations of the target and/or produced hadrons, the partonic polarisations, and the twist order. For example, in fully unpolarised SIDIS at leading twist the hadronic tensor is factorised into a convolution of one unpolarised TMD PDF (for the incoming target hadron) and one unpolarised TMD FF (for the final state hadron):
where is the hard part, is the flavour of the struck parton, is the target hadron, is the detected hadron, and are the light-cone momentum fractions, and is Fourier conjugate of the transverse momentum . The function is a TMD PDF while is a TMD FF. The scale is a renormalization group scale, are rapidity evolution scales. is the hard scale that enters into the hard vertex. In SIDIS , where is the four-momentum of the exchanged virtual photon.
The term is a correction for the region of where a separation into TMD PDFs is not valid, and all transverse momentum is generated inside the hard scattering. This so-called - term is calculable in collinear factorisation. With it included, the corrections are suppressed by powers of , point-by-point in , as indicated by the last term, where . Taking into account all the possible combinations of polarisation (parton, target and detected hadron), there are ten TMD PDFs and eight TMD FFs at leading-twist ,  and the expression of the hadronic tensor modifies accordingly , ,  .
TMD parton distributions or fragmentation functions depend on two auxiliary scales, an , and they satisfy evolution equations with respect to both of them. The evolution with respect to and corresponds to Collins-Soper (CS) evolution and is determined by a process-independent soft factor , , , , , , , , ,  . The scales must satisfy the constraint . The evolution in , instead, is determined by standard renormalisation group methods.
When the energy range covered by the experimental data is not large (see, e.g., Ref. ,  ) fits of TMD PDFs and FFs can be performed without taking into account effects induced by evolution. These fits rely essentialy on a simple parton model approach and are oriented towards investigations of hadron structure at a relatively low-energy scale. Recent examples are Ref. ,  . In order to explore the evolution of hadron structure with the energy scale, these fixed scale fits can be incorporated into a Collins-Soper-Sterman (CSS) style of factorisation theorem like Eq.(1), as described in Refs.   . There, fixed scale fits from , , , , 
in photon-hadron, lepton-hadron and hadron-hadron collisions. For instance, the high-energy factorisation
the heavy-quark leptoproduction cross section in terms of the TMD gluon density via well-prescribed, calculable perturbative coefficients  . This framework is extended to deep-inelastic structure functions in ,  . Perturbative applications of the method include the resummation of small- logarithmic corrections to DIS to all orders in at leading and next-to-leading level , , ,  . In hadron-hadron scattering, high-energy factorisation has been applied to processes such as heavy flavour and Higgs boson production ,  .
the DIS cross section can be written as a convolution in both longitudinal and transverse momenta
of the unintegrated parton density function
with off-shell partonic matrix elements
where the DIS cross sections ) are related to the structure functions and by , and the hard-scattering kernels of Eq.(2) are -dependent.
The factorisation formula, Eq.(2), allows for resummation of logarithmically enhanced contributions to all orders in perturbation theory, both in the hard-scattering coefficients and in the parton evolution, taking into account the full dependence on the factorisation scale and on the factorisation scheme ,  .
Realistic applications of this approach at collider energies require matching of contributions with finite- contributions. To this end, the evolution of the gluon uPDF is obtained by combining the resummation of small- logarithmic contributions , ,  with medium- and large- contributions to parton splitting , ,  , according to the CCFM evolution equations , , ,  .
The cross section ( ) is usually computed in a Fixed Flavour Number (FFN) scheme, where the photon-gluon fusion process ( ) is included. The masses of the quarks are explicitly included with the light and heavy quark masses being free parameters. In addition to , the contribution from valence quarks is included via by using CCFM evolution of valence quarks , ,  . A fit of CCFM uPDFs to the combined DIS precision data , 
has been recently presented in Ref.  using the evolution given in Ref.  . Earlier CCFM fits to DIS were presented in Ref.  . In Ref.  the unintegrated gluon distribution has been obtained by means of a saturation ansatz.
TMDlib is a C++ library which provides a framework and an interface to a collection of different uPDF/TMD parameterisations. The parameterisations of TMDs in TMDlib are explicitly authorised for distribution in TMDlib by the authors. No explicit QCD evolution code is included: the parameterizations are as given in the corresponding references. In the present version of TMDlib no attempt is made to unify grid files and the interpolation procedure, both are those provided by the authors.
The source code of TMDlib can be installed using the standard
with options to specify the installation path and the location of the LHAPDF PDF library  [webb] and the ROOT data analysis framework library , [weba] (which is used optionally for plotting). If ROOT is not found via root-config, the plotting option is disabled.
Useful information about the installation and the determination of compiler flags in custom
The up-to-date list of these functions and their description are provided at PDF sets .
The TMDlib calling sequence is: Initialisation (selecting the desired uPDFs/TMDs); Call (producing the uPDF/TMD for partons at , and ); Information (displaying details about the initialised uPDFs/TMDs).
Here, we restrict ourselves to discussing the basic steps required to handle the available uPDF/TMD distributions within TMDlib.
The TMD fit of Ref.  is provided as a Monte Carlo ensemble of equally probable replicas, as both a grid with polynomial interpolation and the analytic form with the
best-fit parameters for each replica. The user should specify the replica to be initialised and whether he would like to use the grid or the parameterisation via the input variables irep and imode respectively. Through imode it is also possible to select the Fourier transform of the TMD PDF, namely the distribution in transverse coordinate space ( -distribution). For other uPDF/TMD sets, these options are not available and, if specified, they will be ignored.
Both the initialisation and the call to the uPDF/TMD parton set are performed via function overloading of, respectively
Additional useful code, including collection of methods and examples, can be found in the
The TMDlib library is released together with the online plotter platform TMDplotter, also available at
Generated on Fri Jun 7 2019 18:46:38 for TMDlib by 1.8.15