The ATLAS trigger menu consists of several hundreds of trigger chains which are used during data taking. Each chain defines the selection criteria at the first and high-level trigger for one or several physics signatures.
The TriggerMenuMT package contains the Run 3 trigger menu and chain configuration and replaces the Run-2 TriggerMenu package. It’s designed to define the chains in terms of their names, streams, bandwidth and rate groups and other properties, to configure them in terms of steps and the sequences within the steps and to build the control flow.
General information about the menu group and and its organisation can be found on the TriggerMenuInformation twiki.
For more advanced information, please see the topic-specific guides under “Trigger Menu for Experts”.
There is quite some terminology connected to this topic, for which brief definitions of the most relevant terms are given below. For more extensive definitions, see the Trigger Glossary. References to technical terms/code classes are made here instead.
ChainStep class. Each step is made of a list of MenuSequences. Each menu sequence is executed on a single decision object, so single decision chains will only have one MenuSequence per step. The division into steps allows further processing to be avoided if a (fast) negative decision is made in an earlier step. It also allows (event-wide) early rejection if there are no chains passing a given step.MenuSequence class. It includes reconstruction algorithms and a hypothesis algorithm, as well as additional supporting infrastructure algorithms.EventViews, the additional algorithm EventViewVerifier may be necessary to propagate objects from EventViews in the previous step.AND or an OR of the status of their children and return this as their own status. They can be configured in two ways, parallel or sequential, depending on the way the children are allowed to be executed. In the HLT Control Flow we have two main configurations: sequential AND (seqAND) and parallel OR (parOR). The seqAND returns immediately upon any child returning False, and does not execute any remaining children.RoRSeqFilter class.InputMakerAlg/EventViewCreatorAlgEventViewCreator, in addition, creates the EventViews. Inherits from InputMaakerBase.See also the following sections for information on the two major HLT algorithm classes:
The TriggerMenuMT package is divided into two sub-directories:
L1 for L1 configuration details andHLT for the HLT configuration of trigger chains.The generateMT function in GenerateMenu.py handles the generation of the menu configuration for L1 and HLT.
The L1 menu generation code has three components, Base, Config and Menu
Config/ contains the high-level building blocks of a menu, such us algorithms for L1Topo, and thresholds, and items for the CTP. Here new topological algorithms, muon and calorimeter thresholds, and CTP items should be added. The directory further contains information about the inputs from the L1Topo, and MUCTPI on the CTP side.Base/ contains the python classes for the objects that form the L1 menu objects, e.g the L1Items and the L1TopoAlgorithms without any menu-specific content. It should be touched only by people familiar with the trigger configuration code.Menu/ contains the top-level definition of the L1 trigger menu for different types of data taking (pp, HI, MC). This comprises the algorithm assignment of the L1Topo output and the L1 item assignment in the CTP output.Details are in section L1 Menu Construction.
The generation of the HLT trigger menu configuration can be summarised in the following steps:
Physics_pp_run3_v1.py)
are read into a big list.DictFromChainName.py.
SignatureDicts.py.Chain object which is defined in
MenuComponents.py to contain the HLT chain name, the L1 item seeding the chain and a list of chain steps.makeHLTTree function.
Chain objects for combined chains will need to be handled, this still needs implementing in the control flow.The sections below contain a little more detail on the steps for developers.
The chain definition in a menu is based on a namedtuple defined in
ChainDefInMenu.py with some default values assigned. This is subject to changes, so please refer to the file for up-to-date information.
The chain name decoding has not changed w.r.t. the version implemented in Run 2 and is based on the same concept. The allowed values for each signature are defined in the
SignatureDicts.py.
An example for a dictionary for a chain of type HLT_e3_etcut1step_L1EM3 is:
{ "L1item": "L1_EM3",
"chainCounter": 1,
"chainMultiplicities": ["1"],
"chainName": "HLT_e3_etcut1step_L1EM3",
"chainParts": [ { "IDinfo": "",
"L1item": "",
"L2IDAlg": "",
"addInfo": ["etcut1step"],
"caloInfo": "",
"chainPartName": "e3_etcut1step_L1EM3",
"etaRange": "0eta250",
"eventBuildType": "",
"extra": "",
"isoInfo": "",
"lhInfo": "",
"multiplicity": "1",
"signature": "Electron",
"threshold": "3",
"trigType": "e",
"trkInfo": ""}],
"groups": ["RATE:SingleElectron", "BW:Electron"],
"signature": "Electron",
"signatures": "",
"stream": ["Main"],
"topo": [],
"topoStartFrom": False }
Most information is extracted by the DictFromChainName code from the chain name itself, e.g. the signature type, L1 item and the chainPart specific fields.
However some information needs to be specified in the definition of the chain, like e.g. the bandwidth and rate groups and merging strategy (not shown here as it’s a single electron chain). The chainParts key is a list of signature specific sub-directories which will contain more entries in case of multi-leg chains.
The dictionary keys can be chosen freely by each signature. Please make sure to remove obsolete strings. An explanation of the meaning of each sub-string can be found here - not yet setup- pointing to Run2 twiki.
Each signature has a subdirectory under TriggerMenuMT/python/HLT/. The structure of the signature code will be explained at hand of the muon signature. Within the directory, there are two files generally needed by the TriggerMenuMT framework:
GenerateMuonChainDefs.py: The function generateChainConfigs(chainDict) is called from the generateMenuMT in HLT/Config/generateMenuMT.py and is defined in this file. It handles the forwarding of the dictionary to the MuonChainConfiguration.py to set up the steps as well as the above described cases of multiple muon chain dictionaries for specific chains.MuonChainConfiguration.py: The class MuonChainConfiguration in this file is based on a base class
ChainConfigurationBase
which can be extended with functions from which most/all signatures can benefit.
Please feel free to add code to this class to reduce the lines in each signature specific code.
Within this class, the steps of the particular chain that is being configured, are set up.
This can be done in form of a dictionary to avoid the many if-elif-else statements we had in the Run 2 code, e.g.
stepDictionary = {
"":(self.getmuFast(),self.getmuComb(),self.getmuEFSA(),self.getmuEFCB()),
"fast":[self.getmuFast()],
"Comb":[self.getmuFast(), self.getmuComb()],
"ivar":[self.getmuFast(), self.getmuComb(), self.getmuIso()],
"noL1":[self.getFSmuEFSA(), self.getFSmuEFCB()],
}
key = self.chainPart["extra"]+self.chainPart["isoInfo"]
steps=stepDictionary[key]
for step in steps:
chainSteps+=[step]
myChain = self.buildChain(chainSteps)
There can be additional files in the signature directory, in the muon example, we have additionally:
MuonMenuSequences.py: Contains the various sequences needed in the steps, including the maker, hypo and hypo toolMuonRecoSequences.py: Configuration for the reconstruction algorithms, shared with the offline muon configuration code.
Generally, these additional files should be kept to a minimum though.More details about the menu generation is here.
The control flow is then generated based on the Chain object that was passed from the signature specific code containing the configuration of the chain steps. This happens in the function makeHLTTree which is located in HLTCFConfig.py and makes use of further functions in MenuComponents.py and HLTCFComponents.py.
More details on the Control Flow generation is in this section.
To add a new trigger chain, please follow the steps outlined below. You will first need to get the steps ready in terms of algorithms before being able to add them as part of a trigger chain to to TriggerMenuMT. Sometimes you’ll be able to skip a step if e.g. the algorithms have been prepared already.
TrigL2CaloHypoAlgMTTrigL2CaloHypoToolIncTrigL2CaloHypoTool.py
Please not that there is a defined format required, for example TrigL2CaloHypoToolFromName( name, conf )MuonMenuSequences.py.In this latter file create a function for any sequence generation and instantiate all the algorithms, which must include:
In this function make use of dedicated classes that allow to properly configure the MenuSequence in the correct way. For this purpose, instantiate these CA classes following the hierarchy described in details in this section:
SelectionCA to represent the full reconstruction sequence, plus the HypoAlg in CA mode and give the name to the sequenceInViewRecoCA to include all the reconstruction within ViewsMenuSequence to merge selection and HypoTools, representing the complete sequence; an example being: MenuSequence(flags, selectionCA, HypoToolGen = TrigMufastHypoToolFromDict)Please remember that:
sequenceView = parOR(name, [alg or seq])mysequence =seqAND(name, [alg or seq])Once all the algorithms are set up and ready, you can add the chain in a menu. For triggers in development, this is
Dev_pp_run3_v1.py
ChainDefInMenu.pySignatureDicts.pyMuonChainConfiguration.pyIn order to add or activate a new signature to TriggerMenuMT, the procedure is:
chains object. E.g. Dev_pp_run3_v1.py
chains["Awesome"] = [ ... ]
GenerateAwesomeChainDefs.py in the folder Awesome, as the slice is generated via this line
Photon or Streaming.Please refer to the section Testing of code changes in this guide.