• MOTIVATION

This code was developed to allow users to apply the STAR trigger algorithms to both real and simulated data stored in MuDst files.  Additionally, it provides critical information about trigger decisions that are not saved in the data stream (for example the id of the tower that fired the trigger) and therefore must be reconstructed after the fact.  The independent development of filtering mechanisms for simulation production means this code will be used to implement trigger filtering in the bfc.C as well. Currently there is no structure which allows users to implement and test a new trigger.  Trigger development must be done via a cvs co and running private code.

• USER ACCESS FUNCTIONS

The users only access point to the StTriggerUtilities code is through the StTriggerSimuMaker. This maker should provide users with all the information they need about the status and working of the trigger emulator. These are the user accessible functions:

1. bool isTriggerDefined(trigID) -  user inputs trigger id and StTriggerSimuMaker tells user if their desired trigger is implemented in the code.   This function is important because the code returns TRUE by default for all triggers that are not defined.  See details after subsection 3. below.
2. bool isTrigger(trigID) -  user inputs trigger id and StTriggerSimuMaker returns true or false based on the the response from the detector components that compose the pieces of the trigger.  It is important to note that isTrigger() will return TRUE for all events when the code has not been initialized for a specific trigger ID.  See details after subsection 3. below.
3. Detailed information about which trigger tower/patches fired the trigger can be accessed through  const StTriggerSimuResult& detailedResult(int trigId) { return mResults[trigId]. Examples of how to do this are shown in the example macros.
4. Details about the the individual detector decisions that went into the isTrigger() response can be accessed by the user.  They simply need to instantiate  a pointer to the individual detector and then access the decision made by that detector.  For example if the user wanted to check if trigger 137611 condition was fullfilled:

          StTriggerSimuMaker *simuTrig = = new StTriggerSimuMaker("StarTrigSimu");    

          StBemcTriggerSimu *bemc;

          cout<<"  Trigger response for 137611 ="<<simuTrig->isTrigger(137611) <<"  Bemc response = "<<simuTrig->bemc->triggerDecision(137611)<<endl;

If the user requests a response from a detector that is not used in the trigger (for example - the eemc is not used in 137611)  then this detector will by definition always  return kDoNotCare or "2".   The detectors that are necessary to make a trigger decision should return kTrue (1) or kFalse (0).   This allows the StTriggerSimuMaker to take a simple "OR" of the return values from each detector.   If the detector is initialized for that trigger it will return "1"  or "0" - if not then it will always return "2" and therefore never falsely negate a trigger response.

•  USER SETUP FUNCTIONS

1. void useMC(int x) - the user must tell the trigger emulator if the MuDst is a data or simulation file.  Default is set for data
2. User must tell the trigger emulator which detector packages should be used in trigger decisions.  Example of how to implement are in set up macros in CVS.                                                                                                                                                                                                                        void    useEemc(int flag=0);  //0:just process ADC, 1:compare w/ trigData, see enum in Eemc class
   void    useBbc();
   void    useBemc();
   void    useEmc();
   void    useL2(StGenericL2Emulator* );
   void    useL2(StGenericL2Emulator2009* );
3. User has the option to override trigger thresholds taken from the database and used in 2009 trigger decisions. These functions could also be used to test new trigger algorithms.                                                                                                                                                                                                                                                       void setBarrelJetPatchTh(int i, int value) { mBarrelJetPatchTh[i] = value; }
   void setBarrelHighTowerTh(int i, int value) { mBarrelHighTowerTh[i] = value; }
   void setEndcapJetPatchTh(int i, int value) { mEndcapJetPatchTh[i] = value; }
   void setEndcapHighTowerTh(int i, int value) { mEndcapHighTowerTh[i] = value; }                                                                                                       void setOverlapJetPatchTh(int i, int value) { mOverlapJetPatchTh[i] = value; }
   void changeJPThresh(int value) { mChangeJPThresh = value; }

• CODE STRUCTURE

The primary flow of information is always through the StTriggerSimuMaker. It lives in the top directory and gathers/gives information from/to the detector packages in the subdirectories beneath and the user code.  Additional classes in the top directory perform the following functions:

1. StVirtualTriggerSimu - interface class for StTriggerSimuMaker. It collects individual detector trigger responses from StTriggerSimuResult, performs an AND on these responses and returns result to StTriggerSimuMaker.
2. StTriggerSimuResult - support class for StTriggerSimuMaker/StVirtualTriggerSimu. Actually interfaces with each St"Detector"Simu.cxx class and accesses trigger decision.  Also provides detailed information about tower/patch responses in trigger.
3. StTriggerSimuPlayMaker- an example of how a user could access trigger information in a maker instead of a macro

The directory structure beneath StTriggerSimuMaker is organized along two lines.  The first is detectors in the level 0 trigger:  BBC, BEMC, EEMC and then EMC which is the structure that coordinates the point at L0 where BEMC and EEMC DSM trees join together.  

1. Bbc - determines BBC adc response.   StTriggerSimuDecision accessor grabs a the yes or no response. If Bbc is not set up by user (void setBbc()) then return "2";
2. Bemc - determine Bemc response at level 0 for all triggers inserted in StBemcTriggerSimu::Init(). User has decision to configure BEMC to online or offline status. Online uses the online uploaded tower FEE pedestals, tower masks and DSM HT/TP masks.  Offline calculates the tower FEE pedestals from the offline pedestals loaded to the data and uses the offline status tables for tower masks.   StTriggerSimuDecision accesor grabs yes or no response for each trigger id.  If the trigger is not known or the Bemc is not set up by user (void setBEMC())  then response is always "2".
3. Eemc - determine Eemc response at level 0. Currently reads in FEE pedestals from text files located in /afs/rhic.bnl.gov/star/users/pibero/public/StarTrigSimuSetup/ped/
4. Emc - determines last layer of DSM response for level 0 trigger.  Combines BEMC and EEMC output from lower DSM levels. Also location of override for threshold values from database if set by user
5. StDSMUtilities - support class for Eemc and Bemc DSM algorithms.
6. StJanEventMaker - class used to write out events in a custom data format (JanEvent) which mimic the BTOW&ETOW data blocks sent to L2 from the trigger. It is useful to evaluate or develop L2 algorithms in a stand alone mode.  Possible seed class for expanding code into user access for trigger testing.
     

• PROTOCOL for IMPLEMENTING NEW DETECTORS INTO THE TRIGGER EMULATOR

The following detectors are not currently implemeted in the Trigger Emulator:

1. Vertex Position Detector
2. Time Of Flight Detector
3. Forward Meson Spectrometer
4. Forward Pion Detector
5. Zero Degree Calorimeter
6. Forward Time Projection Chamber
7. Silicon Vertex Tracker
8. Silicon Strip Detector
9. Forward Gem Tracker
10. Heavy Flavor Tracker
11. High Level Trigger (ok not a detector but still not implemented)

If you need to have one of the detectors above incorporated into StTriggerUtilities please contact Renee Fatemi and Pibero Djawotho and provide the following information:

1. Name of Detector
2. 1st year of inclusion in trigger
3. Point of contact in detector group
4. Name of person who will test implemented trigger algorithms.
5. 1 -2 paragraph summary of trigger algorithm including dependencies on other detectors
6. link to trigger documentation of DSM structure
7. A list of online runtime parameters needed from the detector in order to operate trigger (pedestals, timing offsets etc).  Please indicate where these parameters are stored currently.  These parameters must be stored in an offline database before the detector can be incorporated.
8. A list of offline parameter needed from the detector in order to emulate trigger (status tables, offline pedestals etc). Please indicate where these parameters are stored currently.  These parameters must be stored in an offline database before the detector can be incorporated.

•  DATABASE INFORMATION
  

StTriggerUtilities must access information in the database for three primary pieces of information:

1. BEMC+EEMC  Detector Parameters.  This information is lumped into two categories:  A) Parameters for the Front End Electronics (FEE) settings such as pedestals, LUT, pedestal shifts, and trigger patch and high tower 6 bit masks B) Parameters for the offline tower status.  For the BEMC these parameters are accessed via StBemcTables.   For the EEMC these parameters are loaded from local text files and need to be transferred to an offline database.
2. Level 0 Trigger Detector Parameters. 
3. Level 2 Trigger Algorithms