# 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|siscone,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

## 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.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
f: 0.75        # Siscone f parameter
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,siscone,eecambridge,jade`, `<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: `<f>` (default 0.75, only relevant for the Siscone algorithm), `<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
f: 0.75
EtaMax: None
YMax: None
BMode: 0
```

wherein `Algorithm` can take the values `kt,antikt,cambridge,siscone,eecambridge,jade`. 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