5 * Revision 1.1.1.1 1996/03/08 17:27:17 mclareni
10 ISAJET ZEBRA INTERFACE
11 F.E. Paige and S.D. Protopopescu
13 Brookhaven National Laboratory
21 The ZEBRA version of ISAJET contains subroutines which replace the
22 usual output package for ISAJET with one using the CERN package ZEBRA.
23 This version provides some features which are not part of the standard
24 ISAJET output. Momenta and masses of the partons are rescaled from the
25 final particles so that they match exactly (this is not so in ISAJET).
26 Resonances decaying strongly are not part of the particle list while
27 particles with heavy quarks decaying weakly are part of a vertex list with
28 the corresponding vertex position and appropriate links to the particles
29 belonging to that vertex. Thus there is no need to generate secondary
30 vertices for charmed or other heavy quark particles and the event structure
31 makes it easy to find which particles come from the decay of a heavy quark.
32 The association of particles with parent partons is also made easy by
33 reference links. For simple calorimeter studies banks are also provided
34 with energy sums over calorimeter cells and banks containing only the
35 leptons (see below). If only those are written instead of particle banks
36 the resulting files are more compact and require considerably less CPU time
37 to analyze (albeit the information is rather limited). In addition jets are
38 calculated by using a cone algorithm on the partons, these can be useful
39 for studying efficiencies of jet finding algorithms and comparing results
40 to theoretical jets. The results of parton jets are in Zebra banks PJET.
42 NOTE: The present version can only handle one run at a time, so you
43 cannot supply a command file with many runs for now. This problem will be
44 fixed in a future release.
46 [2] Creating and running a job
47 ==============================
49 There are command files in BNLCL6::$2$DUA14:[ISAJET.ISALIBRARY] to make
50 EXE files for event generation and analysis.
52 To make an EXE generating ISAJET events which are then written to
53 a file in ZEBRA format users should run command file:
55 $ @isa$area:MAKE_ISAJET_ZEBRA
57 this starts from ISAJET.PAM and makes ISAJET_ZEBRA.FOR, ISAJET_ZEBRA.OLB
58 and ISAJET_ZEBRA.EXE. It requires that ISA$AREA de defined as the area
59 where ISAJET.PAM and command files reside. It also requires that CERN$AREA
60 be defined as the area for the CERN libraries. The above command file
61 assumes symbol YPATCHY is defined. If running on a machine other than a VAX
62 looking at the command file should give a pretty good idea of what needs to
65 If you already have ISAJET_ZEBRA.OLB you can run command file
67 $ @isa$area:LINK_ISAJET_ZEBRA
69 to make ISAJET_ZEBRA.EXE, this program runs with an interactive
70 dialog to generate ISAJET instructions. You can supply your own
71 ISARUN main program if you wish to bypass the dialog, see command
72 file MAKE_ISAJET.COM for the simplest example.
74 User can provide any of 3 logical functions to reduce the
76 1) EDIT(I) = if false event will not be written out
78 Zebra banks have not yet been generated, so
79 user must work from standard ISAJET common blocks
80 2) ISEDIT() = same as EDIT but Zebra banks have been filled
81 3) 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
86 To generate a user program that reads an ISAJET output file in ZEBRA
87 format users should run
89 $ @isa$area:MAKE_ISZRUN
90 this makes a sample user analysis subroutine ISZUSR and an ISZRUN.EXE
91 program. ISZUSR gives an example of how to use the utility subroutines
92 mentioned in next section for analysis.
94 If user already has an ISZUSR subroutine he can generate ISZRUN.EXE by
96 $ @isa$area:LINK_ISZRUN
102 A number of utilities are provided for the user to make it easier for
103 him to use the information in ZEBRA form without him having to learn much
104 about ZEBRA. It is nevertheless recommended that the user familiarize
105 himself with ZEBRA by reading the first chapter of the ZEBRA manual. Also
106 to make full use of the power of ZEBRA users may eventually want to
107 familiarize themselves with some of the utilities provided with it such as
110 o For every ZEBRA bank of name ISxx (most ISAJET ZEBRA banks start with
112 1) GZISxx : an integer function returning pointer to first bank in
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
117 o To generate a full dump:
119 This subroutine calls all the PRISxx subroutines.
121 o Users can provide a primary vertex for each event by:
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.
128 o The parameters for generating PJET banks can be controlled by
129 CALL PJPSET(N,ALG,ETCUT,DRCUT,MAXIT,IR,MUON)
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
141 Other subroutines of interest are:
142 o ISZJET find jets using ISCL banks
143 o ISZUSR example of a user subroutine for analysis
147 [4] Other Subroutines
148 =====================
150 We list here the subroutines that are part of ISAJET_ZEBRA:
152 GENVTX generate secondary vertices (for heavy quark decays)
153 ISABFL fill ISAB bank (begin of run bank)
154 ISACFL 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.
158 ISAEFL fill ISAE bank (main header)
159 ISAFFL fill ISAF bank (end of run bank)
160 ISAJFL fill ISAJ banks (primary jets)
161 ISALFL fill ISAL banks (leptons)
162 ISAPFL fill ISV1 and ISP1 banks (vertices and particles)
163 ISAQFL fill ISAQ banks (secondary partons, both initial and final)
164 ISCMFL fill ISCM (copy of command instructions)
165 ISMEAR generates smeared calorimeter data (modifies ISCL banks)
166 PJETFL fill PJET banks (jets obtained from partons)
167 QRECAL to recalculate momenta and masses of partons starting
168 from the final particles
174 [5] Brief description of Zebra banks
175 ====================================
177 The beginning and end of run records have Zebra banks named ISAB and
178 ISAF while the whole event hangs from Zebra bank ISAE. A complete
179 description of the banks is given in section [6].
181 ISAB data describing event generation (in beginning record)
182 ISCM copy of command file used for event generation( " )
183 ISAF cumulative results from run (in end record)
184 ISAE general event information such as weight, type, etc.
185 ISAJ primary jet momenta and masses
186 ISAQ final and initial partons (momenta and masses)
187 ISV1 primary and short lived vertices (heavy quarks), includes
188 id,mass and 4-momenta of decaying particle
189 ISP1 particles associated with ISV1 (connected via a structural link)
190 id,mass and 4-momenta
191 ISAC simple calorimeter description (no depth)
192 ISCL energy deposition and cell description in calorimeter cell
193 ISMR description of smearing parameters
194 ISAL stable leptons (including neutrinos):id,mass and 4-momenta
195 with reference links to calorimeter cell and ISP1 if they
197 ISJT jets found by subroutine ISZJET.
198 PJHD header for PJET banks
199 PJET jets found adding over partons
200 PJPT pointers to parton banks (ISAQ) contributing to a jet in PJET
202 Whether banks ISV1,ISP1,ISAC,ISCL and ISAL are written out is
203 optional. The ISARUN job asks user to chose an option ISAP, ISAC or ISAL.
204 If ISAP is selected then ISV1 and ISP1 are written out, if ISAC then ISAC
205 and ISCL are written out and if ISAL then ISAL is written out. Any
206 combination can be selected, the instruction ISAPISACISAL causes all banks
209 The banks ISJT are created by calling ISZJET, the banks ISAC and ISCL
210 must be available. One can create the banks ISAC,ISCL and/or ISAL starting
211 from a file containing ISV1 and ISP1 by calling ISACFL and/or ISALFL for
216 [6] Zebra banks documentation
217 =============================
226 ||| | +------------------------------+
227 ||| +-----------------------------+ |
228 +-------+------------+| | |
230 ______ ______ ______ ______ | |
231 | ISAJ \ | ISAQ \ | ISV1 | | ISV1 \ | |
232 | -1 > | -2 > | -3 |--| (-3) > | |
233 |______/ |______/ |______| |______/ | |
236 [PJET -1].<.. : | | | |
237 : [-2] ______ ______ | |
238 :.....| ISP1 \ | ISP1 \ | |
239 [PJET -3] ..<........| -1 > | -1 > | |
240 |______/ |______/ | |
242 [-4]: v <....: : :[-4] | |
243 : free <......: : | |
246 (end vertex) (end vertex) | |
248 +------------+---------------------+ |
251 _________ ______ ______
252 | ISAC | | ISAL \ | PJHD \
254 |_________| |______/ |______/
256 +-------+---------+--+ ______
257 | | | [ISAQ -1]..>.....| PJET \
258 ______ ______ ______ | -1 >
259 | ISCL \ | ISMR \ | ISJT \ |______/
260 | -1 > | -2 > | -3 > |
261 |______/ |______/ |______/ ______
266 +-----------+ +-----------+
268 | begin run | | end run |
270 +-----------+ +-----------+
279 C=======================================================================
283 C Date : June 14,1989
285 C Calorimeter descriptor
288 C ___________________________________________________________________________
289 C -3 struct. to ISJT (jets found using ISZJET)
290 C -2 struct. to smearing parameters (ISMR)
291 C -1 struct. to calorimeter cells (ISCL)
292 C 0 next to next ISAC (only one at present)
294 C +2 origin to ISAE for first and previous ISAC for others
295 C ............................................................................
296 C I-5 calorimeter number
297 C -4 bank name, 'ISAC'
302 C +1 I number of phi cells
308 C=======================================================================
312 C=======================================================================
316 C Date : June 19,1986 DH add ISAM
318 C Top level bank and event descriptor for ISAZEB
321 C ___________________________________________________________________________
322 C -8 struct. to PJHD (parton jet structure header)
323 C -7 struct. to lepton bank (ISAL)
324 C -6 struct. to pseudo cal. (ISAC)
325 C -5 struct. to unassociated particles (ISP3)
326 C -4 struct. to long lived vertices (ISV2)
327 C -3 struct. to short " " (ISV1)
328 C -2 struct. to final/initial bank (ISAQ)
329 C -1 struct. to primary jet (ISAJ)
330 C 0 next to next ISAE
333 C ............................................................................
335 C -4 bank name, 'ISAE'
344 C 5 I number of primary jet banks
345 C 6 I " of stable parton banks (final+initial)
346 C 7 I " of PJET banks
347 C 8 I " of particle banks
348 C 9 I " of vertex banks
349 C 10 I " of lepton banks
350 C 11 F cross section in microbarns
352 C 13 F effective q**2
353 C 14 F hard scattering invariant s
358 C=======================================================================
362 C=======================================================================
366 C Date : June 19,1986
368 C Primary jet information
371 C ___________________________________________________________________________
372 C L-1 ref. to parent primary (ISAJ) (0 if original)
373 C +0 next to next jet (ISAJ)
376 C ............................................................................
377 C I-5 Primary jet number
378 C -4 bank name, 'ISAJ'
392 C=======================================================================
396 C=======================================================================
400 C Date : June 19,1986
402 C Lepton bank (from primary and short lived vertices)
405 C ___________________________________________________________________________
406 C L-4 ref. to particle bank (ISP1)
407 C -3 ref. to primary jet (ISAJ)
408 C -2 ref. to initial parton (ISAQ)
410 C 0 next to next ISAL
412 C +2 origin to ISAE for first and previous ISAL for others
413 C ............................................................................
414 C I-5 particle number
415 C -4 bank name, 'ISAL'
420 C +1 I ISAJET particle ID
429 C=======================================================================
433 C=======================================================================
437 C Date : June 19,1986
439 C Final and initial partons
442 C ___________________________________________________________________________
443 C L-2 ref. to PJET (parton structure jets)
444 C -1 ref. to primary jet (ISAJ)
445 C 0 for initial parton
446 C 0 next to next ISAQ
448 C +2 origin to ISAE for first and previous ISAQ for others
449 C ............................................................................
450 C I-5 final/initial parton number
451 C -4 bank name, 'ISAQ'
456 C +1 I final/initial parton type
465 C=======================================================================
469 C=======================================================================
473 C Date : June 19,1986
475 C Calorimeter cell bank
478 C ___________________________________________________________________________
479 C L-2 ref. to reconstructed jet (ISJT)
480 C -1 ref. to parent parton (ISAQ)
481 C 0 next to next ISCL
483 C +2 origin to ISAC for first and previous ISAL for others
484 C ............................................................................
485 C I-5 cell number (ordinal)
486 C -4 bank name, 'ISCL'
491 C +1 I 10000*(phi index) + y index
492 C 2 I 10000*(# of charged trks) + # of gammas
493 C 3 F e.m. energy deposited
495 C 5 F sin(theta) at center of cell
501 C===========================================================================
506 C=======================================================================
510 C Date : June 19,1986
512 C Jets found by ISZJET
515 C ___________________________________________________________________________
516 C -1 to possible parent parton (ISAQ)
517 C +0 next to next jet (ISJT)
520 C ............................................................................
522 C -4 bank name, 'ISJT'
527 C +1 F ET (transverse energy)
536 C=======================================================================
541 C=======================================================================
545 C Date : June 19,1986
547 C Particle bank (from primary and short lived vertices)
550 C ___________________________________________________________________________
552 C L-4 ref. to secondary vertex (ISV2)
553 C -3 ref. to primary jet (ISAJ)
554 C -2 ref. to initial parton (ISAQ)
556 C 0 next to next ISP1
558 C +2 origin to ISV1 for first and previous ISP1 for others
559 C ............................................................................
560 C I-5 particle number
561 C -4 bank name, 'ISP1'
566 C +1 I ISAJET particle ID
575 C=======================================================================
579 C=======================================================================
582 C Author : Chip Stewart
583 C Date : 7-NOV-1989 18:10:09.84
586 C Bank description : PARTON JET BANK
587 C PJET is constructed by applying a jet algorithm (CONE or
588 C OPENING ANGLE) to either Partons given in the ISAQ bank
589 C or Paricles given in the ISP1 bank.
592 C-----------------------------------------------------------------------
593 C +2 Down link to SPARE
594 C -1 Down link to PJPT
597 C +2 Origin link to PJHD
598 C.......................................................................
600 C -4 Bank name, 'PJET'
605 C +1 I NV = 2 Version Number
606 C 2 F Et ( =Pt in version NV=1 )
615 C 11 I CLASS - (eg. for mapping PJET with RECO )
617 C=======================================================================
622 C E - Sum(Ei) over all the Partons/Particles included in the jet.
628 C Et - Sum[Ei*sin(Thetai)]
630 C Comment: In version NV=1 word 2 was Pt = SQRT ( Px**2 + Py**2 )
632 C Mass - SQRT [ E**2 - ( Px**2 + Py**2 + Pz**2 )]
634 C For Theta, Phi and Eta the following code was used
635 C to calculate them from Px,Py,Pz
637 C PARAMETER( SMALL = 1.0E-5 )
638 C Phi=ATAN2(Py,Px+SMALL) ; IF(Phi.LT.0) Phi=Phi+TWOPI
639 C Theta=ACOS((Pz+SMALL)/(SQRT(Px*Px+Py*Py+Pz*Pz)+SMALL))
640 C Eta=-ALOG(TAN(Theta/2.)+SMALL)
642 C=======================================================================
646 C=======================================================================
649 C Author : Chip Stewart
650 C Date : 7-NOV-1989 17:57:58.00
652 C Bank description : Header for PJET structure
655 C-----------------------------------------------------------------------
657 C -1 DOWN LINK TO PJET
658 C 0 Next link to PJHD
660 C +2 Origin link to ISAE
661 C.......................................................................
663 C -4 Bank name, 'PJHD'
668 C 1 I NV=2 Version number
669 C 2 I N_ALG - 1 for DR CONE , 2 for CMS OPEN ANGLE
670 C 3 I NJET - NUMBER OF PARTON JETS
671 C 4 F algorithm parameters DR_CONE_CUT/OPENING_ANGLE_CUT
672 C 5 F algorithm parameters JET_ET_CUT
673 C 6 I algorithm parameters MAX ITERATIONS
674 C 7 I Initial Radiation switch 0-use IR 1-no IR
675 C 8 I MUON switch (IF NV=1 MUON NOT USED)
676 C 0-no MUONS 1-use MUONS
677 C=======================================================================
681 C=======================================================================
684 C Author : Chip Stewart
687 C Bank description : pointers to Partons (ISAQ) in a given jet
690 C-----------------------------------------------------------------------
691 C -N+1 Ref Link to parton bank ISAQ for Nth parton in this PJET
692 C -2 Ref Link to parton bank ISAQ for 1st " " " "
694 C 0 Next link to none
696 C +2 Origin link to PJET
697 C.......................................................................
699 C -4 Bank name, 'PJPT'
702 C -1 ND = 1 - number of data words in PJPT bank = 1
704 C +1 I Bank version (=1)
705 C=======================================================================