Event information

Inside the event loop of the main program, PYEVNT will be called to generate the next event, as usual. When this is to be an external process, the parton-level event configuration and the event weight is found by a call from PYEVNT to UPEVNT.

Purpose:

routine to be provided by you when you want to implement external processes, wherein the contents of the HEPEUP common block are set. This information specifies the next parton-level event, and some additional event information, see further below. How UPEVNT is expected to solve its task depends on the model selected in IDWTUP, see above. Specifically, note that the process type IDPRUP has already been selected for some IDWTUP options (and then cannot be overwritten), while it remains to be chosen for others.

Note :

a dummy copy of UPEVNT is distributed with the program, in order to avoid potential problems with unresolved external references. This dummy should not be linked when you supply your own UPEVNT routine.

Purpose :

to contain information on the latest external process generated in UPEVNT. A part is one-of-a-kind numbers, like the event weight, but the bulk of the information is a listing of incoming and outgoing particles, with history, colour, momentum, lifetime and spin information.

MAXNUP :

the maximum number of particles that can be specified by the external process.
The maximum of 500 is more than PYTHIA is set up to handle. By default, MSTP(126) = 100, at most 96 particles could be specified, since 4 additional entries are needed in PYTHIA for the two beam particles and the two initiators of initial-state radiation. If this default is not sufficient, MSTP(126) would have to be increased at the beginning of the run.

NUP :

the number of particle entries in the current parton-level event, stored in the NUP first entries of the IDUP, ISTUP, MOTHUP, ICOLUP, PUP, VTIMUP and SPINUP arrays.
The special value NUP = 0 is used to denote the case where UPEVNT is unable to provide an event, at least of the type requested by PYEVNT, e.g. because all events available in a file have already been read. For such an event also the error flag MSTI(51) = 1 instead of the normal = 0.

IDPRUP :

the identity of the current process, as given by the LPRUP codes.
When IDWTUP = $\pm 1$ or $\pm 2$, IDPRUP is selected by PYEVNT and already set when entering UPEVNT. Then UPEVNT has to provide an event of the specified process type, but cannot change IDPRUP. When IDWTUP = $\pm 3$ or $\pm 4$, UPEVNT is free to select the next process, and then should set IDPRUP accordingly.

XWGTUP :

the event weight. The precise definition of XWGTUP depends on the value of the IDWTUP master switch. For IDWTUP = 1 or = 4 it is a dimensional quantity, in pb, with a mean value converging to the total cross section of the respective process. For IDWTUP = 2 the overall normalization is irrelevant. For IDWTUP = 3 only the value +1 is allowed. For negative IDWTUP also negative weights are allowed, although positive and negative weights cannot appear mixed in the same process for IDWTUP = -1 or = -2.

SCALUP :

scale $Q$ of the event, as used in the calculation of parton distributions (factorization scale). If the scale has not been defined, this should be denoted by using the value -1.
In PYTHIA, this is input to PARI(21) - PARI(26) (and internally VINT(51) - VINT(56)) When SCALUP is non-positive, the invariant mass of the parton-level event is instead used as scale. Either of these comes to set the maximum virtuality in the initial-state parton showers. The same scale is also used for the first final-state shower, i.e. the one associated with the hard scattering. As in internal events, PARP(67) and PARP(71) offer multiplicative factors, whereby the respective initial- or final-state showering $Q_{\mathrm{max}}^2$ scale can be modified relative to the scale above. Any subsequent final-state showers are assumed to come from resonance decays, where the resonance mass always sets the scale. Since SCALUP is not directly used inside PYTHIA to evaluate parton densities, its role as regulator of parton-shower activity may be the more important one.

AQEDUP :

the QED coupling $\alpha_{\mathrm{em}}$ used for this event. If $\alpha_{\mathrm{em}}$ has not been defined, this should be denoted by using the value -1.
In PYTHIA, this value is stored in VINT(57). It is not used anywhere, however.

AQCDUP :

the QCD coupling $\alpha_{\mathrm{s}}$ used for this event. If $\alpha_{\mathrm{s}}$ has not been defined, this should be denoted by using the value -1.
In PYTHIA, this value is stored in VINT(58). It is not used anywhere, however.

IDUP(i) :

particle identity code, according to the PDG convention, for particle i. As an extension to this standard, IDUP(i) = 0 can be used to designate an intermediate state of undefined (and possible non-physical) character, e.g. a subsystem with a mass to be preserved by parton showers.
In the PYTHIA event record, this corresponds to the KF = K(I,2) code. But note that, here and in the following, the positions i in HEPEUP and I in PYJETS are likely to be different, since PYTHIA normally stores more information in the beginning of the event record. Since K(I,2) = 0 is forbidden, the IDUP(i) = 0 code is mapped to K(I,2) = 90.

ISTUP(i) :

status code of particle i.

= -1 :

an incoming particle of the hard-scattering process.
In PYTHIA, currently it is presumed that the first two particles, i = 1 and = 2, are of this character, and none of the others. If this is not the case, the HEPEUP record will be rearranged to put such entries first. If the listing is still not acceptable after this, the program execution will stop. This is a restriction relative to the standard, which allows more possibilities. It is also presumed that these two particles are given with vanishing masses and parallel to the respective incoming beam direction, i.e. $E = p_z$ for the first and $E = - p_z$ for the second. The assignment of spacelike virtualities and nonvanishing $p_{\perp}$'s from initial-state radiation and primordial $k_{\perp}$'s is the prerogative of PYTHIA.

= 1 :

an outgoing final-state particle.
Such a particle can, of course, be processed further by PYTHIA, to add showers and hadronization, or perform decays of any remaining resonances.

= 2 :

an intermediate resonance, whose mass should be preserved by parton showers. For instance, in a process such as $\mathrm{e}^+\mathrm{e}^- \to \mathrm{Z}^0 \mathrm{h}^0 \to \mathrm{q}\overline{\mathrm{q}}\, \b\overline{\mathrm{b}}$, the $\mathrm{Z}^0$ and $\mathrm{h}^0$ should both be flagged this way, to denote that the $\mathrm{q}\overline{\mathrm{q}}$ and $\b\overline{\mathrm{b}}$ systems should have their individual masses preserved. In a more complex example, $\d\overline{\mathrm{u}}\to \mathrm{W}^-\mathrm{Z}^0\mathrm{g}\to %% \ell^-\overline{\nu}_{\ell} \, \mathrm{q}\overline{\mathrm{q}}\, \mathrm{g}$, both the $\mathrm{W}^-$ and $\mathrm{Z}^0$ particles and the $\mathrm{W}^-\mathrm{Z}^0$ pseudoparticle (with IDUP(i) = 0) could be given with status 2.
Often mass preservation is correlated with colour singlet subsystems, but this need not be the case. In $\mathrm{e}^+ \mathrm{e}^- \to \t\overline{\mathrm{t}}\to \b\mathrm{W}^+ \, \overline{\mathrm{b}}\mathrm{W}^-$, the $\b$ and $\overline{\mathrm{b}}$ would be in a colour singlet state, but not with a preserved mass. Instead the $\t = \b\mathrm{W}^+$ and $\overline{\mathrm{t}}= \overline{\mathrm{b}}\mathrm{W}^-$ masses would be preserved, i.e. when $\b$ radiates $\b\to \b\mathrm{g}$ the recoil is taken by the $\mathrm{W}^+$. Exact mass preservation also by the hadronization stage is only guaranteed for colour singlet subsystems, however, at least for string fragmentation, since it is not possible to define a subset of hadrons that uniquely belong only with a single coloured particle.
The assignment of intermediate states is not always quantum mechanically well-defined. For instance, $\mathrm{e}^+\mathrm{e}^- \to \mu^- \mu^+ \nu_{\mu} \overline{\nu}_{\mu}$ can proceed both through a $\mathrm{W}^+ \mathrm{W}^-$ and a $\mathrm{Z}^0 \mathrm{Z}^0$ intermediate state, as well as through other graphs, which can interfere with each other. It is here the responsibility of the matrix-element-generator author to pick one of the alternatives, according to some convenient recipe. One option might be to perform two calculations, one complete to select the event kinematics and calculate the event weight, and a second with all interference terms neglected to pick the event history according to the relative weight of each graph. Often one particular graph would dominate, because a certain pairing of the final-state fermions would give invariant masses on or close to some resonance peaks.
In PYTHIA, the identification of an intermediate resonance is not only a matter of preserving a mass, but also of improving the modelling of the final-state shower evolution, since matrix-element-correction factors have been calculated for a variety of possible resonance decays and implemented in the respective parton shower description, see subsection .

= 3 :

an intermediate resonance, given for documentation only, without any demand that the mass should be preserved in subsequent showers.
In PYTHIA, currently particles defined with this option are not treated any differently from the ones with = 2.

= -2 :

an intermediate space-like propagator, defining an $x$ and a $Q^2$, in the Deeply Inelastic Scattering terminology, which should be preserved.
In PYTHIA, currently this option is not defined and should not be used. If it is, the program execution will stop.

= -9 :

an incoming beam particle at time $t = -\infty$. Such beams are not required in most cases, since the HEPRUP common block normally contains the information. The exceptions are studies with non-collinear beams and with varying-energy beams (e.g. from beamstrahlung, subsection ), where HEPRUP does not supply sufficient flexibility. Information given with = -9 overwrites the one given in HEPRUP.
This is an optional part of the standard, since it may be difficult to combine with some of the IDWTUP options.
Currently it is not recognized by PYTHIA. If it is used, the program execution will stop.

MOTHUP(1,i), MOTHUP(2,i) :

position of the first and last mother of particle i. Decay products will normally have only one mother. Then either MOTHUP(2,i) = 0 or MOTHUP(2,i) = MOTHUP(1,i). Particles in the outgoing state of a $2 \to n$ process have two mothers. This scheme does not limit the number of mothers, so long as these appear consecutively in the listing, but in practice there will likely never be more than two mothers per particle.
As has already been mentioned for ISTUP(i) = 2, the definition of history is not always unique. Thus, in a case like $\mathrm{e}^+\mathrm{e}^- \to \mu^+ \mu^- \gamma$, proceeding via an intermediate $\gamma^* / \mathrm{Z}^0$, the squared matrix element contains an interference term between initial- and final-state emission of the photon. This ambiguity has to be resolved by the matrix-elements-based generator.
In PYTHIA, only information on the first mother survives into K(I,3). This is adequate for resonance decays, while particles produced in the primary $2 \to n$ process are given mother code 0, as is customary for internal processes. It implies that two particles are deemed to have the same mothers if the first one agrees; it is difficult to conceive of situations where this would not be the case. Furthermore, it is assumed that the MOTHUP(1,i) < i, i.e. that mothers are stored ahead of their daughters, and that all daughters of a mother are listed consecutively, i.e. without other particles interspersed. If this is not the case, the HEPEUP record will be rearranged so as to adhere to these principles.
PYTHIA has a limit of at most 80 particles coming from the same mother, for the final-state parton shower algorithm to work. In fact, the shower is optimized for a primary $2 \to 2$ process followed by some sequence of $1 \to 2$ resonance decays. Then colour coherence with the initial state, matrix-element matching to gluon emission in resonance decays, and other sophisticated features are automatically included. By contrast, the description of emission in systems with three or more partons is less sophisticated. Apart from problems with the algorithm itself, more information would be needed to do a good job than is provided by the standard. Specifically, there is a significant danger of double counting or gaps between the radiation already covered by matrix elements and the one added by the shower. The omission from HEPEUP of intermediate resonances known to be there, so that e.g. two consecutive $1 \to 2$ decays are bookkept as a single $1\to 3$ branching, is a simple way to reduce the reliability of your studies!

ICOLUP(1,i), ICOLUP(2,i) :

integer tags for the colour flow lines passing through the colour and anticolour, respectively, of the particle. Any particle with colour (anticolour), such as a quark (antiquark) or gluon, will have the first (second) number nonvanishing.
The tags can be viewed as a numbering of different colours in the $N_C \to \infty$ limit of QCD. Any nonzero integer can be used to represent a different colour, but the standard recommends to stay with positive numbers larger than MAXNUP to avoid confusion between colour tags and the position labels i of particles.
The colour and anticolour of a particle is defined with the respect to the physical time ordering of the process, so as to allow a unique definition of colour flow also through intermediate particles. That is, a quark always has a nonvanishing colour tag ICOLUP(1,i), whether it is in the initial, intermediate or final state. A simple example would be $\mathrm{q}\overline{\mathrm{q}}\to \t\overline{\mathrm{t}}\to \b\mathrm{W}^+ \overline{\mathrm{b}}\mathrm{W}^-$, where the same colour label is to be used for the $\mathrm{q}$, the $\t$ and the $\b$. Correspondingly, the $\overline{\mathrm{q}}$, $\overline{\mathrm{t}}$ and $\overline{\mathrm{b}}$ share another colour label, now stored in the anticolour position ICOLUP(2,i).
The colour label in itself does not distinguish between the colour or the anticolour of a given kind; that information appears in the usage either of the ICOLUP(1,i) or of the ICOLUP(2,i) position for the colour or anticolour, respectively. Thus, in a $\mathrm{W}^+ \to \u\overline{\mathrm{d}}$ decay, the $\u$ and $\overline{\mathrm{d}}$ would share the same colour label, but stored in ICOLUP(1,i) for the $\u$ and in ICOLUP(2,i) for the $\overline{\mathrm{d}}$.
In general, several colour flows are possible in a given subprocess. This leads to ambiguities, of a character similar to the ones for the history above, and as is discussed in subsection . Again it is up to the author of the matrix-elements-based generator to find a sensible solution. It is useful to note that all interference terms between different colour flow topologies vanish in the $N_C \to \infty$ limit of QCD. One solution would then be to use a first calculation in standard QCD to select the momenta and find the weight of the process, and a second with $N_C \to \infty$ to pick one specific colour topology according to the relative probabilities in this limit.
The above colour scheme also allows for baryon number violating processes. Such a vertex would appear as `dangling' colour lines, when the ICOLUP and MOTHUP information is correlated. For instance, in $\tilde{\mathrm u}\to \overline{\mathrm{d}}\overline{\mathrm{d}}$ the $\tilde{\mathrm u}$ inherits an existing colour label, while the two $\overline{\mathrm{d}}$'s are produced with two different new labels.
Several examples of colour assignments, both with and without baryon number violation, are given in [Boo01].
In PYTHIA, baryon number violation is not yet implemented as part of the external-process machinery (but exists for internal processes, including internally handled decays of resonances provided externally). It will require substantial extra work to lift this restriction, and this is not imminent.

PUP(1,i), PUP(2,i), PUP(3,i), PUP(4,i), PUP(5,i) :

the particle momentum vector $(p_x, p_y, p_z, E, m)$, with units of GeV. A spacelike virtuality is denoted by a negative sign on the mass.
Apart from the index order, this exactly matches the P momentum conventions in PYJETS.
PYTHIA is forgiving when it comes to using other masses than its own, e.g. for quarks. Thus the external process can be given directly with the $m_{\b }$ used in the calculation, without any worry how this matches the PYTHIA default. However, remember that the two incoming particles with ISTUP(i) = -1 have to be massless.

VTIMUP(i) :

invariant lifetime $c\tau$ in mm, i.e. distance from production to decay. Once the primary vertex has been selected, the subsequent decay vertex positions in space and time can be constructed step by step, by also making use of the momentum information. Propagation in vacuum, without any bending e.g. by magnetic fields, has to be assumed.
This exactly corresponds to the V(I,5) component in PYJETS. Note that it is used in PYTHIA to track colour singlet particles through distances that might be observable in a detector. It is not used to trace the motion of coloured partons at fm scales, through the hadronization process. Also note that PYTHIA will only use this information for intermediate resonances, not for the initial- and final-state particles. For instance, for an undecayed $\tau^-$, the lifetime is selected as part of the $\tau^-$ decay process, not based on the VTIMUP(i) value.

SPINUP(i) :

cosine of the angle between the spin vector of a particle and its three-momentum, specified in the lab frame, i.e. the frame where the event as a whole is defined. This scheme is neither general nor complete, but it is chosen as a sensible compromise.
The main foreseen application is $\tau$'s with a specific helicity. Typically a relativistic $\tau^-$ ($\tau^+$) coming from a $\mathrm{W}^-$ ($\mathrm{W}^+$) decay would have helicity and SPINUP(i) = $-1$ ($+1$). This could be changed by the boost from the $\mathrm{W}$ rest frame to the lab frame, however. The use of a real number, rather than an integer, allows for an extension to the non-relativistic case.
Particles which are unpolarized or have unknown polarization should be given SPINUP(i) = 9.
Explicit spin information is not used anywhere in PYTHIA. It is implicit in many production and decay matrix elements, which often contain more correlation information than could be conveyed by the simple spin numbers discussed here. Correspondingly, it is to be expected that the external generator already performed the decays of the $\mathrm{W}$'s, the $\mathrm{Z}$'s and the other resonances, so as to include the full spin correlations. If this is not the case, such resonances will normally be decayed isotropically. Some correlations could appear in decay chains: the PYTHIA decay $\t\to \b\mathrm{W}^+$ is isotropic, but the subsequent $\mathrm{W}^+ \to \mathrm{q}_1 \overline{\mathrm{q}}_2$ decay contains implicit $\mathrm{W}$ helicity information from the $\t$ decay.
Also $\tau$ decays performed by PYTHIA would be isotropic. An interface routine PYTAUD (see subsection ) can be used to link to external $\tau$ decay generators, but is based on defining the $\tau$ in the rest frame of the decay that produces it, and so is not directly applicable here. Eventually, it will be rewritten to make use of the SPINUP(i) information. In the meantime, and of course also afterwards, a valid option is to perform the $\tau$ decays yourself before passing `parton-level' events to PYTHIA.

One auxiliary routine exists, that formally is part of the PYTHIA package, but could be used by any generator:

SUBROUTINE PYUPRE :

called immediately after UPEVNT has been called to provide a user-process event. It will rearrange the contents of the HEPEUP common block so that afterwards the two incoming partons appear in lines 1 and 2, so that all mothers appear ahead of their daughters, and so that the daughters of a decay are listed consecutively. Such an order can thereby be presumed to exist in the subsequent parsing of the event. If the rules already are obeyed, the routine does not change anything.