First commit.
[u/mrichter/AliRoot.git] / ISAJET / doc / ztext.doc
CommitLineData
0795afa3 1*
2* $Id$
3*
4* $Log$
5* Revision 1.1.1.1 1996/03/08 17:27:17 mclareni
6* Isajet714
7*
8*
9
10 ISAJET ZEBRA INTERFACE
11 F.E. Paige and S.D. Protopopescu
12 Physics Department
13 Brookhaven National Laboratory
14 Upton, NY 11973
15 March 30, 1991
16
17
18 [1] Overview
19 ============
20
21 The ZEBRA version of ISAJET contains subroutines which replace the
22usual output package for ISAJET with one using the CERN package ZEBRA.
23This version provides some features which are not part of the standard
24ISAJET output. Momenta and masses of the partons are rescaled from the
25final particles so that they match exactly (this is not so in ISAJET).
26Resonances decaying strongly are not part of the particle list while
27particles with heavy quarks decaying weakly are part of a vertex list with
28the corresponding vertex position and appropriate links to the particles
29belonging to that vertex. Thus there is no need to generate secondary
30vertices for charmed or other heavy quark particles and the event structure
31makes it easy to find which particles come from the decay of a heavy quark.
32The association of particles with parent partons is also made easy by
33reference links. For simple calorimeter studies banks are also provided
34with energy sums over calorimeter cells and banks containing only the
35leptons (see below). If only those are written instead of particle banks
36the resulting files are more compact and require considerably less CPU time
37to analyze (albeit the information is rather limited). In addition jets are
38calculated by using a cone algorithm on the partons, these can be useful
39for studying efficiencies of jet finding algorithms and comparing results
40to theoretical jets. The results of parton jets are in Zebra banks PJET.
41
42 NOTE: The present version can only handle one run at a time, so you
43cannot supply a command file with many runs for now. This problem will be
44fixed in a future release.
45
46 [2] Creating and running a job
47 ==============================
48
49 There are command files in BNLCL6::$2$DUA14:[ISAJET.ISALIBRARY] to make
50EXE files for event generation and analysis.
51
52 To make an EXE generating ISAJET events which are then written to
53a file in ZEBRA format users should run command file:
54
55$ @isa$area:MAKE_ISAJET_ZEBRA
56
57this starts from ISAJET.PAM and makes ISAJET_ZEBRA.FOR, ISAJET_ZEBRA.OLB
58and ISAJET_ZEBRA.EXE. It requires that ISA$AREA de defined as the area
59where ISAJET.PAM and command files reside. It also requires that CERN$AREA
60be defined as the area for the CERN libraries. The above command file
61assumes symbol YPATCHY is defined. If running on a machine other than a VAX
62looking at the command file should give a pretty good idea of what needs to
63be done.
64
65If you already have ISAJET_ZEBRA.OLB you can run command file
66
67$ @isa$area:LINK_ISAJET_ZEBRA
68
69to make ISAJET_ZEBRA.EXE, this program runs with an interactive
70dialog to generate ISAJET instructions. You can supply your own
71ISARUN main program if you wish to bypass the dialog, see command
72file MAKE_ISAJET.COM for the simplest example.
73
74User can provide any of 3 logical functions to reduce the
75size of output files:
761) EDIT(I) = if false event will not be written out
77 I is event number
78 Zebra banks have not yet been generated, so
79 user must work from standard ISAJET common blocks
802) ISEDIT() = same as EDIT but Zebra banks have been filled
813) PEDIT(ID,P) = if false particle will not be included in
82 the list of particles written out
83 ID= particle ID, P(4)= particle momentum vector
84
85
86To generate a user program that reads an ISAJET output file in ZEBRA
87format users should run
88
89$ @isa$area:MAKE_ISZRUN
90this makes a sample user analysis subroutine ISZUSR and an ISZRUN.EXE
91program. ISZUSR gives an example of how to use the utility subroutines
92mentioned in next section for analysis.
93
94If user already has an ISZUSR subroutine he can generate ISZRUN.EXE by
95
96$ @isa$area:LINK_ISZRUN
97
98
99 [3] Utilities
100 =============
101
102 A number of utilities are provided for the user to make it easier for
103him to use the information in ZEBRA form without him having to learn much
104about ZEBRA. It is nevertheless recommended that the user familiarize
105himself with ZEBRA by reading the first chapter of the ZEBRA manual. Also
106to make full use of the power of ZEBRA users may eventually want to
107familiarize themselves with some of the utilities provided with it such as
108MZDROP and ZSORT.
109
110o For every ZEBRA bank of name ISxx (most ISAJET ZEBRA banks start with
111 IS) there exist:
112 1) GZISxx : an integer function returning pointer to first bank in
113 the linear structure
114 2) GTISxx : a subroutine returning the contents of the bank
115 3) PRISxx : a subroutine generating a printout of the banks with name ISxx
116
117o To generate a full dump:
118 CALL PRTEVZ(unit #)
119 This subroutine calls all the PRISxx subroutines.
120
121o Users can provide a primary vertex for each event by:
122 CALL SETVTX(XYZ)
123 where XYZ is a 3-vector with values x,y,z
124 To supply a function for the vertex user should supply subroutine
125 INTVTX(XYZ) which returns an XYZ vector with each call. The
126 default returns 0,0,0.
127
128o The parameters for generating PJET banks can be controlled by
129 CALL PJPSET(N,ALG,ETCUT,DRCUT,MAXIT,IR,MUON)
130 where
131 Default values
132 N = NUMBER OF PJET ALGORITHMS 1
133 ALG = ALGORITHM TPYE 'CONE' OR 'ANGLE' 'CONE'
134 ETCUT = ET CUT FR PJET JETS 5.0
135 DRCUT = CONE CUT (IN R OR ANGLE) 0.45
136 MAXIT = MAXIMUM NUMBER OF ITERATIONS 1
137 IR = INIT RADIATION FLAG 0=USE IR, 1=NO IR 0
138 MUON = MUON FLAG 0=NO MUONS, 1=use MUONS in PJET 0
139
140
141 Other subroutines of interest are:
142o ISZJET find jets using ISCL banks
143o ISZUSR example of a user subroutine for analysis
144
145
146
147 [4] Other Subroutines
148 =====================
149
150 We list here the subroutines that are part of ISAJET_ZEBRA:
151
152GENVTX generate secondary vertices (for heavy quark decays)
153ISABFL fill ISAB bank (begin of run bank)
154ISACFL fill ISAC and ISCL banks (calorimeter description and
155 calorimeter cells with non-zero energy deposited).
156 Entry point ISACIN calculates all numbers needed for
157 calorimeter description.
158ISAEFL fill ISAE bank (main header)
159ISAFFL fill ISAF bank (end of run bank)
160ISAJFL fill ISAJ banks (primary jets)
161ISALFL fill ISAL banks (leptons)
162ISAPFL fill ISV1 and ISP1 banks (vertices and particles)
163ISAQFL fill ISAQ banks (secondary partons, both initial and final)
164ISCMFL fill ISCM (copy of command instructions)
165ISMEAR generates smeared calorimeter data (modifies ISCL banks)
166PJETFL fill PJET banks (jets obtained from partons)
167QRECAL to recalculate momenta and masses of partons starting
168 from the final particles
169
170
171
172
173
174 [5] Brief description of Zebra banks
175 ====================================
176
177 The beginning and end of run records have Zebra banks named ISAB and
178ISAF while the whole event hangs from Zebra bank ISAE. A complete
179description of the banks is given in section [6].
180
181ISAB data describing event generation (in beginning record)
182ISCM copy of command file used for event generation( " )
183ISAF cumulative results from run (in end record)
184ISAE general event information such as weight, type, etc.
185ISAJ primary jet momenta and masses
186ISAQ final and initial partons (momenta and masses)
187ISV1 primary and short lived vertices (heavy quarks), includes
188 id,mass and 4-momenta of decaying particle
189ISP1 particles associated with ISV1 (connected via a structural link)
190 id,mass and 4-momenta
191ISAC simple calorimeter description (no depth)
192ISCL energy deposition and cell description in calorimeter cell
193ISMR description of smearing parameters
194ISAL stable leptons (including neutrinos):id,mass and 4-momenta
195 with reference links to calorimeter cell and ISP1 if they
196 exist
197ISJT jets found by subroutine ISZJET.
198PJHD header for PJET banks
199PJET jets found adding over partons
200PJPT pointers to parton banks (ISAQ) contributing to a jet in PJET
201
202 Whether banks ISV1,ISP1,ISAC,ISCL and ISAL are written out is
203optional. The ISARUN job asks user to chose an option ISAP, ISAC or ISAL.
204If ISAP is selected then ISV1 and ISP1 are written out, if ISAC then ISAC
205and ISCL are written out and if ISAL then ISAL is written out. Any
206combination can be selected, the instruction ISAPISACISAL causes all banks
207to be written out.
208
209 The banks ISJT are created by calling ISZJET, the banks ISAC and ISCL
210must be available. One can create the banks ISAC,ISCL and/or ISAL starting
211from a file containing ISV1 and ISP1 by calling ISACFL and/or ISALFL for
212each event.
213
214
215
216 [6] Zebra banks documentation
217 =============================
218
219
220 +------------------+
221 | ISAE |
222 | event descriptor |
223 | |
224 +------------------+
225 struc. link ||| | |
226 ||| | +------------------------------+
227 ||| +-----------------------------+ |
228 +-------+------------+| | |
229 | | | | |
230 ______ ______ ______ ______ | |
231 | ISAJ \ | ISAQ \ | ISV1 | | ISV1 \ | |
232 | -1 > | -2 > | -3 |--| (-3) > | |
233 |______/ |______/ |______| |______/ | |
234 : ^ | :...<..: | | |
235 : : | [-2] | | |
236 [PJET -1].<.. : | | | |
237 : [-2] ______ ______ | |
238 :.....| ISP1 \ | ISP1 \ | |
239 [PJET -3] ..<........| -1 > | -1 > | |
240 |______/ |______/ | |
241 : |[-1] : : : | |
242 [-4]: v <....: : :[-4] | |
243 : free <......: : | |
244 v v | |
245 ISV2 ISV2 | |
246 (end vertex) (end vertex) | |
247 | |
248 +------------+---------------------+ |
249 | | |
250 | | |
251 _________ ______ ______
252 | ISAC | | ISAL \ | PJHD \
253 | -6 | | -7 > | -8 >
254 |_________| |______/ |______/
255 | |
256 +-------+---------+--+ ______
257 | | | [ISAQ -1]..>.....| PJET \
258 ______ ______ ______ | -1 >
259 | ISCL \ | ISMR \ | ISJT \ |______/
260 | -1 > | -2 > | -3 > |
261 |______/ |______/ |______/ ______
262 | PJPT |
263 [ISAQ]...<...| -1 |
264 |______|
265
266 +-----------+ +-----------+
267 | ISAB | | ISAF |
268 | begin run | | end run |
269 | | | |
270 +-----------+ +-----------+
271 |
272 +----------+
273 | ISCM |
274 | -1 |
275 +----------+
276
277
278
279C=======================================================================
280C
281C Bank name: ISAC
282C Author : SDP
283C Date : June 14,1989
284C
285C Calorimeter descriptor
286C
287C LQ Q/IQ
288C ___________________________________________________________________________
289C -3 struct. to ISJT (jets found using ISZJET)
290C -2 struct. to smearing parameters (ISMR)
291C -1 struct. to calorimeter cells (ISCL)
292C 0 next to next ISAC (only one at present)
293C +1 up to ISAE
294C +2 origin to ISAE for first and previous ISAC for others
295C ............................................................................
296C I-5 calorimeter number
297C -4 bank name, 'ISAC'
298C -3 NL=2
299C -2 NS=0
300C -1 ND=6
301C 0 STATUS
302C +1 I number of phi cells
303C 2 I " eta "
304C 3 F phi cell size
305C 4 F eta " "
306C 5 F minimum eta
307C 6 F maximum eta
308C=======================================================================
309
310
311
312C=======================================================================
313C
314C Bank name: ISAE
315C Author : SDP
316C Date : June 19,1986 DH add ISAM
317C
318C Top level bank and event descriptor for ISAZEB
319C
320C LQ Q/IQ
321C ___________________________________________________________________________
322C -8 struct. to PJHD (parton jet structure header)
323C -7 struct. to lepton bank (ISAL)
324C -6 struct. to pseudo cal. (ISAC)
325C -5 struct. to unassociated particles (ISP3)
326C -4 struct. to long lived vertices (ISV2)
327C -3 struct. to short " " (ISV1)
328C -2 struct. to final/initial bank (ISAQ)
329C -1 struct. to primary jet (ISAJ)
330C 0 next to next ISAE
331C +1 up
332C +2 origin
333C ............................................................................
334C I-5 bank number
335C -4 bank name, 'ISAE'
336C -3 NL=7
337C -2 NS=7
338C -1 ND=18
339C 0 STATUS
340C +1 I event id(1)
341C 2 I event id(2)
342C 3 I event number
343C 4 I reaction type
344C 5 I number of primary jet banks
345C 6 I " of stable parton banks (final+initial)
346C 7 I " of PJET banks
347C 8 I " of particle banks
348C 9 I " of vertex banks
349C 10 I " of lepton banks
350C 11 F cross section in microbarns
351C 12 F weight
352C 13 F effective q**2
353C 14 F hard scattering invariant s
354C 15 F " " " t
355C 16 F " " " u
356C 17 D Seed (part 1)
357C 18 D Seed (part 2)
358C=======================================================================
359
360
361
362C=======================================================================
363C
364C Bank name: ISAJ
365C Author : SDP
366C Date : June 19,1986
367C
368C Primary jet information
369C
370C LQ Q/IQ
371C ___________________________________________________________________________
372C L-1 ref. to parent primary (ISAJ) (0 if original)
373C +0 next to next jet (ISAJ)
374C +1 up to ISAE
375C +2 origin to ISAE
376C ............................................................................
377C I-5 Primary jet number
378C -4 bank name, 'ISAJ'
379C -3 NL=0
380C -2 NS=0
381C -1 ND=9
382C 0 STATUS
383C +1 I jet ID
384C 2 F px
385C 3 F py
386C 4 F pz
387C 5 F p
388C 6 F mass
389C 7 F phi
390C 8 F theta
391C 9 F eta
392C=======================================================================
393
394
395
396C=======================================================================
397C
398C Bank name: ISAL
399C Author : SDP
400C Date : June 19,1986
401C
402C Lepton bank (from primary and short lived vertices)
403C
404C LQ Q/IQ
405C ___________________________________________________________________________
406C L-4 ref. to particle bank (ISP1)
407C -3 ref. to primary jet (ISAJ)
408C -2 ref. to initial parton (ISAQ)
409C -1 struct. (free)
410C 0 next to next ISAL
411C +1 up to ISAE
412C +2 origin to ISAE for first and previous ISAL for others
413C ............................................................................
414C I-5 particle number
415C -4 bank name, 'ISAL'
416C -3 NL=4
417C -2 NS=1
418C -1 ND=9
419C 0 STATUS
420C +1 I ISAJET particle ID
421C 2 F px
422C 3 F py
423C 4 F pz
424C 5 F p
425C 6 F mass
426C 7 F phi
427C 8 F theta
428C 9 F eta
429C=======================================================================
430
431
432
433C=======================================================================
434C
435C Bank name: ISAQ
436C Author : SDP
437C Date : June 19,1986
438C
439C Final and initial partons
440C
441C LQ Q/IQ
442C ___________________________________________________________________________
443C L-2 ref. to PJET (parton structure jets)
444C -1 ref. to primary jet (ISAJ)
445C 0 for initial parton
446C 0 next to next ISAQ
447C +1 up to ISAE
448C +2 origin to ISAE for first and previous ISAQ for others
449C ............................................................................
450C I-5 final/initial parton number
451C -4 bank name, 'ISAQ'
452C -3 NL=2
453C -2 NS=0
454C -1 ND=9
455C 0 STATUS
456C +1 I final/initial parton type
457C 2 F px
458C 3 F py
459C 4 F pz
460C 5 F E
461C 6 F mass
462C 7 F phi
463C 8 F theta
464C 9 F eta
465C=======================================================================
466
467
468
469C=======================================================================
470C
471C Bank name: ISCL
472C Author : SDP
473C Date : June 19,1986
474C
475C Calorimeter cell bank
476C
477C LQ Q/IQ
478C ___________________________________________________________________________
479C L-2 ref. to reconstructed jet (ISJT)
480C -1 ref. to parent parton (ISAQ)
481C 0 next to next ISCL
482C +1 up to ISAC
483C +2 origin to ISAC for first and previous ISAL for others
484C ............................................................................
485C I-5 cell number (ordinal)
486C -4 bank name, 'ISCL'
487C -3 NL=2
488C -2 NS=0
489C -1 ND=10
490C 0 STATUS
491C +1 I 10000*(phi index) + y index
492C 2 I 10000*(# of charged trks) + # of gammas
493C 3 F e.m. energy deposited
494C 4 F had. " "
495C 5 F sin(theta) at center of cell
496C 6 F cos(theta) "
497C 7 F sin(phi) "
498C 8 F cos(phi) "
499C 9 F phi "
500C 10 F eta "
501C===========================================================================
502
503
504
505
506C=======================================================================
507C
508C Bank name: ISJT
509C Author : SDP
510C Date : June 19,1986
511C
512C Jets found by ISZJET
513C
514C LQ Q/IQ
515C ___________________________________________________________________________
516C -1 to possible parent parton (ISAQ)
517C +0 next to next jet (ISJT)
518C +1 up to ISJT
519C +2 origin to ISAC
520C ............................................................................
521C I-5 jet number
522C -4 bank name, 'ISJT'
523C -3 NL=0
524C -2 NS=0
525C -1 ND=6
526C 0 STATUS
527C +1 F ET (transverse energy)
528C 2 F px
529C 3 F py
530C 4 F pz
531C 5 F E
532C 6 F mass
533C 7 F phi
534C 8 F theta
535C 9 F eta
536C=======================================================================
537
538
539
540
541C=======================================================================
542C
543C Bank name: ISP1
544C Author : SDP
545C Date : June 19,1986
546C
547C Particle bank (from primary and short lived vertices)
548C
549C LQ Q/IQ
550C ___________________________________________________________________________
551C L-5 ref. to GCAH
552C L-4 ref. to secondary vertex (ISV2)
553C -3 ref. to primary jet (ISAJ)
554C -2 ref. to initial parton (ISAQ)
555C -1 struct. (free)
556C 0 next to next ISP1
557C +1 up to ISV1
558C +2 origin to ISV1 for first and previous ISP1 for others
559C ............................................................................
560C I-5 particle number
561C -4 bank name, 'ISP1'
562C -3 NL=4
563C -2 NS=1
564C -1 ND=9
565C 0 STATUS
566C +1 I ISAJET particle ID
567C 2 F px
568C 3 F py
569C 4 F pz
570C 5 F E
571C 6 F mass
572C 7 F phi
573C 8 F theta
574C 9 F eta
575C=======================================================================
576
577
578
579C=======================================================================
580C
581C Bank Name : PJET
582C Author : Chip Stewart
583C Date : 7-NOV-1989 18:10:09.84
584C Version : 2.0
585C
586C Bank description : PARTON JET BANK
587C PJET is constructed by applying a jet algorithm (CONE or
588C OPENING ANGLE) to either Partons given in the ISAQ bank
589C or Paricles given in the ISP1 bank.
590C
591C LQ Q/IQ
592C-----------------------------------------------------------------------
593C +2 Down link to SPARE
594C -1 Down link to PJPT
595C 0 Next link to
596C +1 Up link to PJHD
597C +2 Origin link to PJHD
598C.......................................................................
599C -5 Bank number
600C -4 Bank name, 'PJET'
601C -3 NL = 2
602C -2 NS = 2
603C -1 ND = 12
604C 0 Status
605C +1 I NV = 2 Version Number
606C 2 F Et ( =Pt in version NV=1 )
607C 3 F Px
608C 4 F Py
609C 5 F Pz
610C 6 F E
611C 7 F mass
612C 8 F phi
613C 9 F theta
614C 10 F eta
615C 11 I CLASS - (eg. for mapping PJET with RECO )
616C 12 I NEXT
617C=======================================================================
618C
619C Definitions:
620C -----------
621C
622C E - Sum(Ei) over all the Partons/Particles included in the jet.
623C
624C Px - Sum(Pxi).
625C Py - Sum(Pyi).
626C Pz - Sum(Pzi).
627C
628C Et - Sum[Ei*sin(Thetai)]
629C
630C Comment: In version NV=1 word 2 was Pt = SQRT ( Px**2 + Py**2 )
631C
632C Mass - SQRT [ E**2 - ( Px**2 + Py**2 + Pz**2 )]
633C
634C For Theta, Phi and Eta the following code was used
635C to calculate them from Px,Py,Pz
636C
637C PARAMETER( SMALL = 1.0E-5 )
638C Phi=ATAN2(Py,Px+SMALL) ; IF(Phi.LT.0) Phi=Phi+TWOPI
639C Theta=ACOS((Pz+SMALL)/(SQRT(Px*Px+Py*Py+Pz*Pz)+SMALL))
640C Eta=-ALOG(TAN(Theta/2.)+SMALL)
641C
642C=======================================================================
643
644
645
646C=======================================================================
647C
648C Bank Name : PJHD
649C Author : Chip Stewart
650C Date : 7-NOV-1989 17:57:58.00
651C
652C Bank description : Header for PJET structure
653C
654C LQ Q/IQ
655C-----------------------------------------------------------------------
656C -2 DOWN spare
657C -1 DOWN LINK TO PJET
658C 0 Next link to PJHD
659C +1 Up link to ISAE
660C +2 Origin link to ISAE
661C.......................................................................
662C -5 Bank number
663C -4 Bank name, 'PJHD'
664C -3 NL = 2
665C -2 NS = 2
666C -1 ND = 8
667C 0 Status
668C 1 I NV=2 Version number
669C 2 I N_ALG - 1 for DR CONE , 2 for CMS OPEN ANGLE
670C 3 I NJET - NUMBER OF PARTON JETS
671C 4 F algorithm parameters DR_CONE_CUT/OPENING_ANGLE_CUT
672C 5 F algorithm parameters JET_ET_CUT
673C 6 I algorithm parameters MAX ITERATIONS
674C 7 I Initial Radiation switch 0-use IR 1-no IR
675C 8 I MUON switch (IF NV=1 MUON NOT USED)
676C 0-no MUONS 1-use MUONS
677C=======================================================================
678
679
680
681C=======================================================================
682C
683C Bank Name : PJPT
684C Author : Chip Stewart
685C Date : 15-Dec-1989
686C
687C Bank description : pointers to Partons (ISAQ) in a given jet
688C
689C LQ Q/IQ
690C-----------------------------------------------------------------------
691C -N+1 Ref Link to parton bank ISAQ for Nth parton in this PJET
692C -2 Ref Link to parton bank ISAQ for 1st " " " "
693C -1 not used
694C 0 Next link to none
695C +1 Up link to PJET
696C +2 Origin link to PJET
697C.......................................................................
698C -5 Bank number
699C -4 Bank name, 'PJPT'
700C -3 NL = N+1
701C -2 NS = 0
702C -1 ND = 1 - number of data words in PJPT bank = 1
703C 0 Status
704C +1 I Bank version (=1)
705C=======================================================================
706