Introduction
Similar to the HLT Menus, there are multiple Level-1 Menus available to use in ATLAS, each suited for a specific use-case.
Each L1 Menu requires the harmonic configuration of all the L1 trigger hardware. During late Run 3, this includes the eFEX, jFEX, and gFEX boards that process signals from the calorimeters (for all L1 electron-photon, tau, jet, MET, and total-energy triggers), as well as the Muon sector logic, MUCTPI (Muon-CTP interface), L1Topo, and CTP (Central Trigger Processor) boards and infrastructure. Therefore, any non-trivial change to the L1 triggers has to be vetted and validated by the corresponding system expert.
Usually, changes to the L1 algorithm parameter values are transparent, and only require uploading the new Menu configuration to the system databases. This is done by the on-call Trigger Menu and CTP expert. However, any change to the algorithm themselves, including adding or removing parameters, requires not only an update to the L1 hardware FPGA firmwares, but also to the software infrastructure used in Point 1.
Even if the changes are only meant for offline development using the simulations within Athena, be careful and check with the corresponding experts, since some changes to the L1 Menu json configuration files could cause issues in P1!
The complete L1 menu configuration, including all the algorithm parameters, is stored in the L1Menu_... json file, produced by Athena after running the Trigger configuration step.
Individual L1 trigger construction
Adding a new L1 trigger requires multiple changes. The list of L1 items included in each L1 Menu is included in the corresponding L1 Menu file (e.g. Menu_Physics_pp_run3_v1.py). However, unlike for HLT trigger items, only the name of the trigger is written on that file.
Each L1 trigger requires a corresponding item definition in ItemDef.py, using MenuItem objects. You can think of MenuItem objects to be roughly equivalent to the HLT ChainProp object that contain the full definition of the HLT trigger chain, previously described here.
Most L1 triggers only require a certain number of RoIs with given characteristics (thresholds) to be found. These triggers are usually referred as multiplicity-only L1 triggers. For example, the L1_eEM9 trigger requires a single electromagnetic RoI (corresponding to an electron or photon candidate) with an energy of at least 7 GeV. The L1_2eEM9 trigger requires at least 2 of such RoIs.
All available thresholds that can be used are defined in ThreholdDef.py. Keep in mind that each new threshold will take physical space on the FPGAs, so hardware limitations and available space on the corresponding subsystems must be taken into account when developing new L1 triggers. For most items (eEM, jJ, cTAU, etc…), a small number of spare items have been considered in the initial design, for fast iteration of new triggers without requiring additional changes in the firmware.
Multiple thresholds can be combined on a single trigger. For example, for the di-tau + jets L1_cTAU30M_2cTAU20M_4jJ30p0ETA25 L1 trigger, the following MenuItem definition is required:
MenuItem('L1_cTAU30M_2cTAU20M_4jJ30p0ETA25').setLogic(d.cTAU30M & d.cTAU20M.x(2) & d.jJ300ETA25.x(4) & physcond).setTriggerType(TT.calo)
This definition requires at least 1 cTAU30M combined-tau RoI, at least 2 cTAU20M combined-tau RoIs (one of which is expected to overlap with the cTAU30M RoI, therefore requiring two tau candidates), and 4 jJ300ETA25 jet RoIs. The physcond flag sets the correct bunch-group configuration for the L1 trigger to be applied by the CTP, in this case requiring two crossing bunches (paired bunches in both beams).
In the case of L1 triggers using L1Topo algorithm, like L1_cTAU30M_2cTAU20M_DR-eTAU30eTAU20-jJ55 which requires an angular separation between two tau RoIs and a jet RoI, the corresponding L1Topo algorithm instance needs to be added as an additional threshold:
MenuItem('L1_cTAU30M_2cTAU20M_DR-eTAU30eTAU20-jJ55').setLogic( d.cTAU30M & d.cTAU20M.x(2) & d.TOPO_2DISAMB_jJ55ab_0DR28_eTAU30ab_eTAU20ab & physcond)
All the L1Topo algorithm instances are defined in TopoAlgoDef.py.
Bunch group configurations:
All L1 triggers must contain a matching bunch group setting, corresponding to the bunch configurations of the beams. By default, if the L1 trigger doesn’t indicate a specific beam condition, the paired or filled bunch configuration is used (physcond), requiring 1 bunch on each beam, on the same position, thus making collisions possible. In rare cases, the FILLED suffix is used (e.g. in the random trigger L1_RD0_FILLED).
For calibration, luminosity, and background evaluation purposes, other bunch configurations are available, indicated by the following suffixes:
EMPTY(cosmiccond): No bunches on either beam.FIRSTEMPTY(firstempty): The first empty bunch in a group of empty bunchesUNPAIRED_ISO(unpaired_isocond): One bunch on either beam, isolatedUNPAIRED_NONISO(unpaired_nonisocond): One bunch on either beam, not isolatedCALIB(calibcond): For calibration triggers, at the end of each orbit.FIRSTINTRAIN(firstintrain): The first filled paired bunch on a train of bunches.FIRSTINTRAIN(firstintrain): The first filled paired bunch on a train of bunches.
For other specific bunch group configurations provided by the LHC, the BGRPn suffixes are used, pairing the trigger with a bunch in the nth bunch group.
Algorithm configurations
L1Calo items configuration
In most L1Calo-based trigger thresholds, the number corresponds to the 50%efficiency point in the turn-on curve. The complete list of energy cuts for each threshold is available in L1CaloThresholdMapping.py. For example, for the jJ55 jet threshold, a minimum of 41 GeV is required on each RoI. Items with a L, M or T letter suffix contain an additional isolation requirement.
The parameters that configure the FEX algorithms are, in almost all cases, set in TypeWideThresholdConfig.py. Some signatures use additional configuration files, all available in the L1/Config directory of the TriggerMenuMT package.
The Athena simulation code for the eFEX, jFEX and gFEX systems is available here.
L1Topo items configuration
The configuration for all L1Topo algorithm instances is handled in TopoAlgoDef.py.
Adding or removing any L1Topo algorithm instances requires synthesis and validation of the FPGA firmware, which can take a long time! The same applies for adding any additional parameters to the algorithms. As such, an additional consistency validation is performed, validating that all the parameters included in the configuration are also listed in TopoAlgoDef.py.
To understand the inner workings of all the algorithms, you can study the simulation code in Athena, available in the L1TopoAlgorithms package. But always be mindful of unintended bugs and differences in the implementation!
L1 to HLT Menu mappings
Each HLT Menu must be associated with an L1 Menu, containing all L1 triggers used by the triggers in the HLT Menu. Similar to the HLT Menus, there are multiple L1 Menus available for different purposes, in the L1/Menu directory. The most important ones are:
Menu_Physics_pp_run3_v1.py: used for normal proton-proton collisions and cosmics data-taking.Menu_Physics_HI_run3_v1.py: used for normal heavy ion collisions, and low-pileup proton-proton collisions.Menu_MC_pp_run3_v1.py: used for processing of Monte-Carlo samples. Contains an archive of previously used triggers (e.g. the Legacy L1Calo triggers used during 2022, 2023, and the begining of 2024), and potential new triggers for development.Menu_MC_HI_run3_v1.py: analogous toMenu_MC_pp_run3_v1for heavy ion collisions.
Since different detector configurations can be used for each one of the menus, a matching inputs file is needed, specifying the physical connections from each one of the subdetectors, L1Calo and MUCTPI boards to the CTP. The Legacy L1Calo system had a dedicated input configuration file.
The mapping of an HLT Menu to an L1 Menu (and the corresponding input configuration files) is defined in MenuMapping.py.