Hard cross section calculation with Matchbox

Enabling Matchbox generated processes

The typical setup for Matchbox generated processes is outlined in the *-Matchbox.in input files for different colliders. Matrix elements are provided for a few processes including inclusive Drell-Yan Z and W production, as well as Z and W plus one jet production. For all other processes we chose to rely on external libraries, which need to be enabled in the build of Herwig and are automatically installed when using the bootstrap script.

Using external amplitude providers

Our external amplitude providers typically come in two types, a library providing tree-level amplitudes for both leading and next-to-leading order simulation, and libraries providing the one-loop matrix elements to complete next-to-leading order calculations. The default setup is to bundle both a tree-level and a one-loop provider into the GenericProcesses object, which will then be used by the Factory object to generate the required subprocess.

On-shell production of unstable particles

If on-shell production of unstable particles such as top quarks, W and Z or Higgs bosons is desired, special settings have to be enabled via

read Matchbox/OnShell{Top,W,Z,H}Production.in

This will inform the Matchbox module that hard process matrox elements should be evaluated with the respective external particles on their mass shell and zero width in the hard process generation. Decays are then handled by the standard Decayer classes, including the proper (partial) widths of the particles.

Using the Higgs effective (large-top-mass) theory

The Higgs effective theory with a top quark which has been integrated out, can be enabled by reading the corresponding snippet,

read Matchbox/HiggsEffective.in

Adjusting diagram generation

By default, only electromagnetic charge conservation is used as a direct input when generating the contributing subprocesses. All other conservation rules follow from the list of possible vertices when building the Feynman diagrams. In processes with many final-state particles and/or when using particle groups, probing all the different possibilities can require a significant amount of time due to large combinatorics. Therefore, further conservation laws can be switched on, so that subprocesses which would violate these can be directly discarded.

Possible additional conversation laws are:

  • colour
set Factory:EnforceColourConservation Yes
  • lepton number
set Factory:EnforceLeptonNumberConservation Yes
  • no lepton-flavour changing vertices
set Factory:LeptonFlavourDiagonal Yes
  • quark number
set Factory:EnforceQuarkNumberConservation Yes

For the Standard Model and models with the same structure, where all quantities of teh previous list are conserved, a snippet setting everything at once is available:

read Matchbox/StandardModelLike.in

Additionally, whether the CKM matrix should be taken as diagonal or not can be selected by including the corresponding of the following two snippets.

# read Matchbox/DiagonalCKM.in
# read Matchbox/NonDiagonalCKM.in

Scale choices

A number of scale choices are available for use in the *-Matchbox.in input files. These can be found in the /Herwig/MatrixElements/Matchbox/Scales directory of the repository and are outlined below. When relevant, the QED renormalization scale is set equal to the QCD one unless it is stated otherwise.

Fixed Scale: A fixed value of the renormalization and factorization scales can be set using:

cd  /Herwig/MatrixElements/Matchbox/
set Scales/FixedScale:FixedScale x*GeV
set Factory:ScaleChoice Scales/FixedScale

HTScale: Scales related to the transverse momenta of coloured particles are defined using the /Herwig/Cuts/JetFinder object. The JetFinder takes all outgoing partons in the hard process (i.e. any particle within the j ParticleGroup defined in defaults/MatchboxDefaults.in) and clusters them into jets. Selecting the scale choice:

set Factory:ScaleChoice Scales/HTScale

will set \(\mu_R^2=\mu_F^2=(\sum_i p_T^i)^2\) where \(p_T^i\) is the transverse momentum of the ith jet.

HTPrimeScale: The scale choice:

set Factory:ScaleChoice Scales/HTPrimeScale

is similar to the HTScale but includes all outgoing non-jet particles (i.e. particles which are not contained in the j ParticleGroup definition). More concretely, \(\mu_R^2=\mu_F^2=(\sum_i p_T^i + m_T)^2\) where \(m_T\) is the transverse mass of the system formed by summing the momenta of all the non-jet particles.

LeptonPairMassScale: For processes involving a pair of final-state leptons, two specialist scale choices are provided. Including the line:

set Factory:ScaleChoice Scales/LeptonPairMassScale

will set \(\mu_R^2=\mu_F^2=(p_{l_1}+p_{l_2})^2\) where \(p_{l_1}\) and \(p_{l_2}\) are the momenta of the leptons in the pair.

LeptonPairPtScale: Alternatively, using:

set Factory:ScaleChoice Scales/LeptonPairPtScale

will set \(\mu_R^2=\mu_F^2=(p^x_{l_1}+p^x_{l_2})^2+ (p^y_{l_1}+p^y_{l_2})^2\), i.e. the renormalization and factorization scales are equal to the transverse component of the momentum of the lepton pair.

The QED renormalization scale is set to \(\mu_R^2=(p_{l_1}+p_{l_2})^2\).

MaxJetPtScale: Selecting the scale choice:

set Factory:ScaleChoice Scales/MaxJetPtScale

will set the renormalization and factorization scales equal to the transverse momentum of the hardest jet, i.e. \(\mu_R^2=\mu_F^2=\max_j(p_T^j)^2\), where jets are defined as in the HTScale.

SHatScale: The renormalization and factorization scales may be set equal to the partonic centre-of-mass energy using:

set Factory:ScaleChoice Scales/SHatScale

TopPairMassScale: For processes involving the production of a \(t\bar{t}\) pair, two specialist scale options are provided. Including the line:

set Factory:ScaleChoice Scales/TopPairMassScale

will set \(\mu_R^2=\mu_F^2=(p_t + p_{\bar{t}})^2\) where \(p_t\) (\(p_{\bar{t}}\)) is the momentum of the top (antitop) quark.

TopPairMTScale: Alternatively, including the line:

set Factory:ScaleChoice Scales/TopPairMTScale

will set \(\mu_R^2=\mu_F^2=(m_{T,t}^2+m_{T, \bar{t}}^2)\) where \(m_{T, t}\) (\(m_{T, \bar{t}}\)) is the transverse mass of the top (antitop) quark.


We provide a flexible set of cuts to be applied at the level of the hard process. Notice that these should be chosen to be more inclusive than the cuts used in the analysis once parton showering is taken into account, i.e. the cuts used in the production should in general be loose enough to end up with an analysis that is insensitive to the choice of generation cuts. All migration effect due to parton showers and the underlying events have to be covered.

Except for the jet cuts, which need to be enabled by input file snippets, the default cut objects are already present in the event generator but will not apply any cuts unless specific values are set.

Jet cuts

Cuts on jets are defined using a JetFinder object to cluster jets, together with a number of JetRegion objects and an ordering prescription on the jets. Additionally, cuts on the number of jets are available. A JetRegion can accept a jet labelled according to the ordering and will require this particular jet to be found inside a given \(p_\perp\) range and certain rapidity slices.

For each collider, a default setup for jet cuts can be found in the respective snippets (e.g. DefaultPPJets) and jet finding parameters may be adjusted as:

set /Herwig/Cuts/JetFinder:Variant Kt
set /Herwig/Cuts/JetFinder:ConeRadius 0.4

while JetRegion objects can be modified as:

set /Herwig/Cuts/FirstJet:PtMin 20.*GeV
do /Herwig/Cuts/FirstJet:YRange -5.0 5.0

Jet regions also support upper limits on the transverse momentum by using the PtMax interface. Multiple rapidity intervals may be used to require e.g. forward configurations. Cuts can also be imposed on pairs of jets, e.g.:

cd /Herwig/Cuts
create ThePEG::JetPairRegion DeltaY12Cut
set DeltaY12Cut:FirstRegion FirstJet
set DeltaY12Cut:SecondRegion SecondJet
do DeltaY12Cut:DeltaYMin 3
insert JetCuts:JetPairRegions 0 DeltaY12Cut

JetPairRegion objects further support interfaces on DeltaY{Min,Max}, DeltaR{Min,Max} and Mass{Min,Max}.

Notice that the JetFinder object will cluster jets from whatever has been defined as jet constituents through the Factory object, i.e. in a four flavour scheme final state b quarks will be part of a jet unless the jet has been redefined to not contain b quarks through the ParticleGroup interface of the Factory object. Perhaps we want to define very light jets with only \(u, d, g\) constituents.:

cd /Herwig/MatrixElements/Matchbox

do Factory:StartParticleGroup j
insert Factory:ParticleGroup 0 /Herwig/Particles/d
insert Factory:ParticleGroup 0 /Herwig/Particles/dbar
insert Factory:ParticleGroup 0 /Herwig/Particles/u
insert Factory:ParticleGroup 0 /Herwig/Particles/ubar
insert Factory:ParticleGroup 0 /Herwig/Particles/g
do Factory:EndParticleGroup

The ParticleGroup \(j\) in the above constitutes the default to define a jet in a Matchbox generated process. Likewise, the ParticleGroup \(p\) constitutes the default to define a proton in a Matchbox generated process. In order to redefine the constituents of jets and protons in a Matchbox generated process we recommend, for technical reasons, to always use \(j\) and \(p\) respectively.

Cuts on specific objects

Similar to jet regions, a number of cuts on other objects can be required to demand these objects within certain rapidity slices and a range of transverse momentum. By default we provide the following set:


all of which can be modified just as the JetRegion objects described above. For leptons and charged leptons, \(\Delta R\) and invariant mass cuts are available through the {Charged,}LeptonPairMassCut and {Charged,}LeptonDeltaRCut objects.

Isolation cuts

A smooth cone isolation cut for photons as suggested by Frixione is available through the PhotonIsolationCut object.

Example: cuts for processes with an isolated photon

In order to get photon isolation from hard partons and a minimum transverse momentum for the visibility of a hard photon the following cuts can be applied:

cd /Herwig/Cuts/
insert Cuts:OneCuts 0 PhotonCut
set PhotonCut:PtMin 20*GeV

insert Cuts:MultiCuts 0 /Herwig/Cuts/PhotonIsolationCut

To avoid divergences from photon radiation off final state charged leptons you can apply a \(\Delta R\) cut as follows:

cd /Herwig/Cuts/
insert Cuts:TwoCuts 0 LeptonDeltaRCut
set LeptonDeltaRCut:DeltaRMin 0.2
set LeptonDeltaRCut:FirstMatcher /Herwig/Matchers/ChargedLepton
set LeptonDeltaRCut:SecondMatcher /Herwig/Matchers/Photon

Example: cuts for processes with intermediate \(W\) bosons

In processes with intermediate \(W\) bosons which are demanded via a charged lepton and neutrino in the final state one may wish to apply an invariant mass cut for the \(W\) boson:

cd /Herwig/Cuts/
insert Cuts:TwoCuts 0 LeptonPairMassCut
set LeptonPairMassCut:SecondMatcher /Herwig/Matchers/Neutrino
set LeptonPairMassCut:MinMass 60*GeV
set LeptonPairMassCut:MaxMass 120*GeV

Note that the LeptonPairMassCut:FirstMatcher is a ChargedLepton by default already.

Subtractive matching

The different NLO matching schemes are selected by setting the Factory:ShowerApproximation object. Subtractive, or MC@NLO, matching to the angular-ordered shower is switched on by uncommenting the line:

read Matchbox/MCatNLO-DefaultShower.in

in the *-Matchbox.in input file. Within the MCatNLO-DefaultShower snippet, the ShowerApproximation object is set by the line:

set Factory:ShowerApproximation QTildeMatching

and some default restrictions to the parton-shower phase space are applied:

set /Herwig/Shower/ShowerHandler:RestrictPhasespace Yes
set /Herwig/Shower/ShowerHandler:MaxPtIsMuF Yes
set /Herwig/Shower/ShowerHandler:HardScaleProfile /Herwig/MatrixElements/Matchbox/HardScaleProfile

The first two settings mean that the maximum allowed transverse momentum of shower emissions is set equal to the central value of the factorization scale. The third line ensures that restrictions to the phase space of S events are treated consistently between the hard process and parton shower.

The restriction on the maximum allowed transverse momentum of shower emissions may be removed to obtain a ‘power shower’ setup by adding the lines:

set /Herwig/Shower/ShowerHandler:RestrictPhasespace Off
set /Herwig/Shower/ShowerHandler:HardScaleProfile NULL

Finally, a number of the default shower settings are also modified in MCatNLO-DefaultShower.in such that they are set appropriately for NLO matching. In general, these should not be modified.

Subtractive matching may also be used with the dipole shower. Similar to the angular-ordered case, it is switched on by including the line:

read Matchbox/MCatNLO-DipoleShower.in

in the input file.

The factorization, renormalization and hard scale factors used in the subtractive matching are determined from those set in the shower handler. Therefore, no additional variations one top of those outlined in the angular-ordered and dipole shower sections are required.

Multiplicative matching

Multiplicative matching, based on the POWHEG formalism, is also available and may be switched on by including in the input file:

read Matchbox/Powheg-DefaultShower.in


read Matchbox/Powheg-DipoleShower.in

for matching to the angular-ordered or dipole showers respectively. These snippets in turn read from the Powheg.in file, which sets up the multiplicative matching with the lines:

set Factory:ShowerApproximation MEMatching
set MECorrectionHandler:Factory Factory
insert /Herwig/EventHandlers/EventHandler:PostSubProcessHandlers[0] MECorrectionHandler

The Powheg-*Shower.in files also restrict the transverse momentum of parton shower emissions to be less than the factorization scale using:

set /Herwig/Shower/ShowerHandler:RestrictPhasespace Yes
set /Herwig/Shower/ShowerHandler:MaxPtIsMuF Yes

The above restriction does not apply to the NLO matched emission.

By default the phase space of the NLO matched emission is restricted such that both S and H type POWHEG events are generated. The transverse momentum of the hard emission in S events is limited to be less than the central value of the factorization scale. This hard scale may be varied with:

cd /Herwig/MatrixElements/Matchbox
set MEMatching:HardScaleFactor x

Alternatively, the maximum transverse momentum of S events can be set to a fixed value with:

set HardScaleProfile:FixedHardScale x*GeV

A function may be introduced to smooth the cutoff of the phase space of S events. The resummation profile is used by default, and is switched on by the line:

set HardScaleProfile:ProfileType Resummation

Alternatively, the hfact profile may be switched on with:

set HardScaleProfile:ProfileType HFact

or a sharp cutoff with:

set HardScaleProfile:ProfileType Theta

The original POWHEG formalism, with S events only, can also be run by setting:

set MEMatching:RestrictPhasespace Off
set MEMatching:HardScaleProfile NULL

Unlike subtractive matching, the renormalization and factorization scales used in the matching must be varied explicitly, in conjunction with the scales used in the hard process and shower. This is done by changing \(\small x\) in:

set MEMatching:RenormalizationScaleFactor x
set MEMatching:FactorizationScaleFactor x

Example scale variations are included in the MuUp.in and MuDown.in snippets.

In the case of multiplicative matching to an angular-ordered shower, it is necessary to include a truncated parton shower that simulates soft, wide-angle radiation. This is handled by a modified version of the angular-ordered shower which is selected in Powheg-DefaultShower.in with the settings:

cd /Herwig/EventHandlers
set EventHandler:CascadeHandler /Herwig/Shower/PowhegShowerHandler
cd /Herwig/Shower
set PowhegShowerHandler:Factory /Herwig/MatrixElements/Matchbox/Factory
set ShowerHandler:HardEmission POWHEG

POWHEG style matrix-element corrections are also available for the decays of some particles and are enabled by default when multiplicative matching is used.

In analogy to the normal angular-ordered shower, the factorization, renormalization and hard scale factors can be varied for the PowhegShowerHandler using:

set /Herwig/Shower/PowhegShowerHandler:RenormalizationScaleFactor x
set /Herwig/Shower/PowhegShowerHandler:FactorizationScaleFactor x
set /Herwig/Shower/PowhegShowerHandler:HardScaleFactor x

Switching to leading order

Leading order event generation can also be done using the *-Matchbox.in input files. This is achieved by uncommenting in the input file:

read Matchbox/LO-DefaultShower.in


read Matchbox/LO-DipoleShower.in

depending on the desired parton shower. In addition, any commands setting up subtractive or multiplicative matching should be commented out. Both snippets read in the file LO.in which selects leading order event generation using:

set Factory:VirtualContributions Off
set Factory:RealContributions Off
set Factory:ShowerApproximation NULL

and selects the default LO PDF set and implementation of \(\alpha_s\).

Alternative LO setups are included in the MCatLO-DefaultShower.in and MCatLO-DipoleShower.in input file snippets. In these cases, the leading order hard process settings are combined with the parton shower settings used in the NLO matched setups. As such, these input file snippets should be used for strict LO vs. NLO comparisons.

For leading order processes, the GenericProcesses amplitude which allows you to select different tree level and one loop providers is no longer relevant. Instead an external amplitude provider may be selected by including the lines:

clear Factory:Amplitudes
insert Factory:Amplitudes 0 TreeAmplitudeProvider

where TreeAmplitudeProvider is for example MadGraph. If no external amplitude provider is selected, internal Matchbox amplitudes will be used where possible.

Spin correlations

Spin correlations can be included by adding to the input file

set Factory:SpinCorrelations Yes

This is only possible when using MadGraph amplitudes and, at present, is only available for leading order event generation.

Fixed-order runs and analyses

Assuming the default LHC-Matchbox.in input file, in order to switch to plain fixed order computations one first should switch off the shower matching by commenting the corresponding lines in the Matching section of the input file. For example:

# read Matchbox/MCatNLO-DefaultShower.in

At this point, fixed order computations can be done on the LO or NLO level by uncommenting the relevent snippet in the input file

# read Matchbox/NLO-NoShower.in
# read Matchbox/LO-NoShower.in

Furthermore, setting the sampler to produce weighted events is done as follows:

set /Herwig/EventHandlers/EventHandler:Weighted Yes

to be found in the section Technical parameters for this run. Also, setting the reference value for the running strong coupling constant at a specific scale can be done by including the following lines for example also just before the section Save the generator:

set /Herwig/Couplings/MatchboxNLOAlphaS:input_scale 91.1876*GeV
set /Herwig/Couplings/MatchboxNLOAlphaS:input_alpha_s 0.11798159
set /Herwig/Model:QCD/RunningAlphaS /Herwig/Couplings/MatchboxNLOAlphaS

Finally, in order to run any Rivet analysis in combination with a plain NLO computation, one should use NLORivetAnalysis rather than RivetAnalysis. This can be done by uncommenting the corresponding lines in the Analysis section of the input file:

cd /Herwig/Analysis
# create ThePEG::RivetAnalysis RivetAnalysis RivetAnalysis.so
create ThePEG::NLORivetAnalysis RivetAnalysis RivetAnalysis.so
insert /Herwig/Generators/EventGenerator:AnalysisHandlers 0 RivetAnalysis