BES software note # 5 SOBCARD A Guide to SOBER Runcards Version 1.0 Prepared by WANG Taijie and XU Rongsheng Feb 1989 Version 2.0 Updated by Michael KELSEY November 1993 Version 2.1 Updated by Derrick Kong May 1998 This module describes the runcard formats for the BES Monte Carlo (SOBER -- Simulation Of BEijing spectrometeR). The runcard file is used as input to both the Monte carlo executable image as well as the command procedure SOBER. CHAPTER 1 INTRODUCTION The BES Detector Simulation, SOBER, is controlled in individual user jobs by a run control file containing physics simulation parameters, detector configurations, and output data controls. This file, called the 'SOBCARD' file, may have any name the user wishes to assign, but must have a filetype of 'SOBCARD'. The file may be upper-, lower-, or mixed-case at the user's discretion. This note describes the format and syntax of the SOBCARD file. It is divided into 3 main sections plus an appendix: An introductory section containing general background material. It should be read once by all first time users. Detailed reference manual sections describing all current SOBER command procedure and runtime control cards. Some sample runcard files and their description. A description of how the runcard keywords are defined, and how to add new keyword definitions to SOBER. Appendix A contains a summary of all runcard formats. CHAPTER 2 GENERAL DESCRIPTION The runcard file contains all of the input data needed to run a SOBER job. The runcard file is a Fixed or Variable format file with a maximum record length of 133. The filetype must be 'SOBCARD'. The text within the file may be upper or lower case at the discretion of the owner. 2.1 PURPOSE The runcard file serves two purposes, the obvious one is to supply the input needed to run a program. The second is to document what went on in the job, most importantly the nature of the output data set. To this end the runcard file appears as part of the normal printed output and as part of the output data set itself. In this way the runcards which created the MC data set are available later as a reminder of the contents and nature of the data. SOBER runcards provide access to some 200 different variables and program options which can effect the way data is generated. By setting these parameters through runcards, which are never separated from the data set (rather than through data/assignment statements in routines which are not part of the data) the system provides a level of built in self documentation. Since SOBER contains many parameters which can vary slightly or grossly the nature of the generated data this is not a trivial point. 2.2 NOTATION In the descriptions which follow in the next section we will use some familiar syntactic symbols to describe the formats of the runcards. It should be noted these symbols are NOT part of the card itself. GENERAL DESCRIPTION Page 2-2 13 May 1998 Angle brackets, < >, are used to indicate a value or quantity to be supplied by the user, such as a string or a number. Square brackets, [ ], are used to indicate optional material. A vertical bar, "|", is used to separate alternatives in a list. An ellipsis, ..., is used to indicate multiple occurrences of a quantity (i.e., a list). 2.3 TYPES OF RUNCARDS There are two basic types of records in the SOBCARD file which we'll call 'CP'(Command Procedure) control cards and 'RUNTIME' control cards. The runcard file is read twice during a job; once by the command procedure SOBER and once by the running executable named by the name of SOBCARD file. The first time it is scanned by the SOBER command procedure for records with a '*' in column 1. (This is the only column restrictive format in the runcard file.) These are the CP cards which contain information and options needed merely to run the job. 2.3.1 Command Procedure Control Cards CP control cards contain instances of: The name of the output data set to be written if any. The names of additional OBJ files to be linked. The names of additional DATA files to be loaded. For a full description of the 'CP' control card formats refer to the next section of this note. 2.3.2 Runtime Control Cards The second time the file is scanned by a SOBER routine for 'RUNTIME' control cards. (Any record not containing a '*' in column 1). GENERAL DESCRIPTION Page 2-3 13 May 1998 It is those cards which are the subject of the Section 3 of this document. In general these cards control various program parameters which determine how the program will run and the nature of the output data. These cards contain instances of: Run related parameters such as energy, number of events. A description of the events to generate. System specific parameters such as resolutions, dead channels, noise levels, efficiencies,etc. Assorted program 'convenience' features. 2.4 GENERAL SYNTAX 2.4.1 Logical Cards In the descriptions we will refer to logical "cards" as opposed to physical records (lines of the file). A logical card may consist of a complete record or a portion of a record terminated with a semi-colon (';'). A "card" consists of on e or more key words followed by a list of 0 or more tokens (parameters or values). The terminator is required between multiple logical cards combined in a single record. Otherwise, the end of the physical record indicates termination of a card. 2.4.2 Tokens (Parameters) Tokens consist of comments, integer numbers, floating point numbers and character strings. Character strings may be quoted or unquoted depending on whether blanks are to be part of the string. Numbers may also be represented by what we call here a 'radix-string'. That is a quoted string with a trailing character indicating the radix, for example 'ff'x = '11111111'b = 255. The standard radix strings are '..'x for hex, '..'o for octal, '..'b for binary. Tokens may not span records and are in general separated by blanks or commas. An '=' sign may be used to separate a key-word from a token. The choice is one of personal preference. 2.4.3 Key-words Key-words are the "reserved" words of the runcard system which convey special meaning to the reading routines. GENERAL DESCRIPTION Page 2-4 13 May 1998 In the descriptions key-words are indicated in UPPER case for clarity. They may of course appear in any case in the actual file. Input keys may be abbreviated provided the abbreviation allows for a unique match between the input the and the actual key. Caution: The addition of new runcards to the systems may render a previous legal abbreviation ambiguous. 2.4.4 Comments Comments may appear anywhere a blank or other separator would. They may also span records. They merely serve to document. Comments have the format /* this is a comment */ 2.4.5 Special Convention Certain key-words cause arrays to be filled with the values following it. The filling normally begins at the first location of the array. This could be tedious if one merely wants to fill the last location of a 200 word array. To remedy this certain key-words allow a FORTRAN-like array index to be specified immediately after the key-word pointing to the first location of the array to be filled. Example: The XPARAM card fills the array XPARAM in common /CMODEL/. The following card will fill 3 locations in XPARAM starting at XPARAM(5): XPARAM(5) = 1.234,0.5E-06, 3.14159 ; CHAPTER 3 COMMAND PROCEDURE CONTROL CARDS The 'CP' (command procedure) control cards provide information and control to the SOBER command procedure. There are two different sets of CP control cards, one set for VAX and Unix job, and one set for SLACVM jobs. All CP cards must start on column 1 with '*' sign, and fields must be separated by blanks or tab characters. 3.1 GENERIC CP CONTROL CARDS 3.1.1 *LOGOUT DISK|TAPE See *OUTPUT DISK or *OUTPUT TAPE. 3.1.2 *OUTPUT DISK This card indicates the disk place of output data file, where is the full file name, including disk and directory. Default is the current directory or subdirectory. 3.1.3 *OUTPUT TAPE This card shows that the output data are using tape. indicates the tape serial number, file number, and a name for the tape file. 3.1.4 *SOBDICT This card replaces the standard SOBER runtime dictionary file SOBDICT.CAR with the one located in for VAX and Unix jobs. For SLACVM jobs, COMMAND PROCEDURE CONTROL CARDS Page 3-2 13 May 1998 should be replaced with the filename of an alternate CAR file to be read as the dictionary. (See the chapter on defining new dictionary entries.) 3.2 VAX/UNIX ONLY CP CONTROL CARDS 3.2.1 *BESGEOM indicates the disk name and the directory or subdirectory where the constants file BESGEOM.DAT is located. Default is using the standard file which is in BES group constant set. 3.2.2 *BES$CON indicates the disk name and the directory or subdirectory where the constants files, '*.SOBECONS', are placed. Default is using the standard files which are in BES group constant set. 3.2.3 *DEFINE Defines a VMS logical name. This card uses the identical syntax to the VMS DEFINE command, and may include any valid qualifier to that command. The name will be assigned the specified in the PROCESS logical name table. This card has no effect in Unix jobs. 3.2.4 *HBOOK When you use HBOOK to do event statistics, the output file (.HBK file) is placed in a disk file named . 3.2.5 *LINK The obj's are names of the additional OBJ file which are to be linked by DRUNK frame. Default means linking only one Obj file which name is as same as your DRKCARD's name. Usually, user should link at least one Obj file which contains the window subroutines BESEVN, BESIOR, BESEOR and so on. Any argument valid with the VMS LINK command may be used here, include /LIB or /OPT to specified libraries or options files. The *LINK card may be repeated multiple COMMAND PROCEDURE CONTROL CARDS Page 3-3 13 May 1998 times. 3.2.6 *MESSAG indicates the disk name and the directory or subdirectory where the message file MESSAGE.DAT is found. Default is using BES group message file. 3.3 VAX AND UNIX CP CONTROL CARDS 3.3.1 *EVT_GEN This card indicates the name of the Monte Carlo event generator to be used. Only one *EVT_GEN card may appear in the user's SOBCARD file. If multiple cards appear, only the first one will have any effect. See the Runtime Control Card EVT_TYPE for a list of valid BES generator names. 3.3.2 *SHO_GEN This card indicates the name of the shower counter simulation routine to be used. Currently, only EGS is available as a shower generator, and this card is ignored. 3.3.3 *TEXT ... This card indicates one or more additional user object files ( TEXT) to be loaded with the job. It is analogous to the VAX/Unix *LINK card. 3.3.4 *FILEDEF 3.3.5 *HEADER This card specifies a message data file to be printed at the beginning of the user's SOBER execution. It is analogous to the VAX/Unix *MESSAG card. COMMAND PROCEDURE CONTROL CARDS Page 3-4 13 May 1998 3.3.6 *BLOCKDATA This card specifies a pre-compiled (* TEXT) file containg a BLOCK DATA routine to be loaded for initialization. The default is INIT. 3.3.7 *GLOBAL ... This card specifies additional libraries (* TXTLIB) to be searched during loading for external references. It is analogous to the VAX/Unix *LINK card with an "/LIB" argument. 3.3.8 *SUBMIT ... This card forces the SOBER job to be submitted in BATCH mode, with all the passed as options to the BATCH SUBMIT command. SOBER will automatically generate a SOBSUB EXEC file to be submitted to the batch system. CHAPTER 4 RUNTIME CONTROL CARDS This part of the document is intended as a reference manual for runtime control cards. The sections which follow are organized as much as possible by logical function of the various cards. 4.1 JOB CONFIGURATION OPTIONS 4.1.1 Global Job Control The following set of cards plus a subset of event definition cards constitutes the minimal set of runcards required to run a job. 4.1.1.1 Comment Card Comments are marked at their beginning and end by '/*' and '*/' strings: /* */ A comment may appear any where in the file, either on a line by itself, or as part of a line mixed with keywords and values. The comment behaves like a separator (blanks). Comments must begin and end on the same line of the file; an unclosed comment is automatically closed when the physical end-of-record is reached. 4.1.1.2 END Multiple "runs" may be generated from 1 runcard file set. The 'END' card is used to mark the end of a set of cards. It is required as the last card in a set of cards. Cards for the next "run" will be assumed to start with the next record of the file. RUNTIME CONTROL CARDS Page 4-2 13 May 1998 4.1.1.3 RUN Specifies the run number to be assigned to the next generated dataset, where is a negative integer. In BES, all Monte Carlo run numbers are negative so they may be distinguished from real data. The will be set negative if it is not specified so. 4.1.2 Event Loop Control SOBER will keep track of time remaining in a BATCH job so that it may exit gracefully before time expires. SOBER is also set up to respect the JOBSTOP protocol. 4.1.2.1 ECM The center-of-mass energy of each event must be specified for generators which allow continuum simulation. Here, is a real number indicating the CM energy in GeV. This card is not required when using event generators which either define the CM energy or do not require it. (e.g., TESTER). 4.1.2.2 ENDTIME A real number (in seconds) which will be reserved at the end of the job to allow for histogram output or any such tasks. (i.e., SOBER will wind down if fewer then seconds remain for the running batch machine.) This card only applies for batch jobs. The default time limit is 5 seconds. 4.1.2.3 NEV The number of events to generate in this run. If NEV is not specified the program will assume 0 and do nothing. 4.1.2.4 NEVTIM An integer number of events. The CPU clock will be checked after every -th event. Since the clock test may be time intensive itself one can decrease the cost by checking less frequently (i.e., increase ). The default is 10 events. RUNTIME CONTROL CARDS Page 4-3 13 May 1998 4.1.2.5 RANDOM The random number generators RAN6, RAN7, and RAN9 are initialized with the integer seed values given in , , and , respectively. The SOBER random number system provides for event reproducibility by storing a master random seed from which all other random numbers are generated. In brief, RAN6 is used for the event generator, RAN7 for tracking and RAN9 for detector hitting. At the end of a job SOBER prints out the value of the next random seeds in the sequence so that one may use them as the initial seeds for another run. 4.1.3 Event Generation There are several different event generators available in sober. Some for doing physics, some for simple track generation. Their functions are described in BES software note 7 -- EVENTGEN. Most generators are configured by filling standard arrays in the common block /CMODEL/. A real array, XPARAM(20), and an integer array, MPARAM(20), are available for different kinds of parameters. The format of the data expected is usually explained in the comments for the generator routine. See the section on "Syntax" for detailed information on filling arrays. 4.1.3.1 EVT_TYPE For VAX and Unix jobs, selects the event generator to be used for the next dataset, where is an integer value indicating the event generator to be called. The correspondence between event types and names of event generators are as follows. event-type name of generator 1 HOWL 2 P2MUMU 3 RHOPI 4 SAGERX 5 TESTER 6 P2EPEM 7 EPSCAT (BHABHA) 8 FFF 9 DDPROD 10 KSTARK 11 TAUPRD 12 RADEE RUNTIME CONTROL CARDS Page 4-4 13 May 1998 13 RADGG 14 LUND 15 UGNT 16 P2BB 17 DSSGEN 18 FFGEN 19 FSFGEN 20 BHAGEN 21 DDGEN 22 DSDGEN 23 MUGEN 24 GAMMA2 25 PPGEN 26 RADMU 27 FERMISV 28 (unused) 29 (unused) 30 KORALBE Some generators need control parameters which can be defined by SOBER runtime cards. They are explained in note 7 -- EVENTGEN. Only a list of them is given here. AUTODECAY CHRG_TRKS DECAY GAMMA KSHORT|KLONG MPARAM NEUT_TRKS RESONANCE XPARAM 4.1.3.2 MPARAM [()] Fills values in the /CMODEL/ array MPARAM(20). The is a FORTRAN array index and must be a positive integer. If is not supplied 1 will be assumed. The parameters is a list of 1 to 20 integer values. 4.1.3.3 XPARAM [()] Fills values in the /CMODEL/ array XPARAM(20). The is a FORTRAN array index and must be a positive integer. If is not supplied 1 will be assumed. The parameters is a list of 1 to 20 real tokens. 4.1.4 Extra Track Generation The following cards control the generation of non-event related tracks in the event. Theses extra tracks will be generated at the end of normal event generation. RUNTIME CONTROL CARDS Page 4-5 13 May 1998 Note Currently there is neither stray nor cosmic track generation available. 4.1.4.1 X_COSMIC Generate an average of "cosmic ray" (infinite momentum, straight) tracks per event. The average may be less than 1.0. If 0. is specified (the default) no extra tracks will be generated. 4.1.4.2 X_STRAY Generate an average of "stray" (low moentum, curving) tracks per event. The average may be less than 1.0. If 0. is specified (the default) no extra tracks will be generated. 4.1.5 Rawdata Generation 4.1.5.1 EGS_ON|EGS_OFF Card The EGS_ON and EGS_OFF cards indicate whether EGS code is called for shower simulation. When EGS_ON is set, EGS initialization (HATCH) is done, then EGS is called to simulate the behavior of electrons and gammas in the shower counter region. When EGS_OFF is set, EGS does not work at all, electrons behave like muons in the shower counter and SOBER may crash if a gamma enters the shower counter!!! So EGS_OFF should be used very carefully. An alternative shower generator using parameterization method is expected to work sometime. 4.1.5.2 GEN_MASK The integer will be interpreted as a mask indicating which type of data should be generated by SOBER. Setting a particular bit forces the specified type of data to generated: Bit 0 ('001'B) = Generate raw (detector) data. Bit 1 ('010'B) = Generate MC (physics) data. Bit 2 ('100'B) = Generate TRKLST (reconstructed) data. Since reconstruction requires raw data, setting bit 2 automatically sets bit 0 as well. The individual bits can also be set with the commands: RAWDATA, MCMADE and RECON, and turned off with NORAWDATA, NOMCMADE and NORECON. The default setting is '011'. RUNTIME CONTROL CARDS Page 4-6 13 May 1998 4.1.5.3 LOG_MASK The integer will be interpreted as a mask indicating which type of data should be logged out. Data will not be logged unless it has been generated. Bit 0 ('001'B) = Write raw (detector) data. Bit 1 ('010'B) = Write MC (physics) data. Bit 2 ('100'B) = Write TRKLST (reconstructed) data. The individual bits can also be set with the commands: LOGRAW, LOGMCM and LOGREC, and turned off with NOLOGRAW, NOLOGMCM and NOLOGREC. Also the command NOLOG will turn all logging off (i.e. it's equivalent to LOG_MASK '000'B.) The default setting is '111'. 4.1.5.4 N_CIRC SOBER does a primitive circle fit on the generated drift chamber hits with appropriate spatial resolution to determine the measured momentum of charged tracks. The fit does not produce an error matrix. is an integer specifying the number of iterations for the circle fit algorithm. If = 0, no circle fit will be done. The default is 10. 4.1.5.5 RAW_MASK The integer will be interpreted as a mask indicating which raw data subtypes should appear in the raw data record: Bit 0 ('0000000001'B) = Time of flight Bit 1 ('0000000010'B) = Central Drift Chamber Time TACs Bit 2 ('0000000100'B) = CDC Charge TACs Bit 3 ('0000001000'B) = Trigger Bit 4 ('0000010000'B) = Main Drift Chamber TACs Bit 5 ('0000100000'B) = MDC Pulse Height SHAMs (dE/dx) Bit 6 ('0001000000'B) = MDC Induced Pulse SHAMs (Z pos) Bit 7 ('0010000000'B) = Barrel Shower Counter Bit 8 ('0100000000'B) = Endcap Shower Counter Bit 9 ('1000000000'B) = Muon Tracking 4.1.5.6 TRIG_ON|TRIG_OFF These cards control the override of the trigger simulation routine. The trigger simulator normally determines whether an event would have triggered and hence be logged out. RUNTIME CONTROL CARDS Page 4-7 13 May 1998 The TRIG_OFF card will effectively disable the trigger. The trigger will still be generated; however all events will be logged out regardless of the trigger decision for the event. The TRIG_ON card enables trigger control of event logging which is currently the default mode. Note Currently there is no trigger simulation routine available. Hence TRIG_OFF must be included in the SOBCARD file. 4.1.6 Print Control Options The following cards control the amount and nature of standard SOBER output. Much of the output is useful for first time users or for debugging purposes. 4.1.6.1 PRT_MCPRT Routine MCPRT will be called for the first events to provide a formatted dump of the MCMADE data record. The format is similar to EVPRT output in the off-line. 4.1.6.2 PRT_NOISE The random noise hits generated for various subsystems will be printed out for the first events. This is mainly a debugging tool. 4.1.6.3 PRT_PTS A track-by-track detail will be given for the first events. The output will include the drift times generated along the track, energy deposited in the shower chamber(s), TOF information and muon hits. While useful for debugging this output is not for production running. The default value is 0. Note Currently there is no noise simulation routine available. RUNTIME CONTROL CARDS Page 4-8 13 May 1998 4.1.6.4 PRT_RANDOM The three random seeds for the event will be printed for the first events. 4.1.6.5 PRT_SUM A brief event summary including track-id's and 4-vectors will be printed for the first events. 4.2 USER DEFINED ROUTINES SOBER may call up to 7 user supplied routines as part of a normal job. These routines must be declared SUBROUTINEs, must begin with "SBUS" followed by a three letter code indicating the purpose of the routine (as given below), and must have the appropriate arguments declared. The calling sequence for each routine is indicated in the section heading. 4.2.1 SBUSIOJ -- Initialization Of Job SBUSIOJ is called immediately before the runcard file is read but after all SOBER initialization sequences as an user entry for his(her) own initialization of the whole job. 4.2.2 SBUSIOR(IRUN,IORARG()) -- Initialization Of Run SBUSIOR may be called at the start of each new run, with the run number as the first argument, and an array of up to 10 user parameters (real or integer) as the second. The SBUSIOR card can be used to advantage when developing/testing new code for the MC. The argument list provides a convenient way of passing in parameters to control the users' special requests. 4.2.2.1 IOR_ON|IOR_OFF The IOR_ON and IOR_OFF cards control the calling of the user routine 'SBUSIOR'. The default is OFF. RUNTIME CONTROL CARDS Page 4-9 13 May 1998 4.2.2.2 IORARGS The IORARGS card supplies a list of 1 to 10 integer or real numbers which will be passed to SBUSIOR as the second argument of the call. 4.2.3 SBUSIOE(IRUN,IOEARG()) -- Initialization Of Event SBUSIOE will be called at the start of each event for user's initialization of the event, with the run number as the first argument, and an array of up to 10 user parameters (real or integer) as the second. The SBUSIOE card can be used to advantage when developing/testing new code for the MC. The argument list provides a convenient way of passing in parameters to control the users' special requests, e.g., to clear the data arrays of user routine event by event. 4.2.3.1 IOE_ON|IOE_OFF The IOE_ON and IOE_OFF cards control the calling of the user routine 'SBUSIOE'. The default is OFF. 4.2.3.2 IOEARGS The IOEARGS card supplies a list of 1 to 10 integer or real numbers which will be passed to SBUSIOE as the second argument of the call. 4.2.4 SBUSEVN(IEVT,EVNARG()) -- Event Analysis SBUSEVN will be called after the filling of RAWDAT and MCMADE so that it could be used for analyzing this data, with the event number within the run as the first argument, and an array of up to 10 user parameters (real or integer) as the second. The SBUSEVN card can be used to advantage when developing/testing new code for the MC. The argument list provides a convenient way of passing in parameters to control the users' special requests. RUNTIME CONTROL CARDS Page 4-10 13 May 1998 4.2.4.1 EVN_ON|EVN_OFF The EVN_ON and EVN_OFF cards control the calling of the user routine 'SBUSEVN'. The default is OFF. 4.2.4.2 EVNARGS The EVNARGS card supplies a list of 1 to 10 integer or real numbers which will be passed to SBUSEVN as the second argument of the call. 4.2.5 SBUSDBG(IEVT,DBGARG()) -- Debugging SBUSDBG which may be called at the bottom of the event generation loop in the main routine, with the event number within the run as the first argument, and an array of up to 10 user parameters (real or integer) as the second. The routine is called right after SBUSEVN, users may use it separately for debugging print out. The SBUSDBG card can be used to advantage when developing/testing new code for the MC. The argument list provides a convenient way of passing in parameters to control the users' special requests. 4.2.5.1 DBG_ON|DBG_OFF The DBG_ON and DBG_OFF cards control the calling of the user routine 'SBUSDBG'. The default is OFF. 4.2.5.2 DBGARGS The DBGARGS card supplies a list of 1 to 10 integer or real numbers which will be passed to SBUSDBG as the second argument of the call. 4.2.6 SBUSEOR(IRUN,EORARG()) -- End Of Run SBUSEOR will be called at the end of each run, with the run number as the first argument, and an array of up to 10 user parameters (real or integer) as the second. RUNTIME CONTROL CARDS Page 4-11 13 May 1998 The SBUSEOR card can be used to advantage when developing/testing new code for the MC. The argument list provides a convenient way of passing in parameters to control the users' special requests, e.g., HBOOK output options. 4.2.6.1 EOR_ON|EOR_OFF The EOR_ON and EOR_OFF cards control the calling of the user routine 'SBUSEOR'. The default is OFF. 4.2.6.2 EORARGS The EORARGS card supplies a list of 1 to 10 integer or real numbers which will be passed to SBUSEOR as the second argument of the call. 4.2.7 SBUSEOJ(EOJARG()) -- End Of Job SBUSEOJ will be called at the end of a job, with an array of up to 10 user parameters (real or integer) as the only argument. The SBUSEOJ card can be used to advantage when developing/testing new code for the MC. The argument list provides a convenient way of passing in parameters to control the users' special requests. 4.2.7.1 EOJ_ON|EOJ_OFF The EOJ_ON and EOJ_OFF cards control the calling of the user routine 'SBUSEOJ'. The default is OFF. 4.2.7.2 EOJARGS The EOJARGS card supplies a list of 1 to 10 integer or real numbers which will be passed to SBUSEOJ as the only argument of the call. RUNTIME CONTROL CARDS Page 4-12 13 May 1998 4.3 DETECTOR CONFIGURATION The following cards control options for the BES detector subsystems, including global parameters and detailed resolutions, efficiencies, dead channels and noise levels for various systems. For specific detector components, each subsystem is flagged by a system keyword which must be the first word on the runcard. All keywords following it will be interpreted for that subsystem. See under "$SUB_DICT" in the dictionary definition section (below) for more information. 4.3.1 Magnetic Field The SOBER runs with either a constant field or a inconstant one. CON_B INCON_B card makes the choice and BFIELD card sets the norminal value of the magnetic field. 4.3.1.1 BFIELD The field value (BFIELD in /CONTRL/) will be set to in KGauss when the 'BFIELD' card is present. The default field is 4 kG. The nominal field value and the flag BMFIT are communicated to the off-line via the Type 50 data record so that the correct field in used in reconstruction. 4.3.1.2 CON_B|INCON_B Sets a flag BMFIT in /CONTRL/ to .TRUE. (CON_B) or .FALSE. (INCON_B), which controls if subroutine BESFIEL is called. The default is 'INCON_B'. When the 'CON_B' card is present, the nominal value set by BFIELD card is used while tracking. Otherwise, BESFIEL is called and returns a "real" value. Since BESFIEL is called only by tracking process inside the main drift chamber, in any case the BFIELD value is used for tracking outside the main drift chamber. 4.3.2 Interaction Location The primary vertex position will be gaussian distributed with a central mean specified by the SIG_IR and RUNTIME CONTROL CARDS Page 4-13 13 May 1998 XYZ_IR cards. The default is the origin (0,0,0) with no spread. The values are communicated via Type 50 record to the off-line for reconstruction purposes. 4.3.2.1 SIG_IR The Gaussian spread of vertex positions in each dimension has a sigma of , , and , respectively. The default values are all zero. 4.3.2.2 XYZ_IR Mean vertex position is at (,,). Default is the origin (0,0,0). 4.3.3 DCHSYS -- Central And Main Drift Chambers The parameters for the DCHSYS card are stored in common block /DCSYS/. 4.3.3.1 DC_EFFCY [()] A list of 1 to 11 efficiency levels for the drift chamber layers. 4.3.3.2 DC_NOISE [()] ... A list of 1 to 11 noise levels for the drift chamber layers. The noise level is the maximum number of random noise hits per layer event averaged. 4.3.3.3 DC_TRESO [()] A list of real time resolutions for the 11 layers. Units are 0.1 nsec. Values are stored in DRESOT in /DCSYS/. 4.3.3.4 DC_XRESO [()] A list of spatial resolutions in meters for the 11 DC layers. Values are store in DRESOX in /DCSYS/. RUNTIME CONTROL CARDS Page 4-14 13 May 1998 4.3.3.5 DEAD_CELL CELL LAYER Disable an entire cell in the drift chamber. The key-words LAYER and CELL specify which one. 4.3.3.6 DEAD_WIRE WIRE CELL LAYER Disable one wire in the drift chamber. The key-words LAYER,CELL,WIRE specify which one. 4.3.3.7 E_LOSS ON|OFF Controls whether energy loss correction will be applied to tracks as they are propagated. ON is the default. OFF will cause the 3-momentum (magnitude) to be constant over the orbit. NOTE that dE/dx signals will still be generated. This option merely controls whether the energy loss is actually applied to the track. Note: The combined effect of setting SCATTER and E_LOSS to OFF is to generate tracks with perfect helical orbits (no deviations). These features are intended to make the study of inherent resolutions and systematics in the MC as well as the off-line reconstruction easier. 4.3.3.8 EFFCY ON|OFF Controls whether layer-wise efficiencies will be used when generating DC hits. The default is currently OFF. 4.3.3.9 NOISE ON|OFF Controls the generation of random noise hits in a layer-wise manner. OFF is the current default. 4.3.3.10 PRT_LEV [()] Up to 10 integer print control flags for drift chamber tracking system. RUNTIME CONTROL CARDS Page 4-15 13 May 1998 4.3.3.11 SCATTER ON|OFF Controls multiple scattering in the drift chamber tracking. ON is the default. OFF will generate tracks with no multiple scattering deviations. Note: The combined effect of setting SCATTER and E_LOSS to OFF is to generate tracks with perfect helical orbits (no deviations). These features are intended to make the study of inherent resolutions and systematics in the MC as well as the off-line reconstruction easier. 4.3.3.12 TIME_RESOL ON|OFF Controls whether the generated MTAC time will be smeared by a layer dependant time resolution. The default is OFF. 4.3.3.13 WIRE_SAG ON|OFF Controls whether sag and bowing corrections will be made when drift times are generated. The default is ON. 4.3.3.14 XY_RESOL ON|OFF Controls whether the actual space point from which the time is generated will be smeared by a layer dependant space resolution. The default is OFF. 4.3.4 MUSYS -- Muon Tracking There are a number of parameters which control the details of tracking and hit generation in the muon system. 4.3.4.1 ADC_EV Scale factor in units of BADC/eV which is used to convert the energy deposited in the muon tube in eV to BADC units. RUNTIME CONTROL CARDS Page 4-16 13 May 1998 4.3.4.2 DEAD_ASSEM ''x [''x...] A hex-string indicating a muon assembly (or LCA ) to be disabled. One assembly constitutes 8 channels (tubes). 4.3.4.3 DEAD_TUBE ''x [''x...] A hex-string indicating one muon channel or LCAT to be disabled. 4.3.4.4 LANDAU ON|OFF Selects whether the energy deposition calculation for the raw pulse height will include Landau fluctuations about the mean energy loss. Default is LANDAU. 4.3.4.5 MAX_NOISE_PH Maximum noise pulse height in BADC units to generate for random noise. The noise spectrum will be uniform up to . 4.3.4.6 MU_EFFCY Global efficiency of muon tubes. 4.3.4.7 MU_NOISE [()] ... A list of up to 16 real noise levels, one per muon cluster. There will be noise hits maximum per event. That is, each may be < 1.0. 4.3.4.8 NOISE ON|OFF Turns ON/OFF random noise in the 16 clusters. 4.3.4.9 PRT_LEVS [()] A list of up to 10 integer print control flags for the muon system. RUNTIME CONTROL CARDS Page 4-17 13 May 1998 4.3.4.10 REAL_Z|NOM_Z Selects whether the actual (REAL_Z) calibration constants or nominal values (NOM_Z) are used for charge division. 4.3.4.11 SCATTER ON|OFF Selects whether multiple scattering will be applied to tracks propagated through the muon system. 4.3.4.12 SIGMA_PED Sigma of pedestal in BADC units. (REAL) 4.3.4.13 SIGMA_Z Muon tube Z-resolution in meters. 4.3.4.14 SMEAR_PH ON|OFF Selects whether the rawdata will have pedestal fluctuations applied. 4.3.4.15 SMEAR_Z ON|OFF Selects whether the z-position of the track is to be smeared before charge division is applied. This generates a Z-resolution directly as opposed to smearing the generated pulse heights.) 4.3.4.16 STRAGGLE ON|OFF Selects whether range straggling will be done for energy loss inside the muon steel and clam shell. 4.3.4.17 THRESHOLD = BADC threshold for readout.(Integer) RUNTIME CONTROL CARDS Page 4-18 13 May 1998 4.3.4.18 Z_SLOPE Nominal Z-slope (linear term) for charge division calculation. 4.3.4.19 Z_INT Nominal Z-intercept (constant term) for charge division calculation. 4.3.5 SHOWERSYS -- Shower Counter This card selects various shower system parameters. 4.3.5.1 BC_SCALE Barrel shower counter gain, ADC units per eV. It converts energy deposited via dE/dx in a shower to nominal ADC units. These numbers are logged with the data set so that off-line shower reconstruction routines have access to the "correct" energy scale. 4.3.5.2 NEC_SCALE <-scale> North endcap shower counter gain, ADC units per eV. It converts energy deposited via dE/dx in a shower to nominal ADC units. These numbers are logged with the data set so that off-line shower reconstruction routines have access to the "correct" energy scale. 4.3.5.3 SEC_SCALE South endcap shower counter gain, ADC units per eV. It converts energy deposited via dE/dx in a shower to nominal ADC units. These numbers are logged with the data set so that off-line shower reconstruction routines have access to the "correct" energy scale. 4.3.6 TOFSYS -- Time Of Flight Counters Values set by this card are contained in common /TOFSYS/. RUNTIME CONTROL CARDS Page 4-19 13 May 1998 4.3.6.1 ATTEN_LEN Attenuation length of TOF counter in meters. 4.3.6.2 PROP_VEL Speed of light in counter in m/nsec. 4.3.6.3 RES_ON | RES_OFF RES_ON enables smearing of the generated times by the TOF resolution. RES_OFF disables smearing. The default is OFF. 4.3.6.4 TOF_SIGMA TOF resolution in nsec. (Default is 200 psec.) 4.3.6.5 Z_TOF Effective half-length of counter 4.3.7 DEDXSYS -- DE/dx System 4.3.7.1 LANDAU ON|OFF Selects whether Landau fluctuations will be turned ON or OFF. The default is ON. When OFF the dE/dx pulse will merely be the most probably energy loss. 4.3.7.2 PRT_LEVS [()] A list of up to 10 integer print control flags for the dE/dx routines. 4.3.7.3 SCALE Scale factor for converting energy deposited on signal wires in eV to nominal BADC units. RUNTIME CONTROL CARDS Page 4-20 13 May 1998 4.3.7.4 SIGMA_PED Nominal pedestal sigma used for smearing signals. 4.3.7.5 SMEAR ON|OFF Selects whether the dE/dx signals will be have pedestal fluctuations included. The default is OFF. 4.3.7.6 THRESHOLD Global nominal BADC threshold for readout. CHAPTER 5 RUNCARD EXAMPLES This section contains some annotated sample runcard files. NOTE: THESE SAMPLES ARE OLD MARK III FILES WRITTEN FOR SLACVM. THEY MAY NOT WORK CORRECTLY (ESPECIALLY THE CP CONTROL CARDS) ON VAX OR UNIX. NEW SAMPLE JOBS WILL BE DEVELOPED AND INCLUDED LATER. 5.1 EXAMPLE 1 - USING HOWL This simple example generates a K+K-Pi+Pi- data set using HOWL. * EVT_GEN HOWL ; SHO_GEN FAKSHR ; * LOGOUT Disk KKPIPI HOWL ; * TEXT myevanal print ; /* MC Runcards for K+K-pi+pi- */ Run = -505 ;Ecm =3.0195 ; Nev = 500 ; Print ON ; Chrg_Trks .495 -.495,139 -.139 ; End ; /* End of run 505 */ The 1-st 3 records are the GASPER Exec control cards which specify the event and shower generator, the output data set name and the names of some TEXT files to load. The remaining cards are all that is required to generate 500 events of K+K-pi+pi- according to phase space distributions. The user's PRINT routine will be called at the end of the run. 5.2 EXAMPLE 2 - USING P2MUMU * EVT_GEN P2MUMU ; SHO_GEN FAKSHR ; * LOGOUT Disk PSI2 MUMU A4 ; * TEXT muevanal print ; RUNCARD EXAMPLES Page 5-2 13 May 1998 /* MC Runcards for Psi ->mumu */ Run = -901 ;Ecm =3.0195 ; Nev = 100 ; Print ON ; PRTARGS = 10 '1110'b ; CLEAR ON ; Random = 12345 ; MUSYS Prt_lev(3) = 1 ; End ; /* End of run 901 */ This set of cards will generate 100 mumu events from Psi decay. The starting random seed is 1234. The MUSYS card is used to set the 3rd muon print lev parameter to 1. Routine PRINT will be called with an array with the first two locations containing a 10 and the mask '1110'b. 5.3 EXAMPLE 3 - USING TESTER * EVT_GEN TESTER ; SHO_GEN Fakshr ; * Logout DISK TEST OUTDATA ; /* MC RUNCARDS */ run=-900 ; Ecm = 3.0 ; Nev = 100 ; Tester TRK_ID = 3 P_Gev = 1.5 CHARGE = 1 N_TRKS = 2 NODECAY COS_MIN = -.5 COS_MAX = +0.5 ; End ; /* End of run 900 */ This set of cards will generate 100 events containing 2 muons(+) at 1.5 Gev. The tracks will be uniformly distributed in phi and over the cos(theta) region -0.5 to +0.5. CHAPTER 6 DEFINING NEW SOBER CARDS The runtime control cards described in this note may be modified or extended by users by editing two files in the BES software library. One of these files is the runcard dictionary, SOBDICT.CAR, located in the same area as the BES calibration constants. This file defines all of the keywords recognized by SOBER, and specifies the actions to be taken for each keyword. The second file is the source code for MCINIT, which sets up a table of memory addresses corresponding to variables or subroutines which are affected by the SOBER keywords. Both of these files must be modified together to ensure that the SOBER software remains internally consistent. If the new keyword is supposed to call a subroutine, or to set a new variable, that subroutine or variable must be declared appropriately in the MCINIT routine, and the new subroutine (if any) must be put into the BES software library. 6.1 DICTIONARY FILE FORMAT The runcard dictionary consists of single-line, free-format records, each of which defines a keyword, and the action associated with that keyword. Keywords can have one and only one action associated with them; multiple actions may be implemented by a series of keywords, each of which takes one action in isolation, together with executable code written to detect whether the necessary preceding actions have been taken. The dictionary may contain comments at any point, delimited with the characters '/*' at the beginning of the comment, and '*/' at the end of the comment. Comments are limited to at most a single line: multi-line comments must DEFINING NEW SOBER CARDS Page 6-2 13 May 1998 be delimited separately. The syntax of a dictionary definition is one of: [ ...] [#] [] or $SUB_DICT The second case must appear on a line by itself (possibly with comments) and indicates the start of a subdictionary definition. 6.1.1 This is what the user will type in their runcard file to cause the defined action. If multiple keywords appear before the , they are "synonyms," and any of them may be used in a runcard file to take the same action. 6.1.2 is any one of the following: MOV Store in AND Apply bitwise AND of to OR Apply bitwise OR of to SET Store value bitwise in (OR) CLR Store inverse of bitwise in (NOT-AND) CALL Pass arguments to subroutine SUB Switch control to subdictionary (see below) SKIP Ignore following number of tokens, or remainder of card if =0. 6.1.3 indicates the data value(s) to be operated on. This data may be a string or numeric value read from the card (following the keyword), indicated by one of IVAL Integer value (decimal, binary, octal, or hex) RVAL Floating point value (may be exponential) STR String expression (may use quotation marks) SYM String or keyword to be treated as a string DEFINING NEW SOBER CARDS Page 6-3 13 May 1998 may also be an "immediate value" -- a specific number or symbol, not read from the user's runcard, and preceded by the '#' character. Special symbolic values are: #TRUE Logical .TRUE. (1) value #FALSE Logical .FALSE. (0) value For the case of the SUBD operator, should be an immediate value number (e.g., #2, #7) corresponding to the desired subdictionary. 6.1.4 Indicates where the data values are to be placed, or the action to be taken on the data. It consists of a memory address number, corresponding to the index in the ADDR(i) array defined in the MCINIT initialization routine. may include optional modifiers: = [ [+] [ [] ] ] 6.1.5 + Indicates an offset from the address, for example, if corresponds to an array, then + may be used to reference one element of that array, where the first element is +0. 6.1.6 [] For multi-valued destinations, the increment, [] (the square brackets are required), indicates the size in bytes of each value. A normal integer or real array should have [4] (the default), while string arrays should have an increment equal to the declared length ([n] for a CHARACTER*n array). 6.1.7 is the total length in bytes of the destination. The default length for integers or reals is 4. Strings should have a length n, when the corresponding variable is declared CHARACTER*n. Arrays must have their total length N declared as the array dimension times the size of each element. For DEFINING NEW SOBER CARDS Page 6-4 13 May 1998 example, a Fortran variable INTEGER J(8) must have a declared length in the dictionary of 32 (and an increment of [4]). 6.1.8 $SUB_DICT -- Subdictionaries Subdictionaries are groups of keyword definitions which are only meaningful following a particular keyword on the same runcard. Subdictionary activation may be nested, in that a keyword defined in a subdictionary may transfer control to a different subdictionary. However, returning to a "previous" subdictionary only happens at the end of a runcard (a semi-colon or end of line), in which case "control" returns to the main dictionary. In the dictionary definition file, a subdictionary is started with a "$SUB_DICT" record. Subdictionaries are numbered sequentially through the file as $SUB_DICT cards are encountered: the main dictionary is #1, the first $SUB_DICT begins #2, and so on. 6.2 ADDRESS DEFINITIONS IN MCINIT.FOR If a keyword definition in the dictionary includes a destination argument, that destination must be defined in the executable code. The initialization routine MCINIT is passed as an argument an array of integers ADDR(*), which holds the memory locations of all variables and subroutines used as destinations in the dictionary. Sample address definitions from MCINIT are ADDR(12) = LOC(LODCON) ADDR(20) = LOCLOC(IOJCRD) The variable LODCON in declared LOGICAL in the PILOT.INC include file (it is used to flag whether calibration constants should be loaded for the job). The line above assigns the memory location of LODCON, obtained with the LOC() function, to the dictionary destination 12. In the SOBER dictionary, this address is referenced in the keyword definitions RECON MOV #TRUE 12 /* LODCON */ NORECON MOV #FALSE 12 which assign LODCON = .TRUE. and LODCON = .FALSE. respectively. DEFINING NEW SOBER CARDS Page 6-5 13 May 1998 The second address assignment above stores the address of the subroutine IOJCRD. This routine is (must be) declared EXTERNAL in MCINIT, and the address of the routine is obtained with the function LOCLOC(), and assigned to dictionary destination 20. In the SOBER dictionary, this destination is used with the CALL operator to effect a subroutine call: BESIOJ INIT CALL IVAL 20 [4] 40 /* EVNARG */ Here, the two keywords BESIOJ and INIT both cause subroutine 20 (IOJCRD) to be called. The source IVAL, and the parameters following the destination ("[4] 40"), indicate that IOJCRD is called with an array of ten integers, which should appear on the user's runcard following the BESIOJ keyword. In this case, if the user specifies fewer numeric arguments, all the missing ones will be assigned 0 before IOJCRD is called. APPENDIX A SOBCARD - SUMMARY This appendix is intended as a quick reference for card formats. Cards appear alphabetically. *BESGEOM *BES$CON *LINK *OUTPUT DISK *OUTPUT TAPE *SOBDICT AUTODECAY BFIELD CHRG_TRKS COMMENT CON_B DCHSYS DBGARGS [()] DBG_OFF DBG_ON DECAY TRK LIFE_T DEDXSYS ECM EGS_OFF EGS_ON END ENDTIME EOJARGS [()] EOJ_OFF EOJ_ON EORARGS [()] EOR_OFF EOR_ON EVNARGS [()] EVN_OFF EVN_ON EVTYPE GAMMA GEN_MASK <'xxx'b>; INCON_B IOEARGS [()] IOE_OFF SOBCARD - SUMMARY Page A-2 13 May 1998 IOE_ON IORARGS [()] IOR_OFF IOR_ON LOG_MASK <'xxx'b>; MPARAM [ ... ] MUSYS N_CIRC NEUT_TRKS NEV NEVTIM PRT_MCPRT PRT_NOISE PRT_RANDOM PRT_PTS PRT_SUM RANDOM RAW_MASK <'xxxxxxxxxx'b>; RESONANCE TRK WIDTH RUN SHOWERSYS SIG_IR TOFSYS TRIG_OFF TRIG_ON X_COSMIC X_STRAY XPARAM [ ... ] XYZ_IR