Event Study Routines

After a PYEVNT call, or another similar physics routine call, the event generated is stored in the PYJETS common block, and whatever physical variable is desired may be constructed from this record. An event may be rotated, boosted or listed, and particle data may be listed or modified. Via the functions PYK and PYP the values of some frequently appearing variables may be obtained more easily. As described in subsequent sections, also more detailed event shape analyses may be performed simply.

Purpose:

to perform rotations and Lorentz boosts (in that order, if both in the same call) of jet/particle momenta and vertex position variables.

IMI, IMA :

range of entries affected by transformation, IMI$\leq$I$\leq$IMA. If 0 or below, IMI defaults to 1 and IMA to N. Lower and upper bounds given by positive MSTU(1) and MSTU(2) override the IMI and IMA values, and also the 1 to N constraint.

THE, PHI :

standard polar coordinates $\theta, \varphi$, giving the rotated direction of a momentum vector initially along the $+z$ axis.

BEX, BEY, BEZ :

gives the direction and size $\beta$ of a Lorentz boost, such that a particle initially at rest will have $\mathbf{p}/E =$$\beta$ afterwards.

Remark:

all entries in the range IMI-IMA (or modified as described above) are affected, unless the status code of an entry is K(I,1)$\leq 0$.

Purpose:

to exclude unstable or undetectable jets/particles from the event record. One may also use PYEDIT to store spare copies of events (specifically initial parton configuration) that can be recalled to allow e.g. different fragmentation schemes to be run through with one and the same parton configuration. Finally, an event which has been analyzed with PYSPHE, PYTHRU or PYCLUS (see section ) may be rotated to align the event axis with the $z$ direction.

MEDIT :

tells which action is to be taken.

= 0 :

empty (K(I,1)=0) and documentation (K(I,1)>20) lines are removed. The jets/particles remaining are compressed in the beginning of the PYJETS common block and the N value is updated accordingly. The event history is lost, so that information stored in K(I,3), K(I,4) and K(I,5) is no longer relevant.

= 1 :

as =0, but in addition all jets/particles that have fragmented/decayed (K(I,1)>10) are removed.

= 2 :

as =1, but also all neutrinos and unknown particles (i.e. compressed code KC$= 0$) are removed.

= 3 :

as =2, but also all uncharged, colour neutral particles are removed, leaving only charged, stable particles (and unfragmented partons, if fragmentation has not been performed).

= 5 :

as =0, but also all partons which have branched or been rearranged in a parton shower and all particles which have decayed are removed, leaving only the fragmenting parton configuration and the final-state particles.

= 11 :

remove lines with K(I,1)<0. Update event history information (in K(I,3) - K(I,5)) to refer to remaining entries.

= 12 :

remove lines with K(I,1)=0. Update event history information (in K(I,3) - K(I,5)) to refer to remaining entries.

= 13 :

remove lines with K(I,1)$= 11$, 12 or 15, except for any line with K(I,2)=94. Update event history information (in K(I,3) - K(I,5)) to refer to remaining entries. In particular, try to trace origin of daughters, for which the mother is decayed, back to entries not deleted.

= 14 :

remove lines with K(I,1)$= 13$ or 14, and also any line with K(I,2)=94. Update event history information (in K(I,3) - K(I,5)) to refer to remaining entries. In particular, try to trace origin of rearranged jets back through the parton-shower history to the shower initiator.

= 15 :

remove lines with K(I,1)>20. Update event history information (in K(I,3) - K(I,5)) to refer to remaining entries.

= 16 :

try to reconstruct missing daughter pointers of decayed particles from the mother pointers of decay products. These missing pointers typically come from the need to use K(I,4) and K(I,5) also for colour flow information.

= 21 :

all partons/particles in current event record are stored (as a spare copy) in bottom of common block PYJETS (is e.g. done to save original partons before calling PYEXEC).

= 22 :

partons/particles stored in bottom of event record with =21 are placed in beginning of record again, overwriting previous information there (so that e.g. a different fragmentation scheme can be used on the same partons). Since the copy at bottom is unaffected, repeated calls with =22 can be made.

= 23 :

primary partons/particles in the beginning of event record are marked as not fragmented or decayed, and number of entries N is updated accordingly. Is a simple substitute for =21 plus =22 when no fragmentation/decay products precede any of the original partons/particles.

= 31 :

rotate largest axis, determined by PYSPHE, PYTHRU or PYCLUS, to sit along the $z$ direction, and the second largest axis into the $xz$ plane. For PYCLUS it can be further specified to $+z$ axis and $xz$ plane with $x > 0$, respectively. Requires that one of these routines has been called before.

= 32 :

mainly intended for PYSPHE and PYTHRU, this gives a further alignment of the event, in addition to the one implied by =31. The `slim' jet, defined as the side ($z > 0$ or $z < 0$) with the smallest summed $p_{\perp}$ over square root of number of particles, is rotated into the $+z$ hemisphere. In the opposite hemisphere (now $z < 0$), the side of $x > 0$ and $x < 0$ which has the largest summed $\vert p_z\vert$ is rotated into the $z < 0, x > 0$ quadrant. Requires that PYSPHE or PYTHRU has been called before.

Remark:

all entries 1 through N are affected by the editing. For options 0-5 lower and upper bounds can be explicitly given by MSTU(1) and MSTU(2).

Purpose:

to list an event, jet or particle data, or current parameter values.

MLIST :

determines what is to be listed.

= 0 :

writes a title page with program version number and last date of change; is mostly for internal use.

= 1 :

gives a simple list of current event record, in an 80 column format suitable for viewing directly in a terminal window. For each entry, the following information is given: the entry number I, the parton/particle name (see below), the status code (K(I,1)), the flavour code KF (K(I,2)), the line number of the mother (K(I,3)), and the three-momentum, energy and mass (P(I,1) - P(I,5)). If MSTU(3) is non-zero, lines immediately after the event record proper are also listed. A final line contains information on total charge, momentum, energy and invariant mass.
The particle name is given by a call to the routine PYNAME. For an entry which has decayed/fragmented (K(I,1)= 11-20), this particle name is given within parentheses. Similarly, a documentation line (K(I,1)= 21-30) has the name enclosed in expression signs (!...!) and an event/jet axis information line the name within inequality signs ($<$...$>$). If the last character of the name is a `?', it is a signal that the complete name has been truncated to fit in, and can therefore not be trusted; this is very rare. For partons which have been arranged along strings (K(I,1)= 1, 2, 11 or 12), the end of the parton name column contains information about the colour string arrangement: an A for the first entry of a string, an I for all intermediate ones, and a V for the final one (a poor man's rendering of a vertical doublesided arrow, $\updownarrow$).
It is possible to insert lines just consisting of sequences of ====== to separate different sections of the event record, see MSTU(70) - MSTU(80).

= 2 :

gives a more extensive list of the current event record, in a 132 column format, suitable for wide terminal windows. For each entry, the following information is given: the entry number I, the parton/particle name (with padding as described for =1), the status code (K(I,1)), the flavour code KF (K(I,2)), the line number of the mother (K(I,3)), the decay product/colour-flow pointers (K(I,4), K(I,5)), and the three-momentum, energy and mass (P(I,1) - P(I,5)). If MSTU(3) is non-zero, lines immediately after the event record proper are also listed. A final line contains information on total charge, momentum, energy and invariant mass. Lines with only ====== may be inserted as for =1.

= 3 :

gives the same basic listing as =2, but with an additional line for each entry containing information on production vertex position and time (V(I,1) - V(I,4)) and, for unstable particles, proper lifetime (V(I,5)).

= 4 :

is a simpler version of the listing obtained with =2,but excluding the momentum information, and instead providing the alternative Les Houches style colour tags used for final-state colour reconnection in the new multiple interactions scenario. It thus allows colour flow to be studied and debugged in a "leaner" format.

= 5 :

gives a simple listing of the event record stored in the HEPEVT common block. This is mainly intended as a tool to check how conversion with the PYHEPC routine works. The listing does not contain vertex information, and the flavour code is not displayed as a name.

= 7 :

gives a simple listing of the parton-level event record for an external process, as stored in the HEPEUP common block. This is mainly intended as a tool to check how reading from HEPEUP input works. The listing does not contain lifetime or spin information, and the flavour code is not displayed as a name. It also does not show other HEPEUP numbers, such as the event weight.

= 11 :

provides a simple list of all parton/particle codes defined in the program, with KF code and corresponding particle name. The list is grouped by particle kind, and only within each group in ascending order.

= 12 :

provides a list of all parton/particle and decay data used in the program. Each parton/particle code is represented by one line containing KF flavour code, KC compressed code, particle name, antiparticle name (where appropriate), electrical and colour charge and presence or not of an antiparticle (stored in KCHG), mass, resonance width and maximum broadening, average proper lifetime (in PMAS) and whether the particle is considered stable or not (in MDCY). Immediately after a particle, each decay channel gets one line, containing decay channel number (IDC read from MDCY), on/off switch for the channel, matrix element type (MDME), branching ratio (BRAT), and decay products (KFDP). The MSTU(1) and MSTU(2) flags can be used to set the range of KF codes for which particles are listed.

= 13 :

gives a list of current parameter values for MSTU, PARU, MSTJ and PARJ, and the first 200 entries of PARF. This is useful to keep check of which default values were changed in a given run.

Remark:

for options 1-3 and 12 lower and upper bounds of the listing can be explicitly given by MSTU(1) and MSTU(2).

Purpose:

to provide various integer-valued event data. Note that many of the options available (in particular I$>0$, J$\geq 14$) which refer to event history will not work after a PYEDIT call. Further, the options 14-18 depend on the way the event history has been set up, so with the explosion of different allowed formats these options are no longer as safe as they may have been. For instance, option 16 can only work if MSTU(16)=2.

I=0, J= :

properties referring to the complete event.

= 1 :

N, total number of lines in event record.

= 2 :

total number of partons/particles remaining after fragmentation and decay.

= 6 :

three times the total charge of remaining (stable) partons and particles.

I>0, J= :

properties referring to the entry in line no. I of the event record.

= 1 - 5 :

K(I,1) - K(I,5), i.e. parton/particle status KS, flavour code KF and origin/decay product/colour-flow information.

= 6 :

three times parton/particle charge.

= 7 :

1 for a remaining entry, 0 for a decayed, fragmented or documentation entry.

= 8 :

KF code (K(I,2)) for a remaining entry, 0 for a decayed, fragmented or documentation entry.

= 9 :

KF code (K(I,2)) for a parton (i.e. not colour neutral entry), 0 for a particle.

= 10 :

KF code (K(I,2)) for a particle (i.e. colour neutral entry), 0 for a parton.

= 11 :

compressed flavour code KC.

= 12 :

colour information code, i.e. 0 for colour neutral, 1 for colour triplet, -1 for antitriplet and 2 for octet.

= 13 :

flavour of `heaviest' quark or antiquark (i.e. with largest code) in hadron or diquark (including sign for antiquark), 0 else.

= 14 :

generation number. Beam particles or virtual exchange particles are generation 0, original jets/particles generation 1 and then 1 is added for each step in the fragmentation/decay chain.

= 15 :

line number of ancestor, i.e. predecessor in first generation (generation 0 entries are disregarded).

= 16 :

rank of a hadron in the jet it belongs to. Rank denotes the ordering in flavour space, with hadrons containing the original flavour of the jet having rank 1, increasing by 1 for each step away in flavour ordering. All decay products inherit the rank of their parent. Whereas the meaning of a first-rank hadron in a quark jet is always well-defined, the definition of higher ranks is only meaningful for independently fragmenting quark jets. In other cases, rank refers to the ordering in the actual simulation, which may be of little interest.

= 17 :

generation number after a collapse of a parton system into one particle, with 0 for an entry not coming from a collapse, and -1 for entry with unknown history. A particle formed in a collapse is generation 1, and then one is added in each decay step.

= 18 :

number of decay/fragmentation products (only defined in a collective sense for fragmentation).

= 19 :

origin of colour for showering parton, 0 else.

= 20 :

origin of anticolour for showering parton, 0 else.

= 21 :

position of colour daughter for showering parton, 0 else.

= 22 :

position of anticolour daughter for showering parton, 0 else.

Purpose:

to provide various real-valued event data. Note that some of the options available (I$>0$, J$= 20$-25), which are primarily intended for studies of systems in their respective c.m. frame, requires that a PYEXEC call has been made for the current initial parton/particle configuration, but that the latest PYEXEC call has not been followed by a PYROBO one.

I=0, J= :

properties referring to the complete event.

= 1 - 4 :

sum of $p_x$, $p_y$, $p_z$ and $E$, respectively, for the stable remaining entries.

= 5 :

invariant mass of the stable remaining entries.

= 6 :

sum of electric charge of the stable remaining entries.

I>0, J= :

properties referring to the entry in line no. I of the event record.

= 1 - 5 :

P(I,1) - P(I,5), i.e. normally $p_x$, $p_y$, $p_z$, $E$ and $m$ for jet/particle.

= 6 :

electric charge $e$.

= 7 :

squared momentum $\vert\mathbf{p}\vert^2 = p_x^2 + p_y^2 + p_z^2$.

= 8 :

absolute momentum $\vert\mathbf{p}\vert$.

= 9 :

squared transverse momentum $p_{\perp}^2 = p_x^2 + p_y^2$.

= 10 :

transverse momentum $p_{\perp}$.

= 11 :

squared transverse mass $m_{\perp}^2 = m^2 + p_x^2 + p_y^2$.

= 12 :

transverse mass $m_{\perp}$.

= 13 - 14 :

polar angle $\theta$ in radians (between 0 and $\pi$) or degrees, respectively.

= 15 - 16 :

azimuthal angle $\varphi$ in radians (between $-\pi$ and $\pi$) or degrees, respectively.

= 17 :

true rapidity $y = (1/2) \, \ln((E+p_z)/(E-p_z))$.

= 18 :

rapidity $y_{\pi}$ obtained by assuming that the particle is a pion when calculating the energy $E$, to be used in the formula above, from the (assumed known) momentum $\mathbf{p}$.

= 19 :

pseudorapidity $\eta = (1/2) \, \ln((p+p_z)/(p-p_z))$.

= 20 :

momentum fraction $x_p = 2\vert\mathbf{p}\vert/W$, where $W$ is the total energy of the event, i.e. of the initial jet/particle configuration.

= 21 :

$x_{\mathrm{F}} = 2p_z/W$ (Feynman-$x$ if system is studied in the c.m. frame).

= 22 :

$x_{\perp} = 2p_{\perp}/W$.

= 23 :

$x_E = 2E/W$.

= 24 :

$z_+ = (E+p_z)/W$.

= 25 :

$z_- = (E-p_z)/W$.

Purpose:

to give access to a number of status codes that regulate the behaviour of the event study routines. The main reference for PYDAT1 is in section .

MSTU(1),MSTU(2) :

(D=0,0) can be used to replace the ordinary lower and upper limits (normally 1 and N) for the action of PYROBO, and most PYEDIT and PYLIST calls. Are reset to 0 in a PYEXEC call.

MSTU(3) :

(D=0) number of lines with extra information added after line N. Is reset to 0 in a PYEXEC call, or in an PYEDIT call when particles are removed.

MSTU(11) :

(D=6) file number to which all program output is directed. It is your responsibility to see to it that the corresponding file is also opened for output.

MSTU(12) :

(D=1) writing of title page (version number and last date of change for PYTHIA) on output file.

= 0 :

not done.

= 1 :

title page is written at first occasion, at which time MSTU(12) is set =0.

MSTU(32) :

(I) number of entries stored with PYEDIT(21) call.

MSTU(33) :

(I) if set 1 before a PYROBO call, the V vectors (in the particle range to be rotated/boosted) are set 0 before the rotation/boost. MSTU(33) is set back to 0 in the PYROBO call.

MSTU(70) :

(D=0) the number of lines consisting only of equal signs (======) that are inserted in the event listing obtained with PYLIST(1), PYLIST(2) or PYLIST(3), so as to distinguish different sections of the event record on output. At most 10 such lines can be inserted; see MSTU(71) - MSTU(80). Is reset at PYEDIT calls with arguments 0-5.

MSTU(71) - MSTU(80) :

line numbers below which lines consisting only of equal signs (======) are inserted in event listings. Only the first MSTU(70) of the 10 allowed positions are enabled.