The Event Record

Each new event generated is in its entirety stored in the common block PYJETS, which thus forms the event record. Here each parton or particle that appears at some stage of the fragmentation or decay chain will occupy one line in the matrices. The different components of this line will tell which parton/particle it is, from where it originates, its present status (fragmented/decayed or not), its momentum, energy and mass, and the space-time position of its production vertex. Note that K(I,3)-K(I,5) and the P and V vectors may take special meaning for some specific applications (e.g. sphericity or cluster analysis), as described in those connections.

The event history information stored in K(I,3)-K(I,5) should not be taken too literally. In the particle decay chains, the meaning of a mother is well-defined, but the fragmentation description is more complicated. The primary hadrons produced in string fragmentation come from the string as a whole, rather than from an individual parton. Even when the string is not included in the history (see MSTU(16)), the pointer from hadron to parton is deceptive. For instance, in a $\mathrm{q}\mathrm{g}\overline{\mathrm{q}}$ event, those hadrons are pointing towards the $\mathrm{q}$ ( $\overline{\mathrm{q}}$) parton that were produced by fragmentation from that end of the string, according to the random procedure used in the fragmentation routine. No particles point to the $\mathrm{g}$. This assignment seldom agrees with the visual impression, and is not intended to.

The common block PYJETS has expanded with time, and can now house 4000 entries. This figure may seem ridiculously large, but actually the previous limit of 2000 was often reached in studies of high-$p_{\perp}$ processes at the LHC (and SSC). This is because the event record contains not only the final particles, but also all intermediate partons and hadrons, which subsequently showered, fragmented or decayed. Included are also a wealth of photons coming from $\pi^0$ decays; the simplest way of reducing the size of the event record is actually to switch off $\pi^0$ decays by MDCY(PYCOMP(111),1)=0. Also note that some routines, such as PYCLUS and PYCELL, use memory after the event record proper as a working area. Still, to change the size of the common block, upwards or downwards, is easy: just do a global substitute in the common block and change the MSTU(4) value to the new number. If more than 10000 lines are to be used, the packing of colour information should also be changed, see MSTU(5).

Purpose:

to contain the event record, i.e. the complete list of all partons and particles (initial, intermediate and final) in the current event. (By parton we here mean the subclass of particles that carry colour, for which extra colour flow information is then required. Normally this means quarks and gluons, which can fragment to hadrons, but also squarks and other exotic particles fall in this category.)

N :

number of lines in the K, P and V matrices occupied by the current event. N is continuously updated as the definition of the original configuration and the treatment of fragmentation and decay proceed. In the following, the individual parton/particle number, running between 1 and N, is called I.

NPAD :

dummy to ensure an even number of integers before the double precision reals, as required by some compilers.

K(I,1) :

status code KS, which gives the current status of the parton/particle stored in the line. The ground rule is that codes 1-10 correspond to currently existing partons/particles, while larger codes contain partons/particles which no longer exist, or other kinds of event information.

= 0 :

empty line.

= 1 :

an undecayed particle or an unfragmented parton, the latter being either a single parton or the last one of a parton system.

= 2 :

an unfragmented parton, which is followed by more partons in the same colour-singlet parton system.

= 3 :

an unfragmented parton with special colour flow information stored in K(I,4) and K(I,5), such that adjacent partons along the string need not follow each other in the event record.

= 4 :

a particle which could have decayed, but did not within the allowed volume around the original vertex.

= 5 :

a particle which is to be forced to decay in the next PYEXEC call, in the vertex position given (this code is only set by user intervention).

= 11 :

a decayed particle or a fragmented parton, the latter being either a single parton or the last one of a parton system, cf. =1.

= 12 :

a fragmented parton, which is followed by more partons in the same colour-singlet parton system, cf. =2. Further, a $\mathrm{B}$ meson which decayed as a $\overline{\mathrm{B}}$ one, or vice versa, because of $\mathrm{B}$- $\overline{\mathrm{B}}$ mixing, is marked with this code rather than =11.

= 13 :

a parton which has been removed when special colour flow information has been used to rearrange a parton system, cf. =3.

= 14 :

a parton which has branched into further partons, with special colour-flow information provided, cf. =3.

= 15 :

a particle which has been forced to decay (by user intervention), cf. =5.

= 21 :

documentation lines used to give a compressed story of the event at the beginning of the event record.

= 31 :

lines with information on sphericity, thrust or cluster search.

= 32 :

tabular output, as generated by PYTABU.

= 41 :

a junction, with partons arranged in colour, except that two quark lines may precede or follow a junction. For instance, a configuration like $\mathrm{q}_1 \g_1 \, \mathrm{q}_2 \g_2 \,$(junction) $\, \g_3 \mathrm{q}_3$ corresponds to having three strings $\mathrm{q}_1 \g_1$, $\mathrm{q}_2 \g_2$ and $\mathrm{q}_3 \g_3$ meeting in the junction. The occurence of non-matching colours easily reveal the $\mathrm{q}_2$ as not being a continuation of the $\mathrm{q}_1 \g_1$ string. Here each $\mathrm{g}$ above is shorthand for an arbitrary number of gluons, including none. The most general topology allows two junctions in a system, i.e. $\mathrm{q}_1 \g_1 \, \mathrm{q}_2 \g_2 \,$(junction)$\, \g_0\,$(junction) $\, \g_3 \overline{\mathrm{q}}_3 \, \g_4 \overline{\mathrm{q}}_4$. The final $\mathrm{q}/\overline{\mathrm{q}}$ would have status code 1, the other partons 2. Thus code =41 occurs where =2 would normally have been used, had the junction been an ordinary parton.

= 42 :

a junction, with special colour flow information stored in K(I,4) and K(I,5), such that adjacent partons along the string need not follow each other in the event record. Thus this code matches the =3 of ordinary partons.

= 51 :

a junction of strings which have been fragmented, cf. =41. Thus this code matches the =12 of ordinary partons.

= 52 :

a junction of strings which have been rearranged in colour, cf. =42. Thus this code matches the =13 of ordinary partons.

< 0 :

these codes are never used by the program, and are therefore usually not affected by operations on the record, such as PYROBO, PYLIST and event-analysis routines (the exception is some PYEDIT calls, where lines are moved but not deleted). Such codes may therefore be useful in some connections.

K(I,2) :

particle KF code, as described in section .

K(I,3) :

line number of parent particle, where known, otherwise 0. Note that the assignment of a particle to a given parton in a parton system is unphysical, and what is given there is only related to the way the fragmentation was generated.

K(I,4) :

normally the line number of the first daughter; it is 0 for an undecayed particle or unfragmented parton.

For K(I,1) = 3, 13 or 14, instead, it contains special colour-flow information (for internal use only) of the form
K(I,4) = 200000000*MCFR + 100000000*MCTO + 10000*ICFR + ICTO,
where ICFR and ICTO give the line numbers of the partons from which the colour comes and to where it goes, respectively; MCFR and MCTO originally are 0 and are set to 1 when the corresponding colour connection has been traced in the PYPREP rearrangement procedure. (The packing may be changed with MSTU(5).) The `from' colour position may indicate a parton which branched to produce the current parton, or a parton created together with the current parton but with matched anticolour, while the `to' normally indicates a parton that the current parton branches into. Thus, for setting up an initial colour configuration, it is normally only the `from' part that is used, while the `to' part is added by the program in a subsequent call to parton-shower evolution (for final-state radiation; it is the other way around for initial-state radiation).

For K(I,1) = 42 or 52, see below.

Note: normally most users never have to worry about the exact rules for colour-flow storage, since this is used mainly for internal purposes. However, when it is necessary to define this flow, it is recommended to use the PYJOIN routine, since it is likely that this would reduce the chances of making a mistake.

K(I,5) :

normally the line number of the last daughter; it is 0 for an undecayed particle or unfragmented parton.

For K(I,1) = 3, 13 or 14, instead, it contains special colour-flow information (for internal use only) of the form
K(I,5) = 200000000*MCFR + 100000000*MCTO + 10000*ICFR + ICTO,
where ICFR and ICTO give the line numbers of the partons from which the anticolour comes and to where it goes, respectively; MCFR and MCTO originally are 0 and are set to 1 when the corresponding colour connection has been traced in the PYPREP rearrangement procedure. For further discussion, see K(I,4).

For K(I,1) = 42 or 52, see below.

K(I,4), K(I,5) :

For junctions with K(I,1) = 42 or 52 the colour flow information scheme presented above has to be modified, since now three colour or anticolour lines meet. Thus the form is
K(I,4) = 100000000*MC1 + 10000*ITP + IC1,
K(I,5) = 200000000*MC2 + 100000000*MC3 + 10000*IC2 + IC3.
The colour flow possibilities are

ITP = 1 :

junction of three colours in the final state, with positions as stored in IC1, IC2 and IC3. A typical example would be neutralino decay to three quarks. Note that the positions need not be filled by the line numbers of the final quark themselves, but more likely by the immediate neutralino decay products that thereafter initiate showers and branch further.

ITP = 2 :

junction of three anticolours in the final state, with positions as stored in IC1, IC2 and IC3.

ITP = 3 :

junction of one incoming anticolour to two outgoing colours, with the anticolour position stored in IC1 and the two colour ones in IC2 and IC3. A typical example would be an antisquark decaying to two quarks.

ITP = 4 :

junction of one incoming colour to two outgoing anticolours, with the colour position stored in IC1 and the two anticolour ones in IC2 and IC3.

ITP = 5 :

junction of a colour octet into three colours. The incoming colour is supposed to pass through unchanged, and so is bookkept as usual for the particle itself. IC1 is the position of the incoming anticolour, while IC2 and IC3 are the positions of the new colours associated with the vanishing of this anticolour. A typical example would be gluino decay to three quarks.

ITP = 6 :

junction of a colour octet into three anticolours. The incoming anticolour is supposed to pass through unchanged, and so is bookkept as usual for the particle itself. IC1 is the position of the incoming colour, while IC2 and IC3 are the positions of the new anticolours associated with the vanishing of this colour.

Thus odd (even) ITP code corresponds to a $+1$ ($-1$) change in baryon number across the junction.
The MC1, MC2 and MC3 mark which colour connections have been traced in a PYPREP rearrangement procedure, as above.

P(I,1) :

$p_x$, momentum in the $x$ direction, in GeV/$c$.

P(I,2) :

$p_y$, momentum in the $y$ direction, in GeV/$c$.

P(I,3) :

$p_z$, momentum in the $z$ direction, in GeV/$c$.

P(I,4) :

$E$, energy, in GeV.

P(I,5) :

$m$, mass, in GeV/$c^2$. In parton showers, with space-like virtualities, i.e. where $Q^2 = - m^2 > 0$, one puts P(I,5)$= -Q$.

V(I,1) :

$x$ position of production vertex, in mm.

V(I,2) :

$y$ position of production vertex, in mm.

V(I,3) :

$z$ position of production vertex, in mm.

V(I,4) :

time of production, in mm/$c$ ( $\approx 3.33 \times 10^{-12}$ s).

V(I,5) :

proper lifetime of particle, in mm/$c$ ( $\approx 3.33 \times 10^{-12}$ s). If the particle is not expected to decay, V(I,5)=0. A line with K(I,1)=4, i.e. a particle that could have decayed, but did not within the allowed region, has the proper non-zero V(I,5).

In the absence of electric or magnetic fields, or other disturbances, the decay vertex VP of an unstable particle may be calculated as
VP(j) = V(I,j) + V(I,5)*P(I,j)/P(I,5), j = 1-4.