23. TRG#

This package contains code relevant for the Level 1 (L1) trigger.

23.1. Trigger and TSIM#

TSIM (Trigger SIMulation) is a simulation of the L1 trigger system at Belle II, which is based on several combinations of FPGA based electric circuits. TSIM simulates the firmware logic on the FPGA with C++ source code. By default, TSIM is performed event by event (“fast simulation” mode), and clock by clock behavior is not perfectly simulated (“full simulation” mode).

23.1.1. Trigger Bits#

Trigger bits are pre-defined selection criteria implemented in the trigger system. Thus only 1 (fired) or 0 (not fired) could be assigned to each trigger bit. Details of the trigger bit definitions could be found on the dedicated Confluence page or the dedicated Belle II notes.

There are three kinds of trigger bits: input trigger bits (L1Input), output trigger bits (L1FTDL), and prescaled trigger bits (L1PSNM). They are defined inside the global decision logic (GDL), as shown in Fig. 23.1. Input trigger bits are predefined selections from each sub-detector, with adjustment of the delay and width, in order to fix latency on GDL. For example, ty_0 is one of the input trigger bits meaning the number of neuro 3D tracks is one. Output bits are the outputs of GDL, combining different input trigger bits for final decision. For example, yyy is one of the output trigger bits meaning (ty_2 or ty_3) and !veto. Prescaled trigger bits are output trigger bits after prescaling and masking. Sometimes we want to keep only part of events fired a certain trigger bit, for example, we want to keep only 1% of Bhabha events. A prescale factor of 100 is then assigned to bha_3D (Bhabha selected in 3D criteria). If at least one of the prescaled output bits is fired in an event, the event is triggered.

It is recommended to use prescaled trigger bits (L1PSNM) or un-prescaled trigger bits (L1FTDL) for your analysis. The different prescales are set to the different output trigger bits in each run. In run-independent MC, configuration of the prescales in TSIM can be different from data, so L1 FTDL is recommended. In run-dependent MC, configuration of the prescales in TSIM is consistent with data, so L1PSNM is recommended.

Tip

In the analysis package we provide all the necessary variables for storing the L1Input, L1FTDL and L1PSNM information, please see trigger variables documentation. Note that it is possible to store the L1 information using the trigger bit name (e.g.: L1PSNM(yyy) recommended) or the trigger bit number (deprecated, since the trigger bit number may change across different data taking periods).

Warning

In different experiments, the trigger bits menu could be different, depending on the contents of the global tag. This global tag is available when producing the signal MC samples corresponding to a particular trigger configuration. However, some testing trigger bits might be limited in TSIM. The missing (not valid) trigger bits in TSIM could be found on this Confluence page.

../../_images/gdl.svg

Fig. 23.1 Simplified view of the L1 system and GDL logic.#

Efficiency of a certain trigger bit#

In most hadronic processes, i.e. BB-bar, the trigger efficiency is very close to 100%. Trigger bits for specific low multiplicity processes are also designed, for example, lml1, …, lml16, ecltaub2b, etc. It is recommended to check the trigger efficiencies for those trigger bits if you are working on those processes, and discuss with the experts/trigger performance group if your work needs understanding of the trigger efficiency.

With MC, trigger efficiency of a certain trigger bit (ffy for example ) can be calculated as follows:

\(\epsilon = \frac{N_\text{ffy}}{N_\text{all}}\)

where \(N_\text{all}\) is the number of all generated events, and \(N_\text{ffy}\) is the number of ffy satisfied events. This efficiency is called “true trigger efficiency”.

On the other hand, with data, we do not know the number of generated events, because only L1 passed events are recorded on data. One general way to solve this problem is to use a reference trigger bit, which is independent from the interested trigger bits. For example, to calculate the efficiency of a CDC trigger bit like ffy ((ty_2 or ty_3) and !veto), the ECL trigger bits, like hie (ehigh and !bha_veto and !veto) and c4 (clst>3 and !bha_veto and !veto), can be used as the reference:

\(\epsilon_\text{exp} = \frac{N_\text{fff} \: \text{and} \: (N_\text{hie} \: \text{or} \: N_\text{c4})}{ N_\text{hie} \: \text{or} \: N_\text{c4}}\)

It is recommended to evaluate the differences between data and MC of the trigger efficiency with this method, and apply correction and systematics to the true trigger efficiency.

Tip

Normally ECL trigger bits will be chosen as the reference to CDC trigger bits, and vice versa.

Warning

In this method with the reference bit, phase space of the signal can be affected by the reference trigger bit condition. It is important to check the kinematic dependency of the efficiency.

Tip

For details of the trigger efficiency estimation and validation, please refer to the trigger performance group.

23.2. Functions in L1trigger.py#

It’s not necessary for average users to call any of the functions listed here. Default behavior is enough for analysts.

L1trigger.add_grl_gdl_tsim(path, SimulationMode=1, FilterEvents=False, Belle2Phase='Phase3', simulateT0jitter=False, components=['GRL', 'GDL'])[source]#

Add GRL and GDL modules to the TSIM with no subdetectors. The function have to applied based on the dataobjects produced by add_subdetector_tsim.

Parameters

  • SimulationMode – The simulation mode in TSIM: 1) fast simulation, trigger algoritm simulation only, no firmware simulation; 2) full simulation, both trigger algorithm and firmware are simulated.

  • FilterEvents – if True only the events that pass the L1 trigger will survive simulation, the other are discarded. Make sure you do need to filter events before you set the value to True.

  • Belle2Phase – The trigger menu at the given Phase is applied. Available options: Phase2, Phase3.

  • simulateT0jitter – if True L1 trigger jitter is simulated by EventT0Generator.

  • components – List of logic components to be included in TSIM.

L1trigger.add_subdetector_tsim(path, SimulationMode=1, shortTracks=False, components=['CDC', 'ECL', 'KLM'])[source]#

Add subdetector modules to the TSIM with no GRL and no GDL.

Parameters

  • path – Modules are added to this path.

  • SimulationMode – The simulation mode in TSIM: 1) fast simulation, trigger algoritm simulation only, no firmware simulation; 2) full simulation, both trigger algorithm and firmware are simulated.

  • shortTracks – The standard CDC track finding requires hits in 4 axial super layers. With the shortTracks option, tracks with hits in the 3 innermost super layers are also found.

  • components – List of subdetector components to be included in TSIM.

L1trigger.add_trigger_simulation(path, SimulationMode=1, shortTracks=False, FilterEvents=False, Belle2Phase='Phase3', components=['CDC', 'ECL', 'KLM', 'GRL', 'GDL'], simulateT0jitter=False, PrintInfo=False)[source]#

Add the L1 trigger simulation (TSIM) modules to path.

Parameters

  • path – Modules are added to this path.

  • SimulationMode – The simulation mode in TSIM: 1) fast simulation, trigger algoritm simulation only, no firmware simulation; 2) full simulation, both trigger algorithm and firmware are simulated.

  • shortTracks – The standard CDC track finding requires hits in 4 axial super layers. With the shortTracks option, tracks with hits in the 3 innermost super layers are also found.

  • FilterEvents – if True only the events that pass the L1 trigger will survive simulation, the other are discarded. Make sure you do need to filter events before you set the value to True.

  • Belle2Phase – The trigger menu at the given Phase is applied. Available options: Phase2, Phase3.

  • components – List of sub-trigger components to be included in TSIM.

  • simulateT0jitter – if True L1 trigger jitter is simulated by EventT0Generator.

L1trigger.add_tsim(path, SimulationMode=1, shortTracks=False, FilterEvents=False, Belle2Phase='Phase3', components=['CDC', 'ECL', 'KLM', 'GRL', 'GDL'], PrintInfo=False)[source]#

This convenience function is DEPRECATED!

The L1 trigger simulation (TSIM) is now included in add_simulation.

If you already have a add_simulation in your path, you already get L1 trigger simulation.

If you do not have add_simulation, and you need the L1 trigger simulation, please use add_trigger_simulation().