# 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.

## 5.5.1. ME_GENERATORS¶

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

`Internal`

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

`Amegic`

The AMEGIC++ generator published under [KKS02]

`Comix`

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

## 5.5.2. RESULT_DIRECTORY¶

This parameter specifies the name of the directory which is used by
Sherpa to store integration results and phase-space 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.

## 5.5.3. EVENT_GENERATION_MODE¶

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:

`Weighted`

(alias

`W`

) Weighted events.`Unweighted`

(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).`PartiallyUnweighted`

(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. COLOR_SCHEME¶

This parameter specifies how to perform the color algebra in hard matrix elemens.
The available options are `0`

for the generator-specific default,
`1`

for sum, and `2`

for sampling.

## 5.5.5. HELICITY_SCHEME¶

This parameter specifies how to perform the helicity algebra in hard matrix elemens.
The available options are `0`

for the generator-specific default,
`1`

for sum, and `2`

for sampling.

## 5.5.6. SCALES¶

This parameter specifies how to compute the renormalisation and factorisation scale and potential additional scales.

Note

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 Scale setting in multi-parton processes (METS).

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 `SHOWER:RESPECT_Q2: true`

and use the third argument to specify your resummation scale as above.

Note

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.

### 5.5.6.1. Scale setters¶

The scale setter options which are currently available are

`METS`

`METS`

is the default scale scheme in Sherpa and employed for multi-leg merging, both at leading and next-to-leading order. Since it is important and complex at the same time, it will be described in detail in the next section.`VAR`

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])}

Renormalisation and factorisation 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])}

`FASTJET`

This scale setter can be used to set a scale based on jet-, rather than parton-momenta, using FastJet.

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 unaffected. 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 isSCALES: 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`

(default`kt`

)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`

)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*

(n=2..njet+1), hold the nodal values of the jet clustering in descending order.*MU_n2*Please note that currently this type of scale setting can only be done within the process block (Processes) and not within the (me) section.

`VBF`

Very similar to the

`METS`

scale setter and thus also applicable in multi-leg merged setups, but catering specifically to topologies with two colour-separated parton lines like in VBF/VBS processes for the incoming quarks.

### 5.5.6.2. Scale setting in multi-parton processes (METS)¶

`METS`

is the default scale setting in Sherpa, since it is employed
for multi-leg merging, both at leading and next-to-leading order.
It dynamically defines the three tags `MU_F2`

, `MU_R2`

and
`MU_Q2`

as will be explained below. Those can then be employed in the
actual `<scale-definition>`

in the scale setter. The default is

```
SCALES: METS{MU_F2}{MU_R2}{MU_Q2}
```

The tags may be omitted, i.e.

```
SCALES: METS
```

leads to an identical scale definition.

`METS`

is a very dynamic scheme and depends on two ingredients to construct
a scale that preserves the logarithmic accuracy of the parton evolution defined
by the parton shower:

A sequential recombination algorithm to cluster the multi-leg matrix element onto a core configuration (typically 2->2) using an inversion of the current parton shower. The clustered flavours are determined using run-time information from the matrix element generator. The clustering stops, 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. That defines the core process.

A freely selectable scale in the core process,

`CORE_SCALE`

.

These are then defined to calculate `MU_R2`

from the core scale and the
individual clustering scales such that:

where \(n\) is the order in strong coupling of the core process and \(k\) is the number of clusterings, \(k_{t,i}\) are the relative transverse momenta at each clustering.

The definition of `MU_F2`

and `MU_Q2`

are passed directly on from the core scale setter.

The functional form of the core scale can be defined by the user in the `MEPS`

settings block as follows:

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

Again, for core scale setters which define `MU_F2`

, `MU_R2`

and
`MU_Q2`

the actual scale listing can be dropped.

Possible choices for the core scale setter are:

`Default`

The core scales are defined depending on the core process and as the list and functional form is regularly extended to more core processes, its definition is most easily seen in the source code

`VAR`

Variable core scale setter for free functional definition by the user. Syntax is identical to variable scale setter.

`QCD`

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

`Default`

core scale.`TTBar`

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

`SingleTop`

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]`

).`Photons`

Core scale setter for photon(s)+jets production. Sets the following scales for the possible core processes:

\(\gamma\gamma\): \(\mu_f=\mu_r=\mu_q=m_{\gamma\gamma}\)

\(\gamma j\): \(\mu_f=\mu_r=\mu_q=p_{\perp,\gamma}\)

\(jj\): same as QCD core scale (harmonic mean of s, t, u)

Unordered cluster histories are by default not allowed. Instead, if during clustering a new smaller scale is encountered, the previous maximal scale will be used, or alternatively a user-defined scale specified, e.g.

```
MEPS:
UNORDERED_SCALE: VAR{H_Tp2/sqr(N_FS-2)}
```

If instead you want to allow unordered histories you can also enable them with
`ALLOW_SCALE_UNORDERING: 1`

.

Clusterings onto 2->n (n>2) configurations is possible and for complicated processes can warrant the implementation of a custom core scale, cf. Customization.

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.

One final word of caution: The `METS`

scale scheme might be subject to changes
to enable further classes of processes for merging in the future and integration
results might thus change slightly between different Sherpa versions.

### 5.5.6.3. 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.

### 5.5.6.5. 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 referring 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.

### 5.5.6.6. Explicit scale variations¶

The (nominal) factorisation and renormalisation scales in the fixed-order matrix elements can be scaled explicitly 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.

However, to calculate several variations in a single event generation run, you need to use On-the-fly event weight variations. See the instructions given there to find out how to vary factorisation and renormalisation scale factors on-the-fly, both in the matrix element and in the parton shower.

The starting scale of the parton shower resummation
in a ME+PS merged sample, `MU_Q2`

,
can at the moment not be varied on-the-fly.
To change the (nominal) starting scale explicitly,
a scale factor can be introduced
in the third argument of the METS scale setter:

```
SCALES: METS{MU_F2}{MU_R2}{4.0*MU_Q2}
```

## 5.5.7. COUPLINGS¶

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])}
COUPLINGS:
- "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.8. 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. To list all available
K-factors, the tag `SHOW_KFACTOR_SYNTAX: 1`

can be specified
on the command line. Currently available options are

`None`

No reweighting

`VAR`

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 125 GeV, the corresponding reweighting would readSCALES: VAR{...}{PPerp2(p[3])} COUPLINGS: "Alpha_QCD 1" KFACTOR: VAR{sqr(Alpha_QCD(sqr(125))/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.

## 5.5.9. YUKAWA_MASSES¶

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.10. Dipole subtraction¶

There is one general switch that governs the behaviour of the Catani-Seymour subtraction [CS97] as implemented in Sherpa [GK08, Sch18]. NLO_SUBTRACTION_MODE defines which type of divergences will be subtracted (both off the virtual and real amplitudes). Options are:

`QCD`

Only QCD infrared divergences will be subtracted. This is the default as most users will be familiar with this setting corresponding to the abilities of older Sherpa versions.

`QED`

Only QED infrared divergences will be subtracted.

`QCD+QED`

All Standard Model infrared divergences will be subtracted.

Further, the following list of parameters can be used to optimise
the performance of the dipole subtraction. These dipole
parameters are specified as subsettings to the `DIPOLES`

setting,
like this:

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

The following parameters can be customised:

`SCHEME`

Defines the finite parts of the splitting functions used. Options are:

CS, this is the standard Catani-Seymour subtraction definition of the splitting functions. This is the default for fixed-order calculations.

Dire, this selects the modified splitting functions used in the Dire dipole shower. It is the default for MC@NLO calculations matching to Dire.

CSS, this selects the modified splitting functions used in the CSS parton shower. It is the default for MC@NLO calculations matching to the CSS.

`ALPHA`

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

`ALPHA_FF, ALPHA_FI, ALPHA_IF, ALPHA_II`

Specifies the above dipole alpha only for FF, FI, IF, or II dipoles, respectively.

`AMIN`

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

`NF_GSPLIT`

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.

`KAPPA`

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

`LIST`

If set to 1 all generated dipoles will be listed for all generated processes.