This documentation is meant to for every ATLAS user who wants to know about the details of the trigger chains, how they are defined and maybe even what these long names actually mean. Primarily however, this documentation is meant for beginner menu developers. Therefore in some sections you can find also instructions and warnings.
In ATLAS, a trigger trigger chain, or “trigger” for short, is the sequence of a level-1 (L1) hardware decision logic seed and some high-level trigger (HLT) software reconstruction algorithms (that e.g. reconstruct some muons) and hypotheses (that e.g. make sure these muons pass the correct thresholds). Both the L1 and HLT components have an associated prescale, which says what fraction of possible times you want the trigger to actually consider the events.
Let’s start by going through a simple trigger that some of you might use in your analyses: HLT_2mu14_L12MU10
.
This trigger has a level-1 seed of L1_2MU10
. This means that, in order to pass the event to the HLT at least two 10 GeV GeV muon regions of interest (RoIs) need to be observed by the level-1.
This trigger is a primary trigger, meaning it is identified as being one of the key triggers for the ATLAS physics programme. Additionally, it is unprescaled, meaning the prescale of this trigger is always exactly one at both L1 and HLT: there is no artificial reduction in the fraction of events that could pass this chain. The L1_2MU10
item is flagged as passing in all events that have two, 10 GeV muon RoIs, and we process the HLT algorithms on all events that the L1 item passes. The fact that it is a primary chain is not reflected in the name. Unless particular issues are found during data-taking that require prescaling a specific trigger (for example, a problem in a sector or sub-detector of the muon spectrometer), all chains marked as primary will always be unprescaled.
In events where the L1 item has been satisfied, the HLT runs muon reconstruction around all the muon RoIs that are of the correct pT. These RoIs are said to seed the HLT reconstruction. For example, in HLT_2mu14_L12MU10
, the muon reconstruction is seeded by all MU10
RoIs, but the pT thresholds do not have to match - this is a choice that we make when configuring the trigger.
After each step in the reconstruction, a combination checking algorithm, (ComboHypo
) runs, and makes sure that there are actually two unique HLT objects - i.e. that the trigger satisfies a multiplicity of 2.
The ATLAS uses many chains that impose requirements on diverse objects. They are referred to as combined chains. Their evaluation by the HLT is decomposed into so called legs. Each leg is responsible for steering different reconstruction algorithms. Each leg has its own L1 seed and implements independently the multiplicity requirement. Simple trigger chains can be viewed as a complex chain with a single leg. As is the case for simple trigger chains the L1 seeds do not have to actually exactly match the L1 item that seeds the trigger chain itself.
For example, the chain HLT_2mu14_L12MU10
has one leg with multiplicity two ([2]
) and 2mu14
is seeded by 2MU10
. The chain HLT_2mu10_j40_L12MU10
has two legs, the muon
one with multiplicity 2 and the jet
one with multiplicity 1 ([2,1]
). The chain HLT_2mu10_mu6noL1_L12MU10
also has two legs,
this time two muon
ones with multiplicity 2 on the first leg and multiplicity 1 plus special reconstruction noL1
on the second leg.
For combined chains the seeding RoIs need to be explicitly defined (are not interfered from the L1 item name) in the menu.
An example of a real, five leg chain that is currently in the menu is HLT_j70_0eta320_j50_0eta490_j0_dijetSEP50j12etSEP1000djmassSEPdjdphi240_xe90_tcpufit_xe50_cell_L1MJJ-500-NFF
, where each of the five legs have multiplicity one. The legs are:
j70c
- requiring 70 GeV jet in the central detector (c postfix)j50a
- requiring 50 GeV jet within all of the calorimeter acceptance (a postfix)j0_dijetXX50j12etXX1000djmassXXdjdphi240
– this is not demanding another object but adds a requirement on the two jets to have dPhi greater than 0.240 and invariant mass > 100 GeVxe65_cell
xe90_nn
- requires that the ETmiss is measured in the event, via basic calorimeter cell and sophisticated neural net methods. In this case the two methods are combined with different thresholds to have optimal signal efficiency and background rejection.The sections required to configure each trigger leg are listed in SignatureDicts.py
. As the examples above show, they will be different for each signature, and not all legs need to contain all sections.
ChainProp
objectChains are defined using a ChainProp
objects inside of the menu files themselves, which will be introduced here. The ChainProp
class, defined inside
ChainDefInMenu.py
. The ChainProp
allows for structuring the chain definition, with the following important properties:
Property | Use | Default value |
---|---|---|
name |
The name of the trigger | - |
l1SeedThresholds |
What L1 RoI/threshold seeds each leg | [] |
stream |
What stream(s) does this trigger direct the events to | ['Main'] |
groups |
What prescale/rate groups should this trigger be in | [] |
monGroups |
What monitoring groups the chain belongs to | [] |
We can now go through these one-by-one:
The trigger name (often also called the chain name) encodes nearly everything for the chain. Every piece of the name holds some important meaning, and it must follow the Run 3 naming convention.
Names are structured as follows:
HLT_
+ chain definition + _L1ItemThatSeedsTheChain
.
The contents of the chain definition are not arbitrary, and must be restricted to the definitions provided by each signature, as described in the previous section.
Combined selections over multiple legs can be performed through ComboHypo hypothesis algorithms, as described in this section.
Streamer HLT chains are a special case of triggers whose accept signal is propagated from the L1 trigger, without any additional HLT selection. Those triggers contain the noalg
keyword (e.g. HLT_noalg_L1MBTSA0
), but can contain additional tag or partial event building (PEB) keywords (e.g. HLT_noalg_laser_TilePEB_L1CALREQ2
).
The L1 seed thresholds variable must be a list with the same length as the number of legs in the trigger.
Jets, MET, and noL1 muons and few other corner cases run unseeded, and must be seeded by FSNOSEED
.
Electrons and photons must be seeded by an eEM
threshold, muons by a MU
threshold, and taus by an eTAU
or cTAU
threshold.
Thresholds must be defined in the L1 menu, but do not need to correspond to the L1 item that seeds the chain.
For example, the chain HLT_2mu10_e5_L12MU10
should be seeded by ['MU10','eEM5']
: but this does not mean that the L1 item needs to actually contain eEM5
.
In this case, what happens is the very first HLT step applies a requirement on eEM5
in addition to 2MU10
,
and if there are no eEM5
RoIs in the event the reconstruction does not proceed and the trigger would not accept such an event.
The choice of MU10
to seed muon reconstruction seems obvious, but it is not always the case: for example, should e9
chain leg be seeded by eEM9L
or eEM9
? Never guess, always check with the relevant signature group!
The stream indicates where the events selected by the trigger are going to be written out. All possible choices are listed inside StreamInfo.py
. For physics triggers, this is generally Main
, i.e. physics_Main
, but this will not always be the case. You should be especially careful to clarify exactly which stream the trigger should go into when preparing monitoring or partial event building (PEB) triggers!
As you can see in the table above, the stream
parameter is set to default as ['Main']
. Thus, for many triggers in the menu this stream is not explicitly defined.
The only case in which a trigger should go into more than one stream is when one of those streams is 'express'
. No trigger should go only into express
, so if you are requested to add a trigger into the express stream when it does not already have an explicit stream=[PhysicsStream]
in the ChainProp
, make sure to use stream=[PhysicsStream,'express']
, and not this stream=['express']
.
The groups list is used for three purposes:
PS:Online
, which means that these triggers do not run in either MC or data reprocessings - we only intend them to run online. They are disabled in the default prescale sets prepared when the menu is generated. Examples of such triggers are HLT_timeburner_L1All
, beamspot triggers, and minimum bias triggers.RATE
) and bandwidth (BW
) groups prefixes
pbeast
and are saved into IS (Information Service) for later plotting.Most of the groups should be designated using the variables set inside Physics_pp_run3_v1.py
. These are imported at the top of the menu file (if the required group is not yet imported, you can add it).
These groups designate the chains to be monitored by the Trigger monitoring infrastructure, defined in the packages defined in the TrigMonitoring
Athena directory. Each signature subgroup should decide which chains should be configured with the appropriate monitoring group, as described in the Monitoring Groups section.
During the first step of menu construction, each ChainProp
object is translated to a more descriptive and comprehensive chain dictionary, which we colloquially call chain-dicts
. These dictionaries contain an information that is decoded from the ChainProp
(e.g. the chain name), supplemented by the knowledge specific to each signature.
Since each signature has a different set of necessary parameters, the ChainDict
s will be slightly different in each signatures. However, they all follow the same basic structure.
The logic for parsing the chain name, and the information in the member variables of each ChainProp
, to the corresponding entry ChainDict
is performed within DictFromChainName.py
.
It is crucial that the parameters in the ChainDict
be correctly set, since this is what the signature and menu code later uses to configure the the algorithms and hypothesis tools that comprise a trigger.