KLUE Offline Manual--KL100

Last modification 8 November 1993. Ported to WWW on UNIX. G. Irwin This manual is being continuously enlarged and updated. Table of Contents G. Irwin 11/85 I. File organization -- to be updated for UNIX A. Libraries 1. VAX 2. IBM B. Using the compiler and library maintenance execs 1. VAX 2. IBM II. Compiler description -- to be updated for UNIX A. PREP 1. Function 2. Command syntax B. MORTRAN 1. Function 2. Version 3. Language syntax C. FORTRAN 1. Version 2. Caveats III. Programming rules A. Documentation 1. In subroutine headers 2. In line 3. Offline manual 4. History file -- to be updated for UNIX B. Naming conventions 1. Commons 2. Subroutines 3. Variable names 4. Macro names C. Skeleton prototypes 1. Commons 2. Subroutines D. Program structure 1. Program control parameters 2. Commons 3. Subroutines 4. Constant updating E. Coordination of program modification -- to be updated for UNIX 1. Locking a program subunit for modification 2. Debugging of subunit before installing it 3. Getting the subunit installed F. Programming etiquette 1. Readability 2. Portability IV. Offline program organization A. Data structures B. Basic program flow C. Program control parameters 1. Job control 2. Control of subunits -- PARM commons D. Description of subunits I. File Organization -- to be updated for UNIX G. Irwin 7/85 I.A.1) VAX(VMS) File Organization -- The offline program system is subdivided into 3 directories given below by the VAX logical names defined in a file KLUELOG.COM;. a) KLUE$COMPILE -- contains the PREP and MORTRAN pre-compilers and two .COM; execs which invoke them. These are called COMPILE.COM; and GINSTALL.COM;. As these two execs will change in the future, they should be treated as black boxes for now. The COMPILE exec processes a .PMR; file in the user's default directory through PREP, MORTRAN and FORTRAN to produce .OBJ; and .LIS; files, as well as all the intermediate files generated by PREP and MORTRAN: .MOR;, .FOR;, and .MST; (for MORTRAN, FORTRAN and MORTLIST). The GINSTALL exec is a library maintenance exec to compile one or more .PMR; files in a program library and save the compiled object code in a file called LOADMOD.OLB;. The .FOR; file, produced by MORTRAN for input to FORTRAN is also saved in the program library for use by the VAX interactive debugger. The other intermediate files are deleted. A list of successful compilations is kept in X1.DON; and a list of failures in X1.ERR;. b) KLUE$OFFLINE -- contains the COMMONs(.CMN;), SUBROUTINEs(.PMR;), MORTRAN MACRO(.MCR;) and other miscellaneous files(.MSC;) which make up the offline program itself. File LOADMOD.OLB; is a load library containing the compiled code. c) KLUE$UTIL -- contains machine and installation dependent utilities which are referenced by generic names from the offline program library. This directory also contains a load library of compiled code called LOADMOD.OLB;. In addition there is a sample job KLUEJOB.COM;, which can be run in BATCH or interactively (with DEBUG if desired). To run it, type: @KLUEJOB TEST searchlst , for interactive running, or SUBMIT/PARAM=(TEST,searchlst) KLUEJOB.COM , for BATCH. The parameter TEST is an arbitrary filename which the job will use for temporary files created during compilation and for storing sets of data cards. These files are deleted upon normal job termination. If the job abends, the files are left on the default disk for interactive running. The optional argument "searchlst" can be used to specify the [search directory] parameter described below in the description of the VAX version of COMPILE.COM. This parameter is used if the user wants to have a personal directory of subroutines and commons which PREP and MORTRAN will search before the default KLUE$OFFLINE when compiling subroutines in the user's source deck. For example, ([MY$OFFLINE+KLUE$OFFLINE]) as the second SUBMIT parameter will cause commons and other MORTRAN files to be taken from MY$OFFLINE, instead of KLUE$OFFLINE, if available. I.A.2.) IBM(VM) File Organization -- The offline program system is found on 2 minidisks described below: a) COMPILE DISK -- contains the PREP and MORTRAN pre-compilers and two REXX EXECs which invoke them. These are called COMPAVS EXEC and GINSTALL EXEC. As these two execs will change in the future, they should be treated as black boxes for now. The COMPAVS EXEC processes a PREPMORT file on any accessed minidisk through PREP, MORTRAN and FORTRAN to produce TEXT and LISTING files, as well as all the intermediate files generated by PREP and MORTRAN: MORTRAN, FORTRAN and MORTLIST are their filetypes. The GINSTALL exec is a library maintenance exec to move one or more PREPMORT files onto a program disk and save the compiled object code in a TXTLIB. The LISTING file produced by the FORTVS compiler is also saved in packed format on the program disk for use by the FORTVS interactive debugger or MRCLEAN. The other intermediate files are deleted. All transactions are logged in a file called 1B7 HISTORY on the program disk, together with detailed comments describing the changes. b) OFFLINE DISK -- contains the COMMONs, SUBROUTINEs(ft=PREPMORT), MORTRAN MACROs(ft=MORTMAC) and miscellaneous files(ft=STUFF), which make up the offline program itself. File KLUELM.TXTLIB is a load library containing the compiled code. c) UTILITY DISK -- contains machine and installation dependent utilities which are referenced by generic names from the offline program library. This directory also contains a load library of compiled code called UTILKLUE TXTLIB. I.B.1.) Using the VAX(VMS) Compiler and File Maintenance Execs -- KLUE$COMPILE has two .COM; execs which perform the 3 stage compilation procedure. The person who does the library maintenance can use two symbols defined in KLUELOG.COM to invoke these execs for routine library mainenance: COMPAVS filename to compile filename.PMR GINSTALL parameter list to run GINSTALL The execs themselves are described as follows: @KLUE$COMPILE:COMPILE filename [search_directory] , where filename is the left portion of the name of a .PMR; file to be compiled. This file must be in the default directory. The files resulting from compilation will be placed in the default directory. These include: .MOR; -- the MORTRAN input file prepared by PREP .MST; -- the listing output from MORTRAN .FOR; -- the FORTRAN input file prepared by MORTRAN .LST; -- the listing output from the FORTRAN compiler .OBJ; -- compiled object code from the FORTRAN compiler MORTRAN errors are signalled in the .MST; listing and FORTRAN errors in the .LST; listing. search_directory is the directory list from which PREP is to copy COMMONs, MACROs and miscellaneous files needed to construct a MORTRAN input file. If the search_directory parameter is left blank, the default KLUE$OFFLINE is supplied. The COMPILE.COM; exec actually searches the user's default directory first for .COM;, .MCR;, .PMR; or .MSC; files to copy. Then it goes either to KLUE$OFFLINE or to the sequence of files indicated by the parameter search_directory. The syntax for the search_directory parameter is as follows: ([directory1]+[directory2]+[directory3]+[directory4]) Up to 4 directories may be supplied. The KLUE$OFFLINE directory must be among them if the search_directory parameter is supplied and KLUE$OFFLINE is desired. @KLUE$COMPILE:GINSTALL filename offline_library [search_directory] This exec compiles either a single subroutine or a set of subroutines specified by the filename parameter, places the resulting .FOR; file in the offline_library directory and sticks the compiled object code in the LOADMOD.OLB; file of the offline_library directory. The syntax of each of the parameters is as follows: filename has 4 possible forms: a) The left portion of the file name of a .PMR; file to be compiled. b) A wild-card version of the left part of a .PMR; file name. For example, a filename parameter of DMP* will cause all subroutines starting with DMP to be compiled. c) The expression &LIB signals the presence of a file called LIB.LST; which contains a list, one line per subroutine, of the complete file-spec for each subroutine to be compiled. The format for this list is as generated by the DIR/LIST/NOHEAD command. In particular the ; must be present. d) The expression &ERR points to a list, generated during the previous pass of GINSTALL, of subroutines which failed to compile for any reason. The list is called X1.ERR;. All the subroutines in the list will be recompiled. offline_library is the name of the directory from which the .PMR; file is taken and to which the .FOR; file is written and the LOADMOD.OLB; update is made. search_directory is the directory list from which PREP is to copy COMMONs, MACROs and miscellaneous files needed to construct a MORTRAN input file. If the search_directory parameter is left blank, the offline_library parameter is supplied. The GINSTALL.COM; exec actually searches the user's default directory first for .COM;, .MCR;, .PMR; or .MSC; files to copy. Then it goes either to offline_library or to the sequence of files indicated by the parameter search_directory. The syntax for the search_directory parameter is as follows: ([directory1]+[directory2]+[directory3]+[directory4]) Up to 4 directories may be supplied. The KLUE$OFFLINE directory must be among them if the search_directory parameter is supplied and KLUE$OFFLINE is desired. I.B.2.) Using the IBM(VM) Compiler and File Maintenance Execs -- The COMPILE disk has two REXX EXECs, each of which performs the 3 stage compilation procedure. To run these EXECs, the user types: COMPAVS filename [filetype filemode] , where filename is the name of a file to be COMPILED. If no filetype is supplied, PREPMORT is assumed. If no filemode is specified, COMPAVS will compile the first appropriately named file occurring in the CMS disk search order. The files resulting from compilation will be placed on the user's A-disk. These files may include: MORTRAN -- the MORTRAN input file prepared by PREP MORTLIST -- the listing output from MORTRAN FORTRAN -- the FORTRAN input file prepared by MORTRAN LISTING -- the listing output from the FORTRAN compiler TEXT -- the object code from the FORTRAN compiler MORTRAN errors are signalled in the MORTLIST file and FORTRAN errors in the LISTING file. GINSTALL diskowner diskaddress function filename filetype filemode This is a general file manager for the minidisk specified by the parameters: diskowner diskaddress. All modifications to the disk should be made through this EXEC. Normally, special CZAR privileges are necessary to run this EXEC on the offline program disk. The people authorized to modify a disk with this EXEC are specified in the file 1B7 STAFF, found on the minidisk itself. The function parameter specifies the type of change that the user wishes to make to the specified disk. For each change the EXEC backs up any replaced files two levels deep and records the change in a file called 1B7 HISTORY, including a description of the change typed by the user. The file backups are done by renaming the files with filemode type 0 to make the file invisible to any future person accessing the disk in read-mode, while ensuring that any job which is still using the old file continues to run undisturbed. All function types can be listed by typing HELP MINIMANG. The major function types are detailed below: REP -- simply replaces the file named with a new one. This function may be used to replace files with filetypes COMMON, MORTMAC, STUFF and any other filetypes besides PREPMORT, which must be handled with the LIB function. The filename may be the wildcard parameter * to specify all files with the specified filetype filemode. LIB -- the function that should be used to replace PREPMORT files. The exec compiles either a single subroutine or a set of subroutines specified by the filename parameter, places the resulting LISTING file on the specified offline minidisk and sticks the compiled object code in the program TXTLIB on the specified minidisk. ERASE -- causes the file or files to be removed from the specified disk. If the filetype is PREPMORT, the PREPMORT file is made invisible and the subroutine is removed from the TXTLIB. Before removing a subroutine from the TXTLIB, the EXEC will attempt to recompile the subroutine to discover all the ENTRY points which must also be removed. If a set of GINSTALL commands are anticipated, it is best to do any PREPMORT ERASE steps first, to ensure that subsequent ERASE or REPLACE steps do not remove files which were necessary to the compilation of the original PREPMORT version. If the ERASE command fails, the removal must be effected by hand. REVERT -- Reverses the effect of a previous GINSTALL command, within reason. See HELP MINIMANG for instructions. CON -- Condenses the TXTLIB, squeezing out ghosts. (S)CLEAN -- Gets rid of CORPSE files and other detritus on the disk. The files removed are all filemode type 0. HELP MINIMANG should be invoked before attempting to use (S)CLEAN. For most of the functions above there is a means to process multiple files. This is done through the creation of a CONTROL file, whose name is given in the GINSTALL arguments. If the filetype is specified to be the word CONTROL, the EXEC looks for a file named: filename CONTROL filemode, which should contain a list of files to be processed, one file per line, specified by: filename filetype filemode. II. Compiler description A. PREP -- 1. Function -- a. Copy COMMONs and other files into SUBROUTINES b. Interpret control flags for library management EXECs c. Figure out which libraries to search for files to copy 2. Command syntax -- a. "&COPY FROM filename filetype" The IBM version of <filetype> should always be given, e.g., PREPMORT, COMMON, MORTMAC, STUFF instead of .PMR;, .CMN;, .MCR;, .MSC; b. "&COMMON/comnam/" to copy COMMONs into SUBROUTINEs. c. "&DATA" to mark the start of DATA statements in COMMONs B. MORTRAN -- 1. Function -- a. Provide machine compatibility through special MACROs. b. Provide features of structured programming not available to FORTRAN, while being nothing more than a dialect of FORTRAN. 2. Version -- Standard MORTRAN3 (EGS), but with several differences a) Produces FORTRAN77 code instead of FORTRAN66 b) Uses angle brackets < > instead of square brackets [] c) Creates better statement numbers d) Expands VAX tabs before processing code e) Has a fast character matching algorithm 3. Language syntax To be completed -- see MORTRAN3 manual for now Two important points: a) Statement labels in MORTRAN must be between colons. Instead of 1000 FORMAT, one must use :string: FORMAT. b) MORTRAN PROCEDURE labels must be valid INTEGER names, not :string: labels, contrary to the MORTRAN manual. C. FORTRAN 1. Version -- FORTRAN77 on VAX, FORTVS on IBM 2. Caveats -- a) Serious bugs still being found on IBM FORTVS compiler. b) IBM FORTVS optimizer not as good as for old FORTHX III. Programming rules A. File conventions -- The SUBROUTINEs, COMMONs and other files associated with the program should be stored in a single unique place on disk, one file per COMMON or SUBROUTINE. The name of the file is the name of the COMMON or SUBROUTINE. The SUBROUTINE files contain PREP command statements to cause the COMMONs to be copied in at compile time from the master library. B. Documentation -- to be updated for UNIX 1. In COMMON and SUBROUTINE headers -- All program units should be self documenting. A "&DOC ..." ... "&ENDDOC" section is provided at the beginning of the SUBROUTINE skeleton, for documentation of the SUBROUTINE. Following the SUBROUTINE ...; or COMMON/ statement should appear a set comments identifying the author and date as well as the purpose of the SUBROUTINE. The person responsible for maintaining the file should also be identified in a comment. A history line with author, date and reason should be added for each modification as well. These lines are immediately following the "&DOC ..." line at the beginning of the routine. Important variables in SUBROUTINEs and all variables in COMMONs must be defined in comments. 2. In-line -- Every step of a calculation should be documented with in-line comments. 3. Offline manual -- Sections of this manual should be continually added or updated to cover every aspect of the program. 4. History file -- to be updated for UNIX When the program is modified at SLACVM, all changes are logged with author, date and reason. A copy of this file may be obtained over BITNET by typing: TELL GROUPG AT SLACVM SENDME 1B7 HISTORY ON GROUPG 195 or SEND/REMOTE SLACVM GROUPG SENDME 1B7 HISTORY ON GROUPG 195 , from IBM or VAX, respectively. A filelist of all files on the program disk, with the date of their most recent modification is available with the commands: TELL GROUPG AT SLACVM FILELIST GROUPG 195 or SEND/REMOTE SLACVM GROUPG FILELIST GROUPG 195 , from IBM or VAX, respectively. Consult section V.) of this manual for further instructions on obtaining the current copy of any SLACVM file pertaining to this experiment. C. Naming conventions 1. COMMONs and SUBROUTINEs All COMMON and SUBROUTINE names should be six characters long. So that the COMMONs and SUBROUTINEs of a given type will be grouped together in the listing, the names of all COMMONs and SUBROUTINEs of a type should begin with the same two or three letters. IBM does not permit names longer than 6 characters. 2. Variable names Most variable names should be six characters long. All variables in COMMONs should have six character names. All names of variables in a given COMMON should end with the same two or three characters, to aid in identifying them in code. IBM does not permit names longer than 6 characters. 3. MACRO names -- MORTRAN MACRO names should begin the with $ symbol. Usually the name should have 6 characters following the symbol The last two or three characters in the name should be the same as the characters which terminate the names of variables in the principal COMMON using the MACRO. MACRO names in LATMAC MORTMAC should begin with $$ . D. Skeleton prototypes -- 1. COMMONs -- The model for COMMONs is illustrated below with a complete example from the offline library, COMMON MCRDAT. The skeletal bones upon which this COMMON is hung are given first. The &DATA section is given in the skeleton although it is not present in the MCRDAT example. The &DATA section is only included when PREP copies the COMMON into a BLOCK DATA SUBROUTINE. The skeleton is given with UPPER CASE for universal pieces, and lower case for parts which vary from COMMON to COMMON: "$CONTROL $NAME=&comnam,$NORUN" "MODIFIED BY person mm/yy - reason for change" "MODIFIED BY person mm/yy - reason for change" PARAMETER $xxxxxx = value ; "explanation of parameter" PARAMETER $yyyyyy = value ; "explanation of parameter" COMMON/comnam/ "comment about purpose of common. author date" IDxxxx(6),LNxxxx, aaaaRM,bbbbRM,ccccRM($xxxxxx),ddddRM,eeeeRM, INTEGER*2 IDxxxx; "*********************************************************************" " *** aaaaRM comment describing variable aaaaRM" " *** bbbbRM comment describing variable bbbbRM" " *** ccccRM($xxxxxx) comment describing variable ccccRM" " *** ddddRM comment describing variable ddddRM" " *** eeeeRM comment describing variable eeeeRM" "*********************************************************************" "&DATA" DATA aaaaRM/value/; "*********************************************************************" The example is presented here: "$CONTROL $NAME=&MCRDAT,$NORUN" "MODIFIED BY KONIGSBERG/MELESE 8/85 - ADD SWIM XREF INDEX" "MODIFIED BY IRWIN 10/85 - ADD MULTIPLE PRIMARY VERTICES. ADD /MCREPT/" PARAMETER $MPRVRM = 10 ; "MAX NO OF PRIMARY VERTICES IN /MCRDAT/" PARAMETER $MXWTRM = 5 ; "MAX NO OF WEIGHTS PER EVENT IN /MCRDAT/" COMMON/MCRDAT/ "RAW MONTE CARLO EVENT DATA. G.IRWIN 11/84" "SET UP BY MCOEXE IN STAGE 1." "FILLED BY MCOGEN IN STAGE 1." "ALTERED BY MCOSIM IN STAGES 2/3." ID0101(6),LN0101, NRUNRM,NEVTRM,EVWTRM($MXWTRM),IGENRM,IVTPRM, NLTKRM,NSTKRM,NCTKRM,NNTKRM,IOVFRM, NPRVRM,IDBMRM($MPRVRM),XYZVRM(4,$MPRVRM), PVBMRM(4,$MPRVRM),TBNKRM($NPMTRM,$MXTKRM); INTEGER*2 ID0101; "*********************************************************************" " *** NRUNRM RUN NUMBER" " *** NEVTRM EVENT NUMBER" " *** EVWTRM($MXWTRM) EVENT WEIGHT ARRAY" " 1: OVERALL EVENT WEIGHT=PRODUCT OF ARRAY" " 2: 1ST VTX KAON DECAY MATRIX ELEMENT WT" " 3: 1ST VTX DECAY LIMITS IN Z WEIGHT" " *** IGENRM GENERATOR TYPE" " *** IVTPRM EVT TYPE (MEANING DEPENDS ON IGENRM)" " *** NLTKRM NO OF PARTICLES LISTED IN /MCRDAT/" " *** NSTKRM NO OF FINAL STATE PARTICLES" " THIS IS THE NUMBER OF PARTICLES" " PRESENT UNDECAYED AT THE CURRENT" " STAGE OF ANALYSIS." " JUST AFTER MCOEXE THIS IS" " THE NUMBER OF CHARGED PARTICLES TO BE" " SWUM PLUS THE NUMBER OF NEUTRALS IN" " THE FINAL STATE, SOME OF WHICH MAY BE" " DECAYED IN MCOSIM. AFTER SWIMMING, THIS" " COUNTER IS ADJUSTED BY SUBTRACTING THE" " NUMBER OF PARTICLES DECAYED AND" " ADDING THE NUMBER OF DECAY PRODUCTS." " *** NCTKRM NO OF CHARGED TRACKS IN FINAL STATE" " *** NNTKRM NO OF NEUTRAL PARTICLES IN FINAL STATE" " *** IOVFRM OVERFLOW FLAG FOR TBNKRM" " = 0, FOR NO OVERFLOW" " *** NPRVRM NUMBER OF PRIMARY VERTICES" " *** IDBMRM($MPRVRM) BEAM ID FROM PARTICLE TABLE FOR EACH VTX" " *** XYZVRM(4,$MPRVRM) X,Y,Z,C*TIME EACH PRIMARY VTX. IN METERS" " *** PVBMRM(4,$MPRVRM) DIRCOS(X,Y,Z),/P/ OF BEAM AT EACH VERTEX" " *** TBNKRM($NPMTRM,$MXTKRM) RAW MONTE CARLO PARTICLE BANK" " *** ( 1,ITK) TERMINATION CODE OF PARTICLE: " " IF ZERO NO TERMINATION DECISION HAS" " BEEN MADE (YET). STABLE PARTICLES IN" " THE FINAL STATE WILL EITHER KEEP" " THE VALUE ZERO OR: " " IF -1 LEAVES DETECTOR, E.G.,K0LONG " " OR NON-CONVERTING PHOTON" " IF -2 STOPPING." " IF -3 INTERACTING" " IF POSITIVE = DECAY CODE OF TRACK:" " DECAY CODE OF TRACK--ZERO IF STABLE" " OR IF NOT YET DECAYED. EQUALS DECAY" " BRANCH NUMBER AFTER DECAY IS DONE." " *** ( 2,ITK) TBNKRM INDEX OF PARENT PARTICLE" " = 0 FOR BEAM PARENT" " *** ( 3,ITK) PARTICLE ID: (NEGATIVE VALUES FOR" " ANTI-PARTICLES)" " 0. NOT USED" " 1. = NEUTRINO" " 2. = GAMMA " " 3. = ELECTRON" " 4. = MUON " " 5. = CHARGED PION" " 6. = NEUTRAL PION" " 7. = CHARGED KAON" " 8. = NEUTRAL KAON" " 9. = KSHORT" " 10 = KLONG" " 11. = PROTON" " 12. = NEUTRON" " 13. = LAMBDA" " *** ( 4,ITK) CHARGE (+/-1., OR 0.)" " *** ( 5,ITK) MASS IN (GEV/C**2)" " *** ==>PARTICLE 5-VECTOR IN LAB FRAME" " *** ( 6,ITK) PX(GEV/C) IN LAB FRAME" " *** ( 7,ITK) PY(GEV/C) IN LAB FRAME" " *** ( 8,ITK) PZ(GEV/C) IN LAB FRAME" " *** ( 9,ITK) ENERGY(GEV) IN LAB FRAME" " *** (10,ITK) /P/(GEV/C) IN LAB FRAME" " *** ==>PARTICLE 4-VECTOR IN PARENT C.M. FRAME" " *** (11,ITK) PX(GEV/C) IN PARENT C.M. FRAME" " *** (12,ITK) PY(GEV/C) IN PARENT C.M. FRAME" " *** (13,ITK) PZ(GEV/C) IN PARENT C.M. FRAME" " *** (14,ITK) ENERGY(GEV) IN PARENT C.M. FRAME" " *** (15,ITK) C*TIME (PROPER DECAY TIME) IN METERS" " *** (16,ITK) NUMBER OF DAUGHTERS" " *** (17,ITK) INDEX OF FIRST DAUGHTER IN TBNKRM" " *** (18,ITK) INDEX OF 1ST SPIN WORD IN /MCRSPN/" " *** (19,ITK) INDEX OF SWIM DATA IN /SWMMCS/ (BNKMCS)" " *** (20,ITK) PRIMARY VERTEX NUMBER OF FIRST ANCESTOR" " *** (21,ITK) INDEX OF TERMINATION DATA IN /MCREPT/" "*********************************************************************" 2. SUBROUTINEs -- The model for SUBROUTINEs is illustrated below with an example from the offline library, SUBROUTINE DMPMCR. The skeleton for any SUBROUTINE is given first, then the example. The skeleton is given with UPPER CASE for universal pieces, and lower case for parts which vary from SUBROUTINE to SUBROUTINE: "&DOC subnam" "MODIFIED BY person mm/yy - reason for change" "MODIFIED BY person mm/yy - reason for change" SUBROUTINE subnam(args); " *** comment to explain the subroutine's purpose. author mm/yy" "&COMMON/&comm#1/" "&COMMON/&comm#2/" . . . "&ENDDOC" dimension ... etc. blah blah blah RETURN; END; The example is presented here: "&DOC DMPMCR" "MODIFIED BY KONIGSBERG/MELESE 8/85 - ADD SWIM XREF INDEX" "MODIFIED BY IRWIN 10/85 - ADD MULTIPLE PRIMARY VERTICES AND /MCREPT/" SUBROUTINE DMPMCR(IUNIT); " *** DUMPS COMMON/MCRDAT/ ON UNIT NUMBER IUNIT. G. IRWIN 3/85" "&COMMON/&MCRDAT/" "&COMMON/&MCREPT/" "&ENDDOC" DIMENSION XYZMTK(4),P4END(4); WRITE (IUNIT,:F1:) NRUNRM,NEVTRM,IGENRM,IVTPRM,NLTKRM, NSTKRM,NCTKRM,NNTKRM,IOVFRM,NPRVRM; :F1: FORMAT(//10X,'***** COMMONS /MCRDAT/ AND /MCREPT/ *****', // 5X,'NRUNRM=' ,I10, 5X,'NEVTRM=' ,I10, 5X,'IGENRM=' ,I10, 5X,'IVTPRM=' ,I10, 5X,'NLTKRM=' ,I10, / 5X,'NSTKRM=' ,I10, 5X,'NCTKRM=' ,I10, 5X,'NNTKRM=' ,I10, 5X,'IOVFRM=' ,I10, 5X,'NPRVRM=' ,I10); WRITE (IUNIT,:F2:) EVWTRM; :F2: FORMAT(/ 5X,'EVWTRM=',$MXWTRM E18.8); IF (NPRVRM.GT.0) <NPRT=MIN0(NPRVRM,$MPRVRM); WRITE (IUNIT,:F3:) (J,IDBMRM(J),(XYZVRM(I,J),I=1,4), (PVBMRM(I,J),I=1,4),J=1,NPRT); > :F3: FORMAT(/(5X,'VTX.#',I3,' BEAM PID=',I5,' XYZVRM=',4F10.3, ' PVBMRM=',4F10.6)); IF (NLTKRM.GT.0) <NPRT=MIN0(NLTKRM,$MXTKRM); WRITE(IUNIT,:F4:); DO NT=1,NPRT <NAME=MCDIDN(IFIX(TBNKRM(3,NT))); WRITE(IUNIT,:F5:) NT,(TBNKRM(NP,NT),NP=1,2),NAME, (TBNKRM(NP,NT),NP=4,$NPMTRM); > :F4: FORMAT(/1X,'TK' ,1X,'TCD' ,1X,'IP' , 2X,'NAME' ,1X,'CHG' ,3X,'MASS' , 3X,'PXLAB',3X,'PYLAB',3X,'PZLAB',3X,'ELAB' , 3X,'PLAB' ,3X,'PXPCM',3X,'PYPCM',3X,'PZPCM' , 3X,'EPCM' ,6X,'CTDK' ,1X,'NDAU' ,1X,'L1D' , 1X,'L1SP' ,1X,'L1SWM',1X,'VX' ,1X,'L1T' ); :F5: FORMAT( 1X, I2, F4.0, F3.0, 2X,A4, F4.0, F7.4, F8.3, F8.3, F8.3, F7.3, F7.3, F8.3, F8.3, F8.3, F7.3, E10.3, F5.0, F4.0, F5.0, F6.0, F3.0, F4.0 ); WRITE(IUNIT,:F6:)NTRKEP; :F6: FORMAT(/10X,I5,' TRACKS ARE TERMINATED.'); IF (NTRKEP.GT.0) <WRITE(IUNIT,:F7:); DO IM=1,NLTKRM <IT=TBNKRM(21,IM); IF (IT.LT.1) NEXT; <I=1,4; P4END(I)=TERMEP(I,1,IT)*TBNKRM(5,IM);> CALL MCOVTK(IM,IPAR,XYZMTK); NAME=MCDIDN(IFIX(TBNKRM(3,IM))); WRITE(IUNIT,:F8:)IM,NAME,(P4END(I),I=1,4), (XYZMTK(I),I=1,4), (TERMEP(I,2,IT),I=1,4); > > > :F7: FORMAT(1X,'MCTRK' ,2X,'NAME' , 5X,'PXEND' ,5X,'PYEND' ,5X,'PZEND' ,6X,'EEND' , 6X,'XBEG' ,6X,'YBEG' ,6X,'ZBEG' ,5X,'CTBEG' , 6X,'XEND' ,6X,'YEND' ,6X,'ZEND' ,5X,'CTEND' ); :F8: FORMAT(1X,I5,2X,A4,12F10.4); RETURN; END; E. Program structure -- 1. Program control parameters -- Parameters which control program flow and allow the user to select among various options for processors like decay routines, track swimming, and digitization must be readily accessible in COMMONs so that their values may be dumped by the $DUMP command and so they may be changed dynamically during a job from SUBROUTINE USER. The convention is to have a different PARAMETER COMMON for each processor or module in the program. These COMMONs have names like MCRPRM, SWMPRM and SIMPRM for the Monte-Carlo, swimming and digitization, respectively, for example. No control or option parameters may be buried in code, without COMMON access. Certain parameters may be additionally accessible through NAMELIST data cards, which allow the user to initialize any parameters in a specified NAMELIST, while leaving others alone. Finally, the particle data list, decay table and aperture table are initially inputted to their respective COMMONs from formatted data cards, for which default copies are available on the offline program library. By putting modified versions of these tables in his SOURCE data decks, the user can tailor the tables as he wishes. 2. COMMONs -- a. A COMMON should contain only related information. Hybrid COMMONs should be broken up. All information in a COMMON should ideally be calculated at the same time in the same program module or SUBROUTINE. Program control parameters or calibration constants should appear in different COMMONs from event data, pattern recognition results or summary statistics, as an example. b. COMMONs with large track or point arrays, which are only partially filled for average events, should be constructed so that the null portion of the COMMON can be trun- cated when writing the COMMON out to tape. c. Dump routines -- The person responsible for each COMMON must provide a routine to dump that COMMON. The dump routine names all begin with DMP. The dump routine can be invoked with a standard MACRO statement $DUMP ... , using the COMMON name as a mnemonic, like $DUMP FTTRAK (6), which dumps COMMON FTTRAK on unit 6. Care should be taken to make the dumps readable, having all numbers identified with their variable names. Formats should permit sufficient significant digits to be printed out for each variable. The time that well constructed dumps save for the collaboration as a whole justifies the effort to do them well. The example of the dump routine for COMMON/MCRDAT/ given above in 3.D.2) illustrates the desireable feature of easy modification, as the COMMON evolves. By blocking the FORMAT statements :F4: and :F5: on the page to show the correspondence of heading with list, the number of columns allotted to a particular TBNKRM variable can easily be changed or new variables quickly added to the list, without counting out Hollerith text and generally without any real need to test the new routine, beyond a pro forma check. Again, a little time spent by the original author saves other members of the collaboration potential aggravation later on. d. Each COMMON in the program should begin with two identifying variables named IDggtt(6) and LNggtt, where gg is the two digit identfier of the COMMON group and tt is the identifier of the COMMON type within the group gg. The IDggtt array is INTEGER*2. and LNggtt is INTEGER*4. These variables are filled and used at various times by the job control, updating and tape writing routines. Since the ggtt portion of the variable names follow a code and must be unique, the best policy for a user writing code is to provide the two words at the head of a new COMMON, but to use letters for ggtt pending number assignment when the COMMON is installed in the library. For example, one might use COMMON/PATPAT/IDPATP(6),LNPATP,... , which might later get changed to COMMON/PATPAT/ID0706(6),LN0706,... . 3. SUBROUTINEs -- a. DEBUG printout should be included in all important SUBROUTINEs. The user should be able to select the degree of detail of the dump by setting the value of a DEBUG print flag, normally off. The flag should be available in a ...PRM COMMON where it can be set dynamically. b. MORTRAN replacement MACROs should be used to define the values of all constants like pi,e,c, etc., as well as the dimensions of most arrays in COMMONs. DO LOOPs over these dimensions should refer to the MACRO name rather than some integer value. This allows one to change the dimension of a track or point bank in one place, without having to search through the program for all occurrences of a given integer dimension in a DO LOOP index, for example. The MACRO naming conventions are given in section III.B.4). If a given replacement MACRO is used in more than one COMMON, or in a SUBROUTINE not containing the principal COMMON which references the MACRO, the MACRO definition should be placed in the file PARMMAC MORTMAC on the program library. This will make it available to the entire library. If the MACRO is used only in conjunction with the principal COMMON, it may appear at the head of the principal COMMON, and it will only be defined for SUBROUTINEs containing that COMMON. Thus MACROs for the physical constants (c,pi,e,...) should be defined in the general file PARMMAC MORTMAC. Each replacement MACRO definition statement must contain an in-line comment explaining what the MACRO is and generally where it is referenced. MORTRAN MACROs differ from FORTRAN PARAMETERs in two important ways: 1.) They are triggers for string replacement in the MORTRAN preprocessor, rather than glorified DATA statements, as conceived for FORTRAN77. This means that their names do not have to be legitimate FORTRAN variable names with defined type. 2.) FORTRAN code generated by MORTRAN already contains the replacement string. By contrast, FORTRAN77 does the substitution at LOAD time, and the FORTRAN LISTING does not necessarily indicate the value of the replacement. Note the apparent similarity in the COMMON prototype (section III.D.1.) of the MORTRAN string replacement MACRO form used there with the standard FORTRAN77 PARAMETER statement. Don't be fooled. MORTRAN will intercept that statement and do the string replacement before FORTRAN gets a chance. The BLANKS surrounding the strings as well as the ; terminating the right hand string are important for the syntax of this form of the MORTRAN replacement macro definition. An older form %'$MPRVRM' = '10' also appears in the code. 4. Calibration and survey updating -- Updating of calibration constants and other run or date dependent information should be handled by one centralized utility, operating from a disk data base. Individual SUBROUTINEs are not allowed to refer to run numbers or dates. Instead they should refer to data or indices in COMMONs set by the updating facility. Updating of calibration COMMONs is invoked for new run blocks from JCEXEC, the main SUBROUTINE, automatically by default. F. Coordination of program modification -- to be updated for UNIX 1. Locking a program subunit for modification -- Before anyone begins to modify a piece of code already on the master library, he should check the LOCK FILE available on GROUPG 200 at SLACVM. This can be obtained over BITNET by typing: TELL GROUPG AT SLACVM SENDME LOCK FILE from IBM or SEND/REMOTE SLACVM GROUPG SENDME LOCK FILE from VAX The LOCK FILE lists all program files which any user is currently modifying. If someone changes a SUBROUTINE without clearing his intention to do so with the LOCK FILE, his changes will only be accepted if there is no conflict with another version protected by a LOCK FILE entry. To place an entry in the LOCK FILE, for now, send MAIL to GMIEG at SLACVM. Soon the GROUPG server machine will be able to handle this function automatically. 2. Debugging code before it is installed -- All code must be debugged by the author before it will be installed in the master library and distributed to the collaboration. The code must pass 3 tests for acceptability: a. It must conform to the programming rules of this memo. b. It must compile on the machine of the author. c. It must be robust against all errors. This means it must not ABEND the offline program if it encounters bad data. Sufficient checks must be made to branch around divisions by zero and attempts to access array elements with undefined indices. 3. Getting code installed and distributed -- Currently the way to get new code out to the collaboration is to send new PREPMORT(.PMR;),COMMON(.CMN;),MORTMAC(.MCR;) and STUFF(.MSC;) files over BITNET to GMIEG AT SLACVM. They will be checked, installed in the master library and distributed. G. Programming etiquette 1. Portability -- a. Although MORTRAN can handle 80 column lines of code, we should restrict our code to 72 columns to protect it against any file transfer program which might put label information in columns 73/80. b. IBM insists that all DATA statements for variables in COMMONs occur in a BLOCK DATA SUBROUTINE. The section below "&DATA" in the COMMON skeleton is reserved for DATA statements which PREP will copy into BLOCK DATA SUBROUTINEs but not into regular SUBROUTINEs when the PREP copy trigger "&COMMON/comnam/" is used. DATA statements for variables not in COMMON must occur among the declarative statements at the head of a SUBROUTINE. 2. Readability -- Code should be indented and set off with blank lines to enhance readability. The fact that many terminals have 72 column lines is another reason to avoid coding lines longer than 72 columns. H. Compiler and loader errors -- 1. VAX and IBM are tolerant of 3 kinds of FORTRAN77 errors for which they may issue non-fatal warnings. Our code currently generates all 3 of these error types. It is our current policy to accept these errors, as they may stem from contructions which can be regarded as beneficial. The price we pay for accepting them is loss of compatibility with other computers with the simplest compilers, but we have already lost this compatibility through our use of VAX and IBM extentions to the FORTRAN77 standard. NAMELIST is such an extention. IMPLIED DO inside DATA statements is another one. We must nevertheless pay careful attention to compiler warnings to make sure they do not flag serious errors. Only the first of the three conditions was considered an error in FORTRAN66. Modifications exist to eliminate all three of these errors from our code while retaining the benefits of MORTRAN PROCEDUREs, for example, which produce error types a. and c. The 3 conditions are: a. Statements which are inaccessible. This happens when we branch around code to avoid executing it. MORTRAN PROCEDUREs always generate this error. b. DATA statements which preceed other declarative statements. To avoid this, one either puts all DATA statements at the end of the declaration section or uses INTEGER and REAL statements to insert data instead of DATA. Both cures can be somewhat inconvenient. c. The third violation of the FORTRAN77 standard is not even flagged by IBM or VAX, but it is the most serious hindrance to compatibility with the HP compiler, for example. It comes when you try to jump into a BLOCK IF or a DO LOOP from outside. This is never a good practice unless you came from there originally. MORTRAN PROCEDUREs generate this contruction if executed from a BLOCK IF or DO LOOP. 2. We are no longer tolerant of LOADER warnings about unsatisfied external references. These errors become fatal only if one tries to call one of the routines, but when this happens the program loses its bearings and crashes. In certain cases the program will put COMMON names among the unsatisfied externals. This will cause the program to crash in SUBROUTINE UPCOMM. Please notify G. Irwin of any instances of this that you encounter. A temporary fix to get around the problem is to put the MORTRAN COMMON statement "&COMMON/name/" for the offending common in your USER subroutine. IV. Offline program organization A. Data structures: COMMONS -- The program is organized to permit a clean separation of data into COMMONs, each of which represents the state of knowledge about an event at a single point (STAGE) in the analysis of the event, say, just after track finding, but before track-counter association. Job control parameters, surveys, calibration constants and indexing arrays derived from cable lists and patch panel maps are also segregated into commons of like type. The COMMON naming conventions assure that COMMONs of a given group appear together in a listing of the offline library. Below is a list of many of the groups written or anticipated for the KLUE program: CAL calibration constants CLS event classification CUT event cuts DRV derived detector hit information (e.g., drift distances) EVB raw event buffer EVU unpacked raw event data FIT track fitting IDX index and cross reference maps JC job control flags, templates and status words MCR Monte-Carlo generator commons MCS random number seeds for several chains PAT pattern recognition (track finding) SIM simulated event data used to create a raw event buffer SRV detector survey constants SWM track swimming (transport) TKC track-counter association B. Basic program flow -- After program initialization, during the event cycle, the program processes event after event through a series of analysis stages. At each stage data in COMMONs produced by the previous stage are further analysed to produced data which is put in a new set of COMMONs to be fed to the next stage. The basic stages of the KLUE offline program are: 1. MCOEXE : produce /MCR/ with MC particles and decay products 2. MCSEXE : swim /MCR/ particles through detector -> /SWM/ 3. DIGEXE : digitize tracks from /SWM/ -> /SIM/ 4. PAKEXE : produce raw event buffer /EVB/ (via /EVU/) or : read a real event from tape From this point Monte-Carlo and real events have identical paths. 5. UNPEXE : unpack raw event buffer /EVB/ -> /EVU/ 6. DEREXE : derive drift times, energies, etc. /EVU/ -> /DRV/ 7. PATEXE : track finding /DRV/ -> /PTW/. PATPBG and PATMRG are also called to reconstruct showers in the lead glass and find tracks in the muon range- finder. 8. TKCEXE : track-counter association /PT/&/DRV/ -> /TKC/ CLSEXE : event classification /TKC/ -> /CLS/ 9. FITEXE : track fitting /PT/ -> /FIT/ 10. re-TKC and re-CLS 11. write event to tape if it survives this long. C. Program control parameters -- 1. Job control -- SUBROUTINE JCEXEC is controlled from COMMON JCFLAG, which contains the flags that route JCEXEC through a job. COMMON JCFLAG also contains status words which reveal the internal state of the program to the trained eye. For most purposes COMMON JCFLAG is buffered from the user, by COMMON JCUSER, whose contents are used to set the parameters in JCFLAG. COMMON JCUSER contains the so-called JOB TEMPLATE, by which the user selects the path he wishes JCEXEC to take through the processor modules called to analyse an event. Several handy parameters in JCUSER are available in NAMELIST &JMCPRM, read from FORTRAN UNIT 5 by JCEXEC during initialization. (Temporarily, much of the JOB TEMPLATE stuff has been removed from JCFLAG and JCUSER to prevent confusion during startup. G. Irwin 11/85.) The contents of COMMON JCUSER are as follows: "*************************************************************" LOGICAL LGENUS,LRTPUS,LWTPUS; " *** THESE WORDS ARE SET ZERO BEFORE EACH EVENT. CAN BE RESET BY USER." " *** NOMOUS STOP JOB AFTER THIS EVENT IF SET NON-ZERO " " *** IERRUS DROP THIS EVENT DUE TO ERROR IF SET NON-ZERO " " *** KIEVUS USER FLAG TO KILL EVENT IF SET NON-ZERO " " *** JUMPUS IF NON-ZERO, FORCES JCEXEC TO RESUME PROCESSING " " OF CURRENT EVENT JUST BEFORE STAGE = JUMPUS VALUE " " " " *** THESE WORDS ARE INITIALIZED FROM BLOCK DATA. USER CAN RESET THEM," " SUCCESSIVELY, FROM USEPRE AND AGAIN FROM &JCPARM DATA CARDS. " " *** JBTPUS JOB TYPE -- DETERMINES JOB FLOW TEMPLATE " " *** LGENUS TRUE IF USER WANTS MC GENERATOR ACTIVATED " " *** LRTPUS TRUE IF USER WANTS TO READ INPUT TAPE " " *** LWTPUS TRUE IF USER WANTS TO WRITE OUTPUT TAPE " " *** ICUTUS USER SETS NON-ZERO TO ACTIVATE CUTS IN /CUTPRM/ " " CUTEXE WILL BE CALLED JUST BEFORE USER FOR ALL " " PROGRAM STAGES WHERE ISTGFG LE ICUTUS. " " " " *** THESE WORDS ARE INITIALIZED FROM BLOCK DATA. USER CAN RESET THEM," " SUCCESSIVELY, FROM USEPRE, &JCPARM DATA CARDS, USEBEG AND USER. " " *** IPCBUS PRINT CONTROL BIT FLAG " " *** KRUNUS ITH BIT ON TO KILL ANY RUN WITH THE ITH DEFECT " " LIST OF DEFECTS IS IN COMMON/IDXBAD/ " " SET KRUNUS=0 IN USEBEG TO SUPPRESS RUN KILLING " " *** TLFTUS TIME IN SEC TO BE LEFT FOR USEFIN AND JOB WRAPUP " " *** NERMUS NO. OF NON-FATAL JOB CONTROL ERRORS TO BE PRINTED " " *** KILMUS NO. OF EVENT/RUN KILL MESSAGES TO BE PRINTED " " " " *** THE WORDS BELOW ARE SET IN JCEXEC ACCORDING TO THE JOB TEMPLATE " " SPECIFIED BY THE WORD JBTPUS. USER CAN RESET THEM IN USEBEG. " " *** IRECUS BITS FOR TYPES OF RECORD TO ANALYSE " " BIT 0 NOT USED (LOWEST ORDER ONES BIT) " " BIT 1 ON TO ANALYSE EVENT RECORDS " " BIT 2 ON TO ANALYSE BEGIN-RUN-RECORDS " " BIT 3 ON TO ANALYSE PEDESTAL EVENT RECORDS " " BIT 4 ON TO ANALYSE PULSER EVENT RECORDS " " *** ISTGUS BIT FLAG FOR GROUP STAGES AFTER WHICH TO CALL USER " " SAME BIT PATTERN AS NBLGUS " " *** NBLGUS USER TEMPLATE SETS BITS TO ENABLE STAGE PROCESSING " " BIT 0 NOT USED (LOWEST ORDER ONES BIT) " " BIT 1 ON FOR RAW MONTE-CARLO GROUP (MCR) " " BIT 2 ON FOR SWIM GROUP (SWM) " " BIT 3 ON FOR SIMULATED DETECTOR RESPONSE GROUP (SIM)" " BIT 4 ON FOR INPUT BUFFER GROUP (EVB) " " BIT 5 ON FOR UNPACKED RAW EVENT DATA GROUP (EVU) " " BIT 6 ON FOR DERIVED EVENT DATA GROUP (DRV) " " BIT 7 ON FOR PATTERN RECOGNITION GROUP (PT) " " BIT 8 ON FOR TRACK-COUNTER ASSOC. GROUP (TKC) " " BIT 9 ON FOR TRACK FITTING GROUP (FT) " " *** NBLCUS(31) BITS TO ENABLE SUB-STAGES WITHIN EACH STAGE " " *** KALGUS USER TEMPLATE SETS BITS FOR GROUPS TO VETO FROM TAPE " " SAME BIT PATTERN AS NBLGUS " " *** KALCUS(31) BITS FOR COMMONS TO VETO FROM TAPE IN EACH GROUP " " *** IOTGUS USER TEMPLATE SETS BITS TO WRITE GROUPS ON O/P TAPE " " SAME BIT PATTERN AS NBLGUS " " *** IOTCUS(31) BITS FOR COMMONS TO WRITE ON O/P TAPE IN EACH GROUP " " " "*************************************************************" 2. Monte-Carlo control -- Several parameter COMMONs are used to control the Monte- Carlo pieces. Two of them are addressable by NAMELIST reads during program initialization. In addition there are commons for PARTICLE DATA, DECAY LIST and APERTURE LIST which are filled from formatted data cards files, for which there are default versions on the program library. The user may choose to read these lists from modified versions in SOURCE, instead of from the library. The two COMMONs addressable by NAMELIST are: COMMON/MCRPRM/ "JOB CONTROL PARAMETERS FOR MONTE-CARLO." "ADDRESSABLE FROM NAMELIST &JMCPRM" "*****************************************************************" " *** KRUNJM RUN NUMBER FOR THIS MC RUN -- DETERMINES UPDATES" " *** MXEVJM MAXIMUM NUMBER OF MCOGEN CALLS FROM MCOEXE" " *** SEEDJM MASTER SEED FOR RESETTING /MCSEED/ IN MCOBEG" " IF SEEDJM = 0.D0, NO RESETTING IS DONE." " *** LJDKJM LOGICAL FLAG TO EXECUTE DECAYS FROM MCODKN AND MCSEXE." " DECAYS ARE ACCORDING TO PARTICLE DECAY TABLES /MCRLST/" " *** LJNUJM FALSE TO SUPPRESS DECAY NEUTRINOS IN TBNKRM FROM MCDDKY" " *** LJELJM LOGICAL TRUE TO CALL DE/DX LOSS (SWMELS)" " *** ISCTJM MULTIPLE SCATTERING FLAG...(MCSCAT) CALLED FROM MCSEXE" " =0, IF MULTIPLE SCATTERING IS OFF" " =1, IF MULTIPLE SCATTERING IS GAUSSIAN" " =2, IF MULTIPLE SCATTERING IS NON-GAUSSIAN" " =3, IF MULTIPLE SCATTERING IS WEIGHTED NON-GAUSSIAN" " *** IGENJM NUMBER OF EVENT GENERATOR TO CALL: =1 FOR MCOGE1, ETC." " *** IDBGJM DEBUG PRINT FLAG." " 0=SUPPRESS ALL, 1=ERROR PRINTOUT" " 2=SUMMARY INFO, 3=STEP-BY-STEP" " 4=EVERYTHING" " *** IDEVJM DEBUG PRINT UNIT." "*****************************************************************" COMMON/MCRGP1/ "PARAMETERS FOR MONTE-CARLO KAON GENERATOR#1" "ADDRESSABLE FROM NAMELIST &MCGPRM" "*****************************************************************" " *** PKLOPG LOWER LIMIT FOR KAON MOMENTUM" " *** PKHIPG UPPER LIMIT FOR KAON MOMENTUM" " *** NKDKGP MAXIMUM NUMBER OF K0L DECAYS PER EVENT" " *** RATEPG NUMBER OF K0L IN MOM. AND Z BITE DECAYING IN ONE SPILL." " *** SPILPG LENGTH OF SPILL IN SECONDS." " *** TLIMPG(2) SIDES OF NOISE TIME WINDOW ABOUT MAIN EVENT AT T=0." " *** TKDKPG AVERAGE TIME BETWEEN K DECAYS IN MULTIPLE EVENT (NSEC)" " THIS IS CALCULATED FROM RATEPG AND SPILPG IN MCOIN1." "*****************************************************************" If NKDKGP (default=1,max=10) is > 1, additional noise KAONs are produced at successive time intervals in the target. The first KAON is always produced at t=0. and the successive KAONs step outward by random intervals drawn from the formula TSTEP=-TKDKPG*ln(R), where 0.<R<1. and TKDKPG is the average time between KAONS from the target, calculated from the USER supplied (or default) parameters RATEPG and SPILPG, the KAON flux and spill length, respectively. The length of the event time window TLIMPG(2) and the maximum-number-of-KAONS NKDKGP cut off the generation of noise KAONs which are produced in an otherwise statistical way. In addition the COMMON SRVTGT may be changed in USEPRE to control the targetting angle. USEPRE must be used instead of USEBEG, as USEPRE is called before the rest of the program is initialized and USEBEG is called afterwards. In this case the KAON momentum spectrum would already have been initialized using the default (currently zero) targetting angle by the time USEBEG was called. The parameters of SRVTGT are as follows: "****************************************************************" " *** RTARTS(3) X,Y,Z OF TARGET CENTER" " *** TDIMTS(3) X,Y,Z DIMENSIONS OF TARGET" " *** BDVGTS(2) X AND Y FULL-ANGLES OF BEAM DIVERGENCE" " *** RCOLTS(2) X AND Y OF CENTER OF END OF EFFECTIVE " " COLLIMATOR 10 METERS FROM TARGET" " *** TANGTS TARGETTING ANGLE" " *** CTARTS COSINE OF TARGETTING ANGLE" " *** STARTS SINE OF TARGETTING ANGLE" "****************************************************************" The formatted data card files which define DECAYS and APERTURES have control information implicit in them: a. The DECAY table contains several words for each particle in the list to control the decays of that particle. Some of these words are defined in comment lines in the data cards themselves: ** 1) FOR EACH DECAYING PARTICLE NBR IS THE NUMBER OF DECAY LINES ** TO BE READ. IF THERE ARE MORE THAN NBR LINES, THE REMAINDER ** ARE SKIPPED OVER IN THE SEARCH FOR THE NEXT "DECAY" HEADER. ** THE DECAYS CAN BE IN ANY ORDER, BUT MUST HAVE THE DECAY TYPE ** NUMBERED IN THE CONVENTION EXPECTED BY THE DECAY ROUTINES. ** 2) DKV1/DKVN ARE DEFINED FOR TRACKS FROM THE MAIN VERTEX #1, AND ** FOR NOISE VERTICES NOS 2-10, RESPECTIVELY. THESE FLAGS ARE: ** 0 FOR NO DECAY ALLOWED. ** +N FOR ONLY DECAY TYPE N ALLOWED. ** -1 FOR DECAY BRANCHING RATIOS TO BE TAKEN FROM TABLE. ** 3) LZ1/LZN ARE DEFINED FOR TRACKS FROM THE MAIN VERTEX #1, AND ** FOR NOISE VERTICES NOS 2-10, RESPECTIVELY. THESE FLAGS ARE: ** T TO FORCE PARTICLE TO DECAY BETWEEN DZ- AND DZ+. IF ** A PARTICLE IS CREATED BEYOND DZ+, IT DECAYS NORMALLY. ** F TO ALLOW PARTICLE TO DECAY NORMALLY. ** 4) DZ-1/N AND DZ+1/N ARE THE Z LAB LIMITS OF THE ALLOWED PARTICLE ** DECAY REGION. THE FIRST PAIR DZ-/+1 IS FOR THE PARTICLES ** WITH PRIMARY KAON ANCESTOR AND THE SECOND PAIR DZ-/+N IS ** FOR PARTICLES WITH NOISE KAON ANCESTORS. b. The decay branches are specified in the DECAY TABLE. Each branch is identified by a mnemonic list for the daughter particles. The branch number for a given decay is hard wired in the decay routines and may not be changed on the DECAY data cards, even though the order of decay branch cards may be changed and individual decays may be dropped, commented out with ** in columns 1/2 or truncated by changing the number-of-branches parameter on the parent name card which heads the decay list. c. The APERTURE cards determine the lab Z position of each of the detector subunits. The relative geometry of each detector piece is described in the survey (SRV...) COMMON for that detector element. For the purpose of Monte-Carlo studies, a detector subsystem can be moved in Z by changing the appropriate APERTURE data card, or dropped entirely from the experiment by commenting out its APERTURE card with ** in columns 1/2. The X and Y dimensions of each APERTURE are also given for the purposes of Monte-Carlo swim cuts. 3. Control of other subunits -- parameter commons ...PRM Each module of the program has its own control parameters. These are kept in COMMONs and can be set from USEBEG during job initialization and reset dynamically from SUBROUTINE USER during event processing. Some names of these control parameter commons and the program modules they control are listed here: COMMON driver for MODULE CUTPRM defines cuts for each stage -- CUTEXE SWMPRM directs the generic swimmer -- SWMEXE SIMPRM for digitization -- DIGEXE PATPRM governs the track finding -- PATEXE FITPRM for the track fitting -- FITEXE TKCPRM for track-counter assocn. -- TKCPRM CLSPRM for event classification -- CLSEXE D. Description of program modules Each of the program stages is described in more detail below: Program Stage 1 -- Monte-Carlo Event Generation Driver SUBROUTINE MCOEXE calls MCOGE1 which fills COMMON/MCRDAT/ with 4-vectors and various pointer and indexing words for the particles generated in the event. MCOEXE calls MCODKN to decay particles which do not have to be swum through the magnetic field. This includes the K0L itself and PI0's from its decay. The expected lifetime of each particle is determined and put into /MCRDAT/ at the same time the other properties of the particle are filled in. After stage 1 is completed, the charged secondaries still remain undecayed and gammas remain unconverted. RANDOM NUMBERS -- The conventional way to do random numbers for now is to put common MCSEED in the subroutine and take one of the ASEED or BSEED for your purpose. Then use: CALL GGUBS(ASEEDn,m,RNUM); to fill RNUM(m) with m uniform random numbers between 0. and 1. CALL GGNML(ASEEDn,m,RNUM); to fill RNUM(m) with m normal random numbers CALL GGPON(RLAM,ASEEDn,m,KNUM,IER); to fill KNUM(m) with m or GGPOS Poisson deviates with Poisson parameter RLAM. IER=129 returned for bad RLAM.LE.0. GGPON is used where RLAM changes often and GGPOS where RLAM changes seldom. Also, to generate a single random number instead of a set: X = GGUBFS(ASEEDn); generates one uniform deviate from 0. to 1. Y = GGNQF(ASEEDn); generates one normal deviate All of these routines change the seed to the next value in the chain, so the COMMON/MCSEED/ always contains the current value. Later this scheme can be replaced by the MORTRAN MACRO scheme used by EGS, if the present one proves unworthy. Program Stage 2 -- Monte-Carlo Tracks Swum Through the Detector Monte-Carlo-Swim driver SUBROUTINE MCSEXE sets up the track data from /MCRDAT/ for input to the generic swim routine SWMEXE, which fills /SWMTRK/ with a bank of points along each swum track. Since this common will be overwritten by later calls to the SWMEXE from subsequent stages of the program, the Monte-Carlo-Swim data is also saved in COMMON/SWMMCR/, which can be written to tape, for example. Program Stage 3 -- Monte-Carlo Digitization Monte-Carlo digitization is managed by the driver SUBROUTINE DIGEXE under the influence of parameter COMMON SIMPRM. Each detector element is digitized in turn by calls to two subroutines for each detector element: LOGICAL BTEST; IF (BTEST(ISIMSM,1)) <CALL DIGCER; CALL UMCCER;> "cerenkov" IF (BTEST(ISIMSM,3)) <CALL DIGMHO; CALL UMCMHO;> "muon hodoscope" IF (BTEST(ISIMSM,4)) <CALL DIGTSC; CALL UMCTSC;> "trigger scint." IF (BTEST(ISIMSM,5)) <CALL DIGWIR; CALL UMCWIR;> "wire chambers" IF (BTEST(ISIMSM,6)) <CALL DIGPBG; CALL UMCPBG;> "lead glass" IF (BTEST(ISIMSM,7)) <CALL DIGMRG; CALL UMCMRG;> "mu rangefinder" IF (BTEST(ISIMSM,8)) <CALL DIGTRL; CALL UMCTRL;> "trigger logic" The bits in variable ISIMSM in COMMON SIMPRM can be set by the user in USEBEG to enable the calls to the subroutines for each detector element. ISIMSM is set to ZFFFFFFFF (all detectors on) by default. For each detector element xxx, digitization is done with two loops, a track loop in DIGxxx and a subsequent counter/wire loop in UMCxxx to combine all the hits on a given counter/wire into one ADC+TDC response. DIGxxx fills /SIMxxx/ from /SWMTRK/, using /CALxxx/ and /SRVxxx/. UMCxxx fills /EVUyyy/ from /SIMxxx/, using /CALxxx/. The yyy in /EVUyyy/ stands for WIR for wire chambers, and for /LAT/ for the trigger logic. For the counter systems, there are two output commons: EVUADC and EVUTDC, which contain a single bank of ADC's or TDC's for all counters. COMMON IDXUCT contains pointers to the ADC's and TDC's for each counter subsystem in EVUADC and EVUTDC. The pointers are accessed mneumonically with MORTRAN MACRO names $$xxx, defined in file LATMAC MORTMAC/MCR. In DIGxxx there is an outer loop over tracks appearing in COMMON SWMTRK. For each of these tracks, SWMTRK has a set of points identified by aperture number with (x,y,z,t) and (dircosx,dircosy,dircosz) at the intersection of the track with the aperture plane. There is an array IHTSWM(iapt,itrk) in /SWMTRK/ which points to the hit in BNKSWM(i,ihit) corresponding to a given (aperture,track). IHTSWM elements are set zero for non-existent (aperture,track) combinations. COMMON SRVSWM has a set of variables, one for each aperture, giving the current aperture number defined for each aperture type, such as IwirAP(5) for the five wire planes or ICERAP for the Cerenkov aperture. These variables are set during initialization (UPSWIM) from the APERTURE STUFF/MSC data cards. These variables should be used for the aperture numbers as there is no hardwired convention for aperture numbers in the program. The generic DIGxxx does the following steps for each track in the loop: 1) Loop over each of the counter or wire modules which can be hit. 2) For each counter or wire hit, create an entry in the hit bank BKHTxx(i,ihit) of /SIMxxx/. All hits for a given track are contiguous in BKHTxx. 3) Counting variables NHITxx and NHTKxx(itrk) are incremented for each new hit added to BKHTxx. 4) Offset variable IOTKxx(itrk) is set to the value of the ihit index-1 for the first hit on each track. Then one can find the nth hit for track itrk in BKHTxx(i,IOTKxx(itrk)+n), since each track's hits are contiguous. 5) Since the /SWMTRK/ (x,y,z,t) of the aperture intersection is not necessarily the same as the place where the track actually crosses the counter, the track must be projected to the counter plane and the projected (x,y,z,t) entered in /SIMxxx/'s BKHTxx(8/11,ihit). The track direction cosines are entered in BKHTxx(12/14,ihit). /SIMWIR/ has DOCA's of tracks to wires hit. 6) One uses the data in /SRVxxx/ to determine which counter is hit. This goes into BKHTxx(1,ihit). The quality of the hit is put in BKHTxx(5,ihit), according to tolerances in /SIMPRM/. 7) To enable one to find all the hits in a given counter, variable NHCTxx(ictr) in /SIMxxx/ is incremented for each hit in that counter. L1CTxx(ictr) contains the ihit index for the first hit in the counter. BKHTxx(2,ihit) contains the index of the next hit in that counter. When there are no further hits in the counter, BKHTxx(2,ihit) is set to zero for the last hit. In practice it is convenient for DIGxxx to put the index of the last hit encountered for each counter in L1CTxx(ictr) and set BKHTxx(2,ihit) zero for the first hit filled in the track loop. This backwards pointing sequence has no practical consequence. A similar pointing scheme is done for each wire. 8) Energy deposited in the counter is filled in BKHTxx. For the three scintillator systems, there are also words for the energy recorded by each tube. This is calculated by multiplying the energy deposited by an attenuation factor, using the attenuation coefficient from /CALxxx/. 9) Times at the tube are calculated using the effective speed of light in the counter from /CALxxx/. 10) Enabling flags for inefficiency, smearing and noise hits are supplied in /SIMPRM/. These effects should be included as appropriate in DIGxxx or UMCxxx, but always keyed on the /SIMPRM/ flags so that they can be turned off either for "exact Monte Carlo playback" or for real event reconstruction. The generic SUBROUTINE UMCxxx loops over counters or wires and finds all hits on each one from /SIMxxx/. For each tube or wire in the system, ADC and TDC responses from all hits combined are obtained. In the initial program this can be done to first order for each counter by summing all hit energies and taking the time of the first hit. Since the tube high voltages will be adjusted to make the tube response match the dynamic range of the ADC's, one can presumably quantify the pulse height somewhat vaguely in units of MIPS (minimum ionizing particles), roughly the value expected from most particles, and expect the sensitivity of the system to be a few ADC counts per MIP. The sensitivities for the 2-slope ADC's are found in COMMON/CALxxx/. TDC sensitivities are found in the same place. PH slew and distance corrections to the TDC value are parameterized in CALxxx as well, but can be ignored in early versions of the program. COMMON/SIMTRL/ contains TDC start and ADC gate start times and COMMON/CALADC/ contains pedestals. Pointers to the ADC's and TDC's for each counter system are found in COMMON/IDXUCT/. The mneumonic $$xxx MORTRAN MACROS from file LATMAC MORTMAC are used to reference counter system xxx in /IDXUCT/. The wire chambers do not use /IDXUCT/ as they have their own COMMON/EVUWIR/. Program Stage 4 -- Obtaining the Raw Event Buffer /EVBFIN/ In a real data job, stage 4 is the first stage executed and /EVBFIN/ is read from tape. In a Monte Carlo job it is packed by SUBROUTINE PAKEXE from the unpacked commons /EVULAT/, /EVUADC/, /EVUTDC/, /EVUWIR/ and /EVUHDR/ produced by subroutines UMCxxx in stage 3. Program Stage 5 -- Unpacking the Raw Event Buffer /EVBFIN/ is unpacked from driver UNPEXE into the commons /EVULAT/ /EVUADC/, /EVUTDC/, /EVUWIR/ and /EVUHDR/. The data written into these commons from the UMCxxx routines in stage 3 are overwritten. One can jump over stages 4 and 5 in a Monte-Carlo job, thus pre- venting the UMC... versions of these commons from being destroyed. This is done by putting JUMPUS=6; (COMMON/JCUSER/) in USER stage 3. The program will then skip from stage 3 to stage 6, bypassing stages 4 and 5. Program Stage 6 -- Preparing the Derived Commons Each detector element has a COMMON DRVxxx of derived information calculated by the DERxxx routines (called by DEREXE) from the /EVU.../ commons as input, and using the /CALxxx/ and /SRVxxx/ commons. The algorithms in the DERxxx routines are the exact inverses of the DIGxxx/UMCxxx algorithms. Program Stage 7 -- Pattern Recognition (Track Reconstruction) The commons /PTTRAK/ and /PTWIRE/ are filled with track trajectory parameters and track-wire hit assignments, respectively, by SUBROUTINE PATEXE working from input commons /EVUWIR/ and /DRVWIR/. Program Stage 8 -- Track Counter Association (Event Reconstruction) The tracks found in stage 7 and parametrized as trajectories in COMMON PTTRAK are swum through the detector with the same swim routine SWMEXE used in stage 2, but with multiple scattering turned off. The DIGxxx routines are then called to fill the /SIMxxx/ commons with predictions for the detector response for various hypotheses about particle identification. Then the /DRVxxx/ commons containing the actual detector responses are compared with with the /SIMxxx/ predictions and the /TKC.../ commons are filled with results of this analysis, including the particle identification hypothesis testing. Finally the event is classified into an event type category in the /CLS.../ commons. At this stage the DIGxxx routines are called with noise, inefficiency and resolution smearing turned off. The UMCxxx routines are not called. Program Stage 9 -- Track Fitting For selected events from stage 8, /PTTRAK/ tracks are fitted using a fancy algorithm. The results go in /FTTRAK/ and /FTWIRE/. Track-counter association and event classification are re-done with the more exact tracks. Program Stage 10 -- DST Abstraction An abbreviated DST (data summary tape) common is filled for the whole event. This is condensed and packed information. Program Stage 11 -- Tape Writing Any set of program commons, including, but not limited to the /DST.../ common can be written out before the event is abandoned. The user can jump to this stage from any previous stage without executing the intervening stages, by using variable JUMPUS in COMMON/JCUSER/. Single event display facility To get a picture of an event at any stage, one can call DSPEXE from SUBROUTINE USER. COMMON DSPPRM contains parameters and options which the user can set before any DSPEXE call to choose the type of display, the display device, the views and the input data which should be used for the event, This input data may be from any of several sources: /SWMMCR/ to show track trajectories swum from /MCRDAT/ /SWMTRK/ to show track trajectories swum from /PTTRAK/ or /FTTRAK/ /DRV.../ commons for counter systems to show real hits /SIM.../ commons for counter systems to show simulated hits /DRVWIR/ to show actual wire hits /SIMWIR/ to show expected wire hits An early task might be to get an idea what kinds of displays might be useful and define a COMMON DSPPRM to accomodate the possibilities. Jacobo Konigsberg has prepared this helpful summary of the main SUBROUTINEs and COMMONs to orient the new user. GMI has made a few changes. A brief description of the function of the main routines: I- KLUEJOB.COM on the VAX , KLUE JOB on IBM - It's the actual JOB: links,runs,assigns,deletes, etc. - Contains the SOURCE code for SUBROUTINE USER. - Contains the Data Cards used by the job. - Contains a small main program which calls JCEXEC. The MAIN program also initializes the time limit clock if one is desired and reserves space in blank common for HBOOK. Error handling routines (ERRSET) are initialized here. II- JCEXEC - Called from MAIN PROGRAM. - It's the job control executive, following flags from /JCUSER/. - Calls MCOBEG and USEBEG to initialize once-per-job variables. - Cycles through events, each cycle divided in stages, with a call to SUBROUTINE USER at each stage. SUBROUTINE USER can kill events (KIEVUS) or stop the job (NOMOUS) through /JCUSER/. - Checks for "job-stops" and time limits. III- MCOBEG - Entry point in MCOEXE, called from JCEXEC at initialization. - Reads in Data Cards for Monte Carlo control: &JMCPRM. - Sets up Particle and Decay Tables(MCDINI) from data cards. - Calls MCOIN1 to initialize the specific (KAON) event generator and the KAON spectrum (MCOPKI). IV- USEPRE/USEBEG - ENTRIES in USER called by JCEXEC before/after initialization. - Sets user Flags for this job. - Initializes some variables in PRM commons. - Books histograms(USEBEG). V- MCOEXE - Called in stage 1 from JCEXEC. - Drives the Monte Carlo event generation (calls MCOGE1). - Decays particles at the kaon generation point (calls MCODKN). - Returns control to JCEXEC which calls USER. VI- MCSEXE - Called in stage 2 from JCEXEC - Swims the particles through the detector (calls SWMEXE). - Decays particles while swimming (calls MCDDKY). - Returns control to JCEXEC which calls USER. VII- MCOPKI - Called from ENTRY MCOIN1 in MCOGE1. - Generates the kaon spectrum during initialization. VIII- MCOGE1 - Called by MCOEXE to generate primary KAON(s) for each event. - Selects the proton interaction point in the target. - Generates the momentum and direction cosines for the KAON. - Can generate multiple KAON events. IX- MCODKN - Called from MCOEXE after MCOGE1 for each event. - Chooses the KAON lifetime and decay point and decays it. - Decays particles at the KAON's vertex (calls MCDDKY). - Checks if event makes it through first critical aperture. X- SWMEXE - Called by MCSEXE and other future processors (FITEXE,TKCEXE). - Transports particles through all apertures. - Checks for different cuts (for MCSEXE call only). Cuts not sufficiently differentiated for now. - Magnetic field constant for now. - Multiple scattering before and at aperture is included. - Energy loss absent for now. - No gamma conversion yet. - No nuclear interactions yet. - Radiation losses are not included yet. - Returns to MCSEXE if particle decays while swimming. XI- MCDDKY - Called from MCODKN(stage 1) and MCSEXE(stage 2) to do decays. - Selects decay branch. - Updates particle counters in /MCRDAT/. - Calls the appropiate general purpose decay routines. - Boosts the decay products. XII- USER - Has the same stage structure as JCEXEC and its called by it at each stage. The code is written by the user. - Analyses event data calculated at each stage. - Calls HFILL to increment histograms and plots. - Sets options to kill event or stop job at any stage. XIII- USEFIN - ENTRY in USER called by JCEXEC at the end of the job. - User written code can dump information on the whole job. - Outputs histograms. Common Blocks: CUTSUM (CT) - Cut statistics by track and aperture. JCUSER (US) - Job control flags and templates for the user. The templates are removed for now. MCRDAT (RM) - Raw Monte Carlo event data. MCREPT (PT) - End-point data for MC track terminations. SRVMAG (MG) - Survey constants for magnetic field. SRVSWM (AP) - Survey constants for swimming by aperture. SRVTGT (TS) - Target survey constants. SWMTRK (SWM) - Complete swim information for all apertures and significant intermediate points. This COMMON is effectively a scratch space for SWMTRK to overwrite from a new set of tracks at each stage it is called. Used to output swim data to MCSEXE(for DIGEXE), FITEXE and TKCEXE. SWMMCS (MCS) - An abridged copy of SWMTRK created by a call to SWMSAV from MCSEXE after SWMEXE fills SWMTRK. This COMMON, which need not be filled if option flag LJSVSP is set FALSE in COMMON SWMPRM, prevents the Monte-Carlo swim data from being destroyed by subsequent stage calls to SWMEXE in the case where SWMMCS is to be written to tape.