Trigger Simulator Document

  • Introduction
An offline software to simulate the trigger decision as recorded in the online data is integrated into official STAR software. The code is located at StRoot/StTriggerUtilities. The purpose of this piece of software is
  1. Double-check the online trigger system as part of the quality assurance in users analysis. Normally in the real data taking, the status of the trigger system is monitored simultaneously and most of the issues or troubles would be detected, resolved and recorded very quickly. Though the error in the online system is seldom, the trigger simulator is useful to safe guard a very small fraction of bad events if ever happens due to faulty online trigger system from getting into analysis stream.
  2. In the online system, a set of tower status and pedestal in the barrel calorimeter is used to calculate its front end electronics (FEE) ADC. A hot tower or a wrong small pedestal would lead a large FEE output that allows to pass the trigger thresholds. Normally after the entire run ends in a year, an offline calibration would replace the tower status and pedestal, therefore the trigger simulator allows to use these updated tower status and pedestal to recalculate the trigger decision. Note this recalculation is based on the triggered events that exist already in the online stream.
  3. Most importantly it provides a way to compare the simulation with the triggered events collected in the data to study trigger bias or trigger efficiency. To maximize the statistics in the simulation, the pre-scale is not simulated. It's perfectly fine to comparing one trigger standalone. While studying multiple same type triggers with different thresholds, be mindful that there could be various pre-scales applied to those triggers. The trigger simulator can also be used to promote trigger from a lower threshold one to a higher threshold one in the data stream to avoid trigger overlapping, when both triggers are subject to pre-scales.
  4. Give users opportunities to get that intermediate steps for example jet match ADC, and tower high tower ADC that are frequently used in analysis but not in normal STAR data stream such as MuDst file.
It will achieve the best agreement between data and simulation if you use online barrel tower status and pedestal. The offline calibrated tower status and pedestal can be used in both data and simulation if necessary. The comparison could be a slightly worse quantitatively but not to any extend qualitatively different, given that in data the recalculated results are based from the already triggered sample. 
  • Structure
The input file is STAR standard MuDst file. The pre-requisite STAR makers include: StEmcRawMaker, StEmcADCtoEMaker, StEEmcUtil, StEEmcDbMaker and StEmcTriggerMaker. The simulated triggers are those solely based on barrel and endcap calorimeters. A BBC trigger simulator is developed for the 2009 analysis but is un-maintained since then. The two typical types of triggers simulated are high tower (HT) trigger and jet patch (JP) trigger. The HT trigger select events where the largest HT ADC for a tower in a trigger patch passes threshold. The JP trigger select events where the sum of the patch ADC for all the towers in a trigger patch passes threshold. Triggers are simulated in the barrel and endcap independently first, and then they are unified together to construct the whole electromagnetic tower based trigger. Several triggers from either barrel or endcap solely are passed to final output without unification. Therefore the trigger simulation has the flexibility to simulate triggers by using one or both of barrel and endcap.

Barrel calorimeter consists of 4800 towers with each tower occupying 0.05 * 0.05 in eta and phi space. A 4 * 4 square of towers is patched together called a trigger patch. The output of these trigger patches goes to the first level of the three level DSM boards numbered from 0 to 2, where the higher level board takes the input as the output of the lower level board. The last level board outputs its bits to the designated portion of a 128 bit stream in trigger control unit (TCU). The TCU bit is then used to make the trigger decision.

The trigger simulator asserts that all the 4800 tower ADCs must be present. Before calculating high tower ADC and patch ADC for a tower, the tower FEE pedestal is needed. The input format of tower pedestal is float-type and a series of calculation is need to convert it to FEE pedestal. A pedestal shift value is predetermined to decide the sign and magnitude of the FEE pedestal, which normally is chosen as 24. If tower pedestal is larger than the shift, the FEE pedestal is positive otherwise it is negative. The absolute difference from the shift is then divided by a factor of 4 and rounded to the closest integer. If the value is right in the middle of two integers, it rounds to the lower integer. If the rounded value is greater than 15, it is truncated based on the two lowest bits to 11, 12, 13 and 14.  The resulting value is taken as the pedestal value. The final FEE pedestal output is a 5 bit integer with the highest bit as the sign, where 1 represents positive and 0 represents negative, and the next four bits as the pedestal value.

Before calculating the high tower and patch ADC, the lowest 2 bits from the 12 bit tower ADC is dropped. Then based on the sign of the tower FEE pedestal, the 4 bit pedestal value is subtracted if positive or added if negative from or to the 10 bit ADC. Then to arrive to the patch sum ADC, we drop the two lowest bits from the pedestal adjusted ADC. To get the high tower ADC from the pedestal adjusted ADC, there are four different ways tagged by bit conversion number from 0 to 3. For normal operation we use bin conversion of 2. In this case, we drop the two lowest bit further and extract the next lowest 5 bits. Any overflow beyond the 5 bits would be represented by a single overflow bit. Finally the 6 bit high tower ADC consists of the overflow bit as the highest bit and followed by the 5 extracted bits.

If a tower status is bad (1 means good, other value means bad), both high tower and patch ADCs would be set to 0. If a tower status is good, but high tower status is bad (1 means good, 0 means bad), the high tower ADC would be set to 0. The same rule applies to patch ADC status (1 means good and 0 means bad).

For a given trigger patch, the largest high tower ADC from the 16 towers is taken as the trigger patch high tower ADC. To calculate the patch sum ADC, we first sum all the 16 tower patch ADCs together.  A lookup table (LUT) is used to compute the patch sum by using information such as the number of masked out towers in a trigger patch. The information stored in LUT includes ped, scale, formula, sigma and power-up. LUT ped is a pre-determined value as the patch sum pedestal. LUT scale is used as a dividing factor to patch sum minus pedestal to obtain the final output. The scale factor is normally 1. LUT formula could change the patch sum pedestal or the scale factor by selecting values from 0, 1, or 2 to account for the number of masked out towers. Formula 0 dictates the LUT output is not adjusted by the masked out towers. Formula 1 multiplies the scale factor by the fraction of remaining towers. Formula 2 reduces the pedestal by the number of masked out towers. Normally we use formula 2. The LUT power-up if set to 1, would boost the LUT pedestal up by 15. LUT sigma puts additional constraint on the final output. If patch sum minus LUT pedestal (if formula equals to 2 or power-up set to 1, the adjusted pedestal) is less than sigma, the LUT output would be set to 0. Otherwise the output is equal to the patch sum minus pedestal, which has to be bound from 0 to 62, a 6 bit integer, following a simple rule. If the value is negative, it is set to 0, and if the value goes beyond 62, it stays at 62.

If a trigger patch status is bad (1 means good and 0 means bad), both high tower and patch ADCs would be set to 0. If a trigger patch status is good, but the high tower status is bad (1 means good and 0 means bad), the high tower ADC would be set to 0. The same rule applies to patch sum status (1 means good and 0 means bad) 


Tower id is numbered from 1 to 4800. Each tower has a pair of numbers,crate number and crate sequence, to identify which trigger patch the tower belongs to. Also the 300 trigger patches are numbered from 0 to 299, and each corresponds to the aforementioned pair of crate number and crate sequence. There are 30 crates and 10 sequences in a crate.

The pedestals and status of towers and trigger patches, maps between towers and trigger patches, and the information contained in the  LUT can come from offline calibration database Calibration/bemc or user specified text files through StBemcTriggerSimu::setBemcStatus(const char*). The lines in the text file should begin with #, SoftId, TriggerPedestalShift and TriggerPatch. Lines that begin with # are comments and skipped by the code. Lines that begin with SoftId are followed by tower id, crate number, crate sequence, tower status, high tower status, patch sum status, and trigger patch number. Similarly lines followed by TriggerPedestalShift contain one single number, pedestal shift value. Those started with TriggerPatch contain trigger patch, crate number, crate sequence, high tower status, patch sum status, bit conversion number and LUT formula number. The same information can be obtained from the offline calibration database, except there is more information regarding to the LUT which includes scale, ped, sigma and power-up. The use of input text file is discouraged unless for testing purposes. The offline database is often filled regularly, so users should query offline database to retrieve all the necessary information.

The output of the trigger patch is arranged to a 12 bit ADC, with the highest 6 bits representing to the patch sum ADC and the lowest 6 bits representing the high tower ADC. The output from the 300 trigger patches is fed into 30 level-0 DSM boards, 15 for the east side and 15 for the west side. Each board has 10 input channels. The board number and input channel are arranged sequentially for every ten trigger patches from patch 0 to patch 299. The outputs of level-0 boards go to 6 level-1 boards. The level-2 board spares 6 input channels to accept output from the level-1 output. After processing all the input channels including the 2 extra channels from endcap level-1 boards, it directs its output to TCU. The details of the data flow among DSM boards can be found in the attached file. For older years, you may need to request archived files from STAR trigger group.

The registers in DSM boards also known as thresholds, are retrieved from table "triggerThreshold" in the offline database Calibrations/trg or from table "dict" in database "Conditions_rts" by using StTriggerSimuMaker::useOfflineDB() or StTriggerSimuMaker::useOnlineDB(). The methods should return the same results. To alleviate burden on the STAR database server, reading values from the offline database is strongly encouraged. Both tables contain the same information, "object", "index", "reg", "label", "value" and "defaultvalue". The "object" is the crate number where the boards sit. There are maximum number of 20 crates available, but normally we only use 17 of them for the whole STAR trigger system. Their definition can be found at header file, RTS/trg/include/trgConfNum.h. The level 0 west and east barrel DSM boards located at crate 5,  BCW_CONF_NUM, and 6, BCW_CONF_NUM, respectively. The level 1 barrel boards and level 0 endcap boards are located at crate 2, BC1_CONF_NUM. The level 2 board is located at crate 1, L1_CONF_NUM. The index is to identify the type of board within a crate. The same type of board normally shares the same register value. Both level 0 DSM boards from west and east barrel have index numbered at 16 in crate 5 and 6. Endcap level 0 board is indexed at 21, endcap level 1 board at 23, and barrel level 1 board at 33 in crate 2. The level 2 board is indexed at 20 in crate 1. The "reg" is the register number in a board. The "label" is a series of characters to describe the what the register is, for example "BEMC-JP-th0". The "value" is the value of the register, and if it is "-1", the default value denoted as the "defaultvalue" is used. There used to be a level 3 board however it is not used since 2009. The output from level 2 board is directly send to TCU.

The TCU contains two streams of 128 bits, divided into eight 32 bit integers, named onbits, offbits, onbits1, onbits2, onbits3, offbits1, offbits2 and offbits3. The 4 onbits integers construct the first 128 bit stream, and the rest 4 offbit integers construct the second 128 bit. Each 16 consecutive bits in the 128 stream correspond to an output from a level 2 DSM board. The bit map between onbits and offbits stream is exactly the same, except the offbit stream is used to reject the event if a trigger corresponding to that bit is fired. The barrel and endcap level 2 board output is located at from bit 48 to 63 (bit numbering starts from 0), in other words, the upper 16 bits in onbits1 or offbits1. Normally only first 96 bits are used in the STAR trigger system. Bit 96 is the laser protection bit. For all the electromagnetic triggers, there is no offbit requirements except for the laser protection, for which the bit 96 in the offbit stream is 1. So we only pick out the 16 bits corresponding the barrel and endcap level 2 board as our trigger definition.

Those eight 32 bit integers can be queried from table "triggerDefinition" in offline database "Calibrations/trg" or from table "pwc" in online database "Conditions_rts". In addition if you query the online database you have to get the trigger name, "name", and trigger offline id, "OfflineBit" from table "triggers". The trigger index "idx_trigger" is the key to identify triggers from the two tables. In the offline table "triggerDefinition" it contains trigger index, name, triggerId, and the eight onbit and offbit integers.

Once the simulated bits in the TCU match the selected 16 bits from the onbit stream, the trigger id is deemed to be fired. Users can request if a trigger is fired by using StTriggerSimuMaker::isTrigger(int trgId), if it returns true, it means the simulated trigger is fired, otherwise it's not fired.

Similar to the barrel, endcap electromagnetic calorimeter has 720 towers.

  • Note
The following towers have been swapped their trigger patch since 2009.
4054 <---> 4014 (TP227 <---> TP236)
4055 <---> 4015 (TP227 <---> TP236)
4056 <---> 4016 (TP227 <---> TP236)
4057 <---> 4017 (TP229 <---> TP238)


Barrel jet match numbering scheme:

The jet patches spanned over 1 unit in both eta and phi space, are numbered starting with JP 0 centered at 150 degrees looking from the West into the IR (intersection region) and increasing clockwise, i.e. JP 1 at 90 degrees, JP 2 at 30 degrees, etc. On the East side the numbering picks up at JP 6 centered again at 150 degrees and increasing clockwise (again as seen from the *West* into the IR). Thus JP 0 and JP 6 are in the same phi location in the STAR coordinate system. So are JP 1 and JP 7, etc.

Jet Patch# Eta Phi Quadrant
0 0.5 150 10'
1 0.5 90 12'
2 0.5 30 2'
3 0.5 -30 4'
4 0.5 -90 6'
5 0.5 -150 8'
6 -0.5 150 10'
7 -0.5 90 12'
8 -0.5 30 2'
9 -0.5 -30 4'
10 -0.5 -90 6'
11 -0.5 -150 8'
12 -0.1 150 10'
13 -0.1 90 12'
14 -0.1 30 2'
15 -0.1 -30 4'
16 -0.1 -90 6'
17 -0.1 -150 8'

In 2017 some DSM registers are not presented in the either the offline or the online databases. So they are manually set in function: StTriggerSimuMaker::setTriggerThresholds2017().

A tutorial to fill "triggerThreshold and triggerDefinition" in offline database can be found here.

The LUT ped in the offline databases Calibrations/bemc can be updated by comparing the simulated trigger patch ADC with that in the real data if a consistent difference is found. An study performed for the 2012 pp500 GeV data can be found here.

A test mode for the DSM algorithm can be enabled by setting mTestMode to true in both StBemcTriggerSimu and StEemcTriggerSimu, as the following lines. This mode circumvents the step where the trigger patch output is simulated from tower ADCs. It provides a direct check to the DSM algorithm. The mode should not be used in the data analysis.

simuTrig->bemc->mTestMode = true
simuTrig->eemc->mTestMode = true

Some information about the online monitoring code for the data flow among the STAR DSM boards can be found here.

The DSM boards for various years in both barrel and endcap simulators are achieved through the polymorphism in C++ class. The base class of DSM board for subsequent years is derived from the DSM board defined for the same level from the year of 2009, for example "struct DSMLayer_EM201_2017 : public DSMLayer_EM201_2009 {};".
 
A previous trigger simulator document can be found here.

  • Example
 
StRoot/StTriggerUtilities/macros/RunTriggerSimu.C
StRoot/StTriggerUtilities/macros/RunTriggerSimu2015.C

Studying multiple same type triggers with different thresholds and subject to pre-scales:

For example, in data stream, JP2 trigger with a threshold of 66 ADC counts and a pre-scale of 1, JP1 trigger with a threshold of 36 and a pre-scale of 25, and JP0 trigger with a threshold of 28 and a pre-scale of 100. In data any event that passes JP2 threshold would be recorded however the event that passes JP1 and JP0 is subject to pre-scale. However in simulation a JP2 event would satisfy the JP1 and JP0 trigger and there is no pre-scale applied to either of them. Given possible trigger mix in the data and trying to avoid double counting, an event is counted towards the highest trigger threshold. In this case JP2 is not pre-scaled, a direct comparison works fine by requiring JP2 fired in data and simulation. Since JP1 and JP0 events are after pre-scaling and not satisfying JP2, instead in simulation we use "!JP2 && JP1" as simulated JP1 sample and add (ps_JP1-1)/ps_JP1 = (25-1)/25 = 96% of "!JP2 && JP1" to "!JP1 && JP0" as simulated JP0 sample.

A similar method to promote JP0 events to JP1 events as long as the JP1 fired in the "JP0 && !JP1" data stream. These promoted events should be applied with weights ps_JP0/ps_JP1 = 100/25 = 4 in order to be added to the rest of the JP1 data stream, which is then compared with "!JP1 && JP0" in simulation. However this method could diminish the statistical power from the JP1 data stream because they are combined with events from JP0 data stream by large weight.