User Guide

A user guide for version 0.10.0 of the L1-Trigger Menu Editor (using grammar spec. 7.0).

For installation instructions and how to update see the install page.

Introduction

The Level-1 Trigger Menu Editor is a graphical tool for editing Trigger Menu XML files. It is written in Python3/PyQt5 and makes use of the utm (micro trigger menu) C++ library. The created XML menus are used for creating new trigger firmware implementations and generating new emulator code and trigger studies.

Algorithm expression language

All triggers are formulated using a special expression language.

comb{ MU20[MU-ETA_1p4], MU20[MU-ETA_1p4] }

Example algorithm expression for a 20 GeV di-muon trigger with an η-restriction.

mass_inv{ MU10, MU10 }[MASS_60to150]

Example algorithm expression for a simple invariant mass trigger of two muons.

Tip: for more information see L1-Trigger Menu Grammar Specification (PDF, outdated).

Workflow

In general new trigger menus evolve always from existing menus. As every menu is bond to a specific set of input scales (part of the XML file), there is no option to create new menus from scratch.


Command line usage

Starting from the command line

$ tm-editor

Open one or more files from the command line

$ tm-editor sample.xml

Open from remote location using HTTP, HTTPS or FTP

$ tm-editor http://www.example.org/sample.xml

Loading an XML menu

Go to FileOpen... (Ctrl+O) and select a corresponding XML menu to open.

Additionally a file can be downloaded from a remote location, like a web resource or FTP server.

Go to FileOpen URL... and enter a remote URL, then click the Open button.

Tip: when accessing XML menus using the github.com web interface, make sure to navigate to the XML file's detail page and copy the download (or raw) link (eg. right click, copy link location).

Saving an XML menu

Go to FileSave (Ctrl+S) to save the current document or use FileSave as... (Ctrl+Shift+S) to save the document under a new name.

Important: due to limitations of the XML menu format it is not possible to store cuts that are not assigned to any algorithm of the same menu. Newly created cuts that are not used will be lost at closing the document.

Editing menu information

Click on the Menu node in the navigation panel on the left. At the top you can change the name and description of the current menu. At the bottom a list of all menu parameters is showed.


Figure: Algorithm editor window, editing menu information.


Managing algorithms (seeds)

Click on the Algorithms/Seeds node in the navigation panel on the left. A list of exisiting algorithms is displayed at the top. If you click on an alogithm in the list, details of the selected algorithm are shown at the bottom.


Figure: Algorithm editor window, listing algorithms.


Creating/Editing algorithms (seeds)

To create a new algorithm from scratch, click on Add to open the algoithm editor dialog. To edit an existing algorithm select an item in the table view and click Edit... or simply double click on an item in the table view.

Tip: for more information see L1-Trigger Menu Grammar Specification (PDF, outdated).


Figure: Algorithm editor dialog, version 0.5.0.

  1. Text editor for algorithm expression...
    • right click on functions to edit with function editor.
    • right click on objects to edit with object editor.
    • right click on external signals to edit with external signal editor.
  2. Set algorithm name.
  3. Set algorithm index.
  4. Use graphical map to select a free index position (alternative to 3.)
  5. Preview of the used object requirements, cuts and external signals assigned in the current expression on the left.
  6. Optional comments for the algorithm.
  7. Edit object requirements , external signals or functions at cursor position using dialogs.
  8. Insert object requirements , external signals and functions using dialogs.
  9. Format expression (expand or collapse ). Useful for complex expressions.
Tip: use FormatExpand to format complex expressions in a more readable way.

Table of available objects

Muons Calorimeter Energy sums Min bias HF Towercounts
MU EG ETM MBT0HFP TOWERCOUNT
TAU HTM MBT1HFP
JET ETT MBT0HFM
HTT MBT1HFM
ETTEM
ETMHF


Function Editor

For convenient creation and editing of functions (object combinations, correlations and invariant mass) the function editor can be used.

  • Insert a new function at cursor position by Insert → Insert Function... or by clicking the Insert Function icon in the algorithm editor toolbar.
  • Edit an existing function at cursor position by Edit → Edit Function... or by right clicking on the textual expression and selecting Edit Function...


Figure: Function editor dialog, editing a di-muon expression and applying a charge correlation restriction.

Tip: use Add.. to quickly create new function cuts.

Object Requirement Editor

For convenient creation and editing of object requirements the object requirement editor can be used.

  • Insert a new object requirement at cursor position by Insert → Insert Object... or by clicking the Insert Object icon in the algorithm editor toolbar.
  • Edit an exisitng object requirement at cursor position by Edit → Edit Object... or by right clicking on the textual expression and selecting Edit Object...


Figure: Object requirement editor dialog, editing a muon expression with assigned BX-offset and quality cut.

Tip: use Add.. to quickly create new object requirement cuts.

External Signal Editor

For convenient creation and editing of external signals the external signal requirement editor can be used.

  • Insert a new external signal requirement at cursor position by Insert → Insert External Signal... or by clicking the Insert External Signal icon in the algorithm editor toolbar.
  • Edit an exisitng external signal requirement at cursor position by Edit → Edit External Signal... or by right clicking on the textual expression and selecting Edit External Signal...


Figure: Exernal signal requirement editor dialog, editing a BPTX external signal with assigned BX-offset of 0.


Import algorithms (seeds)

Import algorithms (seeds) from another XML menu using File → Import... or by clicking the Import from exisiting file icon in the main toolbar.

Note: you have to open an existing menu to be able to import algorithms (seeds) from another one.
Note: when importing algorithms with indices that are already occupied they will be moved to the next free index available.


Figure: Import algorithms (seeds) dialog.

Important: when importing from a menu with different scales set you will receive an incompatibility warning. However you can continue to import potential compatible algorithms on your own risk.

Managing cuts

Click on the Cuts node in the navigation panel on the left. A list of exisiting cuts is displayed at the top. If you click on a cut in the list, details of the selected cut are shown at the bottom.


Figure: Application window showing list of defined cuts.


Creating/Editing cuts

To create a new cut from scratch, click on Add to raise the cut editor dialog.


Figure: Cut editor dialog, creating an invariant mass restriction cut.

Select the cut type and name suffix and enter either a range or a data selection, depending on the type of cut.