NNLOJET manual

$\newcommand{\footnotename}{footnote}$ $\def \LWRfootnote {1}$ $\newcommand {\footnote }[2][\LWRfootnote ]{{}^{\mathrm {#1}}}$ $\newcommand {\footnotemark }[1][\LWRfootnote ]{{}^{\mathrm {#1}}}$ $\let \LWRorighspace \hspace $ $\renewcommand {\hspace }{\ifstar \LWRorighspace \LWRorighspace }$ $\newcommand {\TextOrMath }[2]{#2}$ $\newcommand {\mathnormal }[1]{{#1}}$ $\newcommand \ensuremath [1]{#1}$ $\newcommand {\LWRframebox }[2][]{\fbox {#2}} \newcommand {\framebox }[1][]{\LWRframebox } $ $\newcommand {\setlength }[2]{}$ $\newcommand {\addtolength }[2]{}$ $\newcommand {\setcounter }[2]{}$ $\newcommand {\addtocounter }[2]{}$ $\newcommand {\arabic }[1]{}$ $\newcommand {\number }[1]{}$ $\newcommand {\noalign }[1]{\text {#1}\notag \\}$ $\newcommand {\cline }[1]{}$ $\newcommand {\directlua }[1]{\text {(directlua)}}$ $\newcommand {\luatexdirectlua }[1]{\text {(directlua)}}$ $\newcommand {\protect }{}$ $\def \LWRabsorbnumber #1 {}$ $\def \LWRabsorbquotenumber "#1 {}$ $\newcommand {\LWRabsorboption }[1][]{}$ $\newcommand {\LWRabsorbtwooptions }[1][]{\LWRabsorboption }$ $\def \mathchar {\ifnextchar "\LWRabsorbquotenumber \LWRabsorbnumber }$ $\def \mathcode #1={\mathchar }$ $\let \delcode \mathcode $ $\let \delimiter \mathchar $ $\def \oe {\unicode {x0153}}$ $\def \OE {\unicode {x0152}}$ $\def \ae {\unicode {x00E6}}$ $\def \AE {\unicode {x00C6}}$ $\def \aa {\unicode {x00E5}}$ $\def \AA {\unicode {x00C5}}$ $\def \o {\unicode {x00F8}}$ $\def \O {\unicode {x00D8}}$ $\def \l {\unicode {x0142}}$ $\def \L {\unicode {x0141}}$ $\def \ss {\unicode {x00DF}}$ $\def \SS {\unicode {x1E9E}}$ $\def \dag {\unicode {x2020}}$ $\def \ddag {\unicode {x2021}}$ $\def \P {\unicode {x00B6}}$ $\def \copyright {\unicode {x00A9}}$ $\def \pounds {\unicode {x00A3}}$ $\let \LWRref \ref $ $\renewcommand {\ref }{\ifstar \LWRref \LWRref }$ $ \newcommand {\multicolumn }[3]{#3}$ $\require {textcomp}$ $\newcommand {\intertext }[1]{\text {#1}\notag \\}$ $\let \Hat \hat $ $\let \Check \check $ $\let \Tilde \tilde $ $\let \Acute \acute $ $\let \Grave \grave $ $\let \Dot \dot $ $\let \Ddot \ddot $ $\let \Breve \breve $ $\let \Bar \bar $ $\let \Vec \vec $ $\newcommand {\LWRsubmultirow }[2][]{#2}$ $\newcommand {\LWRmultirow }[2][]{\LWRsubmultirow }$ $\newcommand {\multirow }[2][]{\LWRmultirow }$ $\newcommand {\mrowcell }{}$ $\newcommand {\mcolrowcell }{}$ $\newcommand {\STneed }[1]{}$ $\newcommand {\toprule }[1][]{\hline }$ $\let \midrule \toprule $ $\let \bottomrule \toprule $ $\def \LWRbooktabscmidruleparen (#1)#2{}$ $\newcommand {\LWRbooktabscmidrulenoparen }[1]{}$ $\newcommand {\cmidrule }[1][]{\ifnextchar (\LWRbooktabscmidruleparen \LWRbooktabscmidrulenoparen }$ $\newcommand {\morecmidrules }{}$ $\newcommand {\specialrule }[3]{\hline }$ $\newcommand {\addlinespace }[1][]{}$ $\newcommand {\LWRoverlaysymbols }[2]{\mathord {\smash {\mathop {#2\strut }\limits ^{\smash {\lower 3ex{#1}}}}\strut }}$ $\def\alphaup{\unicode{x03B1}}$ $\def\betaup{\unicode{x03B2}}$ $\def\varbetaup{\unicode{x03D0}}$ $\def\gammaup{\unicode{x03B3}}$ $\def\digammaup{\unicode{x03DD}}$ $\def\deltaup{\unicode{x03B4}}$ $\def\epsilonup{\unicode{x03F5}}$ $\def\varepsilonup{\unicode{x03B5}}$ $\def\zetaup{\unicode{x03B6}}$ $\def\etaup{\unicode{x03B7}}$ $\def\thetaup{\unicode{x03B8}}$ $\def\varthetaup{\unicode{x03D1}}$ $\def\iotaup{\unicode{x03B9}}$ $\def\kappaup{\unicode{x03BA}}$ $\def\varkappaup{\unicode{x03F0}}$ $\def\lambdaup{\unicode{x03BB}}$ $\def\muup{\unicode{x03BC}}$ $\def\nuup{\unicode{x03BD}}$ $\def\xiup{\unicode{x03BE}}$ $\def\omicronup{\unicode{x03BF}}$ $\def\piup{\unicode{x03C0}}$ $\def\varpiup{\unicode{x03D6}}$ $\def\rhoup{\unicode{x03C1}}$ $\def\varrhoup{\unicode{x03F1}}$ $\def\sigmaup{\unicode{x03C3}}$ $\def\varsigmaup{\unicode{x03C2}}$ $\def\tauup{\unicode{x03C4}}$ $\def\upsilonup{\unicode{x03C5}}$ $\def\phiup{\unicode{x03D5}}$ $\def\varphiup{\unicode{x03C6}}$ $\def\chiup{\unicode{x03C7}}$ $\def\psiup{\unicode{x03C8}}$ $\def\omegaup{\unicode{x03C9}}$ $\def\Alphaup{\unicode{x0391}}$ $\def\Betaup{\unicode{x0392}}$ $\def\Gammaup{\unicode{x0393}}$ $\def\Digammaup{\unicode{x03DC}}$ $\def\Deltaup{\unicode{x0394}}$ $\def\Epsilonup{\unicode{x0395}}$ $\def\Zetaup{\unicode{x0396}}$ $\def\Etaup{\unicode{x0397}}$ $\def\Thetaup{\unicode{x0398}}$ $\def\Varthetaup{\unicode{x03F4}}$ $\def\Iotaup{\unicode{x0399}}$ $\def\Kappaup{\unicode{x039A}}$ $\def\Lambdaup{\unicode{x039B}}$ $\def\Muup{\unicode{x039C}}$ $\def\Nuup{\unicode{x039D}}$ $\def\Xiup{\unicode{x039E}}$ $\def\Omicronup{\unicode{x039F}}$ $\def\Piup{\unicode{x03A0}}$ $\def\Varpiup{\unicode{x03D6}}$ $\def\Rhoup{\unicode{x03A1}}$ $\def\Sigmaup{\unicode{x03A3}}$ $\def\Tauup{\unicode{x03A4}}$ $\def\Upsilonup{\unicode{x03A5}}$ $\def\Phiup{\unicode{x03A6}}$ $\def\Chiup{\unicode{x03A7}}$ $\def\Psiup{\unicode{x03A8}}$ $\def\Omegaup{\unicode{x03A9}}$ $\def\alphait{\unicode{x1D6FC}}$ $\def\betait{\unicode{x1D6FD}}$ $\def\varbetait{\unicode{x03D0}}$ $\def\gammait{\unicode{x1D6FE}}$ $\def\digammait{\mathit{\unicode{x03DD}}}$ $\def\deltait{\unicode{x1D6FF}}$ $\def\epsilonit{\unicode{x1D716}}$ $\def\varepsilonit{\unicode{x1D700}}$ $\def\zetait{\unicode{x1D701}}$ $\def\etait{\unicode{x1D702}}$ $\def\thetait{\unicode{x1D703}}$ $\def\varthetait{\unicode{x1D717}}$ $\def\iotait{\unicode{x1D704}}$ $\def\kappait{\unicode{x1D705}}$ $\def\varkappait{\unicode{x1D718}}$ $\def\lambdait{\unicode{x1D706}}$ $\def\muit{\unicode{x1D707}}$ $\def\nuit{\unicode{x1D708}}$ $\def\xiit{\unicode{x1D709}}$ $\def\omicronit{\unicode{x1D70A}}$ $\def\piit{\unicode{x1D70B}}$ $\def\varpiit{\unicode{x1D71B}}$ $\def\rhoit{\unicode{x1D70C}}$ $\def\varrhoit{\unicode{x1D71A}}$ $\def\sigmait{\unicode{x1D70E}}$ $\def\varsigmait{\unicode{x1D70D}}$ $\def\tauit{\unicode{x1D70F}}$ $\def\upsilonit{\unicode{x1D710}}$ $\def\phiit{\unicode{x1D719}}$ $\def\varphiit{\unicode{x1D711}}$ $\def\chiit{\unicode{x1D712}}$ $\def\psiit{\unicode{x1D713}}$ $\def\omegait{\unicode{x1D714}}$ $\def\Alphait{\unicode{x1D6E2}}$ $\def\Betait{\unicode{x1D6E3}}$ $\def\Gammait{\unicode{x1D6E4}}$ $\def\Digammait{\mathit{\unicode{x03DC}}}$ $\def\Deltait{\unicode{x1D6E5}}$ $\def\Epsilonit{\unicode{x1D6E6}}$ $\def\Zetait{\unicode{x1D6E7}}$ $\def\Etait{\unicode{x1D6E8}}$ $\def\Thetait{\unicode{x1D6E9}}$ $\def\Varthetait{\unicode{x1D6F3}}$ $\def\Iotait{\unicode{x1D6EA}}$ $\def\Kappait{\unicode{x1D6EB}}$ $\def\Lambdait{\unicode{x1D6EC}}$ $\def\Muit{\unicode{x1D6ED}}$ $\def\Nuit{\unicode{x1D6EE}}$ $\def\Xiit{\unicode{x1D6EF}}$ $\def\Omicronit{\unicode{x1D6F0}}$ $\def\Piit{\unicode{x1D6F1}}$ $\def\Rhoit{\unicode{x1D6F2}}$ $\def\Sigmait{\unicode{x1D6F4}}$ $\def\Tauit{\unicode{x1D6F5}}$ $\def\Upsilonit{\unicode{x1D6F6}}$ $\def\Phiit{\unicode{x1D6F7}}$ $\def\Chiit{\unicode{x1D6F8}}$ $\def\Psiit{\unicode{x1D6F9}}$ $\def\Omegait{\unicode{x1D6FA}}$ $\let \digammaup \Digammaup $ $\renewcommand {\digammait }{\mathit {\digammaup }}$ $\newcommand {\smallin }{\mathrel {\unicode {x220A}}}$ $\newcommand {\smallowns }{\mathrel {\unicode {x220D}}}$ $\newcommand {\notsmallin }{\mathrel {\LWRoverlaysymbols {/}{\unicode {x220A}}}}$ $\newcommand {\notsmallowns }{\mathrel {\LWRoverlaysymbols {/}{\unicode {x220D}}}}$ $\newcommand {\rightangle }{\mathord {\unicode {x221F}}}$ $\newcommand {\intclockwise }{\mathop {\unicode {x2231}}\limits }$ $\newcommand {\ointclockwise }{\mathop {\unicode {x2232}}\limits }$ $\newcommand {\ointctrclockwise }{\mathop {\unicode {x2233}}\limits }$ $\newcommand {\oiint }{\mathop {\unicode {x222F}}\limits }$ $\newcommand {\oiiint }{\mathop {\unicode {x2230}}\limits }$ $\newcommand {\ddag }{\unicode {x2021}}$ $\newcommand {\P }{\unicode {x00B6}}$ $\newcommand {\copyright }{\unicode {x00A9}}$ $\newcommand {\dag }{\unicode {x2020}}$ $\newcommand {\pounds }{\unicode {x00A3}}$ $\newcommand {\iddots }{\mathinner {\unicode {x22F0}}}$ $\newcommand {\utimes }{\mathbin {\overline {\times }}}$ $\newcommand {\dtimes }{\mathbin {\underline {\times }}}$ $\newcommand {\udtimes }{\mathbin {\overline {\underline {\times }}}}$ $\newcommand {\leftwave }{\left \{}$ $\newcommand {\rightwave }{\right \}}$

3 The NNLOJET framework

The NNLOJET code is a parton-level event generator that provides the framework for the implementation of jet production processes to NNLO accuracy in QCD, using the antenna subtraction method. It contains the event generator infrastructure (Monte Carlo phase-space integration, event handling and analysis routines) and provides the unintegrated and integrated antenna functions and the phase-space mappings for all kinematic configurations. The NNLOJET phase-space integration is based on optimized parametrizations of the respective subprocess phase spaces (described in detail in [20]), which are then integrated using the adaptive Monte Carlo routine VEGAS [21].

The implementation of processes in the NNLOJET framework requires the availability of the matrix elements for all RR, RV, and VV contributions, as well as the construction of the antenna subtraction terms. The subtraction terms have been validated by verifying their point-wise convergence to the respective subprocess matrix elements in all limits, as described in detail in [18, 22]. Some of the one-loop subprocess matrix elements were taken from the MCFM code [23], in particular for processes involving vector bosons [24]. The two-loop virtual corrections to all processes with four-point kinematics or beyond contain various special functions, in particular harmonic polylogarithms [25] and their generalizations. These are evaluated using HPLOG [26], TDHPL [27] and CHAPLIN [28], which are all included as part of the NNLOJET distribution. The evaluation of parton distributions and of the strong coupling constant is performed using the standard LHAPDF [29] interface.

3.1 External dependencies

The NNLOJET code is mainly written in modern Fortran with some modules, dependencies and driver files written in C++ and Python. Multi-threading capabilities are supported through OPENMP. The NNLOJET installation requires compilers for Fortran/C/C++, a Python 3 interpreter (minimum version 3.10), as well as CMake (minimum version 3.18) to be available on the system. In addition, LHAPDF 6 [29] must be present, ideally with the lhapdf-config executable searchable from the $PATH of the system. The user is responsible for downloading the necessary PDF sets to be used in the calculation.

3.2 Installation

The source files can be downloaded from https://nnlojet.hepforge.org as a tarball, which unpacks into a directory nnlojet-X.Y.Z. The following commands are then used to build NNLOJET:

$ cd nnlojet-X.Y.Z
$ mkdir build
$ cd build
$ cmake .. [options]
$ make [-jN]
$ make install

The compilation can be run on N cores in parallel with the -jN optional argument. The installation can be customised, by passing additional [options] to the cmake command. The syntax is -D <var>=<value> . The most relevant options are:

•CMAKE_INSTALL_PREFIX=/path/to/nnlojet : target directory where to install NNLOJET (default: /usr/local);
•CMAKE_BUILD_TYPE=Debug|Release|RelWithDebInfo|MinSizeRel : build option for NNLOJET (default: Release);
•LHAPDF_ROOT_DIR=/path/to/LHAPDF : CMake will attempt to find the library automatically but the path can be supplied manually;
•Python3_ROOT_DIR=/path/to/python : CMake will attempt to find a python installation automatically but the path can be supplied manually;
•DOKAN=ON|OFF : optionally skip the installation of the nnlojet-run script (default: ON);
•OPENMP=ON|OFF : enable OpenMP support (default: OFF).

After successful completion of the build and installation, the NNLOJET executable will be located at /path/to/nnlojet/bin/NNLOJET . It is recommended to add the location of the NNLOJET bin directory to the system $PATH variable.

For system-dependent settings (e.g. compiler preferences and options) the user should consult the cmake documentation.

3.3 Usage of NNLOJET

The recommended running mode of NNLOJET is through the Python workflow described in Section 6, which will launch the NNLOJET executable. The process selection, parameter input and output control of NNLOJET are steered through a plain-ASCII runcard file. With this file, NNLOJET can also be launched manually from the command line:

$ NNLOJET --run <runcard>

The NNLOJET executable further offers the optional command-line flags:

--help                   -   display command line options
--iseed                  -   override the seed number of the runcard
--imember                -   override the PDF member of the runcard
--listprocs              -   query all available processes
--listobs <process>       -   display list of valid observables

NNLOJET uses dynamical libraries to load individual processes and initializes many parts of the computational setup at runtime. As a result, the process to be considered, observable selectors and histograms can be specified directly in the runcard in a flexible way without requiring the re-compilation of the code. Any dimensionful parameter is given in units of $[\mathrm {GeV}]$. Cross sections outputs are in $[\mathrm {fb}]$.

Complete examples for runcards are provided together with reference output on the NNLOJET webpage https://nnlojet.hepforge.org/examples.html.