ISAJET/doc/main.doc

   1 \newpage
   2 \section{Main Program\label{MAIN}}
   3
   4       A main program is not supplied with ISAJET. To generate events
   5 and write them to disk, the user should provide a main program which
   6 opens the files and then calls subroutine ISAJET. In the following
   7 sample, i,j,m,n are arbitrary unit numbers.
   8
   9       Main program for VMS:
  10 \begin{verbatim}
  11       PROGRAM RUNJET
  12 C
  13 C          MAIN PROGRAM FOR ISAJET ON BNL VAX CLUSTER.
  14 C
  15       OPEN(UNIT=i,FILE='$2$DUA14:[ISAJET.ISALIBRARY]DECAY.DAT',
  16      $STATUS='OLD',FORM='FORMATTED',READONLY)
  17       OPEN(UNIT=j,FILE='myjob.dat',STATUS='NEW',FORM='UNFORMATTED')
  18       OPEN(UNIT=m,FILE='myjob.par',STATUS='OLD',FORM='FORMATTED')
  19       OPEN(UNIT=n,FILE='myjob.lis',STATUS='NEW',FORM='FORMATTED')
  20 C
  21       CALL ISAJET(+-i,+-j,m,n)
  22 C
  23       STOP
  24       END
  25 \end{verbatim}
  26
  27       Main program for IBM (VM/CMS)
  28 \begin{verbatim}
  29       PROGRAM RUNJET
  30 C
  31 C          MAIN PROGRAM FOR ISAJET ON IBM ASSUMING FILES HAVE BEEN
  32 C          OPENED WITH FILEDEF.
  33 C
  34       CALL ISAJET(+-i,+-j,m,n)
  35 C
  36       STOP
  37       END
  38 \end{verbatim}
  39
  40       Main program for Unix:
  41 \begin{verbatim}
  42       PROGRAM RUNJET
  43 C
  44 C          Main program for ISAJET on Unix
  45 C
  46       CHARACTER*60 FNAME
  47 C
  48 C          Open user files
  49       READ 1000, FNAME
  50 1000  FORMAT(A)
  51       PRINT 1020, FNAME
  52 1020  FORMAT(1X,'Data file      = ',A)
  53       OPEN(2,FILE=FNAME,STATUS='NEW',FORM='UNFORMATTED')
  54       READ 1000, FNAME
  55       PRINT 1030, FNAME
  56 1030  FORMAT(1X,'Parameter file = ',A)
  57       OPEN(3,FILE=FNAME,STATUS='OLD',FORM='FORMATTED')
  58       READ 1000, FNAME
  59       PRINT 1040, FNAME
  60 1040  FORMAT(1X,'Listing file   = ',A)
  61       OPEN(4,FILE=FNAME,STATUS='NEW',FORM='FORMATTED')
  62 C          Open decay table
  63       READ 1000, FNAME
  64       OPEN(1,FILE=FNAME,STATUS='OLD',FORM='FORMATTED')
  65 C
  66 C          Run ISAJET
  67       CALL ISAJET(-1,2,3,4)
  68 C
  69       STOP
  70       END
  71 \end{verbatim}
  72
  73       The arguments of ISAJET are tape numbers for files, all of which
  74 should be opened by the main program.
  75
  76       \verb|TAPEi|: Decay table (formatted). A positive sign prints
  77 the decay table on the output listing. A negative sign suppress
  78 printing of the decay table.
  79
  80       \verb|TAPEj|: Output file for events (unformatted). A positive
  81 sign writes out both resonances and stable particles. A negative sign
  82 writes out only stable particles.
  83
  84       \verb|TAPEm|: Commands as defined in Section 6 (formatted).
  85
  86       \verb|TAPEn|: Output listing (formatted).
  87
  88 \noindent In the sample jobs in Section 3, TAPEm is the default
  89 Fortran input, and TAPEn is the default Fortran output.
  90
  91 \subsection{Interactive Interface}
  92
  93       To use the interactive interface, replace the call to ISAJET in
  94 the above main program by
  95 \begin{verbatim}
  96       CALL ISASET(+-i,+-j,m,n)
  97       CALL ISAJET(+-i,+-j,m,n)
  98 \end{verbatim}
  99 ISASET calls DIALOG, which prompts the user for possible commands,
 100 does a limited amount of error checking, and writes a command file on
 101 TAPEm. This command file is rewound for execution by ISAJET. A main
 102 program is included in patch ISARUN to open the necessary files and to
 103 call ISASET and ISAJET.
 104
 105 \subsection{User Control of Event Loop}
 106
 107       If the user wishes to integrate ISAJET with another program and
 108 have control over the event generation, he can call the driving
 109 subroutines himself. The driving subroutines are:
 110
 111       \verb|ISAINI(+-i,+-j,m,n)|: initialize ISAJET. The arguments are
 112 the same as for subroutine ISAJET.
 113
 114       \verb|ISABEG(IFL)|: begin a run. IFL is a return flag: IFL=0
 115 for a good set of commands; IFL=1001 for a STOP; any other value means
 116 an error.
 117
 118       \verb|ISAEVT(I,OK,DONE)| generate event I. Logical flag OK
 119 signifies a good event (almost always .TRUE.); logical flag DONE
 120 signifies the end of a run.
 121
 122       \verb|ISAEND|: end a run.
 123
 124 \noindent There are also subroutines provided to write standard ISAJET
 125 records, or Zebra records if the Zebra option is selected:
 126
 127       \verb|ISAWBG| to write a begin-of-run record, should be called
 128 immediately after ISABEG
 129
 130       \verb|ISAWEV| to write an event record, should be called
 131 immediately after ISAEVT
 132
 133       \verb|ISAWND| to write an end-of-run record, should be called
 134 immediately after ISAEND
 135
 136       The control of the event loop is somewhat complicated to
 137 accomodate multiple evolution and fragmentation as described in
 138 Section 11. Note in particular that after calling ISAEVT one should
 139 process or write out the event only if OK=.TRUE. The check on the DONE
 140 flag is essential if one is doing multiple evolution and
 141 fragmentation. The following example indicates how events might be
 142 generated, analyzed, and discarded (replace \verb|&| by \verb|+|
 143 everywhere):
 144 \begin{verbatim}
 145       PROGRAM SAMPLE
 146 C
 147 &SELF,IF=IMPNONE
 148       IMPLICIT NONE
 149 &SELF
 150 &CDE,ITAPES
 151 &CDE,IDRUN
 152 &CDE,PRIMAR
 153 &CDE,ISLOOP
 154 C
 155       INTEGER JTDKY,JTEVT,JTCOM,JTLIS,IFL,ILOOP
 156       LOGICAL OK,DONE
 157       SAVE ILOOP
 158 C---------------------------------------------------------------------
 159 C>         Open files as above
 160 C>         Call user initialization
 161 C---------------------------------------------------------------------
 162 C
 163 C          Initialize ISAJET
 164 C
 165       CALL ISAINI(-i,0,m,n)
 166     1 IFL=0
 167       CALL ISABEG(IFL)
 168       IF(IFL.NE.0) STOP
 169 C
 170 C          Event loop
 171 C
 172       ILOOP=0
 173   101 CONTINUE
 174         ILOOP=ILOOP+1
 175 C          Generate one event - discard if .NOT.OK
 176         CALL ISAEVT(ILOOP,OK,DONE)
 177         IF(OK) THEN
 178 C---------------------------------------------------------------------
 179 C>         Call user analysis for event
 180 C---------------------------------------------------------------------
 181         ENDIF
 182       IF(.NOT.DONE) GO TO 101
 183 C
 184 C          Calculate cross section and luminosity
 185 C
 186       CALL ISAEND
 187 C---------------------------------------------------------------------
 188 C>         Call user summary
 189 C---------------------------------------------------------------------
 190       GO TO 1
 191       END
 192 \end{verbatim}
 193
 194 \subsection{Multiple Event Streams}
 195
 196       It may be desirable to generate several different kinds of events
 197 simultaneously to study pileup effects. While normally one would want
 198 to superimpose minimum bias or low-pt jet events on a signal of
 199 interest, other combinations might also be interesting. It would be
 200 very inefficient to reinitialize ISAJET for each event. Therefore, a
 201 pair of subroutines is provided to save and restore the context, i.e.
 202 all of the initialization information, in an array. The syntax is
 203 \begin{verbatim}
 204       CALL CTXOUT(NC,VC,MC)
 205       CALL CTXIN(NC,VC,MC)
 206 \end{verbatim}
 207 where VC is a real array of dimension MC and NC is the number of words
 208 used, about 20000 in the standard case. If NC exceeds MC, a warning is
 209 printed and the job is terminated. The use of these routines is
 210 illustrated in the following example, which opens the files with names
 211 read from the standard input and then superimposes on each event of
 212 the signal sample three events of a pileup sample. It is assumed that
 213 a large number of events is specified in the parameter file for the
 214 pileup sample so that it does not terminate.
 215 \begin{verbatim}
 216       PROGRAM SAMPLE
 217 C
 218 C          Example of generating two kinds of events.
 219 C
 220       CHARACTER*60 FNAME
 221       REAL VC1(20000),VC2(20000)
 222       LOGICAL OK1,DONE1,OK2,DONE2
 223       INTEGER NC1,NC2,IFL,ILOOP,I2,ILOOP2
 224 C
 225 C          Open decay table
 226       READ 1000, FNAME
 227 1000  FORMAT(A)
 228       OPEN(1,FILE=FNAME,STATUS='OLD',FORM='FORMATTED')
 229 C          Open user files
 230       READ 1000, FNAME
 231       OPEN(3,FILE=FNAME,STATUS='OLD',FORM='FORMATTED')
 232       READ 1000, FNAME
 233       OPEN(4,FILE=FNAME,STATUS='NEW',FORM='FORMATTED')
 234       READ 1000,FNAME
 235       OPEN(13,FILE=FNAME,STATUS='OLD',FORM='FORMATTED')
 236       READ 1000,FNAME
 237       OPEN(14,FILE=FNAME,STATUS='NEW',FORM='FORMATTED')
 238 C
 239 C          Initialize ISAJET
 240       CALL ISAINI(-1,0,3,4)
 241       CALL CTXOUT(NC1,VC1,20000)
 242       CALL ISAINI(-1,0,13,14)
 243       IFL=0
 244       CALL ISABEG(IFL)
 245       IF(IFL.NE.0) STOP1
 246       CALL CTXOUT(NC2,VC2,20000)
 247       ILOOP2=0
 248       CALL user_initialization_routine
 249 C
 250 1     IFL=0
 251       CALL CTXIN(NC1,VC1,20000)
 252       CALL ISABEG(IFL)
 253       CALL CTXOUT(NC1,VC1,20000)
 254       IF(IFL.NE.0) GO TO 999
 255       ILOOP=0
 256 C
 257 C          Main event
 258 C
 259 101   CONTINUE
 260         ILOOP=ILOOP+1
 261         CALL CTXIN(NC1,VC1,20000)
 262         CALL ISAEVT(ILOOP,OK1,DONE1)
 263         CALL CTXOUT(NC1,VC1,20000)
 264         IF(.NOT.OK1) GO TO 101
 265         CALL user_analysis_routine
 266 C
 267 C          Pileup
 268 C
 269         CALL CTXIN(NC2,VC2,20000)
 270         I2=0
 271 201     CONTINUE
 272           ILOOP2=ILOOP2+1
 273           CALL ISAEVT(ILOOP2,OK2,DONE2)
 274           IF(OK2) I2=I2+1
 275           IF(DONE2) STOP2
 276           CALL user_analysis_routine
 277         IF(I2.LT.3) GO TO 201
 278         CALL CTXOUT(NC2,VC2,20000)
 279 C
 280       IF(.NOT.DONE1) GO TO 101
 281 C
 282 C          Calculate cross section and luminosity
 283 C
 284       CALL CTXIN(NC1,VC1,20000)
 285       CALL ISAEND
 286       GO TO 1
 287 C
 288 999   CALL CTXIN(NC2,VC2,20000)
 289       CALL ISAEND
 290       CALL user_termination_routine
 291       STOP
 292       END
 293 \end{verbatim}
 294 It is possible to superimpose arbitrary combinations of events,
 295 including events of the same reaction type with different parameters.
 296 In general the number of events would be selected randomly based on the
 297 cross sections and the luminosity.
 298
 299       At this time CTXOUT and CTXIN cannot be used with the Zebra
 300 output routines.