How to Include External Processes

Despite a large repertory of processes in PYTHIA, the number of interesting missing ones clearly is even larger, and with time this discrepancy is likely to increase. There are several reasons why it is not practicable to imagine a PYTHIA which has `everything'. One is the amount of time it takes to implement a process for the few PYTHIA authors, compared with the rate of new cross section results produced by the rather larger matrix-element calculations community. Another is the length of currently produced matrix-element expressions, which would make the program very bulky. A third argument is that, whereas the phase space of $2 \to 1$ and $2 \to 2$ processes can be set up once and for all according to a reasonably flexible machinery, processes with more final-state particles are less easy to generate. To achieve a reasonable efficiency, it is necessary to tailor the phase-space selection procedure to the dynamics of the given process, and to the desired experimental cuts.

At times, simple solutions may be found. Some processes may be seen just as trivial modifications of already existing ones. For instance, you might want to add some extra term, corresponding to contact interactions, to the matrix elements of a PYTHIA $2 \to 2$ process. In that case it is not necessary to go through the machinery below, but instead you can use the PYEVWT routine (subsection ) to introduce an additional weight for the event, defined as the ratio of the modified to the unmodified differential cross sections. If you use the option MSTP(142)=2, this weight is considered as part of the `true' cross section of the process, and the generation is changed accordingly.

A PYTHIA expert could also consider implementing a new process along the lines of the existing ones, hardwired in the code. Such a modification would have to be ported anytime the PYTHIA program is upgraded, however (unless it is made available to the PYTHIA authors and incorporated into the public distribution). For this and other reasons, we will not consider this option in detail, but only provide a few generic remarks. The first step is to pick a process number ISUB among ones not in use. The process type needs to be set in ISET(ISUB) and, if the final state consists of massive particles, these should be specified in KFPR(ISUB,1) and KFPR(ISUB,2). Output is improved if a process name is set in PROC(ISUB). The second and main step is to code the cross section of the hard scattering subprocess in the PYSIGH routine. Usually the best starting point is to use the code of an existing similar process as a template for the new code required. The third step is to program the selection of the final state in PYSCAT, normally a simple task, especially if again a similar process (especially with respect to colour flow) can be used as template. In many cases the steps above are enough, in others additional modifications are required to PYRESD to handle process-specific non-isotropic decays of resonances. Further code may also be required e.g. if a process can proceed via an intermediate resonance that can be on the mass shell.

The recommended solution, if a desired process is missing, is instead to include it into PYTHIA as an `external' process. In this section we will describe how it is possible to specify the parton-level state of some hard-scattering process in a common block. (`Parton-level' is not intended to imply a restriction to quarks and gluons as interacting particles, but only that quarks and gluons are given rather than the hadrons they will produce in the observable final state.) PYTHIA will read this common block, and add initial- and final-state showers, beam remnants and underlying events, fragmentation and decays, to build up an event in as much detail as an ordinary PYTHIA one. Another common block is to be filled with information relevant for the run as a whole, where beams and processes are specified.

Such a facility has been available since long, and has been used e.g. together with the COMPHEP package. COMPHEP [Puk99] is mainly intended for the automatic computation of matrix elements, but also allows the sampling of phase space according to these matrix elements and thereby the generation of weighted or unweighted events. These events can be saved on disk and thereafter read back in to PYTHIA for subsequent consideration [Bel00].

At the Les Houches 2001 workshop it was decided to develop a common standard, that could be used by all matrix-elements-based generators to feed information into any complete event generator [Boo01]. It is similar to, but in its details different from, the approach previously implemented in PYTHIA. Furthermore, it uses the same naming convention: all names in common blocks end with UP, short for User(-defined) Process. This produces some clashes. Therefore the old facility, existing up to and including PYTHIA 6.1, has been completely removed and replaced by the new one. The new code is still under development, and not all particulars have yet been implemented. In the description below we will emphasize current restrictions to the standard, as well as the solutions to aspects not specified by the standard.

In particular, even with the common block contents defined, it is not clear where they are to be filled, i.e. how the external supplier of parton-level events should synchronize with PYTHIA. The solution adopted here -- recommended in the standard -- is to introduce two subroutines, UPINIT and UPEVNT. The first is called by PYINIT at initialization to obtain information about the run itself, and the other called by PYEVNT each time a new event configuration is to be fed in. We begin by describing these two steps and their related common blocks, before proceeding with further details and examples. The description is cast in a PYTHIA-oriented language, but for the common block contents it closely matches the generator-neutral standard in [Boo01]. Restrictions to or extensions of the standard should be easily recognized, but in case you are vitally dependent on following the standard exactly, you should of course check [Boo01].

If you want to provide routines based on this standard, free to be used by a larger community, please inform torbjorn@thep.lu.se. The intention is to create a list of links to such routines, accessible from the standard PYTHIA webpage, if there is interest.