Running HEJ 2

Quick start

In order to run HEJ 2, you need a configuration file and a file containing fixed-order events. A sample configuration is given by the config.yml file distributed together with HEJ 2. Events in the Les Houches Event File format can be generated with standard Monte Carlo generators like MadGraph5_aMC@NLO or Sherpa. If HEJ 2 was compiled with HDF5 support, it can also read and write event files in the format suggested in arXiv:1905.05120. HEJ 2 assumes that the cross section is given by the sum of the event weights. Depending on the fixed-order generator it may be necessary to adjust the weights in the Les Houches Event File accordingly.

The processes supported by HEJ 2 are

  • Pure multijet production

  • Production of a Higgs boson with jets

  • Production of a W boson with jets

  • Production of jets with a charged lepton-antilepton pair, via a virtual Z boson and/or photon

  • Production of two same-sign W bosons with jets

where at least two jets are required in each case. For the time being, only leading-order input events are supported.

After generating an event file events.lhe adjust the parameters under the fixed order jets setting in config.yml to the settings in the fixed-order generation. Resummation can then be added by running:

HEJ config.yml events.lhe

Alternatively it can be more efficient to run HEJ with input events piped from a fixed order generator. To do this with e.g. Sherpa (where the event output file is specified in the Sherpa runcard as events.lhe), run:

mkfifo events.lhe
Sherpa -f Run.dat &
HEJ config.yml events.lhe

Using the default settings, this will produce an output event file HEJ.lhe with events including high-energy resummation.

When using the Docker image, HEJ can be run with:

docker run -v $PWD:$PWD -w $PWD hejdock/hej HEJ config.yml events.lhe

Settings

HEJ 2 configuration files follow the YAML format. The following configuration parameters are supported:

trials

High-energy resummation is performed by generating a number of resummation phase space configurations corresponding to an input fixed-order event. This parameter specifies how many such configurations HEJ 2 should try to generate for each input event. Typical values vary between 10 and 100.

fixed order jets

This tag collects a number of settings specifying the jet definition in the event input. The settings should correspond to the ones used in the fixed-order Monte Carlo that generated the input events.

min pt

Minimum transverse momentum in GeV of fixed-order jets.

algorithm

The algorithm used to define jets. Allowed settings are kt, cambridge, antikt, cambridge for passive. See the FastJet documentation for a description of these algorithms.

R

The R parameter used in the jet algorithm, roughly corresponding to the jet radius in the plane spanned by the rapidity and the azimuthal angle.

resummation jets

This tag collects a number of settings specifying the jet definition in the observed, i.e. resummed events. These settings are optional, by default the same values as for the fixed order jets are assumed.

min pt

Minimum transverse momentum in GeV of resummation jets. This should be between 25% and 50% larger than the minimum transverse momentum of fixed order jets set by fixed order jets: min pt. The contribution from the lower min pt fixed order jets can also be calculated separately using the require low pt jet option.

algorithm

The algorithm used to define jets. The HEJ 2 approach to resummation relies on properties of antikt jets, so this value is strongly recommended. For a list of possible other values, see the fixed order jets: algorithm setting.

R

The R parameter used in the jet algorithm.

event treatment

Specify how to treat different event types. The different event types contribute to different orders in the high-energy limit. The types are:

FKL

Specifies how to treat events respecting FKL rapidity ordering, where all but the two partons extremal in rapidity have to be gluons, e.g. u d => u g d. These configurations are dominant in the high-energy limit.

unordered

Specifies how to treat events with one gluon emission that does not respect FKL ordering, e.g. u d => g u d. In the high-energy limit, such configurations are logarithmically suppressed compared to FKL configurations.

extremal qqbar

Specifies how to treat events with a quark-antiquark pair as extremal partons in rapidity, e.g. g d => u u_bar d. In the high-energy limit, such configurations are logarithmically suppressed compared to FKL configurations.

central qqbar

Specifies how to treat events with a quark-antiquark pair central in rapidity, e.g. g g => g u u_bar g. In the high-energy limit, such configurations are logarithmically suppressed compared to FKL configurations.

non-resummable

Specifies how to treat events where resummation is currently not supported for the given rapidity ordering and/or assignment of parton flavours.

unknown

Specifies how to treat events for processes that are not implemented, e.g. di-photon production.

invalid

Specifies how to treat events that are considered unphysical. Events in this category violate one or more of the following requirements:

  • Charge conservation.

  • Four-momentum conservation.

  • Momenta of massless particles must be lightlike.

  • Incoming particles must not have transverse momentum.

The possible treatments are

  • reweight to enable resummation

  • keep to keep the events as they are up to a possible change of renormalisation and factorisation scale

  • discard to discard these events

  • abort to abort the program if one of these events is encountered

The settings keep, discard, and abort are supported for all event types. The reweight treatment is implemented for different event types depending on the considered process:

FKL

unordered

extremal qqbar

central qqbar

pure jets

Yes

Yes

Yes

Yes

Higgs + jets

Yes

Yes

No

No

W + jets

Yes

Yes

Yes

Yes

Z/γ + jets

Yes

Yes

No

No

same-sign W + jets

Yes

No

No

No
scales

Specifies the renormalisation and factorisation scales for the output events. This can either be a single entry or a list [scale1, scale2, ...]. For the case of a list the first entry defines the central scale. Possible values are fixed numbers to set the scale in GeV or the following:

  • H_T: The sum of the scalar transverse momenta of all final-state particles

  • max jet pperp: The maximum transverse momentum of all jets

  • jet invariant mass: Sum of the invariant masses of all jets

  • m_j1j2: Invariant mass between the two hardest jets.

Scales can be multiplied or divided by overall factors, e.g. H_T/2.

It is also possible to import scales from an external library, see Custom scales

scale factors

A list of numeric factors by which each of the scales should be multiplied. Renormalisation and factorisation scales are varied independently. For example, a list with entries [0.5, 2] would give the four scale choices (0.5μr, 0.5μf); (0.5μr, 2μf); (2μr, 0.5μf); (2μr, 2μf) in this order. The ordering corresponds to the order of the final event weights.

max scale ratio

Specifies the maximum factor by which renormalisation and factorisation scales may difer. For a value of 2 and the example given for the scale factors the scale choices (0.5μr, 2μf) and (2μr, 0.5μf) will be discarded.

log correction

Whether to include corrections due to the evolution of the strong coupling constant in the virtual corrections. Allowed values are true and false.

NLO truncation

Options to truncate the HEJ resummation at next-to-leading order. Used for bin-by-bin NLO reweighting.

enabled

Enable truncation. Allowed values are true and false (default).

nlo order

Set the (base) number of jets in the NLO sample. Allowed values are integers (default: 2).

unweight

Settings for unweighting events. Unweighting can greatly reduce the number of resummation events, speeding up analyses and shrinking event file sizes.

type

How to unweight events. The supported settings are

  • weighted: Generate weighted events. Default, if nothing else specified.

  • resummation: Unweight only resummation events. Each set of resummation events coming from a single fixed order event are unweighted separately according to the largest weight in the current chunk of events.

  • partial: Unweight only resummation events with weights below a certain threshold. The weight threshold is determined automatically in a calibration run prior to the usual event generation.

trials

Maximum number of trial resummation events generated in the calibration run for partial unweighting. This option should only be set for partial unweighting.

If possible, each trial is generated from a different input fixed-order event. If there are not sufficiently many input events, more than one trial event may be generated for each of them and the actual number of trial events may be smaller than requested.

Increasing the number of trials generally leads to better unweighting calibration but increases the run time. Between 1000 and 10000 trials are usually sufficient.

max deviation

Controls the range of events to which unweighting is applied. This option should only be set for partial unweighting.

A larger value means that a larger fraction of events are unweighted. Typical values are between -1 and 1.

event output

Specifies the name of a single event output file or a list of such files. The file format is either specified explicitly or derived from the suffix. For example, events.lhe or, equivalently Les Houches: events.lhe generates an output event file events.lhe in the Les Houches format. The supported formats are

  • file.lhe or Les Houches: file: The Les Houches event file format.

  • file.hepmc2 or HepMC2: file: HepMC format version 2.

  • file.hepmc3 or HepMC3: file: HepMC format version 3.

  • file.hepmc or HepMC: file: The latest supported version of the HepMC format, currently version 3.

  • file.hdf5 or HDF5: file: The HDF5-based format of arXiv:1905.05120.

random generator

Sets parameters for random number generation.

name

Which random number generator to use. Currently, mixmax and ranlux64 are supported. Mixmax is recommended. See the CLHEP documentation for details on the generators.

seed

The seed for random generation. This should be a single number for mixmax and the name of a state file for ranlux64.

analyses

Names and settings for one or more custom and Rivet event analyses.

Entries containing the rivet key are interpreted as Rivet analyses; the values corresponding to this key should be the analyses names. In addition, there is a mandatory output key which determines the prefix for the yoda output file.

For a custom analysis the plugin sub-entry should be set to the analysis file path. All further entries are passed on to the analysis. See Writing custom analyses for details.

vev

Higgs vacuum expectation value in GeV. All electro-weak constants are derived from this together with the particle properties.

particle properties

Specifies various properties of the different particles (Higgs, W or Z). All electro-weak constants are derived from these together with the vacuum expectation value.

Higgs, W or Z

The particle (Higgs, W+ or W-, Z) for which the following properties are defined.

mass

The mass of the particle in GeV.

width

The total decay width of the particle in GeV.

Higgs coupling

This collects a number of settings concerning the effective coupling of the Higgs boson to gluons. This is only relevant for the production process of a Higgs boson with jets and only supported if HEJ 2 was compiled with QCDLoop support.

use impact factors

Whether to use impact factors for the coupling to the most forward and most backward partons. Impact factors imply the infinite top-quark mass limit.

mt

The value of the top-quark mass in GeV. If this is not specified, the limit of an infinite mass is taken.

include bottom

Whether to include the Higgs coupling to bottom quarks.

mb

The value of the bottom-quark mass in GeV. Only used for the Higgs coupling, external bottom-quarks are always assumed to be massless.

require low pt jet

Restrict output to only include events which have fixed order jets with pT less than the resummation jets: min pt. Used to calculate the contribution from a lower min pt in the fixed order jets. This option allows this calculation to be done separately from the calculation where the fixed order min pt is equal to the resummation jets min pt. This is usually a small correction.

off-shell tolerance

Tolerance for numerical inaccuracies in input momenta. Momenta of massless particles with an invariant mass below the given value are rescaled to be on-shell. Transverse momentum components of incoming particles that are smaller than the given tolerance are set to zero. The default value is 0, leaving input momenta unchanged.

Advanced Settings

All of the following settings are optional. Please do not set any of the following options, unless you know exactly what you are doing. The default behaviour gives the most reliable results for a wide range of observables.

soft pt regulator

Specifies the maximum fraction that soft radiation can contribute to the transverse momentum of each the tagging jets, i.e. any jet that affects the event classification, like the most forward and most backward jet or the jets of the central qqbar pair. This setting is needed to regulate an otherwise cancelled divergence. Default is 0.1.

max events

Maximal number of (input) Fixed Order events. HEJ will stop after processing max events many events. Default considers all events.

regulator parameter

Slicing parameter to regularise the subtraction term, called \(\lambda\) in arxiv:1706.01002. Default is 0.2.