Tutorials | FMNLO

Prerequisites on running the program include MG5_aMC@NLO and possibly LHAPDF6 library for invoking fragmentation functions therein.

The recommended version of MG5_aMC@NLO is 3.4.0 which has been tested thoroughly.

The package FastJet is also required which can be installed within MG5_aMC@NLO.

The paths to MG5_aMC@NLO and LHAPDF6 can be set separately at the top of Makefile under the main directory FMNLOv1.0 and of mgen.sh under directory mgen.

The HOPPET v1.2.1-devel program has been modified and integrated into the source file. Users should cite original works of those external programs properly together with this publication.

One can simply run make under the main directory to compile all ingredients.

Note that in order to retain full quark-flavor information in MG5_aMC@NLO, one has to modify madgraph/core/helas_objects.py in the native MG directory to disable group of identical processes. That can be achieved by simply replace True with False at the 3486-th line of the file. We mentioned earlier that the FKS subtractions have not been implemented for NLO calculations of DIS processes in MG5_aMC@NLO. However, we are working toward an alternative solution that will come with the next release of FMNLO.

To calculate the parton fragmentation in a typical hard scattering process, two subsequent steps are followed.

First, inside the directory mgen one invokes MG5_aMC@NLO with a customized analysis routine (a module) to generate the interpolation tables storing matrices of coefficient functions. We have released modules for all processes included in this study. New modules can be added easily following existing examples.

In mgen, the subdirectory common contains the common ingredients needed for all modules. Each module has a separate directory including init.sh for MG5_aMC@NLO command, pre_cuts.f for the selection of relevant phase space, and analysis_HwU_pp.f containing the main analysis routine.

Various input parameters are specified in the file proc.run. Each line contains a record for one input variable: a character tag with the name of the variable, followed by the variable’s value. We take proc.run used for the calculation of CMS isolated-photon-tagged jet measurement as an example.

# main input for generation of NLO fragmentation grid file by MG5
process A180104895
# subgrids with name tags
grid pp
obs 4
cut 0.02
pta1 60.0
pta2 10000.0
ptj1 30.0
ptj2 10000.0
# in MG5 format
set lpp1 1
set lpp2 1
set ebeam1 2510.0
set ebeam2 2510.0
set lhaid 13100
set iseed 11
set muR_over_ref 1.0
set muF_over_ref 1.0
end

process specifies the name of the directory that contains the module to be loaded.
grid is a string indicating the name of the running job.
obs specifies different distributions to be calculated: 1 for distribution in $\zeta$, 2 for distribution in $p_{T,h}$, 3 and 4 for distributions in $\xi_{T}^{j}$ or $\xi_{T}^{\gamma(Z)}$.
cut gives the slicing parameter $\lambda$ and a value of $0.02$ is recommended.
pta1 and pta2 specify the lower and upper limit of the kinematic range of the transverse momentum of the photon.
ptj1 and ptj2 specify the lower and upper limit of the kinematic range of the transverse momentum of the jet.
Other possible inputs in this block include hrap and pth specifying the upper limit on the absolute pseudorapidity and the lower limit on the transverse momentum of the hadrons. isca determines the choice on central value of the fragmentation scale, 1 for our nominal choice of $\max{p_{T,j}}$ ($Q$) for $pp$ ($e^+e^-$) collisions, and 2 for using $p_{T,h}$ ($E_h$). Default values of all above variables are assigned via the script file mgen.sh for individual modules if not specified in proc.run.
The remaining inputs follow the same syntax as the normal MG5_aMC@NLO command, for instance, lpp1 and ebeam1 are type and energy of collision particle 1, lhaid specifies parton distribution of proton used for the calculation, etc.

The generation of fragmentation grid can be launched by the command ./mgen.sh proc.run. Note that for the same process, generation of multiple grids can be grouped into a single input file by simply repeating the two blocks after the process line. Once the generation of grid is finished, it will be stored in an upper-level directory grid, for instance with a name A180104895_pp.fmg for above example.

After generation of the grid, the calculation of physical distributions can be done within seconds by running ./fmnlo in the directory data. Input parameters at this stage are specified in the file input.card.

 1  #  loop for D fun (1/2 -> LO/NLO) | evo for D fun (0/1 -> internal/hoppet)
 2  #  followed by >=1/0 -> internal/LHAPDF | FFID | FFmember
 3  2       0
 4  0       NNFF11_HadronSum_nlo            0
 5  #  normalization | grid file | binnig file
 6  #  0/1/2 -> absolute dis./normalized to corresponding order/leading order
 7  #  can include multiple entries in several lines
 8  1 "../grid/A180104895_pp.fmg" "../grid/1801-04895.Bin"

The 3rd line specifies the order of DGLAP evolution of the fragmentation functions, 1/2 for LO and NLO respectively, followed by 0/1 for using the native evolution provided by the input fragmentation functions or evolving with HOPPET package from the initial scale $Q_0$.
The 4th line indicates the choice of fragmentation functions. A value of 0 indicates the usage of fragmentation functions from LHAPDF6 library and other integer values correspond to fragmentation functions implemented in FMNLO1.0, e.g., 1 for the NLO nominal fragmentation functions presented in this study (note one should use the NLO evolution with HOPPET concurrently), 2 for the BKK functions of unidentified charged hadrons, and 3(4) for the KKP (DSS) functions. The following two inputs specify the name and set number of the fragmentation function in the case of using LHAPDF6. Note that the value of the QCD coupling used in the evolution of fragmentation functions is set consistently. It can either be imported from LHAPDF6 or set by HOPPET with $\alpha_S(M_Z)$ fixed at 0.118. Other possibilities on the choice of fragmentation function can be implemented by modifying the source file internal.f.
The 8th line specifies choice of normalization: 0 for absolute distributions, 1 and 2 for normalized distributions to the total cross sections of corresponding order or LO respectively. The followed are the name of the pre-generated grid file for the calculation and the name of the file containing binning of the distribution. Multiple entries similar to the 8th line can be added to calculate several distributions at once. The binning is set via two-line inputs. For example, in 1801-04895.Bin,

8
0.5  1.0  1.5  2.0  2.5  3.0  3.5  4.0  4.5

the first line specifies the total number of kinematic bins and the
second line contains all nodes of the bins in sequence.

Once ./fmnlo is executed, the format of the printout can be understood easily

ID(1/x dx/dkv)     zd     zu    LO*{1,0.5,2}   NLO*{1,0.5,2}  NLO/LO
1   5.00000E-01   1.00000E+00   2.45041E-01 ..  2.61256E-01 ..  1.066 ..
2   1.00000E+00   1.50000E+00   6.69355E-01 ..  7.61367E-01 ..  1.137 ..
3   1.50000E+00   2.00000E+00   1.33705E+00 ..  1.61524E+00 ..  1.208 ..
4   2.00000E+00   2.50000E+00   2.12904E+00 ..  2.51633E+00 ..  1.182 ..
5   2.50000E+00   3.00000E+00   2.93954E+00 ..  3.23861E+00 ..  1.102 ..
6   3.00000E+00   3.50000E+00   3.65409E+00 ..  3.60505E+00 ..  0.987 ..
7   3.50000E+00   4.00000E+00   4.21952E+00 ..  3.12574E+00 ..  0.741 ..
8   4.00000E+00   4.50000E+00   2.98053E+00 ..  1.44477E+00 ..  0.485 ..

which contains the distribution at LO and NLO for three choices of the fragmentation scale $\mu_D=\{1,1/2,2\}\mu_{D,0}$ and the ratio of NLO to LO predictions for all kinematic bins specified.