THE LOOKUP SYSTEM MANAGER PROGRAM --------------------------------- Overview -------- The Lookup System Manager Program is an interactive program that performs several services related to the Level 1 hardware. It manipulates information from the Lookup System Manager File, a user-readable text file that describes the Level 1 hardware. The main functions of the Lookup System Manager Program are: 1) Interactively read and verify the syntax and content of an LSM file. Data consistency and error reports are explicit and traceable back to the faulty LSM File line. An LSM File should always be verified by the LSM Program before it is read by an application program (like the Level 1 Simulator Program) which uses the LSM Object Library. The LSM Program must be used to find and correct an error reported by the LSM library. 2) compile complex quantities from more basic information. The LSM Program can augment, update or verify these quantities in an LSM file. 3) create input files for a PROM burner, which are used to program the lookup PROMs for the CTFE cards. 4) perform simulation of several of the functions of the Level 1 hardware, using the routines from the Lookup System Manager Object Library. 5) more tools will be attached in the future. The Lookup System Manager Program loads a set of internal arrays using the data from the Lookup System Manager File, and uses this data to perform the various functions of the program. The LSM File ------------ The Lookup System Manager File is a description of the Level 1 Calorimeter Trigger hardware that can be readily understood and easily modified by the user. The file is generally created (or edited) by the user with the possible assistance of other programs. The Lookup System Manager program may be directed to update certain parts of the file and write out a new copy, but otherwise the file is not modified by the program. The syntax of the Lookup System Manager file has been especially chosen for readability, flexibility, and compactness. The syntax allows the user to assign VALUES to each one of the quantities that have been chosen to describe the Level 1 Lookup Hardware. A fairly large number of quantities is needed to fully represent the flexibility and complexity of the hardware. The large number of quantities representing the Level 1 Lookup Hardware is ordered into a smaller number of multidimensional arrays called ITEMS. At the highest level, the file is divided into SECTIONS, each of which fully covers one item to be described. This document contains descriptions of the quantities each SECTION represents, in addition to a full description of the syntax of the Lookup System Manager file. The Lookup System Manager Object Library ---------------------------------------- There exists a collection of FORTRAN routines, that can be called by a user program to fill a common block with the information from a Lookup System Manager File. Some of the information is then directly accessable by the program, and other information can be obtained by calling the simulation routines that are part of the object library. The code for the Lookup System Manager Object Library and the code for the corresponding functions in the Lookup System Manager Program are almost identical, except the Object Library code has been optimized for speed and memory usage, and only performs operations necessary to provide the required information from the LSM file. The object library uses the same LSM files as the full program. Only a portion of the information in the LSM File is interpreted by these routines. The information that is ignored is not directly needed by the simulation routines, rather it represents basic quantities that the LSM Program uses to compile more complex quantities in the LSM File. Elsewhere there exists a file describing the individual routines in the object library Main Actions Performed by the Lookup System Manager Program ----------------------------------------------------------- Load a Lookup System Manager File This item causes the data in an LSM file to be loaded. Prompts are issued for a directory, file name, version number, and whether to perform ASSIGNMENT checks (described elsewhere) while the file is being read. The file loaded will have the name directory:filename_vvvv.lsm, where vvvv is the 4-digit version number. Also, the name of a file is requested to use for recording messages generated. When loading an LSM file, it is possible to generate a large number of error messages, so a file is used to record them. If any messages are generated during the loading of the file, the user is presented with the option of viewing them (under EVE). In any case, the message file remains for review later. An internal flag is set to indicate that a file has been read if no errors in the syntax of the file are found. This is required to perform several of the other operations provided by the Lookup System Manager Program. Verify LSM File Once a file is loaded, several checks can be performed on it to verify that the information it contains is self-consistent, and that its values lie within a reasonable range. Prior to performing this operation, an LSM file must have already been successfully loaded using the LOAD LSM FILE option. Each of several checks may be enabled independently of the others. The checks consist of RANGE CHECKS (formerly ANALYSIS checks), verifying the compiled quantities PROM_CUT and PROM_SLOPE, and verifying the values for the tower geometry. After the selected checks are run, if no messages were generated the user is notified, otherwise the messages are displayed under EVE. Update LSM File --------------- Some of the quantities in the LSM file can be compiled from other quantities in the file. If the user changes part of the file, these compiled quantities might no longer be valid. The Lookup System Manager program can create a new file that contains the data from the original file, except for the updated SECTION(s), which contains the new data. Prior to performing this operation, an LSM file must have already been successfully loaded using the LOAD LSM FILE option. The quantities represented by the sections PROM_OUTPUT_CUT and PROM_SLOPE may be updated in this way. The UPDATE LSM FILE option may also be performed on the values of the tower geometry, retrieving the current values from storage elsewhere. Each quantity may be independently selected for updating. The format of the prompts for the input and output files is similar to the prompt for the input file used in the operation LOAD LSM FILE. The input file name defaults to the name of the file that was originally used in the operation LOAD LSM FILE. It is recommended that this file be used, because the updated data may not be valid with another file. Some of the data from the original file is used to compile the updated quantities, and these quantities will not be valid if they are combined in a file with data they were not compiled from. A second file name is prompted for to use as the output file. The default file name is the same as the default input file name, except the revision number is incremented by one. When the action is actually executed, first the new values are calculated. Then the input LSM file is copied to the output file, omitting all SECTION constructs corresponding to the sections to be updated, and leaving the remainder of the file unchanged. Then the new sections are written to the end of the output file. When the action is finished, the updated file becomes the current file, and the information used in all subsequent actions (until another LSM file is loaded) is the updated information. PROM Builder Routines --------------------- One of the main functions of the Lookup System Manager Program is to create files for input to a PROM burner, to create PROMs for use in the CTFE cards in the Level 1 Trigger hardware. It can also verify that one existing PROM file or all the existing PROM files for a particular configuration are valid. A valid Lookup System Management File must be loaded prior to performing any of these operations. When creating one PROM file, the user is first prompted for the tower coordinates of the CTFE card for which to create the file. Then, an output file name is asked for, along with whether to create a binary file and/or Intellec-format file. An Intellec-format file is a text file that contains the PROM data in hexadecimal format, along with header and addressing information. The components of the file name asked for are directory, file name, and version number. The default value for `file name' is: ' CtysHHPP_CTFE_PROM.filxx ' ^^^^^^^ ^^^^^ where ty = PROM type, EM = electromagnetic lookup memory HD = hadronic lookup memory PX = X - momentum lookup memory PY = Y - momentum lookup memory s = sign of the Eta index, P = positive N = negative HH = Eta index, from 01 to 24 PP = Phi index, from 01 to 32 fil = file type, INT for Intellec format file BIN for binary format file xx = version number of source program, presently (SEP-90 )at 6. Version numbers are being used to keep track of expected changes in the Trigger Tower Coordinate Tables, which will result in different versions PROM's having the same Index numbers. Example File name : CPYN0523_CTFE_PROM.INT05 This identifies an Intel format file for a Y Momentum LUM Prom with version 5 values for Eta = -5, Phi = 23. If the program is directed to create all of the PROM files, the user is prompted for a directory name, a version number, and whether to create binary and/or Intellec format. It then goes through all the possible coordinates, and creates a file for each one whose DOWNLOADED_BYTE (DAC_BYTE) is non-zero. This information will have been loaded from the Lookup System Management File. The files created will have the specification `directory:CtysHHPP_CTFE_PROM.filxx' with `directory' being the directory chosen by the user for the set of files, and `CtysHHPP_CTFE_PROM.filxx' being the default file name encoding the tower coordinates as described above. In the Level 1 hardware, the Energy Lookup Memory is implemented in a Cypress type CY7C245A 2048 x 8 registered EPROM. The Register and Initialization control bytes are programmed with 0's for this application. The Momentum Lookup Memory is implemented in an AMD type AM27291A 2048 x 8 PROM. There are no programmable control bytes. The PROM programming source file for the PROM's is an 8 bit binary sequential file containing the 2048 data bytes written in the order, by address, in which which they are to be stored in the PROM. The Data byte list for the EM and HD Memories is followed by two bytes for the register programming, which are 00,00. In order to obtain the proper format for the output file in a FORTRAN program, VAX extensions to the IO routines had to be used. If D0FLAVOR is used to produce a version for a non-VAXVMS system, calculations are performed but no files are created. It is intended that the PROM data output file be transfered to an IBM PC under DOS 3.3 for use with The Quickpro or Omni ROM burning programs. Simulation Routines ------------------- The Lookup System Manager Program can perform the same calculations as the routines in its companion object library, LSMLIB. An LSM file must be successfully loaded prior to performing any of these operations. Analog to Digital Conversions ----------------------------- Simulates the analog to digital conversions performed by the Calorimeter Trigger for the specified energy deposits for the given trigger tower. Prompts are given for ETA coordinate (+/-[1,24]), PHI coordinate ([1,32]), EM tower energy (GeV), and HD tower energy (GeV). It then gives the simulated EM tower ADC byte and the simulated HD tower ADC byte. Zero is returned for those 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. Prom Responses -------------- Reconstruct the set of prom responses for the specified set of ADC bytes, and the specified Level 0 Trigger information. The program asks for the Level 0 bin number ([-15,15]), ETA index (+/-[1,24]), PHI index ([1,32]), the ADC output byte of the EM Trigger Tower, and the ADC output byte of the HD Trigger Tower. It then gives the expected set of PROM outputs for all of the constructed quantities (EM ET, EM L2, HD ET, HD L2, PX, and PY). 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. The program will display a zero for 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. Calculate Tower Threshold Translation ------------------------------------- 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. The program first asks for the ETA index (+/-[1,24]), PHI index ([1,32]), and the desired threshold energy (GeV). It returns 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. The thresholds computed are the EM ET threshold, the hadronic veto threshold, and the total ET threshold. 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. Calculate Global Threshold Translation -------------------------------------- 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. The program asks for the desired threshold energy (GeV), and then gives the bytes for the EM ET threshold, EM L2 threshold, HD ET threshold, HD L2 threshold, total ET threshold, and total L2 threshold. 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. Simulate Level 0 Response ------------------------- Calculates the Level 0 Trigger response to a given interaction vertex along the z-axis. The program asks for the position of the interaction vertex (in cm from the center of the detector). It then gives the number of the Level 0 Trigger Bin that includes the specified vertex position. It also gives whether the vertex position is considered valid. It is valid if the vertex falls outside the defined bins. 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 the 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. [...[...[...[...]...]...]...] Show Tree Offset ---------------- This operation displays the contents of the internal array TREE_OFFSET, which is derived from some of the data in the input LSM file. This array variable holds for each of the constructed quantities the sum carried over the whole detector of all individual PROM output offsets introduced at each Tower for that quantity. This numbers must be subtracted on the last summing CAT card of each corresponding energy tree in order to produce the correct global energy sum for that quantity. The data block will receive this corrected sum. The array will hold a zero for any value for which the lookup is not implemented. Show Raw Energy to ADC Conversion Factor ---------------------------------------- This operation displays the contents of the internal array ADC_CNT_VS_RAW_E, which is derived from some of the information gathered from the Lookup System Manager Program. If the display is in full-screen mode under COMPACK, the output is paged, with the PF keys controlling the display. This array variable represents the linear transformation factor between the incoming (raw) energy and the output of the ADC. It takes into account (1) the input energy error (2) the analog input scaling factor and (3) the LSB scale of the ADC. (It also depends on the voltage references given to the ADC). In order to calculate the ADC response to an incoming energy, the raw input energy expressed in GeV must be scaled by this factor, the result must then be rounded to the nearest integer and added to the ADC offset. Lookup System Management File ----------------------------- The Lookup System Management File is a description of the Level 1 Calorimeter Trigger hardware that can be readily understood and easily modified by the user. The file is generally created (or edited) by the user with the possible assistance of other programs, and is not altered by the Lookup System Management Utility. The Lookup System Management File is a sequential ASCII file. It must have the extension .LSM. The records (lines) in this file are of variable length, but no longer than 132 characters. Upper case and lower case are equivalent, and may be freely mixed. Any number of space characters is allowed between any two keywords or values in the file (e.g. for indentation). A minimum of one space character is required between any two consecutive keywords or values appearing on one line. Unless otherwise stated, each statement must appear on a single line by itself, with the exception that it may be followed by a comment on the same line. Blank lines, or lines containing only a comment, may appear anywhere. Syntax ------ The syntax has been especially chosen for readability, flexibility, and compactness. The syntax must allow the user to assign VALUES to each one of the quantities that have been chosen to describe the Level 1 Lookup Hardware. A fairly large number of quantities is needed to fully represent the flexibility and complexity of the hardware. The large number of quantities representing the Level 1 Lookup Hardware is ordered into a smaller number of multidimensional arrays called ITEMS. At the highest level, the file is divided into SECTIONS, each of which fully covers one item to be described. Each Item is a multi-dimensional array. Each dimension within an array is associated with an index called a VARIABLE. Each Item will use a particular subset of the available Variables. When whole sections of arrays are assigned the same Value, it is not necessary to repeat the value for each array element. Instead it is sufficient to specify the section of the array covered by the value, thus emphasizing the fact that the values are constant and enhancing the meaningful information out of the large number of quantities. This also covers the case of an array that is independent of one or more of its available dimensions. Describing such a multidimensional domain is done using nested WITH statements specifying upper and lower bound values for each of the variables. When the values to assign to the elements of an item are all different, a LIST statement can be used. This statement must be followed by a list of numbers. The range of variables covered by the list of values is specified in the list statement. The successive members of the list of values are assigned to successive coordinates in the item. File structure -------------- The Lookup System Management File has the following structure: [ section [ []... ]... end_section ]... Items in square brackets indicate that the item is optional, and an ellipsis indicates that more than one of that item may occur. Comments -------- An exclamation point marks the beginning of a comment. The comment extends to the end of the line, and its contents are ignored. Comments can follow commands on the same line. Sections -------- The file is divided into sections, each containing one or more items to be described. Each section is begun with a 'section' statement, and ended with an 'end_section' statement. The section and end_section statements must each be on separate lines from other statements. The syntax for the section statement is as follows: section [ []... ]... end_section This structure is repeated for each section to be specified. The indentation is recommended but not required. The allowable values for section_name are: LEVEL_0_BINS_LOW LEVEL_0_BINS_HIGH LOOKUP_QUANTITIES PAGE_VS_BIN PAGE_NOMINAL_CENTER GLOBAL_ADC_SCALE GLOBAL_ENERGY_SCALE ELECT_NOISE_CUT_FACT TOWER_GEOMETRY_R TOWER_GEOMETRY_Z TOWER_GEOMETRY_PHI ANALOG_INPUT_SCALING ADC_LOCAL_RESCALING DOWNLOADED_BYTE ADC_ZERO_E_RESPONSE ELECT_NOISE LOOKUP_ZERO_E_RESP ENERGY_SCALE_SHIFT FINAL_FITTING TRANSV_ENERGY_CUT PROM_TRANSFER_COEFF is one or more 'with...end_with' constructs. is either a 'list' statement or a single value assignment statement. The sections may occur in any order, and a particular section may appear more than once. Because of this, it is possible to assign a value more than once to a member of an item. If this is attempted, only the last value assigned will be valid, and a warning message will be generated if assignment checks (described elsewhere) are enabled. It is also possible to omit a section, or to declare a section but not specify any values. If the members of an item are incompletely specified and assignment checks are enabled, a warning will be generated regarding the unassigned values. Range Specification ------------------- A range of values must be assigned to each variable that an item depends on to determine what coordinates of the item are assigned. 'with' statements and 'list' statements assign these values to the variables. The following is a list of all possible variables. Only a subset of these will be valid in any given section. CHANNEL LOOKUP PROM SIGN_ETA PHI MAGN_ETA PAGE INDEX BIN 'With' Statements ------------------------ with ..... end_with 'with' statements are used to assign values (or ranges of values) to variables that represent coordinates in the items being described. 'with' and 'end_with' statements must each be on separate lines from other statements. The following is a list of possible choices for and the values it can take: CHANNEL EM HD TOT LOOKUP ET L2 PX PY SIGN_ETA PLUS MINUS PROM EM_PROM HD_PROM PX_PROM PY_PROM PHI integers on range 1 to 32 MAGN_ETA integers on range 1 to 24 PAGE integers on range -3 to 3 INDEX integers on range 1 to 8 BIN integers on range -31 to 31 Nested 'with' statements are used when an item depends on more than one variable. Only a subset of these variables will be valid depending on the section being specified. It is illegal to respecify a variable in a 'with' statement that is already specified in an enclosing 'with...end_with' construct. The 'list' statement may be used in place of one or more of the innermost 'with...end_with' constructs. The 'list' statement must specify all necessary variables not specified in its enclosing 'with' statements, and may only specify variables which take on integer values. A 'list' statement may not respecify variables that have already been specified in an enclosing 'with...end_with' construct, and a variable may not be specified more than once in a given 'list' statement. PAGE, INDEX, BIN, PHI and MAGN_ETA take on integer values, while CHANNEL, LOOKUP, PROM, and SIGN_ETA take on enumerated values. can be one of a single value (for both integer and enumerated variables) to a range of values from to inclusive (for integer variables only). and are integers. and [and ] ... a set of values, where is a . If the assignment checks (described elsewhere) are enabled, a warning will be generated at the end of parsing for items that have not been completely specified. It is possible, with successive 'with...end_with' constructs whose values overlap, to specify a value to the same member of an item more than once. In this case, the last specification is the one that is valid. If assignment checks are enabled, such attempts will produce a warning message. Also, it is possible to have a 'with...end_with' construct that does not have an item specification within it, or alternatively for it to have more than one item specification within it. Single Value Assignment ('assign' statement) -------------------------------------------- assign A single value assignment statement gives to all instances of selected by its enclosing 'with' statements. A single value assignment statement must appear on a line separate from all other statements. can be either a number or an enumerated value. Enumerated values are valid only in those sections whose descriptions explicitly state that an enumerated value is required. List Assignment --------------- list to [ to ] ... [] [] ... end_list The 'list' statement allows a list of values to be scanned, and successive values in the list are assigned to successive instances of specified by the variables. The variables vary through the range to given, where and must be integers. Thus the only allowable values for are: PHI MAGN_ETA PAGE INDEX BIN Unlike the 'with' statement, the 'and' operator is not available for specifying ranges in a 'list' statement. Ranges in a 'list' statement must be of the form ' to '. The rules for variable specification hold across all variable specification blocks in a section, so in a 'list' statement all variables necessary for a particular section that have not been specified by prior 'with' statements must be specified by that 'list' statement. The entries must begin on a separate line from the 'list' statement. The entire set of entries may occupy more than one line. entries appearing together on the same line must be separated from each other by at least one space. can be either a number or an enumerated value. See the description of in 'assign' statements above for more description. The last variable specified varies "fastest" while scanning the list. For example: list SLOPE for MAGN_ETA 1 to 2 INDEX 1 to 3 ! VALUE MAGN_ETA INDEX 1 ! 1 1 2 ! 1 2 3 ! 1 3 4 ! 2 1 5 ! 2 2 6 ! 2 3 end_list Assignment Checks ----------------- At the time that a Lookup System Management File is loaded using the Load LSM File option of the Lookup System Manager Program, it is possible to enable the use of assignment checks while the file is being loaded. When assignment checks are enabled: 1) the Lookup System Manager Program will indicate statements which assign values to members of an item that have already been assigned to by a previous statement. 2) it will also generate messages when a section or with statement is used that does not ultimately result in assigning a value to an item. 3) it will indicate sections and items that have not been completely specified. Find reassigned items: At each assignment statement, a check is made to see if any of the members of the item that the statement assigns have already been assigned. If any members are redefined in this way, one message is generated for each line, and parsing will continue. Identify empty SECTIONs: During the parsing of each SECTION statement, a flag is set to indicate that no assignments have occured. On the parsing of an ASSIGN statement or a LIST statement, the flag is reset to indicate that an assignment has occured. When the END_SECTION statement is parsed, this flag is checked, and a message is generated if the flag indicates that no assignment has occured. The status NO ERROR is returned. Identify empty WITH constructs: During the parsing of each WITH statement, a flag is set to indicate that no assignments have occured. On the parsing of an ASSIGN statement or a LIST statement, the flag is reset to indicate that an assignment has occured. When the END_SECTION statement is parsed, this flag is checked, and a message is generated if the flag indicates that no assignment has occured. The status NO ERROR is returned. Find omitted items: After the file has been read, a check is made on all elements of the common block arrays, to see that no necessary quantities are left undefined. Some of the items select which towers and lookups in other items are defined. If all of the members of an array that should be defined are not, then one message is generated for the whole item. If only a portion of these values are left undefined, then a message is generated for each undefined member. Either of these cases will cause a status of ERROR WHILE ANALYZING FILE to be returned. If it is indicated that a member of an item should be undefined, and a value has been specified for it, then a message is generated and the status ERROR WHILE ANALYZING FILE is returned. Active pages for each quantity are defined in looked up quantities and pages. If a page is not active, then an index of 0 should be assigned to its corresponding member of LOOKUP_QUANTITIES. Existing towers are defined by non-zero values of DOWNLOADED_BYTE. If a tower does not exist, a value of 0 should be assigned to its corresponding member of DOWNLOADED_BYTE. A message is generated for missing values in section LOOKUP_QUANTITIES only if no values have been specified for any of its members. No messages are generated if only some of the values in section LOOKUP_QUANTITIES are left unspecified in the Lookup Manager System File. This is because the values are defined if they are specified, and they are considered undefined if they are not specified. With the assignment checks disabled, error messages during the loading of the file are only generated for errors in the syntax of the file. Description of Data to be Contained in Each Section --------------------------------------------------- The following is a description of the physical quantities that each section of the Lookup System Manager describes. For each quantity, it gives a name for the quantity being described, the name of the SECTION of the LSM file that represents it, the definition of the quantity, the set of variables that describe the dimensions of this quantity, the data type used to represent it, the units it quantity is in, how this information is to be entered into the LSM file, verification checks run on each quantity, and whether or not that section is read by the LSM object library routines. 1. Level 0 Bins Geometric Coverage 2. Lookup Types 3. Lookup Pages 4. Mapping of Lev 0 Bin vs Lookup Page 5. Lookup Page Nominal Center 6. Global ADC Scales 7. Global Energy Scales 8. Electronics Noise Suppresion Coefficient 9. Trigger Tower Geometry 10. Trigger Tower Electronics Noise 11. Input Energy Error 12. Analog Input Scaling Factor 13. Downloaded Bytes 14. ADC Zero Energy Response 15. Lookup Energy Scale Shift 16. Lookup Transverse Energy Cut 17. Final Fitting (Tweak) 18. Lookup Zero Energy Response 19. PROM Output Minimum Energy Cut 20. PROM Slope 1. Level 0 Bins Geometric Coverage ---------------------------------- section name : (2 similar sections) LEVEL_0_BINS_LOW LEVEL_0_BINS_HIGH definition : These quantities describe the coverage of each Level 0 Bin along the z-axis. Two lists of numbers are given: the upper and lower limit of the position of the interaction vertex covered by each Level 0 bin. dimensions : -15 <= BIN <= +15 data type : Floating point real units : centimeters source : manually entered by the Trigger Manager. usage: fill common block variable L0_BIN_COVERAGE. used by SIMUL_LEVEL0.FOR assignment checks: All values should be specified. Error otherwise. verification checks: The upper boundary of each bin should be equal to the lower boundary of the next bin. The boundary coordinates should be ordered from low to high. The entire range of boundaries should be in the range [-120, +120]. Bin #0 should have a width in the range [5.0, 8.0], and the width of each of the other bins should be within 1% of the width of bin #0. The boundaries of bin #0 should be centered on 0.0 within 1%. minimal: Yes 2. Lookup Types --------------- section name : (2 similar sections) FIRST_LOOKUP_TYPE SECOND_LOOKUP_TYPE definition : This information defines which quantity type is built during the first and second lookups. The same type of quantity is built for the EM and the HD channel. The first lookup is currently defined as a lookup of the transverse enery (noted ET), the second lookup (noted L2) will for example rebuild the deposited energy or build another lookup of ET with different low enegy cuts. dimensions : one keyword allowed for each section data type : Keyword units : current keywords are DEPOSITED_ENERGY and TRANSVERSE_ENERGY source : manually entered by the Trigger Manager. usage: fill common block variables FIRST_LOOKUP_TYPE and SECOND_LOOKUP_TYPE. directly accessible in common block. used to calculate prom transfer coefficient. used in the computation of prom lookup cuts. assignment checks: A value should be specified. Error otherwise. verification checks: One of the keywords should be assigned. minimal: Yes 3. Lookup Pages --------------- section name : LOOKUP_QUANTITIES definition : The Calorimeter Trigger Lookup System can adjust its computation of the transverse energies using the Fast Vertex Data from the Level 0 Trigger. A Logical Lookup Page is associated with a segment of the beam pipe and will be used for all interaction vertices falling within this segment. A Physical PROM page called page Index is associated with each Logical lookup page. This section defines how many logical pages are used for each of the first and second lookups of each quantity. For each Logical page, this section assigns a physical PROM page Index to be used to implement the logical lookup page. Logical pages are in the range -3..0..+3, with page #0 covering the center of the detector. A PROM Page Index is in the range 1..8. The number and allocation of lookup pages for a given lookup quantity is constant over all trigger towers. A maximum of 8 independent z-correcting lookup pages can be allocated for a given quantity being looked up. This maximum of 8 lookup pages is however shared between the Et and second lookup of the EM or HD channel. All pages not used (out of the maximum of 8 pages) by the Et lookups ("first lookups") can be allocated for the second lookups as defined above. dimensions : (CHANNEL,LOOKUP) = (EM,ET), (HD,ET), (EM,L2), (HD,L2), (TOT,PX), or (TOT,PY) -3 <= PAGE <= +3 data type : Integer units : PROM Page Index (1..8) source : manually entered by the Trigger Manager. usage: fill common block variable LUQ_PAGE_INDEX. defines how many pages are used for each lookup. defines the mapping of Logical Pages to Page Indices. used by PROM_RESPONSES.FOR assignment checks: An error is generated only if no values are specified. It is not an error to partly specify this item. A page is considered defined if a non-zero value is given to it. verification checks: The indices given should all fall in the range 0 to 8. An index of 0 means that page is not defined. Check that contiguous pages are assigned contiguous indices. Check that EM ET and HD ET each use the same range of indices, EM L2 and HD L2 use the same range of indices, and PX and PY use the same range of indices. The indices given for lookup ET and lookup L2 should not overlap. If a lookup is a deposited energy lookup, check that it is given only one page. minimal: Yes 4. Mapping of Lev 0 Bin vs Lookup Page -------------------------------------- section name : PAGE_VS_BIN definition : For each looked up quantity, this section defines which level 0 bins make up each Logical Lookup Page. Since we only have a maximum of 8 PROM pages and the level 0 trigger can specify up to 31 different z positions, several level 0 bins will typically point to one of our lookup pages. dimensions : (CHANNEL,LOOKUP) = (EM,ET), (HD,ET), (EM,L2), (HD,L2), (TOT,PX), or (TOT,PY) -15 <= BIN <= +15 data type : Integer units : Logical Lookup Page (-3..+3) source : manually entered by the Trigger Manager. usage: fill common block variable LUQ_PAGE_NUMBER. Defines the mapping of Level 0 Bins onto Lookup Pages. used by PROM_RESPONSES. assignment checks: All values should be specified. Error otherwise. verification checks: Check that the bins are contiguous within each page, assigned in increasing order, and that bin 0 is within page 0. Check that values fall in the range [-3,3]. This needs to be done in turn for all lookups. Check that the page given for each bin and looked up quantity maps to a valid prom index (i.e. invalid pages aren't given). Check that each valid page is assigned a bin. minimal: Yes 5. Lookup Page Nominal Center ----------------------------- section name : PAGE_NOMINAL_CENTER definition : For each looked up quantity and each lookup page, the page center defines the optimal z-position chosen to calculate that particular quantity for all interaction vertices (level 0 bins) pointing to that particular page. This nominal center is not necessarily the geometric center of the page. dimensions : (CHANNEL,LOOKUP) = (EM,ET), (HD,ET), (EM,L2), (HD,L2), (TOT,PX), or (TOT,PY) -3 <= PAGE <= +3 data type : Floating point real units : centimeters source : manually entered by the Trigger Manager. usage: fill common block variable PAGE_Z_NOM. used to compute prom transfer coefficient. assignment checks: A page is considered defined if the corresponding page in LOOKUP_QUANTITIES is non-zero. If a value has not been specified for a defined page, then it is an error. If a value has been spedified for an undefined page, then it is an error. verification checks: Check that the location given actually falls within the level 0 boundaries for that lookup and page; calculated from the items level 0 bins geometry and lookup page nominal center. Check that the value given falls within 10% of the center of the segment. minimal: No 6. Global ADC Scales -------------------- section name : GLOBAL_ADC_SCALE definition : This is the overall scale at the output from the ADCs, and thus the scale of the energies recorded in the first level data block. The scale is currently planned to be common for all the towers, but provision should be made for different energy scales in certain trigger towers (eta-dependency). The scale is however always guaranteed identical for the EM and HD section of a same tower. The local corrective factor to this global number would be recorded in item #16 below. The ADC energy scale currently envisioned is 1/4 GeV per least count. dimensions : 1 data type : Floating point real units : GeV source : manually entered by the Trigger Manager. usage: fill common block variable GLOBAL_ADC_SCALE. used in the computation of the common block variable ADC_CNT_VS_RAW_E (ratio between energy deposited in the calorimeter and ADC counts) assignment checks: A value should be specified. Error otherwise. verification checks: Check that the value given falls in the range (0.0, 1.0]. minimal: Yes 7. Global Energy Scales ----------------------- section name : GLOBAL_ENERGY_SCALE definition : For each energy related quantity being constructed, this is the energy scale of the global quantities after sum over the whole detector. This also is the quantum of energy existing at the time of the comparison to the global thresholds. This also is the energy scale corresponding to the global energy quantities recorded in the data block. The scale is currently planned to be common for all trigger towers, but provision should be made for different energy scales for different trigger towers (i.e. eta-dependency cf. item #16 below). The scale described here would still be relevant for the global sum, at the end of the summing trees. The energy scale currently envisioned is 1/4 GeV per least count of EM Et, HD Et and 1/2 GeV for Px and Py. dimensions : (CHANNEL,LOOKUP) = (EM,ET), (HD,ET), (EM,L2), (HD,L2), (TOT,PX), (TOT,PY), (TOT,ET) or (TOT,L2) data type : Floating point real units : GeV source : manually entered by the Trigger Manager. usage: fill common block variable GLOBAL_ENERGY_SCALE. used by GLOBAL_THRESHOLD_TRANSLATION.FOR used by TOWER_THRESHOLD_TRANSLATION.FOR assignment checks: A value for a lookup should be defined if page #0 of that lookup has been assigned an index (from section LOOKUP_QUANTITIES). All such lookups should be assigned values. All other lookups should not have a value specified. Error otherwise. verification checks: Check that the value given falls in the range (0.0, 1.0]. minimal: Yes 8. Electronics Noise Suppresion Coefficient ------------------------------------------- section name : ELECT_NOISE_CUT_FACT definition : This is an expression of the minimum cut in raw input energy that must be implemented in the lookup PROMs to suppress the electronics noise collected in the detector pads and preamps. This cut is only dependent on the raw E energy signal (i.e. it is not dependent on the vertex position correction). This electronics noise suppression coefficient is expressed in units of standard deviation of electronics noise in a given trigger tower. The electronics noise in each trigger tower is specified by its standard deviation sigmas in item #10 below. Different such suppression coefficients may be chosen for different lookup quantity but the SAME noise suppression is uniformly made on ALL TOWERS. This preceding sentence is true in number of sigmas of suppression, not in energy scale since the electronics noise is not uniform over the whole detector. Another energy cut implemented in the lookup PROMS is a "physics cut" chosen to improve the triggering performance. This physics cut is made in corrected Et energy scale, see item #16 below. The energy cut eventually implemented in the PROM (item #19) will be the greatest of the two independent contributions of the electronics noise cut and the physics cut. The physics noise cut should typically dominate, except at (very?) low rapidity. dimensions : (CHANNEL,LOOKUP) = (EM,ET), (HD,ET), (EM,L2), (HD,L2), (TOT,PX), or (TOT,PY) data type : Floating point real units : number of standard deviations of electronics noise. source : manually entered by the Trigger Manager. usage: fill common block variable ELEC_NOISE_CUT_FACT. used in the computation of prom lookup cuts. assignment checks: A value for a lookup should be defined if page #0 of that lookup has been assigned an index (from section LOOKUP_QUANTITIES). All such lookups should be assigned values. All other lookups should not have a value specified. Error otherwise. verification checks: Check that it falls in the range [0, 10). minimal: No 9. Trigger Tower Geometry ------------------------- 9.1. R and Z ------------ section name : TOWER_GEOMETRY_R TOWER_GEOMETRY_z definition : For each of the Electro-magnetic, Hadronic and Total Trigger Tower there are two coordinate values r and z that best describe the tower's geometry. This geometry is used for scaling the input signal from the BLS to its transverse component assuming the interaction vertex was in the center of the detector. It is used again when correcting the quantities using the Level 0 knowledge of the true position of the interaction vertex. Note that even though the Total tower is just the sum of the EM and HD towers, provision is made for independent coordinates. dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 1 <= PHI <= 32 CHANNEL = EM, HD, or TOT data type : Floating point real units : centimeters source : generated from the geometry of the calorimeter by a specialized routine. usage: fill common block variable TOWER_RZ_COORD The EM Trigger Tower coordinates are used to pick the front-end scaling ratio of the EM energy and again to compute the slopes of each z-correcting page of the EM Et and second EM lookup. The HD Trigger Tower coordinates are used to pick the front-end scaling ratio of the HD energy and again to compute the slopes of each z-correcting page of the HD Et and second HD lookup. The Total (EM+HD) Trigger Tower coordinates are used to compute the slopes of each z-correcting page of the Px and Py lookups. assignment checks: A member of an item should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, PHI, and CHANNEL. verification checks: Check that the coordinates for r all fall in the range [1.0, 110.0] for EM, [1.0, 140.0] for HD and TOT, that each HD quantity is larger than its corresponding EM quantity, and that each TOT quantity lies between its corresponding EM and HD quantities. NOTE: undefined towers cannot be compared. Check that the values are constant over PHI. The values of r should be within 20% of each other for eta = [1, 5], and then they should be decreasing for eta = [6, 24]. Check that the coordinates for z all fall in the range [8.0, 210.0] for EM, [9.0, 240.0] for HD, and [8.0, 240.0] for TOT. The value for each HD quantity should be larger than its corresponding EM value, and the value for each TOT quantity should lie between the values of its corresponding EM and HD values. Check that the values are constant over PHI. The values should be increasing for eta = [1, 5], and should be within 20% of each other for eta = [6, 24]. minimal: No 9.2. Phi -------- section name : TOWER_GEOMETRY_PHI definition : For each Total Trigger Tower the azimuthal coordinate participates in the computation of the prom slope of the Px and Py lookups. dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 1 <= PHI <= 32 data type : Floating point real units : degrees. source : generated from the geometry of the calorimeter by a specialized routine. usage: fill common block variable TOWER_PHI_COORD used in the computation of the PROM slope for the Px and Py lookups. assignment checks: A member should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, PHI, and with CHANNEL EM. verification checks: Check that the coordinates for nominal PHI all fall in the range [0.0, 360.0). Check that the coordinates are all increasing, and that they are separated from each other by 360.0/32.0 within 5%. minimal: No 10. Trigger Tower Electronics Noise ----------------------------------- section name : ELECT_NOISE definition : This is the measured or estimated standard deviation of the electronics noise in each trigger tower signal. To obtain the actual noise at the input to the ADC, one must multiply this noise by the input energy error. dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 1 <= PHI <= 32 CHANNEL = EM, or HD data type : Floating point real units : GeV of raw energy. source : manually entered by the Trigger Manager. These quantities can be approximated from the size, the number of pads in a trigger tower and the cable length of each signal merged into each calorimeter trigger tower. It is currently thought to be a task performed by the "geometry program". Typically around 300 MeV for EM and 600 MeV for HD. It can also be statistically evaluated on the actual signal. usage: fill common block variable ELEC_NOISE_SIGMA. used in the computation of prom lookup cuts. assignment checks: A member of an item should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, PHI, and CHANNEL. verification checks: Check that it falls in the range (0.0, 2.0). minimal: Yes 11. Input Energy Error ---------------------- section name : INPUT_ENERGY_ERROR definition : This error describes the departure of the input signal to the front end cards from the actual energy deposited in the calorimeter. This quantity represents the error of the incoming signal due to (1) amplitude error and (2) due to timing differences that cannot be compensated on the ctfe card (i.e. between towers of a same card and between EM and HD channels of a same tower) dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 1 <= PHI <= 32 CHANNEL = EM, or HD data type : Floating point real units : percent source : manually entered by the Trigger Manager, assisted by the statistical comparison between trigger energy signals and main acquisition. usage: fill common block variable INPUT_ENERGY_ERROR. used in the computation of the common block variable ADC_CNT_VS_RAW_E (ratio between energy deposited in the calorimeter and ADC counts) assignment checks: A member of an item should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, PHI, and CHANNEL. verification checks: Check that the value lies in the range [0.0, 10.0]. (upper bound may be changed.) minimal: Yes 12. Analog Input Scaling Factor ------------------------------- section name : ANALOG_INPUT_SCALING definition : This is the primary scaling of the analog signal received by the CTFE card from the BLS card. This scaling factor converts the deposited energy E to its transverse component Et assuming the vertex of the interaction was at the center of the detector (z=0). This signal (Et at z=0) is not yet corrected accordingly to the actual vertex position measurement made by the level 0 trigger. This signal (Et at z=0) is the quantity collected in the data block (after digitization and pedestal correction). In the current design of the calorimeter trigger, this factor is uniformly Sin(theta), where theta is the angle between the beam line and the trigger tower as defined by its geometric coordinates (defined above). Provision is made to also use this coefficient to have different energy scales in different parts of the detector (namely at high rapidity). This coefficient can also be used to compensate for error in the input energy scale from the BLS card. dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 1 <= PHI <= 32 CHANNEL = EM, or HD data type : Floating point real units : none = Gev of Et / GeV of E source : manually entered by the Trigger Manager assited by a specialized program. This scaling is implemented with resistors installed at the analog input of the CTFE card servicing the tower. usage: fill common block variable ANALOG_INPUT_SCALING. used in the computation of the common block variable ADC_CNT_VS_RAW_E (ratio between energy deposited in the calorimeter and ADC counts) assignment checks: A member of an item should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, PHI, and CHANNEL. verification checks: Check that the value lies in the range (0.0, 1.0]. minimal: Yes 13. Downloaded Bytes -------------------- section name : DOWNLOADED_BYTE definition : For each of the Electro-magnetic and Hadronic Trigger Tower these are the quantities that must be downloaded into the DAC circuitry of the CTFE cards in order to produce the ADC zero energy response targeted in item #14 below. Operational downloaded DAC bytes will never be zero due to the specification of the CTFE cards. This variable is also used as an implementation flag: A Trigger Tower is understood as implemented if and only if its DAC_BYTE is different from zero. In the LSM file, a value of 0 must be given for a particular Trigger Tower if it is unimplemented. dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 1 <= PHI <= 32 CHANNEL = EM, or HD data type : Integer units : none, typically 1..20 source : manually entered by the Trigger Manager. The downloaded byte can be roughly evaluated after observing the noise in the received BLS signal by making a large number of measurements of the ADC response. It probably can be more finely tuned after comparing the trigger's view of the calorimeter to the main acquisition readout for a large number of events. usage: fill common block variable DAC_BYTE. Directly accessible variable of the common block. defines implemented Trigger Towers. assignment checks: A member is considered defined if it is non-zero. All members should be specified. DOWNLOADED_BYTE is considered defined for CHANNEL TOT in a given tower if both CHANNEL EM and HD are defined for that tower. verification checks: Check that it falls in the range [0, 20]. Must be greater than 0 for a range contiguous and symmetric across zero, and zero elsewhere. minimal: Yes 14. ADC Zero Energy Response ---------------------------- section name : ADC_ZERESP definition : These are the responses of each ADC to a zero energy input from the BLS. Note that this number is also the remaining pedestal presented to the lookup proms. This also is the remaining pedestals affecting the First Level Trigger Data Block. The zero energy ADC response may be chosen to be zero if the gaussian noise in the detector and BLS electronics is small enough so that it is practical to make cuts well above the noise envelope. The zero energy ADC response may be chosen not to be zero if the positive and negative contribution of the noise must be summed to prevent a rectifier effect. dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 1 <= PHI <= 32 CHANNEL = EM, or HD data type : Integer units : ADC counts (typically 1/4 GeV of uncorrected Et) source : manually entered by the Trigger Manager. usage: fill common block variable ADC_ZERESP. Used to evaluate the downloaded byte. Used by ADC_CONVERSIONS.FOR Used by PROM_RESPONSES.FOR assignment checks: A member of an item should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, PHI, and CHANNEL. verification checks: Check that it falls in the range [0, 25]. minimal: Yes 15. Lookup Energy Scale Shift ----------------------------- section name : ENERGY_SCALE_SHIFT definition : For each quantity being looked up, this item defines the energy corresponding to one least count of the PROM output. The global scale at the end of the energy trees summing these quantities was specified in item #7 above. The local departures from the global scales are only practical to implement if they are in powers or sub-powers of 2 since the rescalings that need to be done before the end of the trees would be executed by bit shifting. Not all combinations of shifts are possible to implement. Shifts can only be made over complete geometric sectors in (eta,phi) handled by one of the Tier #1 CAT2 cards, and never over smaller subsections of such sectors. This comes from the fact that the routing of the partial sums between CTFE cards and Tier #1 CAT2 cards is performed by the front-end backplanes and not by individual cables as it is between tier #1 and Tier#2 or Tier #2 and Tier #3 or Tier #3 and total sums. For either EM or HD energy scales, the shifts for first and second lookups should be the same (especially if the second lookup is also and Et lookup). The scale is currently planned to be common for all looked up quantities and all trigger towers. However, provision is made to allow different energy scales for different quantities (e.g. Energy and Momentum), and for different eta ranges. But phi-dependency is not allowed since it would be limited to whole phi-quadrants by the hardware. dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 (CHANNEL,LOOKUP) = (EM,ET), (HD,ET), (EM,L2), (HD,L2), (TOT,PX), or (TOT,PY) data type : Integer units : Binary shift 0 = same scale as global, +1 = twice the scale, -1 = half the scale,... source : manually entered by the Trigger Manager. usage: fill common block variable LUQ_LOCAL_RESCALING. used by TOWER_THRESHOLD_TRANSLATION.FOR assignment checks: A member should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, the channel that is associated with the given lookup, and with PHI = 1. verification checks: Check that it falls in the range [-4, 4]. Check that it is the same for first and second lookups of the same tower. minimal: Yes 16. Lookup Transverse Energy Cut -------------------------------- section name : TRANSV_ENERGY_CUT definition : If the z-correction PROM lookup also implements a low energy cut dictated by physics considerations, this number is the corresponding minimum z-corrected Et energy below which the tower's contribution to the global summation (i.e. the PROM output) is zero. Only energy deposits with a z-corrected Et equal to or greater than this requested cut will be output by the PROM. The other cut implemented in the lookup PROMS is the "electronics noise suppression" (see items #8 and 10) which is fairly uniform in raw energy units but is scaled with sin(theta) and quickly becomes of small relative contribution when the rapidity increases. The energy cut eventually implemented in the PROM (item #19) will be the greatest of the two independent contributions of the electronics noise cut and the physics cut. The physics noise cut should typically dominate, except at (very?) low rapidity. The physics cut is currently planned to be common for all trigger towers. However, provision is made for allowing different cuts for different eta regions. Phi-dependency is not currently allowed. dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 (CHANNEL,LOOKUP) = (EM,ET), (HD,ET), (EM,L2), (HD,L2), (TOT,PX), or (TOT,PY) data type : Floating point real units : GeV of z-corrected Et. source : manually entered by the Trigger Manager. usage: fill common block variable TRANSV_ENERGY_CUT. used in the computation of prom lookup cuts. assignment checks: A member should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, and the channel that is associated with the given lookup, and with PHI = 1. verification checks: It should fall in range [0.0, 10.0] GeV. If it is 0, then the prom zeresp should also be 0. minimal: No 17. Final Fitting (Tweak) ------------------------ section name : FINAL_FITTING definition : This corrective coefficient complements the purely geometric considerations in the calculation of the PROM transfer coefficient (slope) to match any other contribution. There are two types of contributions that could contribute to the "tweak" in PROM lookup pages. The first contribution is the correction necessary to make up for the finite accuracy components in the BLS and in our analog front-end sections. This first contribution is independent of the lookup page and also independent of the quantity being looked up as long as it is expressed in percents. This first type of correction is preferably made on the input scaling factor, so that the output of the EM and HD ADCs can be properly added together to form the input to the Px and Py PROMs. The second type of contribution would include everything that could not be calculated with the simple geometry of the trigger tower (r,z=cte for all vertex positions). For example if the shower profile or tower sharing varying with the vertex position has enough of an influence on the energy readout. The relative contribution of factors of this second type has not been investigated. The hardware is however ready to make up for such contributions. The tweak is currently planned to be common for all the pages of one looked up quantity and one tower, but provision is made to allow different tweak for each page of each lookup and each trigger tower. dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 1 <= PHI <= 32 (CHANNEL,LOOKUP) = (EM,ET), (HD,ET), (EM,L2), (HD,L2), (TOT,PX), or (TOT,PY) -3 <= PAGE <= +3 units : Percent. source : Manually entered by the Trigger Manager. No first estimate of the tweak can be easily made, and the first value chosen for the tweaks will most likely be zero percent uniformly for all trigger towers and all looked up quantities. The adjustment of the tweak for fine tuning will be achieved by comparing the trigger's view of the calorimeter to the main acquisition readout over a large number of events. Note that this parameter will depend on the optimization criteria chosen for this program. usage: fill common block variable FINAL_FITTING. used in the computation of the PROM slopes. assignment checks: a member should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, PHI, and CHANNEL, and if in addition LOOKUP_QUANTITIES is defined for the same set of CHANNEL, LOOKUP, and PAGE. verification checks: It should fall in the range [-10.0, 10.0]. minimal: No 18. Lookup Zero Energy Response ------------------------------- section name : LOOKUP_ZERESP definition : For each quantity being looked up, the z-corrected quantity may be positively biased if it becomes necessary to prevent rectifier effect. This zero energy response will also become the remaining offset at the output of the lookup proms and thus must be taken into account when programming tower thresholds for EM Et or TOT Et quantities. The global sum of these biases over all towers must also be taken into account when programming global thresholds on energy sums. The global sum of these biases over all towers is also subtracted from the global energy sum to obtain the true global energy sum that will be included in the data block. Having a zero energy response different from zero seems only consistent with an ADC zero energy response being different from zero. However the reciprocal statement is not true, it would be possible to have an ADC zero energy response being different from zero, a Px and Py PROM lookup zero energy response different from zero but an EM and HD Et PROM lookup equal to zero: in such a case, the EM and HD Et lookup are used to remove the ADC offset that needed to be artificially introduced to allow the Px and Py lookup of negative input energies. Having a zero energy response different equal to zero seems only consistent with with making an energy cut in the PROM lookup different from 0. This quantity may not be constant over all trigger towers and may also depend on the quantity being looked up. However, in any case it MUST be constant for all lookup pages of a same quantity because the final correction cannot be dependent on the z-position of the vertex. dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 1 <= PHI <= 32 (CHANNEL,LOOKUP) = (EM,ET), (HD,ET), (EM,L2), (HD,L2), (TOT,PX), or (TOT,PY) data type : Integer units : z-corrected energy scale : typically 1/4 GeV source : manually entered by the Trigger Manager. usage: fill common block variable LOOKUP_ZERESP. Used to derive the common block variable TREE_OFFSET. Used by PROM_RESPONSES.FOR assignment checks: A member of an item should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, PHI, and CHANNEL. verification checks: Check that it falls in the range [0, 25]. If it is not 0, then the energy cut in the prom lookup should be 0. The converse of this is also true. The PROM zero energy response can be non-zero only if the ADC zero energy response is non-zero. minimal: Yes 19. PROM Output Minimum Energy Cut ---------------------------------- section name : PROM_OUTPUT_CUT definition : This quantity is computed from the maximum of the two contributions of the electronics noise cut (cf. item #8 and 10 above) and of the transverse energy cut (cf. item #16 above) . dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 1 <= PHI <= 32 PROM = EM_PROM, HD_PROM, PX_PROM, or PY_PROM 1 <= INDEX <= 8 data type : Integer units : quantum of corrected energy scale: typically 1/4 GeV source : compiled by the Lookup System Management utilities from: the electronics noise cut factor (item #8) the trigger tower electronics noise (item #10) the input energy error (item #11) the prom slope (item #20) the transverse energy cut (item #16) the global energy scale (item #7) the lookup local rescaling (item #15) usage: fill common block variable PROM_CUT. used by PROM_RESPONSES.FOR assignment checks: A member should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, PHI, and the channel that is associated with the selected PROM. verification checks: A check can be made comparing the values given in this section to values re-compiled from the other values in the file. minimal: Yes 20. PROM Slope -------------- section name : PROM_TRANSFER_COEFF definition : This parameter describes the contribution of the geometry of the trigger tower (see item #9) and of the nominal center of each lookup page (item #5) to the slope of the PROM's transfer function. The slope of the PROM's transfer function also takes into account the tweak specified in item #17. dimensions : SIGN_ETA = POS or NEG 1 <= MAGN_ETA <= 20 1 <= PHI <= 32 PROM = EM_PROM, HD_PROM, PX_PROM, or PY_PROM 1 <= INDEX <= 8 data type : Floating point real units : none = GeV of z-corrected quantity / GeV of non-z-corrected Et source : compiled by the Lookup System Management utilities from: the lookup types (item #2) the lookup page nominal center (item #5) the trigger tower geometry (item #9) the final fitting (item #17) usage: fill common block variable PROM_SLOPE. used by PROM_RESPONSES.FOR assignment checks: A member should be defined if DOWNLOADED_BYTE is defined for the same set of SIGN_ETA, MAGN_ETA, PHI, and the channel that is associated with the selected PROM. verification checks: A check can be made comparing the values given in this section to values re-compiled from the other values in the file. minimal: Yes Messages -------- The following are messages generated by the Lookup System Manager Program. The number in brackets listed with some of the following error messages is the code returned by the Lookup System Manager Object Library Routines when they detect that error. Messages produced from the main menu of the Lookup System Manager Program ------------------------------------------------------------------------- File successfully loaded An LSM file has been successfully loaded into memory. Any of the operations may be performed now. No file loaded File not successfully loaded An LSM file has not been successfully loaded into memory yet. The only operation that may be performed currently is `Load LSM File.' File and memory contents updated The operation `Update LSM File' has been performed. The contents of memory now reflect the contents of the updated LSM file that has been written. Messages produced during the operations Load LSM File and Verify LSM File ------------------------------------------------------------------------- [1] No values specified for item No values were assigned to the given section in the LSM file. [2] The following members were not specified The given members of the section should have had a value assigned to them, but did not have one assigned. [3] General Error This error should always occur with further explanation in the error message. It should not occur as a numeric error code. [4] A member was specified when it should not have been A member of the section should have been left undefined, but a value was given to it. [5] General Verification Check Error This error should always occur with further explanation in the error message. It should not occur as a numeric error code. [6] Value out of range The value assigned to the specified member is not within the range valid for that section. Refer to the description of individual sections for the specification of valid values for each section. [7] Range not contiguous The positions given to each value of this section should form a contiguous range. [8] Range not symmetric The values given for this section should be symmetric around the midpoint of the coordinates. [9] HD value is smaller than EM value The value given for a particular coordinate with CHANNEL HD should be larger than the value given for the same coordinate with CHANNEL EM. [10] TOT value does not lie between EM and HD values The value given for a particular coordinate with CHANNEL TOT should lie between the values given for the same coordinates with CHANNEL EM and CHANNEL HD. [11] Range not constant over ETA The values should be constant over a particular subrange of ETA. [12] Range not decreasing The values should be decreasing over a particular coordinate range. [13] Range not increasing The values should be increasing over a particular coordinate range. [14] Range not constant over PHI The values should be constant over PHI. [15] Value not within tolerance in relation to other members The magnitude of the values in this section should each be within a certain percentage of the magnitude of the other values. [16] Contents in TRANSV_ENERGY_CUT imply that a member should be 0 The value at the same coordinate in TRANSV_ENERGY_CUT indicates that the given member should be 0. See the description of the particular section for more information. [17] Contents in TRANSV_ENERGY_CUT imply that a member should not be 0 The value at the same coordinate in TRANSV_ENERGY_CUT indicates that the given member should not be 0. See the description of the particular section for more information. [18] Contents in ADC_ZERESP imply that a member should be 0 The value at the same coordinate in ADC_ZERESP indicates that the given member should be 0. See the description of the particular section for more information. [19] Open on file failed The LSM file could not be opened [20] Read on file failed An IO error occured while reading from the file [21] Expected a NUMBER, found: A NUMBER was expected in the current context of the file. [22] Invalid integer value: Either the value given is not within the range valid for the particular variable, or the second value of a range is less than the first value of a range. [23] Expected AND, TO, or END_OF_LINE, found: [24] Expected AND or END_OF_LINE, found: [25] Expected PLUS or MINUS, found: One of the given strings was expected in the current context. [26] Invalid range: Either the value given is not within the range valid for the particular variable, or the second value of a range is less than the first value of a range. [27] Expected TO, found: [28] Expected EM, HD, or TOT; found: [29] Expected ET, L2, PX, or PY; found: [30] Expected EM_PROM, HD_PROM, PX_PROM, or PY_PROM; found: One of the given strings was expected in the current context. [31] END_WITH without a corresponding WITH An END_WITH statement was found that had no corresponding WITH statement. [32] WITH block without an item assignment A WITH block was encountered that did not contain any item assignments. [33] Unclosed WITH statement before END_SECTION An END_SECTION statement was encountered when there were still open WITH statements. [34] SECTION block without an item assignment A SECTION block was encountered that did not contain any item assignments. [35] Expected END_OF_LINE, found: An END_OF_LINE was expected in the current context. [36] Program error in routine TRANSFORM_RANGE Internal consistency check failed in that routine. Should not occur. [37] Have already specified all valid variables before LIST statement All integer variables have been specified when the LIST statement occurs. Only integer variables may be used in a LIST statement, and there are none left to specify. [38] Have not specified all non-integer variables before LIST statement Non-integer variables may not be used in a LIST statement, and so must be specified prior to the LIST statement. [39] Expected VARIABLE or END_OF_LINE, found: One of the given strings was expected in the current context. [40] Variable not valid in current section: The given variable is not valid in that section. [41] Variable has already been specified: The given variable has already been specified in an enclosing block. [42] Program error in routine PARSE_REMAINING_VARIABLES [43] Program error in routine BUILD_SECOND_STACK Internal consistency check failed in that routine. Should not occur. [44] Attempting to specify too many variables All of the variables have already been specified. [45] Expected a VARIABLE, found: Expected a VARIABLE in the current context. [46] Invalid combination of CHANNEL and LOOKUP: Only certain combinations of values for CHANNEL and LOOKUP are valid in the current section. [47] CHANNEL TOT not valid The value TOT is not valid for the variable CHANNEL in the current section. [48] Program error in routine PARSE_WITH [49] Program error in routine PUSH_VAR, attempt to increase stack beyond bounds [50] Program error in routine PULL_VAR, attempt to decrease stack beyond bounds Internal consistency check failed in that routine. Should not occur. [51] Expected an enumerated value, found: [52] Expected END_LIST, found: [53] Expected WITH, LIST, END_WITH, END_SECTION, or ASSIGN; found: Expected the given string in the current context. [54] Program error in routine PARSE_SECTION Internal consistency check failed in that routine. Should not occur. [55] Not all variables have been specified An assignment statement occured when there were still variables left to specify. [56] Member of item redefined in assignment A value is being assigned to a coordinate of a section that has been assigned to previously. [57] Expected SECTION or END_OF_FILE, found: [58] Expected a section name, found: Expected the given string in the current context. [59] Program error in routine DISPATCH Internal consistency check failed in that routine. Should not occur. [60] Cannot derive quantities: GLOBAL_ADC_SCALE is 0 Several quantities need to be derived from contents of the LSM file. This cannot be done if the value of GLOBAL_ADC_SCALE is 0. Loading file: The program is attempting to load the file with the given name File successfully loaded The program successfully loaded the LSM file File not successfully loaded The program did not successfully load the LSM file ## messages generated. Do you want to view the messages? ## messages were generated by the previous operation. All messages produced during the loading of an LSM file or the verification of an LSM file are written to a file. This is asking whether or not to display them using the EVE editor. Creating subprocess... The EVE editor is being called to display messages. Additional messages produced during the operation `Verify LSM File' ------------------------------------------------------------------- The boundaries on the following two Level 0 bins do not match: The upper boundary of a Level 0 bin must be the same as the lower boundary of the next higher bin. The boundaries on the following Level 0 bin are out of order: The upper boundary of a bin must be a larger number than the lower boundary of that bin. Width of Level 0 bin #0 is out of range. The width of bin #0 must fall within a certain range. See the description of the sections L0_BINS_HIGH and L0_BINS_LOW. Error: Width of Level 0 bin # ? is out of range with respect to bin #0. The width of each bin must be within a certain percentage of the width of bin #0. Level 0 bin #0 is not centered Bin #0 must be centered on 0.0, within a certain percentage tolerance. Member out of order in section LOOKUP_QUANTITIES: The indices assigned to each page must be monotonically increasing. The following 2 members of section LOOKUP_QUANTITIES are not equal: Certain pairs of lookups need to be assigned identical indices for each page. See the description of section LOOKUP QUANTITIES for a list of these pairs. The following two members not equal: Hardware constraints require that there exist certain symmetries in the data. Check the description of the appropriate section for more information. The following members of section LOOKUP_QUANTITIES overlap: One index of a PROM has been assigned to more than one lookup page. Lookup #1 is DEPOSITED_ENERGY, and should have only 1 page assigned to it. Lookup #2 is DEPOSITED_ENERGY, and should have only 1 page assigned to it. Deposited energy lookups do not need to be corrected for vertex position, so it doesn't make sense to use more than 1 page for that lookup. Member out of order in section PAGE_VS_BIN: The PAGEs assigned to the BINs must increase as the BINs increase. BIN 0 not within PAGE 0 in section PAGE_VS_BIN: Level 0 bin #0 (being the center of the detector) must be assigned to page 0 of every defined lookup. Invalid page given in section PAGE_VS_BIN: The value assigned to the given member does not fall in the range [-3,3]. Page not specified in section PAGE_VS_BIN: The given page has been defined in the section LOOKUP_QUANTITIES, but has not been assigned to a bin. Page center does not fall within page boundaries in section PAGE_NOMINAL_CENTER: The location for the page given in PAGE_NOMINAL_CENTER does not fall within the bin boundaries specified by PAGE_VS_BIN, L0_BINS_HIGH and L0_BINS_LOW. Page center not centered within tolerance in section PAGE_NOMINAL_CENTER: The page center given in PAGE_NOMINAL_CENTER should fall on the center of the bins given by PAGE_VS_BIN, L0_BINS_HIGH and L0_BINS_LOW, within a certain tolerance. Section PROM_TRANSFER_COEFF does not agree with other data in file that it is compiled from. The data in PROM_TRANSFER_COEFF is normally created by compiling it from data in other sections of the LSM file. This message was produced because recompiling the data does not produce the same information for PROM_TRANSFER_COEFF as is in the LSM file. Possibly, data in the other sections has been changed, and now the LSM file needs to be updated using the `Update LSM File' operation of the Lookup System Manager Program. Section PROM_OUTPUT_CUT does not agree with other data in file that it is compiled from. The data in PROM_OUTPUT_CUT is normally created by compiling it from data in other sections of the LSM file. This message was produced because recompiling the data does not produce the same information for PROM_OUTPUT_CUT as is in the LSM file. Possibly, data in the other sections has been changed, and now the LSM file needs to be updated using the `Update LSM File' operation of the Lookup System Manager Program. No LSM file loaded. Cannot proceed. This operation cannot be performed without first loading an LSM file. No checks selected. No action is performed because no checks were selected to be performed Performing selected checks. The checks selected in the previous menu are being performed. Messages generated during the operation `Update LSM File.' ---------------------------------------------------------- Cannot proceed without a file loaded A file must be successfully loaded using the `Load LSM File' operation prior to performing any other operation. Reading from file: The data for the non-updated sections of the new LSM file are being read from the stated file. Writing to file: The new LSM file contents are being written to a file of the given name. Cannot open the file: The given file could not be opened. File and memory contents updated Writing the file was successful. The contents of memory now reflect the updated data. Messages generated during the operation `Build PROM File' --------------------------------------------------------- Cannot proceed without a file loaded No other operations can be performed until a file has been successfully loaded using the `Load LSM File' operation. No files to make. Neither binary nor Intellec files were selected to be created, so no operation is performed. Invalid PROM type. The value given for PROM type was not one of EM, HD, PX, or PY. ETA value out of range. The value given for the ETA coordinate is not in the range +/-[1,24]. PHI value out of range. The value given for the PHI coordinate is not in the range [1,32]. Could not create binary file: Could not create Intellec file: The given file could not be created. Writing binary file: Writing Intellec file: The given file is currently being written. Messages generated during the operation `Simulation Routines' ------------------------------------------------------------- Cannot proceed without a file loaded No other operations can be performed until a file has been successfully loaded using the `Load LSM File' operation. ETA value not in range. The value given for the ETA coordinate is not in the range +/-[1,24]. PHI value not in range. The value given for the PHI coordinate is not in the range [1,32]. Level 0 bin number out of range. The value given for the Level 0 bin is not in the range [-15, 15]. EM byte out of range HD byte out of range The specified byte is not in the range [0, 255].