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.
Anatomy of a trigger
A trigger line, a trigger is called a trigger chain in ATLAS. It 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.
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- and
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.
Defining a chain inside a menu file - the ChainProp
jargon alert: menu file, menu python file, menu - these refer to the file that has a the long list of triggers in it - for example, LS2_v1.py or MC_pp_run3.py.
Chains are defined using a ChainProp objects inside of the menu files themselves. The ChainProp class is a namedtuple, defined inside ChainDefInMenu.py. The ChainProp allows for structuring the chain definition and has a very limited set of properties:
| Property | Use | Default value |
|---|---|---|
name |
the name of the trigger | - |
l1SeedThresholds |
what L1 RoI and 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 |
defines what monitoring groups the chain belongs to | [] |
We can now go through these one-by-one:
Trigger name
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_ + the important stuff + _L1ItemThatSeedsTheChain.
L1 seed thresholds
The L1 seed threshold 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!
Stream
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 add this. i.e. we want this:
stream=[PhysicsStream,'express']
never this:
stream=['express'].
Groups
The groups list is used for three purposes:
- To mark the purpose of trigger (primary or supporting)
- Not all trigger will have this designation, but all primary triggers should.
- This flag should only be added when specifically instructed to by menu coordination.
- do not flag triggers as primary or support without explicit approval
- To mark that the trigger belongs to specific prescale groups
- The only current flag here is
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 areHLT_timeburner_L1All, beamspot triggers, and minimum bias triggers.
- The only current flag here is
- To add the trigger to specific rate (
RATE) and bandwidth (BW) groups prefixes- This allows us to monitor the rate of all triggers in a named group together
- These rates show up in e.g.
pbeastand are saved into IS for later plotting. - When setting up combined triggers these groups need to be choose correctly.
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).
Monitoring groups
These groups designate the chains to be carefully monitored. It is typically decided by the signature groups which chains should be flagged with monitoring groups.
Chain dictionaries
During the first step of menu construction the ChainProp is translated to a
chain dictionaries (what we colloquially call a chainDict).
ChainDicts contain an information that is decoded from the ChainProp (e.g. the chain name) and supplemented by the knowledge specific to each signature. Since each signature has a different set of necessary parameters, the ChainDicts will be slightly different in each signatures. However, they all follow the same basic structure.
The parsing from ChainProp to ChainDict happens inside the file 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.