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. "© FROM filename filetype"
The IBM version of 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)
:F3: FORMAT(/(5X,'VTX.#',I3,' BEAM PID=',I5,' XYZVRM=',4F10.3,
' PVBMRM=',4F10.6));
IF (NLTKRM.GT.0)
: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)
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. "cerenkov"
IF (BTEST(ISIMSM,3)) "muon hodoscope"
IF (BTEST(ISIMSM,4)) "trigger scint."
IF (BTEST(ISIMSM,5)) "wire chambers"
IF (BTEST(ISIMSM,6)) "lead glass"
IF (BTEST(ISIMSM,7)) "mu rangefinder"
IF (BTEST(ISIMSM,8)) "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.