DESCRIPTION OF BASIC ROUTINES FOR LEVEL 1 CALORIMETER TRIGGER LOOKUP SYSTEM MANAGER LIBRARY file TRGMISC:CALTRG_LOOKUP_TABLE_ROUTINES.TXT First draft : 8-FEB-1990 21-FEB-1990 26-FEB-1990 1-AUG-1990 17-AUG-1990 -------------------------------------------------------------------------- The following describes the user-accessable routines and arrays available from the Lookup System Manager Library. These are used to do the following: o Load internal arrays with information from a Lookup System Manager File. o Directly access information loaded from the LSM File. o Perform simulation of several operations of the hardware based on the description loaded from the LSM File. The routine INIT_LOOKUP_ROUTINES must be called prior to calling any other routine or accessing any variable from this library. This document also describes the parameters declared in the file `LEVEL1_LOOKUP.PARAMS'. These parameters are used to define array dimensions and to select different operations from a single subroutine. For further description of the Lookup System Manager File or the data contained in it, refer to the documentation of the Lookup System Manager Program. -------------------------------------------------------------------------- INIT_LOOKUP_ROUTINES -------------------- SUBROUTINE INIT_LOOKUP_ROUTINES ( IO_UNIT, FILE_NAME, STATUS ) INTEGER IO_UNIT CHARACTER*(*) FILE_NAME INTEGER STATUS Purpose and Methods : Initialize the common block for subsequent direct access or use of library routines. This subroutine opens the Lookup Management File, initializes the common block from the file, and then closes the file. Inputs : IO_UNIT Is the logical unit number to use for input file. FILE_NAME Is the name of the Lookup System Management file to use as input in filling the common block. Outputs : STATUS Is the initialization status. The normally returned success status is 1. In case of file open or read failure, the FORTRAN IO error code is returned (positive number). Negative numbers are reserved for file syntax interpretation error codes. If more information on the error is desired, load the LSM File with the LSM Program. This will allow the user to view the text of all the error messages produced by loading the LSM File. filled common block : LEVEL1_LOOKUP. Controls: None Comments : A call to INIT_LOOKUP_ROUTINES must be made before any routine can be called, or any varible accessed. The file name is passed as argument to allow selection of a CURRENT hardware description file or any other EXPLORATORY configuration, or retrieval from ARCHIVES. The routine will fill with zeros all variables referencing trigger towers whose description does not appear in the lookup tables. The existence test is made on the downloaded DAC byte that by definition is non-zero only for existing Trigger Towers. Defined 21-FEB-1990 MICHIGAN STATE UNIVERSITY, TRIGGER CONTROL SOFTWARE Created 6-JUN-1990 MICHIGAN STATE UNIVERSITY, TRIGGER CONTROL SOFTWARE Updated 17-AUG-1990 MICHIGAN STATE UNIVERSITY, TRIGGER CONTROL SOFTWARE -------------------------------------------------------------------------- ADC_CONVERSIONS --------------- SUBROUTINE ADC_CONVERSIONS (TRIGGER_TOWER_ENERGY, ADC_BYTE) INCLUDE 'D0$LEVEL1:LEVEL1_LOOKUP.PARAMS' REAL TRIGGER_TOWER_ENERGY ( POS_ETA:NEG_ETA, & ETA_MIN:ETA_MAX, & PHI_MIN:PHI_MAX, & EM_TOWER:HD_TOWER ) INTEGER ADC_BYTE ( POS_ETA:NEG_ETA, & ETA_MIN:ETA_MAX, & PHI_MIN:PHI_MAX, & EM_TOWER:HD_TOWER ) Purpose and Methods : Simulates the analog to digital conversions performed by the Calorimeter Trigger for the specified set of energy deposits over the whole detector. Inputs : TRIGGER_TOWER_ENERGY is the energy deposited in each Electro-Magnetic and each Hadronic Trigger Tower. This is a FORTRAN array variable See the parameter file for translation of dimensions Units : GeV Outputs : ADC_BYTE is the set of simulated ADC output bytes for the specified set of input energy deposit TT_ENERGY. This is a FORTRAN array variable See the parameter file for translation of dimensions Controls: None Comments : A call to INIT_LOOKUP_ROUTINES must have been made before this routine can be called. The routine will fill with zeros all towers whose description does not appear in the lookup tables. The existence test is made on the downloaded DAC byte that by definition is non-zero only for existing Trigger Towers. This simulation does not take the electronics noise into consideration. This simulation does not take the Analog to Digital Conversion Linearity Errors into consideration. This simulation will take into account the analog scaling of the signal coming from the BLS card at the input of the CTFE cards. This scaling typically transforms the raw energy deposit into its transverse component assuming the interaction vertex was at the center of the detector. There might be some sub-range of the detector where the energy is only scaled to a multiple of this z-uncorrected transverse component. This simulation will take into account any output offset performed by the ADC. This simulation can also reproduce the action of the biases due to improper amplitude or timing of the trigger pickoff signals. Defined 29-JAN-1990 MICHIGAN STATE UNIVERSTITY, TRIGGER CONTROL SOFTWARE Updated 2-AUG-1990 MICHIGAN STATE UNIVERSTITY, TRIGGER CONTROL SOFTWARE -------------------------------------------------------------------------- PROM_RESPONSES -------------- SUBROUTINE PROM_RESPONSES ( SIGN_ETA, MAGN_ETA, PHI, & L0_BIN, & EM_ADC_BYTE, HD_ADC_BYTE, & LUQ_BYTE ) INCLUDE 'D0$LEVEL1:LEVEL1_LOOKUP.PARAMS' INTEGER SIGN_ETA, MAGN_ETA, PHI INTEGER L0_BIN INTEGER EM_ADC_BYTE, HD_ADC_BYTE INTEGER LUQ_BYTE ( EM_ET_QUANT:PY_QUANT ) Purpose and Methods : Reconstruct the set of prom responses for the specified set of ADC bytes, and the specified Level 0 Trigger information. Inputs : SIGN_ETA is the sign of the eta index of the trigger tower for which the PROM response is reconstructed. Use 0 to specify a negative eta index, 1 to specify a positive eta index. It is recommended to use one of the compilation constants defined along with the common block. POS_ETA=0 or NEG_ETA=1. MAGN_ETA is the magnitutde of the eta index of the trigger tower for which the PROM response is reconstructed. Range : 1 to 24 PHI is the phi index of the trigger tower for which the PROM response is reconstructed. Range : 1 to 32 EM_ADC_BYTE is the ADC output byte (simulated or from First Level Trigger Data Block information) of the ELectro-Magnetic Trigger Tower for which the PROM response is reconstructed. HD_ADC_BYTE is the ADC output byte (simulated or from First Level Trigger Data Block information) of the Hadronic Trigger Tower for which the PROM response is reconstructed. Outputs : LUQ_BYTE is the expected set of PROM ouptuts for all of the constructed quantities. The PROMs will correct the first estimate of the EM, HD or TOT=EM+HD transverse energy using the information about the position of the interaction vertex made available by the Level 0 Trigger. See the parameter file for the ordering of the elements in this one dimension array. It is highly recommended to always access an element by the parameter pointing to its rank, not by the parameter value. Comments : A call to INIT_LOOKUP_ROUTINES must have been made before this routine can be called. No verification is made of the integrity of the arguments specifying the indices of the Trigger Tower or the Level 0 bin. The subroutine will return a zero in any value for which the lookup (or the tower) is not implemented. This simulation will take into account any scale shift performed by the PROM. This simulation will take into account any low energy cutoff performed by the PROM. This simulation will take into account any input or output offset handled by the PROM. This simulation will take into account the fine tuning "Tweak" of each lookup page. Defined 29-JAN-1990 MICHIGAN STATE UNIVERSITY, TRIGGER CONTROL SOFTWARE Updated 2-AUG-1990 MICHIGAN STATE UNIVERSTITY, TRIGGER CONTROL SOFTWARE -------------------------------------------------------------------------- TOWER_THRESHOLD_TRANSLATION --------------------------- SUBROUTINE TOWER_THRESHOLD_TRANSLATION ( & SIGN_ETA, MAGN_ETA, PHI, & THRSH_TYPE, & DESIRED_THRSH, & HARDWARE_THRSH ) INTEGER THRSH_TYPE INTEGER SIGN_ETA, MAGN_ETA, PHI REAL DESIRED_THRSH INTEGER HARDWARE_THRSH Purpose and Methods : Calculates the appropriate reference byte to load into the CTFE card cluster threshold comparator for the specified Trigger Tower and the specified quantity type in order to achieve the specified energy threshold comparison. The threshold translation is inclusive, meaning that an energy deposit of the amount specified or greater will clear the threshold. In the case of the Hadronic Veto, an hadronic energy deposit of the amount specified or greater will prevent an EM tower to clear its threshold. Inputs : THRSH_TYPE specifies the quantity type for which the threshold translation is requested. It is recommended to use one of the compilation constants defined along with the common block. See TT_..._THRTYP in common block. SIGN_ETA is the sign of the eta index of the trigger tower for which the threshold is requested. Use 0 to specify a negative eta index, 1 to specify a positive eta index. It is recommended to use one of the compilation constants defined along with the common block. POS_ETA=0 or NEG_ETA=1. MAGN_ETA is the magnitutde of the eta index of the trigger tower for which the threshold is requested. Range : 1 to 24 PHI is the phi index of the trigger tower for which the threshold is requested. Range : 1 to 32 DESIRED_THRSH is the desired energy threshold to be applied to the specified tower. Units: GeV. Outputs : HARDWARE_THRSH is the byte of quantified threshold to be loaded in the CTFE cluster threshold comparator of the specified Trigger Tower to achieve the specified threshold comparison. Controls: None Comments : A call to INIT_LOOKUP_ROUTINES must have been made before this routine can be called. No verification is made of the integrity of the arguments specifying the indices of the Trigger Tower. This translation will take into account any offset present at the output of the lookup PROMs. The Threshold comparator (in the hardware) will perform a strict comparison. This means that a Trigger Tower must have a quantified transverse energy at the output from the Lookup PROMS strictly greater than the reference byte programmed for that Trigger Tower to contribute to the global count carried over the whole detector. When the desired threshold exactly falls on an allowed quantified value, the byte will be chosen to implement an inclusve comparison by returning the next smaller byte when necessary. Defined 6-FEB-1990 MICHIGAN STATE UNIVERSTITY, TRIGGER CONTROL SOFTWARE Updated 2-AUG-1990 MICHIGAN STATE UNIVERSTITY, TRIGGER CONTROL SOFTWARE -------------------------------------------------------------------------- GLOBAL_THRESHOLD_TRANSLATION ---------------------------- SUBROUTINE GLOBAL_THRESHOLD_TRANSLATION ( & THRSH_TYPE, & DESIRED_THRSH, & HARDWARE_THRSH ) INTEGER THRSH_TYPE REAL DESIRED_THRSH INTEGER HARDWARE_THRSH Purpose and Methods : Translates the specified global energy threshold to the appropriate reference number to load into a comparator of one of the last summing CAT card of the specified Energy tree. The threshold translation is inclusive, meaning that an energy deposit of the amount specified or greater will clear the threshold. Inputs : THRSH_TYPE specifies the quantity type for which the threshold translation is requested. It is recommended to use one of the compilation constants defined along with the common block. See GL_..._THRTYP in common block. DESIRED_THRSH is the desired energy threshold to be applied to the specified tower. Units: GeV. Outputs : HARDWARE_THRSH is the byte of quantified threshold to be loaded in the appropriate Tier #3 (or final stage) CAT Card to achieve the specified threshold comparison. Controls: None Comments : A call to INIT_LOOKUP_ROUTINES must have been made before this routine can be called. This translation will take into account the global sum of any offset present at the output of the lookup PROMs for the specified quantity. The threshold comparator in the hardware of the CAT card will perform an inclusive comparison. This means that a quantified global energy sum must be greater than or equal to the reference number programmed for that quantity to be considered as passing the threshold. Defined 6-FEB-1990 MICHIGAN STATE UNIVERSTITY, TRIGGER CONTROL SOFTWARE Updated 2-AUG-1990 MICHIGAN STATE UNIVERSTITY, TRIGGER CONTROL SOFTWARE -------------------------------------------------------------------------- SIMUL_LEVEL0 ------------ SUBROUTINE SIMUL_LEVEL0 ( Z_VERTEX, L0_BIN, L0_VALID) REAL Z_VERTEX INTEGER L0_BIN LOGICAL L0_VALID Purpose and Methods : Calculates the Level 0 Trigger response to a given interaction vertex along the z-axis. Inputs : Z_VERTEX specifies position of the interaction vertex for which the corresponding Level 0 Trigger Bin is requested. Units: cm Outputs : L0_BIN the number of the Level 0 Trigger Bin including the specified vertex position. Range: -15 to +15 L0_VALID is the good signal accompanying the level 0 fast vertex position. This signal will be negated for vertices falling outside of the defined bins. Controls: None Comments : A call to INIT_LOOKUP_ROUTINES must have been made before this routine can be called. The routine will return bin #0 when the vertex position is outside of the coverage of the level 0 bins, i.e. for (low boundary of bin #-15 ) < (vertex z-position) < (high boundary of bin #+15). This routine only partially simulate the level 0 "GOOD" signal that specifies whether the level 0 was able to find the vertex of the interaction. This line could be negated for reasons other than the non-existence of a bin including vertex position. A vertex exactly on a bin boundary between two bin coverages will be considered as belonging to the bin closer to the center of the detector. [...[...[...[...]...]...]...] Defined 6-FEB-1990 MICHIGAN STATE UNIVERSTITY, TRIGGER CONTROL SOFTWARE Updated 2-AUG-1990 MICHIGAN STATE UNIVERSTITY, TRIGGER CONTROL SOFTWARE -------------------------------------------------------------------------- PARAMETER FILE -------------- Sign_Eta -------- These parameters encode the sign of the eta index. These parameters are used to dimension some arrays in the common block. POS_ETA Positive Eta value NEG_ETA Negative Eta value Bounds for ETA and PHI ---------------------- These parameters specify the maximum and minimum quantities for the eta and phi indices of the Trigger towers. These parameters are used to dimension some arrays in the common block. ETA_MIN Minimum Eta value ETA_MAX Maximum Eta value PHI_MIN Minimum Phi value PHI_MAX Maximum Phi value Trigger Tower Type ------------------ These parameters define the type of Trigger Tower. There are two basic tower types, the electro-magnetic (EM) and the hadronic (HD) trigger tower. Except at very high rapidity, all EM and HD towers are paired into projective Total (TOT) Trigger Towers and their EM and HD signals are summed for processing certain quantities. These parameters are used to dimension some arrays in the common block. EM_TOWER Electromagnetic Tower HD_TOWER Hadronic Tower TOT_TOWER Total Tower Looked Up Quantities -------------------- Several quantities are looked up: Using the EM Trigger Tower signal, two quantities are successively looked up on the same PROM: The first quantity is the z-corrected EM Transverse Energy (Et), the second is referenced as EM L2. Using the HD Trigger Tower signal, two quantities are successively looked up on the same PROM: The first quantity is the z-corrected HD Transverse Energy (Et), the second is referenced as HD L2. Using the sum EM+HD=TOT Trigger Tower signal, two quantities are simultaneously looked up on two separate PROMs: One is the component Px of the z-corrected TOT Et along the x-axis, the other is the component Py of the z-corrected TOT Et along the y-axis. These parameters are used to dimension some arrays in the common block. EM_ET_QUANT Electromagnetic tower, Transverse energy lookup EM_L2_QUANT Electromagnetic tower, 2nd lookup HD_ET_QUANT Hadronic tower, Transverse energy lookup HD_L2_QUANT Hadronic tower, 2nd lookup PX_QUANT PX momentum lookup PY_QUANT PY momentum lookup TOT_ET_QUANT Total transverse energy lookup TOT_L2_QUANT Total 2nd lookup Prom Type --------- These parameter encode the prom type used to generate a given quantity. See the previous parameters for further details. These parameters are used to dimension some arrays in the common block. EM_PROM HD_PROM PX_PROM PY_PROM Threshold Type -------------- These parameters should be used to specify a threshold type as a parameter to the subroutine for translating Trigger Tower (note TT_) thresholds from GeV units to a downloadable byte. TT_EMET_THRTYP Electromagnetic tower, transverse energy TT_HDVETO_THRTYP Hadronic veto TT_TOTET_THRTYP Total transverse energy Global Threshold Type --------------------- These parameters should be used to specify a threshold type as a parameter to the subroutine for translating global (note GL_) thresholds on global quantities summed over the whole detector from GeV units to a downloadable integer. The existing thresholds are a subset of the available quantities. They are mapped onto the individual quantities so that the proper tree offset can be accessed. GL_EMET_THRTYP GL_EML2_THRTYP GL_HDET_THRTYP GL_HDL2_THRTYP GL_TOTET_THRTYP GL_TOTL2_THRTYP Bounds for Level 0 Bins ----------------------- These parameters specify the maximum and minimum quantities for the Level 0 Bin Numbers (L0_BIN_*). L0_BIN_MIN The minimum Level 0 Bin number L0_BIN_MAX The maximum Level 0 Bin number DIRECTLY USABLE VARIABLES FROM THE LEVEL1_LOOKUP COMMON BLOCK ------------------------------------------------------------- The LEVEL1_LOOKUP common block is internally used by the lookup system management routines. It is initialized with the values read from the lookup system management file. Some quantities are directly usable variables, the list below shows the directly used variables. The rest of the variables are accessed and used by specialized routines. The files 'D0$LEVEL1:LEVEL1_LOOKUP.PARAMS' and 'D0$LEVEL1:LEVEL1_LOOKUP.INC' must be included in any program that accesses these variables. Also, a call to the subroutine INIT_LOOKUP_ROUTINES must be made before any of these variables may be accessed. INTEGER DAC_BYTE ( SIGN_ETA, MAGN_ETA, PHI, EM_TOWER/HD_TOWER ) An array specifying all of the pedestal correction bytes to be downloaded into the DAC of the analog section of the CTFE cards for each Trigger Tower. These bytes must be downloaded into the hardware every time the calorimeter trigger is initialized in order to guaranty that the ADC zero energy responses match what the lookup table describes. INTEGER ADC_ZERESP ( SIGN_ETA, MAGN_ETA, PHI, EM_TOWER/HD_TOWER ) An array that represents the offsets at the output of the ADCs, that is the zero energy response of the ADC. REAL ELEC_NOISE_SIGMA ( SIGN_ETA, MAGN_ETA, PHI, EM_TOWER/HD_TOWER ) An array specifying the expected electronics noise in each Trigger Tower. REAL GLOBAL_ENERGY_SCALE ( EM_ET_QUANT/EM_L2_QUANT /HD_ET_QUANT/HD_L2_QUANT /TOT_ET_QUANT/TOT_L2_QUANT /PX_QUANT/PY_QUANT ) An array specifying the energy scale globally used for each of the quantities summed over the whole detector. If the need arises in the future, the scale might become locally modified on certain trigger towers. REAL GLOBAL_ADC_SCALE A REAL variable specifying the energy scale globally used for the output of the ADCs for each of the EM and HD Trigger Tower channels. If the need arises in the future, the scale might become locally modified on certain trigger towers.