5.5. Matrix elements

The following parameters are used to steer the matrix element calculation setup. To learn how to specify the hard scattering process and further process-specific options in its calculation, please also refer to Processes.


The list of matrix element generators to be employed during the run. When setting up hard processes, Sherpa calls these generators in order to check whether either one is capable of generating the corresponding matrix element. This parameter can also be set on the command line using option -m, see Command Line Options.

The built-in generators are


Simple matrix element library, implementing a variety of 2->2 processes.


The AMEGIC++ generator published under [KKS02]


The Comix generator published under [GH08]

It is possible to employ an external matrix element generator within Sherpa. For advice on this topic please contact the authors, Authors.


This parameter specifies the name of the directory which is used by Sherpa to store integration results and phasespace mappings. The default is Results/. It can also be set using the command line parameter -r, see Command Line Options. The directory will be created automatically, unless the option GENERATE_RESULT_DIRECTORY: false is specified. Its location is relative to a potentially specified input path, see Command Line Options.


This parameter specifies the event generation mode. It can also be set on the command line using option -w, see Command Line Options. The three possible options are:


(alias W) Weighted events.


(alias U) Events with constant weight, which have been unweighted against the maximum determined during phase space integration. In case of rare events with w > max the parton level event is repeated floor(w/max) times and the remainder is unweighted. While this leads to unity weights for all events it can be misleading since the statistical impact of a high-weight event is not accounted for. In the extreme case this can lead to a high-weight event looking like a significant bump in distributions (in particular after the effects of the parton shower).


(alias P) Identical to Unweighted events, but if the weight exceeds the maximum determined during the phase space integration, the event will carry a weight of w/max to correct for that. This is the recommended option to generate unweighted events and the default setting in Sherpa.

For Unweighted and PartiallyUnweighted events the user may set OVERWEIGHT_THRESHOLD: to cap the maximal over-weight w/max taken into account.

5.5.4. SCALES

This parameter specifies how to compute the renormalization and factorization scale and potential additional scales.


In a setup with the parton shower enabled, it is strongly recommended to leave this at its default value, METS, and to instead customise the CORE_SCALE setting as described in METS scale setting with multiparton core processes.

Sherpa provides several built-in scale setting schemes. For each scheme the scales are then set using expressions understood by the Interpreter. Each scale setter’s syntax is

SCALES: <scale-setter>{<scale-definition>}

to define a single scale for both the factorisation and renormalisation scale. They can be set to different values using

SCALES: <scale-setter>{<fac-scale-definition>}{<ren-scale-definition>}

In parton shower matched/merged calculations a third perturbative scale is present, the resummation or parton shower starting scale. It can be set by the user in the third argument like

SCALES: <scale-setter>{<fac-scale-definition>}{<ren-scale-definition>}{<res-scale-definition>}

If the final state of your hard scattering process contains QCD partons, their kinematics fix the resummation scale for subsequent emissions (cf. the description of the METS scale setter below). With the CS Shower, you can instead specify your own resummation scale also in such a case: Set CSS_RESPECT_Q2: true and use the third argument to specify your resummation scale as above.


For all scales their squares have to be given. See Predefined scale tags for some predefined scale tags.

More than three scales can be set as well to be subsequently used, e.g. by different couplings, see COUPLINGS. Scale setters

The scale setter options which are currently available are


The variable scale setter is the simplest scale setter available. Scales are simply specified by additional parameters in a form which is understood by the internal interpreter, see Interpreter. If, for example the invariant mass of the lepton pair in Drell-Yan production is the desired scale, the corresponding setup reads

SCALES: VAR{Abs2(p[2]+p[3])}

Renormalization and factorization scales can be chosen differently. For example in Drell-Yan + jet production one could set

SCALES: VAR{Abs2(p[2]+p[3])}{MPerp2(p[2]+p[3])}

If FastJet is enabled by including --enable-fastjet=/path/to/fastjet in the configure options, this scale setter can be used to set a scale based on jet-, rather than parton-momenta.

The final state parton configuration is first clustered using FastJet and resulting jet momenta are then added back to the list of non strongly interacting particles. The numbering of momenta therefore stays effectively the same as in standard Sherpa, except that final state partons are replaced with jets, if applicable (a parton might not pass the jet criteria and get “lost”). In particular, the indices of the initial state partons and all EW particles are uneffected. Jet momenta can then be accessed as described in Predefined scale tags through the identifiers p[i], and the nodal values of the clustering sequence can be used through MU_n2. The syntax is

SCALES: FASTJET[<jet-algo-parameter>]{<scale-definition>}

Therein the parameters of the jet algorithm to be used to define the jets are given as a comma separated list of

  • the jet algorithm A:kt,antikt,cambridge,siscone (default antikt)

  • phase space restrictions, i.e. PT:<min-pt>, ET:<min-et>, Eta:<max-eta>, Y:<max-rap> (otherwise unrestricted)

  • radial parameter R:<rad-param> (default 0.4)

  • f-parameter for Siscone f:<f-param> (default 0.75)

  • recombination scheme C:E,pt,pt2,Et,Et2,BIpt,BIpt2 (default E)

  • b-tagging mode B:0,1,2 (default 0) This parameter, if specified different from its default 0, allows to use b-tagged jets only, based on the parton-level constituents of the jets. There are two options: With B:1 both b and anti-b quarks are counted equally towards b-jets, while for B:2 they are added with a relative sign as constituents, i.e. a jet containing b and anti-b is not tagged.

  • scale setting mode M:0,1 (default 1) It is possible to specify multiple scale definition blocks, each enclosed in curly brackets. The scale setting mode parameter then determines, how those are interpreted: In the M:0 case, they specify factorisation, renormalisation and resummation scale separately in that order. In the M:1 case, the n given scales are used to calculate a mean scale such that \(\alpha_s^n(\mu_\text{mean})=\alpha_s(\mu_1)\dots\alpha_s(\mu_n)\) This scale is then used for factorisation, renormalisation and resummation scale.

Consider the example of lepton pair production in association with jets. The following scale setter

SCALES: FASTJET[A:kt,PT:10,R:0.4,M:0]{sqrt(PPerp2(p[4])*PPerp2(p[5]))}

reconstructs jets using the kt-algorithm with R=0.4 and a minimum transverse momentum of 10 GeV. The scale of all strong couplings is then set to the geometric mean of the hardest and second hardest jet. Note M:0.

Similarly, in processes with multiple strong couplings, their renormalisation scales can be set to different values, e.g.

SCALES: FASTJET[A:kt,PT:10,R:0.4,M:1]{PPerp2(p[4])}{PPerp2(p[5])}

sets the scale of one strong coupling to the transverse momentum of the hardest jet, and the scale of the second strong coupling to the transverse momentum of second hardest jet. Note M:1 in this case.

The additional tags MU_22 .. MU_n2 (n=2..njet+1), hold the nodal values of the jet clustering in descending order.

Please note that currently this type of scale setting can only be done within the process block (Processes) and not within the (me) section.


The matrix element is clustered onto a core 2->2 configuration using an inversion of current parton shower, cf. SHOWER_GENERATOR, recombining (n+1) particles into n on-shell particles. Their corresponding flavours are determined using run-time information from the matrix element generator. It defines the three tags MU_F2, MU_R2 and MU_Q2 whose values are assigned through this clustering procedure. While MU_F2 and MU_Q2 are defined as the lowest invariant mass or negative virtuality in the core process (for core interactions which are pure QCD processes scales are set to the maximum transverse mass squared of the outgoing particles), MU_R2 is determined using this core scale and the individual clustering scales such that

\[\alpha_s(\mu_{R2})^{n+k} = \alpha_s(\text{core}-\text{scale})^k \alpha_s(kt_1) \dots \alpha_s(kt_n)\]

where k is the order in strong coupling of the core process and k is the number of clusterings, kt_i are the relative transverse momenta at each clustering. The tags MU_F2, MU_R2 and MU_Q2 can then be used on equal footing with the tags of Predefined scale tags to define the final scale.

METS is the default scale scheme in Sherpa, since it is employed for truncated shower merging, see Multijet merged event generation with Sherpa, both at leading and next-to-leading order. Thus, Sherpa’s default is


As the tags MU_F2, MU_R2 and MU_Q2 are predefined by the METS scale setter, they may be omitted, i.e.


leads to an identical scale definition.

The METS scale setter comes in two variants: STRICT_METS and LOOSE_METS. While the former employs the exact inverse of the parton shower for the clustering procedure, and therefore is rather time consuming for multiparton final state, the latter is a simplified version and much faster. Giving METS as the scale setter results in using LOOSE_METS for the integration and STRICT_METS during event generation. Giving either STRICT_METS or LOOSE_METS as the scale setter results in using the respective one during both integration and event generation.

Clusterings onto 2->n (n>2) configurations is possible, see METS scale setting with multiparton core processes.

This scheme might be subject to changes to enable further classes of processes for merging in the future and should therefore be seen with care. Integration results might change slightly between different Sherpa versions.

Occasionally, users might encounter the warning message

METS_Scale_Setter::CalculateScale(): No CSS history for '<process name>' in <percentage>% of calls. Set \hat{s}.

As long as the percentage quoted here is not too high, this does not pose a serious problem. The warning occurs when - based on the current colour configuration and matrix element information - no suitable clustering is found by the algorithm. In such cases the scale is set to the invariant mass of the partonic process. Custom scale implementation

When the flexibility of the VAR scale setter above is not sufficient, it is also possible to implement a completely custom scale scheme within Sherpa as C++ class plugin. For details please refer to the Customization section. Predefined scale tags

There exist a few predefined tags to facilitate commonly used scale choices or easily implement a user defined scale.


Access to the four momentum of the nth particle. The initial state particles carry n=0 and n=1, the final state momenta start from n=2. Their ordering is determined by Sherpa’s internal particle ordering and can be read e.g. from the process names displayed at run time. Please note, that when building jets out of the final state partons first, e.g. through the FASTJET scale setter, these parton momenta will be replaced by the jet momenta ordered in transverse momenta. For example the process u ub -> e- e+ G G will have the electron and the positron at positions p[2] and p[3] and the gluons on postions p[4] and p[5]. However, when finding jets first, the electrons will still be at p[2] and p[3] while the harder jet will be at p[4] and the softer one at p[5].


Square of the scalar sum of the transverse momenta of all final state particles.


Square of the scalar sum of the transverse energies of all final state particles, i.e. contrary to H_T2 H_TM2 takes particle masses into account.


Square of the scalar sum of the transverse momenta of all final state particles weighted by their rapidity distance from the final state boost vector. Thus, takes the form

H_T^{(Y)} = sum_i pT_i exp [ fac |y-yboost|^exp ]

Typical values to use would by 0.3 and 1.


Scale setter for lepton-pair production in association with jets only, implements

H_T' = sqrt(m_ll^2 + pT(ll)^2) + sum_i pT_i (i not l)

Implements a version of H_Tp2 which dresses charged particles first. The parameter <recombination-method> can take the following values: Cone, kt, CA or antikt, while <dR> is the respecitve algorithm’s angular distance parameter.


Square of the beam thrust.

MU_F2, MU_R2, MU_Q2

Tags holding the values of the factorisation, renormalisation scale and resummation scale determined through backwards clustering in the METS scale setter.

MU_22, MU_32, ..., MU_n2

Tags holding the nodal values of the jet clustering in the FASTJET scale setter, cf. Scale setters.

All of those objects can be operated upon by any operator/function known to the Interpreter. Scale schemes for NLO calculations

For next-to-leading order calculations it must be guaranteed that the scale is calculated separately for the real correction and the subtraction terms, such that within the subtraction procedure the same amount is subtracted and added back. Starting from version 1.2.2 this is the case for all scale setters in Sherpa. Also, the definition of the scale must be infrared safe w.r.t. to the radiation of an extra parton. Infrared safe (for QCD-NLO calculations) are:

  • any function of momenta of NOT strongly interacting particles

  • sum of transverse quantities of all partons (e.g. H_T2)

  • any quantity refering to jets, constructed by an IR safe jet algorithm, see below.

Not infrared safe are

  • any function of momenta of specific partons

  • for processes with hadrons in the initial state:

any quantity that depends on parton momenta along the beam axis, including the initial state partons itself

Since the total number of partons is different for different pieces of the NLO calculation any explicit reference to a parton momentum will lead to an inconsistent result. Explicit scale variations

The factorisation and renormalisation scales in the fixed-order matrix elements can be varied separately simply by introducing a prefactor into the scale definition, e.g.

SCALES: VAR{0.25*H_T2}{0.25*H_T2}

for setting both the renormalisation and factorisation scales to H_T/2.

Similarly, the starting scale of the parton shower resummation in a ME+PS merged sample can be varied using the METS scale setter’s third argument like:

SCALES: METS{MU_F2}{MU_R2}{4.0*MU_Q2} METS scale setting with multiparton core processes

The METS scale setter stops clustering when no combination is found that corresponds to a parton shower branching, or if two subsequent branchings are unordered in terms of the parton shower evolution parameter. The core scale of the remaining 2->n process then needs to be defined. This is done by specifying a core scale through

CORE_SCALE: <core-scale-setter>{<core-fac-scale-definition>}{<core-ren-scale-definition>}{<core-res-scale-definition>}

As always, for scale setters which define MU_F2, MU_R2 and MU_Q2 the scale definition can be dropped. Possible core scale setters are


Variable core scale setter. Syntax is identical to variable scale setter.


QCD core scale setter. Scales are set to harmonic mean of s, t and u. Only useful for 2->2 cores as alternatives to the usual core scale of the METS scale setter.


Core scale setter for processes involving top quarks. Implementation details are described in Appendix C of [HHL+13].


Core scale setter for single-top production in association with one jet. If the W is in the t-channel (s-channel), the squared scales are set to the Mandelstam variables t=2*p[0]*p[2] (t=2*p[0]*p[1]).


Within Sherpa, strong and electroweak couplings can be computed at any scale specified by a scale setter (cf. SCALES). The COUPLINGS tag links the argument of a running coupling to one of the respective scales. This is better seen in an example. Assuming the following input

SCALES: VAR{...}{PPerp2(p[2])}{Abs2(p[2]+p[3])}
  - "Alpha_QCD 1"
  - "Alpha_QED 2"

Sherpa will compute any strong couplings at scale one, i.e. PPerp2(p[2]) and electroweak couplings at scale two, i.e. Abs2(p[2]+p[3]). Note that counting starts at zero.

5.5.6. KFACTOR

This parameter specifies how to evaluate potential K-factors in the hard process. This is equivalent to the COUPLINGS specification of Sherpa versions prior to 1.2.2. Currently available options are


No reweighting


Couplings specified by an additional parameter in a form which is understood by the internal interpreter, see Interpreter. The tags Alpha_QCD and Alpha_QED serve as links to the built-in running coupling implementation.

If for example the process g g -> h g in effective theory is computed, one could think of evaluating two powers of the strong coupling at the Higgs mass scale and one power at the transverse momentum squared of the gluon. Assuming the Higgs mass to be 120 GeV, the corresponding reweighting would read

SCALES:    VAR{...}{PPerp2(p[3])}
KFACTOR:   VAR{sqr(Alpha_QCD(sqr(120))/Alpha_QCD(MU_12))}

As can be seen from this example, scales are referred to as MU_<i>2, where <i> is replaced with the appropriate number. Note that counting starts at zero.

It is possible to implement a dedicated K-factor scheme within Sherpa. For advice on this topic please contact the authors, Authors.


This parameter specifies whether the Yukawa couplings are evaluated using running or fixed quark masses: YUKAWA_MASSES: Running is the default since version 1.2.2 while YUKAWA_MASSES: Fixed was the default until 1.2.1.

5.5.8. Dipole subtraction

This list of parameters can be used to optimize the performance when employing the Catani-Seymour dipole subtraction [CS97] as implemented in Amegic [GK08]. The dipole parameters are specified as subsettings to the DIPOLES setting, like this:

  ALPHA: <alpha>
  NF_GSPLIT: <nf>
  # other dipole settings ...

The following parameters can be customised:


Specifies a dipole cutoff in the nonsingular region [Nag03]. Changing this parameter shifts contributions from the subtracted real correction piece (RS) to the piece including integrated dipole terms (I), while their sum remains constant. This parameter can be used to optimize the integration performance of the individual pieces. Also the average calculation time for the subtracted real correction is reduced with smaller choices of “ALPHA” due to the (on average) reduced number of contributing dipole terms. For most processes a reasonable choice is between 0.01 and 1 (default). See also Choosing DIPOLES ALPHA


Specifies the cutoff of real correction terms in the infrared reagion to avoid numerical problems with the subtraction. The default is 1.e-8.


Specifies the number of quark flavours that are produced from gluon splittings. This number must be at least the number of massless flavours (default). If this number is larger than the number of massless quarks the massive dipole subtraction [CDST02] is employed.


Specifies the kappa-parameter in the massive dipole subtraction formalism [CDST02]. The default is 2.0/3.0.