Trigger Menu Basics

Last update: 09 Jul 2024 [History] [Edit]


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 which the following is supposed to clarify a bit . Some of this is based on the Trigger Glossary which contains many more definitions to look up. Only the ones relevant for this section will be defined below.

  • Trigger menu: List of all possible trigger selections, composed of L1 items and HLT trigger chains. The trigger menu includes the definition of the L1 items (e.g. inputs, logic, thresholds, outputs, see L1 item) and HLT trigger chains (e.g. stream, rate/bandwidth group, algorithm properties, see HLT trigger chains) as well as the configuration of the flow of the data between the algorithms (see control flow). Menus can be defined depending on their data-taking purpose (e.g. proton-proton collisions, heavy ions, cosmic menu).
  • Trigger menu prescale set: Defines the composition of active trigger chains in terms of their prescales for the L1 seed item and the HLT selection.
  • Bunch group set: A set of 16 bunch groups, each being a bit-pattern of length 3564 (the number of LHC bunches). These patterns are based on the fill pattern of the LHC and the physics-driven definition of masks to select various types of triggers based on bunch locations relative to the colliding bunches. These patterns are used in the L1CT (aka. CTP) for the formation of the L1 items. There can be many prescale sets for one menu, e.g. defining a set of triggers for a given luminosity step.
  • Prescale Key (PSK): An integer which is the index of the entry in the trigger configuration database (see TriggerDB) describing the prescaling of the L1 items and HLT chains. Separate prescale keys exist for L1 and HLT.
  • Super master key (SMK): An integer which is the index of the entry in the trigger configuration database (see TriggerDB) describing the configuration of the L1Topo algorithms, the available trigger items and their composition in the L1CT, and the HLT chains, streams and job-options, i.e. the configuration of the trigger menu.
  • Bunchgroup key (BGSK) An integer which is the index of the entry in the trigger configuration database (see TriggerDB) describing the bunch group set.
  • L1 item: L1 items are formed in the L1CT and are logical combinations of physics objects from eFEX, jFEX and gFEX systems on the calorimeter side and MUCTPI on the muons side after they have been processed by L1Topo. In the L1Topo the trigger physics objects identified by those systems are counted and possibly topological selections are applied. Before contributing to the L1-accept signal, the bunch mask of one or more of the 16 bunch groups is applied to each of the L1 items. L1 items are formed and evaluated for each bunch crossing.
  • HLT Trigger chain: Each trigger chain represents a logical trigger selection, the union of all from the trigger decision. Trigger chains are in most cases seeded by specific L1 items, though sometimes by more than one or all L1 items. If the L1 seed is satisfied and prescaling information has been evaluated the HLT processing is started. HLT trigger chains are identified by unique names (see Run 3 naming convention ) with properties like seeding items, output stream(s), rate and bandwidth group, and the athena algorithm properties assigned to them.
  • Step: The configuration of a chain is made up of one or several steps, each step is represented by an instance of the 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.
  • Menu Sequence: Each menu sequences is made up of one InputMaker algorithm, followed by reconstruction algorithms and completed with one hypothesis testing algorithm.
  • Reconstruction algorithms: See the section on Reconstruction Algorithms
  • Hypothesis algorithms: See the section on Hypothesis Algorithms
  • Control Flow (CF): Configures an execution graph made of Athena Sequencers that logically collect executions of algorithms. Athena Sequencers represent the control flow nodes. The filter algorithms are used to allow or skip the execution of a given node. This produces early termination of an execution path if triggers are not accepted.
  • Data Flow (DF): Gaudi scheduler execution is based on the Data Flow, meaning that the execution order is ruled by the availability of data handles.
  • HLT Filter Algorithm: This is the Region of Interest Sequence Filter (RoRSeqFilter) which filters HLT decisions and impacts the Control Flow.
  • InputMakerAlg/EventViewCreatorAlg: It inherits from InputMakerBase and starts the sequence, creates the collections for the first RecoAlg, propagates decisions to the HypoAlg; The EventViewCreator, in addition, creates the EventViews.
  • Athena Sequencer (AthSequencer): Sequence used to collect algorithms that need to run in a Menu Sequence, with all algorithms already configured and connected via data handles. It needs to include the InputMaker algorithm providing the appropriate object needed to start the reconstruction in a step. In case of processing in EventViews, the additional algorithm EventViewVerifier may be necessary to propagate objects from EventViews in the previous step. The sequencers are configured to form either an 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.
  • TriggerDB: The trigger configuration database (TriggerDB) is a relational database (currently available only in Oracle) which holds those parts of the trigger configuration that are related to the physics implementation of the trigger on the L1 side and the list of trigger chains and streams as well as the entire job configuration (athena algorithm properties) on the HLT side. It also holds the complete trigger prescaling information, the definition of the L1CT bunchgroups and the setup of the monitoring. Several databases exist, for data taking, reprocessing, and Monte Carlo simulation. The configuration data is accessed through configuration “keys” (see SMK, PSK, BGSK), which are the indexes of the corresponding entries in the database tables.

The TriggerMenuMT package

The TriggerMenuMT package is divided into two sub-directories:

  • L1 for L1 configuration details and
  • HLT for the HLT configuration of trigger chains.

The generateMT function in 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:

  • All chains defined in a given menu (e.g. are read into a big list.
  • For each chain, a dictionary is generated by
  • The chain dictionaries are then prepared to be passed to the corresponding signature code to generate the chain step configuration. This means in particular:
    • Combined chains: The dictionary is divided according to the signatures of the combined chain and sent to the corresponding signature code. The returned configuration will then be combined given the merging strategy specified in the chain definition.
    • Chains of one signature type with more than one leg (e.g. HLT_mu6_mu8): The dictionary with both chain parts is passed to the corresponding signature code, similarly to the case of a chain with multiplicity great than 1 (e.g. HLT_2mu6). The multiplicities are then handled according to the specific setups within a given signature.
  • The dictionaries are sent to the corresponding signature code. The handling of the step setup is individual to a signature and won’t be discussed here. The signature code sends back a Chain object which is defined in to contain the HLT chain name, the L1 item seeding the chain and a list of chain steps.
  • The configuration of all chain objects is then added to a list and passed to the control flow via the makeHLTTree function.
    • Please note: As an additional step, the merging of the 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.

Chain definition

The chain definition in a menu is based on a namedtuple defined in with some default values assigned. This is subject to changes, so please refer to the file for up-to-date information.

Chain name decoding and allowed values

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 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.

Signature specific code

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:

  • The function generateChainConfigs(chainDict) is called from the generateMT and is defined in this file. It handles the forwarding of the dictionary to the to set up the steps as well as the above described cases of multiple muon chain dictionaries for specific chains.
  • 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 = {
              "Comb":[self.getmuFast(), self.getmuComb()],
              "ivar":[self.getmuFast(), self.getmuComb(), self.getmuIso()],
              "noL1":[self.getFSmuEFSA(), self.getFSmuEFCB()],
          key = self.chainPart["extra"]+self.chainPart["isoInfo"]
          for step in steps:
          myChain = self.buildChain(chainSteps)

There can be additional files in the signature directory, in the muon example, we have additionally:

  • Setup of all the different algorithms that are needed to reconstruct muons (including data prepreparation, L2, and EF)
  • Contains the various sequences needed in the steps, including the maker, hypo and hypo tool
  • Configuration for the L2 algorithms, which will be moved to be within the offline muon configuration code Generally, these additional files should be kept to a minimum though.

A very important remark to add here is that when sequences are being prepared, a check is required to see if they have been declared already via the RecoFragmentsPool.retrieve(XXXAthSequence, flags), which automatically checks if the same sequence has been already instantiated, and returns the link to it.

Generation of control flow

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 and makes use of further functions in

How to add a trigger chain

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.

Preparing the algorithms and steps

  • Create the HypoAlg, which is inherited from HypoBase, see an example TrigL2CaloHypoAlgMT
  • Create HypoTools, an example is TrigL2CaloHypoToolInc
  • Configure the HypoTools like in Please not that there is a defined format required, for example TrigL2CaloHypoToolFromName( name, conf )
  • Create a configuration file, in which all the menu sequences are included and configured, an example is in Make a function for any sequence creation and instantiate the algorithms follow this logic:
    • The feature extraction algorithms needed to create the offline objects to be processed by the hypo, with all their configurations
    • The EventViewCreatorAlgorithm, needed to run in the views, alternatively add one InputMaker
    • The Hypo
    • Import the HypoTools
    • The sequences:
      • AthSequencer containing the algorithms running in views configured as parallel OR, an example is: sequenceView = parOR(name, [alg or seq])
      • AthSequencer with all feature extraction algorithms configured as sequential AND: an example is: mysequence =seqAND(name, [alg or seq])
      • MenuSequence with an example being: MenuSequence( Sequence = fastCaloAthSequence, Maker = fastCaloViewsMaker, Hypo = theFastCaloHypo, HypoToolGen = TrigL2CaloHypoToolFromName )

Adding a chain to TriggerMenuMT

Once all the algorithms are set up and ready, you can add the chain in a menu. For triggers in development, this is

  • Make sure you define the chain in the correct signature list with all needed parameters, please take a look at the base class in
  • Make sure all strings of your chain name are following the naming convention and are listed in
  • Check the corresponding logic in your signature directory and if needed, implement the steps that are needed in this particular chain. This is normally done in e.g.
  • Add some top level steering of the dictionary, that is passed in ‘’.

Adding a new signature to TriggerMenuMT

In order to add or activate a new signature to TriggerMenuMT, the procedure is:

  • If it doesn’t exist yet, create a new slice in the corresponding menu by adding a new key to the chains object. E.g.
      chains["Awesome"] = [ ... ]
  • A file with the slice generation has to exist with the exact name in the folder Awesome, as the slice is generated via this line
    • Several slices can be defined in the same folder. Follow the example of Photon or Streaming.

How to test your changes

Please refer to the section Testing of code changes in this guide.