Using AliLog (F.Carminati)
[u/mrichter/AliRoot.git] / 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.