EDM Paths and Trigger Bits

Complete: 3


The paths in a parameter set script file together form a set of bits that can be used for event filtering. Each bit is true if the path claimed success (passed or accept) in processing the event or false if the path claimed failure (fail or reject). Each path is assigned one bit position according to the paths position in the configuration script. The first encountered path is assigned bit position zero. Endpaths do not participate in bit assignment.

The initial release of a framework scheduler that manages trigger bits is available. The purpose of this page is to describe how one can work with the trigger bit information and with the statistics kept by the framework concerning path and module event passes and failures.

The exception handling configuration affects event and trigger path processing.

Reminder of path syntax

A configuration script for cmsRun can contain any number of path and endpath statements. The syntax for each of these is identical. Later sections of this document explain the actual processing differences between the two path types.

The general form of the path (endpath) is: path name = { operand operator operand operator ... operand }


  • name is any valid name you assign to the path
  • operand is the name of a module or sequence to be run in this path

Parentheses can be used at any position and at any level of nesting to form operands.

The purpose of the operators is to allow error checking on paths. If in one path a module is declared to depend on a specific set of modules, then the module must depend on the same modules in the same order in all other paths in that process. If not the error check will fail.

There are only two valid operators

  • the "," or dependency operator, the operand to the right is dependent on the operand on the left (i.e. the right accesses data produced by the left)
  • the "&" or sequencing operator, the operand on the left is executed first, followed by the operand on the right, but they are not dependent on each other

Note that the "," operator has a higher precedence than "&". The result of each operand is a bool (accept or reject). For any given path, the overall answer is the "and" of all the operands. This means that the first operand to return false will stop further processing in this path.

Note that the boolean result of any module mentioned in a path can be reversed by adding a "!" in front of it. The boolean result of any module mentioned in a path can be ignored (always pass) by adding a "-" in front of it (first implemented in 1_3_0_pre1).

Trigger results in the event

There is an EDProduct called TriggerResults which stores the pass or fail result of each path. The Framework automatically writes an object of this type into every event. The TriggerResultInserter is the producer that places this product in the event. It is run with a fixed "module_label" of TriggerResults. The TriggerResultInserter is run after all normal paths have completed, but before any end paths have run.

The order the results are written into the TriggerResults object is the same as the order the paths appear in the configuration. The interface of the TriggerResultsallows one to

  • get out a bit pattern recording the status of each path: pass, failure, ready, or error (the last two only occur when there is some kind of problem)
  • get the index of the module in the path whose status is fail
  • get the parameter set ID of the parameter set containing the trigger names (most users should not use this, but use the utilities in the TriggerNamesService instead).

The TriggerNamesService and associated TriggerNames class have functions that allow one to

  • get the names of all the bits in the order corresponding to TriggerResults
  • get the index of a bit by trigger path name
  • get the name of a specific bit from its index
  • these functions work for the current process or if given a TriggerResults object they work for a current or previous process (as of release 1_6_0_pre1)

Prior to release 1_6_0_pre5, there were configuration parameters named "listOfTriggers" and "makeTriggerResults". These parameters are no longer used by the Framework and have no effect. Although harmless, as a matter of cleanup they should be removed from all configuration files.

Liz's notes on supporting more extensive saving of results

  • It is very difficult to exactly reproduce what the HLT does offline. In a running experiment the code used in the trigger evolves at a much slower pace then the offline due to the need for extra stability. Often after an initial commisioning period the only motivation for udpating the code is retiring of the platform (RH7.3) that the code runs on. Another major obsticle to reproducability is the undertermined state of the calibrations used in the HLT. The trigger table is a very complex application O(200) paths. Not many in the collaboration are expert enough to run it reliably with exactly the right configuration (including DB specification)
  • The HLT/online selection group should have a standard set of well designed single purpose (wehre possible) filter modules that they control and debug.
  • Because of the above it is important to save the values of the quantities that you cut on for each event. A miminal solution would save for each filter a type key and the small number of floats necesary
  • If the possible filters are known in advance it is possible to minimize and customize the history information saved for them.
  • A small percentage ( .5% at CDF ) of auto accept data is needed for both L1 and HLT triggers. These triggers should save the full HLT reconstructed event. In this way suspected BUGS in the trigger can be investigated after the fact.
  • These triggers are not a substitute for well designed backup triggers, however they are usefull in doing offline studies of optimizing trigger rates of the list as a whole.

Summary report

The framework can produce a summary report of path and module pass/fail information. The report is activated by a bool parameter in the "options" pset:

  process PROD {
     untracked PSet options = {
        untracked bool wantSummary = true  # default is false

Warning: see green note above on use of untracked in front of the options pset.

The report only include path and module summaries. The column headings for the path report include:

  • Bit: the number of the bit being reported
  • Passed: the number of events passed by this path
  • Failed: the number of events failed (rejected) by this path
  • Name: the name of this path

The column headings for the module report include:

  • Passed: how many events were passed by this module
  • Failed: how many events were failed by this module
  • Run: how many times this module was run
  • Visited: how many times this module was asked to run by paths (it only runs once per path and returns cached results the rest of the time.
  • Error: how many events caused exceptions to to occur in this module
  • Name: the module label name of this module

There is an addition event total summary that includes total events processed, total number that passed any trigger path, and total number that were failed by all trigger paths.

Output modules using trigger results

Any standard output module can be configured to select events for output depending on the value of bits in the TriggerResults.

Here is a list of examples demostrating how to do this. Assume that the following path expressions exist in the configuration script:

   path p1 = { A, B, C }
   path p2 = { D, E, F }
   path p3 = { G, H }
   path p4 = { I, J }

Warning: This document reflect rules for the latest prerelease. Is very early releases of this feature, the "SelectEvents" pset could not have "untracked" in front of it. You may need to remove "untracked" from "SelectEvents" if you are working in an older release.

If we want to save all events that pass p1, then do the following

  module outp1 = PoolOutputModule {
    untracked string fileName = "savep1.root"
    untracked PSet SelectEvents = {
      vstring SelectEvents = { "p1" }

If we want to save all events that pass p2 or p3, then do the following

  module outp23 = PoolOutputModule {
    untracked string fileName = "savep23.root"
    untracked PSet SelectEvents = {
      vstring SelectEvents = { "p2", "p3" }

If we want to save all events that pass p2 where p2 was a path in a prior process named "HLT", then do the following

  module outp23 = PoolOutputModule {
    untracked string fileName = "savep23.root"
    untracked PSet SelectEvents = {
      vstring SelectEvents = { "p2:HLT" }

If we want to save all events that pass p3 or not p4 (invert p4 decision), then do the following

  module outp3not4 = PoolOutputModule {
    untracked string fileName = "save_p3not4.root"
    untracked PSet SelectEvents = {
      vstring SelectEvents = { "p3", "!p4" }

If we want to save all events that pass any trigger, then do the following

  module outpall = PoolOutputModule {
    untracked string fileName = "save_pall.root"
    untracked PSet SelectEvents = {
      vstring SelectEvents = { "*" }

If we want to save all events that don't pass any trigger, then do the following

  module outpnotall = PoolOutputModule {
    untracked string fileName = "save_pnotall.root"
    untracked PSet SelectEvents = {
      vstring SelectEvents = { "!*" }

The vector of string named SelectEvents lists the paths that are of interest. The answer of whether or not to keep the event is an "or" of all the bits for the named paths.

Additions notes:

  1. Placing a "*" into the list is the same as listing all the triggering paths in the list.
  2. Placing a "!" in front of any name is the means that if the bit is false, then we accept the event.
  3. If the SelectEvents PSet is left out, then all events are selected for output, regardless if a TriggerResults object is in the event or not.
  4. A TriggerResults object does not need to be in the event if the output module is configured to select all events for output.
  5. If SelectEvents = { "*", "!*" }, then is equivalent to selecting all events for output (leaving out the SelectEvents section altogether)
  6. If any trigger is needed to make a selection decision, then a TriggerResults object must be present in the event
  7. Paths themselves provide the "and" operation, so selection is only based on the "or" or all the required bits.

Generic prescale module

FWCore, after CMSSW_0_5_0_pre3, provides a generic prescale filter module called Prescaler. Below is an simple example of how to configure it.

process TEST = {

        untracked PSet options = {
           untracked bool wantSummary = true

        source = EmptySource {
          untracked int32 maxEvents = 20

        # accept 1 event out of "prescaleFactor" events
        # pre1 accepts 1 in 5
        # pre2 accepts 1 in 2

        module pre1 = Prescaler { int32 prescaleFactor = 5 }
        module pre2 = Prescaler { int32 prescaleFactor = 2 }

        module print1 = AsciiOutputModule { }

        # print2 filters based on trigger bit for path "p2"
        module print2 = AsciiOutputModule {
         untracked PSet SelectEvents = { vstring SelectEvents={"p2"}}  

        # e1 sees all events, but print1 only sees events that pass pre1
        endpath e1 = { pre1, print1 }
        # print2 sees all events
        endpath e2 = { print2 }

        # trivial paths with prescale in front
        path p1 = { pre1 }
        path p2 = { pre2 }

Notes concerning path specifications

The scheduler only runs modules at most once per event. Modules are run the first time they are encountered. If a module occurs in more than one path, then a cached result is returned. If the module threw an exception, then the module will rethrow the same exception if it is encountered in a later path.

The decision of any module in any path can be reversed by adding a bang "!" to the front of the name. The reversal of the decision only applies to the current path and is strictly a property of the path instance (it is not a property of the module). Similarly, the decision of any module in any path can be ignored (always pass) by adding a "-" in front of the name (first implemented in 1_3_0_pre1).

  path a = { F, Y, Z }
  path b = { !F, U, V }

Here path 'b' proceeds if 'F' is false and path 'a' proceeds if 'F' is true.

Review Status

Reviewer/Editor and Date (copy from screen) Comments
Main.jbk - 30 Jan 2006 last added page content
JennyWilliams - 31 Jan 2007 editing to include in SWGuide

Responsible: Main.jbk
Last reviewed by: Reviewer

Edit | Attach | Watch | Print version | History: r39 | r24 < r23 < r22 < r21 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r22 - 2007-07-17 - DavidDagenhart

    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2023 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback