L1GtUtils utility class

This page is obsolete for data taken >=2016 To see an example for >=2016 data the best we can do is this example module L1MenuExample.cc, l1MenuExample.py

Introduction

The L1GtUtils utility class aims to provide an easy access to the main L1 trigger quantities for the central bunch cross (with L1 accept L1A) and physics partition, hiding the implementation details (L1 trigger event setup records, L1 trigger EDM products, input tags, etc)

• Decision before trigger mask for a given algorithm or technical trigger
• Decision after trigger mask for a given algorithm or technical trigger
• Prescale factor for a given algorithm or technical trigger
• Trigger mask for a given algorithm or technical trigger
• Prescale factor set index, prescale factor set and trigger mask set for algorithm triggers and technical triggers
• Name of the trigger menu used for the data set
• Pointer to the L1 trigger menu from event setup (starting with Version 2 only)
• Pointer to the L1GtTriggerMenuLite product (starting with Version 2 only)
• Check if L1 trigger configuration is available (starting with Version 2 only)
• Check consistency of L1GtTriggerMenuLite with the event setup (not available yet)

It retrieves the required L1 trigger configuration from event setup and/or from the L1GtTriggerMenuLite product and it caches it. It also retrieves the required EDM products required for the trigger decison (either L1GlobalTriggerReadoutRecord or the lite L1GlobalTriggerRecord). The class works on RECO and AOD data tiers. In case one uses it on RAW data, one has to unpack first the raw data.

For the methods requiring the EDM products, the input tags for the required products could be required to be found using the provenance. They are found once per run and cached (Version 3).

In case the user wants to control the input tags, there are also equivalent methods taking the input tags as input.

Please contact the responsible of this page in case more quantities are necessary to be included.

Usage of L1GtUtils class in an EDM analyzer, filter or producer

A fully working example is available in package L1Trigger/GlobalTriggerAnalyzer in the L1GtAnalyzer, method analyzeL1GtUtils.

Version 3

Version 3 starts with L1Trigger/GlobalTriggerAnalyzer V02-00-00. Due to the usage of the class in HLT, retrieving the input tags from provenance had to be optimized and cached per run. The methods deprecated in Version 2 were also removed.

The only changes needed for Version 3 concern the retrieval of the L1 trigger configuration. All comments and methods for Version 2 remain valid in Version 3.

Use case 0

    // Use case           0 - Retrieve L1 trigger configuration from L1GtTriggerMenuLite only

    bool useL1EventSetup = false;
    bool useL1GtTriggerMenuLite = true;

    // could be added in beginRun(...) - if not added, the caching will be done in analyze/produce/filter method
    m_l1GtUtils.getL1GtRunCache(iRun, evSetup, useL1EventSetup, useL1GtTriggerMenuLite);

    // must be added in analyze/produce/filter method
    m_l1GtUtils.getL1GtRunCache(iEvent, evSetup, useL1EventSetup, useL1GtTriggerMenuLite);

Use case 100000

    // Use case 100000 - Fall through: try first L1GtTriggerMenuLite; if not valid,try event setup.

    bool useL1EventSetup = true;
    bool useL1GtTriggerMenuLite = true;

    // could be added in beginRun(...) - if not added, the caching will be done in analyze/produce/filter method
    m_l1GtUtils.getL1GtRunCache(iRun, evSetup, useL1EventSetup, useL1GtTriggerMenuLite);

    // must be added in analyze/produce/filter method
    m_l1GtUtils.getL1GtRunCache(iEvent, evSetup, useL1EventSetup, useL1GtTriggerMenuLite);
    

Use case 200000

    // Use case 200000 - Retrieve L1 trigger configuration from event setup only.

    bool useL1EventSetup = true;
    bool useL1GtTriggerMenuLite = false;

    // could be added in beginRun(...) - if not added, the caching will be done in analyze/produce/filter method
    m_l1GtUtils.getL1GtRunCache(iRun, evSetup, useL1EventSetup, useL1GtTriggerMenuLite);

    // must be added in analyze/produce/filter method
    m_l1GtUtils.getL1GtRunCache(iEvent, evSetup, useL1EventSetup, useL1GtTriggerMenuLite);
    

Use case 300000

This case is not recommended to be used, as it will produce immediately an error.

In case one desires to control the input tag of L1GtTriggerMenuLite, one replaces in all the calls the method getL1GtRunCache with

    // L1GtTriggerMenuLite input tag given in configuration file

    // could be added in beginRun(...) - if not added, the caching will be done in analyze/produce/filter method
    m_l1GtUtils.getL1GtRunCache(iRun, evSetup, useL1EventSetup, useL1GtTriggerMenuLite, m_l1GtTmLInputTag);
 
    // must be added in analyze/produce/filter method
    m_l1GtUtils.getL1GtRunCache(iEvent, evSetup, useL1EventSetup, useL1GtTriggerMenuLite, m_l1GtTmLInputTag);

Note: in Version 3, one can not mix events with different input tags for the L1 GT records (anyhow, a very complex process, not really recommended). Runs with different input tags are OK.

Version 2

Version 2 retrieves the required L1 trigger configuration from event setup and/or from the L1GtTriggerMenuLite product.

The following use cases are implemented, where the number in the table is the number added to the error code returned by the calling methods in case of an error and the value of l1ConfCode, returned by the method const bool L1GtUtils::availableL1Configuration(int& errorCode, int& l1ConfCode) const.

    L1 configuration code returned by the method 
        "const bool L1GtUtils::availableL1Configuration(int& errorCode, int& l1ConfCode) const";

            Legend:
                     0 - Retrieve L1 trigger configuration from L1GtTriggerMenuLite only
             10000     L1GtTriggerMenuLite product is valid
             99999     L1GtTriggerMenuLite product not valid. Error.
            
            100000 - Fall through: try first L1GtTriggerMenuLite; if not valid,try event setup.
            110000     L1GtTriggerMenuLite product is valid
            120000     L1GtTriggerMenuLite product not valid, event setup valid.
            199999     L1GtTriggerMenuLite product not valid, event setup not valid. Error.
            
            200000 - Retrieve L1 trigger configuration from event setup only.
            210000     Event setup valid.
            299999     Event setup not valid. Error.
            
            300000 - No L1 trigger configuration requested to be retrieved. Error.
                       Must call before using L1GtUtils methods at least one of the following:
                       retrieveL1GtTriggerMenuLite or retrieveL1EventSetup.

Use case 0

    // Use case           0 - Retrieve L1 trigger configuration from L1GtTriggerMenuLite only

    m_l1GtUtils.retrieveL1GtTriggerMenuLite(iEvent, m_l1GtTmLInputTag);
    

Use case 0 is recommended to be used always when analyzing MC samples produced with a given global tag and analyzed with the same release or another release and a different global tag. As explained in this FAQ or, directly, in Potential problem for static global tags, in this case there is the danger to pick up a wrong configuration for the L1 trigger. Please note: when using this case, only the L1 trigger configuration included in L1GtTriggerMenuLite is guaranteed to be correct. For every other record (L1 trigger or other subsystems) please follow the advice from this FAQ.

It is also recommended to be used (on data or MC samples) in environments where the event setup is not available.

Use case 100000

    // Use case 100000 - Fall through: try first L1GtTriggerMenuLite; if not valid,try event setup.

    m_l1GtUtils.retrieveL1EventSetup(evSetup);
    m_l1GtUtils.retrieveL1GtTriggerMenuLite(iEvent, m_l1GtTmLInputTag);
    

Use case 100000 is recommended to be used on data sets where not all the data have L1GtTriggerMenuLite available. Not recomended to be used on MC samples, as long as the global tags do not have a proper IoV association.

Use case 200000

    // Use case 200000 - Retrieve L1 trigger configuration from event setup only.

    m_l1GtUtils.retrieveL1EventSetup(evSetup);
    

Use case 200000 is recommended to be used when the L1GtTriggerMenuLite is known to not be available, as for example online in HLT code. It is also safe to be used on data, where the global tags have a correct IoV association (although also here it is recommended to use use case 0).

Use case 300000

This case is not recommended to be used, as it will produce immediately an error.

Usage of Version 2 of L1GtUtils class in an EDM analyzer, filter or producer

In the private part of the analyzer class header (e.g. L1GtAnalyzer.h - replace it with the name of your analyzer) add

#include "L1Trigger/GlobalTriggerAnalyzer/interface/L1GtUtils.h"

class L1GtAnalyzer: public edm::EDAnalyzer {

private:

    L1GtUtils m_l1GtUtils;

}

In the class implementation (e.g. L1GtAnalyzer.cc)

 
 void L1GtAnalyzer::analyzeL1GtUtilsMenuLite(const edm::Event& iEvent,
        const edm::EventSetup& evSetup) {

    // before accessing any result from L1GtUtils, one must retrieve and cache
    // the L1GtTriggerMenuLite product
    // add this call in the analyze / produce / filter method of your
    // analyzer / producer / filter

    m_l1GtUtils.retrieveL1GtTriggerMenuLite(iEvent, m_l1GtTmLInputTag);

    // ......
    
    
    // access L1 trigger results using public methods from L1GtUtils
    // always check on error code returned by that method

    int iErrorCode = -1;

    bool decisionBeforeMaskAlgTechTrig = m_l1GtUtils.decisionBeforeMask(iEvent,
            m_nameAlgTechTrig, iErrorCode);

    if (iErrorCode == 0) {
 
      // do something

    } else if (iErrorCode == 1) {
        
      // algorithm / technical trigger  does not exist in the L1 menu
      // do something

    } else {

      // error - see error code
      // do whatever needed

    }

    // ......

}
 
void L1GtAnalyzer::analyzeL1GtUtilsEventSetup(const edm::Event& iEvent,
        const edm::EventSetup& evSetup) {

    // before accessing any result from L1GtUtils, one must retrieve and cache
    // the L1 trigger event setup
    // add this call in the analyze / produce / filter method of your
    // analyzer / producer / filter

    m_l1GtUtils.retrieveL1EventSetup(evSetup);

    // access L1 trigger results using public methods from L1GtUtils
    // always check on error code returned by that method

   // see method analyzeL1GtUtilsMenuLite, code within
   // ......
   // ......
   

}

void L1GtAnalyzer::analyzeL1GtUtils(const edm::Event& iEvent,
        const edm::EventSetup& evSetup) {

    // before accessing any result from L1GtUtils, one must retrieve and cache
    // the L1 trigger event setup and the L1GtTriggerMenuLite product
    // add this call in the analyze / produce / filter method of your
    // analyzer / producer / filter

    m_l1GtUtils.retrieveL1EventSetup(evSetup);
    m_l1GtUtils.retrieveL1GtTriggerMenuLite(iEvent, m_l1GtTmLInputTag);

    // access L1 trigger results using public methods from L1GtUtils
    // always check on error code returned by that method

   // see method analyzeL1GtUtilsMenuLite, code within
   // ......
   // ......

}


// analyze each event: event loop
void L1GtAnalyzer::analyze(const edm::Event& iEvent, const edm::EventSetup& evSetup)
{
    
    // analyze: decision for a given algorithm using L1GtUtils functions
    // use only one of the following methods

    // Use case           0 - Retrieve L1 trigger configuration from L1GtTriggerMenuLite only
    // Use case 100000 - Fall through: try first L1GtTriggerMenuLite; if not valid,try event setup.
    // Use case 200000 - Retrieve L1 trigger configuration from event setup only.


    switch (m_l1GtUtilsConfiguration) {
        case 0: {
            analyzeL1GtUtilsMenuLite(iEvent, evSetup);

        }
            break;
        case 100000: {
            analyzeL1GtUtils(iEvent, evSetup);

        }
            break;
        case 200000: {
            analyzeL1GtUtilsEventSetup(iEvent, evSetup);

        }
            break;
        default: {
            // do nothing
        }
            break;
    }

}

The buildfile must include the GlobalTriggerAnalyzer library

<use name=L1Trigger/GlobalTriggerAnalyzer>

m_l1GtUtilsConfiguration is a private member of the analyzer, read from the configuration file, see the L1GtAnalyzer example.

Version 1

Version 1 retrieves the required L1 trigger configuration from event setup only. After retrieval, it caches it.

Usage of Version 1 of L1GtUtils class in an EDM analyzer, filter or producer

In the private part of the analyzer class header (e.g. L1GtAnalyzer.h - replace it with the name of your analyzer) add

#include "L1Trigger/GlobalTriggerAnalyzer/interface/L1GtUtils.h"

class L1GtAnalyzer: public edm::EDAnalyzer {

private:

    L1GtUtils m_l1GtUtils;

}

In the class implementation (e.g. L1GtAnalyzer.cc)

 
void L1GtAnalyzer::analyzeL1GtUtils(const edm::Event& iEvent,
        const edm::EventSetup& evSetup) {

    // before accessing any result from L1GtUtils, one must retrieve and cache
    // the L1 trigger event setup
    // add this call in the analyze / produce / filter method of your
    // analyzer / producer / filter

    m_l1GtUtils.retrieveL1EventSetup(evSetup);

    // access L1 trigger results using public methods from L1GtUtils
    // always check on error code returned by that method

    int iErrorCode = -1;

    bool decisionBeforeMaskAlgTechTrig = m_l1GtUtils.decisionBeforeMask(iEvent,
            m_nameAlgTechTrig, iErrorCode);

    if (iErrorCode == 0) {
 
      // do something

    } else if (iErrorCode == 1) {
        
      // algorithm / technical trigger  does not exist in the L1 menu
      // do something

    } else {

      // error - see error code
      // do whatever needed

    }

}


// analyze each event: event loop
void L1GtAnalyzer::analyze(const edm::Event& iEvent, const edm::EventSetup& evSetup)
{
    
    // analyze: decision for a given algorithm using L1GtUtils functions
    analyzeL1GtUtils(iEvent, evSetup);

}

The buildfile must include the GlobalTriggerAnalyzer library

<use name=L1Trigger/GlobalTriggerAnalyzer>

Methods available in L1GtUtils

This section gives the methods available in both versions of the class (Version 1 and Version 2). Methods available only in Version 2 and methods deprecated in Version 2 are clearly marked.

Deprecated methods will be removed in some future version, please replace in your code them with the newer equivalent methods.

For the functions decisionBeforeMask, decisionAfterMask, decision prescaleFactor, trigger mask, the following input parameters are to be given

• pointer to event const edm::Event& iEvent
• input tag for the L1GlobalTriggerRecord product (only if user wants to control the input tag) const edm::InputTag& l1GtRecordInputTag
• input tag for the L1GlobalTriggerReadoutRecord product (only if user wants to control the input tag) const edm::InputTag& l1GtReadoutRecordInputTag
• algorithm trigger (name or alias) or technical trigger name const std::string& nameAlgTechTrig

• error code, by reference int& errorCode
• return: the corresponding quantity

If input tags are not given as arguments, they are found for the appropriate EDM products from provenance.

Users are encouraged to use methods with the automatic retrieval of input tags (methods without input tags as input), if there are no reasons to select an EDM record with a given input tag.

Decision before trigger mask for a given algorithm or technical trigger

    ///   return decision before trigger mask for a given algorithm or technical trigger
    const bool decisionBeforeMask(const edm::Event& iEvent,
            const edm::InputTag& l1GtRecordInputTag,
            const edm::InputTag& l1GtReadoutRecordInputTag,
            const std::string& nameAlgoTechTrig, int& errorCode) const;

    const bool decisionBeforeMask(const edm::Event& iEvent,
            const std::string& nameAlgoTechTrig, int& errorCode) const;

Decision after trigger mask for a given algorithm or technical trigger

    ///   return decision after trigger mask for a given algorithm or technical trigger
    const bool decisionAfterMask(const edm::Event& iEvent,
            const edm::InputTag& l1GtRecordInputTag,
            const edm::InputTag& l1GtReadoutRecordInputTag,
            const std::string& nameAlgoTechTrig, int& errorCode) const;

    const bool decisionAfterMask(const edm::Event& iEvent,
            const std::string& nameAlgoTechTrig, int& errorCode) const;


    ///   return decision after trigger mask for a given algorithm or technical trigger
    ///          function identical with decisionAfterMask
    const bool decision(const edm::Event& iEvent,
            const edm::InputTag& l1GtRecordInputTag,
            const edm::InputTag& l1GtReadoutRecordInputTag,
            const std::string& nameAlgoTechTrig, int& errorCode) const;

    const bool decision(const edm::Event& iEvent,
            const std::string& nameAlgoTechTrig, int& errorCode) const;

Prescale factor for a given algorithm or technical trigger

    ///   return prescale factor for a given algorithm or technical trigger
    const int prescaleFactor(const edm::Event& iEvent,
            const edm::InputTag& l1GtRecordInputTag,
            const edm::InputTag& l1GtReadoutRecordInputTag,
            const std::string& nameAlgoTechTrig, int& errorCode) const;

    const int prescaleFactor(const edm::Event& iEvent,
            const std::string& nameAlgoTechTrig, int& errorCode) const;

Trigger mask for a given algorithm or technical trigger

    ///   return trigger mask for a given algorithm or technical trigger
    const int triggerMask(const edm::Event& iEvent,
            const edm::InputTag& l1GtRecordInputTag,
            const edm::InputTag& l1GtReadoutRecordInputTag,
            const std::string& nameAlgoTechTrig, int& errorCode) const;

    const int triggerMask(const edm::Event& iEvent,
            const std::string& nameAlgoTechTrig, int& errorCode) const;

    ///     faster than previous two methods - one needs in fact for the
    ///     masks the event setup only
    const int triggerMask(const std::string& nameAlgoTechTrig, int& errorCode) const;

Prescale factor set index for algorithm triggers and technical triggers

    /// return the index of the actual set of prescale factors used for the
    /// event (must be the same for all events in the luminosity block,
    /// if no errors)
    ///

    /// enum TriggerCategory {
    ///     AlgorithmTrigger = 0,
    ///     TechnicalTrigger = 1
    /// };

    const int prescaleFactorSetIndex(const edm::Event& iEvent,
            const edm::InputTag& l1GtRecordInputTag,
            const edm::InputTag& l1GtReadoutRecordInputTag,
            const TriggerCategory& trigCategory, int& errorCode) const;

    const int prescaleFactorSetIndex(const edm::Event& iEvent,
            const TriggerCategory& trigCategory, int& errorCode) const;

    ///     deprecated versions in Version 2 of L1GtUtils

   /// triggerAlgTechTrig = "TechnicalTriggers" - index for technical triggers
   /// triggerAlgTechTrig = "PhysicsAlgorithms" - index for algorithm triggers

    const int prescaleFactorSetIndex(const edm::Event& iEvent,
            const edm::InputTag& l1GtRecordInputTag,
            const edm::InputTag& l1GtReadoutRecordInputTag,
            const std::string& triggerAlgoTechTrig, int& errorCode) const;

    const int prescaleFactorSetIndex(const edm::Event& iEvent,
            const std::string& triggerAlgoTechTrig, int& errorCode) const;

Prescale factor set for algorithm triggers and technical triggers

    /// return the actual set of prescale factors used for the
    /// event (must be the same for all events in the luminosity block,
    /// if no errors)

    const std::vector<int>& prescaleFactorSet(const edm::Event& iEvent,
            const edm::InputTag& l1GtRecordInputTag,
            const edm::InputTag& l1GtReadoutRecordInputTag,
            const TriggerCategory& trigCategory, int& errorCode);

    const std::vector<int>& prescaleFactorSet(const edm::Event& iEvent,
            const TriggerCategory& trigCategory, int& errorCode);

    ///     deprecated versions in Version 2 of L1GtUtils

   /// triggerAlgTechTrig = "TechnicalTriggers" - set for technical triggers
   /// triggerAlgTechTrig = "PhysicsAlgorithms" - set for algorithm triggers

    const std::vector<int>& prescaleFactorSet(const edm::Event& iEvent,
            const edm::InputTag& l1GtRecordInputTag,
            const edm::InputTag& l1GtReadoutRecordInputTag,
            const std::string& triggerAlgoTechTrig, int& errorCode);

    const std::vector<int>& prescaleFactorSet(const edm::Event& iEvent,
            const std::string& triggerAlgoTechTrig, int& errorCode);

Trigger mask set for algorithm triggers and technical triggers

    /// return the set of trigger masks for the physics partition (partition zero)
    /// used for the event (remain the same in the whole run, if no errors)

    const std::vector<unsigned int>& triggerMaskSet(
            const TriggerCategory& trigCategory, int& errorCode);


    ///     deprecated version in Version 2 of L1GtUtils

   /// triggerAlgTechTrig = "TechnicalTriggers" - set for technical triggers
   /// triggerAlgTechTrig = "PhysicsAlgorithms" - set for algorithm triggers

    const std::vector<unsigned int>& triggerMaskSet(
            const std::string& triggerAlgoTechTrig, int& errorCode);

Name of the trigger menu used for the data set

    /// return the L1 trigger menu name
    const std::string& l1TriggerMenu() const;

    /// return the L1 trigger menu implementation
    const std::string& l1TriggerMenuImplementation() const;

Pointer to the L1 trigger menu from event setup (starting with Version 2 only)

    /// return a pointer to the L1 trigger menu from event setup
    const L1GtTriggerMenu* ptrL1TriggerMenuEventSetup(int& errorCode);

Pointer to the L1GtTriggerMenuLite product (starting with Version 2 only)

    /// return a pointer to the L1GtTriggerMenuLite product
    const L1GtTriggerMenuLite* ptrL1GtTriggerMenuLite(int& errorCode);

Check if L1 trigger configuration is available (starting with Version 2 only)

Return "true" if a valid L1 trigger configuration was found. See Introduction for errorCode and l1ConfCode signification.

    /// check if L1 trigger configuration is available
    /// return false and an error code if configuration is not available
    const bool availableL1Configuration(int& errorCode, int& l1ConfCode) const;

Error code interpretation

The methods in L1GtUtils are designed to not fail under any circumstances, therefore no exceptions are thrown anywhere. Instead, each method returns an error code. The user must check the error code before using the results of a method.

The error code cumulates the "L1 configuration code" resulted from checking the availability of the requested L1 trigger configuration with errors specific to each method.

Development history

Only major changes are listed here. For detailed changes, please look in the Tag Collector and in CVS repository.

Version 2

Version 2 contains reading L1 trigger configuration from event setup and L1GtTriggerMenuLite. It started with tag

V01-04-00       L1Trigger/GlobalTriggerAnalyzer

N/A      L1Trigger/GlobalTriggerAnalyzer

• CMSSW_3_7_0_pre5
• N/A: TO BE ADDED for 3_6_X
• N/A: TO BE ADDED for 3_5_X

Version 1

Version 1 contains only reading the L1 trigger configuration from event setup. It started with tag

V01-00-01      L1Trigger/GlobalTriggerAnalyzer

V01-03-03      L1Trigger/GlobalTriggerAnalyzer

The tags are included in the following releases:

• CMSSW_3_4_2
• CMSSW_3_5_0 - CMSSW_3_5_8
• CMSSW_3_6_0 - CMSSW_3_6_1
• CMSSW_3_7_0_pre0 - CMSSW_3_7_0_pre4

Note: for releases from the cycle CMSSW_3_5_X (up to and including CMSSW_3_5_2), please check out the following two tags fixing a bug in the framework and a bug in L1GtAnalyzer plugin declaration. The bugs do not manifest in 3_4_X and are corrected starting with CMSSW_3_5_3.

V07-15-09       FWCore/Framework                                 
V01-00-01-00   L1Trigger/GlobalTriggerAnalyzer                  

Review status

Responsible: VasileGhete