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 {\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 [65]), which are then integrated using the adaptive Monte Carlo routine VEGAS [66].
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 [63, 67]. Some of the one-loop subprocess matrix elements were taken from the MCFM
code [20], in particular for processes involving vector bosons [68]. The two-loop virtual corrections to all processes with four-point kinematics or beyond contain various special functions, in particular harmonic polylogarithms [69]
and their generalizations. These are evaluated using HPLOG [70], TDHPL [71] and CHAPLIN [72], which are all
included as part of the NNLOJET distribution, with explicit consent of the respective code authors and thus in line with the underlying licensing provisions. The evaluation of parton distributions and of the strong coupling constant is performed using the standard
LHAPDF [73] 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 [73] 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.