Guide to the CMS Trigger System

Documentation Guide

An event is the result of a single reading of the detector electronics capturing signals generated by particles from several bunch crossings. The online Trigger and Data Acquisition System (TriDAS) is tasked with selecting and storing the most interesting events (around 1000 events per second) from the millions of detected events. An event has to pass two independent sets of tests, or Trigger Levels, in order to qualify. These tests range from quick and simple (Level 1, called L1) to more complex and time-consuming (Levels 2 and 3, called the "high-level trigger", or HLT). Ultimately, the HLT system produces RAW data events containing:

the detector data,
the L1 trigger result
the HLT selection result (HLT trigger bits)
and some of the higher-level objects created during HLT processing.

Original Source: TriggerSystem

The HLT

The HLT contains many trigger paths, each corresponding to a dedicated trigger (such as a prescaled single-electron trigger or a 3-jets-with-MET trigger). A path consists of several steps (software modules). Each module performs a well-defined task such as unpacking (raw to digi), reconstruction of physics objects (electrons, muons, jets, MET, etc.), making intermediate decisions that trigger more refined reconstructions in subsequent modules, and calculating the final decision for a trigger path. The CMSSW Framework/EDM ensures that if an intermediate filter decision on a trigger path is negative, the rest of the path is skipped, and this specific trigger is regarded as rejecting the event. In order to save computation time, each reconstruction step is followed by a filter to skip unnecessary time-consuming reco code.

In general it is expected that all HLT trigger paths are run, even if the event is already accepted by a path. In case this turns out to be too time-consuming, a truncated mode of HLT operations should be expected. In the truncated mode, the HLT short-circuits after the first acceptance, once the necessary triggers for classifying the event for a primary data set and output stream are computed. The subsequent triggers would not be executed. Presumably, the triggers not run online could be run in the offline reconstruction to compute all trigger bits for events written out, so that we can get a complete trigger picture that allows trigger efficiency studies.

Each HLT trigger path must be seeded by one or more L1 trigger bit seeds: the first filter module in each HLT path looks for a suitable L1 seed (consisting of L1 bit(s) and L1 object(s)) as a starting point for that specific HLT trigger.

Original Source: SWGuideHighLevelTrigger

Persistent Trigger Results Objects and Available Software

AOD (2010-2012)

Two persistent HLT products are available:

TriggerResults: Contains all the usual decision bits. It is subclassed from HLTGlobalStatus object.

The TriggerResults product is available for events written to output. It provides access to both configuration information and trigger decisions, i.e., all the usual "trigger bits", including:
- Final decision of individual path and of full trigger table
- Which triggers were run (some triggers may not run due to lack of a corresponding L1 seed or HLT running in truncated mode)
- The index of the intermediate or final module instances on the path that rejected the event (for each trigger rejecting the event)
- The index of the module instances on the path that encountered un-recoverable errors (for each trigger encountering an error condition)
The corresponding code can be found in DataFormats/Common/interface/TriggerResults.h and DataFormats/Common/interface/HLTGlobalStatus.h
TriggerEvent: Summarises the "L3" trigger collections and "L3" filter decisions.

The corresponding code can be found in DataFormats/HLTReco/interface/TriggerEvent.h

Additionally, the package HLTrigger/HLTcore contains several analyzers that pull out the trigger information. You can use the corresponding analyzers directly - see their cfi files in the python subdirectory - or copy relevant code pieces into your modules. The TriggerSummaryAnalyzerAOD analyser prints the content of the TriggerEvent product. The HLTEventAnalyzerAOD analyser combines the information from TriggerResults and TriggerEvent products.

The HLTEventAnalyzer plugin makes use of the helper class HLTConfigProvider (also in HLTrigger/HLTcore), which extracts the HLT configuration (paths and modules) from the provenance.

Note: This helper class must be initialised by calling it's init(...) from the beginRun() method of your plugin. The helper class has to be (re-)initialised in beginRun(), because the HLT configuration can only change between runs.

Original Source: Persistent Trigger Results Objects

Find more software and usage instructions in

MiniAOD (2015 and beyond)

MiniAOD contains:

trigger bits associated to all paths
all the trigger objects that have contributed to firing at least one filter within the trigger
all objects reconstructed
L1 global trigger summary
the prescale values of all triggers

Trigger bits for each path are stored as edm::TriggerResults, as standard in CMSSW.

In order to access paths by trigger name, you can get an edm::TriggerNames instance from the Event, which translates indices in names. The mapping is the same in all events sharing the same trigger configuration, which is defined by the parameterSetID() method of the trigger results object.

Trigger objects associated to filters in the HLT are saved as instances of pat::TriggerObjectStandAlone, so that they can be used for e.g. trigger matching and measurements of trigger efficiency with the tag-and-probe method. The trigger names stored in the objects are packed, but they can be unpacked by passing an edm::TriggerNames instance.

Trigger prescale are encoded for each path into an pat::PackedTriggerPrescales, which can be unpacked with an edm::TriggerNames if access by path name is needed.

For tips and examples on accessing the trigger information, check the MiniAOD Analysis Documentation, which contains both example CMSSW code and example python code.

Find examples for accessing trigger information using POET (physics object extractor tool) in:

Physics object extractor tool for the CMS 2015 data.
CMS Open Data Workshops, particularly from 2022 and 2023.

Note: POET is not available for the CMS 2016 MiniAOD data, but the trigger information can still be accessed using EDAnalyzers similar to those available for 2015 MiniAOD.

NanoAOD (2016 and beyond)

In NanoAOD, trigger bit information is available for all trigger paths in the input files. The bits that are not available in some events are filled with zeros. Trigger objects are stored in NanoAOD for some filters as defined here. Trigger prescales are not stored in NanoAOD, but this information can be found using the brilcalc command line tool, as described in the last two sections of the CMS luminosity calculation guide.

Trigger information is stored in the following collections of branches:

L1_*: Trigger bit for each L1 path.
L1PreFiringWeight_*: L1 pre-firing event correction weight. Prefiring of L1 triggers represents a problem in their combined effect with the CMS trigger rules. It causes inefficiency in recording potentially interesting events. See the CMS Open Data Guide for more details.
HLT_*: Trigger bit for each HLT path.

HLT Trigger Path definitions

For each dataset, the possible HLT trigger paths are listed in the dataset record. Each HLT path is composed of different algorithms defined in the data-taking configuration files, which are given in:

The exact parameters (such as pT or eta cuts) for each component of the HLT path can be found in the data-taking configuration file.

For an example, if you are looking for information about the HLT_Dimuon10_Jpsi trigger, look for a string process.HLT_Dimuon10_Jpsi in the data-taking configuration file corresponding to the event range of your interest. You will find the corresponding CMSSW path, which consists of all the modules (i.e., specifically python-configured CMSSW code) and/or sequences (groups of modules) that make up that trigger path. You can then look for each of these modules or sequences in the same configuration file until you find the parameters with which they are configured.

As an example, you will find one of the modules of this path, hltDimuon10JpsiL3Filtered, by searching for process.hltDimuon10JpsiL3Filtered. You will see that it is an instantiation of class HLTMuonDimuonL3Filter:

process.hltDimuon10JpsiL3Filtered = cms.EDFilter( "HLTMuonDimuonL3Filter",

followed by the values of different parameters for this algorithm.

All HLT algorithm classes and definitions of the parameters therein can be found in HLTrigger. The example class above can be found in HLTMuonDimuonL3Filter.h. These two links lead to the code for CMSSW_5_3_X. Switch to the correct CMSSW version using the tab on the upper left of the pages.