Further comments

This section contains additional information on a few different topics: cross section interpretation, negative-weight events, relations with other PYTHIA switches and routines, and error conditions.

In several `IDWTUP` options,
the `XWGTUP` variable is supposed to give the differential
cross section of the current event, times the phase-space volume
within which events are generated, expressed in picobarns.
(Converted to millibarns inside PYTHIA.) This means that, in the limit
that many events are generated, the average value of `XWGTUP`
gives the total cross section of the simulated process.
Of course, the tricky part is that the differential cross section
usually is strongly peaked in a few regions of the phase space, such
that the average probability to accept an event,
`XWGTUP``XMAXUP(i)` is
small. It may then be necessary to find a suitable set of transformed
phase-space coordinates, for which the correspondingly transformed
differential cross section is better behaved.

To avoid confusion, here is a more formal version of the above
paragraph. Call the differential phase space, e.g. for a
process
, where and
are the momentum fractions carried by the two incoming partons and
the Mandelstam variable of the scattering (see section
). Call
the differential cross section
of the process, e.g. for :
,
i.e. the product of parton distributions and hard-scattering matrix
elements, summed over all allowed incoming flavours and .
The physical cross section that one then wants to generate is
, where the integral is over
the allowed phase-space volume. The event generation procedure consists
of selecting an uniformly in and then evaluating the weight
at this point. `XWGTUP` is now simply
`XWGTUP`
, i.e. the differential
cross section times the considered volume of phase space. Clearly,
when averaged over many events, `XWGTUP` will correctly estimate
the desired cross section. If `XWGTUP` fluctuates too much, one
may try to transform to new variables ,
where events are now picked accordingly to and
`XWGTUP`
.

A warning. It is important that is indeed uniformly picked within the allowed phase space, alternatively that any Jacobians are properly taken into account. For instance, in the case above, one approach would be to pick , and uniformly in the ranges , , and , with full phase space volume . The cross section would only be non-vanishing inside the physical region given by (in the massless case), i.e. Monte Carlo efficiency is likely to be low. However, if one were to choose values only in the range , small values would be favoured, since the density of selected values would be larger there. Without the use of a compensating Jacobian , an incorrect answer would be obtained. Alternatively, one could start out with a phase space like , where the limits decouple. Of course, the variable can be translated back into a , which will then always be in the desired range . The transformation itself here gives the necessary Jacobian.

At times, it is convenient to split a process into a discrete set of
subprocesses for the parton-level generation, without retaining these
in the `IDPRUP` classification. For instance, the cross section above
contains a summation over incoming partons. An alternative would then
have been to let each subprocess correspond to one unique combination
of incoming flavours. When an event of process type is to be
generated, first a specific subprocess is selected with probability
, where
. For this subprocess an
`XWGTUP` is generated as above, except that there is no longer
a summation over incoming flavours. Since only a fraction of all
events now contain this part of the cross section, a compensating factor
is introduced, i.e. `XWGTUP``XWGTUP`.
Further, one has to define
`XMAXUP(i)`
`XMAXUP` and
`XSECUP(i)` `XSECUP`.
The generation efficiency will be maximized for the coefficients
selected proportional to `XMAXUP`, but this is no requirement.

The standard allows external parton-level events to come with negative weights, unlike the case for internal PYTHIA processes. In order to avoid indiscriminate use of this option, some words of caution are in place. In next-to-leading-order calculations, events with negative weights may occur as part of the virtual corrections. In any physical observable quantity, the effect of such events should cancel against the effect of real events with one more parton in the final state. For instance, the next-to-leading order calculation of gluon scattering contains the real process , with a positive divergence in the soft and collinear regions, while the virtual corrections to are negatively divergent. Neglecting the problems of outgoing gluons collinear with the beams, and those of soft gluons, two nearby outgoing gluons in the process can be combined into one effective one, such that the divergences can be cancelled.

If rather widely separated gluons can be combined, the remaining negative contributions are not particularly large. Different separation criteria could be considered; one example would be . The recombination of well separated partons is at the price of an arbitrariness in the choice of clustering algorithm, when two gluons of nonvanishing invariant mass are to be combined into one massless one, as required to be able to compare with the kinematics of the massless process when performing the divergence cancellations. Alternatively, if a smaller cut is used, where the combining procedure is less critical, there will be more events with large positive and negative weights that are to cancel.

Without proper care, this cancellation could easily be destroyed by the subsequent showering description, as follows. The standard for external processes does not provide any way to pass information on the clustering algorithm used, so the showering routine will have to make its own choice what region of phase space to populate with radiation. One choice could be to allow a cone defined by the nearest colour-connected parton (see section for a discussion). There could then arise a significant mismatch in shower description between events where two gluons are just below or just above the cut for being recombined, equivalently between and events. Most of the phase space may be open for the former, while only the region below may be it for the latter. Thus the average `two-parton' events may end up containing significantly more jet activity than the corresponding `three-parton' ones. The smaller the cut, the more severe the mismatch, both on an event-by-event basis and in terms of the event rates involved.

One solution would be to extend the standard also to specify which clustering algorithm has been used in the matrix-element calculation, and with what parameter values. Any shower emission that would give rise to an extra jet, according to this algorithm, would be vetoed. If a small cut is used, this is almost equivalent to allowing no shower activity at all. (That would still leave us with potential mismatch problems in the hadronization description. Fortunately the string fragmentation approach is very powerful in this respect, with a smooth transition between two almost parallel gluons and a single one with the full energy [Sjö84].) But we know that the unassisted matrix-element description cannot do a good job of the internal structure of jets on an event-by-event basis, since multiple-gluon emission is the norm in this region. Therefore a will be required, to let the matrix elements describe the wide-angle emission and the showers the small-angle one. This again suggests a picture with only a small contribution from negative-weight events. In summary, the appearance of a large fraction of negative-weight events should be a sure warning sign that physics is likely to be incorrectly described.

The above example illustrates that it may, at times, be desirable to
sidestep the standard and provide further information directly in the
PYTHIA common blocks. (Currently there is no exact match to the
clustering task mentioned above, although the already-described
`UPVETO` routine, section , could be constructed
to make use of such information. Here we concentrate on a few simpler
ways to intervene, possibly to be used in
conjunction with `UPVETO`.) Then it is useful to note that,
apart from the hard-process generation machinery itself, the external
processes are handled almost exactly as the internal ones. Thus
essentially all switches and parameter values related to showers,
underlying events and hadronization can be modified at will. This even
applies to alternative listing modes of events and history pointers,
as set by `MSTP(128)`. Also some of the information on the hard
scattering is available, such as `MSTI(3)`,
`MSTI(21) - MSTI(26)`, and `PARI(33) - PARI(38)`. Before using
them, however, it is prudent to check that your variables of interest
do work as intended for the particular process you study. Several
differences do remain between internal and external processes, in
particular related to final-state showers and resonance decays. For
internal processes, the `PYRESD` routine will perform a shower
(if relevant) directly after each decay. A typical example would be
that a
decay is immediately followed by a shower,
which could change the momentum of the before it decays in its
turn. For an external process, this decay chain would presumably
already have been carried out. When the equivalent shower to the
above is performed, it is therefore now necessary also to boost the
decay products of the . The special sequence of showers and boosts
for external processes is administrated by the `PYADSH` routine.
Should the decay chain not have been carried out, e.g if `HEPEUP`
event record contains an undecayed , then `PYRESD` will
be called to let it decay. The decay products will be visible also
in the documentation section, as for internal processes.

You are free to make use of whatever tools you want in your
`UPINIT` and `UPEVNT` routines, and normally there would be
little or no contact with the rest of PYTHIA, except as described above.
However, several PYTHIA tools can be used, if you so wish. One
attractive possibility is to use `PYPDFU` for
parton-distribution-function evaluation. Other possible tools could
be `PYR` for random-number generation, `PYALPS` for
evaluation, `PYALEM` for evaluation of a running
, and
maybe a few more.

We end with a few comments on anomalous situations. As already
described, you may put `NUP = 0` inside `UPEVNT`, e.g.
to signal the end of the file from which events are read.
If the program encounters this value at a return from `UPEVNT`,
then it will also exit from `PYEVNT`, without incrementing the
counters for the number of events generated. It is then up to you to
have a check on this condition in your main event-generation loop.
This you do either by looking at `NUP` or at `MSTI(51)`; the
latter is set to 1 if no event was generated.

It may also happen that a parton-level configuration fails elsewhere
in the `PYEVNT` call. For instance, the beam-remnant treatment
occasionally encounters situations it cannot handle, wherefore the
parton-level event is rejected and a new one generated. This happens also
with ordinary (not user-defined) events, and usually comes about as a
consequence of the initial-state radiation description leaving too
little energy for the remnant. If the same hard scattering were to
be used as input for a new initial-state radiation and beam-remnant
attempt, it could then work fine. There is a possibility to give events
that chance, as follows. `MSTI(52)` counts the number of times a
hard-scattering configuration has failed to date. If you come in to
`UPEVNT` with `MSTI(52)` non-vanishing, this means that the
latest configuration failed. So long as the contents of the `HEPEUP`
common block are not changed, such an event may be given another try.
For instance, a line

IF(MSTI(52).GE.1.AND.MSTI(52).LE.4) RETURNat the beginning of

The above comment only refers to very rare occurrences (less than one in a hundred), which are not errors in a strict sense; for instance, they do not produce any error messages on output. If you get warnings and error messages that the program does not understand the flavour codes or cannot reconstruct the colour flows, it is due to faults of yours, and giving such events more tries is not going to help.