Next: An example
Up: How to Include External
Previous: Run 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.
- 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. The code can be used to read event information previously
written by PYUPEV, however.
- 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
- 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
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 = or , 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 = or ,
UPEVNT is free to select the next process, and then should set
- 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 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
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
used for this
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,
- AQCDUP :
- the QCD coupling
used for this
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,
- 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. for the first and for the second. Should the
particles not be massless at input, and is shuffled between the
two incoming partons to assure this, while preserving the total quantities.
The assignment of space-like virtualities and nonvanishing 's from
initial-state radiation and primordial '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
, the and
should both be flagged this way, to denote that the
systems should have their individual masses preserved.
In a more complex example,
, both the and
particles and the
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
, the and
would be in a colour singlet state, but not with a
preserved mass. Instead the
masses would be preserved, i.e. when radiates
the recoil is taken by the . 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
The assignment of intermediate states is not always quantum mechanically
well-defined. For instance,
both through a
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 section
- = 3 :
- an intermediate resonance, given for documentation only,
without any demand that the mass should be preserved in subsequent
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
and a , 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 . 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, section ), 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
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
As has already been mentioned for ISTUP(i) = 2, the definition of
history is not always unique. Thus, in a case like
, proceeding via an intermediate
, 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 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 process followed by some sequence
of 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 than is provided by the standard would be needed to
do a good job. 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 decays are bookkept as a single
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
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
, where the same colour
label is to be used for the , the and the . Correspondingly,
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
decay, the and
would share the same colour label, but stored
in ICOLUP(1,i) for the and in ICOLUP(2,i) for the
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 section .
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
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
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
inherits an existing
colour label, while the two
's are produced with two different
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
- PUP(1,i), PUP(2,i), PUP(3,i), PUP(4,i), PUP(5,i) :
- the particle momentum vector
, with units of GeV.
A space-like 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 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,
and will be modified correspondingly if this is not the case at input.
- VTIMUP(i) :
- invariant lifetime 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
, the lifetime is selected as part of the 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
The main foreseen application is 's with a specific helicity.
Typically a relativistic () coming from a
() decay would have helicity and SPINUP(i) = ().
This could be changed by the boost from the 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 's, the '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
is isotropic, but the
decay contains implicit helicity
information from the decay.
Also decays performed by PYTHIA would be isotropic. An interface
routine PYTAUD (see section ) can be used
to link to external decay generators, but is based on defining
the in the rest frame of the decay that produces it, and so is
not directly applicable here. It could be rewritten to make use of the
SPINUP(i) information, however. In the meantime, and of
course also afterwards, a valid option is to perform the 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 the order. Further, the routine
can shuffle energy and momentum between the two incoming partons
to ensure that they are both massless.
Next: An example
Up: How to Include External
Previous: Run information