# 5.7. Selectors¶

Sherpa provides the following selectors that set up cuts at the matrix element level:

Some selectors modify the momenta and flavours of the set of final state particles. These selectors also take a list of subselectors which then act on the modified flavours and momenta. Details are explained in the respective selectors’ description.

## 5.7.1. Inclusive selectors¶

The selectors listed here implement cuts on the matrix element level, based on event properties. The corresponding syntax is

```
SELECTORS:
- [<keyword>, <parameter 1>, <parameter 2>, ...]
- # other selectors ...
```

Parameters that accept numbers can also be given in a form that is
understood by the internal algebra interpreter, see
Interpreter. The selectors act on *all* particles in the
event. Their respective keywords are

`[N, <kf>, <min value>, <max value>]`

Minimum and maximum multiplicity of flavour

`<kf>`

in the final state.`[PTmis, <min value>, <max value>]`

Missing transverse momentum cut (at the moment only neutrinos are considered invisible)

`[ETmis, <min value>, <max value>]`

Missing transverse energy cut (at the moment only neutrinos are considered invisible)

`[IsolationCut, <kf>, <dR>, <exponent>, <epsilon>, <optional: mass_max>]`

Smooth cone isolation [Fri98], the parameters given are the flavour

`<kf>`

to be isolated against massless partons and the isolation cone parameters.`[NJ, <N>, <algo>, <min value>, <max value>]`

NJettiness from [SJW10], where

`<algo>`

specifies the jet finding algorithm to determine the hard jet directions and`<N>`

is their multiplicity.`algo=kt|antikt|cambridge,PT:<ptmin>,R:<dR>[,[ETA:<etamax>,Y:<ymax>]]`

## 5.7.2. One particle selectors¶

The selectors listed here implement cuts on the matrix element level, based on single particle kinematics. The corresponding syntax is

```
SELECTORS:
- [<keyword>, <flavour code>, <min value>, <max value>]
- # other selectors ...
```

`<min value>`

and `<max value>`

are floating point
numbers, which can also be given in a form that is understood by the
internal algebra interpreter, see Interpreter. The selectors
act on *all* possible particles with the given flavour. Their
respective keywords are

`PT`

transverse momentum cut

`ET`

transverse energy cut

`Y`

rapidity cut

`Eta`

pseudorapidity cut

`PZIN`

cut on the z-component of the momentum, acts on initial-state flavours only (commonly used in DIS analyses)

`HT`

Visible transverse energy cut

`E`

energy cut

`Polar_Angle`

Polar Angle cut in radians. An optional boolean can be provided to switch to degrees e.g [<keyword>, <flavour code>, <min value>, <max value>, <radians>]

## 5.7.3. Two particle selectors¶

The selectors listed here implement cuts on the matrix element level, based on two particle kinematics. The corresponding is

```
SELECTORS:
- [<keyword>, <flavour1 code>, <flavour2 code>, <min value>, <max value>]
- # other selectors ...
```

`<min value>`

and `<max value>`

are floating point
numbers, which can also be given in a form that is understood by the
internal algebra interpreter, see Interpreter. The selectors
act on *all* possible particles with the given flavour. Their
respective keywords are

`Mass`

invariant mass

`Q2`

DIS-like virtuality

`PT2`

pair transverse momentum

`MT2`

pair transverse mass

`DY`

rapidity separation

`DEta`

pseudorapidity separation

`DPhi`

azimuthal separation

`DR`

angular separation (build from eta and phi)

`DR(y)`

angular separation (build from y and phi)

`INEL`

inelasticity, one of the flavours must be in the initial-state (commonly used in DIS analyses)

## 5.7.4. Decay selectors¶

The selectors listed here implement cuts on the matrix element level, based on particle decays, see Decay and DecayOS.

`DecayMass`

Invariant mass of a decaying particle. The syntax is

- [DecayMass, <flavour code>, <min value>, <max value>]

`Decay`

Any kinematic variable of a decaying particle. The syntax is

- [Decay(<expression>), <flavour code>, <min value>, <max value>]

where

`<expression>`

is an expression handled by the internal interpreter, see Interpreter.`Decay2`

Any kinematic variable of a pair of decaying particles. The syntax is

- [Decay2(<expression>), <flavour1 code>, <flavour2 code>, <min value>, <max value>]

where

`<expression>`

is an expression handled by the internal interpreter, see Interpreter.

Particles are identified by flavour, i.e. the cut is applied on
*all* decaying particles that match `<flavour code>`

.
`<min value>`

and `<max value>`

are floating point
numbers, which can also be given in a format that is understood by the
internal algebra interpreter, see Interpreter.

## 5.7.5. Particle dressers¶

## 5.7.6. Jet selectors¶

There are two different types of jet finders

`NJetFinder`

k_T-type algorithm to select on a given number of jets

`FastjetFinder`

Select on a given number of jets using FastJet algorithms

Their respective syntax and defaults are

```
SELECTORS:
- NJetFinder:
N: 0
PTMin: 0.0
ETMin: 0.0
R: 0.4
Exp: 1
EtaMax: None
YMax: None
MassMax: 0.0
- FastjetFinder:
Algorithm: kt
N: 0
PTMin: 0.0
ETMin: 0.0
DR: 0.4
EtaMax: None
YMax: None
Nb: -1
Nb2: -1
```

Note that all parameters are optional. If they are not specified,
their respective default values as indicated in the above snippet is
used. However, at the very least the number of jets, `N`

,
should be specified to require a non-zero number of jets.

The `NJetFinder`

allows to select for kinematic configurations
with at least `<N>`

jets that satisfy both, the
`<PTMin>`

and the `<ETMin>`

minimum requirements and
that are in a pseudo-rapidity region `|eta|`

. The
`<Exp>`

(exponent) allows to apply a kt-algorithm
(1) or an anti-kt algorithm (-1). As only massless partons are clustered by
default, the `<MassMax>`

allows to also include partons with a mass
up to the specified values. This is useful e.g. in calculations with massive
b-quarks which shall nonetheless satisfy jet criteria.

The second option `FastjetFinder`

allows to use the FastJet plugin, through fjcore.
It takes the following arguments: `<Algorithm>`

can take the values
`kt,antikt,cambridge,eecambridge`

, `<N>`

is the
minimum number of jets to be found, `<PTMin>`

and `<ETMin>`

are
the minimum transverse momentum and/or energy, `<DR>`

is the radial
parameter. Optional arguments are: `<EtaMax>`

and `<YMax>`

as
maximal absolute (pseudo-)rapidity, `<Nb>`

and `<Nb2>`

set the
number of required b-jets, where for the former both b and anti-b
quarks are counted equally towards b-jets, while for the latter they
are added with a relative sign as constituents, i.e. a jet containing
b and anti-b is not tagged (default: -1, i.e. no b jets are required).
Note that only `<Algorithm>`

, `<N>`

and `<PTMin>`

are relevant
for the lepton-lepton collider algorithms.

The selector `FastjetVeto`

allows to use the FastJet plugin to apply jet veto cuts. Its syntax is
identical to `FastjetFinder`

.

The momenta and nodal values of the jets found with FastJet can also be used to calculate more elaborate selector criteria. The syntax of this selector is

```
- FastjetSelector:
Expression: <expression>
Algorithm: kt
N: 0
PTMin: 0.0
ETMin: 0.0
DR: 0.4
EtaMax: None
YMax: None
BMode: 0
```

wherein `Algorithm`

can take the values
`kt,antikt,cambridge,eecambridge`

. In the algebraic
`<expression>`

, `MU_n2`

(n=2..njet+1) signify the nodal values of
the jets found and `p[i]`

are their momenta. For details see
Scale setters. For example, in lepton pair production in
association with jets

```
- FastjetSelector:
Expression: Mass(p[4]+p[5])>100
Algorithm: antikt
N: 2
PTMin: 40
ETMin: 0
DR: 0.5
```

selects all phase space points where two anti-kt jets with at least 40
GeV of transverse momentum and an invariant mass of at least 100 GeV
are found. The expression must calculate a boolean value. The
`BMode`

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 `BMode: 1`

both b and anti-b
quarks are counted equally towards b-jets, while for `BMode: 2`

they
are added with a relative sign as constituents, i.e. a jet containing
b and anti-b is not tagged. Note that only `<epression>`

,
`<algorithm>`

, `<n>`

and `<ptmin>`

are relevant when using the
lepton-lepton collider algorithms.

## 5.7.7. Isolation selector¶

Instead of the simple `IsolationCut`

(Inclusive selectors), you may
also use the more flexible `Isolation_Selector`

to require photons (or other
particles) with a smooth cone isolation and additionally apply further criteria
to them. Example:

```
SELECTORS:
- Isolation_Selector:
Isolation_Particle: 22
Rejection_Particles: [93]
Isolation_Parameters:
R: 0.1
EMAX: 0.1
EXP: 2
PT: 0.
Y: 2.7
NMin: 2
Remove_Nonisolated: true
Subselectors:
- VariableSelector:
Variable: PT
Flavs: [22]
Ranges:
- [20, E_CMS]
- [18, E_CMS]
Ordering: [PT_UP]
- [DR, 22, 22, 0.2, 10000.0 ]
#for integration efficiency: m_yy >= sqrt(2 pTmin1 pTmin2 (1-cos dR))
- [Mass, 22, 22, 3.7, E_CMS]
```

## 5.7.8. Universal selector¶

The universal selector is intended to implement non-standard cuts on the matrix element level. Its syntax is

```
SELECTORS:
- VariableSelector:
Variable: <variable>
Flavs: [<kf1>, ..., <kfn>]
Ranges:
- [<min1>, <max1>]
- ...
- [<minn>, <maxn>]
Ordering: [<order1>, ..., <orderm>]
```

The `Variable`

parameter defines the name of the variable to cut
on. The keywords for available predefined can be figured by running
Sherpa `SHOW_VARIABLE_SYNTAX: true`

. Or alternatively, an
arbitrary cut variable can be constructed using the internal
interpreter, see Interpreter. This is invoked with the command
`Calc(...)`

. In the formula specified there you have to use place
holders for the momenta of the particles: `p[0]`

… `p[n]`

hold
the momenta of the respective particles `kf1`

… `kfn`

. A list of
available vector functions and operators can be found here
Interpreter.

`<kf1>,..,`

specify the PDG codes of the particles the
variable has to be calculated from. The ranges ```
[<min>,
<max>]
```

then define the cut regions.

If the `Ordering`

parameter is not given, the order of cuts is
determined internally, according to Sherpa’s process classification
scheme. This then has to be matched if you want to have different
cuts on certain different particles in the matrix element. To do this,
you should put enough (for the possible number of combinations of your
particles) arbitrary ranges at first and run Sherpa with debugging
output for the universal selector: ```
Sherpa 'FUNCTION_OUTPUT:
{"Variable_Selector::Trigger": 15}'
```

. This will start to produce
lots of output during integration, at which point you can interrupt
the run (Ctrl-c). In the `Variable_Selector::Trigger(): {...}`

output you can see, which particle combinations have been found and
which cut range your selector has held for them (vs. the arbitrary
range you specified). From that you should get an idea, in which order
the cuts have to be specified.

If the fourth argument is given, particles are ordered before the cut
is applied. Possible orderings are `PT_UP`

, `ET_UP`

,
`E_UP`

, `ETA_UP`

and `ETA_DOWN`

, (increasing
p_T, E_T, E, eta, and decreasing eta). They have to be specified for
each of the particles, separated by commas.

Examples

```
SELECTORS:
# two-body transverse mass
- VariableSelector:
Variable: mT
Flavs: [11, -12]
Ranges:
- [50, E_CMS]
# cut on the pT of only the hardest lepton in the event
- VariableSelector:
Variable: PT
Flavs: 90
Ranges:
- [50, E_CMS]
Ordering: [PT_UP]
# using bool operations to restrict eta of the electron to |eta| < 1.1 or
# 1.5 < |eta| < 2.5
- VariableSelector:
Variable: Calc(abs(Eta(p[0]))<1.1||(abs(Eta(p[0]))>1.5&&abs(Eta(p[0]))<2.5))
Flavs: 11
Ranges:
- [1, 1] # NOTE: this means true for bool operations
# requesting opposite side tag jets in VBF
- VariableSelector:
Variable: Calc(Eta(p[0])*Eta(p[1]))
Flavs: [93, 93]
Ranges:
- [-100, 0]
Ordering: [PT_UP, PT_UP]
# restricting electron+photon mass to be outside of [87.0,97.0]
- VariableSelector:
Variable: Calc(Mass(p[0]+p[1])<87.0||Mass(p[0]+p[1])>97.0)
Flavs: [11, 22]
Ranges:
- [1, 1]
# in ``Z[lepton lepton] Z[lepton lepton]``, cut on mass of lepton-pairs
# produced from Z's
- VariableSelector:
Variable: m
Flavs: [90, 90]
# here we use knowledge about the internal ordering to cut only on the
# correct lepton pairs
Ranges:
- [80, 100]
- [0, E_CMS]
- [0, E_CMS]
- [0, E_CMS]
- [0, E_CMS]
- [80, 100]
```

## 5.7.9. Minimum selector¶

This selector can combine several selectors to pass an event if either those passes the event. It is mainly designed to generate more inclusive samples that, for instance, include several jet finders and that allows a specification later. The syntax is

```
SELECTORS:
- MinSelector:
Subselectors:
- <selector 1>
- <selector 2>
...
```

The Minimum selector can be used if constructed with other selectors mentioned in this section