Trigger Implementation

The following section explains the structure of the b-jet trigger software and validation framework in Athena release 22.

Table of contents

1. B-jet trigger software
   1. General structure
      1. Jet signature code
      2. InputMaker
      3. b-tagging hypo
   2. Flavour tagging
      1. Flavour tagging output
2. Validation of b-jet trigger software
   1. ART framework
   2. ART Tutorial / creating your own histograms
      1. Setup
      2. What to do next time you log in
      3. Running ART for producing histograms
         1. Customising program options
         2. Adding new histograms/variables
      4. Producing plots

B-jet trigger software

In this chapter the structure of the b-jet trigger software will be introduced. Upstream of the high-level-trigger (HLT) b-jet signature code lies core trigger software which takes care of Level1 triggering, chain execution, etc. This part will not be covered in the following chapter. For more information on this you can consult core trigger documentation, experts, or check out the code directly at GitLab.

General structure

The HLT b-jet signature code is located here athena. The diagram below shows the basic structure of the code.

Credit C. Varni

×

Jet signature code

The first step is the jet signature code. From there on we retrieve 3 collections:

• First stage fast tracks
• Vertices
• Calibrated jets

InputMaker

For every jet associated to the primary vertex in the event, the InputMaker creates a region of interest (RoI) around the jet-axis of size 0.4 times 0.4 in the eta-phi plane. For each RoI an event view is generated, containing the primary vertex and the corresponding jet and tracks. The following algorithms are executed inside the event views:

• Second stage fast tracking and precision tracking
• Flavour tagging

b-tagging hypo

The last step consist of the hypo tool. It decides on which chains the jets, and thereby the whole event, passes by cutting on the jet pT and b-tagging weights. The chains are defined here.

Flavour tagging

The b-jet trigger flavour tagging part can be found in this file and consists of these parts:

• Particle to jet association
• Secondary vertexing
• Running Run2 taggers (IP2D, IP3D, SV1, JetFitter, Mv2c10)
• Decorating collections with variables which are needed as inputs for new taggers
• Running new Run3 taggers (DL1, RNNIP, DL1r)

In general the same code as for offline flavour tagging is executed. You can find more details on the offline flavour tagging code in the software section.
This has several advantages in terms of maintenance, extension, comparability, etc. The only difference are the inputs, namely the configuration flags and collections, that are passed to the algorithms.
In a last step the algorithms from the new-style ComponentAccumulators have to be extracted and configured to old-style using the function conf2toConfigurable. Finally the sequence of flavour tagging algorithms is added to the whole b-jet trigger sequence.

Flavour tagging output

The output variables of the flavour tagging algorithms have to be added in TriggerEDM in order to be ported to the output-file. Every new collection as well as decoration has to be listed here.

Validation of b-jet trigger software

For checking differences between releases Monitoring code can be used. For large term validations the ATLAS Release Tester (ART) code is used.

ART framework

The ART code for flavour-tagging can be found here in athena. Initially it was developed to histogram offline quantities. A new class called “PhysicsTriggerVariablePlots”, which inherits from “PhysicsVariablePlots”, was added to also histogram variables at trigger level. The two classes just differ in the way the collections are retrieved from the input files. Where as for offline quantities, the collections can be accessed directly, for trigger navigation has to be used in order to retain information on which event/jet passed which chain.
The core algorithm lies in PhysicsVariablePlots and PhysicsTriggerVariablePlots for offline and trigger, respectively.
Offline-jets have to a pass a quality selection, kinematic selection and a JVT cut. Trigger-jets have to pass only a kinematic selection. Those selections are defined in FTAGValidationAlgorithm. In addition trigger jets are matched to offline jets (including a DR=0.2 cut to avoid mismatches) to gain flavour information.
The same functions are used for plotting and the histogram definitions are stored in a single json-file.

ART Tutorial / creating your own histograms

Setup

1. Checkout code

   mkdir source build run
git clone https://gitlab.cern.ch/atlas/athena.git
git fetch origin

2. Setup athena

   cd ../source
setupATLAS
asetup Athena,master,latest

   In case you want to analyse a file, which has been produced in the past, you should setup the release with which the file has been created. E.g.

   asetup 22.0.55,Athena

3. Determine packages to compile

   Create empty file called “package_filters_example.txt”
   or copy it from athena: cp ../athena/Projects/WorkDir/package_filters_example.txt .
   Add the packages you want to compile, e.g.:

   + PhysicsAnalysis/JetTagging/FlavourTaggingTests
   - .*
   

   In case you don’t want to do any code changes, just add the “- .*” line.

4. Compile

   cd ../build
cmake -DATLAS_PACKAGE_FILTER_FILE=../source/package_filters_example.txt ../athena/Projects/WorkDir/
make
source */setup.sh

5. (Optional) Syncing with the latest version of athena
   In case there is any reason for you to synchronise your code with the latest version of athena, you can follow these instruction to do so:

   cd <path-to-athena-folder>
git remote add upstream https://:@gitlab.cern.ch:8443/atlas/athena.git
git fetch upstream
git merge upstream/master -m "<message>"
   (If there are conflicts: 1. Check them: git status. 2. Solve them. 3. Commit them: git add * git commit -m "<message>")
   cd <path-to-source-folder>
setupATLAS
asetup Athena,master,latest,here
cd ../build
rm -rf *
cmake -DATLAS_PACKAGE_FILTER_FILE=../source/package_filters_example.txt ../athena/Projects/WorkDir/
make
source */setup.sh

What to do next time you log in

cd <path-to-source-folder>
setupATLAS
asetup

Running ART for producing histograms

Execute one of the scripts in test-folder for running ART code, e.g.:

python <path-to-athena-folder>/PhysicsAnalysis/JetTagging/FlavourTaggingTests/test/test_trigAna_FTAG_PhysicsVariablePlots_AOD_grid.py

In case you want to analyse a file, which has been produced in the past, just change the flags.Input.File value (and remove the step rdo2aod in test.exec_step to save time).

Customising program options

JobOptions for offline are defined here. Below you can find the list of configurable options:

JobOptions for trigger are defined here. Below you can find the list of configurable options:

Adding new histograms/variables

Variables can be added in PhysicsVariablePlots and PhysicsTriggerVariablePlots. The syntax for filling a new histogram is:

1D: ATH_CHECK( fillHistogram( "<histname>",<variable> ) );
2D: ATH_CHECK( fillHistogram( "<histname>",<variableX>, <variableY> ) );

Don’t forget the prefix “chain” in <histname> inside the function PhysicsTriggerVariablePlots::execute(). In this way chain information will be retained.

Anyhow in most cases you will want to add track variables inside PhysicsVariablePlots::computeAndStoreTrackVariables or b-tagging variables inside PhysicsVariablePlots::analyseBTaggingObject. Here you also want to add flavour information by adding “flavour” to <histname>. Then the syntax is:

ATH_CHECK( fillHistogram( chain + flavour + "<histname>",<variable> ) );
e.g. ATH_CHECK( fillHistogram( chain+flavour+"DL1r_pu",DL1r_pu ) );

“chain” and “flavour” variables are set at this point by pre executed code.

The last step missing is the definition of the histogram you want to fill. This is done in a json-file. The syntax is:

"<histname>": {
     "title": "<Histogram-title>", 
     "xtitle": "<X-axis-title>", 
     "ytitle": "<Y-axis-title>",
     "forEachTruthType": ["<flavour>",...],
     "path": {"<test>": "<path>", ...}, 
     "xbins": <Number-of-X-bins>, 
     "ybins": <Number-of-Y-bins>, 
     "xmin": <Lower-X-boundary>, 
     "xmax": <Upper-X-boundary>, 
     "ymin": <Lower-Y-boundary>,
     "ymax": <Lower-Y-boundary>,
     "type": "<hist-type>"
},

In case you have no flavour information, pass an empty array to forEachTruthType-option.
In case you define a 1D-histogram, leave out ybins, ymin, ymax-option.
Possible hist-types: “TH1I”, “TH1F”, “TH1D”, “TH2I”, “TH2F”, “TH2D”

One example:

"DL1r_pu": {
    "title": "DL1r u-probability for jets", 
    "xtitle": "DL1r pu", 
    "ytitle": "Entries",
    "forEachTruthType": ["U", "B", "C", "DATA"], 
    "path": {"PHYSVAL": "", "ART": "bTagging"}, 
    "xbins": 100, 
    "xmin": 0, 
    "xmax": 1, 
    "type": "TH1F"
},

Producing plots

Output of the ART code are ROOT-files containing histograms.\ For producing (pretty) plots you can take a look at the scripts here: https://gitlab.cern.ch/cnass/b-jet-trigger-artplotter