TMDlib is hosted by Hepforge, IPPP Durham
TMDLIB manual

TMDlib and TMDplotter: library and plotting tools for
Transverse Momentum Dependent parton distributions

F. Hautmann
Rutherford Appleton Laboratory, Dept. of Theoretical Physics,
University of Oxford, UK
H. Jung
DESY, Hamburg, FRG,
University of Antwerp, Belgium
P. Connor
DESY, Hamburg, FRG
M. Kr"a mer
DESY, Hamburg, FRG
P. J. Mulders
Department of Physics and Astronomy, VU University Amsterdam, and Nikhef, the Netherlands
E. R. Nocera
Universit`a degli Studi di Milano and INFN Milano, Italy
T. C. Rogers
C.N. Yang Institute for Theoretical Physics, Stony Brook University, Department of Physics, Southern Methodist University, Dallas, Texas, USA
A. Signori
Department of Physics and Astronomy, VU University Amsterdam, and Nikhef, the Netherlands

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[59][6][48].

The same basic picture applies to other (semi-)inclusive processes, like semi-inclusive DIS (SIDIS), and $e^+e^-$ 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 $e^+e^-$ annihilation[40],[41],[43],[42],[44],[45],[80],[82],[83],[79],[78],[52],[32]. 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- $x$) limit[24],[75],[35], [66] . In this context, the functions encoding the hadronic structure are more often referred to as unintegrated parton distribution functions (uPDFs), see e.g. Refs.[11],[10],[69],[51],[50],[49],[68],[64],[62] .

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.[74][71][17][53][60][9][4][86] are rather different.

TMDlib is a tool to make easier phenomenological comparisons of different uPDFs and TMDs.

Theoretical framework

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.

TMD factorization and evolution

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 $\Lambda_{\rm QCD}$, 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):

\[ W^{\mu \nu} \sim {\cal H}^{\mu \nu}(Q;\mu) \sum_a \int d^2 {\bf b}_{\perp} e^{-i {\bf q}_{\perp} \cdot {\bf b}_{\perp}} f^{a,T} (x,{\bf b}_{\perp};\zeta_f,\mu)\ D^{a \to h} (z,{\bf b}_{\perp};\zeta_D,\mu)\ + Y_{\rm SIDIS}({\bf q}_\perp,Q) + {\cal O}((\Lambda_{\rm QCD}/Q)^{p})\ , (1) \]

where ${\cal H}$ is the hard part, $a$ is the flavour of the struck parton, $T$ is the target hadron, $h$ is the detected hadron, $x$ and $z$ are the light-cone momentum fractions, and ${\bf b}_{\perp}$ is Fourier conjugate of the transverse momentum ${\bf q}_{\perp}$. The function $f^{a,T} (x,{\bf b}_{\perp};\zeta_f,\mu)$ is a TMD PDF while $D^{a \to h} (z,{\bf b}_{\perp};\zeta_D,\mu)$ is a TMD FF. The scale $\mu$ is a renormalization group scale, $\zeta_{f,D}$ are rapidity evolution scales. $Q$ is the hard scale that enters into the hard vertex. In SIDIS $Q = \sqrt{-q^2}$, where $q$ is the four-momentum of the exchanged virtual photon.

The term $Y_{\rm SIDIS}({\bf q}_\perp,Q)$ is a correction for the region of $q_\perp \sim Q$ where a separation into TMD PDFs is not valid, and all transverse momentum is generated inside the hard scattering. This so-called $Y$- term is calculable in collinear factorisation. With it included, the corrections are suppressed by powers of $\Lambda_{\rm QCD}/Q$, point-by-point in ${\bf q}_\perp$, as indicated by the last term, where $p > 0$. 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[20],[21] and the expression of the hadronic tensor modifies accordingly[81],[16],[14] .

TMD parton distributions or fragmentation functions depend on two auxiliary scales, $\zeta_{f,D}$ an $\mu$, and they satisfy evolution equations with respect to both of them. The evolution with respect to $\zeta_{f}$ and $\zeta_D$ corresponds to Collins-Soper (CS) evolution and is determined by a process-independent soft factor[36],[37],[71],[67],[45],[52],[29],[30],[31],[54] . The scales $\zeta_f,\ \zeta_D$ must satisfy the constraint $\zeta_f \zeta_D = Q^4$. The evolution in $\mu$, instead, is determined by standard renormalisation group methods.

When the energy range covered by the experimental data is not large (see, e.g., Ref.[5],[3] ) 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.[85],[9] . 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.[12][13] . There, fixed scale fits from[84],[7],[8],[39],[38] are combined with traditional CSS style fits from Refs.[74],[71].

High-energy factorization and evolution

A form of TMD factorisation holds at high energy[24],[27],[28] and has been applied to several processes in photon-hadron, lepton-hadron and hadron-hadron collisions. For instance, the high-energy factorisation expresses the heavy-quark leptoproduction cross section in terms of the TMD gluon density via well-prescribed, calculable perturbative coefficients[27] . This framework is extended to deep-inelastic structure functions in[23],[22] . Perturbative applications of the method include the resummation of small- $x$ logarithmic corrections to DIS to all orders in $\alpha_s$ at leading and next-to-leading $\ln x$ level[23],[22],[33],[56] . In hadron-hadron scattering, high-energy factorisation has been applied to processes such as heavy flavour and Higgs boson production[27],[66] .

In the framework of high-energy factorisation[24],[27],[28] the DIS cross section can be written as a convolution in both longitudinal and transverse momenta of the unintegrated parton density function ${\cal A}\left(x,\kt,\mu\right)$ with off-shell partonic matrix elements

\[ \sigma_j ( x , Q^2 ) = \int_x^1 d z \int d^2k_t \ \hat{\sigma}_j( x , Q^2 , { z} , k_t ) \ {\cal A}\left( { z} ,\kt, \mu \right) \, (2) , \]

where the DIS cross sections $\sigma_j$, ($j= 2 , L$) are related to the structure functions $F_2$ and $F_L$ by $\sigma_j = 4 \pi^2 F_j / Q^2$, and the hard-scattering kernels ${\hat \sigma}_j$ of Eq.(2) are $k_t$-dependent.

The factorisation formula, Eq.(2), allows for resummation of logarithmically enhanced $x\to 0 $ 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 $\mu$ and on the factorisation scheme[23],[22] .

Realistic applications of this approach at collider energies require matching of $x \to 0$ contributions with finite- $x$ contributions. To this end, the evolution of the gluon uPDF ${\cal A} $ is obtained by combining the resummation of small- $x$ logarithmic contributions[76],[57],[15] with medium- and large- $x$ contributions to parton splitting[59],[6],[48] , according to the CCFM evolution equations[34],[25],[26],[77] .

The cross section $\sigma_j$ ( $j= 2 , L$) is usually computed in a Fixed Flavour Number (FFN) scheme, where the photon-gluon fusion process ( $\gamma^* g^* \to q \bar{q}$) is included. The masses of the quarks are explicitly included with the light and heavy quark masses being free parameters. In addition to $\gamma^* g^* \to q\bar{q}$, the contribution from valence quarks is included via $\gamma^* q \to q$ by using CCFM evolution of valence quarks[46],[47],[63] . A fit of CCFM uPDFs to the combined DIS precision data[1],[2] has been recently presented in Ref.[63] using the evolution given in Ref.[65] . Earlier CCFM fits to DIS were presented in Ref.[70] . In Ref.[58] the unintegrated gluon distribution has been obtained by means of a saturation ansatz.

TMDlib documentation

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 autotools sequence:

make install

with options to specify the installation path and the location of the LHAPDF PDF library[19]web:LHAPDF and the ROOT data analysis framework library[18],web:ROOT (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 makefiles} is provided by executing the TMDlib-config script.

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 $x$, $\mu$ and $k_\perp$); 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 first step consists in initialising the desired uPDF/TMD set. Initialisation assigns the chosen uPDF/TMD set, specified by its name, an identifying number proper to that set. This number is stored into memory and called each time the identification of the uPDF/TMD set is needed by any TMDlib internal function.

The TMD fit of Ref.[85] is provided as a Monte Carlo ensemble of $N_{\mathrm{rep}}=200$ 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 ( $b_T$-distribution). For other uPDF/TMD sets, these options are not available and, if specified, they will be ignored.

    The second step consists in calling the desired function. Specifically, the light-cone momentum fractions $x^+$ and $x^-$ (often set $x^-=0$) carried by the parton, the parton transverse momentum $k_t$ (in GeV), the energy scale $\mu$ (in GeV) and the flavour code identifying the target are the input variables. Returned is the momentum weighted parton distribution.

Both the initialisation and the call to the uPDF/TMD parton set are performed via function overloading of, respectively

  • TMDinit;
  • TMDpdf;

Additional useful code, including collection of methods and examples, can be found in the src folder.

The TMDlib library is released together with the online plotter platform TMDplotter, also available at