NNLOJET manual

5 Runcard syntax

5.1 General syntax

The general syntax of a runcard file follows these rules:

• •Each statement should be written on a separate line. Wrapping across multiple lines requires the line continuation symbol & at the end of the line and at the beginning of the following line.

• •Comments start with an exclamation mark ! , all characters that follow ! will be ignored by the parser.

• •The parser does not distinguish between upper- and lower-case letters, with the exception of observable names (see below) which are case sensitive but typically defined in lower case.

• •Assignments follow the syntax <var> = <val>[...] with any white space allowed in between and possibly extra options provided inside square brackets [...] .

• •Lists are specified as [<val1>,<val2>,...,<valN>] and white space will be ignored.

• •The types of literals follow Fortran syntax:

  • – BOOL : boolean variables, .true. or .false. ;

  • – INT : integers;

  • – DBLE : double precision variables, e.g. 13.6d3 and 1d-8 ;

  • – STR : string expression made up with any ASCII characters (without any quotes).

The runcard is composed of the following separate blocks:

• •PROCESS [required]: defines and specifies the process;

• •RUN [required]: defines the technical parameters and settings;

• •PARAMETERS : defines the input settings and parameter values;

• •SELECTORS [required]: defines the event and object selectors for the fiducial cross section;

• •HISTOGRAMS : defines output histograms (observable, binning, extra options);

• •SCALES [required]: specifies the set of renormalization and factorization scales for simultaneous evaluation;

• •CHANNELS [required]: selects the subprocesses to be activated;

as well as optional single-line settings:

• •REWEIGHT : weight to bias the sampling of the integrator;

• •PDF_INTERPOLATION : switch on dynamical interpolation for PDFs.

They are described in detail in Sect. 5.3.

5.2 Observables

The event selectors for the fiducial cross section, settings for the histograms and values for the scales are specified in terms of observables. The list of available observables depends on the selected process.

Each observable is implemented in a generic way and is internally assigned a unique identifier. Dimensionful observables are defined in $[\mathrm{GeV}]$ units. In order to obtain a list of all available observables for a given process with a short description one simply needs to run NNLOJET --listobs <process_name> in the terminal. For example, for $\mathrm{Z}$-plus-jet production, it returns:

$ NNLOJET --listobs ZJ
*
*   > jet acceptance cuts <
*
*   jets_pt
*   jets_y
*   jets_abs_y
*   jets_eta
*   jets_abs_eta
*   jets_et
*   jets_min_dr_lj
*
*    > process-specific observables <
*
*   ptlm       --- transverse momentum of l-
*   Elm        --- energy of l-
*   ylm        --- (pseudo-)rapidity of l-
*   abs_ylm    --- |ylm|
*   ptlp       --- transverse momentum of l+
*   Elp        --- energy of l+
*   ylp        --- (pseudo-)rapidity of l+
*   abs_ylp    --- |ylp|
*   ptl1       --- transverse momentum of leading lepton
*   yl1        --- (pseudo-)rapidity of leading lepton
*   abs_yl1    --- |yl1|
...

Internally, each observable has an attribute to query its validity for an event it was evaluated for. The validity state is typically concerned with observables that are defined based on objects that can vary in multiplicity, such as jets. For example, the transverse momentum of the sub-leading jet in the event ptj2 is only valid if the event contains at least two jets after applying all event and jet selection cuts. For a process that only requires one jet to be resolved, e.g. $\mathrm{Z}+jet$, this observable can thus become invalid. While the observable in this case is technically of one order lower in the perturbative accuracy, it is still possible to evaluate it. It is important to keep in mind the validity state of an observable when defining selectors and histograms, as will be discussed below.

5.2.1 Reweighting functions

Reweighting functions define multiplicative factors that are applied to the event weight within a limited context. They can be used in different parts of the runcard to influence various behaviours of the run or the output, as described in Sects. 5.3.5 and 5.3.8. The syntax for reweighting functions is:

<observable> ** <power> * <factor> + <offset>

• •The <observable> is specified using the unique string identifier;

• •The <power> , <factor> and <offset> are DBLE ;

• •The symbols ** , * and + can only appear once with any white space ignored;

• •The ordering of variables and observables does not matter.

For example, all the following lines constitute valid reweighting functions:

2            ! a constant factor
ptz          ! an observable
ptz**2       ! an observable raised to a power
3*ptz        ! a rescaled observable
ptz+1        ! an observable with an offset
3*ptz**2+1   ! any combination of the above

5.3 Runcard sections

In the following, the runcard input is illustrated in detail. Mandatory settings are highlighted as “[required]”.

5.3.1 Process block

The PROCESS block defines the process to be calculated and is specified following the general syntax:

PROCESS <process_name>
<option1> = <value1>[<parameters1>]
<option2> = <value2>[<parameters2>]
...
END_PROCESS

The currently supported process names (<process_name>) at NNLO can be obtained with the NNLOJET --listprocs command. As described in Sect. 4, they are:

• •Z , ZJ : production of $\mathrm{Z}$-boson (plus up to one jet), including $\mathrm{Z}$-boson decay to two charged leptons;

• •Wp , Wm , WpJ , WmJ : production of ${\mathrm{W}}^{+}$/${\mathrm{W}}^{-}$-boson (plus up to one jet), including $\mathrm{W}$-boson decay to a charged lepton and a neutrino;

• •H , HJ : production of $\mathrm{H}$-boson (plus up to one jet), excluding $\mathrm{H}$-boson decay;

• •H2 , H2J : production of $\mathrm{H}$-boson (plus up to one jet) with decay mode to two colour singlets. Specifically:

  • – HTO2P , HTO2PJ with decay mode to a $\gamma$ pair;

• •H3 , H3J : production of $\mathrm{H}$-boson (plus up to one jet) with decay mode to three colour singlets. Specifically:

  • – HTO2L1P , HTO2L1PJ with Dalitz decay mode to ${\ell }^{+}{\ell }^{-}+\gamma$;

• •H4 , H4J : production of $\mathrm{H}$-boson (plus up to one jet) with decay mode to four colour singlets. Specifically:

  • – HTO4E , HTO4EJ with decay mode to two light lepton pairs with the same flavour;

  • – HTO2E2MU , HTO2E2MUJ with decay mode to two light lepton pairs with different flavour;

  • – HTO2L2N , HTO2L2NJ with decay mode to a lepton plus a neutrino pair mediated by $W$-bosons;

• •GJ : production of photon plus one jet;

• •GG : production of photon pair;

• •JJ : production of two jets;

• •eeJJ , eeJJJ : production of up to three jets in electron–position colliders;

• •epLJ , epLJJ : production of up to two jets in neutral-current lepton-proton collisions, resulting in lepton-plus-jets final states (no distinction is made between leptons and antileptons);

• •epNJ , epNJJ : production of up to two jets in charged-current lepton-proton collisions, resulting in neutrino-plus-jets final states;

• •epNbJ , epNbJJ : production of up to two jets in charged-current antilepton-proton collisions, resulting in antineutrino-plus-jets final states.

The process names refer to the underlying Born-level process, which can then be used to compute derived quantities with the same final-state kinematics but without identified jets. For example, ZJ also allows the computation of the transverse momentum distribution of the $\mathrm{Z}$-boson, with the jet requirement being replaced by a non-zero transverse momentum of the $\mathrm{Z}$-boson due to partonic recoil. Likewise, GJ contains inclusive photon production, JJ single-inclusive-jet production, and eeJJJ the three-jet-like event shapes.

The currently supported options and values for the PROCESS block are listed in the following.

A collider choice is specified with:

• •collider = STR [required]: using pre-defined collider setups:

  • – proton–proton collider: PP ;

  • – proton–antiproton collider: PAP ;

  • – proton–electron collider (deep-inelastic scattering): PE ;

  • – electron–positron collider: EPEM ;

• •beam1 = STR , beam2 = STR : More flexibility is provided by setting the beams individually with the following allowed values: P ($\mathrm{p}$), AP ($\overline{\mathrm{p}}$), EM (${\mathrm{e}}^{-}$), EP (${\mathrm{e}}^{+}$), HE (${}_2^4\mathrm{He}$), LI (${}_3^7\mathrm{Li}$), C (${}_6^{12}\mathrm{C}$), O (${}_8^{16}\mathrm{O}$), CU (${}_{29}^{64}\mathrm{Cu}$), AU (${}_{79}^{197}\mathrm{Au}$), PB (${}_{82}^{208}\mathrm{Pb}$). Setting beam1 and beam2 will override the collider choice. It is the responsibility of the user to choose a compatible (nuclear) PDF set for each beam in the RUN block described below. The centre-of-mass energy is specified for the nucleon–nucleon system. In case of an asymmetric beams setup (beam1 $\ne$ beam2), NNLOJET will further perform the appropriate longitudinal boost of the hadronic centre-of-mass system. The collider coordinate system is then chosen such that beam1 is in the positive $z$ direction.

The collider energy is provided by setting either one of the following options:

• •sqrts = DBLE [required]: definition of centre-of-mass energy;

• •Ebeam1 = DBLE , Ebeam2 = DBLE : definition of energy of individual beams instead of specifying sqrts , allows for asymmetric collisions. Setting Ebeam1 and Ebeam2 will override the sqrts value.

The standard jet reconstruction algorithms are implemented directly in NNLOJET and can be specified with the following options:

• •jet = <algo>[<options>] : specification of jet algorithm; the option in DBLE specifies the jet-resolution parameter. The algorithm can be chosen with the following syntax:

  • – anti-$k_T$ algorithm  [94]: antikt[DBLE] ;

  • – Cambridge–Aachen algorithm  [95] (longitudinally invariant): ca[DBLE] ;

  • – $k_T$ algorithm  [96, 97] (longitudinally invariant): kt[DBLE] ;

  • – Durham algorithm  [98] (for ${\mathrm{e}}^{+}{\mathrm{e}}^{-}$ collisions): durham[DBLE] ;

  • – Jade algorithm  [99] (for ${\mathrm{e}}^{+}{\mathrm{e}}^{-}$ collisions): jade[DBLE] ;

  • – No algorithm required: none ;

• •jet_exclusive = BOOL : jet exclusive flag, specifying whether events with more jets than required should be rejected (default: .false.);

• •jet_recomb = STR : jet-recombination scheme: V4 , to combine jets by adding the 4-vector of the momenta, and ET , to combine jets with $E_T$ as the weights (default: V4).

Several optional settings in the PROCESS block are only relevant for specific classes of processes:

• •V_NC = STR : restriction on virtual neutral-current gauge-bosons. Options for STR :

  • – ZGAMMA (default): both $\mathrm{Z}$ bosons and photons are allowed in the amplitudes;

  • – GAMMA : only photons, useful for example in DIS processes;

  • – Z: only $\mathrm{Z}$ bosons are allowed;

• •L_NC = STR : decay mode of $\mathrm{Z}$ bosons decay to leptons. Values:

  • – NU : decay to neutrinos (single family) $\mathrm{Z}\to \nu \overline{\nu }$;

  • – L (default): decay to charged leptons (single family) $\mathrm{Z}\to {\ell }^{+}{\ell }^{-}$.

• •decay_type = INT : definition of heavy-particle decay types used in the phase-space generator. It is set automatically for each process and unstable particle, but can be overridden using the following INT values:

  • – 0: use $\mathrm{d}{M}^2/M^2$;

  • – 1: use resonance parametrization;

  • – 2: narrow width inserted, delta function;

  • – 3: on-shell heavy particle, no decay.

The isolation of photons and leptons is defined using the following options:

• •photon_isolation / lepton_isolation : define the isolation of non-QCD particles, as documented in detail in  [76]. It allows the combination of several isolation prescriptions that must be simultaneously fulfilled, using the syntax
  <isolation> = <algo1>[<params1>] + <algo2>[<params2>] + ... .
  For lepton isolation, only fixed-cone isolation is supported. For photon isolation, the following isolation prescriptions are available:

  • – none : no isolation required;

  • – fixed : fixed-cone isolation. The non-QCD particle with transverse momentum $p_T$ is isolated if the hadronic transverse energy in a cone of size $R_{\mathrm{c}\mathrm{o}\mathrm{n}\mathrm{e}}$ does not exceed

    $$

    $$\begin{array}{}\text{(9)}& E_T^{\max }=E_T^{\mathrm{const}}+ϵp_T.\end{array}$$

    Parameters:

    • * R_cone : isolation-cone size $R_{\mathrm{c}\mathrm{o}\mathrm{n}\mathrm{e}}$;

    • * ET_const : $E_T^{\mathrm{const}}$;

    • * ETmax_epsilon : $ϵ$;

  • – smooth : smooth-cone isolation  [73]. The non-QCD particle with transverse momentum $p_T$ is isolated according to a profile function $\mathcal{X}(R,n)$ that permits a decreasing amount of hadronic energy $E_T^{\mathrm{smooth}}=\mathcal{X}(R,n)E_T^{\max }$ within sub-cones of radius $R<R_{\mathrm{cone}}$ and $E_T^{\max }$ as defined in (9):

    $$

    $$\mathcal{X}(R,n)={\left[\frac{1-\cos (R)}{1-\cos (R_{\mathrm{cone}})}\right]}^n.$$

  • – hybrid_smooth : hybrid isolation. A variant of the smooth-cone isolation defined in  [100]. The following parameters can be specified:

    • * ET_const : $E_T^{\mathrm{const}}$;

    • * ETmax_epsilon : $ϵ$;

    • * R_cone : the smooth-cone size or the outer fixed-cone size in hybrid isolation;

    • * n : parameter $n$ in profile function;

    • * R_inner : inner smooth-cone size in case hybrid isolation is used, where R_inner < R_cone must be satisfied;

  • – democratic : democratic isolation. The jet clustering procedure includes the non-QCD object, which is then called isolated if it carries more than a fraction $z_{\mathrm{cut}}$ of the transverse energy of the jet it is assigned to. Parameters:

    • * zcut : threshold of transverse-energy fraction between the photon and the jet. If the transverse energy fraction is larger than zcut , the clustered particles are considered as one photon; if the fraction is smaller than zcut , the clustered particles are considered as one jet.

• •photon_recomb = DBLE : angular distance $R$ below which two photons are recombined;

• •photon_fragmentation = STR : definition of photon fragmentation setup. The parameteter specifies the parametrization of the photon fragmentation functions:

  • – ALEPH : a simple parametrization obtained from a one-parameter fit by ALEPH  [101];

  • – BFG0 , BFGPERT : BFG0  [77];

  • – BFG1 , BFGI : BFGI  [77];

  • – BFG2 , BFGII : BFGII  [77].

Finally, several PROCESS settings are relevant only for DIS:

• •pol = DBLE : polarization fraction of incoming lepton beam (default: 0.0);

• •lab_ordereta = BOOL : a flag to order jets in the laboratory frame in $\eta$ (default: .false.);

• •dis_eventshapes = DBLE : minimum value of hadronic energy in an event for DIS event shapes (default: 0.0);

• •eprc = BOOL : switch to use a running electromagnetic coupling evaluated at the scale $Q^2$ (default: .false.);

• •dis_frame = STR : definition of the DIS frame, with the following options:

  • – FIXT : fixed target system;

  • – BREIT : Breit frame;

  • – LAB : the laboratory frame.

  The default is BREIT for epLJJ , epNJJ , epNbJJ and LAB for epLJ , epNJ , epNbJ .

5.3.2 Run block

This block defines technical settings for the NNLOJET execution. Runs in NNLOJET consist of two phases:

• •The warmup phase aims to construct VEGAS grids that are adapted to the integrand at hand (event-selection cuts, regions of larger weights etc.). The VEGAS grids are initialized as uniform distributions in the raw random variables, and the calculation proceeds in multiple iterations. After each iteration, the grids are adapted according to the accumulated cross section for importance sampling. The events sampled during the warmup phase do not enter the final result. For performance reasons, histogram filling and scales beyond the central scales are deactivated.

• •The production phase performs the Monte Carlo integration for the total and differential cross sections according to the VEGAS grid that was adapted during the warmup. The VEGAS grids are frozen at this stage and will no longer be updated.

To run NNLOJET, at least one of the two phases needs to be activated. The production phase can only be performed if a dedicated VEGAS grid was produced by a warmup phase beforehand. When the nnlojet-run workflow is used to run NNLOJET, the warmup and production phases are automatically handled and can be omitted from the runcard.

The general syntax for the RUN block is:

RUN <run_name>
<option1> = <value1>[<parameters1>]
<option2> = <value2>[<parameters2>]
...
END_RUN

The field <run_name> specifies the user-defined name for the run and it is used to name the output files. The <run_name> for a production phase must be the same as the respective warmup phase for the VEGAS grids to be properly loaded. The options are:

• •PDF = <PDF_set>[<member>] [required]: specification of a PDF set according to the naming convention of LHAPDF  [29]. For asymmetric colliders, separate PDFs can be specified for each beam by instead providing PDF1 and PDF2 individually. The optional <member> = INT parameter specifies the PDF member. It defaults to 0 , i.e. the central member of the PDF set. Note that the PDF is required also for electron-positron collisions, for the running of ${\alpha }_{\mathrm{s}}$;

• •iseed = INT : specification of the seed for the random number generator (default: $1$).;

• •warmup = <ncall>[<niter>] : specification of warmup run settings. <ncall> = INT indicates the number of integrand evaluations per iteration and <niter> = INT the number of iterations. Instead of <niter> , it is also possible to specify auto , which will automatically distribute the total number of <ncall> evaluations of the integrand into a staggered batch of iterations (at least one of warmup or production needs to be specified);

• •production = <ncall>[<niter>] : specification of production run settings; in particular, <ncall> = INT indicates the number of integrand evaluations per iteration and <niter> = INT the number of iterations (at least one of warmup or production needs to be specified);

• •tcut = DBLE : technical cutoff defined relative to the squared partonic centre-of-mass energy $\hat{s}$. Events with any invariant smaller than tcut $\cdot \hat{s}$ are rejected in the phase-space integration. The technical cut must be chosen considerably smaller than the smallest scale that is resolved by the final-state definition (default: 1d-8);

• •reset_vegas_grid = BOOL : switch for overwriting the local VEGAS grid; when set to .true. , the warmup run will be started with a new uniform VEGAS grid; when set to .false. , the warmup run will continue starting from the previous VEGAS grid if one exists (default: .false.).

NNLOJET also provides some optional optimization settings which can speed up the calculation when used properly. They are in general only intended for expert users. The following optimization settings are available:

• •angular_average = BOOL : switch to average over azimuthal angle rotations in unresolved regions, required to make antenna subtraction terms strictly local (default: .true.);

• •cache_kinematics = BOOL : switch to cache all kinematics of mapped momentum sets (default: .false.);

• •scale_coefficients = BOOL : switch to internally use a decomposition of weights into scale coefficients of scale logarithms. Necessary for scale overrides (default: .false.);

• •multi_channel = <N> : option for multi-channel adaption over individual channels. For the definition of channels, see 5.3.7. The parameter <N> is of type INT . If <N> is $0$, every existing channel is evaluated in each sampled phase-space point. Multi-channeling is activated by selecting a non-zero <N> , leading to a selective evaluation of different channels by distributing events among them. An importance sampling is applied by evaluating those channels more often which have a larger contribution to the cross section. The strategy for dividing the channels into groups is determined by the value of <N> . If <N> is positive, channels will be grouped such that every phase-space point will evaluate a subset of <N> channels. If <N> is negative, the total number of groups is specified, i.e. the integrator will attempt to divide active channels into $|$ <N> $|$ equal-sized groups (default $0$);

• •lips_reduce = BOOL : switch for the reduced phase-space mode, a variant of the phase-space generator that exploits the permutation symmetries of a specific process (default: .false.).

5.3.3 Parameters block

The PARAMETERS block defines the Standard Model input parameters of the calculation. The general syntax follows the pattern:

PARAMETERS
<variable>[<spec>] = <value>
<option> = <value>
...
END_PARAMETERS

The attributes of particle <particle> are set with the syntax <attribute>[<particle>] . <particle> may assume any acronym from Table 1 as its value. The possible attributes are listed in the following, with the default value taken from [102]:

• •mass[<particle>] = DBLE : the mass of the particle, which can be set for the massive particles in the Standard Model and the proton. The mass values correspond to the mass scheme defined below;

• •width[<particle>] = DBLE : the decay width of the particle. $\mathrm{Z}$, $\mathrm{W}$, $\mathrm{H}$ and top quark are supported. The widths correspond to the scheme defined below.

Further parameters and prescriptions can be set as follows:

• •hard_photon_alpha0 = BOOL : switch to use ${\alpha }_0$ as the electroweak coupling for resolved photons in photon-production processes (default: .false.);

• •scheme[<scheme>] = STR : the specification of schemes in mass, width and electroweak coupling. The options for <scheme> are:

  • – MV : define the mass scheme for electroweak gauge bosons. Possible values are:

    • * OS (default): on-shell scheme;

    • * POLE : pole scheme;

    • * MSBAR : $\overline{\mathrm{MS}}$-scheme;

  • – GV : define the width schemes for electroweak gauge bosons. Possible values are:

    • * NWA : for the narrow-width approximation;

    • * CMS : for complex-mass scheme;

    • * NAIVE (default): for naive fixed-width scheme;

    • * RUN: for running on-shell scheme;

    • * POLE : for pole scheme;

  • – ALPHA : the electroweak coupling prescription. Possible values are:

    • * GMU (default): $G_{\mu }$ scheme, derived from the Fermi constant and the $\mathrm{Z}$ and $\mathrm{W}$ masses (override default value with GF = DBLE);

    • * FIX : fixed scheme (override default value with alpha = DBLE);

    • * ALPHA0: ${\alpha }_0$ scheme (override default value with alpha0 = DBLE);

    • * ALPHAMZ: $\alpha (M_{\mathrm{Z}})$ scheme (override default value with alphaMZ = DBLE);

• •CKM = STR : the specification of the CKM matrix. Users can change the entries by modifying driver/core/CKM.f90 if necessary. The available options are:

  • – IDENTITY (default): diagonal CKM matrix;

  • – FULL : Wolfenstein parameters [103];

  • – CABIBBO : Cabibbo mixing angle only [103];

  • – MCFM : the default setup of MCFM.

5.3.4 Selectors block

In NNLOJET, two types of selection criteria are distinguished: object-level and event-level criteria. Object-level criteria may be used to impose conditions on the reconstructed objects, i.e. jets and photons. For example, they allow to select jets with a minimum transverse momentum or within a specific rapidity range. Any object that does not fulfill these conditions is omitted from the event record.

Event-level criteria define which event candidates should be used to calculate cross sections and fill histograms. If an event-level criterion is not fulfilled, the entire event candidate is discarded. Typical examples are a minimum number of jets per event, additional constraints on the leading jet, or constraints on leptons.

The SELECTORS block specifies the object-level and event-level selection criteria. It is encapsulated by

SELECTORS
! put selectors here
END_SELECTORS

It can be left empty if the process is well-defined (corresponding to a fully-inclusive event selection) or filled with any number of selector statements of the form:

<type> <observable> min=<val_min> max=<val_max>

• •The <type> can be either select or reject . In case partially valid observables are expected, one can use select_if_valid or reject_if_valid . An event is selected only if it passes all select statements and is rejected by none of the reject statements.

• •The <observable> is specified using a pre-defined string identifier. Possible values for a given process can be checked using the --listobs query of the NNLOJET command. Object-level cuts are listed in the photon cuts and jet acceptance cuts sections, while event-level selectors are listed in the process-specific observables section.

• •It is only necessary to specify at least one of the two assignments for min and max . If unspecified, the other boundary defaults to $\pm \mathrm{\infty }$. If both are specified, the order of the assignments is irrelevant.

Selector statements can be given in any order. Since each selector will internally generate a new object, it is better to have as few lines as possible. It is therefore preferable to write

select ylp min = -5 max = +5   ! --> accept [-5, +5]

or

select abs_ylp max = +5       ! --> accept |y| < 5 => [-5, +5]

instead of

select ylp min = -5                 ! --> accept [-5, +infinity]
select ylp max = +5                 ! --> accept [-infinity, +5]

It is possible to define OR groups, where all the selector statements inside the group have ‘or’ relations. The groups are encapsulated by

OR
! put selectors here
END_OR

It is not possible to use OR groups on object-level selectors.

A common example use case of the reject type in the selectors is the exclusion of the barrel–endcap gap region that can be implemented as follows:

select abs_ylp max = +5                             ! global selector
reject abs_ylp min = +1.4442 max = +1.560           ! barrel-endcap

which is more intuitive and cleaner than the alternative only using select and an OR group:

OR
select ylp min = -5      max = -1.560
select ylp min = -1.4442 max = +1.4442
select ylp min = +1.560 max = +5
END_OR

5.3.5 Histograms block

The HISTOGRAMS block specifies all the histograms to be filled during the run. It is encapsulated between the lines

HISTOGRAMS
! put histograms here
END_HISTOGRAMS

It can be populated with histogram statements of the following two types

<observable> nbins=<val_nbins> min=<val_min> max=<val_max>
<observable> [edge0,edge1,edge2,...,edgeN]

• •The first version corresponds to a histogram with uniformly-space (linear or logarithmic) bins, whereas the second version specifies the bin boundaries as a list and allows for flexible bin edges.

• •The <observable> is specified using the unique string identifier and events giving rise to an invalid attribute (see Sect. 5.2 for the definition) are skipped in the accumulation.

• •As a decorator to the <observable> specification, it is possible to specify a file-name override using the notation <observable> > <dat_name> . If this specification is omitted, the file name will use the observable name by default. This option is needed if there exist multiple histograms that bin the same observable (see example below) in order to avoid file-name clashes.

• •For cross sections, the special name cross can be used instead of the histogram statements above. NNLOJET will always register such a histogram by default so that user-defined cross section statements must always be of the form cross > <dat_name> with a file-name override. It should be noted that histograms keep track of overflows such that the cross section can also be calculated from the histogram contents by summing the bins and the overflow. It is therefore rarely necessary to define a cross section histogram explicitly.

Every histogram statement can further be supplemented by optional settings. The available options are:

• •fac = <rwg_fct> : multiply all weights passed to the histogram with a generic reweighting function following the syntax described in Sect. 5.2.1;

• •mu0 = (DBLE * )<observable> : override scale. This options sets the both factorization and renormalization scale to the specified value. Only available if scale_coefficients = .true. is set in the RUN block;

• •binning = STR : switch between linear and logarithmic binning, in case equal-sized bins are used. Possible values are:

  • – LIN (default): linear binning;

  • – LOG : logarithmic binning;

• •output_type = INT : specify the luminosity-breakdown type: a value of 0 will only output the numbers for the total (default), while a value of 1 will in addition provide numbers broken down into separate partonic luminosities: (e.g. $\overline{q}\overline{q}$, $\mathrm{g}\overline{q}$, $q\overline{q}$, $\overline{q}\mathrm{g}$, $\mathrm{g}\mathrm{g}$, $q\mathrm{g}$, $\overline{q}q$, $\mathrm{g}q$, $qq$). See Sect. 6.3 for further description of the output data files;

• •cumulant = INT : option for cumulant distributions with possible values:

  • – 0 (default): standard differential distribution $\mathrm{d}\sigma /\mathrm{d}$ <obs> ;

  • – -1 : cumulant distribution ${\int }_{o_{\min }}^{o_i}\mathrm{d}\sigma /\mathrm{d}$ <obs> ;

  • – +1 : cumulant distribution ${\int }_{o_i}^{o_{\max }}\mathrm{d}\sigma /\mathrm{d}$ <obs> .

  The values $o_{\min }$ and $o_{\max }$ respectively correspond to the lower and upper bounds of the histogram and the user must ensure that it covers the desired kinematic range. Observable values outside of this range are ignored in the cumulant output and are instead collected in an overflow bin.

A further optional specification is given by histogram selectors which can be assigned right below a histogram definition as follows:

<observable> ...
HISTOGRAM_SELECTORS
! put selectors here
END_HISTOGRAM_SELECTORS

with the selector syntax defined in Sect. 5.3.4 but without the support of OR blocks. This allows to generate multi-differential distributions in a flexible way as follows:

ptz > ptz_bin1 nbins=75 min=0 max=150
HISTOGRAM_SELECTORS
select abs_yz max=0.3
END_HISTOGRAM_SELECTORS
ptz > ptz_bin2 nbins=30 min=0 max=90
HISTOGRAM_SELECTORS
select abs_yz min=0.3 max=1
END_HISTOGRAM_SELECTORS
ptz > ptz_bin3 [0,10,15,20,25,30,40,50,60,80,100]
HISTOGRAM_SELECTORS
select abs_yz min=1 max=2
END_HISTOGRAM_SELECTORS

Here, the modified file names (> ptz_bin<i>) are needed in order to avoid file name clashes. Furthermore, we can choose different ptz -binnings for each yz bin. The histogram file will correspond precisely to what is specified in the runcard, for the example above this means

$$\begin{array}{}\text{(10)}& \mathtt{\text{ptz\_bin1}}:& & {\frac{\mathrm{d}\sigma }{\mathrm{d}{p}_{\mathrm{T},\mathrm{Z}}}|}_{|y_{\mathrm{Z}}|<0.3}& \ne \frac{{\mathrm{d}}^2\sigma }{\mathrm{d}{p}_{\mathrm{T},\mathrm{Z}}\mathrm{d}{y}_{\mathrm{Z}}}\text{(in the first }{y}_{\mathrm{Z}}\text{ bin)}.\end{array}$$ In order to obtain the double-differential distribution on the right-hand-side of this expression one has to further divide the histogram contents by the bin-width for $y_{\mathrm{Z}}\in [-0.3,0.3]$ which is $0.6$ in this case.

The way invalid observables (see Sect. 5.2 for the definition) are treated within the histogram selectors deserves special care. Once an observable is used in a select or reject statement within the HISTOGRAM_SELECTORS block, it is implicitly assumed that it must be valid for all events that are considered for the histogram filling. This means that if an invalid observable is encountered for such a specification, the weight associated with that event is discarded in the accumulation of the histogram. If this is not the desired behaviour, it is instead possible to use the select_if_valid or reject_if_valid specifications that allow to ignore the selector in case the observable is evaluated with an invalid attribute.

Some observables are defined in a composite manner, i.e. they can potentially induce multiple bookings to the same histogram from different observables. For this purpose, NNLOJET defines the concept of a composite histogram that follows the following syntax:

COMPOSITE > <dat_name> ... <opt_comp>
<obs1> <opt1>
<obs2> <opt2>
...
END_COMPOSITE

where ... at the top can be the fixed-bin or the variable-bin specification and <opt_comp> the optional specifications both described above. The composite histogram will be filled with the sum of all the sub-histograms defined inside the block, where each can specify individual options, i.e. fac and mu0 as described above. Both the composite histogram as well as the sub-histograms can further be supplemented by histogram selectors. In case the observable of the sub-histogram is invalid, it will simply be skipped in the accumulation.

A non-trivial example of this feature is the inclusive-jet distribution in a specific rapidity bin and a jet-based scale setting such as the jet-$p_T$. In this case, we must register as many sub-histograms as the maximum possible number of jets (invalid observables will be skipped), each dressed with a selector block and further ensure that for each sub-histogram, the weight is re-assembled for the value of the respective jet $p_T$ as the scale:

COMPOSITE > ptj0_ybin0 [0,10,20,50,100,200,300,500,700,1000]
ptj1 mu0=ptj1
HISTOGRAM_SELECTORS
select abs_yj1 min=0 max=.5
END_HISTOGRAM_SELECTORS
ptj2 mu0=ptj2
HISTOGRAM_SELECTORS
select abs_yj2 min=0 max=.5
END_HISTOGRAM_SELECTORS
ptj3 mu0=ptj3
HISTOGRAM_SELECTORS
select abs_yj3 min=0 max=.5
END_HISTOGRAM_SELECTORS
ptj4 mu0=ptj4
HISTOGRAM_SELECTORS
select abs_yj4 min=0 max=.5
END_HISTOGRAM_SELECTORS
END_COMPOSITE

5.3.6 Scales block

The SCALES block specifies all scale combinations that should be evaluated simultaneously during the run. It is encapsulated by the block:

SCALES
! put scales here
END_SCALES

and requires at least one scale specification to be present. The first entry will be considered the central scale that is also used for the VEGAS grid adaption. Up to six additional scale specifications can be supplied. A scale specification constitutes a line in the block that specifies the factorization scale ${\mu }_F$ (muF) and the renormalization scale ${\mu }_R$ (muR)

muF = <sclF>        muR = <sclR>

In case a process that contains a fragmentation function is run, the associated factorization scale (${\mu }_A$) can be set separately using a pair muF = [<sclF>,<sclA>] , which otherwise will default to ${\mu }_A={\mu }_F$ in case only a single scale is specified. The scale <scl> can be set in two ways:

• •fixed scale: <scl> = DBLE in units of $[\mathrm{GeV}]$;

• •dynamical scale: <scl> = <obs> or DBLE*<obs> , where <obs> is the unique STR identifier of an observable.

5.3.7 Channels block

In NNLOJET a channel constitutes a specific scattering process, uniquely determined by the external states and the crossing, further decomposed into gauge-invariant colour factors. For example, the leading-colour $\mathcal{O}(N_c^2)$ contribution to the scattering sub-process $gg\to q\overline{q}$ constitutes one channel of the LO dijet production process at hadron colliders.

When the workflow described in Sect. 6.1 is used to perform the calculation, the channel information will be automatically populated, such that the user does not need to specify them manually and instead can keep this block empty. Therefore, the information provided here is intended for expert users and/or to assist in debugging the workflow calculations.

The CHANNELS block specifies all the channels to be computed during the run by giving a list of identifiers. The VEGAS integrand is defined as the sum of the channels specified in this block (optionally grouped according to the value of the multi_channel flag, see Sect. 5.3.2). The process-id number associated with a given channel can be found in the respective driver/process/XYZ/selectchannelXYZ.f source file of the associated process XYZ. In addition, the following abbreviations are defined to simplify the specification:

• •ALL ;

• •LO , NLO , NNLO ;

• •V , R ;

• •VV , RV , RR , RRa , RRb .

The suffices a and b for the double-real (RR) contribution only exist for specific processes and correspond to a separation of the phase space into two disjoint parts with optimized sampling strategies. The general syntax for the channel block is as follows:

CHANNELS region = STR
! put list of process id's / wildcards here
END_CHANNELS

In addition to specifying the sub-process on individual lines, any number of (white-space separated) process id’s can be given in a single line as well. The region option only matters for the double-real contribution and processes where a phase-space separation was introduced; allowed values in this case are: a for the RRa piece, b for the RRb piece, and all (default) to include both.

5.3.8 Single-line Optional Settings

In a runcard, the user is further able to specify single-line options independent of any blocks mentioned above. All single-line settings are optional.

Reweight

The re-weighting feature has a one-line syntax

REWEIGHT <rwg_fct>

where the specification of the reweighting function <rwg_fct> follows the syntax described in Sect. 5.2.1. This function is evaluated for every event and used to re-scale the weights returned to the VEGAS integrator. It can therefore be used to increase or decrease the relevance of certain kinematic regions in the VEGAS grid adaptation, allowing for a more uniform phase-space coverage for distributions that span over several orders of magnitude. The re-weighting does not apply to the event booking into histograms. Similarly, once the VEGAS grid is frozen, i.e. during the production stage of the calculation, this option has no impact on the produced output.

PDF Interpolation

The PDF interpolation option is a single-line setting to switch on a one-dimensional cubic spline interpolation (fixed $x$, interpolation in ${\mu }_{\mathrm{F}}$), which aims to reduce the number of calls to LHAPDF. By default it is not activated but it can be switched on with the following syntax:

PDF_INTERPOLATION stepfac = DBLE

where the optional argument stepfac specifies the uniform spacing of the interpolation grid in the $\log ({\mu }_{\mathrm{F}})$ space as a multiplicative factor. The default value is 2 .