% This file contains a draft LaTeX2e version of the % PYTHIA 6.1 physics description and manual % Copyright Torbjorn Sjostrand 1998 % Last changed : 27 December 1998 % Formats are appropriate for output on A4 paper; % to change to US legal size look a few lines down from this. \documentclass[12pt]{article} %define page size: these two lines are for A4 paper \setlength{\textheight}{245mm} \setlength{\topmargin}{-5mm} %define page size: these two lines are for US legal size paper %to enable them, remove % at the beginning of the lines %\setlength{\textheight}{240mm} %\setlength{\topmargin}{10mm} %define page size: common for A4 and US legal \setlength{\headheight}{0mm} \setlength{\headsep}{0mm} \setlength{\footskip}{12mm} \setlength{\textwidth}{160mm} \setlength{\oddsidemargin}{0mm} \setlength{\evensidemargin}{0mm} %line spacing \renewcommand{\baselinestretch}{0.9} %define math alphabets for roman, boldface and teletype \newcommand{\mrm}[1]{\mathrm{#1}} \newcommand{\mbf}[1]{\mathbf{#1}} \newcommand{\mtt}[1]{\mathtt{#1}} \newcommand{\tsc}[1]{\textsc{#1}} \newcommand{\tbf}[1]{\textbf{#1}} \newcommand{\ttt}[1]{\texttt{#1}} %program names \newcommand{\Py}{\tsc{Pythia}} \newcommand{\Je}{\tsc{Jetset}} \newcommand{\PyJe}{\tsc{Pythia/Jetset}} \newcommand{\JePy}{\tsc{Jetset/Pythia}} %some frequent physics symbols \newcommand{\alphas}{\alpha_{\mathrm{s}}} \newcommand{\alphaem}{\alpha_{\mathrm{em}}} \newcommand{\ssintw}{\sin^2 \! \theta_W} \newcommand{\scostw}{\cos^2 \! \theta_W} \newcommand{\pT}{p_{\perp}} \newcommand{\pTmin}{p_{\perp\mathrm{min}}} \newcommand{\MSbar}{$\overline{\mrm{MS}}$} \newcommand{\br}[1]{\overline{#1}} %roman names for particles in math mode \renewcommand{\a}{\mathrm{a}} \renewcommand{\b}{\mathrm{b}} \renewcommand{\c}{\mathrm{c}} \renewcommand{\d}{\mathrm{d}} \newcommand{\e}{\mathrm{e}} \newcommand{\f}{\mathrm{f}} \newcommand{\g}{\mathrm{g}} \newcommand{\hrm}{\mathrm{h}} \newcommand{\lrm}{\mathrm{l}} \newcommand{\n}{\mathrm{n}} \newcommand{\p}{\mathrm{p}} \newcommand{\q}{\mathrm{q}} \newcommand{\s}{\mathrm{s}} \renewcommand{\t}{\mathrm{t}} \renewcommand{\u}{\mathrm{u}} \newcommand{\A}{\mathrm{A}} \newcommand{\B}{\mathrm{B}} \newcommand{\D}{\mathrm{D}} \newcommand{\F}{\mathrm{F}} \renewcommand{\H}{\mathrm{H}} \newcommand{\J}{\mathrm{J}} \newcommand{\K}{\mathrm{K}} \renewcommand{\L}{\mathrm{L}} \newcommand{\Q}{\mathrm{Q}} \newcommand{\R}{\mathrm{R}} \newcommand{\T}{\mathrm{T}} \newcommand{\W}{\mathrm{W}} \newcommand{\Z}{\mathrm{Z}} \newcommand{\bbar}{\overline{\mathrm{b}}} \newcommand{\cbar}{\overline{\mathrm{c}}} \newcommand{\dbar}{\overline{\mathrm{d}}} \newcommand{\fbar}{\overline{\mathrm{f}}} \newcommand{\pbar}{\overline{\mathrm{p}}} \newcommand{\qbar}{\overline{\mathrm{q}}} \newcommand{\sbar}{\overline{\mathrm{s}}} \newcommand{\tbar}{\overline{\mathrm{t}}} \newcommand{\ubar}{\overline{\mathrm{u}}} \newcommand{\Fbar}{\overline{\mathrm{F}}} \newcommand{\Qbar}{\overline{\mathrm{Q}}} %some useful abbreviations \newcommand{\Jpsi}{\mathrm{J}/\psi} \newcommand{\pomeron}{\mathrm{I}\!\mathrm{P}} \newcommand{\reggeon}{\mathrm{I}\!\mathrm{R}} \newcommand{\ee}{\e^+\e^-} \newcommand{\ep}{\e\p} \newcommand{\pp}{\p\p} \newcommand{\ppbar}{\p\pbar} \newcommand{\gammaZ}{\gamma^* / \Z^0} \newcommand{\mmin}{\mathrm{min}} \newcommand{\mmax}{\mathrm{max}} %new list environments to replace itemize and enumerate \newenvironment{Itemize}{\begin{list}{$\bullet$}% {\setlength{\topsep}{0.2mm}\setlength{\partopsep}{0.2mm}% \setlength{\itemsep}{0.2mm}\setlength{\parsep}{0.2mm}}}% {\end{list}} \newcounter{enumct} \newenvironment{Enumerate}{\begin{list}{\arabic{enumct}.}% {\usecounter{enumct}\setlength{\topsep}{0.2mm}% \setlength{\partopsep}{0.2mm}\setlength{\itemsep}{0.2mm}% \setlength{\parsep}{0.2mm}}}{\end{list}} %list environment suitable for manuals \newenvironment{entry}% {\begin{list}{}{\setlength{\topsep}{0mm} \setlength{\itemsep}{0mm} \setlength{\parskip}{0mm} \setlength{\parsep}{0mm} \setlength{\leftmargin}{20mm} \setlength{\rightmargin}{0mm} \setlength{\labelwidth}{18mm} \setlength{\labelsep}{2mm}}}% {\end{list}} \newenvironment{subentry}% {\begin{list}{}{\setlength{\topsep}{0mm} \setlength{\itemsep}{0mm} \setlength{\parskip}{0mm} \setlength{\parsep}{0mm} \setlength{\leftmargin}{10mm} \setlength{\rightmargin}{0mm} \setlength{\labelwidth}{18mm} \setlength{\labelsep}{2mm}}}% {\end{list}} \newcommand{\itemc}[1]{\item[\textbf{#1}\hfill]} \newcommand{\iteme}[1]{\item[\texttt{#1}\hfill]} \newcommand{\itemn}[1]{\item[{#1}\hfill]} %draw box around routine or common block name \setlength{\fboxrule}{1pt} \setlength{\fboxsep}{3mm} \newcommand{\drawbox}[1]{\vspace{\baselineskip}\noindent% \fbox{\texttt{#1}}\vspace{0.5\baselineskip}} \newcommand{\drawboxtwo}[2]{\vspace{\baselineskip}\noindent% \fbox{\begin{minipage}{150mm}\begin{tabbing}% {\texttt{#1}}\\{\texttt{#2}}% \end{tabbing}\end{minipage}}\vspace{0.5\baselineskip}} \newcommand{\drawboxthree}[3]{\vspace{\baselineskip}\noindent% \fbox{\begin{minipage}{150mm}\begin{tabbing}% {\texttt{#1}}\\{\texttt{#2}}\\{\texttt{#3}}% \end{tabbing}\end{minipage}}\vspace{0.5\baselineskip}} \newcommand{\drawboxfour}[4]{\vspace{\baselineskip}\noindent% \fbox{\begin{minipage}{150mm}\begin{tabbing}% {\texttt{#1}}\\{\texttt{#2}}\\{\texttt{#3}}\\{\texttt{#4}}% \end{tabbing}\end{minipage}}\vspace{0.5\baselineskip}} \newcommand{\boxsep}{\vspace{0.5\baselineskip}} %fraction of page devoted to figures and other floats \setcounter{topnumber}{1} \setcounter{bottomnumber}{1} \renewcommand{\textfraction}{0.1} \renewcommand{\topfraction}{0.9} \renewcommand{\bottomfraction}{0.9} \renewcommand{\floatpagefraction}{0.8} %one caption and figure/table, indented but spanning whole page \newlength{\captivewidth} \setlength{\captivewidth}{\textwidth} \addtolength{\captivewidth}{-10mm} \newcommand{\captive}[1]{\rule{5mm}{0mm}% \begin{minipage}{\captivewidth}% \caption[small]{#1}\end{minipage}} %minimal separation between rows in table \newlength{\tablinsep} \setlength{\tablinsep}{0.73\baselineskip} %size of column (half page width + blank in middle) \newlength{\halfpagewid} \setlength{\halfpagewid}{0.5\textwidth} \addtolength{\halfpagewid}{-10mm} %set level for table of contents \setcounter{tocdepth}{2} \begin{document} %set sloppy attitude to line breaks \sloppy \pagestyle{empty} \begin{flushright} LU TP 99--??\\ December 1998\\ hep-ph/yymmnnn \end{flushright} \vspace{\fill} \begin{center} \tbf{{\Huge P}{\LARGE YTHIA}~~{\Huge 6.1} \\[5mm] \tbf{{\LARGE Physics and Manual}} \\[10mm] \tbf{{\Large Torbj\"orn Sj\"ostrand}} \\[3mm] {\large Department of Theoretical Physics,} \\[1mm] {\large University of Lund, S\"olvegatan 14A,} \\[1mm] {\large S-223 62 \tsc{Lund}, \tsc{Sweden}}\\ \vspace{\fill} \fbox{\hspace{1mm}\rule{0mm}{7mm} \begin{minipage}[t]{150mm} \begin{tabbing} {\tt ~~~~~~~~~~~~*......*~~~~~~~~~~~~}\\[-1.1mm] {\tt ~~~~~~~*:::!!:::::::::::*~~~~~~~}\\[-1.1mm] {\tt ~~~~*::::::!!::::::::::::::*~~~~}\\[-1.1mm] {\tt ~~*::::::::!!::::::::::::::::*~~}\\[-1.1mm] {\tt ~*:::::::::!!:::::::::::::::::*~}\\[-1.1mm] {\tt ~*:::::::::!!:::::::::::::::::*~}\\[-1.1mm] {\tt ~~*::::::::!!::::::::::::::::*!~}\\[-1.1mm] {\tt ~~~~*::::::!!::::::::::::::*~!!~}\\[-1.1mm] {\tt ~~~~!!~*:::!!:::::::::::*~~~~!!~}\\[-1.1mm] {\tt ~~~~!!~~~~~!*~-><-~*~~~~~~~~~!!~}\\[-1.1mm] {\tt ~~~~!!~~~~~!!~~~~~~~~~~~~~~~~!!~}\\[-1.1mm] {\tt ~~~~!!~~~~~!!~~~~~~~~~~~~~~~~!!~}\\[-1.1mm] {\tt ~~~~!!~~~~~~~~~~~~~~~~~~~~~~~!!~}\\[-1.1mm] {\tt ~~~~!!~~~~~~~~ep~~~~~~~~~~~~~!!~}\\[-1.1mm] {\tt ~~~~!!~~~~~~~~~~~~~~~~~~~~~~~!!~}\\[-1.1mm] {\tt ~~~~!!~~~~~~~~~~~~~~~~~pp~~~~!!~}\\[-1.1mm] {\tt ~~~~!!~~~e+e-~~~~~~~~~~~~~~~~!!~}\\[-1.1mm] {\tt ~~~~!!~~~~~~~~~~~~~~~~~~~~~~~!!~}\\[-1.1mm] {\tt ~~~~!!~~~~~~~~~~~~~~~~~~~~~~~~~~}\\[-1.1mm] \end{tabbing} \end{minipage} \rule[-6mm]{0mm}{6mm}\hspace{3mm}} \vspace{\fill} \fbox{\begin{minipage}[t]{126mm}\begin{center} {\large All references should be to the latest published version:} \\[1mm] {\large T. Sj\"ostrand, Computer Physics Commun. {\bf 82} (1994) 74.} \end{center}\end{minipage}} \vspace{\fill} \copyright{} Copyright Torbj\"orn Sj\"ostrand and Lund University, Lund 1998 \end{center} \clearpage \section*{Preface} The {\Py} and {\Je} programs are frequently used for event generation in high-energy physics. The emphasis is on multiparticle production in collisions between elementary particles. This in particular means hard interactions in $\ee$, $\pp$ and $\ep$ colliders, although also other applications are envisaged. The programs are intended to generate complete events, in as much detail as experimentally observable ones, within the bounds of our current understanding of the underlying physics. Many of the components of the programs represent original research, in the sense that models have been developed and implemented for a number of aspects not covered by standard theory. Although originally conceived separately, the {\Py} and {\Je} programs today are so often used together that it makes sense to merge them. Therefore {\Py}~5.7 and {\Je}~7.4 were the last versions to appear individually; as of {\Py}~6.1 all the code is collected under the {\Py} heading. Both programs have a long history, and several manuals have come out. The most recent one is \\[1mm] T. Sj\"ostrand, Computer Physics Commun. {\bf 82} (1994) 74, \\[1mm] so please use this for all official references. Additionally remember to cite the original literature on the physics topics of particular relevance for your studies. (There is no reason to omit references to good physics papers simply because some of their contents have also been made available as program code.) Event generators often have a reputation for being `black boxes'; if nothing else, this report should provide you with a glimpse of what goes on inside the programs. Some such understanding may be of special interest for new users, who have no background in the field. An attempt has been made to structure the report sufficiently well that many of the sections can be read independently of each other, so you can pick the sections that interest you. I have tried to keep together the physics and the manual sections on specific topics, where practicable, which represents a change of policy compared with previous manual versions. Any feedback on this and other aspects is welcome. A large number of persons should be thanked for their contributions. Hans-Uno Bengtsson is the originator of the {\Py} program, and for many years we worked in parallel on its further development. Mats Bengtsson is the main author of the final-state parton-shower algorithm. Bo Andersson and G\"osta Gustafson are the originators of the Lund model, and strongly influenced the early development of the programs. Steve Mrenna has written the supersymmetric process machinery. Leif L\"onnblad has contributed the updated Bose--Einstein routine and Patrik Ed\'en an improved popcorn scenario for baryon production. Further comments on the programs have been obtained from users too numerous to be mentioned here, but who are all gratefully acknowledged. To write programs of this size and complexity would be impossible without a strong user feedback. The moral responsibility for any remaining errors clearly rests with me. However, kindly note that this is a `University World' product, distributed `as is', free of charge, without any binding guarantees. And always remember that the programs do not represent a dead collection of established truths, but rather one of many possible approaches to the problem of multiparticle production in high-energy physics, at the frontline of current research. Be critical! \cleardoublepage \tableofcontents \cleardoublepage \pagestyle{plain} \setcounter{page}{1} \section{Introduction} Multiparticle production is the most characteristic feature of current high-energy physics. Today, observed particle multiplicities are typically between ten and a hundred, and with future machines this range will be extended upwards. The bulk of the multiplicity is found in jets, i.e. in bunches of hadrons (or decay products of hadrons) produced by the hadronization of quarks and gluons. \subsubsection*{The Complexity of High-Energy Processes} To first approximation, all processes have a simple structure at the level of interactions between the fundamental objects of nature, i.e. quarks, leptons and gauge bosons. For instance, a lot can be understood about the structure of hadronic events at LEP just from the `skeleton' process $\ee \to \Z^0 \to \q \qbar$. Corrections to this picture can be subdivided, arbitrarily but conveniently, into three main classes. Firstly, there are bremsstrahlung-type modifications, i.e. the emission of additional final-state particles by branchings such as $\e \to \e \gamma$ or $\q \to \q \g$. Because of the largeness of the strong coupling constant $\alphas$, and because of the presence of the triple gluon vertex, QCD emission off quarks and gluons is especially prolific. We therefore speak about `parton showers', wherein a single initial parton may give rise to a whole bunch of partons in the final state. Also photon emission may give sizeable effects in $\ee$ and $\ep$ processes. The bulk of the bremsstrahlung corrections are universal, i.e. do not depend on the details of the process studied, but only on one or a few key numbers, such as the momentum transfer scale of the process. Such universal corrections may be included to arbitrarily high orders, using a probabilistic language. Alternatively, exact calculations of bremsstrahlung corrections may be carried out order by order in perturbation theory, but rapidly the calculations then become prohibitively complicated and the answers correspondingly lengthy. Secondly, we have `true' higher-order corrections, which involve a combination of loop graphs and the soft parts of the bremsstrahlung graphs above, a combination needed to cancel some divergences. In a complete description it is therefore not possible to consider bremsstrahlung separately, as assumed here. The necessary perturbative calculations are usually very difficult; only rarely have results been presented that include more than one non-`trivial' order, i.e. more than one loop. As above, answers are usually very lengthy, but some results are sufficiently simple to be generally known and used, such as the running of $\alphas$, or the correction factor $1 + \alphas/\pi + \cdots$ in the partial widths of $\Z^0 \to \q \qbar$ decay channels. For high-precision studies it is imperative to take into account the results of loop calculations, but usually effects are minor for the qualitative aspects of high-energy processes. Thirdly, quarks and gluons are confined. In the two points above, we have used a perturbative language to describe the short-distance interactions of quarks, leptons and gauge bosons. For leptons and colourless bosons this language is sufficient. However, for quarks and gluons it must be complemented with a picture for the hadronization process (which can be subdivided into fragmentation and decays), wherein the coloured partons are transformed into jets of colourless hadrons, photons and leptons. This process is still not yet understood from first principles, but has to be based on models. In one sense, hadronization effects are overwhelmingly large, since this is where the bulk of the multiplicity comes from. In another sense, the overall energy flow of a high-energy event is mainly determined by the perturbative processes, with only a minor additional smearing caused by the hadronization step. One may therefore pick different levels of ambition, but in general detailed studies require a detailed modelling of the hadronization process. The simple structure that we started out with has now become considerably more complex --- instead of maybe two final-state partons we have a hundred final particles. The original physics is not gone, but the skeleton process has been dressed up and is no longer directly visible. A direct comparison between theory and experiment is therefore complicated at best, and impossible at worst. \subsubsection*{Event Generators} It is here that event generators come to the rescue. In an event generator, the objective strived for is to use computers to generate events as detailed as could be observed by a perfect detector. This is not done in one step, but rather by `factorizing' the full problem into a number of components, each of which can be handled reasonably accurately. Basically, this means that the hard process is used as input to generate bremsstrahlung corrections, and that the result of this exercise is thereafter left to hadronize. This sounds a bit easier than it really is --- else this report would be a lot thinner. However, the basic idea is there: if the full problem is too complicated to be solved in one go, try to subdivide it into smaller tasks of manageable proportions. In the actual generation procedure, most steps therefore involve the branching of one object into two, or at least into a very small number, each of which being free to branch in its turn. A lot of bookkeeping is involved, but much is of a repetitive nature, and can therefore be left for the computer to handle. As the name indicates, the output of an event generator should be in the form of `events', with the same average behaviour and the same fluctuations as real data. In the data, fluctuations arise from the quantum mechanics of the underlying theory. In generators, Monte Carlo techniques are used to select all relevant variables according to the desired probability distributions, and thereby ensure randomness in the final events. Clearly some loss of information is entailed: quantum mechanics is based on amplitudes, not probabilities. However, only very rarely do (known) interference phenomena appear that cannot be cast in a probabilistic language. This is therefore not a more restraining approximation than many others. Once there, an event generator can be used in many different ways. The five main applications are probably the following: \begin{Itemize} \item To give physicists a feeling for the kind of events one may expect/hope to find, and at what rates. \item As a help in the planning of a new detector, so that detector performance is optimized, within other constraints, for the study of interesting physics scenarios. \item As a tool for devising the analysis strategies that should be used on real data, so that signal-to-background conditions are optimized. \item As a method for estimating detector acceptance corrections that have to be applied to raw data, in order to extract the `true' physics signal. \item As a convenient framework within which to interpret the observed phenomena in terms of a more fundamental underlying theory (usually the Standard Model). \end{Itemize} Where does a generator fit into the overall analysis chain of an experiment? In `real life', the machine produces interactions. These events are observed by detectors, and the interesting ones are written to tape by the data acquisition system. Afterwards the events may be reconstructed, i.e. the electronics signals (from wire chambers, calorimeters, and all the rest) may be translated into a deduced setup of charged tracks or neutral energy depositions, in the best of worlds with full knowledge of momenta and particle species. Based on this cleaned-up information, one may proceed with the physics analysis. In the Monte Carlo world, the r\^ole of the machine, namely to produce events, is taken by the event generators described in this report. The behaviour of the detectors --- how particles produced by the event generator traverse the detector, spiral in magnetic fields, shower in calorimeters, or sneak out through cracks, etc. --- is simulated in programs such as \tsc{Geant} \cite{Bru89}. Traditionally, this latter activity is called event simulation, which is somewhat unfortunate since the same words could equally well be applied to what, here, we call event generation. A more appropriate term is detector simulation. Ideally, the output of this simulation has exactly the same format as the real data recorded by the detector, and can therefore be put through the same event reconstruction and physics analysis chain, except that here we know what the `right answer' should be, and so can see how well we are doing. Since the full chain of detector simulation and event reconstruction is very time-consuming, one often does `quick and dirty' studies in which these steps are skipped entirely, or at least replaced by very simplified procedures which only take into account the geometric acceptance of the detector and other trivial effects. One may then use the output of the event generator directly in the physics studies. There are still many holes in our understanding of the full event structure, despite an impressive amount of work and detailed calculations. To put together a generator therefore involved making a choice on what to include, and how to include it. At best, the spread between generators can be used to give some impression of the uncertainties involved. A multitude of approximations will be discussed in the main part of this report, but already here is should be noted that many major approximations are related to the almost complete neglect of the second point above, i.e. of the non-`trivial' higher-order effects. It can therefore only be hoped that the `trivial' higher order parts give the bulk of the experimental behaviour. By and large, this seems to be the case; for $\ee$ annihilation it even turns out to be a very good approximation. The necessity to make compromises has one major implication: to write a good event generator is an art, not an exact science. It is therefore essential not to blindly trust the results of any single event generator, but always to make several cross-checks. In addition, with computer programs of tens of thousands of lines, the question is not whether bugs exist, but how many there are, and how critical their positions. Further, an event generator cannot be thought of as all-powerful, or able to give intelligent answers to ill-posed questions; sound judgement and some understanding of a generator are necessary prerequisites for successful use. In spite of these limitations, the event generator approach is the most powerful tool at our disposal if we wish to gain a detailed and realistic understanding of physics at current or future high-energy colliders. \subsubsection*{The Origins of the JETSET and PYTHIA Programs} Over the years, many event generators have appeared. Surveys of generators for $\ee$ physics in general and LEP in particular may be found in \cite{Kle89,Sjo89}, for high-energy hadron--hadron ($\pp$) physics in \cite{Ans90,Sjo92,Kno93}, and for $\ep$ physics in \cite{HER92}. We refer the reader to those for additional details and references. In this particular report, the two closely connected programs {\Je} and {\Py}, now merged under the {\Py} label, will be described. {\Je} has its roots in the efforts of the Lund group to understand the hadronization process, starting in the late seventies \cite{And83}. The so-called string fragmentation model was developed as an explicit and detailed framework, within which the long-range confinement forces are allowed to distribute the energies and flavours of a parton configuration among a collection of primary hadrons, which subsequently may decay further. This model, known as the Lund string model, or `Lund' for short, contained a number of specific predictions, which were confirmed by data from PETRA and PEP, whence the model gained a widespread acceptance. The Lund string model is still today the most elaborate and widely used fragmentation model at our disposal. It remains at the heart of the {\JePy} programs. In order to predict the shape of events at PETRA/PEP, and to study the fragmentation process in detail, it was necessary to start out from the partonic configurations that were to fragment. The generation of complete $\ee$ hadronic events was therefore added, originally based on simple $\gamma$ exchange and first-order QCD matrix elements, later extended to full $\gammaZ$ exchange with first-order initial-state QED radiation and second-order QCD matrix elements. A number of utility routines were also provided early on, for everything from event listing to jet finding. By the mid-eighties it was clear that the matrix-element approach had reached the limit of its usefulness, in the sense that it could not fully describe the multijet topologies of the data. (Later on, the use of optimized perturbation theory was to lead to a resurgence of the matrix-element approach, but only for specific applications.) Therefore a parton-shower description was developed \cite{Ben87a} as an alternative to the matrix-element one. The combination of parton showers and string fragmentation has been very successful, and forms the main approach to the description of hadronic $\Z^0$ events. In recent years, {\Je} has been a fairly stable product, covering the four main areas of fragmentation, final-state parton showers, $\ee$ event generation and general utilities. The successes of string fragmentation in $\ee$ made it interesting to try to extend this framework to other processes, and explore possible physics consequences. Therefore a number of other programs were written, which combined a process-specific description of the hard interactions with the general fragmentation framework of {\Je}. The {\Py} program evolved out of early studies on fixed-target proton--proton processes, addressed mainly at issues related to string drawing. With time, the interest shifted towards higher energies, first to the SPS $\ppbar$ collider, and later to SSC and LHC, in the context of a number of workshops in the USA and Europe. Parton showers were added, for final-state radiation by making use of the {\Je} routine, for initial-state one by the development of the concept of `backwards evolution', specifically for {\Py} \cite{Sjo85}. Also a framework was developed for minimum-bias and underlying events \cite{Sjo87a}. Another main change was the introduction of an increasing number of hard processes, within the Standard Model and beyond. A special emphasis was put on the search for the Standard Model Higgs, in different mass ranges and in different channels, with due respect to possible background processes. The bulk of the machinery developed for hard processes actually depended little on the choice of initial state, as long as the appropriate parton distributions were there for the incoming partons and particles. It therefore made sense to extend the program from being only a $\pp$ generator to working also for $\ee$ and $\ep$. This process was only completed in 1991, again spurred on by physics workshop activities. Currently {\Py} should therefore work equally well for a selection of different possible incoming beam particles. The tasks of including new processes, and of improving the simulation of already present ones, are never-ending. Work therefore continues apace. While {\Je} was independent of {\Py} until 1996, their ties had grown much stronger over the years, and the border-line between the two programs had become more and more artificial. It was therefore decided to merge the two, starting from {\Py}~6.1. The different origins in part still are reflected in this manual, but the strive is towards a seamless merger. \subsubsection*{About this Report} As we see, {\Je} and {\Py} started out as very ideologically motivated programs, developed to study specific physics questions in enough detail that explicit predictions could be made for experimental quantities. As it was recognized that experimental imperfections could distort the basic predictions, the programs were made available for general use by experimentalists. It thus became feasible to explore the models in more detail than would otherwise have been possible. As time went by, the emphasis came to shift somewhat, away from the original strong coupling to a specific fragmentation model, towards a description of high-energy multiparticle production processes in general. Correspondingly, the use expanded from being one of just comparing data with specific model predictions, to one of extensive use for the understanding of detector performance, for the derivation of acceptance correction factors, for the prediction of physics at future high-energy accelerators, and for the design of related detectors. While the ideology may be less apparent, it is still there, however. This is not something unique to the programs discussed here, but inherent in any event generator, or at least any generator that attempts to go beyond the simple parton level skeleton description of a hard process. Do not accept the myth that everything available in Monte Carlo form represents ages-old common knowledge, tested and true. Ideology is present by commissions or omissions in any number of details. Programs like {\Py} and {\Je} represent a major amount of original physics research, often on complicated topics where no simple answers are available. As a (potential) program user you must be aware of this, so that you can form your own opinion, not just about what to trust and what not to trust, but also how much to trust a given prediction, i.e. how uncertain it is likely to be. {\Je} and {\Py} are particularly well endowed in this respect, since a number of publications exist where most of the relevant physics is explained in considerable detail. In fact, the problem may rather be the opposite, to find the relevant information among all the possible places. One main objective of the current report is therefore to collect much of this information in one single place. Not all the material found in specialized papers is reproduced, by a wide margin, but at least enough should be found here to understand the general picture and to know where to go for details. The current report is therefore intended to replace the previous round of published physics descriptions and program manuals \cite{Sjo86,Sjo87,Ben87,Sjo94}. Until a new published version exists, make all references to the most recent published one in \cite{Sjo94}. Further specification could include a statement of the type `We use {\Py} version X.x'. (If you are a {\LaTeX} fan, you may want to know that the program name in this report has been generated by the command \verb+\textsc{Pythia}+.) Kindly do not refer to {\Py} as `unpublished', `private communication' or `in preparation': such phrases are only creating unnecessary confusion. In addition, remember that many of the individual physics components are documented in separate publications. If some of these contain ideas that are useful to you, there is every reason to cite them. A reasonable selection would vary as a function of the physics you are studying. The criterion for which to pick should be simple: imagine that a Monte Carlo implementation had not been available. Would you then have cited a given paper on the grounds of its physics contents alone? If so, do not punish the extra effort of turning these ideas into publicly available software. (Monte Carlo manuals are good for nothing in the eyes of many theorists, so often only the acceptance of `mainstream' publications counts.) Here follows a list of some main areas where the $\PyJe$ programs contain original research: \begin{Itemize} \item The string fragmentation model \cite{And83}. \item The string effect \cite{And80}. \item Baryon production (diquark/popcorn) \cite{And82,And85}. \item Fragmentation of multiparton systems \cite{Sjo84}. \item Fragmentation effects on $\alphas$ determinations \cite{Sjo84a}. \item Initial state parton showers \cite{Sjo85}. \item Final state parton showers \cite{Ben87a}. \item Photon radiation from quarks \cite{Sjo92c} \item Deep inelastic scattering \cite{And81a,Ben88}. \item Photoproduction \cite{Sch93a} and $\gamma\gamma$ physics \cite{Sch94a}. \item Parton distributions of the photon \cite{Sch95}. \item Colour flow in hard scatterings \cite{Ben84}. \item Elastic and diffractive cross sections \cite{Sch94}. \item Minijets (multiple parton--parton interactions) \cite{Sjo87a}. \item Rapidity gaps \cite{Dok92}. \item Jet clustering in $k_{\perp}$ \cite{Sjo83}. \end{Itemize} In addition to a physics survey, the current report also contains a complete manual for the two programs. Such manuals have always been updated and distributed jointly with the programs. To a first approximation, we therefore do not have much new to offer here. However, an attempt has been made to group the material more logically according to physics topics than in previous distributions, to tie it closer to the physics description, and to improve the layout and therefore the readability. Any feedback is welcome. A word of warning may be in place. The program description is fairly lengthy, and certainly could not be absorbed in one sitting. This is not even necessary, since all switches and parameters are provided with sensible default values, based on our best understanding (of the physics, and of what you expect to happen if you do not specify any options). As a new user, you can therefore disregard all the fancy options, and just run the program with a minimum ado. Later on, as you gain experience, the options that seem useful can be tried out. No single user is ever likely to find need for more than a fraction of the total number of possibilities available, yet many of them have been added to meet specific user requests. In some instances, not even this report will provide you with all the information you desire. You may wish to find out about recent versions of the program, know about related software, pick up a few sample main programs to get going, or get hold of related physics papers. Some such material can be found if you link to my {\Py} webpage:\\ \ttt{http://www.thep.lu.se/~torbjorn/Pythia.html}\\ and study the contents there. \subsubsection*{Disclaimer} At all times it should be remembered that this is not a commercial product, developed and supported by professionals. Instead it is a `University World' product, developed by a very few physicists (mainly the current author) originally for their own needs, and supplied to other physicists on an `as-is' basis, free of charge. No guarantees are therefore given for the proper functioning of the programs, nor for the validity of physics results. In the end, it is always up to you to decide for yourself whether to trust a given result or not. Usually this requires comparison either with analytical results or with results of other programs, or with both. Even this is not necessarily foolproof: for instance, if an error is made in the calculation of a matrix element for a given process, this error will be propagated both into the analytical results based on the original calculation and into all the event generators which subsequently make use of the published formulae. In the end, there is no substitute for a sound physics judgement. This does not mean that you are all on your own, with a program nobody feels responsible for. Attempts are made to check processes as carefully as possible, to write programs that do not invite unnecessary errors, and to provide a detailed and accurate documentation. All of this while maintaining the full power and flexibility, of course, since the physics must always take precedence in any conflict of interests. If nevertheless any errors or unclarities are found, please do communicate them to me, e.g. on phone +46 -- 46 -- 222 48 16 or e-mail torbjorn@thep.lu.se. Every attempt will be made to solve problems as soon as is reasonably possible, given that this support is by one person alone, who also has other responsibilities. \subsubsection*{Appendix: The Historical Pythia} While the origin and connotations of the `{\Je}' program name should be commonly known, the `{\Py}' label may need some explanation. The myth tells how Apollon, the God of Wisdom, killed the powerful dragon-like monster Python, close to the village of Delphi in Greece. To commemorate this victory, Apollon founded the Pythic Oracle in Delphi, on the slopes of Mount Parnassos. Here men could come to learn the will of the Gods and the course of the future. The oracle plays an important r\^ole in many of the other Greek myths, such as those of Heracles and of King Oedipus. Questions were to be put to the Pythia, the `Priestess' or `Prophetess' of the Oracle. In fact, she was a local woman, usually a young maiden, of no particular religious schooling. Seated on a tripod, she inhaled the obnoxious vapours that seeped up through a crevice in the ground. This brought her to a trance-like state, in which she would scream seemingly random words and sounds. It was the task of the professional priests in Delphi to record those utterings and edit them into the official Oracle prophecies, which often took the form of poems in perfect hexameter. In fact, even these edited replies were often less than easy to interpret. The Pythic oracle acquired a reputation for ambiguous answers. The Oracle existed already at the beginning of the historical era in Greece, and was universally recognized as the foremost religious seat. Individuals and city states came to consult, on everything from cures for childlessness to matters of war. Lavish gifts allowed the temple area to be built and decorated. Many states supplied their own treasury halls, where especially beautiful gifts were on display. Sideshows included the Omphalos, a stone reputedly marking the centre of the Earth, and the Pythic games, second only to the Olympic ones in importance. Strife inside Greece eventually led to a decline in the power of the Oracle. A serious blow was dealt when the Oracle of Zeus Ammon (see below) declared Alexander the Great to be the son of Zeus. The Pythic Oracle lived on, however, and was only closed by a Roman Imperial decree in 390 \tsc{ad}, at a time when Christianity was ruthlessly destroying any religious opposition. Pythia then had been at the service of man and Gods for a millenium and a half. The r\^ole of the Pythic Oracle replies on the course of history is nowhere better described than in `The Histories' by Herodotus \cite{HerBC}, the classical and captivating description of the Ancient World at the time of the Great War between Greeks and Persians. Especially famous is the episode with King Croisus of Lydia. Contemplating a war against the upstart Persian Empire, he resolves to ask an oracle what the outcome of a potential battle would be. However, to have some guarantee for the veracity of any prophecy, he decides to send embassies to all the renowned oracles of the known World. The messengers are instructed to inquire the various divinities, on the hundredth day after their departure, what King Croisus is doing at that very moment. From the Pythia the messengers bring back the reply \begin{em}\begin{verse} I know the number of grains of sand as well as the expanse of the sea, \\ And I comprehend the dumb and hear him who does not speak, \\ There came to my mind the smell of the hard-shelled turtle, \\ Boiled in copper together with the lamb, \\ With copper below and copper above. \end{verse}\end{em} The veracity of the Pythia is thus established by the crafty ruler, who had waited until the appointed day, slaughtered a turtle and a lamb, and boiled them together in a copper cauldron with a copper lid. Also the Oracle of Zeus Ammon in the Libyan desert is able to give a correct reply (lost to posterity), while all others fail. King Croisus now sends a second embassy to Delphi, inquiring after the outcome of a battle against the Persians. The Pythia answers \begin{em}\begin{verse} If Croisus passes over the Halys he will dissolve a great Empire. \end{verse}\end{em} Taking this to mean he would win, the King collects his army and crosses the border river, only to suffer a crushing defeat and see his Kingdom conquered. When the victorious King Cyrus allows Croisus to send an embassy to upbraid the Oracle, the God Apollon answers through his Prophetess that he has correctly predicted the destruction of a great empire --- Croisus' own --- and that he cannot be held responsible if people choose to interpret the Oracle answers to their own liking. The history of the {\Py} program is neither as long nor as dignified as that of its eponym. However, some points of contact exist. You must be very careful when you formulate the questions: any ambiguities will corrupt the reply you get. And you must be even more careful not to misinterpret the answers; in particular not to pick the interpretation that suits you before considering the alternatives. Finally, even a perfect God has servants that are only human: a priest might mishear the screams of the Pythia and therefore produce an erroneous oracle reply; the current author might unwittingly let a bug free in the program {\Py}. \clearpage \section{Physics Overview} In this section we will try to give an overview of the main physics features of {\Py}, and also to introduce some terminology. The details will be discussed in subsequent sections. For the description of a typical high-energy event, an event generator should contain a simulation of several physics aspects. If we try to follow the evolution of an event in some semblance of a time order, one may arrange these aspects as follows: \begin{Enumerate} \item Initially two beam particles are coming in towards each other. Normally each particle is characterized by a set of parton distribution functions, which defines the partonic substructure in terms of flavour composition and energy sharing. \item One shower initiator parton from each beam starts off a sequence of branchings, such as $\q \to \q \g$, which build up an initial-state shower. \item One incoming parton from each of the two showers enters the hard process, where then a number of outgoing partons are produced, usually two. It is the nature of this process that determines the main characteristics of the event. \item Also the outgoing partons may branch, to build up final-state showers. \item When a shower initiator is taken out of a beam particle, a beam remnant is left behind. This remnant may have an internal structure, and a net colour charge that relates it to the rest of the final state. \item The QCD confinement mechanism ensures that the outgoing quarks and gluons are not observable, but instead fragment to colour neutral hadrons. \item Many of the produced hadrons are unstable and decay further. \end{Enumerate} Conventionally, only quarks and gluons are counted as partons, while leptons and photons are not. If pushed {\it ad absurdum} this may lead to some unwieldy terminology. We will therefore, where it does not matter, speak of an electron or a photon in the `partonic' substructure of an electron, lump branchings $\e \to \e \gamma$ together with other `parton shower' branchings such as $\q \to \q \g$, and so on. With this notation, the division into the above seven points applies equally well to an interaction between two leptons, between a lepton and a hadron, and between two hadrons. In the following subsections, we will survey the above seven aspects, not in the same order as given here, but rather in the order in which they appear in the program execution, i.e. starting with the hard process. \subsection{Hard Processes and Parton Distributions} In {\Je}, only two hard processes are available. The first and main one is $\ee \to \gammaZ \to \q \qbar$. Here the `$*$' of $\gamma^*$ is used to denote that the photon must be off the mass shell. The distinction is of some importance, since a photon on the mass shell cannot decay. Of course also the $\Z^0$ can be off the mass shell, but here the distinction is less relevant (strictly speaking, a $\Z^0$ is always off the mass shell). In the following we may not always use `$*$' consistently, but the rule of thumb is to use a `$*$' only when a process is not kinematically possible for a particle of nominal mass. The quark $\q$ in the final state of $\ee \to \gammaZ \to \q \qbar$ may be $\u$, $\d$, $\s$, $\c$, $\b$ or $\t$; the flavour in each event is picked at random, according to the relative couplings, evaluated at the hadronic c.m. energy. Also the angular distribution of the final $\q \qbar$ pair is included. No parton-distribution functions are needed. The other {\Je} process is a routine to generate $\g \g \g$ and $\gamma \g \g$ final states, as expected in onium 1$^{--}$ decays such as $\Upsilon$. Given the current limits on the top mass, toponium will decay weakly much too fast for these processes to be of any interest, so therefore no new applications are expected. {\Py} contains a much richer selection, with close to a hundred different hard processes. These may be classified in many different ways. One is according to the number of final-state objects: we speak of `$2 \to 1$' processes, `$2 \to 2$' ones, `$2 \to 3$' ones, etc. This aspect is very relevant from a programming point of view: the more particles in the final state, the more complicated the phase space and therefore the whole generation procedure. In fact, {\Py} is optimized for $2 \to 1$ and $2 \to 2$ processes. There is currently no generic treatment of processes with three or more particles in the final state, but rather a few different machineries, each tailored to the pole structure of a specific class of graphs. This may be seen as a major limitation, and indeed is so at times. However, often one can come quite far with only one or two particles in the final state, since showers will add the required extra activity. The classification may also be misleading at times, since an $s$-channel resonance is considered as a single particle, even if it is assumed always to decay into two final-state particles. Thus the process $\ee \to \W^+ \W^- \to \q_1 \qbar'_1 \, \q_2 \qbar'_2$ is classified as $2 \to 2$, although the decay treatment of the $\W$ pair includes the full $2 \to 4$ matrix elements. Another classification is according to the physics scenario. This will be the main theme of section \ref{s:pytproc}. The following major groups may be distinguished: \begin{Itemize} \item Hard QCD processes, e.g. $\q \g \to \q \g$. \item Soft QCD processes, such as diffractive and elastic scattering, and minimum-bias events. \item Heavy-flavour production, e.g. $\g \g \to \t \tbar$. \item Prompt-photon production, e.g. $\q \g \to \q \gamma$. \item Photon-induced processes, e.g. $\gamma \g \to \q \qbar$. \item Deep inelastic scattering, e.g. $\q \ell \to \q \ell$. \item $\W / \Z$ production, such as the $\ee \to \gammaZ$ already found in {\Je}, or $\q \qbar \to \W^+ \W^-$. \item Standard model Higgs production, where the Higgs is reasonably light and narrow, and can therefore still be considered as a resonance. \item Gauge boson scattering processes, such as $\W \W \to \W \W$, when the Standard Model Higgs is so heavy and broad that resonant and non-resonant contributions have to be considered together. \item Non-standard Higgs particle production, within the framework of a two-Higgs-doublet scenario with three neutral and two charged Higgs states. \item Production of new gauge bosons, such as a $\Z'$. \item Production of fourth-generation fermions. \item Leptoquark production. \item Deviations from Standard Model processes, e.g. due to contact interactions or a strongly interacting gauge boson sector. These scenarios do not always appear as separate processes, but may just be options to some of the processes above. \end{Itemize} This is by no means a survey of all interesting physics. Most notable is the absence of supersymmetric particle production and decay, but many other examples could be found. Also, within the scenarios studied, not all contributing graphs have always been included, but only the more important and/or more interesting ones. In many cases, various approximations are involved in the matrix elements coded. The cross section for a given process $ij \to k$ is given by \begin{equation} \sigma_{ij \to k} = \int \d x_1 \int \d x_2 \, f^1_i(x_1) \, f^2_j(x_2) \, \hat{\sigma}_{ij \to k} ~. \end{equation} Here $\hat{\sigma}$ is the cross section for the hard partonic process, as codified in the matrix elements for each specific process. For processes with many particles in the final state it would be replaced by an integral over the allowed final-state phase space. The $f^a_i(x)$ are the parton-distribution functions, which describe the probability to find a parton $i$ inside beam particle $a$, with parton $i$ carrying a fraction $x$ of the total $a$ momentum. Actually, parton distributions also depend on some momentum scale $Q^2$ that characterizes the hard process. Parton distributions are most familiar for hadrons, such as the proton. Hadrons are inherently composite objects, made up of quarks and gluons. Since we do not understand QCD, a derivation from first principles of hadron parton distributions does not yet exist, although some progress is being made in lattice QCD studies. It is therefore necessary to rely on parametrizations, where experimental data are used in conjunction with the evolution equations for the $Q^2$ dependence, to pin down the parton distributions. Several different groups have therefore produced their own fits, based on slightly different sets of data, and with some variation in the theoretical assumptions. Also for fundamental particles, such as the electron, is it convenient to introduce parton distributions. The function $f^{\e}_{\e}(x)$ thus parametrizes the probability that the electron that takes part in the hard process retains a fraction $x$ of the original energy, the rest being radiated (into photons) in the initial state. Of course, such radiation could equally well be made part of the hard interaction, but the parton-distribution approach usually is much more convenient. If need be, a description with fundamental electrons is recovered for the choice $f_{\e}^{\e}(x, Q^2)=\delta(x-1)$. Note that, contrary to the proton case, electron parton distributions are calculable from first principles, and reduce to the $\delta$ function above for $Q^2 \to 0$. The electron may also contain photons, and the photon may in its turn contain quarks and gluons. The internal structure of the photon is a bit of a problem, since the photon contains a point-like part, which is perturbatively calculable, and a vector-meson dominance part, which is not. Normally, the photon parton distributions are therefore parametrized, just as the hadron ones. Since the electron ultimately contains quarks and gluons, hard QCD processes like $\q \g \to \q \g$ therefore not only appear in $\pp$ collisions, but also in $\ep$ ones (`resolved photoproduction') and in $\ee$ ones (`doubly resolved 2$\gamma$ events'). The parton distribution function approach here makes it much easier to reuse one and the same hard process in different contexts. There is also another kind of possible generalization. The two processes $\q \qbar \to \gammaZ$, studied in hadron colliders, and $\ee \to \gammaZ$, studied in $\ee$ colliders, are really special cases of a common process, $\f \fbar \to \gammaZ$, where $\f$ denotes a fundamental fermion, i.e. a quark, lepton or neutrino. The whole structure is therefore only coded once, and then slightly different couplings and colour prefactors are used, depending on the initial state considered. Usually the interesting cross section is a sum over several different initial states, e.g. $\u \ubar \to \gammaZ$ and $\d \dbar \to \gammaZ$ in a hadron collider. This kind of summation is always implicitly done, even when not explicitly mentioned in the text. \subsection{Initial- and Final-State Radiation} In every process that contains coloured and/or charged objects in the initial or final state, gluon and/or photon radiation may give large corrections to the overall topology of events. Starting from a basic $2 \to 2$ process, this kind of corrections will generate $2 \to 3$, $2 \to 4$, and so on, final-state topologies. As the available energies are increased, hard emission of this kind is increasingly important, relative to fragmentation, in determining the event structure. Two traditional approaches exist to the modelling of perturbative corrections. One is the matrix-element method, in which Feynman diagrams are calculated, order by order. In principle, this is the correct approach, which takes into account exact kinematics, and the full interference and helicity structure. The only problem is that calculations become increasingly difficult in higher orders, in particular for the loop graphs. Only in exceptional cases have therefore more than one loop been calculated in full, and often we do not have any loop corrections at all at our disposal. On the other hand, we have indirect but strong evidence that, in fact, the emission of multiple soft gluons plays a significant r\^ole in building up the event structure, e.g. at LEP, and this sets a limit to the applicability of matrix elements. Since the phase space available for gluon emission increases with the available energy, the matrix-element approach becomes less relevant for the full structure of events at higher energies. However, the perturbative expansion by itself is better behaved at higher energies, owing to the running of $\alphas$. As a consequence, inclusive measurements, e.g. of the rate of well-separated jets, should yield more reliable results. The second possible approach is the parton-shower one. Here an arbitrary number of branchings of one parton into two (or more) may be put together, to yield a description of multijet events, with no explicit upper limit on the number of partons involved. This is possible since the full matrix-element expressions are not used, but only approximations derived by simplifying the kinematics, and the interference and helicity structure. Parton showers are therefore expected to give a good description of the substructure of jets, but in principle the shower approach has limited predictive power for the rate of well-separated jets (i.e. the 2/3/4/5-jet composition). In practice, shower programs may be patched up to describe the hard-gluon emission region reasonably well, in particular for the $\ee$ annihilation process. Nevertheless, the shower description is not optimal for absolute $\alphas$ determinations. Thus the two approaches are complementary in many respects, and both have found use. However, because of its simplicity and flexibility, the parton-shower option is generally the first choice, while the matrix elements one is mainly used for $\alphas$ determinations, angular distribution of jets, triple-gluon vertex studies, and other specialized studies. Obviously, the ultimate goal would be to have an approach where the best aspects of the two worlds are harmoniously married. \subsubsection{Matrix elements} Matrix elements are especially made use of in the {\Je} implementation of the process $\ee \to \gammaZ \to \q \qbar$. For initial-state QED radiation, a first order (unexponentiated) description has been adopted. This means that events are subdivided into two classes, those where a photon is radiated above some minimum energy, and those without such a photon. In the latter class, the soft and virtual corrections have been lumped together to give a total event rate that is correct up to one loop. This approach worked fine at PETRA/PEP energies, but does not do so well for the $\Z^0$ line shape, i.e. in regions where the cross section is rapidly varying and high precision is strived for. For final-state QCD radiation, several options are available. The default is the parton-shower one (see below), but the matrix-elements options are also frequently used. In the definition of 3- or 4-jet events, a cut is introduced whereby it is required that any two partons have an invariant mass bigger than some fraction of the c.m. energy. 3-jet events which do not fulfill this requirement are lumped with the 2-jet ones. The first-order matrix-element option, which only contains 3- and 2-jet events therefore involves no ambiguities. In second order, where also 4-jets have to be considered, a main issue is what to do with 4-jet events that fail the cuts. Depending on the choice of recombination scheme, whereby the two nearby partons are joined into one, different 3-jet events are produced. Therefore the second-order differential 3-jet rate has been the subject of some controversy, and {\Je} actually contains two different implementations. By contrast, {\Py} does not contain any full higher-order matrix elements, with loop contributions included. There are a few cases where higher-order matrix elements are included at the Born level. Consider e.g. the case of $\W$ production at a hadron collider, which is contained in the lowest-order process $\q \qbar' \to \W$. In an inclusive description, additional jets recoiling against the $\W$ may be generated by parton showers. {\Py} also contains the two first-order processes $\q \g \to \W \q'$ and $\q \qbar' \to \W \g$. The cross sections for these processes are divergent when the $\pT \to 0$. In this region a correct treatment would therefore have to take into account loop corrections, which are not available in {\Py}. Depending on the physics application, one could then use {\Py} in one of two ways. In the region of small $\pT$, the preferred option is lowest-order matrix elements combined with parton showers. For the production of a $\W$ at large $\pT$, on the other hand, the shower approach is too imprecise to give the right cross section; additionally the event selection machinery is very inefficient. Here it is advantageous to generate first-order events, and then add showers only to describe additional softer radiation. \subsubsection{Parton showers} The separation of radiation into initial- and final-state showers is arbitrary, but very convenient. There are also situations where it is appropriate: for instance, the process $\ee \to \Z^0 \to \q \qbar$ only contains final-state QCD radiation (QED radiation, however, is possible both in the initial and final state), while $\q \qbar \to \Z^0 \to \ee$ only contains initial-state QCD one. Similarly, the distinction of emission as coming either from the $\q$ or from the $\qbar$ is arbitrary. In general, the assignment of radiation to a given mother parton is a good approximation for an emission close to the direction of motion of that parton, but not for the wide-angle emission in between two jets, where interference terms are expected to be important. In both initial- and final-state showers, the structure is given in terms of branchings $a \to bc$, specifically $\e \to \e \gamma$, $\q \to \q \g$, $\q \to \q \gamma$, $\g \to \g \g$, and $\g \to \q \qbar$. Each of these processes is characterized by a splitting kernel $P_{a \to bc}(z)$. The branching rate is proportional to the integral $\int P_{a \to bc}(z) \, \d z$. The $z$ value picked for a branching describes the energy sharing, with daughter $b$ taking a fraction $z$ and daughter $c$ the remaining $1-z$ of the $a$ energy. Once formed, the daughters $b$ and $c$ may in turn branch, and so on. Each parton is characterized by some virtuality scale $Q^2$, which gives an approximate sense of time ordering to the cascade. In the initial-state shower, $Q^2$ values are gradually increasing as the hard scattering is approached, while $Q^2$ is decreasing in the final-state showers. Shower evolution is cut off at some lower scale $Q_0$, typically around 1 GeV for QCD branchings. The same cut-off scale is also used to regularize the soft gluon emission divergences in the splitting kernels. From above, a maximum scale $Q_{\mmax}$ is introduced, where the showers are matched to the hard interaction itself. The relation between $Q_{\mmax}$ and the kinematics of the hard scattering is uncertain, and the choice made can strongly affect the amount of well-separated jets. Despite a number of common traits, the initial- and final-state radiation machineries are in fact quite different, and are described separately below. For historical reasons, the final-state shower is found in {\Je} and the initial-state one in {\Py}. Final-state showers are time-like, i.e. partons have $m^2 = E^2 - \mbf{p}^2 \geq 0$. The evolution variable $Q^2$ of the cascade is therefore in {\Je} associated with the $m^2$ of the branching parton, but this choice is not unique. Starting from $Q^2_{\mmax}$, an original parton is evolved downwards in $Q^2$ until a branching occurs. The selected $Q^2$ value defines the mass of the branching parton, and the $z$ of the splitting kernel the parton energy division between its daughters. These daughters may now, in turn, evolve downwards, in this case with maximum virtuality already defined by kinematics, and so on down to the $Q_0$ cut-off. In QCD showers, corrections to the leading-log picture, so-called coherence effects, lead to an ordering of subsequent emissions in terms of decreasing angles. This does not follow automatically from the mass-ordering constraint, but is implemented as an additional requirement on allowed emissions. Photon emission is not affected by angular ordering. It is also possible to obtain non-trivial correlations between azimuthal angles in the various branchings, some of which are implemented as options. Finally, the theoretical analysis strongly suggests the scale choice $\alphas = \alphas(\pT^2) = \alphas(z(1-z)m^2)$, and this is the default in the program. The final-state radiation machinery is applied in the c.m. frame of the hard scattering. The total energy and momentum of the hard-scattering subsystem is preserved, as is the direction of the outgoing partons (in that frame). In contrast to final-state showers, initial-state ones are space-like. This means that, in the sequence of branchings $a \to bc$ that lead up from the shower initiator to the hard interaction, particles $a$ and $b$ have $m^2 = E^2 - \mbf{p}^2 <0$. The `side branch' particle $c$, which does not participate in the hard scattering, may be on the mass shell, or have a time-like virtuality. In the latter case a time-like shower will evolve off it, rather like the final-state radiation described above. To first approximation, the evolution of the space-like main branch is characterized by the evolution variable $Q^2 = -m^2$, which is required to be strictly increasing along the shower, i.e. $Q_b^2 > Q_a^2$. Corrections to this picture have been calculated, but are basically absent in {\Py}. Initial-state radiation is handled within the backwards evolution scheme. In this approach, the choice of the hard scattering is based on the use of evolved parton distributions, which means that the inclusive effects of initial-state radiation are already included. What remains is therefore to construct the exclusive showers. This is done starting from the two incoming partons at the hard interaction, tracing the showers `backwards in time', back to the two shower initiators. In other words, given a parton $b$, one tries to find the parton $a$ that branched into $b$. The evolution in the Monte Carlo is therefore in terms of a sequence of decreasing space-like virtualities $Q^2$ and increasing momentum fractions $x$. Branchings on the two sides are interleaved in a common sequence of decreasing $Q^2$ values. In the above formalism, there is no real distinction between gluon and photon emission. Some of the details actually do differ, as will be explained in the full description. The initial- and final-state radiation shifts around the kinematics of the original hard interaction. In deep inelastic scattering, this means that the $x$ and $Q^2$ values that can be derived from the momentum of the scattered lepton do not agree with the values originally picked. In high-$\pT$ processes, it means that one no longer has two jets with opposite and compensating $\pT$, but more complicated topologies. Effects of any original kinematics selection cuts are therefore smeared out, an unfortunate side-effect of the parton-shower approach. \subsection{Beam Remnants} In a hadron--hadron collision, the initial-state radiation algorithm reconstructs one shower initiator in each beam. This initiator only takes some fraction of the total beam energy, leaving behind a beam remnant which takes the rest. For a proton beam, a $\u$ quark initiator would leave behind a $\u \d$ diquark beam remnant, with an antitriplet colour charge. The remnant is therefore colour-connected to the hard interaction, and forms part of the same fragmenting system. It is further customary to assign a primordial transverse momentum to the shower initiator, to take into account the motion of quarks inside the original hadron, basically as required by the uncertainty principle. This primordial $k_{\perp}$ is selected according to some suitable distribution, and the recoil is assumed to be taken up by the beam remnant. Often the remnant is more complicated, e.g. a $\g$ initiator would leave behind a $\u \u \d$ proton remnant system in a colour octet state, which can conveniently be subdivided into a colour triplet quark and a colour antitriplet diquark, each of which are colour-connected to the hard interaction. The energy sharing between these two remnant objects, and their relative transverse momentum, introduces additional degrees of freedom, which are not understood from first principles. Na\"{\i}vely, one would expect an $\ep$ event to have only one beam remnant, and an $\ee$ event none. This is not always correct, e.g. a $\gamma \gamma \to \q \qbar$ interaction in an $\ee$ event would leave behind the $\e^+$ and $\e^-$ as beam remnants, and a $\q \qbar \to \g \g$ interaction in resolved photoproduction in an $\ee$ event would leave behind one $\e^{\pm}$ and one $\q / \qbar$ in each remnant. Corresponding complications occur for photoproduction in $\ep$ events. There is another source of beam remnants. If parton distributions are used to resolve an electron inside an electron, some of the original energy is not used in the hard interaction, but is rather associated with initial-state photon radiation. The initial-state shower is in principle intended to trace this evolution and reconstruct the original electron before any radiation at all took place. However, because of cut-off procedures, some small amount may be left unaccounted. Alternatively the user may have chosen to switch off initial-state radiation altogether, but still preserved the resolved electron parton distributions. In either case the remaining energy is given to a single photon of vanishing transverse momentum, which is then considered in the same spirit as `true' beam remnants. So far we have assumed that each event only contains one hard interaction, i.e. that each incoming particle has only one parton which takes part in hard processes, and that all other constituents sail through unaffected. This is appropriate in $\ee$ or $\ep$ events, but not necessarily so in hadron--hadron collisions. Here each of the beam particles contains a multitude of partons, and so the probability for several interactions in one and the same event need not be negligible. In principle these additional interactions could arise because one single parton from one beam scatters against several different partons from the other beam, or because several partons from each beam take place in separate $2 \to 2$ scatterings. Both are expected, but combinatorics should favour the latter, which is the mechanism considered in {\Py}. The dominant $2 \to 2$ QCD cross sections are divergent for $\pT \to 0$, and drop rapidly for larger $\pT$. Probably the lowest-order perturbative cross sections will be regularized at small $\pT$ by colour coherence effects: an exchanged gluon of small $\pT$ has a large transverse wave function and can therefore not resolve the individual colour charges of the two incoming hadrons; it will only couple to an average colour charge that vanishes in the limit $\pT \to 0$. In the program, some effective $\pTmin$ scale is therefore introduced, below which the perturbative cross section is either assumed completely vanishing or at least strongly damped. Phenomenologically, $\pTmin$ comes out to be a number of the order of 1.5--2.0 GeV. In a typical `minimum-bias' event one therefore expects to find one or a few scatterings at scales around or a bit above $\pTmin$, while a high-$\pT$ event also may have additional scatterings at the $\pTmin$ scale. The probability to have several high-$\pT$ scatterings in the same event is small, since the cross section drops so rapidly with $\pT$. The understanding of multiple interaction is still very primitive, and even the experimental evidence that it exists at all is rather weak. {\Py} therefore contains several different options, with a fairly simple one as default. The options differ in particular on the issue of the `pedestal' effect: is there an increased probability or not for additional interactions in an event which is known to contain a hard scattering, compared with one that contains no hard interactions? \subsection{Fragmentation} QCD perturbation theory, formulated in terms of quarks and gluons, is valid at short distances. At long distances, QCD becomes strongly interacting and perturbation theory breaks down. In this confinement regime, the coloured partons are transformed into colourless hadrons, a process called either hadronization or fragmentation. In this paper we reserve the former term for the combination of fragmentation and the subsequent decay of unstable particles. The fragmentation process has yet to be understood from first principles, starting from the QCD Lagrangian. This has left the way clear for the development of a number of different phenomenological models. Three main schools are usually distinguished, string fragmentation (SF), independent fragmentation (IF) and cluster fragmentation (CF), but many variants and hybrids exist. Being models, none of them can lay claims to being `correct', although some may be better founded than others. The best that can be aimed for is internal consistency, a good representation of existing data, and a predictive power for properties not yet studied or results at higher energies. {\Je} is intimately connected with string fragmentation, in the form of the time-honoured `Lund model'. This is the default for all {\JePy} applications, but independent fragmentation options also exist, for applications where one wishes to study the importance of string effects. All current models are of a probabilistic and iterative nature. This means that the fragmentation process as a whole is described in terms of one or a few simple underlying branchings, of the type jet $\to$ hadron + remainder-jet, string $\to$ hadron + remainder-string, and so on. At each branching, probabilistic rules are given for the production of new flavours, and for the sharing of energy and momentum between the products. To understand fragmentation models, it is useful to start with the simplest possible system, a colour-singlet $\q \qbar$ 2-jet event, as produced in $\ee$ annihilation. Here lattice QCD studies lend support to a linear confinement picture (in the absence of dynamical quarks), i.e. the energy stored in the colour dipole field between a charge and an anticharge increases linearly with the separation between the charges, if the short-distance Coulomb term is neglected. This is quite different from the behaviour in QED, and is related to the presence of a triple-gluon vertex in QCD. The details are not yet well understood, however. The assumption of linear confinement provides the starting point for the string model. As the $\q$ and $\qbar$ partons move apart from their common production vertex, the physical picture is that of a colour flux tube (or maybe colour vortex line) being stretched between the $\q$ and the $\qbar$. The transverse dimensions of the tube are of typical hadronic sizes, roughly 1 fm. If the tube is assumed to be uniform along its length, this automatically leads to a confinement picture with a linearly rising potential. In order to obtain a Lorentz covariant and causal description of the energy flow due to this linear confinement, the most straightforward way is to use the dynamics of the massless relativistic string with no transverse degrees of freedom. The mathematical, one-dimensional string can be thought of as parametrizing the position of the axis of a cylindrically symmetric flux tube. From hadron spectroscopy, the string constant, i.e. the amount of energy per unit length, is deduced to be $ \kappa \approx 1$ GeV/fm. The expression `massless' relativistic string is somewhat of a misnomer: $\kappa$ effectively corresponds to a `mass density' along the string. Let us now turn to the fragmentation process. As the $\q$ and $\qbar$ move apart, the potential energy stored in the string increases, and the string may break by the production of a new $\q' \qbar'$ pair, so that the system splits into two colour-singlet systems $\q \qbar'$ and $\q' \qbar$. If the invariant mass of either of these string pieces is large enough, further breaks may occur. In the Lund string model, the string break-up process is assumed to proceed until only on-mass-shell hadrons remain, each hadron corresponding to a small piece of string with a quark in one end and an antiquark in the other. In order to generate the quark--antiquark pairs $\q' \qbar'$ which lead to string break-ups, the Lund model invokes the idea of quantum mechanical tunnelling. This leads to a flavour-independent Gaussian spectrum for the $\pT$ of $\q' \qbar'$ pairs. Since the string is assumed to have no transverse excitations, this $\pT$ is locally compensated between the quark and the antiquark of the pair. The total $\pT$ of a hadron is made up out of the $\pT$ contributions from the quark and antiquark that together form the hadron. Some contribution of very soft perturbative gluon emission may also effectively be included in this description. The tunnelling picture also implies a suppression of heavy-quark production, $\u : \d : \s : \c \approx 1 : 1 : 0.3 : 10^{-11}$. Charm and heavier quarks hence are not expected to be produced in the soft fragmentation, but only in perturbative parton-shower branchings $\g \to \q \qbar$. When the quark and antiquark from two adjacent string breakings are combined to form a meson, it is necessary to invoke an algorithm to choose between the different allowed possibilities, notably between pseudoscalar and vector mesons. Here the string model is not particularly predictive. Qualitatively one expects a $1 : 3$ ratio, from counting the number of spin states, multiplied by some wave-function normalization factor, which should disfavour heavier states. A tunnelling mechanism can also be used to explain the production of baryons. This is still a poorly understood area. In the simplest possible approach, a diquark in a colour antitriplet state is just treated like an ordinary antiquark, such that a string can break either by quark--antiquark or antidiquark--diquark pair production. A more complex scenario is the `popcorn' one, where diquarks as such do not exist, but rather quark--antiquark pairs are produced one after the other. This latter picture gives a less strong correlation in flavour and momentum space between the baryon and the antibaryon of a pair. In general, the different string breaks are causally disconnected. This means that it is possible to describe the breaks in any convenient order, e.g. from the quark end inwards. One therefore is led to write down an iterative scheme for the fragmentation, as follows. Assume an initial quark $\q$ moving out along the $+z$ axis, with the antiquark going out in the opposite direction. By the production of a $\q_1 \qbar_1$ pair, a meson $\q \qbar_1$ is produced, leaving behind an unpaired quark $\q_1$. A second pair $\q_2 \qbar_2$ may now be produced, to give a new meson $\q_1 \qbar_2$, etc. At each step the produced hadron takes some fraction of the available energy and momentum. This process may be iterated until all energy is used up, with some modifications close to the $\qbar$ end of the string in order to make total energy and momentum come out right. The choice of starting the fragmentation from the quark end is arbitrary, however. A fragmentation process described in terms of starting at the $\qbar$ end of the system and fragmenting towards the $\q$ end should be equivalent. This `left--right' symmetry constrains the allowed shape of the fragmentation function $f(z)$, where $z$ is the fraction of the remaining light-cone momentum $E \pm p_z$ (+ for the $\q$ jet, $-$ for the $\qbar$ one) taken by each new particle. The resulting `Lund symmetric fragmentation function' has two free parameters, which are determined from data. If several partons are moving apart from a common origin, the details of the string drawing become more complicated. For a $\q \qbar \g$ event, a string is stretched from the $\q$ end via the $\g$ to the $\qbar$ end, i.e. the gluon is a kink on the string, carrying energy and momentum. As a consequence, the gluon has two string pieces attached, and the ratio of gluon to quark string force is 2, a number which can be compared with the ratio of colour charge Casimir operators, $N_C/C_F = 2/(1-1/N_C^2) = 9/4$. In this, as in other respects, the string model can be viewed as a variant of QCD where the number of colours $N_C$ is not 3 but infinite. Note that the factor 2 above does not depend on the kinematical configuration: a smaller opening angle between two partons corresponds to a smaller string length drawn out per unit time, but also to an increased transverse velocity of the string piece, which gives an exactly compensating boost factor in the energy density per unit string length. The $\q \qbar \g$ string will fragment along its length. To first approximation this means that there is one fragmenting string piece between $\q$ and $\g$ and a second one between $\g$ and $\qbar$. One hadron is straddling both string pieces, i.e. sitting around the gluon corner. The rest of the particles are produced as in two simple $\q \qbar$ strings, but strings boosted with respect to the overall c.m. frame. When considered in detail, the string motion and fragmentation is more complicated, with the appearance of additional string regions during the time evolution of the system. These corrections are especially important for soft and collinear gluons, since they provide a smooth transition between events where such radiation took place and events where it did not. Therefore the string fragmentation scheme is `infrared safe' with respect to soft or collinear gluon emission. For events that involve many partons, there may be several possible topologies for their ordering along the string. An example would be a $\q \qbar \g_1 \g_2$ (the gluon indices are here used to label two different gluon-momentum vectors), where the string can connect the partons in either of the sequences $\q - \g_1 - \g_2 - \qbar$ and $\q - \g_2 - \g_1 - \qbar$. The matrix elements that are calculable in perturbation theory contain interference terms between these two possibilities, which means that the colour flow is not always well-defined. Fortunately, the interference terms are down in magnitude by a factor $1/N_C^2$, where $N_C = 3$ is the number of colours, so approximate recipes can be found. In the leading log shower description, on the other hand, the rules for the colour flow are well-defined. A final comment: in the argumentation for the importance of colour flows there is a tacit assumption that soft-gluon exchanges between partons will not normally mess up the original colour assignment; this is likely the case but has not been proven. \subsection{Decays} A large fraction of the particles produced by fragmentation are unstable and subsequently decay into the observable stable (or almost stable) ones. It is therefore important to include all particles with their proper mass distributions and decay properties. Although involving little deep physics, this is less trivial than it may sound: while a lot of experimental information is available, there is also very much that is missing. For charm mesons, it is necessary to put together measured exclusive branching ratios with some inclusive multiplicity distributions to obtain a consistent and reasonably complete set of decay channels, a rather delicate task. For bottom, so far only a rather simple phase-space type of generator has been used for hadronic decays. Normally it is assumed that decay products are distributed according to phase space, i.e. that there is no dynamics involved in their relative distribution. However, in many cases additional assumptions are necessary, e.g. for semileptonic decays of charm and bottom hadrons one needs to include the proper weak matrix elements. Particles may also be produced polarized and impart a non-isotropic distribution to their decay products. Many of these effects are not at all treated in the program. In fact, spin information is not at all carried along, but has to be reconstructed explicitly when needed. The normal decay treatment is handled by {\Je}, making use of a set of tables where branching ratios and decay modes are stored. In {\Py} a separate decay treatment exists, used exclusively for a specific list of particles: $\Z^0$, $\W^{\pm}$, $\H^0$, $\Z'^0$, $\W'^{\pm}$, $\H'^0$, $\A^0$, $\H^{\pm}$, $\eta_{\mrm{tech}}^0$, $\R^0$, $\q^*$, $\ell^*$, and the leptoquark $\L_{\Q}$. Together we call these resonances, and contrast the `particle decay' treatment of {\Je} with the `resonance decay' one of {\Py}. Of course, this is just a matter of terminology: a particle like the $\rho$ could also be called a resonance. What characterizes a ({\Py}) resonance is that partial widths and branching ratios are calculated dynamically, as a function of the actual mass of a particle. Therefore not only do branching ratios change between an $\H^0$ of nominal mass 100 GeV and one of 200 GeV, but also for a Higgs of nominal mass 200 GeV, the branching ratios would change between an actual mass of 190 GeV and 210 GeV, say. This is particularly relevant for reasonably broad resonances, and in threshold regions. For an approach like this to work, it is clearly necessary to have perturbative expressions available for all partial widths, which is one reason why a corresponding treatment would not be the same for an ordinary hadronic resonance, like the $\rho$. The decay products of {\Py} resonances are typically quarks, leptons, or other resonances, e.g. $\W \to \q \qbar'$ or $\H^0 \to \W^+ \W^-$. In decays to quarks, parton showers are automatically added to give a more realistic multijet structure, and one may also allow photon emission off leptons. If the decay products in turn are resonances, further decays are necessary. Often spin information is available in resonance decay matrix elements, contrary to the normal state of affairs in ordinary particle decays. This means that the angular orientations in the two decays of a $\W^+ \W^-$ pair are properly correlated. Occasionally, the information is not available, and then resonances decay isotropically. The top quark is a special problem. The original machinery is based on the assumption that the $\t$ is long-lived, so that top hadrons have time to form in the fragmentation process, and afterwards these mesons decay weakly. With current `best bet' mass values, this is not correct, but one should rather consider top decay before fragmentation. Top should then be handled like one of the above resonances. Therefore the program now contains an alternative along these lines, which is the preferred option. \clearpage \section{Program Overview} This section contains a diverse collection of information. The first part is an overview of previous {\Je} and {\Py} versions. The second gives instructions for installation of the programs and describes their philosophy: how they are constructed and how they are supposed to be used. It also contains some information on how to read this manual. The third and final part contains several examples of pieces of code or short programs, to illustrate the general style of program usage. The last part is mainly intended as an introduction for completely new users, and can be skipped by more experienced ones. {\Je} is the older of the two, and is at the origin of the whole `Lund' family of event generators. It can be subdivided in two parts. The larger is a generic package for jet fragmentation, particle decays, final-state parton showers, event-analysis routines, and other utitilies. This package can be used in the context of any hard process, provided one is willing to buy the underlying assumption of jet universality, i.e. that the fragmentation process is fundamentally the same whether one is considering an $\ee$ or a $\pp$ event, and that the only differences are to be found in the parton-level processes involved. This package is not only used by all other `Lund' programs, but also by numerous other programs written to study specific processes. The smaller part of {\Je} is a generator for $\ee$ annihilation events, according to either a parton-shower or a matrix-element approach. The {\Je} program is now merged with (\Py}. {\Py} was originally a program made to generate hard or soft processes in collisions between leptons, hadrons and photons, especially at $\ee$, $\ep$ and $\pp$ colliders. Where {\Je} was a loose collection of routines that you could combine as desired, {\Py} was a more structured program, where you initially set up what processes you want to study, and thereafter all events will be generated according to this specification. Included is an extensive library of hard subprocess differential cross sections, a library of parton distributions, a process generation machinery, treatment of initial-state showers and beam remnants, and a few odds and ends. The combined {\PyJe} package is completely self-contained. An interface to external parton-distribution function libraries is provided, however, plus a few other optional interfaces. Many programs written by other persons make use of {\Je}, and a few also of {\Py}. It is not my intention to give a complete list here. A majority of these programs are specific to given collaborations, and therefore not publicly distributed. Below we give a list of a few public programs from the `Lund group', which may have a somewhat wider application. None of them are supported by the current author, so any requests should be directed to the persons mentioned. \begin{Itemize} \item \tsc{Ariadne} is a generator for dipole emission, written mainly by L. L\"onnblad \cite{Pet88}. The dipole provides an alternative formulation of initial- and final-state showers. {\Je} or {\Py} can be used to generate the hard process and {\Je} to do the fragmentation. \item \tsc{Aroma} is a generator for heavy-flavour processes in leptoproduction, written by G.~Ingelman and G. Schuler \cite{Ing88}. It uses {\Je} for fragmentation. \item \tsc{Fritiof} is a generator for hadron--hadron, hadron--nucleus and nucleus--nucleus collisions \cite{Nil87}, which makes use of {\Py} to generate hard QCD scatterings and of {\Je} for fragmentation. Currently H. Pi is responsible for program development. \item \tsc{Lepto} is a leptoproduction event generator, written mainly by G. Ingelman \cite{Ing80}. It can generate parton configurations in deep inelastic scattering according to a number of possibilities. It makes use of {\Je} for fragmentation and additionally has a parton-shower option based on {\Py}. \item \tsc{Lucifer} is a photoproduction generator written by G. Ingelman and A. Weigend \cite{Ing87a}. It is a modification of an earlier version of {\Py} and makes use of {\Je}. \item \tsc{Pompyt} is a generator for pomeron interactions written by P. Bruni and G. Ingelman \cite{Bru93}. This program defines parton distributions, flux factors and other aspects specific to the pomeron, which is combined with the standard {\Py} machinery for process generation. \item \tsc{Twister} is a generator for higher-twist processes, written by G. Ingelman \cite{Ing87}. It is a modification of an earlier version of {\Py} and makes use of {\Je}. \end{Itemize} One should also note that a version of {\Py} has been modified to include the effects of longitudinally polarized incoming protons. This is the work of St. G\"ullenstern et al. \cite{Gul93}. \subsection{Update History} For the record, in Tables \ref{Jetsetver} and \ref{Pythiaver} we list the official main versions of {\Je} and {\Py}, respectively, with some brief comments. \begin{table}[tp] \captive{The main versions of {\Je}, with their date of appearance, published manuals, and main changes from previous versions. \label{Jetsetver}} \\ \vspace{1ex} \begin{center} \begin{tabular}{|c|c|c|l|@{\protect\rule{0mm}{\tablinsep}}} \hline No. & Date & Publ. & Main new or improved features \\[1mm] \hline 1 & Nov 78 & \cite{Sjo78} & single-quark jets \\ 2 & May 79 & \cite{Sjo79} & heavy-flavour jets \\ 3.1 & Aug 79 & --- & 2-jets in $\ee$, preliminary 3-jets \\ 3.2 & Apr 80 & \cite{Sjo80} & 3-jets in $\ee$ with full matrix elements, \\ & & & toponium $\to \g \g \g$ decays \\ 3.3 & Aug 80 & --- & softer fragmentation spectrum \\ 4.1 & Apr 81 & --- & baryon production and diquark fragmentation, \\ & & & fourth-generation quarks, larger jet systems \\ 4.2 & Nov 81 & --- & low-$\pT$ physics \\ 4.3 & Mar 82 & \cite{Sjo82} & 4-jets and QFD structure in $\ee$, \\ & Jul 82 & \cite{Sjo83} & event-analysis routines \\ 5.1 & Apr 83 & --- & improved string fragmentation scheme, symmetric \\ & & & fragmentation, full 2$^{\mrm{nd}}$ order QCD for $\ee$ \\ 5.2 & Nov 83 & --- & momentum-conservation schemes for IF, \\ & & & initial-state photon radiation in $\ee$ \\ 5.3 & May 84 & --- & `popcorn' model for baryon production \\ 6.1 & Jan 85 & --- & common blocks restructured, parton showers \\ 6.2 & Oct 85 & \cite{Sjo86} & error detection \\ 6.3 & Oct 86 & \cite{Sjo87} & new parton-shower scheme \\ 7.1 & Feb 89 & --- & new particle codes and common block structure, \\ & & & more mesons, improved decays, vertex information, \\ & & & Abelian gluon model, Bose--Einstein effects \\ 7.2 & Nov 89 & --- & interface to new standard common block, \\ & & & photon emission in showers \\ 7.3 & May 90 & \cite{Sjo92d} & expanded support for non-standard particles \\ 7.4 & Dec 93 & \cite{Sjo94} & updated particle data and defaults \\[1mm] \hline \end{tabular} \end{center} \end{table} \begin{table}[tp] \captive{The main versions of {\Py}, with their date of appearance, published manuals, and main changes from previous versions. \label{Pythiaver}} \\ \vspace{1ex} \begin{center} \begin{tabular}{|c|c|c|l|@{\protect\rule{0mm}{\tablinsep}}} \hline No. & Date & Publ. & Main new or improved features \\[1mm] \hline 1 & Dec 82 & \cite{Ben84} & synthesis of predecessors \tsc{Compton}, \tsc{Highpt} and \\ & & & \tsc{Kassandra} \\ 2 & --- & & \\ 3.1 & --- & & \\ 3.2 & --- & & \\ 3.3 & Feb 84 & \cite{Ben84a} & scale-breaking parton distributions \\ 3.4 & Sep 84 & \cite{Ben85} & more efficient kinematics selection \\ 4.1 & Dec 84 & & initial- and final-state parton showers, $\W$ and $\Z$ \\ 4.2 & Jun 85 & & multiple interactions \\ 4.3 & Aug 85 & & $\W \W$, $\W \Z$, $\Z \Z$ and $\R$ processes \\ 4.4 & Nov 85 & & $\gamma \W$, $\gamma \Z$, $\gamma \gamma$ processes \\ 4.5 & Jan 86 & & $\H^0$ production, diffractive and elastic events \\ 4.6 & May 86 & & angular correlation in resonance pair decays \\ 4.7 & May 86 & & $\Z'^0$ and $\H^+$ processes \\ 4.8 & Jan 87 & \cite{Ben87} & variable impact parameter in multiple interactions \\ 4.9 & May 87 & & $\g \H^+$ process \\ 5.1 & May 87 & & massive matrix elements for heavy quarks \\ 5.2 & Jun 87 & & intermediate boson scattering \\ 5.3 & Oct 89 & & new particle and subprocess codes, new common block \\ & & & structure, new kinematics selection, some \\ & & & lepton--lepton and lepton--hadron interactions, \\ & & & new subprocesses \\ 5.4 & Jun 90 & & $s$-dependent widths, resonances not on the mass shell, \\ & & & new processes, new parton distributions \\ 5.5 & Jan 91 & & improved $\ee$ and $\ep$, several new processes \\ 5.6 & Sep 91 & \cite{Sjo92d} & reorganized parton distributions, new processes, \\ & & & user-defined external processes \\ 5.7 & Dec 93 & \cite{Sjo94} & new total cross sections, photoproduction, top decay \\ 6.1 & Mar 97 & (this) & merger with {\Je}, double precision, supersymmetry \\ & & & baryon production, virtual photon processes \\[1mm] \hline \end{tabular} \end{center} \end{table} All versions preceding {\Py}~6.1 should now be considered obsolete, and are no longer maintained. For stable applications, the earlier combination {\Je}~7.4 and {\Py}~5.7 could still be used, however. The move from {\Je}~7.4 and {\Py}~5.7 to {\Py}~6.1 was a major one. For reasons of space, individual points are therefore not listed separately below, but only the main ones, plus a somewhat more extensive documentation of the most recent subversions. If nothing is explicitly said, these recent changes do not affect backwards compatibility, but only add new features. The main new features of {\Py}~6.1 include: \begin{Itemize} \item The supersymmetric process machinery of \textsc{SPythia} has been included. \item {\Py} and {\Je} have been merged. \item All real variables are declared in double precision. \item The internal mapping of particle codes has changed. \item Extended capabilities to handle reactions of virtual photons, including the flux of such photons inside incomign $\e^{\pm}$. \item Baryon production according to advanced popcorn scheme. \end{Itemize} The following changes have been made since the beginning of 1998, i.e. since the distribution 7.121: \begin{Enumerate} \item {\Py} version 5.722, xx January 1998: \begin{Itemize} \item xxx \end{Itemize} \end{Enumerate} \subsection{Program Installation} \label{ss:install} The {\Py} `master copy' is the one found on my webpage\\ \ttt{http://www.thep.lu.se/~torbjorn/Pythia.html}\\ There you have: \begin{tabbing} ~~~ \= \ttt{pythia61xx.f}~~~~~~~ \= the {\Py}~6.1xx code, \\ \> \ttt{pythia61.tex} \> this {\Py} manual, and \\ \> \ttt{pythia61.update} \> plain text update notes to the manual. \end{tabbing} In addition to these, one may also find older versions of the program and manuals, sample main programs and other pieces of related software, and other physics papers. The programs are written entirely in standard Fortran 77, and should run on any machine with such a compiler. To a first approximation, program compilation should therefore be straightforward. Unfortunately, experience with many different compilers has been uniform: the options available for obtaining optimized code actually produce erroneous code (e.g. operations inside \ttt{DO} loops are moved out before them, where some of the variables have not yet been properly set). Therefore the general advice is to use a low optimization level. Note that this is often not the default setting. \ttt{SAVE} statements have been included in accordance with the Fortran standard. All default settings and particle and process data are stored in \ttt{BLOCK DATA PYDATA}. Theis subprogram must be linked for a proper functioning of the other routines. On some machines this is not done automatically but must be forced by you, in particular if {\Py} is maintained as a library from which routines are to be loaded only when they are needed. In this connection we note that the library approach does not give any significant space advantages over a loading of the packages as a whole, since a normal run will call on most of the routines anyway, directly or indirectly. With the move towards higher energies, e.g. for LHC applications, single-precision (32 bit) real arithmetic has become inappropriate. Thertefore a declaration \ttt{IMPLICIT DOUBLE PRECISION(A-H,O-Z)} at the beginning of each subprogram is inserted to ensure double-precision (64 bit) real arithmetic. Remeber that this also means that all calls to {\Py} routiens have to be done with real variables declared correspondingly in the user-written calling program. The \ttt{IMPLICIT INTEGER(I-N)} then follows, but is included to avoid problems on some compilers. A test program, \ttt{PYTEST}\label{p:PYTEST}, is included in the {\Py} package. It is disguised as a subroutine, so you have to run a main program \begin{verbatim} CALL PYTEST(1) END \end{verbatim} This program will generate over a thousand events of different types, under a variety of conditions. If {\Py} has not been properly installed, this program is likely to crash, or at least generate a number of erroneous events. This will then clearly be marked in the output, which otherwise will just contain a few sample event listings and a table of the number of different particles produced. To switch off the output of normal events and final table, use \ttt{PYTEST(0)} instead of \ttt{PYTEST(1)}. The final tally of errors detected should read 0. \subsection{Program Philosophy} The Monte Carlo programs are built as slave systems, i.e. you, the user, have to supply the main program. From this the various subroutines are called on to execute specific tasks, after which control is returned to the main program. Some of these tasks may be very trivial, whereas the `high-level' routines by themselves may make a large number of subroutine calls. Many routines are not intended to be called directly by you, but only from higher-level routines such as \ttt{LUEXEC}, \ttt{LUEEVT}, \ttt{PYINIT} or \ttt{PYEVNT}. Basically, this means that there are three ways by which you communicate with the programs. First, by setting common block variables, you specify the details of how the programs should perform specific tasks, i.e. which subprocesses should be generated (for {\Py}), which particle masses should be assumed, which coupling constants used, which fragmentation scenarios, and so on with hundreds of options and parameters. Second, by calling subroutines you tell the programs to generate events according to the rules established above. Normally there are few subroutine arguments, and those are usually related to details of the physical situation, such as what c.m. energy to assume for events. Third, you can either look at the common block \ttt{LUJETS} to extract information on the generated event, or you can call on various functions and subroutines to analyse the event further for you. It should be noted that, while the physics content is obviously at the centre of attention, the {\JePy} package also contains a very extensive setup of auxiliary service routines. The hope is that this will provide a comfortable working environment, where not only events are generated, but where you also linger on to perform a lot of the subsequent studies. Of course, for detailed studies, it may be necessary to interface the output directly to a detector simulation program. The general rule is that all routines have names that are six characters long, beginning with \ttt{LU} for {\Je} routines and \ttt{PY} for {\Py} ones. Real-valued functions in {\Je} begin with \ttt{UL} instead. There are three exceptions to both the length and the initial character rules: \ttt{KLU}, \ttt{PLU} and \ttt{RLU}. The former two functions are strongly coupled to the \ttt{K} and \ttt{P} matrices in the \ttt{LUJETS} common block, the latter uses \ttt{R} to emphasize the r\^ole as a random-number generator. Also common block names are six characters long and start with \ttt{LU} or \ttt{PY}. On the issue of initialization, {\Je} and {\Py} behave quite differently. Most {\Je} routines work without any initialization (except for the one implied by the presence of \ttt{BLOCK DATA LUDATA}, see above), i.e. each event and each task stand on their own. Current common block values are used to perform the tasks in specific ways, and those rules can be changed from one event to the next (or even within the generation of one and the same event) without any penalty. The random-number generator is initialized at the first call, but usually this is transparent. Therefore the two {\Je} routines \ttt{LUEEVT} (and some of the routines called by it) and \ttt{LUONIA} are basically the only ones to contain some elements of initialization, where there are a few advantages if events are generated in a coherent fashion, but even here the penalty for not doing it is small. In {\Py}, on the other hand, a sizeable amount of initialization is performed in the \ttt{PYINIT} call, and thereafter the events generated by \ttt{PYEVNT} all obey the rules established at that point. Therefore common block variables that specify methods to be used have to be set before the \ttt{PYINIT} call and then not be changed afterwards, with few exceptions. Of course, it is possible to perform several \ttt{PYINIT} calls in the same run, but there is a significant time overhead involved, so this is not something one would do for each new event. Apart from writing a title page, giving a brief initialization information, printing error messages if need be, and responding to explicit requests for listings, all tasks of the programs are performed `silently'. All output is directed to unit \ttt{MSTU(11)}, by default 6, and it is up to you to set this unit open for write. The only exceptions are \ttt{RLUGET}, \ttt{RLUSET} and \ttt{LUUPDA} where, for obvious reasons, the input/output file number is specified at each call. Here you again have to see to it that proper read/write access is set. The programs are extremely versatile, but the price to be paid for this is having a large number of adjustable parameters and switches for alternative modes of operation. No single user is ever likely to need more than a fraction of the available options. Since all these parameters and switches are assigned sensible default values, there is no reason to worry about them until the need arises. Unless explicitly stated (or obvious from the context) all switches and parameters can be changed independently of each other. One should note, however, that if only a few switches/parameters are changed, this may result in an artificially bad agreement with data. Many disagreements can often be cured by a subsequent retuning of some other parameters of the model, in particular those that were once determined by a comparison with data in the context of the default scenario. For example, for $\ee$ annihilation, such a retuning could involve one QCD parameter ($\alphas$ or $\Lambda$), the longitudinal fragmentation function, and the average transverse fragmentation momentum. The programs contain a number of checks that requested processes have been implemented, that flavours specified for jet systems make sense, that the energy is sufficient to allow hadronization, that the memory space in \ttt{LUJETS} is large enough, etc. If anything goes wrong that the program can catch (obviously this may not always be possible), an error message will be printed and the treatment of the corresponding event will be cut short. In serious cases, the program will abort. As long as no error messages appear on the output, it may not be worthwhile to look into the rules for error checking, but if but one message appears, it should be enough cause for alarm to receive prompt attention. Also warnings are sometimes printed. These are less serious, and the experienced user might deliberately do operations which go against the rules, but still can be made to make sense in their context. Only the first few warnings will be printed, thereafter the program will be quiet. By default, the program is set to stop execution after ten errors, after printing the last erroneous event. It must be emphasized that not all errors will be caught. In particular, one tricky question is what happens if an integer-valued common block switch or subroutine/function argument is used with a value that is not defined. In some subroutine calls, a prompt return will be expedited, but in most instances the subsequent action is entirely unpredictable, and often completely haywire. The same goes for real-valued variables that are assigned values outside the physically sensible range. One example will suffice here: if \ttt{PARJ(2)} is defined as the $\s / \u$ suppression factor, a value $>1$ will not give more profuse production of $\s$ than of $\u$, but actually a spillover into $\c$ production. Users, beware! \subsection{Manual Conventions} In the manual parts of this report, some conventions are used. All names of subprograms, common blocks and variables are given in upper-case `typewriter' style, e.g. \ttt{MSTP(111)=0}. Also program examples are given in this style. If a common block variable must have a value set at the beginning of execution, then a default value is stored in one of the block data subprograms \ttt{LUDATA} and \ttt{PYDATA}. Such a default value is usually indicated by a `(D=\ldots)' immediately after the variable name, e.g. \begin{entry} \iteme{MSTJ(1) :} (D=1) choice of fragmentation scheme. \end{entry} All variables in the {\Je} common blocks (with very few exceptions, clearly marked) can be freely changed from one event to the next, or even within the treatment of one single event. In the {\Py} common blocks the situation is more complicated. The values of many switches and parameters are used already in the \ttt{PYINIT} call, and cannot be changed after that. The problem is mentioned in the preamble to the afflicted common blocks, which in particular means \ttt{/PYPARS/} and \ttt{/PYSUBS/}. For the variables which may still be changed from one event to the next, a `(C)' is added after the `(D=\ldots)' statement. Normally, variables internal to the program are kept in separate common blocks and arrays, but in a few cases such internal variables appear among arrays of switches and parameters, mainly for historical reasons. These are denoted by `(R)' for variables you may want to read, because they contain potentially interesting information, and by `(I)' for purely internal variables. In neither case may the variables be changed by you. In the description of a switch, the alternatives that this switch may take are often enumerated, e.g. \begin{entry} \iteme{MSTJ(1) :} (D=1) choice of fragmentation scheme. \begin{subentry} \iteme{= 0 :} no jet fragmentation at all. \iteme{= 1 :} string fragmentation according to the Lund model. \iteme{= 2 :} independent fragmentation, according to specification in \ttt{MSTJ(2)} and \ttt{MSTJ(3)}. \end{subentry} \end{entry} If you then use any value other than 0, 1 or 2, results are unpredictable. The action could even be different in different parts of the program, depending on the order in which the alternatives are identified. It is also up to you to choose physically sensible values for parameters: there is no check on the allowed ranges of variables. We gave an example of this at the end of the preceding section. Subroutines you are expected to use are enclosed in a box at the point where they are defined: \drawbox{CALL LULIST(MLIST)} \boxsep This is followed by a description of input or output parameters. The difference between input and output is not explicitly marked, but should be obvious from the context. In fact, the event-analysis routines of section \ref{ss:evanrout} return values, while all the rest only have input variables. Routines that are only used internally are not boxed in. However, we use boxes for all common blocks, so as to enhance the readability. \subsection{Getting Started with JETSET} \label{ss:JETstarted} As a first example, assume that you want to study the production of $\u \ubar$ 2-jet systems at 20 GeV energy. To do this, write a main program \begin{verbatim} CALL LU2ENT(0,2,-2,20.) CALL LULIST(1) END \end{verbatim} and run this program, linked together with {\Je}. The routine \ttt{LU2ENT} is specifically intended for storing two entries (jets or particles). The first argument (0) is a command to perform fragmentation and decay directly after the entries have been stored, the second and third that the two entries are $\u$ (2) and $\ubar$ ($-2$), and the last that the c.m. energy of the pair is 20 GeV. When this is run, the resulting event is stored in the \ttt{LUJETS} common block. This information can then be read out by you. No output is produced by \ttt{LU2ENT} itself, except for a title page which appears once for every {\JePy} run. Instead the second command, to \ttt{LULIST}, provides a simple visible summary of the information stored in \ttt{LUJETS}. The argument (1) indicates that the short version should be used, which is suitable for viewing the listing directly on an 80-column terminal screen. It might look as shown here. \begin{verbatim} Event listing (summary) I particle/jet KS KF orig p_x p_y p_z E m 1 (u) A 12 2 0 0.000 0.000 10.000 10.000 0.006 2 (u~) V 11 -2 0 0.000 0.000 -10.000 10.000 0.006 3 (string) 11 92 1 0.000 0.000 0.000 20.000 20.000 4 (rho+) 11 213 3 0.098 -0.154 2.710 2.856 0.885 5 (rho-) 11 -213 3 -0.227 0.145 6.538 6.590 0.781 6 pi+ 1 211 3 0.125 -0.266 0.097 0.339 0.140 7 (Sigma0) 11 3212 3 -0.254 0.034 -1.397 1.855 1.193 8 (K*+) 11 323 3 -0.124 0.709 -2.753 2.968 0.846 9 p~- 1 -2212 3 0.395 -0.614 -3.806 3.988 0.938 10 pi- 1 -211 3 -0.013 0.146 -1.389 1.403 0.140 11 pi+ 1 211 4 0.109 -0.456 2.164 2.218 0.140 12 (pi0) 11 111 4 -0.011 0.301 0.546 0.638 0.135 13 pi- 1 -211 5 0.089 0.343 2.089 2.124 0.140 14 (pi0) 11 111 5 -0.316 -0.197 4.449 4.467 0.135 15 (Lambda0) 11 3122 7 -0.208 0.014 -1.403 1.804 1.116 16 gamma 1 22 7 -0.046 0.020 0.006 0.050 0.000 17 K+ 1 321 8 -0.084 0.299 -2.139 2.217 0.494 18 (pi0) 11 111 8 -0.040 0.410 -0.614 0.751 0.135 19 gamma 1 22 12 0.059 0.146 0.224 0.274 0.000 20 gamma 1 22 12 -0.070 0.155 0.322 0.364 0.000 21 gamma 1 22 14 -0.322 -0.162 4.027 4.043 0.000 22 gamma 1 22 14 0.006 -0.035 0.422 0.423 0.000 23 p+ 1 2212 15 -0.178 0.033 -1.343 1.649 0.938 24 pi- 1 -211 15 -0.030 -0.018 -0.059 0.156 0.140 25 gamma 1 22 18 -0.006 0.384 -0.585 0.699 0.000 26 gamma 1 22 18 -0.034 0.026 -0.029 0.052 0.000 sum: 0.00 0.000 0.000 0.000 20.000 20.000 \end{verbatim} (A few blanks have been removed between the columns to make it fit into the format of this text.) Look in the particle/jet column and note that the first two lines are the original $\u$ and $\ubar$, where `bar' is actually written `$\sim$' to save space in longer names. The parentheses enclosing the names, `\ttt{(u)}' and `\ttt{(u\~{})}', are there as a reminder that these jets actually have been allowed to fragment. The jets are still retained so that event histories can be studied. Also note that the \ttt{KF} (flavour code) column contains 2 in the first line and $-2$ in the second. These are the codes actually stored to denote the presence of a $\u$ and a $\ubar$, cf. the \ttt{LU2ENT} call, while the names written are just conveniences used when producing visible output. The \ttt{A} and \ttt{V} near the end of the particle/jet column indicate the beginning and end of a string (or cluster, or independent fragmentation) parton system; any intermediate entries belonging to the same system would have had an \ttt{I} in that column. (This gives a poor man's representation of an up-down arrow, $\updownarrow$.) In the \ttt{orig} (origin) column, the zeros indicate that $\u$ and $\ubar$ are two initial entries. The subsequent line, number 3, denotes the fragmenting $\u \ubar$ string system as a whole, and has origin 1, since the first parton of this string system is entry number 1. The particles in lines 4--10 have origin 3 to denote that they come directly from the fragmentation of this string. In string fragmentation it is not meaningful to say that a particle comes from only the $\u$ quark or only the $\ubar$ one. It is the string system as a whole that gives a $\rho^+$, a $\rho^-$, a $\pi^+$, a $\Sigma^0$, a $\K^{*+}$, a $\pbar^-$, and a $\pi^-$. Note that some of the particle names are again enclosed in parentheses, indicating that these particles are not present in the final state either, but have decayed further. Thus the $\pi^-$ in line 13 and the $\pi^0$ in line 14 have origin 5, as an indication that they come from the decay of the $\rho^-$ in line 5. Only the names not enclosed in parentheses remain at the end of the fragmentation/decay chain, and are thus experimentally observable. The actual status code used to distinguish between different classes of entries is given in the \ttt{KS} column; codes in the range 1--10 correspond to remaining entries, and those above 10 to those that have fragmented or decayed. The columns with \ttt{p\_x}, \ttt{p\_y}, \ttt{p\_z}, \ttt{E} and \ttt{m} are quite self-explanatory. All momenta, energies and masses are given in units of GeV, since the speed of light is taken to be $c = 1$. Note that energy and momentum are conserved at each step of the fragmentation/decay process (although there exist options where this is not true). Also note that the $z$ axis plays the r\^ole of preferred direction, along which the original partons are placed. The final line is intended as a quick check that nothing funny happened. It contains the summed charge, summed momentum, summed energy and invariant mass of the final entries at the end of the fragmentation/decay chain, and the values should agree with the input implied by the \ttt{LU2ENT} arguments. (In fact, warnings would normally appear on the output if anything untoward happened, but that is another story.) The above example has illustrated roughly what information is to be had in the event record, but not so much about how it is stored. This is better seen by using a 132-column format for listing events. Try e.g. the following program \begin{verbatim} CALL LU3ENT(0,1,21,-1,30.,0.9,0.7) CALL LULIST(2) CALL LUEDIT(3) CALL LULIST(2) END \end{verbatim} where a 3-jet $\d \g \dbar$ event is generated in the first line and listed in the second. This listing will contain the numbers as directly stored in the common block \ttt{LUJETS} \begin{verbatim} COMMON/LUJETS/N,K(4000,5),P(4000,5),V(4000,5) \end{verbatim} For particle \ttt{I}, \ttt{K(I,1)} thus gives information on whether or not a jet or particle has fragmented or decayed, \ttt{K(I,2)} gives the particle code, \ttt{K(I,3)} its origin, \ttt{K(I,4)} and \ttt{K(I,5)} the position of fragmentation/decay products, and \ttt{P(I,1})--\ttt{P(I,5)} momentum, energy and mass. The number of lines in current use is given by \ttt{N}, i.e. 1 $\leq$ \ttt{I} $\leq$ \ttt{N}. The \ttt{V} matrix contains decay vertices; to view those \ttt{LULIST(3)} has to be used. It is important to learn the rules for how information is stored in \ttt{LUJETS}. The third line in the program illustrates another important point about {\Je}: a number of routines are available for manipulating the event record after the event has been generated. Thus \ttt{LUEDIT(3)} will remove everything except stable charged particles, as shown by the result of the second \ttt{LULIST} call. More advanced possibilities include things like sphericity or clustering routines. Apart from the input arguments of subroutine calls, control on the doings of {\Je} may be imposed via the \ttt{LUDAT1}, \ttt{LUDAT2}, \ttt{LUDAT3} and \ttt{LUDAT4} common blocks. Here sensible default values are always provided. A user might want to switch off all particle decays by putting \ttt{MSTJ(21)=0} or increase the $\s / \u$ ratio in fragmentation by putting \ttt{PARJ(2)=0.40}, to give but two examples. It is by exploring the possibilities offered here that {\Je} can be turned into an extremely versatile tool, even if all the nice physics is already present in the default values. As a final, semirealistic example, assume that the $\pT$ spectrum of $\pi^+$ particles is to be studied in 91.2 GeV $\ee$ annihilation events, where $\pT$ is to be defined with respect to the sphericity axis. Using the HBOOK package (version 4, watch out for version- or installation-specific differences) for histogramming, a complete program might look like \begin{verbatim} C...Common blocks. COMMON/LUJETS/N,K(4000,5),P(4000,5),V(4000,5) COMMON/PAWC/HMEMOR(10000) C...Reserve histogram memory and book histograms. CALL HLIMIT(10000) CALL HBOOK1(1,'pT spectrum of pi+',100,0.,5.,0.) C...Number of events to generate. Loop over events. NEVT=100 DO 110 IEVT=1,NEVT C...Generate event. List first one. CALL LUEEVT(0,91.2) IF(IEVT.EQ.1) CALL LULIST(1) C...Find sphericity axis and rotate event so sphericity along z axis. CALL LUSPHE(SPH,APL) CALL LUEDIT(31) C...Loop over all particles, but skip if not pi+. DO 100 I=1,N IF(K(I,2).NE.211) GOTO 100 C...Calculate pT and fill in histogram. PT=SQRT(P(I,1)**2+P(I,2)**2) CALL HF1(1,PT,1.) C...End of particle and event loops. 100 CONTINUE 110 CONTINUE C...Normalize histogram properly and list it. CALL HOPERA(1,'+',1,1,20./NEVT,0.) CALL HISTDO END \end{verbatim} Study this program, try to understand what happens at each step, and run it to check that it works. You should then be ready to look at the relevant sections of this report and start writing your own programs. \subsection{Getting Started with PYTHIA} \label{ss:PYTstarted} A {\Py} run has to be more strictly organized than a {\Je} one, in that it is necessary to initialize the generation before events can be generated, and in that it is not possible to change switches and parameters freely during the course of the run. A fairly precise recipe for how a run should be structured can therefore be given. Thus, the usage of {\Py} can be subdivided into three steps. \begin{Enumerate} \item The initialization step. It is here that all the basic characteristics of the coming generation are specified. The material in this section includes the following. \begin{Itemize} \item Common blocks, at least the following, and maybe some more: \begin{verbatim} COMMON/LUJETS/N,K(4000,5),P(4000,5),V(4000,5) COMMON/LUDAT1/MSTU(200),PARU(200),MSTJ(200),PARJ(200) COMMON/PYSUBS/MSEL,MSUB(200),KFIN(2,-40:40),CKIN(200) COMMON/PYPARS/MSTP(200),PARP(200),MSTI(200),PARI(200) \end{verbatim} \vspace{-\baselineskip} \item Selection of required processes. Some fixed `menus' of subprocesses can be selected with different \ttt{MSEL} values, but with {\tt MSEL}=0 it is possible to compose `\`a la carte', using the subprocess numbers. To generate processes 14, 18 and 29, for instance, one needs \begin{verbatim} MSEL=0 MSUB(14)=1 MSUB(18)=1 MSUB(29)=1 \end{verbatim} \vspace{-\baselineskip} \item Selection of kinematics cuts in the \ttt{CKIN} array. To generate hard scatterings with 5~GeV $\leq \pT \leq$ 10~GeV, for instance, use \begin{verbatim} CKIN(3)=5. CKIN(4)=10. \end{verbatim} \vspace{-\baselineskip} Unfortunately, initial- and final-state radiation will shift around the kinematics of the hard scattering, making the effects of cuts less predictable. One therefore always has to be very careful that no desired event configurations are cut out. \item Definition of underlying physics scenario, e.g. top mass. \item Selection of parton-distribution sets, $Q^2$ definitions, and all other details of the generation. \item Switching off of generator parts not needed for toy simulations, e.g. fragmentation for parton level studies. \item Initialization of the event generation procedure. Here kinematics is set up, maxima of differential cross sections are found for future Monte Carlo generation, and a number of other preparatory tasks carried out. Initialization is performed by \ttt{PYINIT}, which should be called only after the switches and parameters above have been set to their desired values. The frame, the beam particles and the energy have to be specified. \begin{verbatim} CALL PYINIT('CMS','p','pbar',1800.) \end{verbatim} \vspace{-\baselineskip} \item Any other initial material required by the user, e.g. histogram booking. \end{Itemize} \item The generation loop. It is here that events are generated and studied. It includes the following tasks: \begin{Itemize} \item Generation of the next event, with \begin{verbatim} CALL PYEVNT \end{verbatim} \vspace{-\baselineskip} \item Printing of a few events, to check that everything is working as planned, with \begin{verbatim} CALL LULIST(1) \end{verbatim} \vspace{-\baselineskip} \item An analysis of the event for properties of interest, either directly reading out information from the \ttt{LUJETS} common block or making use of a number of utility routines in {\Je}. \item Saving of events on tape, or interfacing to detector simulation. \end{Itemize} \item The finishing step. Here the tasks are: \begin{Itemize} \item Printing a table of deduced cross sections, obtained as a by-product of the Monte Carlo generation activity, with the command \begin{verbatim} CALL PYSTAT(1) \end{verbatim} \vspace{-\baselineskip} \item Printing histograms and other user output. \end{Itemize} \end{Enumerate} To illustrate this structure, imagine a toy example, where one wants to simulate the production of a 300 GeV Higgs particle. In {\Py}, a program for this might look something like the following. \begin{verbatim} C...Common blocks. COMMON/LUJETS/N,K(4000,5),P(4000,5),V(4000,5) COMMON/LUDAT1/MSTU(200),PARU(200),MSTJ(200),PARJ(200) COMMON/LUDAT2/KCHG(500,3),PMAS(500,4),PARF(2000),VCKM(4,4) COMMON/LUDAT3/MDCY(500,3),MDME(2000,2),BRAT(2000),KFDP(2000,5) COMMON/PYSUBS/MSEL,MSUB(200),KFIN(2,-40:40),CKIN(200) COMMON/PYPARS/MSTP(200),PARP(200),MSTI(200),PARI(200) COMMON/PAWC/HBOOK(10000) C...Number of events to generate. Switch on proper processes. NEV=1000 MSEL=0 MSUB(102)=1 MSUB(123)=1 MSUB(124)=1 C...Select t and H masses and kinematics cuts in mass. PMAS(6,1)=140. PMAS(25,1)=300. CKIN(1)=290. CKIN(2)=310. C...For simulation of hard process only: cut out unnecessary tasks. MSTP(61)=0 MSTP(71)=0 MSTP(81)=0 MSTP(111)=0 C...Initialize and list partial widths. CALL PYINIT('CMS','p','p',16000.) CALL PYSTAT(2) C...Book histograms. CALL HLIMIT(10000) CALL HBOOK1(1,'Higgs mass',50,275.,325.,0.) C...Generate events. Look at first few. DO 200 IEV=1,NEV CALL PYEVNT IF(IEV.LE.3) CALL LULIST(1) C...Loop over particles to find Higgs and histogram its mass. DO 100 I=1,N 100 IF(K(I,2).EQ.25) HMASS=P(I,5) CALL HF1(1,HMASS,1.) 200 CONTINUE C...Print cross sections and histograms. CALL PYSTAT(1) CALL HISTDO END \end{verbatim} Here 102, 123 and 124 are the three main Higgs production graphs $\g \g \rightarrow \H$, $\Z \Z \rightarrow \H$, and $\W \W \rightarrow \H$, and \ttt{MSUB(ISUB)=1} is the command to switch on process \ttt{ISUB}. Full freedom to combine subprocesses `\`a la carte' is ensured by \ttt{MSEL=0}; ready-made `menus' can be ordered with other \ttt{MSEL} numbers. The \ttt{PMAS} commands set the masses of the top quark and the Higgs itself, and the \ttt{CKIN} variables the desired mass range of the Higgs --- a Higgs with a 300 GeV nominal mass actually has a fairly broad Breit--Wigner type mass distribution. The \ttt{MSTP} switches that come next are there to modify the generation procedure, in this case to switch off initial- and final-state radiation, multiple interactions among beam jets, and fragmentation, to give only the `parton skeleton' of the hard process. The \ttt{PYINIT} call initializes {\Py}, by finding maxima of cross sections, recalculating the Higgs decay properties (which depend on the Higgs mass), etc. The decay properties can be listed with \ttt{PYSTAT(2)}. Inside the event loop, \ttt{PYEVNT} is called to generate an event, and \ttt{LULIST(1)} to list the event. The information used by \ttt{LULIST(1)} is the event record, stored in the common block \ttt{LUJETS}. Here one finds all produced particles, both final and intermediate ones, with information on particle species and event history (\ttt{K} array), particle momenta (\ttt{P} array) and production vertices (\ttt{V} array). In the loop over all particles produced, \ttt{1} through \ttt{N}, the Higgs particle is found by its code, \ttt{K(I,2)=25}, and its mass is stored in \ttt{P(I,5)}. After all events have been generated, \ttt{PYSTAT(1)} gives a summary of the number of events generated in the various allowed channels, and the inferred cross sections. In the run above, a typical event listing might look like the following. \begin{verbatim} Event listing (summary) I particle/jet KF p_x p_y p_z E m 1 !p+! 2212 0.000 0.000 8000.000 8000.000 0.938 2 !p+! 2212 0.000 0.000-8000.000 8000.000 0.938 ====================================================================== 3 !g! 21 -0.505 -0.229 28.553 28.558 0.000 4 !g! 21 0.224 0.041 -788.073 788.073 0.000 5 !g! 21 -0.505 -0.229 28.553 28.558 0.000 6 !g! 21 0.224 0.041 -788.073 788.073 0.000 7 !H0! 25 -0.281 -0.188 -759.520 816.631 300.027 8 !W+! 24 120.648 35.239 -397.843 424.829 80.023 9 !W-! -24 -120.929 -35.426 -361.677 391.801 82.579 10 !e+! -11 12.922 -4.760 -160.940 161.528 0.001 11 !nu_e! 12 107.726 39.999 -236.903 263.302 0.000 12 !s! 3 -62.423 7.195 -256.713 264.292 0.199 13 !c~! -4 -58.506 -42.621 -104.963 127.509 1.350 ====================================================================== 14 (H0) 25 -0.281 -0.188 -759.520 816.631 300.027 15 (W+) 24 120.648 35.239 -397.843 424.829 80.023 16 (W-) -24 -120.929 -35.426 -361.677 391.801 82.579 17 e+ -11 12.922 -4.760 -160.940 161.528 0.001 18 nu_e 12 107.726 39.999 -236.903 263.302 0.000 19 s A 3 -62.423 7.195 -256.713 264.292 0.199 20 c~ V -4 -58.506 -42.621 -104.963 127.509 1.350 21 ud_1 A 2103 -0.101 0.176 7971.328 7971.328 0.771 22 d V 1 -0.316 0.001 -87.390 87.390 0.010 23 u A 2 0.606 0.052 -0.751 0.967 0.006 24 uu_1 V 2203 0.092 -0.042-7123.668 7123.668 0.771 ====================================================================== sum: 2.00 0.00 0.00 0.00 15999.98 15999.98 \end{verbatim} The above event listing is abnormally short, in part because some columns of information were removed to make it fit into this text, in part because all initial- and final-state QCD radiation, all non-trivial beam jet structure, and all fragmentation was inhibited in the generation. Therefore only the skeleton of the process is visible. In lines 1 and 2 one recognizes the two incoming protons. In lines 3 and 4 are incoming partons before initial-state radiation and in 5 and 6 after --- since there is no such radiation they coincide here. Line 7 shows the Higgs produced by $\g \g$ fusion, 8 and 9 its decay products and 10--13 the second-step decay products. Up to this point lines give a summary of the event history, indicated by the exclamation marks that surround particle names (and also reflected in the \ttt{K(I,1)} code, not shown). From line 14 onwards come the particles actually produced in the final states, first in lines 14--16 particles that subsequently decayed, which have their names surrounded by brackets, and finally the particles and jets left in the end, including beam remnants. Here this also includes a number of unfragmented jets, since fragmentation was inhibited. Ordinarily, the listing would have gone on for a few hundred more lines, with the particles produced in the fragmentation and their decay products. The final line gives total charge and momentum, as a convenient check that nothing unexpected happened. The first column of the listing is just a counter, the second gives the particle name and information on status and string drawing (the \ttt{A} and \ttt{V}), the third the particle-flavour code (which is used to give the name), and the subsequent columns give the momentum components. One of the main problems is to select kinematics efficiently. Imagine for instance that one is interested in the production of a single $\Z$ with a transverse momentum in excess of 50 GeV. If one tries to generate the inclusive sample of $\Z$ events, by the basic production graphs $\q \qbar \rightarrow \Z$, then most events will have low transverse momenta and will have to be discarded. That any of the desired events are produced at all is due to the initial-state generation machinery, which can build up transverse momenta for the incoming $\q$ and $\qbar$. However, the amount of initial-state radiation cannot be constrained beforehand. To increase the efficiency, one may therefore turn to the higher-order processes $\q \g \rightarrow \Z \q$ and $\q \qbar \rightarrow \Z \g$, where already the hard subprocess gives a transverse momentum to the $\Z$. This transverse momentum can be constrained as one wishes, but again initial- and final-state radiation will smear the picture. If one were to set a $\pT$ cut at 50 GeV for the hard-process generation, those events where the $\Z$ was given only 40 GeV in the hard process but got the rest from initial-state radiation would be missed. Not only therefore would cross sections come out wrong, but so might the typical event shapes. In the end, it is therefore necessary to find some reasonable compromise, by starting the generation at 30 GeV, say, if one knows that only rarely do events below this value fluctuate up to 50 GeV. Of course, most events will therefore not contain a $\Z$ above 50 GeV, and one will have to live with some inefficiency. It is not uncommon that only one event out of ten can be used, and occasionally it can be even worse. If it is difficult to set kinematics, it is often easier to set the flavour content of a process. In a Higgs study, one might wish, for example, to consider the decay $\H^0 \rightarrow \Z^0 \Z^0$, with each $\Z^0 \rightarrow \ee$ or $\mu^+ \mu^-$. It is therefore necessary to inhibit all other $\H^0$ and $\Z^0$ decay channels, and also to adjust cross sections to take into account this change, all of which is fairly straightforward. However, if one wanted to consider instead the decay $\Z^0 \rightarrow \c \cbar$, with a $\D$ meson producing a lepton, not only would there then be the problem of different leptonic branching ratios for different $\D$:s (which means that fragmentation and decay treatments would no longer decouple), but also that of additional $\c \cbar$ pair production in parton-shower evolution, at a rate that is unknown beforehand. In practice, it is therefore impossible to force $\D$ decay modes in a consistent manner. \clearpage \section{Monte Carlo Techniques} Quantum mechanics introduces a concept of randomness in the behaviour of physical processes. The virtue of event generators is that this randomness can be simulated by the use of Monte Carlo techniques. In the process, the program authors have to use some ingenuity to find the most efficient way to simulate an assumed probability distribution. A detailed description of possible techniques would carry us too far, but in this section some of the most frequently used approaches are presented, since they will appear in discussions in subsequent sections. Further examples may be found e.g. in \cite{Jam80}. First of all one assumes the existence of a random number generator. This is a (Fortran) function which, each time it is called, returns a number $R$ in the range between 0 and 1, such that the inclusive distribution of numbers $R$ is flat in the range, and such that different numbers $R$ are uncorrelated. The random number generator that comes with {\Je} is described at the end of this section, and we defer the discussion until then. \subsection{Selection From a Distribution} \label{ss:MCdistsel} The situation that is probably most common is that we know a function $f(x)$ which is non-negative in the allowed $x$ range $x_{\mmin} \leq x \leq x_{\mmax}$. We want to select an $x$ `at random' so that the probability for a given $x$ is proportional to $f(x)$. Here $f(x)$ might be a fragmentation function, a differential cross section, or any of a number of distributions. One does not have to assume that the integral of $f(x)$ is explicitly normalized to unity: by the Monte Carlo procedure of picking exactly one accepted $x$ value, normalization is implicit in the final result. Sometimes the integral of $f(x)$ does carry a physics content of its own, as part of an overall weight factor we want to keep track of. Consider, for instance, the case when $x$ represents one or several phase-space variables and $f(x)$ a differential cross section; here the integral has a meaning of total cross section for the process studied. The task of a Monte Carlo is then, on the one hand, to generate events one at a time, and, on the other hand, to estimate the total cross section. The discussion of this important example is deferred to section \ref{ss:PYTcrosscalc}. If it is possible to find a primitive function $F(x)$ which has a known inverse $F^{-1}(x)$, an $x$ can be found as follows (method 1): \begin{eqnarray} & \displaystyle{ \int_{x_{\mmin}}^{x} f(x) \, \d x = R \int_{x_{\mmin}}^{x_{\mmax}} f(x) \, \d x } & \nonumber \\[1mm] \Longrightarrow & x = F^{-1}(F(x_{\mmin}) + R(F(x_{\mmax}) - F(x_{\mmin}))) ~. & \end{eqnarray} The statement of the first line is that a fraction $R$ of the total area under $f(x)$ should be to the left of $x$. However, seldom are functions of interest so nice that the method above works. It is therefore necessary to use more complicated schemes. Special tricks can sometimes be found. Consider e.g. the generation of a Gaussian $f(x) = \exp(-x^2)$. This function is not integrable, but if we combine it with the same Gaussian distribution of a second variable $y$, it is possible to transform to polar coordinates \begin{equation} f(x) \, \d x \, f(y) \, \d y = \exp(-x^2-y^2) \, \d x \, \d y = r \exp(-r^2) \, \d r \, \d \varphi ~, \end{equation} and now the $r$ and $\varphi$ distributions may be easily generated and recombined to yield $x$. At the same time we get a second number $y$, which can also be used. For the generation of transverse momenta in fragmentation, this is very convenient, since in fact we want to assign two transverse degrees of freedom. If the maximum of $f(x)$ is known, $f(x) \leq f_{\mmax}$ in the $x$ range considered, a hit-or-miss method will always yield the correct answer (method 2): \begin{Enumerate} \item select an $x$ with even probability in the allowed range, i.e. $x = x_{\mmin} + R(x_{\mmax} - x_{\mmin})$; \item compare a (new) $R$ with the ratio $f(x)/f_{\mmax}$; if $f(x)/f_{\mmax} \le R$, then reject the $x$ value and return to point 1 for a new try; \item otherwise the most recent $x$ value is retained as final answer. \end{Enumerate} The probability that $f(x)/f_{\mmax} > R$ is proportional to $f(x)$; hence the correct distribution of retained $x$ values. The efficiency of this method, i.e. the average probability that an $x$ will be retained, is $(\int \, f(x) \, \d x) / (f_{\mmax}(x_{\mmax} - x_{\mmin}))$. The method is acceptable if this number is not too low, i.e. if $f(x)$ does not fluctuate too wildly. Very often $f(x)$ does have narrow spikes, and it may not even be possible to define an $f_{\mmax}$. An example of the former phenomenon is a function with a singularity just outside the allowed region, an example of the latter an integrable singularity just at the $x_{\mmin}$ and/or $x_{\mmax}$ borders. Variable transformations may then be used to make a function smoother. Thus a function $f(x)$ which blows up as $1/x$ for $x \rightarrow 0$, with an $x_{\mmin}$ close to 0, would instead be roughly constant if transformed to the variable $y = \ln x$. The variable transformation strategy may be seen as a combination of methods 1 and 2, as follows. Assume the existence of a function $g(x)$, with $f(x) \leq g(x)$ over the $x$ range of interest. Here $g(x)$ is picked to be a `simple' function, such that the primitive function $G(x)$ and its inverse $G^{-1}(x)$ are known. Then (method 3): \begin{Enumerate} \item select an $x$ according to the distribution $g(x)$, using method 1; \item compare a (new) $R$ with the ratio $f(x)/g(x)$; if $f(x)/g(x) \le R$, then reject the $x$ value and return to point 1 for a new try; \item otherwise the most recent $x$ value is retained as final answer. \end{Enumerate} This works, since the first step will select $x$ with a probability $g(x) \, \d x = \d G(x)$ and the second retain this choice with probability $f(x)/g(x)$. The total probability to pick a value $x$ is then just the product of the two, i.e. $f(x) \, \d x$. If $f(x)$ has several spikes, method 3 may work for each spike separately, but it may not be possible to find a $g(x)$ that covers all of them at the same time, and which still has an invertible primitive function. However, assume that we can find a function $g(x) = \sum_i g_i(x)$, such that $f(x) \leq g(x)$ over the $x$ range considered, and such that the functions $g_i(x)$ each are non-negative and simple, in the sense that we can find primitive functions and their inverses. In that case (method 4): \begin{Enumerate} \item select an $i$ at random, with relative probability given by the integrals \begin{equation} \int_{x_{\mmin}}^{x_{\mmax}} g_i(x) \, \d x = G_i(x_{\mmax}) - G_i(x_{\mmin}) ~; \nonumber \end{equation} \item for the $i$ selected, use method 1 to find an $x$, i.e. \begin{equation} x = G_i^{-1}(G_i(x_{\mmin}) + R(G_i(x_{\mmax})-G_i(x_{\mmin}))) ~; \nonumber \end{equation} \item compare a (new) $R$ with the ratio $f(x)/g(x)$; if $f(x)/g(x) \le R$, then reject the $x$ value and return to point 1 for a new try; \item otherwise the most recent $x$ value is retained as final answer. \end{Enumerate} This is just a trivial extension of method 3, where steps 1 and 2 ensure that, on the average, each $x$ value picked there is distributed according to $g(x)$: the first step picks $i$ with relative probability $\int g_i(x) \, \d x$, the second $x$ with absolute probability $g_i(x) / \int g_i(x) \, \d x$ (this is one place where one must remember to do normalization correctly); the product of the two is therefore $g_i(x)$ and the sum over all $i$ gives back $g(x)$. We have now arrived at an approach that is sufficiently powerful for a large selection of problems. In general, for a function $f(x)$ which is known to have sharp peaks in a few different places, the generic behaviour at each peak separately may be covered by one or a few simple functions $g_i(x)$, to which one adds a few more $g_i(x)$ to cover the basic behaviour away from the peaks. By a suitable selection of the relative strengths of the different $g_i$'s, it is possible to find a function $g(x)$ that matches well the general behaviour of $f(x)$, and thus achieve a reasonable Monte Carlo efficiency. The major additional complication is when $x$ is a multidimensional variable. Usually the problem is not so much $f(x)$ itself, but rather that the phase-space boundaries may be very complicated. If the boundaries factorize it is possible to pick phase-space points restricted to the desired region. Otherwise the region may have to be inscribed in a hyper-rectangle, with points picked within the whole hyper-rectangle but only retained if they are inside the allowed region. This may lead to a significant loss in efficiency. Variable transformations may often make the allowed region easier to handle. There are two main methods to handle several dimensions, each with its set of variations. The first method is based on a factorized ansatz, i.e. one attempts to find a function $g(\mbf{x})$ which is everywhere larger than $f(\mbf{x})$, and which can be factorized into $g(\mbf{x}) = g^{(1)}(x_1) \, g^{(2)}(x_2) \cdots g^{(n)}(x_n)$, where $\mbf{x} = (x_1,x_2,\ldots,x_n)$. Here each $g^{(j)}(x_j)$ may in its turn be a sum of functions $g^{(j)}_i$, as in method 4 above. First, each $x_j$ is selected independently, and afterwards the ratio $f(\mbf{x})/g(\mbf{x})$ is used to determine whether to retain the point. The second method is useful if the boundaries of the allowed region can be written in a form where the maximum range of $x_1$ is known, the allowed range of $x_2$ only depends on $x_1$, that of $x_3$ only on $x_1$ and $x_2$, and so on until $x_n$, whose range may depend on all the preceding variables. In that case it may be possible to find a function $g(\mbf{x})$ that can be integrated over $x_2$ through $x_n$ to yield a simple function of $x_1$, according to which $x_1$ is selected. Having done that, $x_2$ is selected according to a distribution which now depends on $x_1$, but with $x_3$ through $x_n$ integrated over. In particular, the allowed range for $x_2$ is known. The procedure is continued until $x_n$ is reached, where now the function depends on all the preceding $x_j$ values. In the end, the ratio $f(\mbf{x})/g(\mbf{x})$ is again used to determine whether to retain the point. \subsection{The Veto Algorithm} \label{ss:vetoalg} The `radioactive decay' type of problems is very common, in particular in parton showers, but it is also used, e.g. in the multiple interactions description in {\Py}. In this kind of problems there is one variable $t$, which may be thought of as giving a kind of time axis along which different events are ordered. The probability that `something will happen' (a nucleus decay, a parton branch) at time $t$ is described by a function $f(t)$, which is non-negative in the range of $t$ values to be studied. However, this na\"{\i}ve probability is modified by the additional requirement that something can only happen at time $t$ if it did not happen at earlier times $t' < t$. (The original nucleus cannot decay once again if it already did decay; possibly the decay products may decay in their turn, but that is another question.) The probability that nothing has happened by time $t$ is expressed by the function ${\cal N}(t)$ and the differential probability that something happens at time $t$ by ${\cal P}(t)$. The basic equation then is \begin{equation} {\cal P}(t) = - \frac{\d {\cal N}}{\d t} = f(t) \, {\cal N}(t) ~. \end{equation} For simplicity, we shall assume that the process starts at time $t = 0$, with ${\cal N}(0) = 1$. The above equation can be solved easily if one notes that $\d {\cal N} / {\cal N} = \d \ln {\cal N}$: \begin{equation} {\cal N}(t) = {\cal N}(0) \exp \left\{ - \int_0^t f(t') \, \d t' \right\} = \exp \left\{ - \int_0^t f(t') \, \d t' \right\} ~, \end{equation} and thus \begin{equation} {\cal P}(t) = f(t) \exp \left\{ - \int_0^t f(t') \, \d t' \right\} ~. \label{mc:Pveto} \end{equation} With $f(t) = c$ this is nothing but the textbook formulae for radioactive decay. In particular, at small times the correct decay probability, ${\cal P}(t)$, agrees well with the input one, $f(t)$, since the exponential factor is close to unity there. At larger $t$, the exponential gives a dampening which ensures that the integral of ${\cal P}(t)$ never can exceed unity, even if the integral of $f(t)$ does. The exponential can be seen as the probability that nothing happens between the original time 0 and the final time $t$. In the parton-shower language, this is (almost) the so-called Sudakov form factor. If $f(t)$ has a primitive function with a known inverse, it is easy to select $t$ values correctly: \begin{equation} \int_0^t {\cal P}(t') \, \d t' = {\cal N}(0) - {\cal N}(t) = 1 - \exp \left\{ - \int_0^t f(t') \, \d t' \right\} = 1 - R ~, \end{equation} which has the solution \begin{equation} F(0) - F(t) = \ln R ~~~ \Longrightarrow ~~~ t = F^{-1}(F(0) - \ln R) ~. \end{equation} If $f(t)$ is not sufficiently nice, one may again try to find a better function $g(t)$, with $f(t) \leq g(t)$ for all $t \geq 0$. However to use method 3 with this $g(t)$ would not work, since the method would not correctly take into account the effects of the exponential term in ${\cal P}(t)$. Instead one may use the so-called veto algorithm: \begin{Enumerate} \item start with $i = 0$ and $t_0 = 0$; \item add 1 to $i$ and select $t_i = G^{-1}(G(t_{i-1}) - \ln R)$, i.e. according to $g(t)$, but with the constraint that $t_i > t_{i-1}$, \item compare a (new) $R$ with the ratio $f(t_i)/g(t_i)$; if $f(t_i)/g(t_i) \le R$, then return to point 2 for a new try; \item otherwise $t_{i}$ is retained as final answer. \end{Enumerate} It may not be apparent why this works. Consider, however, the various ways in which one can select a specific time $t$. The probability that the first try works, $t = t_1$, i.e. that no intermediate $t$ values need be rejected, is given by \begin{equation} {\cal P}_0 (t) = \exp \left\{ - \int_0^t g(t') \, \d t' \right\} \, g(t) \, \frac{f(t)}{g(t)} = f(t) \exp \left\{ - \int_0^t g(t') \, \d t' \right\} ~, \end{equation} where the exponential times $g(t)$ comes from eq.~(\ref{mc:Pveto}) applied to $g$, and the ratio $f(t)/g(t)$ is the probability that $t$ is accepted. Now consider the case where one intermediate time $t_1$ is rejected and $t = t_2$ is only accepted in the second step. This gives \begin{equation} {\cal P}_1 (t) = \int_0^t \d t_1 \exp \left\{ - \int_0^{t_1} g(t') \, \d t' \right\} g(t_1) \left[ 1 - \frac{f(t_1)}{g(t_1)} \right] \exp \left\{ - \int_{t_1}^t g(t') \, \d t' \right\} g(t) \, \frac{f(t)}{g(t)} ~, \end{equation} where the first exponential times $g(t_1)$ gives the probability that $t_1$ is first selected, the square brackets the probability that $t_1$ is subsequently rejected, the following piece the probability that $t = t_2$ is selected when starting from $t_1$, and the final factor that $t$ is retained. The whole is to be integrated over all possible intermediate times $t_1$. The exponentials together give an integral over the range from 0 to $t$, just as in ${\cal P}_0$, and the factor for the final step being accepted is also the same, so therefore one finds that \begin{equation} {\cal P}_1 (t) = {\cal P}_0 (t) \int_0^t \d t_1 \left[ g(t_1) - f(t_1) \right] ~. \end{equation} This generalizes. In ${\cal P}_2$ one has to consider two intermediate times, $0 \leq t_1 \leq t_2 \leq t_3 = t$, and so \begin{eqnarray} {\cal P}_2 (t) & = & {\cal P}_0 (t) \int_0^t \d t_1 \left[ g(t_1) - f(t_1) \right] \int_{t_1}^t \d t_2 \left[ g(t_2) - f(t_2) \right] \nonumber \\ & = & {\cal P}_0 (t) \frac{1}{2} \left( \int_0^t \left[ g(t') - f(t') \right] \d t' \right)^2 ~. \end{eqnarray} The last equality is most easily seen if one also considers the alternative region $0 \leq t_2 \leq t_1 \leq t$, where the r\^oles of $t_1$ and $t_2$ have just been interchanged, and the integral therefore has the same value as in the region considered. Adding the two regions, however, the integrals over $t_1$ and $t_2$ decouple, and become equal. In general, for ${\cal P}_i$, the $i$ intermediate times can be ordered in $i!$ different ways. Therefore the total probability to accept $t$, in any step, is \begin{eqnarray} {\cal P} (t) & = & \displaystyle{ \sum_{i=0}^{\infty} {\cal P}_i (t) = {\cal P}_0 (t) \sum_{i=0}^{\infty} \frac{1}{i!} \left( \int_0^t \left[ g(t') - f(t') \right] \d t' \right)^i } \nonumber \\ & = & \displaystyle{ f(t) \exp \left\{ - \int_0^t g(t') \, \d t' \right\} \exp \left\{ \int_0^t \left[ g(t') - f(t') \right] \d t' \right\} } \nonumber \\ & = & \displaystyle{ f(t) \exp \left\{ - \int_0^t f(t') \, \d t' \right\} ~, } \end{eqnarray} which is the desired answer. If the process is to be stopped at some scale $t_{\mmax}$, i.e. if one would like to remain with a fraction ${\cal N}(t_{\mmax})$ of events where nothing happens at all, this is easy to include in the veto algorithm: just iterate upwards in $t$ at usual, but stop the process if no allowed branching is found before $t_{\mmax}$. Usually $f(t)$ is a function also of additional variables $x$. The methods of the preceding subsection are easy to generalize if one can find a suitable function $g(t,x)$ with $f(t,x) \leq g(t,x)$. The $g(t)$ used in the veto algorithm is the integral of $g(t,x)$ over $x$. Each time a $t_i$ has been selected also an $x_i$ is picked, according to $g(t_i,x) \, dx$, and the $(t,x)$ point is accepted with probability $f(t_i,x_i)/g(t_i,x_i)$. \subsection{The Random Number Generator} The construction of a good, portable (pseudo)random generator is not a trivial task. Therefore {\Je} has traditionally stayed away from that area, and just provided the routine \ttt{RLU} as an interface, which the user could modify to call on an existing routine, implemented on the actual machine being used. In recent years, progress has been made in constructing portable generators with large periods and other good properties; see the review \cite{Jam90}. Therefore the current version contains a random number generator based on the algorithm proposed by Marsaglia, Zaman and Tsang \cite{Mar90}. This routine should work on any machine with a mantissa of at least 24 digits, i.e. all common 32-bit (or more) computers. Given the same initial state, the sequence will also be identical on different machines. This need not mean that the same sequence of events will be generated on an IBM and a VAX, say, since the different treatments of roundoff errors in numerical operations will lead to slightly different real numbers being tested against these random numbers in IF statements. Also code optimization may lead to a divergence. Apart from nomenclature issues, and the coding of \ttt{RLU} as a function rather than a subroutine, the only difference between the {\Je} code and the code given in \cite{Jam90} is that slightly different algorithms are used to ensure that the random number is not equal to 0 or 1 within the machine precision. The generator has a period of over $10^{43}$, and the possibility to obtain almost $10^9$ different and disjoint subsequences, selected by giving an initial integer number. The price to be paid for the long period is that the state of the generator at a given moment cannot be described by a single integer, but requires about 100 words. Some of these are real numbers, and are thus not correctly represented in decimal form. The normal procedure, which makes it possible to restart the generation from a seed value written to the run output, is therefore not convenient. The CERN library implementation keeps track of the number of random numbers generated since the start. With this value saved, in a subsequent run the random generator can be asked to skip ahead the corresponding number of random numbers. {\Je} is a heavy user of random numbers, however: typically 30\% of the full run time is spent on random number generation. Of this, half is overhead coming from the function call administration, but the other half is truly related to the speed of the algorithm. Therefore a skipping ahead would take place with 15\% of the time cost of the original run, i.e. an uncomfortably high figure. Instead a different solution is chosen here. Two special routines are provided for writing and reading the state of the random number generator (plus some initialization information) on a sequential file, in a machine-dependent internal representation. The file used for this purpose has to be specified by you, and opened for read and write. A state is written as a single record, in free format. It is possible to write an arbitrary number of states on a file, and a record can be overwritten, if so desired. The event generation loop might then look something like: \begin{Enumerate} \item save the state of the generator on file (using flag set in point 3 below), \item generate an event, \item study the event for errors or other reasons why to regenerate it later; set flag to overwrite previous generator state if no errors, otherwise set flag to create new record; \item loop back to point 1. \end{Enumerate} With this procedure, the file will contain the state before each of the problematical events. An alternative approach might be to save the state every 100 events or so. If the events are subsequently processed through a detector simulation, you may have to save also other sets of seeds, naturally. In addition to the service routines, the common block which contains the state of the generator is available for manipulation, if you so desire. In particular, the initial seed value is by default 19780503, i.e. different from the Marsaglia/CERN default 54217137. It is possible to change this value before any random numbers have been generated, or to force reinitialization in mid-run with any desired new seed. Inside {\JePy}, some initialization may take place in connection with the very first event generated in a run, so sometimes it may be necessary to generate one ordinary event before reading in a saved state to generate an interesting event. In the current {\Py} version, some of the multiple interaction machinery options contain an element of learning, which means that the event sequence may be broken. It should be noted that, of course, the appearance of a random number generator package inside {\Je} does in no way preclude the use of other routines. You can easily revert to the old approach, where \ttt{RLU} is nothing but an interface to an arbitrary external random number generator; e.g. to call a routine \ttt{RNDM} all you need to have is \begin{verbatim} FUNCTION RLU(IDUMMY) 100 RLU=RNDM(IDUMMY) IF(RLU.LE.0..OR.RLU.GE.1.) GOTO 100 RETURN END \end{verbatim} The random generator subpackage consists of the following components. \drawbox{R = RLU(IDUMMY)}\label{p:RLU} \begin{entry} \itemc{Purpose:} to generate a (pseudo)random number \ttt{R} uniformly in the range 0$<$\ttt{R}$<$1, i.e. excluding the endpoints. \iteme{IDUMMY :} dummy input argument; normally 0. \end{entry} \drawbox{CALL RLUGET(LFN,MOVE)}\label{p:RLUGET} \begin{entry} \itemc{Purpose:} to dump the current state of the random number generator on a separate file, using internal representation for real and integer numbers. To be precise, the full contents of the \ttt{LUDATR} common block are written on the file, with the exception of \ttt{MRLU(6)}. \iteme{LFN :} (logical file number) the file number to which the state is dumped. You must associate this number with a true file (with a machine-dependent name), and see to it that this file is open for write. \iteme{MOVE :} choice of adding a new record to the file or overwriting old record(s). Normally only options 0 or $-$1 should be used. \begin{subentry} \iteme{= 0 (or > 0) :} add a new record to the end of the file. \iteme{= -1 :} overwrite the last record with a new one (i.e. do one \ttt{BACKSPACE} before the new write). \iteme{= $-n$ :} back up $n$ records before writing the new record. The records following after the new one are lost, i.e. the last $n$ old records are lost and one new added. \end{subentry} \end{entry} \drawbox{CALL RLUSET(LFN,MOVE)}\label{p:RLUSET} \begin{entry} \itemc{Purpose:} to read in a state for the random number generator, from which the subsequent generation can proceed. The state must previously have been saved by a \ttt{RLUGET} call. Again the full contents of the \ttt{LUDATR} common block are read, with the exception of \ttt{MRLU(6)}. \iteme{LFN :} (logical file number) the file number from which the state is read. You must associate this number with a true file previously written with a \ttt{RLUGET} call, and see to it that this file is open for read. \iteme{MOVE :} positioning in file before a record is read. With zero value, records are read one after the other for each new call, while non-zero values may be used to navigate back and forth, and e.g. return to the same initial state several times. \begin{subentry} \iteme{= 0 :} read the next record. \iteme{= $+n$ :} skip ahead $n$ records before reading the record that sets the state of the random number generator. \iteme{= $-n$ :} back up $n$ records before reading the record that sets the state of the random number generator. \end{subentry} \end{entry} \drawbox{COMMON/LUDATR/MRLU(6),RRLU(100)}\label{p:LUDATR} \begin{entry} \itemc{Purpose:} to contain the state of the random number generator at any moment (for communication between \ttt{RLU}, \ttt{RLUGET} and \ttt{RLUSET}), and also to provide the user with the possibility to initialize different random number sequences, and to know how many numbers have been generated. \iteme{MRLU(1) :}\label{p:MRLU} (D=19780503) the integer number that specifies which of the possible subsequences will be initialized in the next \ttt{RLU} call for which \ttt{MRLU(2)=0}. Allowed values are 0$\leq$\ttt{MRLU(1)}$\leq$900\,000\,000, the original Marsaglia (and CERN library) seed is 54217137. The \ttt{MRLU(1)} value is not changed by any of the {\Je} routines. \iteme{MRLU(2) :} (D=0) initialization flag, put to 1 in the first \ttt{RLU} call of run. A reinitialization of the random number generator can be made in mid-run by resetting \ttt{MRLU(2)} to 0 by hand. In addition, any time the counter \ttt{MRLU(3)} reaches 1000000000, it is reset to 0 and \ttt{MRLU(2)} is increased by 1. \iteme{MRLU(3) :} (D=0) counter for the number of random numbers generated from the beginning of the run. To avoid overflow when very many numbers are generated, \ttt{MRLU(2)} is used as described above. \iteme{MRLU(4), MRLU(5) :} \ttt{I97} and \ttt{J97} of the CERN library implementation; part of the state of the generator. \iteme{MRLU(6) :} (D=0) current position, i.e. how many records after beginning, in the file; used by \ttt{RLUGET} and \ttt{RLUSET}. \iteme{RRLU(1) - RRLU(97) :}\label{p:RRLU} the \ttt{U} array of the CERN library implementation; part of the state of the generator. \iteme{RRLU(98) - RRLU(100) :} \ttt{C}, \ttt{CD} and \ttt{CM} of the CERN library implementation; the first part of the state of the generator, the latter two constants calculated at initialization. \end{entry} \clearpage \section{The Event Record} The event record is the central repository for information about the particles produced in the current event: flavours, momenta, event history, and production vertices. It plays a very central r\^ole: without a proper understanding of what the record is and how information is stored, it is meaningless to try to use either {\Je} or {\Py}. The record is stored in the common block \ttt{LUJETS}. Almost all the routines thatthe user calls can be viewed as performing some action on the record: fill a new event, let partons fragment or particles decay, boost it, list it, find clusters, etc. In this section we will first describe the KF flavour code, subsequently the \ttt{LUJETS} common block, and then give a few comments about the r\^ole of the event record in the programs. To ease the interfacing of different event generators, a \ttt{HEPEVT} standard common block structure for the event record has been agreed on. For historical reasons the standard common blocks are not directly used in {\Je}, but a conversion routine comes with the program, and is described at the end of this section. \subsection{Particle Codes} \label{ss:codes} The new particle code now adopted by the Particle Data Group \cite{PDG88,PDG92} is used consistently throughout the program, and is referred to as the KF particle code. This code you have to be thoroughly familiar with. It is described below. Note that a few inconsistencies between the KF and the PDG codes are known, which stem from differences of interpretation of the rules agreed on when developing the standard. These rules form the basis of the PDG tables and (independently) of the {\Je} tables. (Of course, my private opinion is that I follow the original agreement, and the PDG deviate from it.) Hopefully, this should have few practical consequences, since only rarely-produced particles are affected. Anyway, here is a list of the known discrepancies: \begin{Enumerate} \item The PDG has not allowed for the existence of an $\eta_{\b}$, which in {\Je} is included with code 551. This code is reserved for $\chi_{0 \b}$ by the PDG, a particle which appears as 10551 in {\Je}. (We agree to have $\eta_{\c}$ as 441, which illustrates the basic difference: I use the additional recurrence figure to refer to a whole multiplet, whether all particles of that multiplet have been found or not; the PDG, on the other hand, does not reserve space for particles which we know should be there but have not yet been discovered, which means that members of a multiplet need not go together.) \item The PDG has not allowed for the existence of an $\hrm_{1 \c}$, which in {\Je} is represented by 10443. Therefore $\chi_{1 \c}$ is the PDG code 10443 but {\Je} code 20443. Further $\psi'$ is either 20443 or 30443, and $\Upsilon' = \Upsilon(2S)$ either 20553 or 30553. (Comment as for point 1.) \item Different conventions for spin $1/2$ baryons with one heavy flavour (charm, bottom, top), one strange flavour, and one light ($\u$ or $\d$). Here two states exist, e.g. $\Xi_{\c}^+$ and $\Xi'^+_{\c}$, both with flavour content $\c\s\u$. By analogy with the $\Lambda^0$--$\Sigma$ pair, {\Je} uses the decreasing order of flavour content for the heavier state and inversed order of the two lighter flavours for the lighter state, while the PDG tables use the opposite convention. Thus in {\Je} $\Xi_{\c}^+$ is 4232 and $\Xi'^+_{\c}$ 4322, while in PDG it is the other way around. \end{Enumerate} There are no plans to change the {\Je} rules to agree with the PDG ones in either of the cases above. The KF code is not convenient for a direct storing of masses, decay data, or other particle properties, since the KF codes are so spread out. Instead a compressed code KC between 1 and 500 is used here, where the most frequently used particles have a separate code, but many heavy-flavour hadrons are lumped together in groups. Normally this code is only used at very specific places in the program, not visible to the user. If need be, the correspondence can always be obtained by using the function \ttt{LUCOMP}, \mbox{\ttt{KC = LUCOMP(KF)}}. It is therefore not intended that you should ever need to know any KC codes at all. It may be useful to know, however, that for codes smaller than 80, KF and KC agree. The particle names printed in the tables in this section correspond to the ones obtained with the routine \ttt{LUNAME}, which is used extensively, e.g. in \ttt{LULIST}. Greek characters are spelt out in full, with a capital first letter to correspond to a capital Greek letter. Generically the name of a particle is made up of the following pieces: \begin{Enumerate} \item The basic root name. This includes a * for most spin 1 ($L = 0$) mesons and spin $3/2$ baryons, and a $'$ for some spin $1/2$ baryons (where there are two states to be distinguished, cf. $\Lambda$--$\Sigma^0$). The rules for heavy baryon naming are in accordance with the 1986 Particle Data Group conventions \cite{PDG86}. For mesons with one unit of orbital angular momentum, K (D, B, \ldots) is used for quark-spin 0 and K* (D*, B*, \ldots) for quark-spin 1 mesons; the convention for `*' may here deviate slightly from the one used by the PDG. \item Any lower indices, separated from the root by a \_. For heavy hadrons, this is the additional heavy-flavour content not inherent in the root itself. For a diquark, it is the spin. \item The character $\sim$ (alternatively bar, see \ttt{MSTU(15)}) for an antiparticle, wherever the distinction between particle and antiparticle is not inherent in the charge information. \item Charge information: $++$, $+$, $0$, $-$, or $--$. Charge is not given for quarks or diquarks. Some neutral particles which are customarily given without a 0 also here lack it, such as neutrinos, $\g$, $\gamma$, and flavour-diagonal mesons other than $\pi^0$ and $\rho^0$. Note that charge is included both for the proton and the neutron. While non-standard, it is helpful in avoiding misunderstandings when looking at an event listing. \end{Enumerate} Below follows a list of KF particle codes. The list is not complete; a more extensive one may be obtained with \ttt{CALL LULIST(11)}. Particles are grouped together, and the basic rules are described for each group. Whenever a distinct antiparticle exists, it is given the same KF code with a minus sign (whereas KC codes are always positive). \begin{Enumerate} \item Quarks and leptons, Table \ref{t:codeone}. \\ This group contains the basic building blocks of matter, arranged according to family, with the lower member of weak isodoublets also having the smaller code (thus $\d$ precedes $\u$, contrary to the ordering in previous {\Je} versions). A fourth generation is included for future reference. The quark codes are used as building blocks for the diquark, meson and baryon codes below. \begin{table}[ptb] \captive{Quark and lepton codes. \protect\label{t:codeone} } \\ \vspace{1ex} \begin{center} \begin{tabular}{|c|c|c||c|c|c|@{\protect\rule{0mm}{\tablinsep}}} \hline KF & Name & Printed & KF & Name & Printed \\ \hline 1 & $\d$ & \ttt{d} & 11 & $\e^-$ & \ttt{e-} \\ 2 & $\u$ & \ttt{u} & 12 & $\nu_{\e}$ & \ttt{nu\_e} \\ 3 & $\s$ & \ttt{s} & 13 & $\mu^-$ & \ttt{mu-} \\ 4 & $\c$ & \ttt{c} & 14 & $\nu_{\mu}$ & \ttt{nu\_mu} \\ 5 & $\b$ & \ttt{b} & 15 & $\tau^-$ & \ttt{tau-} \\ 6 & $\t$ & \ttt{t} & 16 & $\nu_{\tau}$ & \ttt{nu\_tau} \\ 7 & $\lrm$ & \ttt{l} & 17 & $\chi^-$ & \ttt{chi-} \\ 8 & $\hrm$ & \ttt{h} & 18 & $\nu_{\chi}$ & \ttt{nu\_chi} \\ 9 & & & 19 & & \\ 10 & & & 20 & & \\ \hline \end{tabular} \end{center} \end{table} \item Gauge bosons and other fundamental bosons, Table \ref{t:codetwo}. \\ This group includes all the gauge and Higgs bosons of the standard model, as well as some of the bosons appearing in various extensions of it. The latter are not covered by the standard PDG codes. They correspond to one extra {\bf U(1)} group and one extra {\bf SU(2)} one, a further Higgs doublet, a (scalar, colour octet) techni-$\eta$, a (scalar) leptoquark $\L_{\Q}$, and a horizontal gauge boson $\R$ (coupling between families). Additionally, we here include the pomeron $\pomeron$ and reggeon $\reggeon$ `particles', which are important e.g. in the description of diffractive scattering, but have no obvious position anywhere in the classification scheme. \begin{table}[ptb] \captive{Gauge boson and other fundamental boson codes. \protect\label{t:codetwo} } \\ \vspace{1ex} \begin{center} \begin{tabular}{|c|c|c||c|c|c|@{\protect\rule{0mm}{\tablinsep}}} \hline KF & Name & Printed & KF & Name & Printed \\ \hline 21 & $\g$ & \ttt{g} & 31 & & \\ 22 & $\gamma$ & \ttt{gamma} & 32 & $\Z'^0$ & \ttt{Z'0} \\ 23 & $\Z^0$ & \ttt{Z0} & 33 & $\Z''^0$ & \ttt{Z"0} \\ 24 & $\W^+$ & \ttt{W+} & 34 & $\W'^+$ & \ttt{W'+} \\ 25 & $\H^0$ & \ttt{H0} & 35 & $\H'^0$ & \ttt{H'0} \\ 26 & & & 36 & $\A^0$ & \ttt{A0} \\ 27 & & & 37 & $\H^+$ & \ttt{H+} \\ 28 & $\reggeon$ & \ttt{reggeon} & 38 & $\eta_{\mrm{techni}}$ & \ttt{eta\_tech0} \\ 29 & $\pomeron$ & \ttt{pomeron} & 39 & $\L_{\Q}$ & \ttt{LQ} \\ 30 & & & 40 & $\R^0$ & \ttt{R0} \\ \hline \end{tabular} \end{center} \end{table} \item Free space. \\ The positions 41--80 are currently unused. In the future, they might come to be used, e.g. for supersymmetric partners of the particles above, or for some other kind of new physics. At the moment, they are at your disposal. \item Various special codes, Table \ref{t:codefour}. \\ In a Monte Carlo, it is always necessary to have codes that do not correspond to any specific particle, but are used to lump together groups of similar particles for decay treatment, or to specify generic decay products. These codes, which again are non-standard, are found between numbers 81 and 100. Several are not found in the event record, and therefore properly belong only to the KC group of codes. \begin{table}[ptb] \captive{Various special codes. \protect\label{t:codefour} } \\ \vspace{1ex} \begin{center} \begin{tabular}{|c|c|c|@{\protect\rule{0mm}{\tablinsep}}} \hline KF & Printed & Meaning \\ \hline 81 & \ttt{specflav} & Spectator flavour; used in decay-product listings \\ 82 & \ttt{rndmflav} & A random $\u$, $\d$, or $\s$ flavour; possible decay product \\ 83 & \ttt{phasespa} & Simple isotropic phase-space decay \\ 84 & \ttt{c-hadron} & Information on decay of generic charm hadron \\ 85 & \ttt{b-hadron} & Information on decay of generic bottom hadron \\ 86 & \ttt{t-hadron} & Information on decay of generic top hadron \\ 87 & \ttt{l-hadron} & Information on decay of generic low hadron \\ 88 & \ttt{h-hadron} & Information on decay of generic high hadron \\ 89 & \ttt{Wvirt} & Off-mass-shell $\W$ in weak decays of $\t$, $\lrm$, $\hrm$ or $\chi$ \\ 90 & \ttt{diquark} & Generic code for diquark colour information \\ 91 & \ttt{cluster} & Parton system in cluster fragmentation \\ 92 & \ttt{string} & Parton system in string fragmentation \\ 93 & \ttt{indep.} & Parton system in independent fragmentation \\ 94 & \ttt{CMshower} & Four-momentum of time-like showering system \\ 95 & \ttt{SPHEaxis} & Event axis found with \ttt{LUSPHE} \\ 96 & \ttt{THRUaxis} & Event axis found with \ttt{LUTHRU} \\ 97 & \ttt{CLUSjet} & Jet (cluster) found with \ttt{LUCLUS} \\ 98 & \ttt{CELLjet} & Jet (cluster) found with \ttt{LUCELL} \\ 99 & \ttt{table} & Tabular output from \ttt{LUTABU} \\ 100 & & \\ \hline \end{tabular} \end{center} \end{table} \item Diquark codes, Table \ref{t:codefive}. \\ A diquark made up of a quark with code $i$ and another with code $j$, where $i \geq j$, and with total spin $s$, is given the code \begin{equation} \mrm{KF} = 1000 i + 100 j + 2s + 1 ~, \end{equation} i.e. the tens position is left empty (cf. the baryon code below). Some of the most frequently used codes are listed in the table. All the lowest-lying spin 0 and 1 diquarks are included in the program. The corresponding KC code is 90, and it is mainly used to store colour charge. \begin{table}[ptb] \captive{Diquark codes. \protect\label{t:codefive} } \\ \vspace{1ex} \begin{center} \begin{tabular}{|c|c|c||c|c|c|@{\protect\rule{0mm}{\tablinsep}}} \hline KF & Name & Printed & KF & Name & Printed \\ \hline & & & 1103 & $\d\d_1$ & \ttt{dd\_1} \\ 2101 & $\u\d_0$ & \ttt{ud\_0} & 2103 & $\u\d_1$ & \ttt{ud\_1} \\ & & & 2203 & $\u\u_1$ & \ttt{uu\_1} \\ 3101 & $\s\d_0$ & \ttt{sd\_0} & 3103 & $\s\d_1$ & \ttt{sd\_1} \\ 3201 & $\s\u_0$ & \ttt{su\_0} & 3203 & $\s\u_1$ & \ttt{su\_1} \\ & & & 3303 & $\s\s_1$ & \ttt{ss\_1} \\ \hline \end{tabular} \end{center} \end{table} \item Meson codes, Tables \ref{t:codesixa} and \ref{t:codesixb}. \\ A meson made up of a quark with code $i$ and an antiquark with code $-j$, $j \neq i$, and with total spin $s$, is given the code \begin{equation} \mrm{KF} = \left\{ 100 \max(i,j) + 10 \min(i,j) + 2s + 1 \right\} \, \mrm{sign}(i-j) \, (-1)^{\max(i,j)} ~. \end{equation} Note the presence of an extra $-$ sign if the heaviest quark is a down-type one. This is in accordance with the particle--antiparticle distinction adopted in the 1986 Review of Particle Properties \cite{PDG86}. It means for example that a $\B$ meson contains a $\bbar$ antiquark rather than a $\b$ quark. The flavour-diagonal states are arranged in order of ascending mass. The standard rule of having the last digit of the form $2s+1$ is broken for the $\K_{\mrm{S}}^0$--$\K_{\mrm{L}}^0$ system, where it is 0, and this convention should carry over to mixed states in the $\B$ meson system. For higher multiplets with the same spin, $\pm$10000, $\pm$20000, etc., are added to provide the extra distinction needed. Some of the most frequently used codes are given below. The full lowest-lying pseudoscalar and vector multiplets are included in the program, Table \ref{t:codesixa}. \begin{table}[ptb] \captive{Meson codes, part 1. \protect\label{t:codesixa} } \\ \vspace{1ex} \begin{center} \begin{tabular}{|c|c|c||c|c|c|@{\protect\rule{0mm}{\tablinsep}}} \hline KF & Name & Printed & KF & Name & Printed \\ \hline 211 & $\pi^+$ & \ttt{pi+} & 213 & $\rho^+$ & \ttt{rho+} \\ 311 & $\K^0$ & \ttt{K0} & 313 & $\K^{*0}$ & \ttt{K*0} \\ 321 & $\K^+$ & \ttt{K+} & 323 & $\K^{*+}$ & \ttt{K*+} \\ 411 & $\D^+$ & \ttt{D+} & 413 & $\D^{*+}$ & \ttt{D*+} \\ 421 & $\D^0$ & \ttt{D0} & 423 & $\D^{*0}$ & \ttt{D*0} \\ 431 & $\D_s^+$ & \ttt{D\_s+} & 433 & $\D_{\s}^{*+}$ & \ttt{D*\_s+} \\ 511 & $\B^0$ & \ttt{B0} & 513 & $\B^{*0}$ & \ttt{B*0} \\ 521 & $\B^+$ & \ttt{B+} & 523 & $\B^{*+}$ & \ttt{B*+} \\ 531 & $\B_s^0$ & \ttt{B\_s0} & 533 & $\B_{\s}^{*0}$ & \ttt{B*\_s0} \\ 541 & $\B_c^+$ & \ttt{B\_c+} & 543 & $\B_{\c}^{*+}$ & \ttt{B*\_c+} \\ 111 & $\pi^0$ & \ttt{pi0} & 113 & $\rho^0$ & \ttt{rho0} \\ 221 & $\eta$ & \ttt{eta} & 223 & $\omega$ & \ttt{omega} \\ 331 & $\eta'$ & \ttt{eta'} & 333 & $\phi$ & \ttt{phi} \\ 441 & $\eta_{\c}$ & \ttt{eta\_c} & 443 & $\Jpsi$ & \ttt{J/psi} \\ 551 & $\eta_{\b}$ & \ttt{eta\_b} & 553 & $\Upsilon$ & \ttt{Upsilon} \\ 661 & $\eta_{\t}$ & \ttt{eta\_t} & 663 & $\Theta$ & \ttt{Theta} \\ 130 & $\K_{\mrm{L}}^0$ & \ttt{K\_L0} & & & \\ 310 & $\K_{\mrm{S}}^0$ & \ttt{K\_S0} & & & \\ \hline \end{tabular} \end{center} \end{table} Also the lowest-lying orbital angular momentum $L = 1$ mesons are included, Table \ref{t:codesixb}: one pseudovector multiplet obtained for total quark-spin 0 ($L = 1, S = 0 \Rightarrow J = 1$) and one scalar, one pseudovector and one tensor multiplet obtained for total quark-spin 1 ($L = 1, S = 1 \Rightarrow J = 0, 1$ or 2), where $J$ is what is conventionally called the spin $s$ of the meson. Any mixing between the two pseudovector multiplets is not taken into account. Please note that some members of these multiplets have still not been found, and are included here only based on guesswork. Even for known ones, the information on particles (mass, width, decay modes) is highly incomplete. Only two radial excitations are included, the $\psi' = \psi(2S)$ and $\Upsilon' = \Upsilon(2S)$. \begin{table}[ptb] \captive{Meson codes, part 2. \protect\label{t:codesixb} } \\ \vspace{1ex} \begin{center} \begin{tabular}{|c|c|c||c|c|c|@{\protect\rule{0mm}{\tablinsep}}} \hline KF & Name & Printed & KF & Name & Printed \\ \hline 10213 & $\b_1$ & \ttt{b\_1+} & 10211 & $\a_0^+$ & \ttt{a\_0+} \\ 10313 & $\K_1^0$ & \ttt{K\_10} & 10311 & $\K_0^{*0}$ & \ttt{K*\_00} \\ 10323 & $\K_1^+$ & \ttt{K\_1+} & 10321 & $\K_0^{*+}$ & \ttt{K*\_0+} \\ 10413 & $\D_1^+$ & \ttt{D\_1+} & 10411 & $\D_0^{*+}$ & \ttt{D*\_0+} \\ 10423 & $\D_1^0$ & \ttt{D\_10} & 10421 & $\D_0^{*0}$ & \ttt{D*\_00} \\ 10433 & $\D_{1 \s}^+$ & \ttt{D\_1s+} & 10431 & $\D_{0 \s}^{*+}$ & \ttt{D*\_0s+} \\ 10113 & $\b_1^0$ & \ttt{b\_10} & 10111 & $\a_0^0$ & \ttt{a\_00} \\ 10223 & $\hrm_1^0$ & \ttt{h\_10} & 10221 & $\f_0^0$ & \ttt{f\_00} \\ 10333 & $\hrm'^0_1$ & \ttt{h'\_10} & 10331 & $\f'^0_0$ & \ttt{f'\_00} \\ 10443 & $\hrm_{1 \c}^0$ & \ttt{h\_1c0} & 10441 & $\chi_{0 \c}^0$ & \ttt{chi\_0c0} \\ \hline 20213 & $\a_1^+$ & \ttt{a\_1+} & 215 & $\a_2^+$ & \ttt{a\_2+} \\ 20313 & $\K_1^{*0}$ & \ttt{K*\_10} & 315 & $\K_2^{*0}$ & \ttt{K*\_20} \\ 20323 & $\K_1^{*+}$ & \ttt{K*\_1+} & 325 & $\K_2^{*+}$ & \ttt{K*\_2+} \\ 20413 & $\D_1^{*+}$ & \ttt{D*\_1+} & 415 & $\D_2^{*+}$ & \ttt{D*\_2+} \\ 20423 & $\D_1^{*0}$ & \ttt{D*\_10} & 425 & $\D_2^{*0}$ & \ttt{D*\_20} \\ 20433 & $\D_{1 \s}^{*+}$ & \ttt{D*\_1s+} & 435 & $\D_{2 \s}^{*+}$ & \ttt{D*\_2s+} \\ 20113 & $\a_1^0$ & \ttt{a\_10} & 115 & $\a_2^0$ & \ttt{a\_20} \\ 20223 & $\f_1^0$ & \ttt{f\_10} & 225 & $\f_2^0$ & \ttt{f\_20} \\ 20333 & $\f'^0_1$ & \ttt{f'\_10} & 335 & $\f'^0_2$ & \ttt{f'\_20} \\ 20443 & $\chi_{1 \c}^0$ & \ttt{chi\_1c0} & 445 & $\chi_{2 \c}^0$ & \ttt{chi\_2c0} \\ \hline 30443 & $\psi'$ & \ttt{psi'} & & & \\ 30553 & $\Upsilon'$ & \ttt{Upsilon'} & & & \\ \hline \end{tabular} \end{center} \end{table} The corresponding meson KC codes, used for organizing mass and decay data, range between 101 and 240. \item Baryon codes, Table \ref{t:codeseven}. \\ A baryon made up of quarks $i$, $j$ and $k$, with $i \geq j \geq k$, and total spin $s$, is given the code \begin{equation} \mrm{KF} = 1000 i + 100 j + 10 k + 2s + 1 ~. \end{equation} An exception is provided by spin $1/2$ baryons made up of three different types of quarks, where the two lightest quarks form a spin-0 diquark ($\Lambda$-like baryons). Here the order of the $j$ and $k$ quarks is reversed, so as to provide a simple means of distinction to baryons with the lightest quarks in a spin-1 diquark ($\Sigma$-like baryons). For hadrons with heavy flavours, the root names are Lambda or Sigma for hadrons with two $\u$ or $\d$ quarks, Xi for those with one, and Omega for those without $\u$ or $\d$ quarks. Some of the most frequently used codes are given in Table \ref{t:codeseven}. The full lowest-lying spin $1/2$ and $3/2$ multiplets are included in the program. The corresponding KC codes, used for organizing mass and decay data, range between 301 and 400, with some slots still free. \begin{table}[ptb] \captive{Baryon codes. \protect\label{t:codeseven} } \\ \vspace{1ex} \begin{center} \begin{tabular}{|c|c|c||c|c|c|@{\protect\rule{0mm}{\tablinsep}}} \hline KF & Name & Printed & KF & Name & Printed \\ \hline & & & 1114 & $\Delta^-$ & \ttt{Delta-} \\ 2112 & $\n$ & \ttt{n0} & 2114 & $\Delta^0$ & \ttt{Delta0} \\ 2212 & $\p$ & \ttt{p+} & 2214 & $\Delta^+$ & \ttt{Delta+} \\ & & & 2224 & $\Delta^{++}$ & \ttt{Delta++} \\ 3112 & $\Sigma^-$ & \ttt{Sigma-} & 3114 & $\Sigma^{*-}$ & \ttt{Sigma*-} \\ 3122 & $\Lambda^0$ & \ttt{Lambda0} & & & \\ 3212 & $\Sigma^0$ & \ttt{Sigma0} & 3214 & $\Sigma^{*0}$ & \ttt{Sigma*0} \\ 3222 & $\Sigma^+$ & \ttt{Sigma+} & 3224 & $\Sigma^{*+}$ & \ttt{Sigma*+} \\ 3312 & $\Xi^-$ & \ttt{Xi-} & 3314 & $\Xi^{*-}$ & \ttt{Xi*-} \\ 3322 & $\Xi^0$ & \ttt{Xi0} & 3324 & $\Xi^{*0}$ & \ttt{Xi*0} \\ & & & 3334 & $\Omega^-$ & \ttt{Omega-} \\ 4112 & $\Sigma_{\c}^0$ & \ttt{Sigma\_c0} & 4114 & $\Sigma_{\c}^{*0}$ & \ttt{Sigma*\_c0} \\ 4122 & $\Lambda_{\c}^+$ & \ttt{Lambda\_c+} & & & \\ 4212 & $\Sigma_{\c}^+$ & \ttt{Sigma\_c+} & 4214 & $\Sigma_{\c}^{*+}$ & \ttt{Sigma*\_c+} \\ 4222 & $\Sigma_{\c}^{++}$ & \ttt{Sigma\_c++} & 4224 & $\Sigma_{\c}^{*++}$ & \ttt{Sigma*\_c++} \\ 4132 & $\Xi_{\c}^0$ & \ttt{Xi\_c0} & & & \\ 4312 & $\Xi'^0_{\c}$ & \ttt{Xi'\_c0} & 4314 & $\Xi_{\c}^{*0}$ & \ttt{Xi*\_c0} \\ 4232 & $\Xi_{\c}^+$ & \ttt{Xi\_c+} & & & \\ 4322 & $\Xi'^+_{\c}$ & \ttt{Xi'\_c+} & 4324 & $\Xi_{\c}^{*+}$ & \ttt{Xi*\_c+} \\ 4332 & $\Omega_{\c}^0$ & \ttt{Omega\_c0} & 4334 & $\Omega_{\c}^{*0}$ & \ttt{Omega*\_c0} \\ 5112 & $\Sigma_{\b}^-$ & \ttt{Sigma\_b-} & 5114 & $\Sigma_{\b}^{*-}$ & \ttt{Sigma*\_b-} \\ 5122 & $\Lambda_{\b}^0$ & \ttt{Lambda\_b0} & & & \\ 5212 & $\Sigma_{\b}^0$ &\ttt{Sigma\_b0} & 5214 & $\Sigma_{\b}^{*0}$ & \ttt{Sigma*\_b0} \\ 5222 & $\Sigma_{\b}^+$ & \ttt{Sigma\_b+} & 5224 & $\Sigma_{\b}^{*+}$ & \ttt{Sigma*\_b+} \\ \hline \end{tabular} \end{center} \end{table} \item Diffractive states, Table \ref{t:codeeight}. \\ These codes are not standard ones: they have been defined by analogy to be used for denoting diffractive states in {\Py}, as part of the event history. The first two or three digits give flavour content, while the last one is 0, to denote the somewhat unusual character of the code. Only a few codes have been introduced; depending on circumstances these also have to double up for other diffractive states. \begin{table}[ptb] \captive{Diffractive state codes. \protect\label{t:codeeight} } \\ \vspace{1ex} \begin{center} \begin{tabular}{|c|c|c|@{\protect\rule{0mm}{\tablinsep}}} \hline KF & Printed & Meaning \\ \hline 110 & \ttt{rho\_diff0} & Diffractive $\pi^0 / \rho^0 / \gamma$ state \\ 210 & \ttt{pi\_diffr+} & Diffractive $\pi^+$ state \\ 220 & \ttt{omega\_di0} & Diffractive $\omega$ state \\ 330 & \ttt{phi\_diff0} & Diffractive $\phi$ state \\ 440 & \ttt{J/psi\_di0} & Diffractive $\Jpsi$ state \\ 2110 & \ttt{n\_diffr} & Diffractive $\n$ state \\ 2210 & \ttt{p\_diffr+} & Diffractive $\p$ state \\ \hline \end{tabular} \end{center} \end{table} \item Free compressed codes. The positions 401--500 of mass and decay arrays are left open. Here a user may map any new kind of particle from the ordinary KF codes, which probably are above 10000, into a more manageable KC range for mass and decay data information. The mapping must be implemented in the \ttt{LUCOMP} function. \end{Enumerate} \subsection{The Event Record} \label{ss:evrec} Each new event generated is in its entirety stored in the common block \ttt{LUJETS}, which thus forms the event record. Here each jet or particle that appears at some stage of the fragmentation or decay chain will occupy one line in the matrices. The different components of this line will tell which jet/particle it is, from where it originates, its present status (fragmented/decayed or not), its momentum, energy and mass, and the space--time position of its production vertex. Note that \ttt{K(I,3)}--\ttt{K(I,5)} and the \ttt{P} and \ttt{V} vectors may take special meaning for some specific applications (e.g. sphericity or cluster analysis), as described in those connections. The event history information stored in \ttt{K(I,3)}--\ttt{K(I,5)} should not be taken too literally. In the particle decay chains, the meaning of a mother is well-defined, but the fragmentation description is more complicated. The primary hadrons produced in string fragmentation come from the string as a whole, rather than from an individual parton. Even when the string is not included in the history (see \ttt{MSTU(16)}), the pointer from hadron to parton is deceptive. For instance, in a $\q\g\qbar$ event, those hadrons are pointing towards the $\q$ ($\qbar$) parton that were produced by fragmentation from that end of the string, according to the random procedure used in the fragmentation routine. No particles point to the $\g$. This assignment seldom agrees with the visual impression, and is not intended to. The common block \ttt{LUJETS} has expanded with time, and can now house 4000 entries. This figure may seem ridiculously large, but actually the previous limit of 2000 was often reached in studies of high-$\pT$ processes at the LHC and SSC. This is because the event record contains not only the final particles, but also all intermediate partons and hadrons, which subsequenty showered, fragmented or decayed. Included are also a wealth of photons coming from $\pi^0$ decays; the simplest way of reducing the size of the event record is actually to switch off $\pi^0$ decays by \ttt{MDCY(LUCOMP(111),1)=0}. Also note that some routines, such as \ttt{LUCLUS} and \ttt{LUCELL}, use memory after the event record proper as a working area. Still, to change the size of the common block, upwards or downwards, is easy: just do a global substitute in the common block and change the \ttt{MSTU(4)} value to the new number. If more than 10000 lines are to be used, the packing of colour information should also be changed, see \ttt{MSTU(5)}. \drawbox{COMMON/LUJETS/N,K(4000,5),P(4000,5),V(4000,5)}\label{p:LUJETS} \begin{entry} \itemc{Purpose:} to contain the event record, i.e. the complete list of all partons and particles in the current event. \iteme{N :}\label{p:N} number of lines in the \ttt{K}, \ttt{P} and \ttt{V} matrices occupied by the current event. \ttt{N} is continuously updated as the definition of the original configuration and the treatment of fragmentation and decay proceed. In the following, the individual parton/particle number, running between 1 and \ttt{N}, is called \ttt{I}. \iteme{K(I,1) :}\label{p:K} status code KS, which gives the current status of the parton/particle stored in the line. The ground rule is that codes 1--10 correspond to currently existing partons/particles, while larger codes contain partons/particles which no longer exist, or other kinds of event information. \begin{subentry} \iteme{= 0 :} empty line. \iteme{= 1 :} an undecayed particle or an unfragmented jet, the latter being either a single jet or the last one of a jet system. \iteme{= 2 :} an unfragmented jet, which is followed by more jets in the same colour-singlet jet system. \iteme{= 3 :} an unfragmented jet with special colour flow information stored in \ttt{K(I,4)} and \ttt{K(I,5)}, such that adjacent partons along the string need not follow each other in the event record. \iteme{= 4 :} a particle which could have decayed, but did not within the allowed volume around the original vertex. \iteme{= 5 :} a particle which is to be forced to decay in the next \ttt{LUEXEC} call, in the vertex position given (this code is only set by user intervention). \iteme{= 11 :} a decayed particle or a fragmented jet, the latter being either a single jet or the last one of a jet system, cf. \ttt{=1}. \iteme{= 12 :} a fragmented jet, which is followed by more jets in the same colour-singlet jet system, cf. \ttt{=2}. Further, a $\B$ meson which decayed as a $\br{\B}$ one, or vice versa, because of $\B$--$\br{\B}$ mixing, is marked with this code rather than \ttt{=11}. \iteme{= 13 :} a jet which has been removed when special colour flow information has been used to rearrange a jet system, cf. \ttt{=3}. \iteme{= 14 :} a parton which has branched into further partons, with special colour-flow information provided, cf. \ttt{=3}. \iteme{= 15 :} a particle which has been forced to decay (by user intervention), cf. \ttt{=5}. \iteme{= 21 :} documentation lines used to give a compressed story of the event at the beginning of the event record. \iteme{= 31 :} lines with information on sphericity, thrust or cluster search. \iteme{= 32 :} tabular output, as generated by \ttt{LUTABU}. \iteme{= 41 :} junction (currently not fully implemented). \iteme{< 0 :} these codes are never used by the program, and are therefore usually not affected by operations on the record, such as \ttt{LUROBO}, \ttt{LULIST} and event-analysis routines (the exception is some \ttt{LUEDIT} calls, where lines are moved but not deleted). Such codes may therefore be useful in some connections. \end{subentry} \iteme{K(I,2) :} parton/particle KF code, as described in section \ref{ss:codes}. \iteme{K(I,3) :} line number of parent particle or jet, where known, otherwise 0. Note that the assignment of a particle to a given jet in a jet system is unphysical, and what is given there is only related to the way the event was generated. \iteme{K(I,4) :} normally the line number of the first daughter; it is 0 for an undecayed particle or unfragmented jet. For \ttt{K(I,1) = 3, 13} or \ttt{14}, instead, it contains special colour-flow information (for internal use only) of the form \\ \ttt{K(I,4)} = 200000000*MCFR + 100000000*MCTO + 10000*ICFR + ICTO, \\ where ICFR and ICTO give the line numbers of the partons from which the colour comes and to where it goes, respectively; MCFR and MCTO originally are 0 and are set to 1 when the corresponding colour connection has been traced in the \ttt{LUPREP} rearrangement procedure. (The packing may be changed with \ttt{MSTU(5)}.) The `from' colour position may indicate a parton which branched to produce the current parton, or a parton created together with the current parton but with matched anticolour, while the `to' normally indicates a parton that the current parton branches into. Thus, for setting up an initial colour configuration, it is normally only the `from' part that is used, while the `to' part is added by the program in a subsequent call to parton-shower evolution (for final-state radiation; it is the other way around for initial-state radiation). {\bf Note:} normally most users never have to worry about the exact rules for colour-flow storage, since this is used mainly for internal purposes. However, when it is necessary to define this flow, it is recommended to use the \ttt{LUJOIN} routine, since it is likely that this would reduce the chances of making a mistake. \iteme{K(I,5) :} normally the line number of the last daughter; it is 0 for an undecayed particle or unfragmented jet. For \ttt{K(I,1) = 3, 13} or \ttt{14}, instead, it contains special colour-flow information (for internal use only) of the form \\ \ttt{K(I,5)} = 200000000*MCFR + 100000000*MCTO + 10000*ICFR + ICTO, \\ where ICFR and ICTO give the line numbers of the partons from which the anticolour comes and to where it goes, respectively; MCFR and MCTO originally are 0 and are set to 1 when the corresponding colour connection has been traced in the \ttt{LUPREP} rearrangement procedure. For further discussion, see \ttt{K(I,4)}. \iteme{P(I,1) :}\label{p:P} $p_x$, momentum in the $x$ direction, in GeV/$c$. \iteme{P(I,2) :} $p_y$, momentum in the $y$ direction, in GeV/$c$. \iteme{P(I,3) :} $p_z$, momentum in the $z$ direction, in GeV/$c$. \iteme{P(I,4) :} $E$, energy, in GeV. \iteme{P(I,5) :} $m$, mass, in GeV/$c^2$. In parton showers, with space-like virtualities, i.e. where $Q^2 = - m^2 > 0$, one puts \ttt{P(I,5)}$ = -Q$. \iteme{V(I,1) :}\label{p:V} $x$ position of production vertex, in mm. \iteme{V(I,2) :} $y$ position of production vertex, in mm. \iteme{V(I,3) :} $z$ position of production vertex, in mm. \iteme{V(I,4) :} time of production, in mm/$c$ ($\approx 3.33 \times 10^{-12}$ s). \iteme{V(I,5) :} proper lifetime of particle, in mm/$c$ ($\approx 3.33 \times 10^{-12}$ s). If the particle is not expected to decay, \ttt{V(I,5)=0}. A line with \ttt{K(I,1)=4}, i.e. a particle that could have decayed, but did not within the allowed region, has the proper non-zero \ttt{V(I,5)}. In the absence of electric or magnetic fields, or other disturbances, the decay vertex \ttt{VP} of an unstable particle may be calculated as \\ \ttt{VP(j) = V(I,j) + V(I,5)*P(I,j)/P(I,5)}, \ttt{j} = 1--4. \end{entry} \subsection{How The Event Record Works} The event record is the main repository for information about an event. In the generation chain, it is used as a `scoreboard' for what has already been done and what remains to be done. This information can be studied by you, to access information not only about the final state, but also about what came before. \subsubsection{A simple example} The example of section \ref{ss:JETstarted} may help to clarify what is going on. When \ttt{LU2ENT} is called to generate a $\q\qbar$ pair, the quarks are stored in lines 1 and 2 of the event record, respectively. Colour information is set to show that they belong together as a colour singlet. The counter \ttt{N} is also updated to the value of 2. At no stage is the previously generated event removed. Lines 1 and 2 are overwritten, but lines 3 onwards still contain whatever may have been there before. This does not matter, since \ttt{N} indicates where the `real' record ends. As \ttt{LUEXEC} is called, explicitly by you or indirectly by \ttt{LU2ENT}, the first entry is considered and found to be the first jet of a system. Therefore the second entry is also found, and these two together form a jet system, which may be allowed to fragment. The `string' that fragments is put in line 3 and the fragmentation products in lines 4 through 10 (in this particular case). At the same time, the $\q$ and $\qbar$ in the first two lines are marked as having fragmented, and the same for the string. At this stage, \ttt{N} is 10. Internally there is another counter with the value 2, which indicates how far down in the record the event has been studied. This second counter is gradually increased by one. If the entry in the corresponding line can fragment or decay, then fragmentation or decay is perfomed. The fragmentation/decay products are added at the end of the event record, and \ttt{N} is updated accordingly. The entry is then also marked as having been treated. For instance, when line 3 is considered, the `string' entry of this line is seen to have been fragmented, and no action is taken. Line 4, a $\rho^+$, is allowed to decay to $\pi^+ \pi^0$; the decay products are stored in lines 11 and 12, and line 4 is marked as having decayed. Next, entry 5 is allowed to decay. The entry in line 6, $\pi^+$, is a stable particle (by default) and is therefore passed by without any action being taken. In the beginning of the process, entries are usually unstable, and \ttt{N} grows faster than the second counter of treated entries. Later on, an increasing fraction of the entries are stable end products, and the r\^oles are now reversed, with the second counter growing faster. When the two coincide, the end of the record has been reached, and the process can be stopped. All unstable objects have now been allowed to fragment or decay. They are still present in the record, so as to simplify the tracing of the history. Notice that \ttt{LUEXEC} could well be called a second time. The second counter would then start all over from the beginning, but slide through until the end without causing any action, since all objects that can be treated already have been. Unless some of the relevant switches were changed meanwhile, that is. For instance, if $\pi^0$ decays were switched off the first time around but on the second, all the $\pi^0$'s found in the record would be allowed to decay in the second call. A particle once decayed is not `undecayed', however, so if the $\pi^0$ is put back stable and \ttt{LUEXEC} is called a third time, nothing will happen. \subsubsection{Applications to PYTHIA} \label{sss:PYrecord} In a full-blown event generated with {\Py}, the usage of \ttt{LUJETS} is more complicated, although the general principles survive. \ttt{LUJETS} is used extensively both by the {\Py} and the {\Je} routines; indeed it provides the bridge that allows the general utility routines in {\Je} to be used also for {\Py} events. The {\Py} event listing begins (optionally) with a few lines of event summary, specific to the hard process simulated and thus not described in the overview above. These specific parts are covered in the following. In most instances, only the partons and particles actually produced are of interest. For \ttt{MSTP(125)=0}, the event record starts off with the parton configuration existing after hard interaction, initial- and final-state radiation, multiple interactions and beam remnants have been considered. The partons are arranged in colour singlet clusters, ordered as required for string fragmentation. Also photons and leptons produced as part of the hard interaction (e.g. from $\q\qbar \to \g \gamma$ or $\u\ubar \to \Z^0 \to \ee$) appear in this part of the event record. These original entries appear with pointer \ttt{K(I,3)=0}, whereas the products of the subsequent fragmentation and decay have \ttt{K(I,3)} numbers pointing back to the line of the parent. The standard documentation, obtained with \ttt{MSTP(125)=1}, includes a few lines at the beginning of the event record, which contain a brief summary of the process that has taken place. The number of lines used depends on the nature of the hard process and is stored in \ttt{MSTI(4)} for the current event. These lines all have \ttt{K(I,1)=21}. For all processes, lines 1 and 2 give the two incoming hadrons. When listed with \ttt{LULIST}, these two lines will be separated from subsequent ones by a sequence of `\ttt{======}' signs, to improve readability. For diffractive and elastic events, the two outgoing states in lines 3 and 4 complete the list. Otherwise, lines 3 and 4 contain the two partons that initiate the two initial-state parton showers, and 5 and 6 the end products of these showers, i.e. the partons that enter the hard interaction. With initial-state radiation switched off, lines 3 and 5 and lines 4 and 6 coincide. For a simple $2 \to 2$ hard scattering, lines 7 and 8 give the two outgoing partons/particles from the hard interaction, before any final-state radiation. For $2 \to 2$ processes proceeding via an intermediate resonance such as $\gammaZ$, $\W^{\pm}$ or $\H^0$, the resonance is found in line 7 and the two outgoing partons/particles in 8 and 9. In some cases one of these may be a resonance in its own right, or both of them, so that further pairs of lines are added for subsequent decays. If the decay of a given resonance has been switched off, then no decay products are listed either in this initial summary or in the subsequent ordinary listing. Whenever partons are listed, they are assumed to be on the mass shell for simplicity. The fact that effective masses may be generated by initial- and final-state radiation is taken into account in the actual parton configuration that is allowed to fragment, however. A special case is provided by $\W^+ \W^-$ or $\Z^0 \Z^0$ fusion to an $\H^0$. Then the virtual $\W$'s or $\Z$'s are shown in lines 7 and 8, the $\H^0$ in line 9, and the two recoiling quarks (that emitted the bosons) in 10 and 11, followed by the Higgs decay products. Since the $\W$'s and $\Z$'s are space-like, what is actually listed as the mass for them is $-\sqrt{-m^2}$. The listing of the event documentation closes with another line made up of `\ttt{======}' signs. A few examples may help clarify the picture. For a single diffractive event $\p \pbar \to \p_{\mrm{diffr}} \pbar$, the event record will start with \\ \verb& I K(I,1) K(I,2) K(I,3) & comment \\ \verb& 1 21 2212 0 & incoming $\p$ \\ \verb& 2 21 -2212 0 & incoming $\pbar$ \\ \verb&========================= & not part of record; appears in listings \\ \verb& 3 21 27 1 & outgoing $\p_{\mrm{diffr}}$ \\ \verb& 4 21 -2212 2 & outgoing $\pbar$ \\ \verb&========================= & again not part of record The typical QCD $2 \to 2$ process would be \\ \verb& I K(I,1) K(I,2) K(I,3) & comment \\ \verb& 1 21 2212 0 & incoming $\p$ \\ \verb& 2 21 -2212 0 & incoming $\pbar$ \\ \verb&========================= & \\ \verb& 3 21 2 1 & $\u$ picked from incoming $\p$ \\ \verb& 4 21 -1 2 & $\dbar$ picked from incoming $\pbar$ \\ \verb& 5 21 21 3 & $\u$ evolved to $\g$ at hard scattering \\ \verb& 6 21 -1 4 & still $\dbar$ at hard scattering \\ \verb& 7 21 21 0 & outgoing $\g$ from hard scattering \\ \verb& 8 21 -1 0 & outgoing $\dbar$ from hard scattering \\ \verb&========================= & Note that, where well defined, the \ttt{K(I,3)} code does contain information as to which side the different partons come from, e.g. above the gluon in line 5 points back to the $\u$ in line 3, which points back to the proton in line 1. In the example above, it would have been possible to associate the scattered g in line 7 with the incoming one in line 5, but this is not possible in the general case, consider e.g. $\g \g \to \g \g$. As a final example, $\W^+\W^-$ fusion to an $\H^0$ in process 8 (not process 124, which is lengthier) might look like \\ \verb& I K(I,1) K(I,2) K(I,3) & comment \\ \verb& 1 21 2212 0 & first incoming $\p$ \\ \verb& 2 21 2212 0 & second incoming $\p$ \\ \verb&========================= & \\ \verb& 3 21 2 1 & $\u$ picked from first $\p$ \\ \verb& 4 21 21 2 & $\g$ picked from second $\p$ \\ \verb& 5 21 2 3 & still $\u$ after initial-state radiation \\ \verb& 6 21 -4 4 & $\g$ evolved to $\cbar$ \\ \verb& 7 21 24 5 & space-like $\W^+$ emitted by $\u$ quark \\ \verb& 8 21 -24 6 & space-like $\W^-$ emitted by $\cbar$ quark \\ \verb& 9 21 25 0 & Higgs produced by $\W^+ \W^-$ fusion \\ \verb&10 21 1 5 & $\u$ turned into $\d$ by emission of $\W^+$ \\ \verb&11 21 -3 6 & $\cbar$ turned into $\sbar$ by emission of $\W^-$ \\ \verb&12 21 23 9 & first $\Z^0$ coming from decay of $\H^0$ \\ \verb&13 21 23 9 & second $\Z^0$ coming from decay of $\H^0$ \\ \verb&14 21 12 12 & $\nu_{\e}$ from first $\Z^0$ decay \\ \verb&15 21 -12 12 & $\br{\nu}_{\e}$ from first $\Z^0$ decay \\ \verb&16 21 5 13 & $\b$ quark from second $\Z^0$ decay \\ \verb&17 21 -5 13 & $\bbar$ antiquark from second $\Z^0$ decay \\ \verb&========================= & After these lines with the initial information, the event record looks the same as for \ttt{MSTP(125)=0}, i.e. first comes the parton configuration to be fragmented and, after another separator line `\ttt{======}' in the output (but not the event record), the products of subsequent fragmentation and decay chains. The \ttt{K(I,3)} pointers for the partons, as well as leptons and photons produced in the hard interaction, are now pointing towards the documentation lines above, however. In particular, beam remnants point to 1 or 2, depending on which side they belong to, and partons emitted in the initial-state parton showers point to 3 or 4. In the second example above, the partons produced by final-state radiation will be pointing back to 7 and 8; as usual, it should be remembered that a specific assignment to 7 or 8 need not be unique. For the third example, final-state radiation partons will come both from partons 10 and 11 and from partons 16 and 17, and additionally there will be a neutrino--antineutrino pair pointing to 14 and 15. The extra pairs of partons that are generated by multiple interactions do not point back to anything, i.e. they have \ttt{K(I,3)=0}. There exists a third documentation option, \ttt{MSTP(125)=2}. Here the history of initial- and final-state parton branchings may be traced, including all details on colour flow. This information has not been optimized for user-friendliness, and cannot be recommended for general usage. With this option, the initial documentation lines are the same. They are followed by blank lines, \ttt{K(I,1)=0}, up to line 20 (can be changed in \ttt{MSTP(126)}). From line 21 onwards each parton with \ttt{K(I,1)=} 3, 13 or 14 appears with special colour-flow information in the \ttt{K(I,4)} and \ttt{K(I,5)} positions. For an ordinary $2 \to 2$ scattering, the two incoming partons at the hard scattering are stored in lines 21 and 22, and the two outgoing in 23 and 24. The colour flow between these partons has to be chosen according to the proper relative probabilities in cases when many alternatives are possible, see section \ref{sss:QCDjetclass}. If there is initial-state radiation, the two partons in lines 21 and 22 are copied down to lines 25 and 26, from which the initial-state showers are reconstructed backwards step by step. The branching history may be read by noting that, for a branching $a \to b c$, the \ttt{K(I,3)} codes of $b$ and $c$ point towards the line number of $a$. Since the showers are reconstructed backwards, this actually means that parton $b$ would appear in the listing before parton $a$ and $c$, and hence have a pointer to a position below itself in the list. Associated time-like partons $c$ may initiate time-like showers, as may the partons of the hard scattering. Again a showering parton or pair of partons will be copied down towards the end of the list and allowed to undergo successive branchings $c \to d e$, with $d$ and $e$ pointing towards $c$. The mass of time-like partons is properly stored in \ttt{P(I,5)}; for space-like partons $-\sqrt{-m^2}$ is stored instead. After this section, containing all the branchings, comes the final parton configuration, properly arranged in colour, followed by all subsequent fragmentation and decay products, as usual. \subsection{The HEPEVT Standard} \label{ss:HEPEVT} A set of common blocks was developed and agreed on within the framework of the 1989 LEP physics study, see \cite{Sjo89}. This standard defines an event record structure which should make the interfacing of different event generators much simpler. It would be a major work to rewrite {\PyJe} to agree with this standard event record structure. More importantly, the standard only covers quantities which can be defined unambiguously, i.e. which are independent of the particular program used. There are thus no provisions for the need for colour-flow information in models based on string fragmentation, etc., so the standard common blocks would anyway have to be supplemented with additional event information. For the moment, the adopted approach is therefore to retain the \ttt{LUJETS} event record, but supply a routine \ttt{LUHEPC} which can convert to or from the standard event record. Owing to a somewhat different content in the two records, some ambiguities do exist in the translation procedure. \ttt{LUHEPC} has therefore to be used with some judgment. In this section, the new standard event structure is first presented, i.e. the most important points in \cite{Sjo89} are recapitulated. Thereafter the conversion routine is described, with particular attention to ambiguities and limitations. The standard event record is stored in two common blocks. The second of these is specifically intended for spin information. Since {\Je} never (explicitly) makes use of spin information, this latter common block is not addressed here. A third common block for colour flow information has been discussed, but never formalized. In order to make the components of the standard more distinguishable in user programs, the three characters \ttt{HEP} (for High Energy Physics) have been chosen to be a part of all names. Originally it was not specified whether real variables should be in single or double precision. At the time, this meant that single precision became the default choice, but since then the trend has been towards increasing precision. In connection with the 1995 LEP~2 workshop, it was therefore agreed to adopt \ttt{DOUBLE PRECISION} real variables as part of the standard. \drawboxfour{~PARAMETER (NMXHEP=2000)} {~COMMON/HEPEVT/NEVHEP,NHEP,ISTHEP(NMXHEP),IDHEP(NMXHEP),} {\&JMOHEP(2,NMXHEP),JDAHEP(2,NMXHEP),PHEP(5,NMXHEP),VHEP(4,NMXHEP)} {~DOUBLE PRECISION PHEP, VHEP} \label{p:HEPEVT}\begin{entry} \itemc{Purpose:} to contain an event record in a Monte Carlo-independent format. \iteme{NMXHEP:} maximum numbers of entries (partons/particles) that can be stored in the common block. The default value of 2000 can be changed via the parameter construction. In the translation, it is checked that this value is not exceeded. \iteme{NEVHEP:} is normally the event number, but may have special meanings, according to the description below: \begin{subentry} \iteme{> 0 :} event number, sequentially increased by 1 for each call to the main event generation routine, starting with 1 for the first event generated. \iteme{= 0 :} for a program which does not keep track of event numbers, as {\Je}. \iteme{= -1 :} special initialization record; not used by {\Je}. \iteme{= -2 :} special final record; not used by {\Je}. \end{subentry} \iteme{NHEP:} the actual number of entries stored in the current event. These are found in the first \ttt{NHEP} positions of the respective arrays below. Index \ttt{IHEP}, 1$\leq$\ttt{IHEP}$\leq$\ttt{NHEP}, is used below to denote a given entry. \iteme{ISTHEP(IHEP):} status code for entry \ttt{IHEP}, with the following meanings: \begin{subentry} \iteme{= 0 :} null entry. \iteme{= 1 :} an existing entry, which has not decayed or fragmented. This is the main class of entries, which represents the `final state' given by the generator. \iteme{= 2 :} an entry which has decayed or fragmented and is therefore not appearing in the final state, but is retained for event history information. \iteme{= 3 :} a documentation line, defined separately from the event history. This could include the two incoming reacting particles, etc. \iteme{= 4 - 10 :} undefined, but reserved for future standards. \iteme{= 11 - 200 :} at the disposal of each model builder for constructs specific to his program, but equivalent to a null line in the context of any other program. \iteme{= 201 - :} at the disposal of users, in particular for event tracking in the detector. \end{subentry} \iteme{IDHEP(IHEP) :} particle identity, according to the PDG standard. The four additional codes 91--94 have been introduced to make the event history more legible, see section \ref{ss:codes} and the \ttt{MSTU(16)} description. \iteme{JMOHEP(1,IHEP) :} pointer to the position where the mother is stored. The value is 0 for initial entries. \iteme{JMOHEP(2,IHEP) :} pointer to position of second mother. Normally only one mother exists, in which case the value 0 is to be used. In {\Je}, entries with codes 91--94 are the only ones to have two mothers. The flavour contents of these objects, as well as details of momentum sharing, have to be found by looking at the mother partons, i.e. the two partons in positions \ttt{JMOHEP(1,IHEP)} and \ttt{JMOHEP(2,IHEP)} for a cluster or a shower system, and the range \ttt{JMOHEP(1,IHEP)}--\ttt{JMOHEP(2,IHEP)} for a string or an independent fragmentation parton system. \iteme{JDAHEP(1,IHEP) :} pointer to the position of the first daughter. If an entry has not decayed, this is 0. \iteme{JDAHEP(2,IHEP) :} pointer to the position of the last daughter. If an entry has not decayed, this is 0. It is assumed that daughters are stored sequentially, so that the whole range \ttt{JDAHEP(1,IHEP)}--\ttt{JDAHEP(2,IHEP)} contains daughters. This variable should be set also when only one daughter is present, as in $\K^0 \to \K_{\mrm{S}}^0$ decays, so that looping from the first daughter to the last one works transparently. Normally daughters are stored after mothers, but in backwards evolution of initial-state radiation the opposite may appear, i.e. that mothers are found below the daughters they branch into. Also, the two daughters then need not appear one after the other, but may be separated in the event record. \iteme{PHEP(1,IHEP) :} momentum in the $x$ direction, in GeV/$c$. \iteme{PHEP(2,IHEP) :} momentum in the $y$ direction, in GeV/$c$. \iteme{PHEP(3,IHEP) :} momentum in the $z$ direction, in GeV/$c$. \iteme{PHEP(4,IHEP) :} energy, in GeV. \iteme{PHEP(5,IHEP) :} mass, in GeV/$c^2$. For space-like partons, it is allowed to use a negative mass, according to \ttt{PHEP(5,IHEP)}$ = -\sqrt{-m^2}$. \iteme{VHEP(1,IHEP) :} production vertex $x$ position, in mm. \iteme{VHEP(2,IHEP) :} production vertex $y$ position, in mm. \iteme{VHEP(3,IHEP) :} production vertex $z$ position, in mm. \iteme{VHEP(4,IHEP) :} production time, in mm/$c$ ($\approx 3.33 \times 10^{-12}$ s). \end{entry} \boxsep This completes the brief description of the standard. In {\Je}, the routine \ttt{LUHEPC} is provided as an interface. \drawbox{CALL LUHEPC(MCONV)}\label{p:LUHEPC} \begin{entry} \itemc{Purpose:} to convert between the \ttt{LUJETS} event record and the \ttt{HEPEVT} event record. \iteme{MCONV :} direction of conversion. \begin{subentry} \iteme{= 1 :} translates the current \ttt{LUJETS} record into the \ttt{HEPEVT} one, while leaving the original \ttt{LUJETS} one unaffected. \iteme{= 2 :} translates the current \ttt{HEPEVT} record into the \ttt{LUJETS} one, while leaving the original \ttt{HEPEVT} one unaffected. \end{subentry} \end{entry} \boxsep The conversion of momenta is trivial: it is just a matter of exchanging the order of the indices. The vertex information is but little more complicated; the extra fifth component present in \ttt{LUJETS} can be easily reconstructed from other information for particles which have decayed. (Some of the advanced features made possible by this component, such as the possibility to consider decays within expanding spatial volumes in subsequent \ttt{LUEXEC} calls, cannot be used if the record is translated back and forth, however.) Also, the particle codes \ttt{K(I,2)} and \ttt{IDHEP(I)} are identical, since they are both based on the PDG codes. The remaining, non-trivial areas deal with the status codes and the event history. In moving from \ttt{LUJETS} to \ttt{HEPEVT}, information on colour flow is lost. On the other hand, the position of a second mother, if any, has to be found; this only affects lines with \ttt{K(I,2)=} 91--94. Also, for lines with \ttt{K(I,1)=} 13 or 14, the daughter pointers have to be found. By and large, however, the translation from \ttt{LUJETS} to \ttt{HEPEVT} should cause little problem, and there should never be any need for user intervention. (We assume that {\Je} is run with the default \ttt{MSTU(16)=1}, otherwise some discrepancies with respect to the proposed standard event history description will be present.) In moving from \ttt{HEPEVT} to \ttt{LUJETS}, information on a second mother is lost. Any codes \ttt{IDHEP(I)} not equal to 1, 2 or 3 are translated into \ttt{K(I,1)=0}, and so all entries with \ttt{K(I,1)}$\geq 30$ are effectively lost in a translation back and forth. All entries with \ttt{IDHEP(I)=2} are translated into \ttt{K(I,1)=11}, and so entries of type \ttt{K(I,1) = 12, 13, 14} or \ttt{15} are never found. There is thus no colour-flow information available for partons which have fragmented. For partons with \ttt{IDHEP(I)=1}, i.e. which have not fragmented, an attempt is made to subdivide the partonic system into colour singlets, as required for subsequent string fragmentation. To this end, it is assumed that partons are stored sequentially along strings. Normally, a string would then start at a $\q$ ($\qbar$) or $\qbar\qbar$ ($\q\q$) entry, cover a number of intermediate gluons, and end at a $\qbar$ ($\q$) or $\q\q$ ($\qbar\qbar$) entry. Particles could be interspersed in this list with no adverse effects, i.e. a $\u-\g-\gamma-\ubar$ sequence would be interpreted as a $\u-\g-\ubar$ string plus an additional photon. A closed gluon loop would be assumed to be made up of a sequential listing of the gluons, with the string continuing from the last gluon up back to the first one. Contrary to the previous, open string case, the appearance of any particle but a gluon would therefore signal the end of the gluon loop. For example, a $\g-\g-\g-\g$ sequence would be interpreted as one single four-gluon loop, while a $\g-\g-\gamma-\g-\g$ sequence would be seen as composed of two 2-gluon systems. If these interpretations, which are not unique, are not to your liking, it is up to you to correct them, e.g. by using \ttt{LUJOIN} to tell exactly which partons should be joined, in which sequence, to give a string. Calls to \ttt{LUJOIN} (or the equivalent) are also necessary if \ttt{LUSHOW} is to be used to have some partons develop a shower. For practical applications, one should note that {\Je} $\ee$ events, which have been allowed to shower but not to fragment, do have partons arranged in the order assumed above, so that a translation to \ttt{HEPEVT} and back does not destroy the possibility to perform fragmentation by a simple \ttt{LUEXEC} call. Also the hard interactions in {\Py} fulfil this condition, while problems may appear in the multiple interaction scenario, where several closed $\g\g$ loops may appear directly following one another, and thus would be interpreted as a single multigluon loop after translation back and forth. \clearpage \section{Hard Processes in JETSET} \label{s:JETSETproc} {\Je} contains the simulation of two hard processes. The process of main interest is $\ee \to \gammaZ \to \q \qbar$. Higher-order QCD corrections can be obtained either with parton showers or with second-order matrix elements. The details of the parton-shower evolution are given in section \ref{s:showinfi}, while this section contains the matrix-element description, including a summary of the {\Je} algorithm for initial-state photon radiation. Also {\Py} can be used to simulate the process $\ee \to \gammaZ \to \q \qbar$, but without the options of using second-order matrix elements or polarized incoming beams. Some other differences between the two algorithms are described. The other hard process in {\Je} is $\Upsilon$ decay to $\g \g \g$ or $\gamma \g \g$, which is briefly commented on. The main sources of information for this chapter are refs. \cite{Sjo83,Sjo86,Sjo89}. \subsection{Annihilation Events in the Continuum} \label{ss:eematrix} The description of $\ee$ annihilation into hadronic events involves a number of components: the $s$ dependence of the total cross section and flavour composition, multijet matrix elements, angular orientation of events, initial-state photon bremsstrahlung and effects of initial-state electron polarization. Many of the published formulae have been derived for the case of massless outgoing quarks. For each of the components described in the following, we will begin by discussing the massless case, and then comment on what is done to accommodate massive quarks. \subsubsection{Electroweak cross sections} In the standard theory, fermions have the following couplings (illustrated here for the first generation): \begin{center} \begin{tabular}{lll@{\protect\rule{0mm}{\tablinsep}}} $e_{\nu} = 0$, & $v_{\nu} = 1$, & $a_{\nu} = 1$, \\ $e_{\e} = -1$, & $v_{\e} = -1 + 4\ssintw$, & $a_{\e} = -1$, \\ $e_{\u} = 2/3$, & $v_{\u} = 1 - 8\ssintw /3$, & $a_{\nu} = 1$, \\ $e_{\d} = -1/3$, & $v_{\d} = -1 + 4\ssintw /3$, & $a_{\d} = -1$, \\ \end{tabular} \end{center} with $e$ the electric charge, and $v$ and $a$ the vector and axial couplings to the $\Z^0$. The relative energy dependence of the weak neutral current to the electromagnetic one is given by \begin{equation} \chi(s) = \frac{1}{4\ssintw\scostw} \; \frac{s}{s - m_{\Z}^2 + i m_{\Z}\Gamma_{\Z}} ~, \label{ee:chis} \end{equation} where $s = E_{\mrm{cm}}^2$. In {\Je} the electroweak mixing parameter $\ssintw$ and the $\Z^0$ mass $m_{\Z}$ and width $\Gamma_{\Z}$ are considered as constants to be given by you (while {\Py} itself calculates an $s$-dependent width). Although the incoming $\e^+$ and $\e^-$ beams are normally unpolarized, we have included the possibility of polarized beams, following the formalism of \cite{Ols80}. Thus the incoming $\e^+$ and $\e^-$ are characterized by polarizations $\mbf{P}^{\pm}$ in the rest frame of the particles: \begin{equation} \mbf{P}^{\pm} = P_{\mrm{T}}^{\pm} \hat{\mbf{s}}^{\pm} + P_{\mrm{L}}^{\pm} \hat{\mbf{p}}^{\pm} ~, \end{equation} where $0 \leq P_{\mrm{T}}^{\pm} \leq 1$ and $-1 \leq P_{\mrm{L}}^{\pm} \leq 1$, with the constraint \begin{equation} (\mbf{P}^{\pm})^2 = (P_{\mrm{T}}^{\pm})^2 + (P_{\mrm{L}}^{\pm})^2 \leq 1 ~. \end{equation} Here $\hat{\mbf{s}}^{\pm}$ are unit vectors perpendicular to the beam directions $\hat{\mbf{p}}^{\pm}$. To be specific, we choose a right-handed coordinate frame with $\hat{\mbf{p}}^{\pm} = (0,0, \mp 1)$, and standard transverse polarization directions (out of the machine plane for storage rings) $\hat{\mbf{s}}^{\pm} = (0, \pm 1,0)$, the latter corresponding to azimuthal angles $\varphi^{\pm} = \pm \pi /2$. As free parameters in the program we choose $P_{\mrm{L}}^+$, $P_{\mrm{L}}^-$, $P_{\mrm{T}} = \sqrt{P_{\mrm{T}}^+ P_{\mrm{T}}^-}$ and $\Delta \varphi = (\varphi^+ + \varphi^-) /2$. In the massless QED case, the probability to produce a flavour $\f$ is proportional to $e_{\f}^2$, i.e up-type quarks are four times as likely as down-type ones. In lowest-order massless QFD the corresponding relative probabilities are given by \cite{Ols80} \begin{eqnarray} h_{\f}(s) & = & e_{\e}^2 \, (1 - P_{\mrm{L}}^+ P_{\mrm{L}}^-) \, e_{\f}^2 \, + \, 2 e_{\e} \left\{ v_{\e} (1 - P_{\mrm{L}}^+ P_{\mrm{L}}^-) - a_{\e} (P_{\mrm{L}}^- - P_{\mrm{L}}^+) \right\} \, \Re\chi(s) \, e_{\f} v_{\f} \, + \nonumber \\ & & + \, \left\{ (v_{\e}^2 + a_{\e}^2) (1 - P_{\mrm{L}}^+ P_{\mrm{L}}^-) - 2 v_{\e} a_{\e} (P_{\mrm{L}}^- - P_{\mrm{L}}^+) \right\} \, \left| \chi(s) \right|^2 \, \left\{ v_{\f}^2 + a_{\f}^2 \right\} ~, \label{ee:hf} \end{eqnarray} where $\Re\chi(s)$ denotes the real part of $\chi(s)$. The $h_{\f}(s)$ expression depends both on the $s$ value and on the longitudinal polarization of the $\e^{\pm}$ beams in a non-trivial way. The cross section for the process $\ee \to \gammaZ \to \f \fbar$ may now be written as \begin{equation} \sigma_{\f}(s) = \frac{4 \pi \alphaem^2}{3 s} R_{\f}(s) ~, \end{equation} where $R_{\f}$ gives the ratio to the lowest-order QED cross section for the process $\ee \to \mu^+ \mu^-$, \begin{equation} R_{\f}(s) = N_C \, R_{\mrm{QCD}} \, h_{\f}(s) ~. \end{equation} The factor of $N_C = 3$ counts the number of colour states available for the $\q\qbar$ pair. The $R_{\mrm{QCD}}$ factor takes into account QCD loop corrections to the cross section. For $n_f$ effective flavours (normally $n_f =5$) \begin{equation} R_{\mrm{QCD}} \approx 1 + \frac{\alphas}{\pi} + (1.986 - 0.115 n_f) \left( \frac{\alphas}{\pi} \right)^2 + \cdots \label{ee:RQCD} \end{equation} in the $\br{\mrm{MS}}$ renormalization scheme \cite{Din79}. Note that $R_{\mrm{QCD}}$ does not affect the relative quark-flavour composition, and so is of peripheral interest in {\Je}. (For leptons the $N_C$ and $R_{\mrm{QCD}}$ factors would be absent, i.e. $N_C \, R_{\mrm{QCD}} = 1$, but leptonic final states are not generated in {\Je}.) Neglecting higher-order QCD and QFD effects, the corrections for massive quarks are given in terms of the velocity $v_{\q}$ of a quark with mass $m_{\q}$, $v_{\q} = \sqrt{ 1 - 4 m_{\q}^2 /s}$, as follows. The vector quark current terms in $h_{\f}$ (proportional to $e_{\f}^2$, $e_{\f} v_{\f}$, or $v_{\f}^2$) are multiplied by a threshold factor $v_{\q} (3 - v_{\q}^2) /2$, while the axial vector quark current term (proportional to $a_{\f}^2$) is multiplied by $v_{\q}^3$. While inclusion of quark masses in the QFD formulae decreases the total cross section, first-order QCD corrections tend in the opposite direction \cite{Jer81}. Na\"{\i}vely, one would expect one factor of $v_{\q}$ to get cancelled. So far, the available options are either to include threshold factors in full or not at all. Given that all five quarks are light at the scale of the $\Z^0$, the issue of quark masses is not really of interest at LEP. Here, however, purely weak corrections are important, in particular since they change the $\b$ quark partial width differently from that of the other ones \cite{Kuh89}. No such effects are included in the program. \subsubsection{First-order QCD matrix elements} The Born process $\ee \to \q \qbar$ is modified in first-order QCD by the probability for the $\q$ or $\qbar$ to radiate a gluon, i.e. by the process $\ee \to \q \qbar \g$. The matrix element is conveniently given in terms of scaled energy variables in the c.m. frame of the event, $x_1 = 2E_{\q}/E_{\mrm{cm}}$, $x_2 = 2E_{\qbar}/E_{\mrm{cm}}$, and $x_3 = 2E_{\g}/E_{\mrm{cm}}$, i.e. $x_1 + x_2 + x_3 = 2$. For massless quarks the matrix element reads \cite{Ell76} \begin{equation} \frac{1}{\sigma_0} \, \frac{\d \sigma}{\d x_1 \, \d x_2} = \frac{\alphas}{2\pi} \, C_F \, \frac{x_1^2 + x_2^2}{(1-x_1)(1-x_2)} ~, \label{ee:ME3j} \end{equation} where $\sigma_0$ is the lowest-order cross section, $C_F = 4/3$ is the appropriate colour factor, and the kinematically allowed region is $0 \leq x_i \leq 1, i = 1, 2, 3$. By kinematics, the $x_k$ variable for parton $k$ is related to the invariant mass $m_{ij}$ of the other two partons $i$ and $j$ by $y_{ij} = m_{ij}^2/E_{\mrm{cm}}^2 = 1 - x_k$. The strong coupling constant $\alphas$ is in first order given by \begin{equation} \alphas(Q^2) = \frac{12\pi}{(33-2n_f) \, \ln(Q^2/\Lambda^2)} ~. \label{ee:aS3j} \end{equation} Conventionally $Q^2 = s = E_{\mrm{cm}}^2$; we will return to this issue below. The number of flavours $n_f$ is 5 for LEP applications, and so the $\Lambda$ value determined is $\Lambda_5$ (while e.g. most deep inelastic scattering studies refer to $\Lambda_4$, the energies for these experiments being below the bottom threshold). The $\alphas$ values are matched at flavour thresholds, i.e. as $n_f$ is changed the $\Lambda$ value is also changed. It is therefore the derivative of $\alphas$ that changes at a threshold, not $\alphas$ itself. In order to separate 2-jets from 3-jets, it is useful to introduce jet-resolution parameters. This can be done in several different ways. Most famous are the $y$ and $(\epsilon, \delta)$ procedures. We will only refer to the $y$ cut, which is the one used in the program. Here a 3-parton configuration is called a 2-jet event if \begin{equation} \min_{i,j} (y_{ij}) = \min_{i,j} \left( \frac{m_{ij}^2}{E_{\mrm{cm}}^2} \right) < y ~. \end{equation} The cross section in eq.~(\ref{ee:ME3j}) diverges for $x_1 \rightarrow 1$ or $x_2 \rightarrow 1$ but, when first-order propagator and vertex corrections are included, a corresponding singularity with opposite sign appears in the $\q \qbar$ cross section, so that the total cross section is finite. In analytical calculations, the average value of any well-behaved quantity ${\cal Q}$ can therefore be calculated as \begin{equation} \left\langle {\cal Q} \right\rangle = \frac{1}{\sigma_{\mrm{tot}}} \lim_{y \rightarrow 0} \left( {\cal Q}(\mrm{2parton}) \, \sigma_{\mrm{2parton}}(y) + \int_{y_{ij} > y} {\cal Q}(x_1,x_2) \, \frac{\d \sigma_{\mrm{3parton}}}{\d x_1 \, \d x_2} \, \d x_1 \, \d x_2 \right) ~, \label{ee:Obs} \end{equation} where any explicit $y$ dependence disappears in the limit $y \rightarrow 0$. In a Monte Carlo program, it is not possible to work with a negative total 2-jet rate, and thus it is necessary to introduce a fixed non-vanishing $y$ cut in the 3-jet phase space. Experimentally, there is evidence for the need of a low $y$ cut, i.e. a large 3-jet rate. For LEP applications, the recommended value is $y = 0.01$, which is about as far down as one can go and still retain a positive 2-jet rate. With $\alphas = 0.12$, in full second-order QCD (see below), the $2:3:4$ jet composition is then approximately $11 \% : 77 \% : 12 \%$. Note, however, that initial-state QED radiation may occasionally lower the c.m. energy significantly, i.e. increase $\alphas$, and thereby bring the 3-jet fraction above unity if $y$ is kept fixed at 0.01 also in those events. Therefore, at PETRA/PEP energies, $y$ values slightly above 0.01 are needed. In addition to the $y$ cut, the program contains a cut on the invariant mass $m_{ij}$ between any two partons, which is typically required to be larger than 2 GeV. This cut corresponds to the actual merging of two nearby parton jets, i.e. where a treatment with two separate partons rather than one would be superfluous in view of the smearing arising from the subsequent fragmentation. Since the cut-off mass scale $\sqrt{y} E_{\mrm{cm}}$ normally is much larger, this additional cut only enters for events at low energies. For massive quarks, the amount of QCD radiation is slightly reduced \cite{Iof78}: \begin{eqnarray} \frac{1}{\sigma_0} \, \frac{\d \sigma}{\d x_1 \, \d x_2} & = & \frac{\alphas}{2\pi} \, C_F \, \left\{ \frac{x_1^2 + x_2^2}{(1-x_1)(1-x_2)} - \frac{4 m_{\q}^2}{s} \left( \frac{1}{1-x_1} + \frac{1}{1-x_2} \right) \right. \nonumber \\[1mm] & & - \left. \frac{2 m_{\q}^2}{s} \left( \frac{1}{(1-x_1)^2} + \frac{1}{(1-x_2)^2} \right) - \frac{4 m_{\q}^4}{s^2} \left( \frac{1}{1-x_1} + \frac{1}{1-x_2} \right)^2 \right\} ~. \label{ee:threejMEmass} \end{eqnarray} In addition, the phase space for emission is reduced by the requirement \begin{equation} \frac{(1-x_1)(1-x_2)(1-x_3)}{x_3^2} \geq \frac{m_{\q}^2}{s} ~. \end{equation} For $\b$ quarks at LEP energies, these corrections are fairly small. \subsubsection{4-jet matrix elements} Two new event types are added in second-order QCD, $\ee \to \q \qbar \g \g$ and $\ee \to \q \qbar \q' \qbar'$. The 4-jet cross section has been calculated by several groups \cite{Ali80a,Gae80,Ell81,Dan82}, which agree on the result. The formulae are too lengthy to be quoted here. In one of the calculations \cite{Ali80a}, quark masses were explicitly included, but {\Je} only includes the massless expressions, as taken from \cite{Ell81}. Here the angular orientation of the event has been integrated out, so that five independent internal kinematical variables remain. These may be related to the six $y_{ij}$ and the four $y_{ijk}$ variables, $y_{ij} = m_{ij}^2 / s = (p_i + p_j)^2 / s$ and $y_{ijk} = m_{ijk}^2 / s = (p_i + p_j + p_k)^2 / s$, in terms of which the matrix elements are given. The original calculations were for the pure $\gamma$-exchange case; it was recently pointed out \cite{Kni89} that an additional contribution to the $\ee \to \q \qbar \q' \qbar'$ cross section arises from the axial part of the $\Z^0$. This term is not included in the program, but fortunately it is finite and small. Whereas the way the string, i.e. the fragmenting colour flux tube, is stretched is uniquely given in $\q \qbar \g$ event, for $\q \qbar \g \g$ events there are two possibilities: \mbox{$\q - \g_1 - \g_2 - \qbar$} or \mbox{$\q - \g_2 - \g_1 - \qbar$}. A knowledge of quark and gluon colours, obtained by perturbation theory, will uniquely specify the stretching of the string, as long as the two gluons do not have the same colour. The probability for the latter is down in magnitude by a factor $1 / N_C^2 = 1 / 9$. One may either choose to neglect these terms entirely, or to keep them for the choice of kinematical setup, but then drop them at the choice of string drawing \cite{Gus82}. We have adopted the latter procedure. Comparing the two possibilities, differences are typically 10--20\% for a given kinematical configuration, and less for the total 4-jet cross section, so from a practical point of view this is not a major problem. In higher orders, results depend on the renormalization scheme; we will use $\br{\mrm{MS}}$ throughout. In addition to this choice, several possible forms can be chosen for $\alphas$, all of which are equivalent to that order but differ in higher orders. We have picked the recommended standard \cite{PDG88} \begin{equation} \label{ee:aS4j} \alphas(Q^2) = \frac{12\pi}{(33-2n_f) \, \ln (Q^2 / \Lambda^2_{\br{\mrm{MS}}})} \left\{ 1 - 6 \, \frac{153-19n_f}{(33-2n_f)^2} \, \frac{\ln (\ln ( Q^2 / \Lambda^2_{\br{\mrm{MS}}}))} {\ln ( Q^2 / \Lambda^2_{\br{\mrm{MS}}})} \right\} ~. \end{equation} \subsubsection{Second-order 3-jet matrix elements} As for first order, a full second-order calculation consists both of real parton emission terms and of vertex and propagator corrections. These modify the 3-jet and 2-jet cross sections. Although there was some initial confusion, everybody soon agreed on the size of the loop corrections \cite{Ell81,Ver81,Fab82}. In analytic calculations, the procedure of eq.~(\ref{ee:Obs}), suitably expanded, can therefore be used unambiguously for a well-behaved variable. For Monte Carlo event simulation, it is again necessary to impose some finite jet-resolution criterion. This means that four-parton events which fail the cuts should be reassigned either to the 3-jet or to the 2-jet event class. It is this area that caused quite a lot of confusion in the past \cite{Kun81,Got82,Ali82,Zhu83,Gut84,Gut87,Kra88}, and where full agreement does not exist. Most likely, agreement will never be reached, since there are indeed ambiguous points in the procedure, related to uncertainties on the theoretical side, as follows. For the $y$-cut case, any two partons with an invariant mass $m_{ij}^2 < y E_{\mrm{cm}}^2$ should be recombined into one. If the four-momenta are simply added, the sum will correspond to a parton with a positive mass, namely the original $m_{ij}$. The loop corrections are given in terms of final massless partons, however. In order to perform the (partial) cancellation between the four-parton real and the 3-parton virtual contributions, it is therefore necessary to get rid of the bothersome mass in the four-parton states. Several recombinations are used in practice, which go under names such as `E', `E0', `p' and `p0' \cite{OPA91}. In the `E'-type schemes, the energy of a recombined parton is given by $E_{ij} = E_i + E_j$, and three-momenta may have to be adjusted accordingly. In the `p'-type schemes, on the other hand, three-momenta are added, $\mbf{p}_{ij} = \mbf{p}_i + \mbf{p}_j$, and then energies may have to be adjusted. These procedures result in different 3-jet topologies, and therefore in different second-order differential 3-jet cross sections. Within each scheme, a number of lesser points remain to be dealt with, in particular what to do if a recombination of a nearby parton pair were to give an event with a non-$\q\qbar\g$ flavour structure. {\Je} contains two alternative second-order 3-jet implementations, GKS and ERT(Zhu). For historical reasons the former is default, but actually the latter is the recommended one today. Other parametrizations have also been made available that run together with {\Je}, see \cite{Sjo89,Mag89}. The GKS option is based on the GKS \cite{Gut84} calculation, where some of the original mistakes in FKSS \cite{Fab82} have been corrected. The GKS formulae have the advantage of giving the second-order corrections in closed analytic form, as not-too-long functions of $x_1$, $x_2$, and the $y$ cut. However, it is today recognized, also by the authors, that important terms are still missing, and that the matrix elements should therefore not be taken too seriously. The option is thus kept mainly for backwards compatibility. The ERT(Zhu) generator \cite{Zhu83} is based on the ERT matrix elements \cite{Ell81}, with a Monte Carlo recombination procedure suggested by Kunszt \cite{Kun81} and developed by Ali \cite{Ali82}. It has the merit of giving corrections in a convenient, parametrized form. For practical applications, the main limitation is that the corrections are only given for discrete values of the cut-off parameter $y$, namely $y$ = 0.01, 0.02, 0.03, 0.04, and 0.05. The basic approach is the following. Without any loss of generality, the full second-order 3-jet cross section can be written in terms of the `ratio function' $R(X,Y;y)$, defined by \begin{equation} \frac{1}{\sigma_0} \frac{\d \sigma_3^{\mrm{tot}}}{\d X \, \d Y} = \frac{\alphas}{\pi} A_0(X,Y) \left\{ 1 + \frac{\alphas}{\pi} R(X,Y;y) \right\} ~, \label{ee:Zhupar} \end{equation} where $X = x_1 - x_2 = x_{\q} - x_{\qbar}$, $Y = x_3 = x_g$, $\sigma_0$ is the lowest-order hadronic cross section, and $A_0(X,Y)$ the standard first-order 3-jet cross section, cf. eq.~(\ref{ee:ME3j}). By Monte Carlo integration, the value of $R(X,Y;y)$ is evaluated in bins of $(X,Y)$, and the result parametrized by a simple function $F(X,Y;y)$. In order to obtain the second-order 3-jet rate, a small cut $y_0 = 10^{-7}$ was introduced. It was assumed that four-parton events which fail this cut can be (partly) cancelled analytically against the virtual 3-jet events, to give a net `regularized virtual' contribution to the 3-jet rate. For a given choice of $y$ cut, in the physical range $y \gg y_0$, an additional `soft' contribution comes from four-parton events which survive the $y_0$ cut but fail the $y$ one. A large sample (9\,000\,000) of four-parton events was generated inside the $y_0$ cut region. For events which failed the more stringent $y$ cuts, the parton pair with the smallest invariant mass was recombined into an effective jet, using the `p0' recombination scheme. This means that the individual three-momenta were added, $\mbf{p}_{ij} = \mbf{p}_i + \mbf{p}_j$, the mass of the recombined pair was set to zero for the calculation of energy, $E_{ij} = |\mbf{p}_i + \mbf{p}_j|$, and finally all four-momenta were rescaled by a common factor so as to preserve the correct c.m. frame energy. In calculating the ${\cal O}(\alphas^2)$ correction functions, care was taken to maintain the flavour signature of the jets in the recombination process. A quark and a gluon were recombined into a quark with the same flavour as the original quark, two gluons were recombined to form a gluon, etc. In some cases the three jets of the final state were not in the standard $\q \qbar \g$ configuration. The probability for this to happen corresponded to less than 0.5\% of the total cross section, even for the most stringent cuts used. For these non-$\q \qbar \g$ final states, the assignment of $\q$, $\qbar$ and $\g$ was done at random. The sum of `regularized virtual' (1\,000\,000 3-jet events were generated, with evaluated second-order weights) and `soft' corrections, normalized to the first-order 3-jet cross section, was tabulated in the $(X,Y)$ plane, using bins of size $0.05 \times 0.05$. This estimated $R$-function behaviour was then fit with a 12-parameter function $F$, \begin{eqnarray} F(X,Y;y)& = & p_1 + p_2 X^2 + p_3 X^4 + (p_4+p_5 X^2)Y+ (p_6+p_7X^2)Y^2 + \nonumber\\ & & (p_8+p_9X^2)Y^3 + p_{10}/(X^2-Y^2) + p_{11}/(1-Y) + p_{12}/Y ~. \label{ee:ZhuFun} \end{eqnarray} The parameters $p_i$ are reproduced in \cite{Sjo89}. \subsubsection{The matrix-element event generator scheme} The program contains parametrizations, separately, of the total first-order 3-jet rate, the total second-order 3-jet rate, and the total 4-jet rate, all as functions of $y$ (with $\alphas$ as a separate prefactor). These parametrizations have been obtained as follows: \begin{Itemize} \item The first-order 3-jet matrix element is almost analytically integrable; some small finite pieces were obtained by a truncated series expansion of the relevant integrand. \item The GKS second-order 3-jet matrix elements were integrated for 40 different $y$-cut values, evenly distributed in $\ln y$ between a smallest value $y = 0.001$ and the kinematical limit $y = 1/3$. For each $y$ value, 250\,000 phase-space points were generated, evenly in $\d \ln (1-x_i) = \d x_i/(1-x_i)$, $i = 1,2$, and the second-order 3-jet rate in the point evaluated. The properly normalized sum of weights in each of the 40 $y$ points were then fitted to a polynomial in $\ln(y^{-1}-2)$. For the ERT(Zhu) matrix elements the parametrizations in eq.~(\ref{ee:ZhuFun}) were used to perform a corresponding Monte Carlo integration for the five $y$ values available. \item The 4-jet rate was integrated numerically, separately for $\q \qbar \g \g$ and $\q \qbar \q' \qbar'$ events, by generating large samples of 4-jet phase-space points within the boundary $y = 0.001$. Each point was classified according to the actual minimum $y$ between any two partons. The same events could then be used to update the summed weights for 40 different counters, corresponding to $y$ values evenly distributed in $\ln y$ between $y = 0.001$ and the kinematical limit $y = 1/6$. In fact, since the weight sums for large $y$ values only received contributions from few phase-space points, extra (smaller) subsamples of events were generated with larger $y$ cuts. The summed weights, properly normalized, were then parametrized in terms of polynomials in $\ln(y^{-1} - 5)$. Since it turned out to be difficult to obtain one single good fit over the whole range of $y$ values, different parametrizations are used above and below $y=0.018$. As originally given, the $\q \qbar \q' \qbar'$ parametrization only took into account four $\q'$ flavours, i.e. secondary $\b \bbar$ pairs were not generated, but this has been corrected for LEP. \end{Itemize} In the generation stage, each event is treated on its own, which means that the $\alphas$ and $y$ values may be allowed to vary from event to event. The main steps are the following. \begin{Enumerate} \item The $y$ value to be used in the current event is determined. If possible, this is the value given by you, but additional constraints exist from the validity of the parametrizations ($y \geq 0.001$ for GKS, $0.01 \leq y \leq 0.05$ for ERT(Zhu)) and an extra (user-modifiable) requirement of a minimum absolute invariant mass between jets (which translates into varying $y$ cuts due to the effects of initial-state QED radiation). \item The $\alphas$ value is calculated. \item For the $y$ and $\alphas$ values given, the relative two/three/4-jet composition is determined. This is achieved by using the parametrized functions of $y$ for 3- and 4-jet rates, multiplied by the relevant number of factors of $\alphas$. In ERT(Zhu), where the second-order 3-jet rate is available only at a few $y$ values, intermediate results are obtained by linear interpolation in the ratio of second-order to first-order 3-jet rates. The 3-jet and 4-jet rates are normalized to the analytically known second-order total event rate, i.e. divided by $R_{\mrm{QCD}}$ of eq.~(\ref{ee:RQCD}). Finally, the 2-jet rate is obtained by conservation of total probability. \item If the combination of $y$ and $\alphas$ values is such that the total 3- plus 4-jet fraction is larger than unity, i.e. the remainder 2-jet fraction negative, the $y$-cut value is raised (for that event), and the process is started over at point 3. \item The choice is made between generating a 2-, 3- or 4-jet event, according to the relative probabilities. \item For the generation of 4-jets, it is first necessary to make a choice between $\q \qbar \g \g$ and $\q \qbar \q' \qbar'$ events, according to the relative (parametrized) total cross sections. A phase-space point is then selected, and the differential cross section at this point is evaluated and compared with a parametrized maximum weight. If the phase-space point is rejected, a new one is selected, until an acceptable 4-jet event is found. \item For 3-jets, a phase-space point is first chosen according to the first-order cross section. For this point, the weight \begin{equation} W(x_1,x_2;y) = 1 + \frac{\alphas}{\pi} R(x_1,x_2;y) \label{ee:WTJS} \end{equation} is evaluated. Here $R(x_1,x_2;y)$ is analytically given for GKS \cite{Gut84}, while it is approximated by the parametrization $F(X,Y;y)$ of eq.~(\ref{ee:ZhuFun}) for ERT(Zhu). Again, linear interpolation of $F(X,Y;y)$ has to be applied for intermediate $y$ values. The weight $W$ is compared with a maximum weight \begin{equation} W_{\mmax}(y) = 1 + \frac{\alphas}{\pi} R_{\mmax}(y) ~, \end{equation} which has been numerically determined beforehand and suitably parametrized. If the phase-space point is rejected, a new point is generated, etc. \item Massive matrix elements are not available in {\Je} for second-order QCD (but are in the first-order option). However, if a 3- or 4-jet event determined above falls outside the phase-space region allowed for massive quarks, the event is rejected and reassigned to be a 2-jet event. (The way the $y_{ij}$ and $y_{ijk}$ variables of 4-jet events should be interpreted for massive quarks is not even unique, so some latitute has been taken here to provide a reasonable continuity from 3-jet events.) This procedure is known not to give the expected full mass suppression, but is a reasonable first approximation. \item Finally, if the event is classified as a 2-jet event, either because it was initially so assigned, or because it failed the massive phase-space cuts for 3- and 4-jets, the generation of 2-jets is trivial. \end{Enumerate} \subsubsection{Optimized perturbation theory} Theoretically, it turns out that the second-order corrections to the 3-jet rate are large. It is therefore not unreasonable to expect large third-order corrections to the 4-jet rate. Indeed, the experimental 4-jet rate is much larger than second order predicts (when fragmentation effects have been folded in), if $\alphas$ is determined based on the 3-jet rate \cite{Sjo84a,JAD88}. The only consistent way to resolve this issue is to go ahead and calculate the full next order. This is a tough task, however, so people have looked at possible shortcuts. For example, one can try to minimize the higher-order contributions by a suitable choice of the renormalization scale \cite{Ste81} --- `optimized perturbation theory'. This is equivalent to a different choice for the $Q^2$ scale in $\alphas$, a scale which is not unambiguous anyway. Indeed the standard value $Q^2 = s = E_{\mrm{cm}}^2$ is larger than the natural physical scale of gluon emission in events, given that most gluons are fairly soft. One could therefore pick another scale, $Q^2 = f s$, with $f < 1$. The ${\cal O}(\alphas)$ 3-jet rate would be increased by such a scale change, and so would the number of 4-jet events, including those which collapse into 3-jet ones. The loop corrections depend on the $Q^2$ scale, however, and compensate the changes above by giving a larger negative contribution to the 3-jet rate. The possibility of picking an optimized scale $f$ is implemented as follows \cite{Sjo89}. Assume that the differential 3-jet rate at scale $Q^2 = s$ is given by the expression \begin{equation} R_3 = r_1 \alphas + r_2 \alphas^2 ~, \end{equation} where $R_3$, $r_1$ and $r_2$ are functions of the kinematical variables $x_1$ and $x_2$ and the $y$ cut, as described above. When the coupling is chosen at a different scale, $Q'^2 = f s$, the 3-jet rate has to be changed to \begin{equation} R_3' = r_1' \alphas' + r_2 \alphas'^2 ~, \end{equation} where $r_1' = r_1$, \begin{equation} r_2' = r_2 + r_1 \frac{33-2n_f}{12\pi} \ln f ~, \label{ee:r2optim} \end{equation} and $\alphas' = \alphas(fs)$. Since we only have the Born term for 4-jets, here the effects of a scale change come only from the change in the coupling constant. Finally, the 2-jet cross section can still be calculated from the difference between the total cross section and the 3- and 4-jet cross sections. If an optimized scale is used in the program, the default value is $f=0.002$, which is favoured by the studies in ref. \cite{Bet89}. (In fact, it is also possible to use a correspondingly optimized $R_{\mrm{QCD}}$ factor, eq.~(\ref{ee:RQCD}), but then the corresponding $f$ is chosen independently and much closer to unity.) The success of describing the jet rates should not hide the fact that one is dabbling in (educated, hopefully) guesswork, and that any conclusions based on this method have to be taken with a pinch of salt. One special problem associated with the use of optimized perturbation theory is that the differential 3-jet rate may become negative over large regions of the $(x_1, x_2)$ phase space. This problem already exists, at least in principle, even for a scale $f = 1$, since $r_2$ is not guaranteed to be positive definite. Indeed, depending on the choice of $y$ cut, $\alphas$ value and recombination scheme, one may observe a small region of negative differential 3-jet rate for the full second-order expression. This region is centred around $\q \qbar \g$ configurations, where the $\q$ and $\qbar$ are close together in one hemisphere and the $\g$ is alone in the other, i.e. $x_1 \approx x_2 \approx 1/2$. It is well understood why second-order corrections should be negative in this region \cite{Dok89}: the $\q$ and $\qbar$ of a $\q \qbar \g$ state are in a relative colour octet state, and thus the colour force between them is repulsive, which translates into a negative second-order term. However, as $f$ is decreased below unity, $r_2'$ receives a negative contribution from the $\ln f$ term, and the region of negative differential cross section has a tendency to become larger, also after taking into account related changes in $\alphas$. In an event-generator framework, where all events are supposed to come with unit weight, it is clearly not possible to simulate negative cross sections. What happens in the program is therefore that no 3-jet events at all are generated in the regions of negative differential cross section, and that the 3-jet rate in regions of positive cross sections is reduced by a constant factor, chosen so that the total number of 3-jet events comes out as it should. This is a consequence of the way the program works, where it is first decided what kind of event to generate, based on integrated 3-jet rates in which positive and negative contributions are added up with sign, and only thereafter the kinematics is chosen. Based on our physics understanding of the origin of this negative cross section, the approach adopted is as sensible as any, at least to that order in perturbation theory (what one might strive for is a properly exponentiated description of the relevant region). It can give rise to funny results for low $f$ values, however, as observed by OPAL \cite{OPA92} for the energy--energy correlation asymmetry. \subsubsection{Angular orientation} While pure $\gamma$ exchange gives a simple $1 + \cos^2\theta$ distribution for the $\q$ (and $\qbar$) direction in $\q \qbar$ events, $\Z^0$ exchange and $\gammaZ$ interference results in a forward--backward asymmetry. If one introduces \begin{eqnarray} h'_{\f}(s) & = & 2 e_{\e} \left\{ a_{\e} (1 - P_{\mrm{L}}^+ P_{\mrm{L}}^-) - v_{\e} (P_{\mrm{L}}^- - P_{\mrm{L}}^+) \right\} \, \Re\chi(s) e_{\f} a_{\f} \nonumber \\ & & + \, \left\{ 2 v_{\e} a_{\e} (1 - P_{\mrm{L}}^+ P_{\mrm{L}}^-) - (v_{\e}^2 + a_{\e}^2) (P_{\mrm{L}}^- - P_{\mrm{L}}^+) \right\} \, |\chi(s)|^2 \, v_{\f} a_{\f} ~, \end{eqnarray} then the angular distribution of the quark is given by \begin{equation} \frac{\d \sigma}{\d (\cos\theta_{\f})} \propto h_{\f}(s)(1 + \cos^2\theta_{\f}) + 2 h'_{\f}(s) \cos\theta_{\f} ~. \end{equation} The angular orientation of a 3- or 4-jet event may be described in terms of three angles $\chi$, $\theta$ and $\varphi$; for 2-jet events only $\theta$ and $\varphi$ are necessary. From a standard orientation, with the $\q$ along the $+z$ axis and the $\qbar$ in the $xz$ plane with $p_x > 0$, an arbitrary orientation may be reached by the rotations $+\chi$ in azimuthal angle, $+\theta$ in polar angle, and $+\varphi$ in azimuthal angle, in that order. Differential cross sections, including QFD effects and arbitrary beam polarizations have been given for 2- and 3-jet events in refs. \cite{Ols80,Sch80}. We use the formalism of ref. \cite{Ols80}, with $\chi \to \pi - \chi$ and $\varphi^- \to - (\varphi + \pi/2)$. The resulting formulae are tedious, but straightforward to apply, once the internal jet configuration has been chosen. 4-jet events are approximated by 3-jet ones, by joining the two gluons of a $\q \qbar \g \g$ event and the $\q'$ and $\qbar'$ of a $\q \qbar \q' \qbar'$ event into one effective jet. This means that some angular asymmetries are neglected \cite{Ali80a}, but that weak effects are automatically included. It is assumed that the second-order 3-jet events have the same angular orientation as the first-order ones, some studies on this issue may be found in \cite{Kor85}. Further, the formulae normally refer to the massless case; only for the QED 2- and 3-jet cases are mass corrections available. The main effect of the angular distribution of multijet events is to smear the lowest-order result, i.e. to reduce any anisotropies present in 2-jet systems. In the parton-shower option of the program, only the initial $\q \qbar$ axis is determined. The subsequent shower evolution then {\it de facto} leads to a smearing of the jet axis, although not necessarily in full agreement with the expectations from multijet matrix-element treatments. \subsubsection{Initial-state radiation} Initial-state photon radiation has been included using the formalism of ref. \cite{Ber82}. Here each event contains either no photon or one, i.e. it is a first-order non-exponentiated description. The main formula for the hard radiative photon cross section is \begin{equation} \frac{\d \sigma}{\d x_{\gamma}} = \frac{\alphaem}{\pi} \, \left( \ln\frac{s}{m_{\e}^2} -1 \right) \, \frac{1 + (1-x_{\gamma})^2}{x_{\gamma}} \, \sigma_0 (\hat{s}) ~, \end{equation} where $x_{\gamma}$ is the photon energy fraction of the beam energy, $\hat{s} = (1-x_{\gamma}) s$ is the squared reduced hadronic c.m. energy, and $\sigma_0$ is the ordinary annihilation cross section at the reduced energy. In particular, the selection of jet flavours should be done according to expectations at the reduced energy. The cross section is divergent both for $x_{\gamma} \to 1$ and $x_{\gamma} \to 0$. The former is related to the fact that $\sigma_0$ has a $1/\hat{s}$ singularity (the real photon pole) for $\hat{s} \to 0$. An upper cut on $x_{\gamma}$ can here be chosen to fit the experimental setup. The latter is a soft photon singularity, which is to be compensated in the no-radiation cross section. A requirement $x_{\gamma} > 0.01$ has therefore been chosen so that the hard-photon fraction is smaller than unity. In the total cross section, effects from photons with $x_{\gamma} < 0.01$ are taken into account, together with vertex and vacuum polarization corrections (hadronic vacuum polarizations using a simple parametrization of the more complicated formulae of ref. \cite{Ber82}). The hard photon spectrum can be integrated analytically, for the full $\gammaZ$ structure including interference terms, provided that no new flavour thresholds are crossed and that the $R_{\mrm{QCD}}$ term in the cross section can be approximated by a constant over the range of allowed $\hat{s}$ values. In fact, threshold effects can be taken into account by standard rejection techniques, at the price of not obtaining the exact cross section analytically, but only by an effective Monte Carlo integration taking place in parallel with the ordinary event generation. In addition to $x_{\gamma}$, the polar angle $\theta_{\gamma}$ and azimuthal angle $\varphi_{\gamma}$ of the photons are also to be chosen. Further, for the orientation of the hadronic system, a choice has to be made whether the photon is to be considered as having been radiated from the $\e^+$ or from the $\e^-$. Final-state photon radiation, as well as interference between initial- and final-state radiation, has been left out of this treatment. The formulae for $\ee \to \mu^+ \mu^-$ cannot be simply taken over for the case of outgoing quarks, since the quarks as such only live for a short while before turning into hadrons. Another simplification in our treatment is that effects of incoming polarized $\e^{\pm}$ beams have been completely neglected, i.e. neither the effective shift in azimuthal distribution of photons nor the reduction in polarization is included. The polarization parameters of the program are to be thought of as the effective polarization surviving after initial-state radiation. \subsubsection{Alternative matrix elements} The program contains two sets of `toy model' matrix elements, one for an Abelian vector gluon model and one for a scalar gluon model. Clearly both of these alternatives are already excluded by data, and are anyway not viable alternatives for a consistent theory of strong interactions. They are therefore included more as references to show how well the characteristic features of QCD can be measured experimentally. Second-order matrix elements are available for the Abelian vector gluon model. These are easily obtained from the standard QCD matrix elements by a substitution of the Casimir group factors: $C_F = 4/3 \to 1$, $N_C = 3 \to 0$, and $T_R = n_{\f}/2 \to 3 n_{\f}$. First-order matrix elements contain only $C_F$; therefore the standard first-order QCD results may be recovered by a rescaling of $\alphas$ by a factor $4/3$. In second order the change of $N_C$ to 0 means that $\g \to \g\g$ couplings are absent from the Abelian model, while the change of $T_R$ corresponds to an enhancement of the $\g \to \q'\qbar'$ coupling, i.e. to an enhancement of the $\q\qbar\q'\qbar'$ 4-jet event rate. The second-order corrections to the 3-jet rate turn out to be strongly negative --- if $\alphas$ is fitted to get about the right rate of 4-jet events, the predicted differential 3-jet rate is negative almost everywhere in the $(x_1, x_2)$ plane. Whether this unphysical behaviour would be saved by higher orders is unclear. It has been pointed out that the rate can be made positive by a suitable choice of scale, since $\alphas$ runs in opposite directions in an Abelian model and in QCD \cite{Bet89}. This may be seen directly from eq. (\ref{ee:r2optim}), where the term $33 = 11 N_C$ is absent in the Abelian model, and therefore the scale-dependent term changes sign. In the program, optimized scales have not been implemented for this toy model. Therefore the alternatives provided for you are either to generate only 4-jet events, or to neglect second-order corrections to the 3-jet rate, or to have the total 3-jet rate set vanishing (so that only 2- and 4-jet events are generated). Normally we would expect the former to be the one of most interest, since it is in angular (and flavour) distributions of 4-jet events that the structure of QCD can be tested. Also note that the `correct' running of $\alphas$ is not included; you are expected to use the option where $\alphas$ is just given as a constant number. The scalar gluon model is even more excluded than the Abelian vector one, since differences appear already in the 3-jet matrix element \cite{Lae80}: \begin{equation} \frac{\d \sigma}{\d x_1 \, \d x_2} \propto \frac{x_3^2}{(1-x_1)(1-x_2)} \end{equation} when only $\gamma$ exchange is included. The axial part of the $\Z^0$ gives a slightly different shape; this is included in the program but does not make much difference. The angular orientation does include the full $\gammaZ$ interference \cite{Lae80}, but the main interest is in the 3-jet topology as such \cite{Ell79}. No higher-order corrections are included. It is recommended to use the option of a fixed $\alphas$ also here, since the correct running is not available. \subsection{Decays of Onia Resonances} \label{ss:oniadecays} Many different possibilities are open for the decay of heavy $J^{PC} = 1^{--}$ onia resonances. Of special interest are the decays into three gluons or two gluons plus a photon, since these offer unique possibilities to study a `pure sample' of gluon jets. A routine for this purpose is included in the program. It was written at a time where the expectations were to find toponium at PETRA energies. If, as now seems likely, the top mass is above 100~GeV, weak decays will dominate, to the extent that the top quark will decay weakly even before a bound toponium state is formed, and thus the routine will be of no use for top. The charm system, on the other hand, is far too low in mass for a jet language to be of any use. The only application is therefore likely to be for $\Upsilon$, which unfortunately also is on the low side in mass. The matrix element for $\q \qbar \to \g \g \g$ is (in lowest order) \cite{Kol78} \begin{equation} \frac{1}{\sigma_{\g \g \g}} \frac{\d \sigma_{\g \g \g}}{\d x_1 \, \d x_2} = \frac{1}{\pi^2 - 9} \left\{ \left( \frac{1-x_1}{x_2 x_3} \right)^2 + \left( \frac{1-x_2}{x_1 x_3} \right)^2 + \left( \frac{1-x_3}{x_1 x_2} \right)^2 \right\} ~, \label{ee:Upsilondec} \end{equation} where, as before, $x_i = 2 E_i / E_{\mrm{cm}}$ in the c.m. frame of the event. This is a well-defined expression, without the kind of singularities encountered in the $\q \qbar \g$ matrix elements. In principle, no cuts at all would be necessary, but for reasons of numerical simplicity we implement a $y$ cut as for continuum jet production, with all events not fulfilling this cut considered as (effective) $\g \g$ events. For $\g \g \g$ events, each $\g \g$ invariant mass is required to be at least 2 GeV. Another process is $\q \qbar \to \gamma \g \g$, obtained by replacing a gluon in $\q \qbar \to \g \g \g$ by a photon. This process has the same normalized cross section as the one above, if e.g. $x_1$ is taken to refer to the photon. The relative rate is \cite{Kol78} \begin{equation} \frac{\sigma_{\gamma \g \g}}{\sigma_{\g \g \g}} = \frac{36}{5} \, \frac{e_{\q}^2 \, \alphaem} {\alphas(Q^2)} ~. \end{equation} Here $e_{\q}$ is the charge of the heavy quark, and the scale in $\alphas$ has been chosen as the mass of the onium state. If the mass of the recoiling $\g \g$ system is lower than some cut-off (by default 2 GeV), the event is rejected. In the present implementation the angular orientation of the $\g \g \g$ and $\gamma \g \g$ events is given for the $\ee \to \gamma^* \to$ onium case \cite{Kol78} (optionally with beam polarization effects included), i.e. weak effects have not been included, since they are negligible at around 10~GeV. It is possible to start a perturbative shower evolution from either of the two states above. However, for $\Upsilon$ the phase space for additional evolution is so constrained that not much is to be gained from that. We therefore do not recommend this possibility. The shower generation machinery, when starting up from a $\gamma \g \g$ configuration, is constructed such that the photon energy is not changed. This means that there is currently no possibility to use showers to bring the theoretical photon spectrum in better agreement with the experimental one. In string fragmentation language, a $\g \g \g$ state corresponds to a closed string triangle with the three gluons at the corners. As the partons move apart from a common origin, the string triangle expands. Since the photon does not take part in the fragmentation, the $\gamma \g \g$ state corresponds to a double string running between the two gluons. \subsection{Routines and Common Block Variables} \label{ss:eeroutines} \subsubsection{$\ee$ continuum event generation} The only routine a normal user will call to generate $\ee$ continuum events is \ttt{LUEEVT}. The other routines listed below, as well as \ttt{LUSHOW} (see section \ref{ss:showrout}), are called by \ttt{LUEEVT}. \drawbox{CALL LUEEVT(KFL,ECM)}\label{p:LUEEVT} \begin{entry} \itemc{Purpose:} to generate a complete event $\ee \to \gammaZ \to \q\qbar \to$ parton shower $\to$ hadrons according to QFD and QCD cross sections. As an alternative to parton showers, second-order matrix elements are available for $\q\qbar + \q\qbar\g + \q\qbar\g\g + \q\qbar\q'\qbar'$ production. \iteme{KFL :} flavour of events generated. \begin{subentry} \iteme{= 0 :} mixture of all allowed flavours according to relevant probabilities. \iteme{= 1 - 8 :} primary quarks are only of the specified flavour \ttt{KFL}. \end{subentry} \iteme{ECM :} total c.m. energy of system. \itemc{Remark:} Each call generates one event, which is independent of preceding ones, with one exception, as follows. If radiative corrections are included, the shape of the hard photon spectrum is recalculated only with each \ttt{LUXTOT} call, which normally is done only if \ttt{KFL}, \ttt{ECM} or \ttt{MSTJ(102)} is changed. A change of e.g. the $\Z^0$ mass in mid-run has to be followed either by a user call to \ttt{LUXTOT} or by an internal call forced e.g. by putting \ttt{MSTJ(116)=3}. \end{entry} \boxsep \begin{entry} \iteme{SUBROUTINE LUXTOT(KFL,ECM,XTOT) :}\label{p:LUXTOT} to calculate the total hadronic cross section, including quark thresholds, weak, beam polarization, and QCD effects and radiative corrections. In the process, variables necessary for the treatment of hard photon radiation are calculated and stored. \begin{subentry} \iteme{KFL, ECM :} as for \ttt{LUEEVT}. \iteme{XTOT :} the calculated total cross section in nb. \end{subentry} \iteme{SUBROUTINE LURADK(ECM,MK,PAK,THEK,PHIK,ALPK) :}\label{p:LURADK} to describe initial-state hard $\gamma$ radiation. \iteme{SUBROUTINE LUXKFL(KFL,ECM,ECMC,KFLC) :}\label{p:LUXKFL} to generate the primary quark flavour in case this is not specified by the user. \iteme{SUBROUTINE LUXJET(ECM,NJET,CUT) :}\label{p:LUXJET} to determine the number of jets (2, 3 or 4) to be generated within the kinematically allowed region (characterized by \ttt{CUT} $= y_{\mrm{cut}}$) in the matrix-element approach; to be chosen such that all probabilities are between 0 and 1. \iteme{SUBROUTINE LUX3JT(NJET,CUT,KFL,ECM,X1,X2) :}\label{p:LUX3JT} to generate the internal momentum variables of a 3-jet event, $\q\qbar\g$, according to first- or second-order QCD matrix elements. \iteme{SUBROUTINE LUX4JT(NJET,CUT,KFL,ECM,KFLN,X1,X2,X4,X12,X14) :}% \label{p:LUX4JT} to generate the internal momentum variables for a 4-jet event, $\q\qbar\g\g$ or $\q\qbar\q'\qbar'$, according to second-order QCD matrix elements. \iteme{SUBROUTINE LUXDIF(NC,NJET,KFL,ECM,CHI,THE,PHI) :}\label{p:LUXDIF} to describe the angular orientation of the jets. In first-order QCD the complete QED or QFD formulae are used; in second order 3-jets are assumed to have the same orientation as in first, and 4-jets are approximated by 3-jets. \end{entry} \subsubsection{A routine for onium decay} In \ttt{LUONIA} we have implemented the decays of heavy onia resonances into three gluons or two gluons plus a photon, which are the dominant non-background-like decays of $\Upsilon$. \drawbox{CALL LUONIA(KFL,ECM)}\label{p:LUONIA} \begin{entry} \itemc{Purpose:} to simulate the process $\ee \to \gamma^* \to 1^{--}$ onium resonance $\to (\g\g\g$ or $\g\g\gamma) \to$ shower $\to$ hadrons. \iteme{KFL :} the flavour of the quark giving rise to the resonance. \begin{subentry} \iteme{= 0 :} generate $\g\g\g$ events alone. \iteme{= 1 - 8 :} generate $\g\g\g$ and $\g\g\gamma$ events in mixture determined by the squared charge of flavour \ttt{KFL}. Normally \ttt{KFL=} 5 or 6. \end{subentry} \iteme{ECM :} total c.m. energy of system. \end{entry} \subsubsection{Common block variables} The status codes and parameters relevant for the $\ee$ routines are found in the common block \ttt{LUDAT1}. This common block also contains more general status codes and parameters, described elsewhere. \drawbox{COMMON/LUDAT1/MSTU(200),PARU(200),MSTJ(200),PARJ(200)} \begin{entry} \itemc{Purpose:} to give access to a number of status codes and parameters regulating the performance of the $\ee$ event generation routines. \iteme{MSTJ(101) :}\label{p:MSTJ101} (D=5) gives the type of QCD corrections used for continuum events. \begin{subentry} \iteme{= 0 :} only $\q\qbar$ events are generated. \iteme{= 1 :} $\q\qbar + \q\qbar\g$ events are generated according to first-order QCD. \iteme{= 2 :} $\q\qbar + \q\qbar\g + \q\qbar\g\g + \q\qbar\q'\qbar'$ events are generated according to second-order QCD. \iteme{= 3 :} $\q\qbar + \q\qbar\g + \q\qbar\g\g + \q\qbar\q'\qbar'$ events are generated, but without second-order corrections to the 3-jet rate. \iteme{= 5 :} a parton shower is allowed to develop from an original $\q\qbar$ pair, see \ttt{MSTJ(40) - MSTJ(50)} for details. \iteme{= -1 :} only $\q\qbar\g$ events are generated (within same matrix-element cuts as for \ttt{=1}). Since the change in flavour composition from mass cuts or radiative corrections is not taken into account, this option is not intended for quantitative studies. \iteme{= -2 :} only $\q\qbar\g\g$ and $\q\qbar\q'\qbar'$ events are generated (as for \ttt{=2}). The same warning as for \ttt{=-1} applies. \iteme{= -3 :} only $\q\qbar\g\g$ events are generated (as for \ttt{=2}). The same warning as for \ttt{=-1} applies. \iteme{= -4 :} only $\q\qbar\q'\qbar'$ events are generated (as for \ttt{=2}). The same warning as for \ttt{=-1} applies. \itemc{Note 1:} \ttt{MSTJ(101)} is also used in \ttt{LUONIA}, with \iteme{$\leq$ 4 :} $\g\g\g + \gamma\g\g$ events are generated according to lowest-order matrix elements. \iteme{$\geq$ 5 :} a parton shower is allowed to develop from the original $\g\g\g$ or $\g\g\gamma$ configuration, see \ttt{MSTJ(40) - MSTJ(50)} for details. \itemc{Note 2:} The default values of fragmentation parameters have been chosen to work well with the default parton-shower approach above. If any of the other options are used, or if the parton shower is used in non-default mode, it may be necessary to retune fragmentation parameters. As an example, we note that the second-order matrix-element approach (\ttt{MSTJ(101)=2}) at PETRA/PEP energies gives a better description when the $a$ and $b$ parameters of the symmetric fragmentation function are set to $a =$\ttt{PARJ(41)=1}, $b =$\ttt{PARJ(42)=0.7}, and the width of the transverse momentum distribution to $\sigma =$\ttt{PARJ(21)=0.40}. In principle, one also ought to change the joining parameter to \ttt{PARJ(33)=PARJ(35)=1.1} to preserve a flat rapidity plateau, but if this should be forgotten, it does not make too much difference. For applications at TRISTAN or LEP, one must expect to have to change the matrix-element approach parameters even more, to make up for additional soft gluon effects not covered in this approach. \end{subentry} \iteme{MSTJ(102) :} (D=2) inclusion of weak effects ($\Z^0$ exchange) for flavour production, angular orientation, cross sections and initial-state photon radiation in continuum events. \begin{subentry} \iteme{= 1 :} QED, i.e. no weak effects are included. \iteme{= 2 :} QFD, i.e. including weak effects. \iteme{= 3 :} as \ttt{=2}, but at initialization in \ttt{LUXTOT} the $\Z^0$ width is calculated from $\ssintw$, $\alphaem$ and $\Z^0$ and quark masses (including bottom and top threshold factors for \ttt{MSTJ(103)} odd), assuming three full generations, and the result is stored in \ttt{PARJ(124)}. \end{subentry} \iteme{MSTJ(103) :} (D=7) mass effects in continuum matrix elements, in the form \ttt{MSTJ(103)} $= M_1 + 2M_2 + 4M_3$, where $M_i = 0$ if no mass effects and $M_i = 1$ if mass effects should be included. Here; \begin{subentry} \iteme{$M_1$ :} threshold factor for new flavour production according to QFD result; \iteme{$M_2$ :} gluon emission probability (only applies for \ttt{|MSTJ(101)|}$\leq 1$, otherwise no mass effects anyhow); \iteme{$M_3$ :} angular orientation of event (only applies for \ttt{|MSTJ(101)|}$\leq 1$ and \ttt{MSTJ(102)=1}, otherwise no mass effects anyhow). \end{subentry} \iteme{MSTJ(104) :} (D=5) number of allowed flavours, i.e. flavours that can be produced in a continuum event if the energy is enough. A change to 6 makes top production allowed above the threshold, etc. Note that in $\q\qbar\q'\qbar'$ events only the first five flavours are allowed in the secondary pair, produced by a gluon breakup. \iteme{MSTJ(105) :} (D=1) fragmentation and decay in \ttt{LUEEVT} and \ttt{LUONIA} calls. \begin{subentry} \iteme{= 0 :} no \ttt{LUEXEC} calls, i.e. only matrix-element and/or parton-shower treatment. \iteme{= 1 :} \ttt{LUEXEC} calls are made to generate fragmentation and decay chain. \iteme{= -1 :} no \ttt{LUEXEC} calls and no collapse of small jet systems into one or two particles (in \ttt{LUPREP}). \end{subentry} \iteme{MSTJ(106) :} (D=1) angular orientation in \ttt{LUEEVT} and \ttt{LUONIA}. \begin{subentry} \iteme{= 0 :} standard orientation of events, i.e. $\q$ along $+z$ axis and $\qbar$ along $-z$ axis or in $xz$ plane with $p_x > 0$ for continuum events, and $\g_1\g_2\g_3$ or $\gamma\g_2\g_3$ in $xz$ plane with $\g_1$ or $\gamma$ along the $+z$ axis for onium events. \iteme{= 1 :} random orientation according to matrix elements. \end{subentry} \iteme{MSTJ(107) :} (D=0) radiative corrections to continuum events. \begin{subentry} \iteme{= 0 :} no radiative corrections. \iteme{= 1 :} initial-state radiative corrections (including weak effects for \ttt{MSTJ(102)=} 2 or 3). \end{subentry} \iteme{MSTJ(108) :} (D=2) calculation of $\alphas$ for matrix-element alternatives. The \ttt{MSTU(111)} and \ttt{PARU(112)} values are automatically overwritten in \ttt{LUEEVT} or \ttt{LUONIA} calls accordingly. \begin{subentry} \iteme{= 0 :} fixed $\alphas$ value as given in \ttt{PARU(111)}. \iteme{= 1 :} first-order formula is always used, with $\Lambda_{\mrm{QCD}}$ given by \ttt{PARJ(121)}. \iteme{= 2 :} first- or second-order formula is used, depending on value of \ttt{MSTJ(101)}, with $\Lambda_{\mrm{QCD}}$ given by \ttt{PARJ(121)} or \ttt{PARJ(122)}. \end{subentry} \iteme{MSTJ(109) :} (D=0) gives a possibility to switch from QCD matrix elements to some alternative toy models. Is not relevant for shower evolution, \ttt{MSTJ(101)=5}, where one can use \ttt{MSTJ(49)} instead. \begin{subentry} \iteme{= 0 :} standard QCD scenario. \iteme{= 1 :} a scalar gluon model. Since no second-order corrections are available in this scenario, one can only use this with \ttt{MSTJ(101) = 1} or \ttt{-1}. Also note that the event-as-a-whole angular distribution is for photon exchange only (i.e. no weak effects), and that no higher-order corrections to the total cross section are included. \iteme{= 2 :} an Abelian vector gluon theory, with the colour factors $C_F = 1$ ($= 4/3$ in QCD), $N_C = 0$ ($= 3$ in QCD) and $T_R = 3 n_f$ ($= n_f/2$ in QCD). If one selects $\alpha_{\mrm{Abelian}} = (4/3) \alpha_{\mrm{QCD}}$, the 3-jet cross section will agree with the QCD one, and differences are to be found only in 4-jets. The \ttt{MSTJ(109)=2} option has to be run with \ttt{MSTJ(110)=1} and \ttt{MSTJ(111)=0}; if need be, the latter variables will be overwritten by the program. \\ {\bf Warning:} second-order corrections give a large negative contribution to the 3-jet cross section, so large that the whole scenario is of doubtful use. In order to make the second-order options work at all, the 3-jet cross section is here by hand set exactly equal to zero for \ttt{MSTJ(101)=2}. It is here probably better to use the option \ttt{MSTJ(101)=3}, although this is not a consistent procedure either. \end{subentry} \iteme{MSTJ(110) :} (D=2) choice of second-order contributions to the 3-jet rate. \begin{subentry} \iteme{= 1 :} the GKS second-order matrix elements, i.e. the old {\Je} standard. \iteme{= 2 :} the Zhu parametrization of the ERT matrix elements, based on the program of Kunszt and Ali, i.e. in historical sequence ERT/Kunszt/Ali/Zhu. The parametrization is available for $y =$ 0.01, 0.02, 0.03, 0.04 and 0.05. Values outside this range are put at the nearest border, while those inside it are given by a linear interpolation between the two nearest points. Since this procedure is rather primitive, one should try to work at one of the values given above. Note that no Abelian QCD parametrization is available for this option. \end{subentry} \iteme{MSTJ(111) :} (D=0) use of optimized perturbation theory for second-order matrix elements (it can also be used for first-order matrix elements, but here it only corresponds to a trivial rescaling of the $\alphas$ argument). \begin{subentry} \iteme{= 0 :} no optimization procedure; i.e. $Q^2 = E_{\mrm{cm}}^2$. \iteme{= 1 :} an optimized $Q^2$ scale is chosen as $Q^2 = f E_{\mrm{cm}}^2$, where $f =$\ttt{PARJ(128)} for the total cross section $R$ factor, while $f =$\ttt{PARJ(129)} for the 3- and 4-jet rates. This $f$ value enters via the $\alphas$, and also via a term proportional to $\alphas^2 \ln f$. Some constraints are imposed; thus the optimized `3-jet' contribution to $R$ is assumed to be positive (for \ttt{PARJ(128)}), the total 3-jet rate is not allowed to be negative (for \ttt{PARJ(129)}), etc. However, there is no guarantee that the differential 3-jet cross section is not negative (and truncated to 0) somewhere (this can also happen with $f = 1$, but is then less frequent). The actually obtained $f$ values are stored in \ttt{PARJ(168)} and \ttt{PARJ(169)}, respectively. If an optimized $Q^2$ scale is used, then the $\Lambda_{\mrm{QCD}}$ (and $\alphas$) should also be changed. With the value $f = 0.002$, it has been shown \cite{Bet89} that a $\Lambda_{\mrm{QCD}} = 0.100$ GeV gives a reasonable agreement; the parameter to be changed is \ttt{PARJ(122)} for a second-order running $\alphas$. Note that, since the optimized $Q^2$ scale is sometimes below the charm threshold, the effective number of flavours used in $\alphas$ may well be 4 only. If one feels that it is still appropriate to use 5 flavours (one choice might be as good as the other), it is necessary to put \ttt{MSTU(113)=5}. \end{subentry} \iteme{MSTJ(115) :} (D=1) documentation of continuum or onium events, in increasing order of completeness. \begin{subentry} \iteme{= 0 :} only the parton shower, the fragmenting partons and the generated hadronic system are stored in the \ttt{LUJETS} common block. \iteme{= 1 :} also a radiative photon is stored (for continuum events). \iteme{= 2 :} also the original $\ee$ are stored (with \ttt{K(I,1)=21}). \iteme{= 3 :} also the $\gamma$ or $\gammaZ$ exchanged for continuum events, the onium state for resonance events is stored (with \ttt{K(I,1)=21}). \end{subentry} \iteme{MSTJ(116) :} (D=1) initialization of total cross section and radiative photon spectrum in \ttt{LUEEVT} calls. \begin{subentry} \iteme{= 0 :} never; cannot be used together with radiative corrections. \iteme{= 1 :} calculated at first call and then whenever \ttt{KFL} or \ttt{MSTJ(102)} is changed or \ttt{ECM} is changed by more than \ttt{PARJ(139)}. \iteme{= 2 :} calculated at each call. \iteme{= 3 :} everything is reinitialized in the next call, but \ttt{MSTJ(116)} is afterwards automatically put \ttt{=1} for use in subsequent calls. \end{subentry} \iteme{MSTJ(119) :} (I) check on need to reinitialize \ttt{LUXTOT}. \iteme{MSTJ(120) :} (R) type of continuum event generated with the matrix-element option (with the shower one, the result is always \ttt{=1}). \begin{subentry} \iteme{= 1 :} $\q\qbar$. \iteme{= 2 :} $\q\qbar\g$. \iteme{= 3 :} $\q\qbar\g\g$ from Abelian (QED-like) graphs in matrix element. \iteme{= 4 :} $\q\qbar\g\g$ from non-Abelian (i.e. containing triple-gluon coupling) graphs in matrix element. \iteme{= 5 :} $\q\qbar\q'\qbar'$. \end{subentry} \iteme{MSTJ(121) :} (R) flag set if a negative differential cross section was encountered in the latest \ttt{LUX3JT} call. Events are still generated, but maybe not quite according to the distribution one would like (the rate is set to zero in the regions of negative cross section, and the differential rate in the regions of positive cross section is rescaled to give the `correct' total 3-jet rate). \boxsep \iteme{PARJ(121) :}\label{p:PARJ121} (D=1.0 GeV) $\Lambda$ value used in first-order calculation of $\alphas$ in the matrix-element alternative. \iteme{PARJ(122) :} (D=0.25 GeV) $\Lambda$ values used in second-order calculation of $\alphas$ in the matrix-element alternative. \iteme{PARJ(123) :} (D=91.187 GeV) mass of $\Z^0$ as used in propagators for the QFD case. \iteme{PARJ(124) :} (D=2.489 GeV) width of $\Z^0$ as used in propagators for the QFD case. Overwritten at initialization if \ttt{MSTJ(102)=3}. \iteme{PARJ(125) :} (D=0.01) $y_{\mrm{cut}}$, minimum squared scaled invariant mass of any two partons in 3- or 4-jet events; the main user-controlled matrix-element cut. \ttt{PARJ(126)} provides an additional constraint. For each new event, it is additionally checked that the total 3- plus 4-jet fraction does not exceed unity; if so the effective $y$ cut will be dynamically increased. The actual $y$-cut value is stored in \ttt{PARJ(150)}, event by event. \iteme{PARJ(126) :} (D=2. GeV) minimum invariant mass of any two partons in 3- or 4-jet events; a cut in addition to the one above, mainly for the case of a radiative photon lowering the hadronic c.m. energy significantly. \iteme{PARJ(127) :} (D=1. GeV) is used as a safety margin for small colour-singlet jet systems, cf. \ttt{PARJ(32)}, specifically $\q\qbar'$ masses in $\q\qbar\q'\qbar'$ 4-jet events and $\g\g$ mass in onium $\gamma\g\g$ events. \iteme{PARJ(128) :} (D=0.25) optimized $Q^2$ scale for the QCD $R$ (total rate) factor for the \ttt{MSTJ(111)=1} option is given by $Q^2 = f E_{\mrm{cm}}^2$, where $f =$\ttt{PARJ(128)}. For various reasons the actually used $f$ value may be increased compared with the nominal one; while \ttt{PARJ(128)} gives the nominal value, \ttt{PARJ(168)} gives the actual one for the current event. \iteme{PARJ(129) :} (D=0.002) optimized $Q^2$ scale for the 3- and 4-jet rate for the \ttt{MSTJ(111)=1} option is given by $Q^2 = f E_{\mrm{cm}}^2$, where $f =$\ttt{PARJ(129)}. For various reasons the actually used $f$ value may be increased compared with the nominal one; while \ttt{PARJ(129)} gives the nominal value, \ttt{PARJ(169)} gives the actual one for the current event. The default value is in agreement with the studies of Bethke \cite{Bet89}. \iteme{PARJ(131), PARJ(132) :} (D=2*0.) longitudinal polarizations $P_{\mrm{L}}^+$ and $P_{\mrm{L}}^-$ of incoming $\e^+$ and $\e^-$. \iteme{PARJ(133) :} (D=0.) transverse polarization $P_{\mrm{T}} = \sqrt{P_{\mrm{T}}^+ P_{\mrm{T}}^-}$, with $P_{\mrm{T}}^+$ and $P_{\mrm{T}}^-$ transverse polarizations of incoming $\e^+$ and $\e^-$. \iteme{PARJ(134) :} (D=0.) mean of transverse polarization directions of incoming $\e^+$ and $\e^-$, $\Delta \varphi = (\varphi^+ + \varphi^-) /2$, with $\varphi$ the azimuthal angle of polarization, leading to a shift in the $\varphi$ distribution of jets by $\Delta \varphi$. \iteme{PARJ(135) :} (D=0.01) minimum photon energy fraction (of beam energy) in initial-state radiation; should normally never be changed (if lowered too much, the fraction of events containing a radiative photon will exceed unity, leading to problems). \iteme{PARJ(136) :} (D=0.99) maximum photon energy fraction (of beam energy) in initial-state radiation; may be changed to reflect actual trigger conditions of a detector (but must always be larger than \ttt{PARJ(135)}). \iteme{PARJ(139) :} (D=0.2 GeV) maximum deviation of $E_{\mrm{cm}}$ from the corresponding value at last \ttt{LUXTOT} call, above which a new call is made if \ttt{MSTJ(116)=1}. \iteme{PARJ(141) :} (R) value of $R$, the ratio of continuum cross section to the lowest-order muon pair production cross section, as given in massless QED (i.e. three times the sum of active quark squared charges, possibly modified for polarization). \iteme{PARJ(142) :} (R) value of $R$ including quark-mass effects (for \ttt{MSTJ(102)=1}) and/or weak propagator effects (for \ttt{MSTJ(102)=2}). \iteme{PARJ(143) :} (R) value of $R$ as \ttt{PARJ(142)}, but including QCD corrections as given by \ttt{MSTJ(101)}. \iteme{PARJ(144) :} (R) value of $R$ as \ttt{PARJ(143)}, but additionally including corrections from initial-state photon radiation (if \ttt{MSTJ(107)=1}). Since the effects of heavy flavour thresholds are not simply integrable, the initial value of \ttt{PARJ(144)} is updated during the course of the run to improve accuracy. \iteme{PARJ(145) - PARJ(148) :} (R) absolute cross sections in nb as for the cases \ttt{PARJ(141) - PARJ(144)} above. \iteme{PARJ(150) :} (R) current effective matrix element cut-off $y_{\mrm{cut}}$, as given by \ttt{PARJ(125), PARJ(126)} and the requirements of having non-negative cross sections for 2-, 3- and 4-jet events. Not used in parton showers. \iteme{PARJ(151) :} (R) value of c.m. energy \ttt{ECM} at last \ttt{LUXTOT} call. \iteme{PARJ(152) :} (R) current first-order contribution to the 3-jet fraction; modified by mass effects. Not used in parton showers. \iteme{PARJ(153) :} (R) current second-order contribution to the 3-jet fraction; modified by mass effects. Not used in parton showers. \iteme{PARJ(154) :} (R) current second-order contribution to the 4-jet fraction; modified by mass effects. Not used in parton showers. \iteme{PARJ(155) :} (R) current fraction of 4-jet rate attributable to $\q\qbar\q'\qbar'$ events rather than $\q\qbar\g\g$ ones; modified by mass effects. Not used in parton showers. \iteme{PARJ(156) :} (R) has two functions when using second-order QCD. For a 3-jet event, it gives the ratio of the second-order to the total 3-jet cross section in the given kinematical point. For a 4-jet event, it gives the ratio of the modified 4-jet cross section, obtained when neglecting interference terms whose colour flow is not well defined, to the full unmodified one, all evaluated in the given kinematical point. Not used in parton showers. \iteme{PARJ(157) - PARJ(159) :} (I) used for cross-section calculations to include mass threshold effects to radiative photon cross section. What is stored is basic cross section, number of events generated and number that passed cuts. \iteme{PARJ(160) :} (R) nominal fraction of events that should contain a radiative photon. \iteme{PARJ(161) - PARJ(164) :} (I) give shape of radiative photon spectrum including weak effects. \iteme{PARJ(168) :} (R) actual $f$ value of current event in optimized perturbation theory for $R$; see \ttt{MSTJ(111)} and \ttt{PARJ(128)}. \iteme{PARJ(169) :} (R) actual $f$ value of current event in optimized perturbation theory for 3- and 4-jet rate; see \ttt{MSTJ(111)} and \ttt{PARJ(129)}. \iteme{PARJ(171) :} (R) fraction of cross section corresponding to the axial coupling of quark pair to the intermediate $\gammaZ$ state; needed for the Abelian gluon model 3-jet matrix element. \end{entry} \subsection{Examples} An ordinary $\ee$ annihilation event in the continuum, at a c.m. energy of 40 GeV, may be generated with \begin{verbatim} CALL LUEEVT(0,40.) \end{verbatim} In this case a $\q\qbar$ event is generated, including weak effects, followed by parton-shower evolution and fragmentation/decay treatment. Before a call to \ttt{LUEEVT}, however, a number of default values may be changed, e.g. \ttt{MSTJ(101)=2} to use second-order QCD matrix elements, giving a mixture of $\q\qbar$, $\q\qbar\g$, $\q\qbar\g\g$, and $\q\qbar\q'\qbar'$ events, \ttt{MSTJ(102)=1} to have QED only, \ttt{MSTJ(104)=6} to allow $\t\tbar$ production as well, \ttt{MSTJ(107)=1} to include initial-state photon radiation (including a treatment of the $\Z^0$ pole), \ttt{PARJ(123)=92.0} to change the $\Z^0$ mass, \ttt{PARJ(81)=0.3} to change the parton-shower $\Lambda$ value, or \ttt{PARJ(82)=1.5} to change the parton-shower cut-off. If initial-state photon radiation is used, some restrictions apply to how one can alternate the generation of events at different energies or with different $\Z^0$ mass, etc. These restrictions are not there for efficiency reasons (the extra time for recalculating the extra constants every time is small), but because it ties in with the cross-section calculations (see \ttt{PARJ(144)}). Most parameters can be changed independently of each other. However, if just one or a few parameters/switches are changed, one should not be surprised to find a rather bad agreement with the data, like e.g. a too low or high average hadron multiplicity. It is therefore usually necessary to retune one parameter related to the perturbative QCD description, like $\alphas$ or $\Lambda$, one of the two parameters $a$ and $b$ of the Lund symmetric fragmentation function (since they are so strongly correlated, it is often not necessary to retune both of them), and the average fragmentation transverse momentum --- see Note~2 of the \ttt{MSTJ(101)} description for an example. For very detailed studies it may be necessary to retune even more parameters. The three-gluon and gluon--gluon--photon decays of $\Upsilon$ may be simulated by a call \begin{verbatim} CALL LUONIA(5,9.46) \end{verbatim} Unfortunately, with present top-mass limits, this routine will not be of much interest for toponium studies (weak decays will dominate). A typical program for analysis of $\ee$ annihilation events at 100 GeV might look something like \begin{verbatim} COMMON/LUJETS/N,K(4000,5),P(4000,5),V(4000,5) COMMON/LUDAT1/MSTU(200),PARU(200),MSTJ(200),PARJ(200) COMMON/LUDAT2/KCHG(500,3),PMAS(500,4),PARF(2000),VCKM(4,4) COMMON/LUDAT3/MDCY(500,3),MDME(2000,2),BRAT(2000),KFDP(2000,5) MDCY(LUCOMP(111),1)=0 ! put pi0 stable MSTJ(107)=1 ! include initial-state radiation PARU(41)=1. ! use linear sphericity ..... ! other desired changes ..... ! initialize analysis statistics DO 100 IEVENT=1,1000 ! loop over events CALL LUEEVT(0,100.) ! generate new event IF(IEVENT.EQ.1) CALL LULIST(2) ! list first event CALL LUTABU(11) ! save particle composition ! statistics CALL LUEDIT(2) ! remove decayed particles CALL LUSPHE(SPH,APL) ! linear sphericity analysis IF(SPH.LT.0.) GOTO 100 ! too few particles in event for ! LUSPHE to work on it (unusual) CALL LUEDIT(31) ! orient event along axes above IF(IEVENT.EQ.1) CALL LULIST(2) ! list first treated event ..... ! fill analysis statistics CALL LUTHRU(THR,OBL) ! now do thrust analysis ..... ! more analysis statistics 100 CONTINUE ! CALL LUTABU(12) ! print particle composition ! statistics ..... ! print analysis statistics END \end{verbatim} \clearpage \section{Process Generation in PYTHIA} \label{s:PYTprocgen} Much can be said about the hard processes in {\Py} and the way they are generated. Therefore the material has been split into three sections. In the current one the philo\-sophy underlying the event generation scheme is presented. Here we provide a generic description, where some special cases are swept under the carpet. In the next section, the existing processes are enumerated, with some comments about applications and limitations. Finally, in the third section the generation routines and common block switches are described. The section starts with a survey of parton distributions, followed by a detailed description of the simple $2 \to 2$ and $2 \to 1$ hard subprocess generation schemes, including pairs of resonances. This is followed by a few comments on more complicated configurations. \subsection{Parton Distributions} \label{ss:structfun} The parton-distribution function $f_i^a(x,Q^2)$ parametrizes the probability to find a parton $i$ with a fraction $x$ of the beam energy when the beam particle $a$ is probed by a hard scattering at virtuality scale $Q^2$. Usually the momentum-weighted combination $x f_i^a(x,Q^2)$ is used, for which the normalization condition $\sum_i \int_0^1 dx \, x f_i^a(x,Q^2) \equiv 1$ normally applies. The $Q^2$ dependence of parton distributions is perturbatively calculable, see section \ref{sss:initshowstruc}. The parton distributions in {\Py} come in many shapes, as shown in the following. \subsubsection{Baryons} For protons, many sets exist on the market. These are obtained by fits to experimental data, constrained so that the $Q^2$ dependence is in accordance with the standard QCD evolution equations. The (new) default in \tsc{Pythia} is CTEQ2L \cite{Bot93}, a modern leading-order fit. Ten other sets are found in \tsc{Pythia}. The complete list is: \begin{Itemize} \item EHLQ sets 1 and 2 \cite{Eic84}; \item DO sets 1 and 2 \cite{Duk82}; \item the other CTEQ2 fits, namely CTEQ2M, CTEQ2MS, CTEQ2MF, CTEQ2ML, and CTEQ2D \cite{Bot93}; and \item the dynamically generated fit GRV LO (updated version) \cite{Glu92}. \end{Itemize} Of these, EHLQ, DO, CTEQ2L and GRV LO are leading-order parton distributions, while CTEQ2D are in the next-to-leading-order DIS scheme and the rest in the next-to-leading order $\br{\mrm{MS}}$ scheme. The EHLQ and DO sets are by now rather old, and are kept mainly for backwards compatibility. Since only Born-level matrix elements are included in the program, there is no particular reason to use higher-order parton distributions --- the resulting combination is anyway only good to leading-order accuracy. (Some higher-order corrections are effectively included by the parton-shower treatment, but there is no exact match.) There is a steady flow of new parton-distribution sets on the market. To keep track of all of them is a major work on its own. Therefore {\Py} contains an interface to an external library of parton distribution functions, \tsc{Pdflib} \cite{Plo93}. This is a truly encyclopedic collection of almost all proton, pion and photon parton distributions proposed since the late 70's. Two dummy routines come with the {\Py} package, so as to avoid problems with unresolved external references if \tsc{Pdflib} is not linked. One should also note that {\Py} does not check the results, but assumes that sensible answers will be returned, also outside the nominal $(x, Q^2)$ range of a set. Only the sets that come with {\Py} have been suitably modified to provide reasonable answers outside their nominal domain of validity. From the proton parton distributions, those of the neutron are obtained by isospin conjugation, i.e. $f_{\u}^{\n} = f_{\d}^{\p}$ and $f_{\d}^{\n} = f_{\u}^{\p}$. The program does allow for incoming beams of a number of hyperons: $\Lambda^0$, $\Sigma^{-,0,+}$, $\Xi^{-,0}$ and $\Omega^-$. Here one has essentially no experimental information. One could imagine to construct models in which valence $\s$ quarks are found at larger average $x$ values than valence $\u$ and $\d$ ones, because of the larger $\s$-quark mass. However, hyperon beams is a little-used part of the program, included only for a few specific studies. Therefore a simple approach has been taken, in which an average valence quark distribution is constructed as $f_{\mrm{val}} = (f_{\u,\mrm{val}}^{\p} + f_{\d,\mrm{val}}^{\p})/3$, according to which each valence quark in a hyperon is assumed to be distributed. Sea-quark and gluon distributions are taken as in the proton. Any proton parton distribution set may be used with this procedure. \subsubsection{Mesons and photons} Data on meson parton distributions are scarce, so only very few sets have been constructed, and only for the $\pi^{\pm}$. {\Py} contains the Owens set 1 and 2 parton distributions \cite{Owe84}, which for a long time were essentially the only sets on the market, and the more recent dynamically generated GRV LO (updated version) \cite{Glu92a}. The first one is the default in {\Py}. Further sets are found in \tsc{Pdflib} and can therefore be used by {\Py}, just as described above for protons. Sets of photon parton distributions have been obtained as for hadrons; an additional complication comes from the necessity to handle the matching of the vector meson dominance (VMD) and the perturbative pieces in a consistent manner. New sets have been produced where this division is explicit and therefore especially well suited for applications to event generation\cite{Sch95}. The Schuler and Sj\"ostand set 1D is the default. Although the vector-meson philosophy is at the base, the details of the fits do not rely on pion data, but only on $F_2^{\gamma}$ data. Here follows a brief summary of relevant details. Photons obey a set of inhomogeneous evolution equations, where the inhomogeneous term is induced by $\gamma \to \q\qbar$ branchings. The solution can be written as the sum of two terms, \begin{equation} f_a^{\gamma}(x,Q^2) = f_a^{\gamma,\mrm{NP}}(x,Q^2;Q_0^2) + f_a^{\gamma,\mrm{PT}}(x,Q^2;Q_0^2) ~, \end{equation} where the former term is a solution to the homogeneous evolution with a (non-perturbative) input at $Q=Q_0$ and the latter is a solution to the full inhomogeneous equation with boundary condition $f_a^{\gamma,\mrm{PT}}(x,Q_0^2;Q_0^2) \equiv 0$. One possible physics interpretation is to let $f_a^{\gamma,\mrm{NP}}$ correspond to $\gamma \leftrightarrow V$ fluctuations, where $V = \rho^0, \omega, \phi, \ldots$ is a set of vector mesons, and let $f_a^{\gamma,\mrm{PT}}$ correspond to perturbative (`anomalous') $\gamma \leftrightarrow \q\qbar$ fluctuations. The discrete spectum of vector mesons can be combined with the continuous (in virtuality $k^2$) spectrum of $\q\qbar$ fluctuations, to give \begin{equation} f_a^{\gamma}(x,Q^2) = \sum_V \frac{4\pi\alphaem}{f_V^2} f_a^{\gamma,V}(x,Q^2) + \frac{\alphaem}{2\pi} \, \sum_{\q} 2 e_{\q}^2 \, \int_{Q_0^2}^{Q^2} \frac{{\d} k^2}{k^2} \, f_a^{\gamma,\q\qbar}(x,Q^2;k^2) ~, \end{equation} where each component $f^{\gamma,V}$ and $f^{\gamma,\q\qbar}$ obeys a unit momentum sum rule. In sets 1 the $Q_0$ scale is picked at a low value, 0.6~GeV, where an identification of the non-perturbative component with a set of low-lying mesons appear natural, while sets 2 use a higher value, 2~GeV, where the validity of perturbation theory is better established. The data are not good enough to allow a precise determination of $\Lambda_{\mrm{QCD}}$. Therefore we use a fixed value $\Lambda^{(4)} = 200$~MeV, in agreement with conventional results for proton distributions. In the VMD component the $\rho^0$ and $\omega$ have been added coherently, so that $\u\ubar : \d\dbar = 4 : 1$ at $Q_0$. Unlike the $\p$, the $\gamma$ has a direct component where the photon acts as an unresolved probe. In the definition of $F_2^{\gamma}$ this adds a component $C^{\gamma}$, symbolically \begin{equation} F_2^{\gamma}(x,Q^2) = \sum_{\q} e_{\q}^2 \left[ f_{\q}^{\gamma} + f_{\qbar}^{\gamma} \right] \otimes C_{\q} + f_{\g}^{\gamma} \otimes C_{\g} + C^{\gamma} ~. \end{equation} Since $C^{\gamma} \equiv 0$ in leading order, and since we stay with leading-order fits, it is permissible to neglect this complication. Numerically, however, it makes a non-negligible difference. We therefore make two kinds of fits, one DIS type with $C^{\gamma} = 0$ and one {\MSbar} type including the universal part of $C^{\gamma}$. When jet production is studied for real incoming photons, the standard evolution approach is reasonable also for heavy flavours, i.e. predominantly the $\c$, but with a lower cut-off $Q_0 \approx m_{\c}$ for $\gamma \to \c\cbar$. Moving to deep inelastic scattering, $\e\gamma \to \e X$, there is an extra kinematical constraint: $W^2 = Q^2 (1-x)/x > 4 m_{\c}^2$. It is here better to use the `Bethe-Heitler' cross section for $\gamma^* \gamma \to \c\cbar$. Therefore each distribution appears in two variants. For applications to real $\gamma$'s the parton distributions are calculated as the sum of a vector-meson part and an anomalous part including all five flavours. For applications to DIS, the sum runs over the same vector-meson part, an anomalous part and possibly a $C^{\gamma}$ part for the three light flavours, and a Bethe-Heitler part for $\c$ and $\b$. In addition to the SaS sets, {\Py} also contains the Drees--Grassie set of parton distributions \cite{Dre85} and, as for the proton, there is an interface to the \tsc{Pdflib} library \cite{Plo93}. However, these sets do not allow a subdivision of the photon parton distributions into one VMD part and one anomalous part. This subdivision is necessary a sophisticated modelling of $\gamma\p$ and $\gamma\gamma$ events, see above and section \ref{sss:photoprod}. As an alternative, for the VMD part alone, the $\rho^0$ parton distribution can be found from the assumed equality \begin{equation} f^{\rho^0}_i = f^{\pi^0}_i = \frac{1}{2} \, (f^{\pi^+}_i + f^{\pi^-}_i) ~. \end{equation} Thus any $\pi^+$ parton distribution set, from any library, can be turned into a VMD $\rho^0$ set. The $\omega$ parton distribution is assumed the same, while the $\phi$ and $\Jpsi$ ones are handled in the very crude approximation $f^{\phi}_{\s,\mrm{val}} = f^{\pi^+}_{\u,\mrm{val}}$ and $f^{\phi}_{\mrm{sea}} = f^{\pi^+}_{\mrm{sea}}$. therefore is default. The VMD part needs to be complemented by an anomalous part to make upp a full photon distribution. The latter is fully perturbatively calculable, given the lower cut-off scale $Q_0$. The SaS parametrization of the anomalous part is therefore used throughout for this purpose. The $Q_0$ scale can be set freely in the \ttt{PARP(15)} parameter. The $f_i^{\gamma,\mrm{anom}}$ distribution can be further decomposed, by the flavour and the $\pT$ of the original branching $\gamma \to \q\qbar$. The flavour is distributed according to squared charge (plus flavour thresholds for heavy flavours) and the $\pT$ according to $\d \pT^2 / \pT^2$ in the range $Q_0 < \pT < Q$. At the branching scale, the photon only consists of a $\q\qbar$ pair, with $x$ distribution $\propto x^2 + (1-x)^2$. A component $f_a^{\gamma,\q\qbar}(x,Q^2;k^2)$, characterized by its $k \approx \pT$ and flavour, then is evolved homogeneously from $\pT$ to $Q$. For theoretical studies it is convenient to be able to access a specific component of this kind. Therefore also leading-order parametrizations of these decomposed distributions are available \cite{Sch95}. \subsubsection{Leptons} \label{sss:estructfun} Contrary to the hadron case, there is no necessity to introduce the parton-distribution function concept for leptons. A lepton can be considered as a point-like particle, with initial-state radiation handled by higher-order matrix elements. However, the parton distribution function approach offers a slightly simplified but very economical description of initial-state radiation effects for any hard process, also those for which higher-order corrections are not yet calculated. Parton distributions for electrons have been introduced in {\Py}, but not yet for muons, i.e. currently $f_{\mu}^{\mu}(x, Q^2) = \delta (x-1)$. Also for the electron one is free to use a simple `unresolved' $\e$, $f_{\e}^{\e}(x, Q^2) = \delta(x-1)$, where the $\e$ retains the full original momentum. Electron parton distributions are calculable entirely from first principles, but different levels of approximation may be used. The parton-distribution formulae in {\Py} are based on a next-to-leading-order exponentiated description, see ref. \cite{Kle89}, p. 34. The approximate behaviour is \begin{eqnarray} & & f_{\e}^{\e}(x,Q^2) \approx \frac{\beta}{2} (1-x)^{\beta/2-1} ~; \nonumber \\ & & \beta = \frac{2 \alphaem}{\pi} \left( \ln \frac{Q^2}{m_{\e}^2} -1 \right) ~. \end{eqnarray} The form is divergent but integrable for $x \to 1$, i.e. the electron likes to keep most of the energy. To handle the numerical precision problems for $x$ very close to unity, the parton distribution is set, by hand, to zero for $x > 0.999999$, and is rescaled upwards in the range $0.9999 < x < 0.999999$, in such a way that the total area under the parton distribution is preserved: \begin{equation} \left( f_{\e}^{\e}(x,Q^2) \right)_{\mrm{mod}} = \left\{ \begin{array}{ll} f_{\e}^{\e}(x,Q^2) & 0 \leq x \leq 0.9999 \\[2mm] \frac{\displaystyle 100^{\beta/2}}{\displaystyle 100^{\beta/2}-1} \, f_{\e}^{\e}(x,Q^2) & 0.9999 < x \leq 0.999999 \\[4mm] 0 & x > 0.999999 \, ~. \end{array} \right. \end{equation} The branchings $\e \to \e \gamma$, which are responsible for the softening of the $f_{\e}^{\e}$ parton distribution, also gives rise to a flow of photons. In photon-induced hard processes, the $f_{\gamma}^{\e}$ parton distribution can be used to describe the equivalent flow of photons. The formula used in the program is the simple first-order expression. There is some ambiguity in the choice of $Q^2$ range over which emissions should be included. The na\"{\i}ve (default) choice is \begin{equation} f_{\gamma}^{\e}(x,Q^2) = \frac{\alphaem}{2 \pi} \, \frac{1+(1-x)^2}{x} \, \ln \left( \frac{Q^2}{m_{\e}^2} \right) ~. \end{equation} Here it is assumed that only one scale enters the problem, namely that of the hard interaction, and that the scale of the branching $\e \to \e \gamma$ is bounded from above by the hard interaction scale. For a pure QCD or pure QED shower this is an appropriate procedure, cf. section \ref{sss:showermatching}, but in other cases it may not be optimal. In particular, for photoproduction the alternative that is probably most appropriate is \cite{Ali88}: \begin{equation} f_{\gamma}^{\e}(x,Q^2) = \frac{\alphaem}{2 \pi} \, \frac{1+(1-x)^2}{x} \, \ln \left( \frac{Q^2_{\mmax} (1-x)}{m_{\e}^2 \, x^2} \right) ~. \end{equation} Here $Q^2_{\mmax}$ is a user-defined cut for the range of scattered electron kinematics that is counted as photoproduction. Note that we now deal with two different $Q^2$ scales, one related to the hard subprocess itself, which appears as the argument of the parton distribution, and the other related to the scattering of the electron, which is reflected in $Q^2_{\mmax}$. In resolved photoproduction or resolved $\gamma\gamma$ interactions, one has to include the parton distributions for quarks and gluons inside the photon inside the electron. There are no published sets where results are directly presented in terms of quark and gluon distributions inside the electron. In the program, the $f_{\q,\g}^{\e}$ are therefore obtained by a numerical convolution according to \begin{equation} f_{\q,\g}^{\e}(x, Q^2) = \int_x^1 \frac{dx_{\gamma}}{x_{\gamma}} \, f_{\gamma}^{\e}(x_{\gamma}, Q^2) \, f^{\gamma}_{\q,\g} \! \left( \frac{x}{x_{\gamma}}, Q^2 \right) ~, \label{pg:foldqgine} \end{equation} with $f^{\e}_{\gamma}$ as discussed above. The necessity for numerical convolution makes this parton distribution evaluation rather slow compared with the others; one should therefore only have it switched on for resolved photoproduction studies. One can obtain the positron distribution inside an electron, which is also the electron sea parton distribution, by a convolution of the two branchings $\e \to \e \gamma$ and $\gamma \to \ee$; the result is \cite{Che75} \begin{equation} f_{\e^+}^{\e^-}(x,Q^2) = \frac{1}{2} \, \left\{ \frac{\alphaem}{2 \pi} \, \left( \ln \frac{Q^2}{m_{\e}^2} -1 \right) \right\}^2 \, \frac{1}{x} \, \left( \frac{4}{3} - x^2 - \frac{4}{3} x^3 + 2x(1+x) \ln x \right) ~. \end{equation} Finally, the program also contains the distribution of a transverse $\W^-$ inside an electron \begin{equation} f_{\W}^{\e}(x,Q^2) = \frac{\alphaem}{2 \pi} \, \frac{1}{4 \ssintw} \, \frac{1+(1-x)^2}{x} \, \ln \left( 1 + \frac{Q^2}{m_{\W}^2} \right) ~. \end{equation} \subsection{Kinematics and Cross section for a $2 \to 2$ Process} \label{ss:kinemtwo} In this section we begin the description of kinematics selection and cross-section calculation. The example is for the case of a $2 \to 2$ process, with final-state masses assumed to be vanishing. Later on we will expand to finite fixed masses, and to resonances. Consider two incoming beam particles in their c.m. frame, each with energy $E_{\mrm{beam}}$. The total squared c.m. energy is then $s = 4 E_{\mrm{beam}}^2$. The two partons that enter the hard interaction do not carry the total beam momentum, but only fractions $x_1$ and $x_2$, respectively, i.e. they have four-momenta \begin{eqnarray} p_1 & = & E_{\mrm{beam}}(x_1; 0, 0, x_1) ~, \nonumber \\ p_2 & = & E_{\mrm{beam}}(x_2; 0, 0, -x_2) ~. \end{eqnarray} There is no reason to put the incoming partons on the mass shell, i.e. to have time-like incoming four-vectors, since partons inside a particle are always virtual and thus space-like. These space-like virtualities are introduced as part of the initial-state parton-shower description, see section \ref{sss:initshowtrans}, but do not affect the formalism of this section. The one example where it would be appropriate to put a parton on the mass shell is for an incoming lepton beam, but even here the massless kinematics description is adequate as long as the c.m. energy is correctly calculated with masses. The squared invariant mass of the two partons is defined as \begin{equation} \hat{s} = (p_1 + p_2)^2 = x_1 \, x_2 \, s ~. \end{equation} Instead of $x_1$ and $x_2$, it is often customary to use $\tau$ and either $y$ or $x_{\mrm{F}}$: \begin{eqnarray} \tau & = & x_1 x_2 = \frac{\hat{s}}{s} ~; \\ y & = & \frac{1}{2} \ln \frac{x_1}{x_2} ~; \\ x_{\mrm{F}} & = & x_1 - x_2 ~. \end{eqnarray} In addition to $x_1$ and $x_2$, two additional variables are needed to describe the kinematics of a scattering $1 + 2 \to 3 + 4$. One corresponds to the azimuthal angle $\varphi$ of the scattering plane around the beam axis. This angle is always isotropically distributed for unpolarized incoming beam particles, and so need not be considered further. The other variable can be picked as $\hat{\theta}$, the polar angle of parton 3 in the c.m. frame of the hard scattering. The conventional choice is to use the variable \begin{equation} \hat{t} = (p_1 - p_3)^2 = (p_2 - p_4)^2 = - \frac{\hat{s}}{2} (1 - \cos \hat{\theta}) ~, \end{equation} with $\hat{\theta}$ defined as above. In the following, we will make use of both $\hat{t}$ and $\hat{\theta}$. It is also customary to define $\hat{u}$, \begin{equation} \hat{u} = (p_1 - p_4)^2 = (p_2 - p_3)^2 = - \frac{\hat{s}}{2} (1 + \cos \hat{\theta}) ~, \end{equation} but $\hat{u}$ is not an independent variable since \begin{equation} \hat{s} + \hat{t} + \hat{u} = 0 ~. \end{equation} If the two outgoing particles have masses $m_3$ and $m_4$, respectively, then the four-momenta in the c.m. frame of the hard interaction are given by \begin{equation} \hat{p}_{3,4} = \left( \frac{\hat{s} \pm (m_3^2-m_4^2)}{2\sqrt{\hat{s}}} , \pm \frac{\sqrt{\hat{s}}}{2} \, \beta_{34} \sin \hat{\theta}, 0, \pm \frac{\sqrt{\hat{s}}}{2} \, \beta_{34} \cos \hat{\theta} \right) ~, \end{equation} where \begin{equation} \beta_{34} = \sqrt{ \left( 1 - \frac{m_3^2}{\hat{s}} - \frac{m_4^2}{\hat{s}} \right)^2 - 4 \, \frac{m_3^2}{\hat{s}} \, \frac{m_4^2}{\hat{s}} } ~. \end{equation} Then $\hat{t}$ and $\hat{u}$ are modified to \begin{equation} \hat{t}, \hat{u} = - \frac{1}{2} \left\{ ( \hat{s} - m_3^2 - m_4^2 ) \mp \hat{s} \, \beta_{34} \cos \hat{\theta} \right\} ~, \end{equation} with \begin{equation} \hat{s} + \hat{t} + \hat{u} = m_3^2 + m_4^2 ~. \end{equation} The cross section for the process $1 + 2 \to 3 + 4$ may be written as \begin{eqnarray} \sigma & = & \int \int \int \d x_1 \, \d x_2 \, \d \hat{t} \, f_1(x_1, Q^2) \, f_2(x_2, Q^2) \, \frac{\d \hat{\sigma}}{\d \hat{t}} \nonumber \\ & = & \int \int \int \frac{\d \tau}{\tau} \, \d y \, \d \hat{t} \, x_1 f_1(x_1, Q^2) \, x_2 f_2(x_2, Q^2) \, \frac{\d \hat{\sigma}}{\d \hat{t}} ~. \label{pg:sigma} \end{eqnarray} The choice of $Q^2$ scale is ambiguous, and several alternatives are available in the program. For massless outgoing particles the default is the squared transverse momentum \begin{equation} Q^2 = \hat{p}_{\perp}^2 = \frac{\hat{s}}{4} \sin^2\hat{\theta} = \frac{\hat{t}\hat{u}}{\hat{s}} ~, \end{equation} which is modified to \begin{equation} Q^2 = \frac{1}{2} (m_{\perp 3}^2 + m_{\perp 4}^2) = \frac{1}{2} (m_3^2 + m_4^2) + \hat{p}_{\perp}^2 = \frac{1}{2} (m_3^2 + m_4^2) + \frac{\hat{t} \hat{u} - m_3^2 m_4^2}{\hat{s}} \end{equation} when masses are introduced. The mass term is selected such that, for $m_3 = m_4 = m$, the expression reduces to the squared transverse mass, $Q^2 = \hat{m}_{\perp}^2 = m^2 + \hat{p}_{\perp}^2$. The $\d \hat{\sigma}/\d \hat{t}$ expresses the differential cross section for a scattering, as a function of the kinematical quantities $\hat{s}$, $\hat{t}$ and $\hat{u}$. It is in this function that the physics of a given process resides. The performance of a machine is measured in terms of its luminosity $\cal L$, which is directly proportional to the number of particles in each bunch and to the bunch crossing frequency, and inversely proportional to the area of the bunches at the collision point. For a process with a $\sigma$ as given by eq.~(\ref{pg:sigma}), the differential event rate is given by $\sigma {\cal L}$, and the number of events collected over a given period of time \begin{equation} N = \sigma \, \int {\cal L} \, \d t ~. \end{equation} The program does not calculate the number of events, but only the integrated cross sections. \subsection{Resonance Production} \label{ss:kinemreson} The simplest way to produce a resonance is by a $2 \to 1$ process. If the decay of the resonance is not considered, the cross-section formula does not depend on $\hat{t}$, but takes the form \begin{equation} \sigma = \int \int \frac{\d \tau}{\tau} \, \d y \, x_1 f_1(x_1, Q^2) \, x_2 f_2(x_2, Q^2) \, \hat{\sigma}(\hat{s}) ~. \label{pg:sigmares} \end{equation} Here the physics is contained in the cross section $\hat{\sigma}(\hat{s})$. The $Q^2$ scale is usually taken to be $Q^2 = \hat{s}$. In published formulae, cross sections are often given in the zero-width approximation, i.e. $\hat{\sigma}(\hat{s}) \propto \delta (\hat{s} - m_R^2)$, where $m_R$ is the mass of the resonance. Introducing the scaled mass $\tau_R = m_R^2/s$, this corresponds to a delta function $\delta (\tau - \tau_R)$, which can be used to eliminate the integral over $\tau$. However, what we normally want to do is replace the $\delta$ function by the appropriate Breit--Wigner shape. For a resonance width $\Gamma_R$ this is achieved by the replacement \begin{equation} \delta (\tau - \tau_R) \to \frac{s}{\pi} \, \frac{m_R \Gamma_R}{(s \tau - m_R^2)^2 + m_R^2 \Gamma_R^2} ~. \label{pg:resshapeone} \end{equation} In this formula the resonance width $\Gamma_R$ is a constant. An improved description of resonance shapes is obtained if the width is made $\hat{s}$-dependent (occasionally also referred to as mass-dependent width, since $\hat{s}$ is not always the resonance mass), see e.g. \cite{Ber89}. To first approximation, this means that the expression $m_R \Gamma_R$ is to be replaced by $\hat{s} \Gamma_R / m_R$. To be more precise, in the program the quantity $H_R(\hat{s})$ is introduced, and the Breit--Wigner is written as \begin{equation} \delta (\tau - \tau_R) \to \frac{s}{\pi} \, \frac{H_R(s \tau)}{(s \tau - m_R^2)^2 + H_R^2(s \tau)} ~. \label{pg:resshapetwo} \end{equation} The $H_R$ factor is evaluated as a sum over all possible final-state channels, $H_R = \sum_f H_R^{(f)}$. Each decay channel may have its own $\hat{s}$ dependence, as follows. A decay to a fermion pair, $R \to \f \fbar$, gives no contribution below threshold, i.e. for $\hat{s} < 4 m_{\f}^2$. Above threshold, $H_R^{(f)}$ is proportional to $\hat{s}$, multiplied by a threshold factor $\beta (3 - \beta^2)/2$ for the vector part of a spin 1 resonance, by $\beta^3$ for the axial vector part, and again by $\beta^3$ for a spin 0 resonance. Here $\beta = \sqrt{1 - 4m_{\f}^2/\hat{s}}$. For the decay into unequal masses, e.g. of the $\W^+$, corresponding but more complicated expressions are used. For decays into a quark pair, the universal first-order strong correction factor $1 + \alphas(\hat{s}) / \pi$ is included in $H_R^{(f)}$. The second-order corrections are often known, but then are specific to each resonance, and are not included. An option exists for the $\gamma/\Z^0/\Z'^0$ resonances, where threshold effects due to $\q\qbar$ bound-state formation are taken into account in a smeared-out, average sense, see eq.~(\ref{pp:threshenh}). For other decay channels, not into fermion pairs, the $\hat{s}$ dependence is typically more complicated. For instance, the decay $\H^0 \to \W^+ \W^-$ has a partial width proportional to $\hat{s}^2$, with a threshold factor $\beta^3$. Since a Higgs with $m_{\H} < 2 m_{\W}$ could still decay in this channel, it is in fact necessary to perform a two-dimensional integral over the $W^{\pm}$ Breit--Wigner mass distributions to obtain the correct result (and this has to be done numerically, at least in part). Fortunately, a Higgs particle lighter than $2 m_{\W}$ is sufficiently narrow that the integral only needs to be performed once and for all at initialization (whereas most other partial widths are recalculated whenever needed). Channels that proceed via loops, such as $\H \to \g \g$, also display complicated threshold behaviours. The coupling structure within the electroweak sector is usually (re)expressed in terms of gauge boson masses, $\alphaem$ and $\ssintw$, i.e. factors of $G_{\F}$ are replaced according to \begin{equation} \sqrt{2} G_{\F} = \frac{\pi \, \alphaem}{\ssintw \, m_{\W}^2} ~. \end{equation} Having done that, $\alphaem$ is allowed to run \cite{Kle89}, and is evaluated at the $\hat{s}$ scale. Thereby the relevant electroweak loop correction factors are recovered at the $m_{\W}/m_{\Z}$ scale. However, the option exists to go the other way and eliminate $\alpha_em$ in favour of $G_{\F}$. Currently $\ssintw$ is not allowed to run. For the Higgs particle, the couplings to fermions are proportional to the fermion masses; then also the masses are evaluated at the $\hat{s}$ scale. In summary, we see that an $\hat{s}$ dependence may enter several different ways into the $H_R^{(f)}$ expressions from which the total $H_R$ is built up. Also note that, with the exception of the term $(\s \tau - m_R^2)^2$ in the denominator of the Breit--Wigner, no memory remains of the nominal $m_R$ mass: everywhere else, what enters is the actual resonance mass $\sqrt{\hat{s}}$. When only decays to a specific final state $f$ are considered, the $H_R$ in the denominator remains the sum over all allowed decay channels, but the numerator only contains the $H_R^{(f)}$ term of the final state considered. If the combined production and decay process $i \to R \to f$ is considered, the same $\hat{s}$ dependence is implicit in the coupling structure of $i \to R$ as one would have had in $R \to i$, i.e. to first approximation there is a symmetry between couplings of a resonance to the initial and to the final state. The cross section $\hat{\sigma}$ is therefore, in the program, written in the form \begin{equation} \hat{\sigma}_{i \to R \to f}(\hat{s}) \propto \frac{\pi}{\hat{s}} \, \frac{H_R^{(i)}(\hat{s}) \, H_R^{(f)}(\hat{s})} {(\hat{s} - m_R^2)^2 + H_R^2(\hat{s})} ~. \label{pg:Hinoutsym} \end{equation} As a simple example, the cross section for the process $\e^- \br{\nu}_{\e} \to \W^- \to \mu^- \br{\nu}_{\mu}$ can be written as \begin{equation} \hat{\sigma}(\hat{s}) = 12 \, \frac{\pi}{\hat{s}} \, \frac{H_{\W}^{(i)}(\hat{s}) \, H_{\W}^{(f)}(\hat{s})} {(\hat{s} - m_{\W}^2)^2 + H_{\W}^2(\hat{s})} ~, \end{equation} where \begin{equation} H_{\W}^{(i)}(\hat{s}) = H_{\W}^{(f)}(\hat{s}) = \frac{\alphaem(\hat{s})}{24 \, \ssintw} \, \hat{s} ~. \end{equation} If the effects of several initial and/or final states are studied, it is straightforward to introduce an appropriate summation in the numerator. The analogy between the $H_R^{(f)}$ and $H_R^{(i)}$ cannot be pushed too far, however. The two differ in several important aspects. Firstly, colour factors appear reversed: the decay $R \to \q\qbar$ contains a colour factor $N_C = 3$ enhancement, while $\q\qbar \to R$ is instead suppressed by a factor $1/N_C = 1/3$. Secondly, the $1 + \alphas(\hat{s}) / \pi$ first-order correction factor for the final state has to be replaced by a more complicated $K$ factor for the initial state. This factor is not usually known, or it is known (to first non-trivial order) but too lengthy to be included in the program. Thirdly, incoming partons as a rule are space-like. All the threshold suppression factors of the final state expressions are therefore irrelevant when production is considered. In sum, the $H_R^{(f)}$--$H_R^{(i)}$ analogy is mainly useful as a consistency cross-check, while the two usually are calculated separately. Exceptions include the rather messy loop structure involved in $\g\g \to \H^0$ and $\H^0 \to \g\g$, which is only coded once. It is of some interest to consider the observable resonance shape when the effects of parton distributions are included. In a hadron collider, to first approximation, parton distributions tend to have a behaviour roughly like $f(x) \propto 1/x$ for small $x$ --- this is why $f(x)$ is replaced by $xf(x)$ in eq. (\ref{pg:sigma}). Instead, the basic parton-distribution behaviour is shifted into the factor of $1/\tau$ in the integration phase space $\d \tau/\tau$, cf. eq.~(\ref{pg:sigmares}). When folded with the Breit--Wigner shape, two effects appear. One is that the overall resonance is tilted: the low-mass tail is enhanced and the high-mass one suppressed. The other is that an extremely long tail develops on the low-mass side of the resonance: when $\tau \to 0$, eq. (\ref{pg:Hinoutsym}) with $H_R(\hat{s}) \propto \hat{s}$ gives a $\hat{\sigma}(\hat{s}) \propto \hat{s} \propto \tau$, which exactly cancels the $1/\tau$ factor mentioned above. Na\"{\i}vely, the integral over $y$, $\int \d y = - \ln \tau$, therefore gives a net logarithmic divergence of the resonance shape when $\tau \to 0$. Clearly, it is then necessary to consider the shape of the parton distributions in more detail. At not-too-small $Q^2$, the evolution equations in fact lead to parton distributions more strongly peaked than $1/x$, typically with $xf(x) \propto x^{-0.3}$, and therefore a divergence like $\tau^{-0.3}$ in the cross-section expression. Eventually this divergence is regularized by a closing of the phase space, i.e. that $H_R(\hat{s})$ vanishes faster than $\hat{s}$, and by a less drastic small-$x$ parton-distribution behaviour when $Q^2 \approx \hat{s} \to 0$. The secondary peak at small $\tau$ may give a rather high cross section, which can even rival that of the ordinary peak around the nominal mass. This is the case, for instance, with $\W$ production. Such a peak has never been observed experimentally, but this is not surprising, since the background from other processes is overwhelming at low $\hat{s}$. Thus a lepton of one or a few GeV of transverse momentum is far more likely to come from the decay of a charm or bottom hadron than from a `$\W$' of a mass of a few GeV. When resonance production is studied, it is therefore important to set limits on the mass of the resonance, so as to agree with the experimental definition, at least to first approximation. If not, cross-section information given by the program may be very confusing. Another problem is that often the matrix elements really are valid only in the resonance region. The reason is that one usually includes only the simplest $s$-channel graph in the calculation. It is this `signal' graph that has a peak at the position of the resonance, where it (usually) gives much larger cross sections than the other `background' graphs. Away from the resonance position, `signal' and `background' may be of comparable order, or the `background' may even dominate. There is a quantum mechanical interference when some of the `signal' and `background' graphs have the same initial and final state, and this interference may be destructive or constructive. When the interference is non-negligible, it is no longer meaningful to speak of a `signal' cross section. As an example, consider the scattering of longitudinal $\W$'s, $\W^+_{\mrm{L}} \W^-_{\mrm{L}} \to \W^+_{\mrm{L}} \W^-_{\mrm{L}}$, where the `signal' process is $s$-channel exchange of a Higgs. This graph by itself is ill-behaved away from the resonance region. Destructive interference with `background' graphs such as $t$-channel exchange of a Higgs and $s$- and $t$-channel exchange of a $\gamma/\Z$ is required to save unitarity at large energies. In $\ee$ colliders, the $f_{\e}^{\e}$ parton distribution is peaked at $x = 1$ rather than at $x = 0$. The situation therefore is the opposite, if one considers e.g. $\Z^0$ production in a machine running at energies above $m_{\Z}$: the tail towards lower masses is suppressed and the one towards higher masses enhanced, with a sharp secondary peak at around the nominal energy of the machine. Also in this case, an appropriate definition of cross sections therefore is necessary --- with additional complications due to the interference between $\gamma^*$ and $\Z^0$. When other processes are considered, problems of interference with background appears also here. Numerically the problems may be less pressing, however, since the secondary peak is occuring in a high-mass region, rather than in a more complicated low-mass one. Further, in $\ee$ there is little uncertainty from the shape of the parton distributions. In $2 \to 2$ processes where a pair of resonances are produced, e.g. $\ee \to \Z^0 \H^0$, cross section are almost always given in the zero-width approximation for the resonances. Here two substitutions of the type \begin{equation} 1 = \int \delta (m^2 - m_R^2) \, dm^2 \to \int \frac{1}{\pi} \, \frac{m_R \Gamma_R}{(m^2 - m_R^2)^2 + m_R^2 \Gamma_R^2} \, dm^2 \label{pg:resshapethree} \end{equation} are used to introduce mass distributions for the two resonance masses, i.e. $m_3^2$ and $m_4^2$. In the formula, $m_R$ is the nominal mass and $m$ the actually selected one. The phase-space integral over $x_1$, $x_1$ and $\hat{t}$ in eq. (\ref{pg:sigma}) is then extended to involve also $m_3^2$ and $m_4^2$. The effects of the mass-dependent width is only partly taken into account, by replacing the nominal masses $m_3^2$ and $m_4^2$ in the $\d \hat{\sigma} / \d \hat{t}$ expression by the actually generated ones (also e.g. in the relation between $\hat{t}$ and $\cos\hat{\theta}$), while the widths are evaluated at the nominal masses. This is the equivalent of a simple replacement of $m_R \Gamma_R$ by $\hat{s} \Gamma_R / m_R$ in the numerator of eq. (\ref{pg:resshapeone}), but not in the denominator. In addition, the full threshold dependence, i.e. the $\beta$-dependent factors, is not reproduced. There is no particular reason why the full mass-dependence could not be introduced, except for the extra work and time consumption needed for each process. In fact, the matrix elements for several $\gammaZ$ production processes do contain the full expressions. On the other hand, the matrix elements given in the literature are often valid only when the resonances are almost on the mass shell, since some graphs have been omitted. As an example, the process $\q\qbar \to \e^- \br{\nu}_{\e} \mu^+ \nu_{\mu}$ is dominated by $\q\qbar \to \W^- \W^+$ when each of the two lepton pairs is close to $m_{\W}$ in mass, but in general also receives contributions e.g. from $\q\qbar \to \Z^0 \to \ee$, followed by $\e^+ \to \br{\nu}_{\e} \W^+$ and $\W^+ \to \mu^+ \nu_{\mu}$. The latter contributions are neglected in cross sections given in the zero-width approximation. Processes with one final-state resonance and another ordinary final-state product, e.g. $\q \g \to \W^+ \q'$, are treated in the same spirit as the $2 \to 2$ processes with two resonances, except that only one mass need be selected according to a Breit--Wigner. \subsection{Cross-section Calculations} \label{ss:PYTcrosscalc} In the program, the variables used in the generation of a $2 \to 2$ process are $\tau$, $y$ and $z = \cos\hat{\theta}$. For a $2 \to 1$ process, the $z$ variable can be integrated out, and need therefore not be generated as part of the hard process, except when the allowed angular range of decays is restricted. In unresolved lepton beams, i.e. when $f_{\e}^{\e}(x) = \delta(x-1)$, the variables $\tau$ and/or $y$ may be integrated out. We will cover all these special cases towards the end of the section, and here concentrate on `standard' $2 \to 2$ and $2 \to 1$ processes. \subsubsection{The simple $2 \to 2$ processes} In the spirit of section \ref{ss:MCdistsel}, we want to select simple functions such that the true $\tau$, $y$ and $z$ dependence of the cross sections is approximately modelled. In particular, (almost) all conceivable kinematical peaks should be represented by separate terms in the approximate formulae. If this can be achieved, the ratio of the correct to the approximate cross sections will not fluctuate too much, but allow reasonable Monte Carlo efficiency. Therefore the variables are generated according to the distributions $h_{\tau}(\tau)$, $h_y(y)$ and $h_z(z)$, where normally \begin{eqnarray} h_{\tau}(\tau) & = & \frac{c_1}{{\cal I}_1} \, \frac{1}{\tau} + \frac{c_2}{{\cal I}_2} \, \frac{1}{\tau^2} + \frac{c_3}{{\cal I}_3} \, \frac{1}{\tau(\tau + \tau_R)} + \frac{c_4}{{\cal I}_4} \, \frac{1}{(s\tau - m_R^2)^2 + m_R^2 \Gamma_R^2} \nonumber \\ & & + \frac{c_5}{{\cal I}_5} \, \frac{1}{\tau(\tau + \tau_{R'})} + \frac{c_6}{{\cal I}_6} \, \frac{1}{(s\tau - m_{R'}^2)^2 + m_{R'}^2 \Gamma_{R'}^2} ~, \\[1mm] h_y(y) & = & \frac{c_1}{{\cal I}_1} \, (y - y_{\mmin}) + \frac{c_2}{{\cal I}_2} \, (y_{\mmax} - y) + \frac{c_3}{{\cal I}_3} \, \frac{1}{\cosh y} ~, \\[1mm] h_z(z) & = & \frac{c_1}{{\cal I}_1} + \frac{c_2}{{\cal I}_2} \, \frac{1}{a-z} + \frac{c_3}{{\cal I}_3} \, \frac{1}{a+z} + \frac{c_4}{{\cal I}_4} \, \frac{1}{(a-z)^2} + \frac{c_5}{{\cal I}_5} \, \frac{1}{(a+z)^2} ~. \label{pg:hforms} \end{eqnarray} Here each term is separately integrable, with an invertible primitive function, such that generation of $\tau$, $y$ and $z$ separately is a standard task, as described in section \ref{ss:MCdistsel}. In the following we describe the details of the scheme, including the meaning of the coefficients $c_i$ and ${\cal I}_i$, which are separate for $\tau$, $y$ and $z$. The first variable to be selected is $\tau$. The range of allowed values, $\tau_{\mmin} \leq \tau \leq \tau_{\mmax}$, is generally constrained by a number of user-defined requirements. A cut on the allowed mass range is directly reflected in $\tau$, a cut on the $\pT$ range indirectly. The first two terms of $h_{\tau}$ are intended to represent a smooth $\tau$ dependence, as generally obtained in processes which do not receive contributions from $s$-channel resonances. Also $s$-channel exchange of essentially massless particles ($\gamma$, $\g$, light quarks and leptons) are accounted for, since these do not produce any separate peaks at non-vanishing $\tau$. The last four terms of $h_{\tau}$ are there to catch the peaks in the cross section from resonance production. These terms are only included when needed. Each resonance is represented by two pieces, a first to cover the interference with graphs which peak at $\tau =0$, plus the variation of parton distributions, and a second to approximate the Breit--Wigner shape of the resonance itself. The subscripts $R$ and $R'$ denote values pertaining to the two resonances, with $\tau_R = m_R^2/s$. Currently there is only one process where the full structure with two resonances is used, namely $\f \fbar \to \gamma^*/\Z^0/\Z'^0$. Otherwise either one or no resonance peak is taken into account. The kinematically allowed range of $y$ values is constrained by $\tau$, $|y| \leq - \frac{1}{2} \ln\tau$, and you may impose additional cuts. Therefore the allowed range $y_{\mmin} \leq y \leq y_{\mmax}$ is only constructed after $\tau$ has been selected. The first two terms of $h_y$ give a fairly flat $y$ dependence --- for processes which are symmetric in $y \leftrightarrow -y$, they will add to give a completely flat $y$ spectrum between the allowed limits. In principle, the natural subdivision would have been one term flat in $y$ and one forward--backward asymmetric, i.e. proportional to $y$. The latter is disallowed by the requirement of positivity, however. The $y - y_{\mmin}$ and $y_{\mmax} - y$ terms actually used give the same amount of freedom, but respect positivity. The third term is peaked at around $y = 0$, and represents the bias of parton distributions towards this region. The allowed $z = \cos\hat{\theta}$ range is na\"{\i}vely $-1 \leq z \leq 1$. However, most cross sections are divergent for $z \to \pm 1$, so some kind of regularization is necessary. Normally one requires $\pT \geq \pTmin$, which translates into $z^2 \leq 1 - 4 \pTmin^2/(\tau s)$ for massless outgoing particles. Since again the limits depend on $\tau$, the selection of $z$ is done after that of $\tau$. Additional requirements may constrain the range further. In particular, a $p_{\perp\mmax}$ constraint may split the allowed $z$ range into two, i.e. $z_{-\mmin} \leq z \leq z_{-\mmax}$ or $z_{+\mmin} \leq z \leq z_{+\mmax}$. An unsplit range is represented by $z_{-\mmax} = z_{+\mmin} = 0$. For massless outgoing particles the parameter $a = 1$ in $h_z$, such that the five terms represent a piece flat in angle and pieces peaked as $1/\hat{t}$, $1/\hat{u}$, $1/\hat{t}^2$, and $1/\hat{u}^2$, respectively. For non-vanishing masses one has $a = 1 + 2 m_3^2 m_4^2/\hat{s}^2$. In this case, the full range $-1 \leq z \leq 1$ is therefore available --- physically, the standard $\hat{t}$ and $\hat{u}$ singularities are regularized by the masses $m_3$ and $m_4$. For each of the terms, the ${\cal I}_i$ coefficients represent the integral over the quantity multiplying the coefficient $c_i$; thus, for instance: \begin{eqnarray} h_{\tau}: & & {\cal I}_1 = \int \frac{\d \tau}{\tau} = \ln \left( \frac{\tau_{\mmax}}{\tau_{\mmin}} \right) ~, \nonumber \\ & & {\cal I}_2 = \int \frac{\d \tau}{\tau^2} = \frac{1}{\tau_{\mmin}} - \frac{1}{\tau_{\mmax}} ~; \nonumber \\ h_y: & & {\cal I}_1 = \int (y - y_{\mmin}) \, \d y = \frac{1}{2} (y_{\mmax} - y_{\mmin})^2 ~; \nonumber \\ h_z: & & {\cal I}_1 = \int \d z = (z_{-\mmax} - z_{-\mmin}) + (z_{+\mmax} - z_{+\mmin}) , \nonumber \\ & & {\cal I}_2 = \int \frac{\d z}{a-z} = \ln \left( \frac{(a-z_{-\mmin})(a-z_{+\mmin})} {(a-z_{-\mmax})(a-z_{-\mmin})} \right) ~. \end{eqnarray} The $c_i$ coefficients are normalized to unit sum for $h_{\tau}$, $h_y$ and $h_z$ separately. They have a simple interpretation, as the probability for each of the terms to be used in the preliminary selection of $\tau$, $y$ and $z$, respectively. The variation of the cross section over the allowed phase space is explored in the initialization procedure of a {\Py} run, and based on this knowledge the $c_i$ are optimized so as to give functions $h_{\tau}$, $h_y$ and $h_z$ that closely follow the general behaviour of the true cross section. For instance, the coefficient $c_4$ in $h_{\tau}$ is to be made larger the more the total cross section is dominated by the region around the resonance mass. The phase-space points tested at initialization are put on a grid, with the number of points in each dimension given by the number of terms in the respective $h$ expression, and with the position of each point given by the median value of the distribution of one of the terms. For instance, the $\d \tau / \tau$ distribution gives a median point at $\sqrt{\tau_{\mmin}\tau_{\mmax}}$, and $\d \tau / \tau^2$ has the median $2 \tau_{\mmin} \tau_{\mmax} / (\tau_{\mmin} + \tau_{\mmax})$. Since the allowed $y$ and $z$ ranges depend on the $\tau$ value selected, then so do the median points defined for these two variables. With only a limited set of phase-space points studied at the initialization, the `optimal' set of coefficients is not uniquely defined. To be on the safe side, 40\% of the total weight is therefore assigned evenly between all allowed $c_i$, whereas the remaining 60\% are assigned according to the relative importance surmised, under the constraint that no coefficient is allowed to receive a negative contribution from this second piece. After a preliminary choice has been made of $\tau$, $y$ and $z$, it is necessary to find the weight of the event, which is to be used to determine whether to keep it or generate another one. Using the relation $\d \hat{t} = \hat{s} \, \beta_{34} \, \d z / 2$, eq.~(\ref{pg:sigma}) may be rewritten as \begin{eqnarray} \sigma & = & \int \int \int \frac{\d \tau}{\tau} \, \d y \, \frac{\hat{s} \beta_{34}}{2} \d z \, x_1 f_1(x_1, Q^2) \, x_2 f_2(x_2, Q^2) \, \frac{\d \hat{\sigma}}{\d \hat{t}} \nonumber \\[1mm] & = & \frac{\pi}{s} \int h_{\tau}(\tau) \, \d \tau \int h_y(y) \, \d y \int h_z(z) \, \d z \, \beta_{34} \, \frac{x_1 f_1(x_1, Q^2) \, x_2 f_2(x_2, Q^2)} {\tau^2 h_{\tau}(\tau) \, h_y(y) \, 2 h_z(z)} \, \frac{\hat{s}^2}{\pi} \frac{\d \hat{\sigma}}{\d \hat{t}} \nonumber \\[1mm] & = & \left\langle \frac{\pi}{s} \, \frac{\beta_{34}}{\tau^2 h_{\tau}(\tau) \, h_y(y) \, 2 h_z(z)} \, x_1 f_1(x_1, Q^2) \, x_2 f_2(x_2, Q^2) \, \frac{\hat{s}^2}{\pi} \frac{\d \hat{\sigma}}{\d \hat{t}} \right\rangle ~. \label{pg:sigmamap} \end{eqnarray} In the middle line, a factor of $1 = h_{\tau}/h_{\tau}$ has been introduced to rewrite the $\tau$ integral in terms of a phase space of unit volume: $\int h_{\tau}(\tau) \, \d \tau = 1$ according to the relations above. Correspondingly for the $y$ and $z$ integrals. In addition, factors of $1 = \hat{s}/ (\tau s)$ and $1 = \pi / \pi$ are used to isolate the dimensionless cross section $(\hat{s}^2/\pi) \, \d \hat{\sigma} / \d \hat{t}$. The content of the last line is that, with $\tau$, $y$ and $z$ selected according to the expressions $h_{\tau}(\tau)$, $h_y(y)$ and $h_z(z)$, respectively, the cross section is obtained as the average of the final expression over all events. Since the $h$'s have been picked to give unit volume, there is no need to multiply by the total phase-space volume. As can be seen, the cross section for a given Monte Carlo event is given as the product of four factors, as follows: \begin{Enumerate} \item The $\pi/s$ factor, which is common to all events, gives the overall dimensions of the cross section, in GeV$^{-2}$. Since the final cross section is given in units of mb, the conversion factor of 1 GeV$^{-2} = 0.3894$ mb is also included here. \item Next comes the `Jacobian', which compensates for the change from the original to the final phase-space volume. \item The parton-distribution function weight is obtained by making use of the parton distribution libraries in {\Py} or externally. The $x_1$ and $x_2$ values are obtained from $\tau$ and $y$ via the relations $x_{1,2} = \sqrt{\tau} \exp(\pm y)$. \item Finally, the dimensionless cross section $(\hat{s}^2/\pi) \, \d \hat{\sigma} / \d \hat{t}$ is the quantity that has to be coded for each process separately, and where the physics content is found. \end{Enumerate} Of course, the expression in the last line is not strictly necessary to obtain the cross section by Monte Carlo integration. One could also have used eq.~(\ref{pg:sigma}) directly, selecting phase-space points evenly in $\tau$, $y$ and $\hat{t}$, and averaging over those Monte Carlo weights. Clearly this would be much simpler, but the price to be paid is that the weights of individual events could fluctuate wildly. For instance, if the cross section contains a narrow resonance, the few phase-space points that are generated in the resonance region obtain large weights, while the rest do not. With our procedure, a resonance would be included in the $h_{\tau}(\tau)$ factor, so that more events would be generated at around the appropriate $\tau_R$ value (owing to the $h_{\tau}$ numerator in the phase-space expression), but with these events assigned a lower, more normal weight (owing to the factor $1/h_{\tau}$ in the weight expression). Since the weights fluctuate less, fewer phase-space points need be selected to get a reasonable cross-section estimate. In the program, the cross section is obtained as the average over all phase-space points generated. The events actually handed on to the user should have unit weight, however (an option with weighted events exists, but does not represent the mainstream usage). At initialization, after the $c_i$ coefficients have been determined, a search inside the allowed phase-space volume is therefore made to find the maximum of the weight expression in the last line of eq.~(\ref{pg:sigmamap}). In the subsequent generation of events, a selected phase-space point is then retained with a probability equal to the weight in the point divided by the maximum weight. Only the retained phase-space points are considered further, and generated as complete events. The search for the maximum is begun by evaluating the weight in the same grid of points as used to determine the $c_i$ coefficients. The point with highest weight is used as starting point for a search towards the maximum. In unfortunate cases, the convergence could be towards a local maximum which is not the global one. To somewhat reduce this risk, also the grid point with second-highest weight is used for another search. After initialization, when events are generated, a warning message will be given by default at any time a phase-space point is selected where the weight is larger than the maximum, and thereafter the maximum weight is adjusted to reflect the new knowledge. This means that events generated before this time have a somewhat erroneous distribution in phase space, but if the maximum violation is rather modest the effects should be negligible. The estimation of the cross section is not affected by any of these considerations, since the maximum weight does not enter into eq. (\ref{pg:sigmamap}). For $2 \to 2$ processes with identical final-state particles, the symmetrization factor of $1/2$ is explicitly included at the end of the $\d \hat{\sigma} / \d \hat{t}$ calculation. In the final cross section, a factor of 2 is retrieved because of integration over the full phase space (rather than only half of it). That way, no special provisions are needed in the phase-space integration machinery. \subsubsection{Resonance production} We have now covered the simple $2 \to 2$ case. In a $2 \to 1$ process, the $\hat{t}$ integral is absent, and the differential cross section $\d \hat{\sigma} / \d \hat{t}$ is replaced by $\hat{\sigma}(\hat{s})$. The cross section may now be written as \begin{eqnarray} \sigma & = & \int \int \frac{\d \tau}{\tau} \, \d y \, x_1 f_1(x_1, Q^2) \, x_2 f_2(x_2, Q^2) \, \hat{\sigma}(\hat{s}) \nonumber \\ & = & \frac{\pi}{s} \int h_{\tau}(\tau) \, \d \tau \int h_y(y) \, \d y \, \frac{x_1 f_1(x_1, Q^2) \, x_2 f_2(x_2, Q^2)} {\tau^2 h_{\tau}(\tau) \, h_y(y)} \, \frac{\hat{s}}{\pi} \hat{\sigma}(\hat{s}) \nonumber \\ & = & \left\langle \frac{\pi}{s} \, \frac{1}{\tau^2 h_{\tau}(\tau) \, h_y(y)} \, x_1 f_1(x_1, Q^2) \, x_2 f_2(x_2, Q^2) \, \frac{\hat{s}}{\pi} \hat{\sigma}(\hat{s}) \right\rangle ~. \label{pg:sigmamapres} \end{eqnarray} The structure is thus exactly the same, but the $z$-related pieces are absent, and the r\^ole of the dimensionless cross section is played by $(\hat{s}/\pi) \hat{\sigma}(\hat{s})$. If the range of allowed decay angles of the resonance is restricted, e.g. by requiring the decay products to have a minimum transverse momentum, effectively this translates into constraints on the $z = \cos\hat{\theta}$ variable of the $2 \to 2$ process. The difference is that the angular dependence of a resonance decay is trivial, and that therefore the $z$-dependent factor can be easily evaluated. For a spin-0 resonance, which decays isotropically, the relevant weight is simply $(z_{-\mmax} - z_{-\mmin})/2 + (z_{+\mmax} - z_{+\mmin})/2$. For a transversely polarized spin-1 resonance the expression is, instead, \begin{equation} \frac{3}{8}(z_{-\mmax} - z_{-\mmin}) + \frac{3}{8}(z_{+\mmax} - z_{+\mmin}) + \frac{1}{8}(z_{-\mmax} - z_{-\mmin})^3 + \frac{1}{8}(z_{+\mmax} - z_{+\mmin})^3 ~. \end{equation} Since the allowed $z$ range could depend on $\tau$ and/or $y$ (it does for a $\pT$ cut), the factor has to be evaluated for each individual phase-space point and included in the expression of eq. (\ref{pg:sigmamapres}). For $2 \to 2$ processes where either of the final-state particles is a resonance, or both, an additional choice has to be made for each resonance mass, eq.~(\ref{pg:resshapethree}). Since the allowed $\tau$, $y$ and $z$ ranges depend on $m_3^2$ and $m_4^2$, the selection of masses have to precede the choice of the other phase-space variables. Just as for the other variables, masses are not selected uniformly over the allowed range, but are rather distributed according to a function $h_m(m^2) \, dm^2$, with a compensating factor $1/h_m(m^2)$ in the `Jacobian'. The functional form picked is normally \begin{equation} h_m(m^2) = \frac{c_1}{{\cal I}_1} \, \frac{1}{\pi} \, \frac{m_R \Gamma_R}{(m^2 - m_R^2)^2 + m_R^2 \Gamma_R^2} + \frac{c_2}{{\cal I}_2} + \frac{c_3}{{\cal I}_3} \, \frac{1}{m^2} + \frac{c_4}{{\cal I}_4} \, \frac{1}{m^4} ~. \label{pg:reshdist} \end{equation} The definition of the ${\cal I}_i$ integrals is analogous to the one before. The $c_i$ coefficients are not found by optimization, but predetermined, normally to $c_1 = 0.8$, $c_2 = c_3 =0.1$, $c_4 = 0$. Clearly, had the phase space and the cross section been independent of $m_3^2$ and $m_4^2$, the optimal choice would have been to put $c_1 = 1$ and have all other $c_i$ vanishing --- then the $1/h_m$ factor of the `Jacobian' would exactly have cancelled the Breit--Wigner of eq.~(\ref{pg:resshapethree}) in the cross section. The second and the third terms are there to cover the possibility that the cross section does not die away quite as fast as given by the na\"{\i}ve Breit--Wigner shape. In particular, the third term covers the possibility of a secondary peak at small $m^2$, in a spirit slightly similar to the one discussed for resonance production in $2 \to 1$ processes. The fourth term is only used for processes involving $\gammaZ$ production, where the $\gamma$ propagator guarantees that the cross section does have a significant secondary peak for $m^2 \to 0$. Therefore here the choice is $c_1 = 0.4$, $c_2 = 0.05$, $c_3 = 0.3$ and $c_4 = 0.25$. A few special tricks have been included to improve efficiency when the allowed mass range of resonances is constrained by kinematics or by user cuts. For instance, if a pair of equal or charge-conjugate resonances are produced, such as in $\ee \to \W^+ \W^-$, use is made of the constraint that the lighter of the two has to have a mass smaller than half the c.m. energy. \subsubsection{Lepton beams} Lepton beams have to be handled slightly differently from what has been described so far. One also has to distinguish between a lepton for which parton distributions are included and one which is treated as an unresolved point-like particle. The necessary modifications are the same for $2 \to 2$ and $2 \to 1$ processes, however, since the $\hat{t}$ degree of freedom is unaffected. If one incoming beam is an unresolved lepton, the corresponding parton-distribution piece collapses to a $\delta$ function. This function can be used to integrate out the $y$ variable: $\delta(x_{1,2} - 1) = \delta(y \pm (1/2) \ln \tau)$. It is therefore only necessary to select the $\tau$ and the $z$ variables according to the proper distributions, with compensating weight factors, and only one set of parton distributions has to be evaluated explicitly. If both incoming beams are unresolved leptons, both the $\tau$ and the $y$ variables are trivially given: $\tau = 1$ and $y = 0$. Parton-distribution weights disappear completely. For a $2 \to 2$ process, only the $z$ selection remains to be performed, while a $2 \to 1$ process is completely specified, i.e. the cross section is a simple number that only depends on the c.m. energy. For a resolved electron, the $f_{\e}^{\e}$ parton distribution is strongly peaked towards $x = 1$. This affects both the $\tau$ and the $y$ distributions, which are not well described by either of the pieces in $h_{\tau}(\tau)$ or $h_y(y)$ in processes with interacting $\e^{\pm}$. (Processes which involve e.g. the $\gamma$ content of the $\e$ are still well simulated, since $f_{\gamma}^{\e}$ is peaked at small $x$.) If both parton distributions are peaked close to 1, the $h_{\tau}(\tau)$ expression in eq. (\ref{pg:hforms}) is therefore increased with one additional term of the form $h_{\tau}(\tau) \propto 1 / (1 - \tau)$, with coefficients $c_7$ and ${\cal I}_7$ determined as before. The divergence when $\tau \to 1$ is cut off by our regularization procedure for the $f_{\e}^{\e}$ parton distribution; therefore we only need consider $\tau < 1 - 2 \times 10^{-6}$. Correspondingly, the $h_y(y)$ expression is expanded with a term $1/(1 - \exp(y-y_0))$ when incoming beam number 1 consists of a resolved $\e^{\pm}$, and with a term $1/(1 - \exp(-y-y_0))$ when incoming beam number 2 consists of a resolved $\e^{\pm}$. Both terms are present for an $\ee$ collider, only one for an $\ep$ one. The coefficient $y_0 = - (1/2) \ln \tau$ is the na\"{\i}ve kinematical limit of the $y$ range, $|y| < y_0$. From the definitions of $y$ and $y_0$ it is easy to see that the two terms above correspond to $1/(1-x_1)$ and $1/(1-x_2)$, respectively, and thus are again regularized by our parton-distribution function cut-off. Therefore the integration ranges are $y < y_0 -10^{-6}$ for the first term and $y > - y_0 + 10^{-6}$ for the second one. \subsubsection{Mixing processes} \label{sss:mixingproc} In the cross-section formulae given so far, we have deliberately suppressed a summation over the allowed incoming flavours. For instance, the process $\f\fbar \to \Z^0$ in a hadron collider receives contributions from $\u\ubar \to \Z^0$, $\d\dbar \to \Z^0$, $\s\sbar \to \Z^0$, and so on. These contributions share the same basic form, but differ in the parton-distribution weights and (usually) in a few coupling constants in the hard matrix elements. It it therefore convenient to generate the terms together, as follows: \begin{Enumerate} \item A phase-space point is picked, and all common factors related to this choice are evaluated, i.e. the `Jacobian' and the common pieces of the matrix elements (e.g. for a $\Z^0$ the basic Breit--Wigner shape, excluding couplings to the initial flavour). \item The parton-distribution-function library is called to produce all the parton distributions, at the relevant $x$ and $Q^2$ values, for the two incoming beams. \item A loop is made over the two incoming flavours, one from each beam particle. For each allowed set of incoming flavours, the full matrix-element expression is put together, using the common pieces and the flavour-dependent couplings. This is multiplied by the common factors and the parton-distribution weights to obtain a cross-section weight. \item Each allowed flavour combination is stored as a separate entry in a table, together with its weight. In addition, a summed weight is calculated. \item The phase-space point is kept or rejected, according to a comparison of the summed weight with the maximum weight obtained at initialization. Also the cross-section Monte Carlo integration is based on the summed weight. \item If the point is retained, one of the allowed flavour combinations is picked according to the relative weights stored in the full table. \end{Enumerate} Generally, the flavours of the final state are either completely specified by those of the initial state, e.g. as in $\q\g \to \q\g$, or completely decoupled from them, e.g. as in $\f\fbar \to \Z^0 \to \f'\fbar'$. In neither case need therefore the final-state flavours be specified in the cross-section calculation. It is only necessary, in the latter case, to include an overall weight factor, which takes into account the summed contribution of all final states that are to be simulated. For instance, if only the process $\Z^0 \to \ee$ is studied, the relevant weight factor is simply $\Gamma_{\e\e} / \Gamma_{\mrm{tot}}$. Once the kinematics and the incoming flavours have been selected, the outgoing flavours can be picked according to the appropriate relative probabilities. In some processes, such as $\g\g \to \g\g$, several different colour flows are allowed, each with its own kinematical dependence of the matrix-element weight, see section \ref{sss:QCDjetclass}. Each colour flow is then given as a separate entry in the table mentioned above, i.e. in total an entry is characterized by the two incoming flavours, a colour-flow index, and the weight. For an accepted phase-space point, the colour flow is selected in the same way as the incoming flavours. The program can also allow the mixed generation of two or more completely different processes, such as $\f\fbar \to \Z^0$ and $\q\qbar \to \g\g$. In that case, each process is initialized separately, with its own set of coefficients $c_i$ and so on. The maxima obtained for the individual cross sections are all expressed in the same units, even when the dimensionality of the phase space is different. (This is because we always transform to a phase space of unit volume, $\int h_{\tau}(\tau) \, \d \tau \equiv 1$, etc.) The above generation scheme need therefore only be generalized as follows: \begin{Enumerate} \item One process is selected among the allowed ones, with a relative probability given by the maximum weight for this process. \item A phase-space point is found, using the distributions $h_{\tau}(\tau)$ and so on, optimized for this particular process. \item The total weight for the phase-space point is evaluated, again with `Jacobians', matrix elements and allowed incoming flavour combinations that are specific to the process. \item The point is retained with a probability given by the ratio of the actual to the maximum weight of the process. If the point is rejected, one has to go back to step 1 and pick a new process. \item Once a phase-space point has been accepted, flavours may be selected, and the event generated in full. \end{Enumerate} It is clear why this works: although phase-space points are selected among the allowed processes according to relative probabilities given by the maximum weights, the probability that a point is accepted is proportional to the ratio of actual to maximum weight. In total, the probability for a given process to be retained is therefore only proportional to the average of the actual weights, and any dependence on the maximum weight is gone. In $\gamma\p$ and $\gamma\gamma$ physics, the different components of the photon give different final states, see section \ref{sss:photoprod}. Technically, this introduces a further level of administration, since each event class contains a set of (partly overlapping) processes. From an ideological point of view, however, it just represents one more choice to be made, that of event class, before the selection of process in step 1 above. When a weighting fails, both class and process have to be picked anew. \subsection{$2 \to 3$ and $2 \to 4$ Processes} The {\Py} machinery to handle $2 \to 1$ and $2 \to 2$ processes is fairly sophisticated and generic. The same cannot be said about the generation of hard scattering processes with more than two final-state particles. The number of phase-space variables is larger, and it is therefore more difficult to find and transform away all possible peaks in the cross section by a suitably biased choice of phase-space points. In addition, matrix-element expressions for $2 \to 3$ processes are typically fairly lengthy. Therefore {\Py} only contains a very limited number of $2 \to 3$ and $2 \to 4$ processes, and almost each process is a special case of its own. It is therefore less interesting to discuss details, and we only give a very generic overview. If the Higgs mass is not light, interactions among longitudinal $\W$ and $\Z$ gauge bosons are of interest. In the program, $2 \to 1$ processes such as $\W_{\mrm{L}}^+ \W_{\mrm{L}}^- \to \H^0$ and $2 \to 2$ ones such as $\W_{\mrm{L}}^+ \W_{\mrm{L}}^- \to \Z_{\mrm{L}}^0 \Z_{\mrm{L}}^0$ are included. The former are for use when the $\H^0$ still is reasonably narrow, such that a resonance description is applicable, while the latter are intended for high energies, where different contributions have to be added up. Since the program does not contain $\W_{\mrm{L}}$ or $\Z_{\mrm{L}}$ distributions inside hadrons, the basic hard scattering has to be convoluted with the $\q \to \q' \W_{\mrm{L}}$ and $\q \to \q \Z_{\mrm{L}}$ branchings, to yield effective $2 \to 3$ and $2 \to 4$ processes. However, it is possible to integrate out the scattering angles of the quarks analytically, as well as one energy-sharing variable \cite{Cha85}. Only after an event has been accepted are these other kinematical variables selected. This involves further choices of random variables, according to a separate selection loop. In total, it is therefore only necessary to introduce one additional variable in the basic phase-space selection, which is chosen to be $\hat{s}'$, the squared invariant mass of the full $2 \to 3$ or $2 \to 4$ process, while $\hat{s}$ is used for the squared invariant mass of the inner $2 \to 1$ or $2 \to 2$ process. The $y$ variable is coupled to the full process, since parton-distribution weights have to be given for the original quarks at $x_{1,2} = \sqrt{\tau'} \exp{(\pm y)}$. The $\hat{t}$ variable is related to the inner process, and thus not needed for the $2 \to 3$ processes. The selection of the $\tau' = \hat{s}'/s$ variable is done after $\tau$, but before $y$ has been chosen. To improve the efficiency, the selection is made according to a weighted phase space of the form $\int h_{\tau'}(\tau') \, \d \tau'$, where \begin{equation} h_{\tau'}(\tau') = \frac{c_1}{{\cal I}_1} \frac{1}{\tau'} + \frac{c_2}{{\cal I}_2} \, \frac{(1- \tau / \tau')^3}{\tau'^2} + \frac{c_3}{{\cal I}_3} \, \frac{1}{\tau' (1 - \tau')} ~, \end{equation} in conventional notation. The $c_i$ coefficients are optimized at initialization. The $c_3$ term, peaked at $\tau' \approx 1$, is only used for $\ee$ collisions. The choice of $h_{\tau'}$ is roughly matched to the longitudinal gauge-boson flux factor, which is of the form \begin{equation} \left( 1 + \frac{\tau}{\tau'} \right) \, \ln \left( \frac{\tau}{\tau'} \right) - 2 \left( 1 - \frac{\tau}{\tau'} \right) ~. \end{equation} For a light $\H$ the effective $\W$ approximation above breaks down, and it is necessary to include the full structure of the $\q \q' \to \q \q' \H^0$ (i.e. $\Z\Z$ fusion) and $\q \q' \to \q'' \q''' \H^0$ (i.e. $\W\W$ fusion) matrix elements. The $\tau'$, $\tau$ and $y$ variables are here retained, and selected according to standard procedures. The Higgs mass is represented by the $\tau$ choice; normally the $\H^0$ is so narrow that the $\tau$ distribution effectively collapses to a $\delta$ function. In addition, the three-body final-state phase space is rewritten as \begin{equation} \left( \prod_{i=3}^5 \frac{1}{(2 \pi)^3} \frac{\d^3 p_i}{2 E_i} \right) \, (2 \pi)^4 \delta^{(4)} (p_3 + p_4 + p_5 - p_1 - p_2) = \frac{1}{(2 \pi)^5} \, \frac{\pi^2}{4 \sqrt{\lambda_{\perp 34}}} \, \d p_{\perp 3}^2 \, \frac{\d \varphi_3}{2 \pi} \, \d p_{\perp 4}^2 \, \frac{\d \varphi_4}{2 \pi} \, \d y_5 ~, \end{equation} where $\lambda_{\perp 34} = (m_{\perp 34}^2 - m_{\perp 3}^2 - m_{\perp 4}^2)^2 - 4 m_{\perp 3}^2 m_{\perp 4}^2$. The outgoing quarks are labelled 3 and 4, and the outgoing Higgs 5. The $\varphi$ angles are selected isotropically, while the two transverse momenta are picked, with some foreknowledge of the shape of the $\W / \Z$ propagators in the cross sections, according to $h_{\perp} (\pT^2) \, \d \pT^2$, where \begin{equation} h_{\perp}(\pT^2) = \frac{c_1}{{\cal I}_1} + \frac{c_2}{{\cal I}_2} \, \frac{1}{m_R^2 + \pT^2} + \frac{c_3}{{\cal I}_3} \, \frac{1}{(m_R^2 + \pT^2)^2} ~, \end{equation} with $m_R$ the $\W$ or $\Z$ mass, depending on process, and $c_1 = c_2 = 0.05$, $c_3 = 0.9$. Within the limits given by the other variable choices, the rapidity $y_5$ is chosen uniformly. A final choice remains to be made, which comes from a twofold ambiguity of exchanging the longitudinal momenta of partons 3 and 4 (with minor modifications if they are massive). Here the relative weight can be obtained exactly from the form of the matrix element itself. No good phase-space choice was found for the process $\g \g \to \Z^0 \b \bbar$. This process is therefore not so easy to generate with {\Py}. What is currently done is to use the basic formalism of $2 \to 2$ processes, where the $\b + \bbar$ system is considered as an effective `resonance'. Two masses are then selected, the $\Z^0$ one according to eq.~(\ref{pg:reshdist}) and the $\b + \bbar$ one according to $\d m^2 / m^2$. Both `decays' are selected isotropically in the respective rest frame, to give the final four fermions in terms of which the matrix element is given. In addition, $\tau$, $y$ and $z$ are selected according to the standard rules for $2 \to 2$ processes. \subsection{Resonance Decays} \label{ss:resdecay} Resonances can be made to decay in two different routines. One is the standard decay treatment (in \ttt{LUDECY}) that can be used for any unstable particle, where decay channels are chosen according to fixed probabilities, and decay angles usually are picked isotropically in the rest frame of the resonance, see section \ref{ss:partdecays}. The more sophisticated treatment (in \ttt{PYRESD}) is the default one for resonances produced in {\Py}, and is described here. The following are included in the list of resonances: $\Z^0$, $\W^{\pm}$, $\H^0$, $\Z'^0$, $\W'^{\pm}$, $\H'^0$, $\A^0$, $\H^{\pm}$, $\eta_{\mrm{tech}}^0$, $\L_{\Q}$, and $\R^0$. The top is also considered as a resonance if it is assumed to decay before it has time to fragment. Likewise for the fourth generation fermions. If the fourth generation is used to represent excited quarks and leptons, these are also considered to be resonances. \subsubsection{The decay scheme} In the beginning of the decay treatment, either one or two resonances may be present, the former represented by processes such as $\q \qbar' \to \W^+$ and $\q \g \to \W^+ \q'$, the latter by $\q \qbar \to \W^+ \W^-$. If the latter is the case, the decay of the two resonances is considered in parallel (unlike \ttt{LUDECY}, where one particle at a time is made to decay). First the decay channel of each resonance is selected according to the relative weights $H_R^{(f)}$, as described above, evaluated at the actual mass of the resonance, rather than at the nominal one. Threshold factors are therefore fully taken into account, with channels automatically switched off below the threshold. Normally the masses of the decay products are well-defined, but e.g. in decays like $\H^0 \to \W^+ \W^-$ it is also necessary to select the decay product masses. This is done according to two Breit--Wigners of the type in eq.~(\ref{pg:resshapethree}), multiplied by the threshold factor, which depends on both masses. Next the decay angles of the resonance are selected isotropically in its rest frame. Normally the full range of decay angles is available, but in $2 \to 1$ processes the decay angles of the original resonance may be restrained by user cuts, e.g. on the $\pT$ of the decay products. Based on the angles, the four-momenta of the decay products are constructed and boosted to the correct frame. As a rule, matrix elements are given with quark and lepton masses assumed vanishing. Therefore the four-momentum vectors constructed at this stage are actually massless for all quarks and leptons. The matrix elements may now be evaluated. For a process such as $\q \qbar \to \W^+ \W^- \to \e^+ \nu_{\e} \mu^- \br{\nu}_{\mu}$, the matrix element is a function of the four-momenta of the two incoming fermions and of the four outgoing ones. An upper limit for the event weight can be constructed from the cross section for the basic process $\q \qbar \to \W^+ \W^-$, as already used to select the two $\W$ momenta. If the weighting fails, new resonance decay angles are picked and the procedure is iterated until acceptance. Based on the accepted set of angles, the correct decay product four-momenta are constructed, including previously neglected fermion masses. Quarks and, optionally, leptons are allowed to radiate, using the standard final-state showering machinery, with maximum virtuality given by the resonance mass. In some decays new resonances are produced, and these are then subsequently allowed to decay. Only one resonance pair is considered at a time, i.e. it is not possible to include correlations which involve the simultaneous decay of three or more resonances. This is in fact all that is currently needed: in a process like $\q\qbar \to \Z^0 \H^0 \to \Z^0 \W^+ \W^- \to 6$ fermions, the spinless nature of the $\H^0$ ensures that the $\W^{\pm}$ decays are decoupled from that of the $\Z^0$ (but not from each other). \subsubsection{Cross-section considerations} \label{sss:resdecaycross} The cross section for a process which involves the production of one or several resonances is always reduced to take into account channels not allowed by user flags. This is trivial for a single $s$-channel resonance, cf. eq.~(\ref{pg:Hinoutsym}), but can also be included approximately if several layers of resonance decays are involved. At initialization, the ratio between the user-allowed width and the nominally possible one is evaluated and stored, starting from the lightest resonances and moving upwards. As an example, one first finds the reduction factors for $\W^+$ and for $\W^-$ decays, which need not be the same if e.g. $\W^+$ is allowed to decay only to quarks and $\W^-$ only to leptons. These factors enter together as a weight for the $\H^0 \to \W^+ \W^-$ channel, which is thus reduced in importance compared with other possible Higgs decay channels. This is also reflected in the weight factor of the $\H^0$ itself, where some channels are open in full, others completely closed, and finally some (like the one above) open but with reduced weight. Finally, the weight for the process $\q\qbar \to \Z^0 \H^0$ is evaluated as the product of the $\Z^0$ weight factor and the $\H^0$ one. The standard cross section of the process is multiplied with this weight. Since the restriction on allowed decay modes is already included in the hard process cross section, mixing of different event types is greatly simplified, and the selection of decay channel chains is straightforward. There is a price to be paid, however. The reduction factors evaluated at initialization all refer to resonances at their nominal masses. For instance, the $\W$ reduction factor is evaluated at the nominal $\W$ mass, even when that factor is used, later on, in the description of the decay of a 120 GeV Higgs, where at least one $\W$ would be produced below this mass. We know of no case where this approximation has any serious consequences, however. The weighting procedure works because the number of resonances to be produced, directly or in subsequent decays, can be derived recursively already from the start. It does not work for particles which could also be produced at later stages, such as the parton-shower evolution and the fragmentation. For instance, $\D^0$ mesons can be produced fairly late in the event generation chain, in unknown numbers, and so weights could not be introduced to compensate, e.g. for the forcing of decays only into $\pi^+ \K^-$. For similar reasons the top is only considered as a resonance if it is not allowed to hadronize; see discussion in section \ref{sss:heavflavclass}. One should note that this reduction factor is separate from the description of the resonance shape itself, where the full width of the resonance has to be used. This width is based on the sum of all possible decay modes, not just the simulated ones. {\Py} does allow the possibility to change also the underlying physics scenario, e.g. to include the decay of a $\Z^0$ into a fourth-generation neutrino. Normally the evaluation of the reduction factors is straightforward. However, for decays into a pair of equal or charge-conjugate resonances, such as $\Z^0 \Z^0$ or $\W^+ \W^-$, it is possible to pick combinations in such a way that the weight of the pair does not factorize into a product of the weight of each resonance itself. To be precise, any decay channel can be given seven different status codes: \begin{Itemize} \item $-1$: a non-existent decay mode, completely switched off and of no concern to us; \item 0: an existing decay channel, which is switched off; \item 1: a channel which is switched on; \item 2: a channel switched on for particles, but off for antiparticles; \item 3: a channel switched on for antiparticles, but off for particles; \item 4: a channel switched on for one of the resonances, but not for both; \item 5: a channel switched on for the other of the resonances, but not for both. \end{Itemize} The meaning of possibilities 4 and 5 is exemplified by the statement `in a $\W^+\W^-$ pair, one $\W$ decays hadronically and the other leptonically', which thus covers the cases where either $\W^+$ or $\W^-$ decays hadronically. Neglecting non-existing channels, each channel belongs to either of the classes above. If we denote the total branching ratio into channels of type $i$ by $r_i$, this then translates into the requirement $r_0 + r_1 + r_2 + r_3 + r_4 + r_5 = 1$. For a single particle the weight factor is $r_1 + r_2 + r_4$, and for a single antiparticle $r_1 + r_3 + r_4$. For a pair of identical resonances, the joint weight is instead \begin{equation} (r_1 + r_2)^2 + 2 (r_1 + r_2) (r_4 + r_5) + 2 r_4 r_5 ~, \end{equation} and for a resonance--antiresonance pair \begin{equation} (r_1 + r_2)(r_1 + r_3) + (2 r_1 + r_2 + r_3) (r_4 + r_5) + 2 r_4 r_5 ~. \label{eq:WWallchancomb} \end{equation} If some channels come with a reduced weight because of restrictions on subsequent decay chains, this may be described in terms of properly reduced $r_i$, so that the sum is less than unity. For instance, in a $\t\tbar \to \b\W^+ \, \bbar\W^-$ process, the $\W$ decay modes may be restricted to $\W^+ \to \q\qbar$ and $\W^- \to \e^-\bar{\nu}_{\e}$, in which case $(\sum r_i)_{\t} \approx 2/3$ and $(\sum r_i)_{\tbar} \approx 1/9$. With index $\pm$ denoting resonance/antiresonance, eq.~(\ref{eq:WWallchancomb}) then generalizes to \begin{equation} (r_1 + r_2)^+ (r_1 + r_3)^- + (r_1 + r_2)^+ (r_4 + r_5)^- + (r_4 + r_5)^+ (r_1 + r_3)^- + r_4^+ r_5^- + r_5^+ r_4^- ~. \label{eq:WWallchancombgen} \end{equation} \subsection{Nonperturbative Processes} \label{ss:nonpertproc} A few processes are not covered by the discussion so far. These are the ones that depend on the details of hadronic wave functions, and therefore are not strictly calculable perturbatively (although perturbation theory may often provide some guidance). What we have primarily in mind is elastic scattering, diffractive scattering and low-$\pT$ `minimum-bias' events in hadron--hadron collisions, but one can also find corresponding processes in $\gamma \p$ and $\gamma \gamma$ interactions. The description of these processes is rather differently structured from that of the other ones, as is explained below. Models for `minimum-bias' events are discussed in detail in section \ref{ss:multint}, to which we refer for details on this part of the program. \subsubsection{Hadron--hadron interactions} In hadron--hadron interactions, the total hadronic cross section for $AB \to$ anything, $\sigma^{AB}_{\mrm{tot}}$, is calculated using the parametrization of Donnachie and Landshoff \cite{Don92}. In this approach, each cross section appears as the sum of one pomeron term and one reggeon one \begin{equation} \sigma^{AB}_{\mrm{tot}}(s) = X^{AB} \, s^{\epsilon} + Y^{AB} \, s^{-\eta} ~, \label{pg:sigtotpomreg} \end{equation} where $s = E_{\mrm{cm}}^2$. The powers $\epsilon = 0.0808$ and $\eta = 0.4525$ are expected to be universal, whereas the coefficients $X^{AB}$ and $Y^{AB}$ are specific to each initial state. (In fact, the high-energy behaviour given by the pomeron term is expected to be the same for particle and antiparticle interactions, i.e. $X^{\br{A}B} = X^{AB}$.) Parametrizations not provided in \cite{Don92} have been calculated in the same spirit, making use of quark counting rules \cite{Sch93a}. The total cross section is subdivided according to \begin{equation} \sigma^{AB}_{\mrm{tot}}(s) = \sigma^{AB}_{\mrm{el}}(s) + \sigma^{AB}_{\mrm{sd}(XB)}(s) + \sigma^{AB}_{\mrm{sd}(AX)}(s) + \sigma^{AB}_{\mrm{dd}}(s) + \sigma^{AB}_{\mrm{nd}}(s) ~. \label{pg:sigtotsplit} \end{equation} Here `el' is the elastic process $AB \to AB$, `sd$(XB)$' the single diffractive $AB \to XB$, `sd$(AX)$' the single diffractive $AB \to AX$, `dd' the double diffractive $AB \to X_1 X_2$, and `nd' the non-diffractive ones. Higher diffractive topologies, such as central diffraction, are currently neglected. In the following, the elastic and diffractive cross sections and event characteristics are described, as given in the model by Schuler and Sj\"ostrand \cite{Sch94,Sch93a}. The non-diffractive component is identified with the `minimum bias' physics already mentioned, a practical but not unambiguous choice. Its cross section is given by `whatever is left' according to eq.~(\ref{pg:sigtotsplit}), and its properties are discussed in section \ref{ss:multint}. At not too large squared momentum transfers $t$, the elastic cross section can be approximated by a simple exponential fall-off. If one neglects the small real part of the cross section, the optical theorem then gives \begin{equation} \frac{\d\sigma_{\mrm{el}}}{\d t} = \frac{\sigma_{\mrm{tot}}^2}{16 \pi} \, \exp(B_{\mrm{el}} t) ~, \end{equation} and $\sigma_{\mrm{el}} = \sigma_{\mrm{tot}}^2 / 16 \pi B_{\mrm{el}}$. The elastic slope parameter is parametrized by \begin{equation} B_{\mrm{el}} = B^{AB}_{\mrm{el}}(s) = 2 b_A + 2 b_B + 4 s^{\epsilon} -4.2 ~, \end{equation} with $s$ given in units of GeV and $B_{\mrm{el}}$ in GeV$^{-2}$. The constants $b_{A,B}$ are $b_{\p} = 2.3$, $b_{\pi,\rho,\omega,\phi} = 1.4$, $b_{\J/\psi} = 0.23$. The increase of the slope parameter with c.m. energy is faster than the logarithmically one conventionally assumed; that way the ratio $\sigma_{\mrm{el}} / \sigma_{\mrm{tot}}$ remains well-behaved at large energies. The diffractive cross sections are given by \begin{eqnarray} \frac{\d\sigma_{\mrm{sd}(XB)}(s)}{\d t \, \d M^2} & = & \frac{g_{3\pomeron}}{16\pi} \, \beta_{A\pomeron} \, \beta_{B\pomeron}^2 \, \frac{1}{M^2} \, \exp(B_{\mrm{sd}(XB)}t) \, F_{\mrm{sd}} ~, \nonumber \\ \frac{\d\sigma_{\mrm{sd}(AX)}(s)}{\d t \, \d M^2} & = & \frac{g_{3\pomeron}}{16\pi} \, \beta_{A\pomeron}^2 \, \beta_{B\pomeron} \, \frac{1}{M^2} \, \exp(B_{\mrm{sd}(AX)}t) \, F_{\mrm{sd}} ~, \nonumber \\ \frac{\d\sigma_{\mrm{dd}}(s)}{\d t \, \d M_1^2 \, \d M_2^2} & = & \frac{g_{3\pomeron}^2}{16\pi} \, \beta_{A\pomeron} \, \beta_{B\pomeron} \, \frac{1}{M_1^2} \, \frac{1}{M_2^2} \, \exp(B_{\mrm{dd}}t) \, F_{\mrm{dd}} ~. \end{eqnarray} The couplings $\beta_{A\pomeron}$ are related to the pomeron term $X^{AB} s^{\epsilon}$ of the total cross section parametrization, eq.~(\ref{pg:sigtotpomreg}). Picking a reference scale $\sqrt{s_{\mrm{ref}}} = 20$ GeV, the couplings are given by $\beta_{A\pomeron}\beta_{B\pomeron} = X^{AB} \, s_{\mrm{ref}}^{\epsilon}$. The triple-pomeron coupling is determined from single-diffractive data to be $g_{3\pomeron} \approx 0.318$ mb$^{1/2}$; within the context of the formulae in this section. The spectrum of diffractive masses $M$ is taken to begin 0.28 GeV $\approx 2 m_{\pi}$ above the mass of the respective incoming particle and extend to the kinematical limit. The simple $\d M^2 / M^2$ form is modified by the mass-dependence in the diffractive slopes and in the $F_{\mrm{sd}}$ and $F_{\mrm{dd}}$ factors. The slope parameters are assumed to be \begin{eqnarray} B_{\mrm{sd}(XB)}(s) & = & 2b_B + 2\alpha' \ln\left(\frac{s}{M^2}\right) ~, \nonumber \\ B_{\mrm{sd}(AX)}(s) & = & 2b_A + 2\alpha' \ln\left(\frac{s}{M^2}\right) ~, \nonumber \\ B_{\mrm{dd}}(s) & = & 2\alpha' \ln\left(e^4 + \frac{s s_0}{M_1^2 M_2^2} \right) ~. \end{eqnarray} Here $\alpha' = 0.25$ GeV$^{-2}$ and conventionally $s_0$ is picked as $s_0 = 1 / \alpha'$. The term $e^4$ in $B_{\mrm{dd}}$ is added by hand to avoid a breakdown of the standard expression for large values of $M_1^2 M_2^2$. The $b_{A,B}$ terms protect $B_{\mrm{sd}}$ from breaking down; however a minimum value of 2 is still explicitly required for $B_{\mrm{sd}}$, which comes into play e.g. for a $\Jpsi$ state (as part of a VMD photon beam). The kinematical range in $t$ depends on all the masses of the problem. In terms of the scaled variables $\mu_1 = m_A^2/s$, $\mu_2 = m_B^2/s$, $\mu_3 = M_{(1)}^2/s$ ($=m_A^2/s$ when $A$ scatters elastically), $\mu_4 = M_{(2)}^2/s$ ($=m_B^2/s$ when $B$ scatters elastically), and the combinations \begin{eqnarray} C_1 & = & 1 - (\mu_1 + \mu_2 + \mu_3 + \mu_4) + (\mu_1 - \mu_2) (\mu_3 - \mu_4) ~, \nonumber \\ C_2 & = & \sqrt{(1 - \mu_1 -\mu_2)^2 - 4 \mu_1 \mu_2} \, \sqrt{(1 - \mu_3 - \mu_4)^2 - 4 \mu_3 \mu_4} ~, \nonumber \\ C_3 & = & (\mu_3 - \mu_1) (\mu_4 - \mu_2) + (\mu_1 + \mu_4 - \mu_2 - \mu_3) (\mu_1 \mu_4 - \mu_2 \mu_3) ~, \end{eqnarray} one has $t_{\mmin} < t < t_{\mmax}$ with \begin{eqnarray} t_{\mmin} & = & - \frac{s}{2} (C_1 + C_2) ~, \nonumber \\ t_{\mmax} & = & - \frac{s}{2} (C_1 - C_2) = - \frac{s}{2} \, \frac{4C_3}{C_1 + C_2} = \frac{s^2 C_3}{t_{\mmin}} ~. \end{eqnarray} The Regge formulae above for single- and double-diffractive events are supposed to hold in certain asymptotic regions of the total phase space. Of course, there will be diffraction also outside these restrictive regions. Lacking a theory which predicts differential cross sections at arbitrary $t$ and $M^2$ values, the Regge formulae are used everywhere, but fudge factors are introduced in order to obtain `sensible' behaviour in the full phase space. These factors are: \begin{eqnarray} F_{\mrm{sd}} & = & \left( 1 - \frac{M^2}{s} \right) \left( 1 + \frac{c_{\mrm{res}} \, M_{\mrm{res}}^2} {M_{\mrm{res}}^2 + M^2} \right) ~, \nonumber \\ F_{\mrm{dd}} & = & \left( 1 - \frac{\left( M_1 + M_2 \right)^2}{s} \right) \left( \frac{s\, m_{\p}^2}{ s\, m_{\p}^2 + M_1^2\, M_2^2} \right) \nonumber \\ & \times & \left( 1 + \frac{c_{\mrm{res}} \, M_{\mrm{res}}^2} {M_{\mrm{res}}^2 + M_1^2} \right) \left( 1 + \frac{c_{\mrm{res}} \, M_{\mrm{res}}^2} {M_{\mrm{res}}^2 + M_2^2} \right) ~. \end{eqnarray} The first factor in either expression suppresses production close to the kinematical limit. The second factor in $F_{dd}$ suppresses configurations where the two diffractive systems overlap in rapidity space. The final factors give an enhancement of the low-mass region, where a resonance structure is observed in the data. Clearly a more detailed modelling would have to be based on a set of exclusive states rather than on this smeared-out averaging procedure. A reasonable fit to $\p\p / \pbar\p$ data is obtained for $c_{\mrm{res}} = 2$ and $M_{\mrm{res}} = 2$~GeV, for an arbitary particle $A$ which is diffractively excited we use $M_{\mrm{res}}^A = m_A - m_{\p} + 2$~GeV. The diffractive cross-section formulae above have been integrated for a set of c.m. energies, starting at 10 GeV, and the results have been parametrized. The form of these parametrizations is given in ref. \cite{Sch94}, with explicit numbers for the $\p\p/\pbar\p$ case. {\Py} also contains similar parametrizations for $\pi\p$ (assumed to be same as $\rho\p$ and $\omega\p$), $\phi\p$, $\Jpsi\p$, $\rho\rho$ ($\pi\pi$ etc.), $\rho\phi$, $\rho\Jpsi$, $\phi\phi$, $\phi\Jpsi$ and $\Jpsi\Jpsi$. The processes above do not obey the ordinary event mixing strategy. First of all, since their total cross sections are known, it is possible to pick the appropriate process from the start, and then remain with that choice. In other words, if the selection of kinematical variables fails, one would not go back and pick a new process, the way it was done in section \ref{sss:mixingproc}. Second, it is not possible to impose any cuts or restrain allowed incoming or outgoing flavours: if not additional information were to be provided, it would make the whole scenario ill-defined. Third, it is not recommended to mix generation of these processes with that of any of the other ones: normally the other processes have so small cross sections that they would almost never be generated anyway. (We here exclude the cases of `underlying events' and `pile-up events', where mixing is provided for, and even is a central part of the formalism, see sections \ref{ss:multint} and \ref{ss:pileup}.) Once the cross-section parametrizations has been used to pick one of the processes, the variables $t$ and $M$ are selected according to the formulae given above. A $\rho^0$ formed by $\gamma \to \rho^0$ in elastic or diffractive scattering is polarized, and therefore its decay angular distribution in $\rho^0 \to \pi^+ \pi^-$ is taken to be proportional to $\sin^2 \theta$, where the reference axis is given by the $\rho^0$ direction of motion. A light diffractive system, with a mass less than 1 GeV above the mass of the incoming particle, is allowed to decay isotropically into a two-body state. Single-resonance diffractive states, such as a $\Delta^+$, are therefore not explicily generated, but are assumed described in an average, smeared-out sense. A more massive diffractive system is subsequently treated as a string with the quantum numbers of the original hadron. Since the exact nature of the pomeron exchanged between the hadrons is unknown, two alternatives are included. In the first, the pomeron is assumed to couple to (valence) quarks, so that the string is stretched directly between the struck quark and the remnant diquark (antiquark) of the diffractive state. In the second, the interaction is rather with a gluon, giving rise to a `hairpin' configuration in which the string is stretched from a quark to a gluon and then back to a diquark (antiquark). Both of these scenarios could be present in the data; the default choice is to mix them in equal proportions. There is experimental support for more complicated scenarios \cite{Ing85}, wherein the pomeron has a partonic substructure, which e.g. can lead to high-$\pT$ jet production in the diffractive system. The full machinery, wherein a pomeron spectrum is folded with a pomeron-proton hard interaction, is not available in {\Py}. \subsubsection{Photoproduction and $\gamma\gamma$ physics} \label{sss:photoprod} The photoproduction part is still under active development. Currently only interactions between a hadron and a real photon have been studied in detail. $\gamma\gamma$ physics is under study \cite{Sch94a}, and is now preliminarily included for real photons. Deep inelastic scattering on a real photon is also preliminarily included. In the future it is hoped to add interactions of mildly virtual photons (the transition region between real photons and deep inelastic scattering). The total $\gamma\p$ and $\gamma\gamma$ cross sections can again be parametrized in a form like eq.~(\ref{pg:sigtotpomreg}), which is not so obvious since the photon has more complicated structure than an ordinary hadron. In fact, the structure is still not so well understood. The model we outline is the one studied by Schuler and Sj\"ostrand \cite{Sch93,Sch93a}. In this model the physical photon is represented by \begin{equation} | \gamma \rangle = \sqrt{Z_3} \, | \gamma_B \rangle + \sum_{V=\rho^0,\omega,\phi,\Jpsi} \frac{e}{f_V} \, | V \rangle + \frac{e}{f_{\q\qbar}} \, | \q\qbar \rangle + \sum_{\ell=\e,\mu,\tau} \frac{e}{f_{\ell\ell}} \, | \ell^+ \ell^- \rangle ~. \label{pg:gammadecompo} \end{equation} By virtue of this superposition, one is led to a model of $\gamma\p$ interactions, where three different kinds of events may be distinguished: \begin{Itemize} \item Direct events, wherein the bare photon $| \gamma_B \rangle$ interacts directly with a parton from the proton. The process is perturbatively calculable, and no parton distributions of the photon are involved. The typical event structure is two high-$\pT$ jets and a proton remnant, while the photon does not leave behind any remnant. \item VMD events, in which the photon fluctuates into a vector meson, predominantly a $\rho^0$. All the event classes known from ordinary hadron--hadron interactions may thus occur here, such as elastic, diffractive, low-$\pT$ and high-$\pT$ events. For the latter, one may define (VMD) parton distributions of the photon, and the photon also leaves behind a beam remnant. This remnant is smeared in transverse momentum by a typical `primordial $k_{\perp}$' of a few hundred MeV. \item Anomalous events, in which the photon fluctuates into a $\q\qbar$ pair of larger virtuality than in the VMD class. This process is perturbatively calculable, as is the subsequent QCD evolution. It gives rise to the so-called anomalous part of the parton distributions ofthe photon, whence the name for the class. It is assumed that only high-$\pT$ events may occur. Either the $\q$ or the $\qbar$ plays the r\^ole of a beam remnant, but this remnant has a larger $\pT$ than in the VMD case, related to the virtuality of the $\gamma \leftrightarrow \q\qbar$ fluctuation. \end{Itemize} The $| \ell^+ \ell^- \rangle$ states can only interact strongly with partons inside the hadron at higher orders, and can therefore be neglected. In order that the above classification is smooth and free of double counting, one has to introduce scales that separate the three components. The main one is $p_0$, which separates the low-mass vector meson region from the high-mass $| \q\qbar \rangle$ one, $p_0 \approx m_{\phi}/2 \approx 0.5$ GeV. Since it is the same $\gamma\q\qbar$ vertex that is responsible for the bare $\gamma \p$ interactions, $p_0$ is also the lower cut-off of the photon--parton cross sections. In addition, a $\pTmin$ cut-off is needed to separate low-$\pT$ and high-$\pT$ physics; see section \ref{ss:multint}. As it turns out, somewhat different $\pTmin$ values are needed for the VMD and anomalous parts; at least qualitatively this can be understood in terms of different sizes of the wave functions. The VMD and anomalous events are together called resolved ones. In terms of high-$\pT$ jet production, the VMD and anomalous contributions can be combined into a total resolved one, and the same for parton-distribution functions. However, the two classes differ in the structure of the underlying event and in the appearance of soft processes. In terms of cross sections, eq.\ (\ref{pg:gammadecompo}) corresponds to \begin{equation} \sigma_{\mrm{tot}}^{\gamma\p}(s) = \sigma_{\mrm{dir}}^{\gamma\p}(s) + \sigma_{\mrm{VMD}}^{\gamma\p}(s) + \sigma_{\mrm{anom}}^{\gamma\p}(s) ~. \label{pg:gammacrossdecompo} \end{equation} The direct cross section is, to lowest order, the perturbative cross section for the two processes $\gamma\q \to \q\g$ and $\gamma\g \to \q\qbar$, with a lower cut-off $\pT > p_0$. Properly speaking, this should be multiplied by the $Z_3$ coefficient, \begin{equation} Z_3 = 1 - \sum_{V=\rho^0,\omega,\phi,\Jpsi} \left( \frac{e}{f_V} \right)^2 - \left( \frac{e}{f_{\q\qbar}} \right)^2 - \sum_{\ell=\e,\mu,\tau} \left( \frac{e}{f_{\ell\ell}} \right)^2 ~, \end{equation} but normally $Z_3$ is so close to unity as to make no difference. The VMD factor $(e/f_V)^2 = 4\pi\alphaem/f_V^2$ gives the probability for the transition $\gamma \to V$. The coefficients $f_V^2/4\pi$ are determined from data to be (with a non-negligible amount of uncertainty) 2.20 for $\rho^0$, 23.6 for $\omega$, 18.4 for $\phi$ and 11.5 for $\Jpsi$. Together these numbers imply that the photon can be found in a VMD state about 0.4\% of the time, dominated by the $\rho^0$ contribution. All the properties of the VMD interactions can be obtained by appropriately scaling down $V\p$ physics predictions. Thus the whole machinery developed in the previous subsection for hadron--hadron interactions is directly applicable. Also parton distributions of the VMD component inside the photon are obtained by suitable rescaling. The contribution from the `anomalous' high-mass fluctuations depends on the typical scale $\mu$ of the interaction \begin{equation} \left( \frac{e}{f_{\q\qbar}} \right)^2 \approx \frac{\alphaem}{2\pi} \, \frac{N_C}{3} \, \left( 2 \sum_{\q} e_{\q}^2 \right) \ln\left( \frac{\mu^2}{p_0^2} \right) ~, \label{anomintfirst} \end{equation} where $N_C = 3$ and $\q$ runs over the quarks that can be taken massless compared with $\mu$. The logarithmic increase with $\mu$ implies that the anomalous contribution to the total photoproduction cross section ($\mu \sim m_V$) is less important than that to high-$\pT$ jet production ($\mu \sim \pT$). To first approximation, therefore only perturbative jet production above some $\pTmin$ scale is considered. This includes the standard QCD parton--parton scattering processes, with anomalous-photon parton distributions that are fully perturbatively calculable \cite{Sch95}. In order to satisfy the equality in eq.~(\ref{pg:gammacrossdecompo}), with the total cross section known and the direct and VDM contributions already fixed, a behaviour roughly like \begin{equation} \pTmin^{\mrm{anom}}(s) = 0.70 + 0.17 \log^2(1.+0.05\sqrt{s}) \end{equation} is needed over the HERA energy range. This is to be seen entirely as a pragmatic parametrization, not be given any fundamental interpretation. It is based on SaS set~1D, another set might well require a somewhat different form. In $\gamma\gamma$ physics \cite{Sch94a}, the superposition in eq.~(\ref{pg:gammadecompo}) applies separately for each of the two incoming photons. In total there are therefore $3 \times 3 = 9$ combinations. However, trivial symmetry reduces this to six distinct classes, written in terms of the total cross section (cf. eq.~(\ref{pg:gammacrossdecompo})) as \begin{eqnarray} \sigma_{\mrm{tot}}^{\gamma\gamma}(s) & = & \sigma_{\mrm{dir}\times\mrm{dir}}^{\gamma\gamma}(s) + \sigma_{\mrm{VMD}\times\mrm{VMD}}^{\gamma\gamma}(s) + \sigma_{\mrm{anom}\times\mrm{anom}}^{\gamma\gamma}(s) \nonumber \\ & + & 2 \sigma_{\mrm{dir}\times\mrm{VMD}}^{\gamma\gamma}(s) + 2 \sigma_{\mrm{dir}\times\mrm{anom}}^{\gamma\gamma}(s) + 2 \sigma_{\mrm{VMD}\times\mrm{anom}}^{\gamma\gamma}(s) ~. \label{pg:gagacrossdecompo} \end{eqnarray} A parametrization of the total $\gamma\gamma$ cross section and comments on its subdivision into the six classes is found in \cite{Sch94a}. The six different kinds of $\gamma\gamma$ events are thus: \begin{Itemize} \item The direct$\times$direct events, which correspond to the subprocess $\gamma\gamma \to \q\qbar$ (or $\ell^+\ell^-$). The typical event structure is two high-$\pT$ jets and no beam remnants. The lower cut-off is $\pT > p_0$. \item The VMD$\times$VMD events, which have the same properties as the VMD $\gamma\p$ events. There are four by four combinations of the two incoming vector mesons, with one VMD factor for each meson. \item The anomalous$\times$anomalous events, wherein each photon fluctuates into a $\q\qbar$ pair of larger virtuality than in the VMD class. One parton of each pair gives a beam remnant, whereas the other (or a daughter parton thereof) participates in a high-$\pT$ scattering, with $\pT > \pTmin^{\mrm{anom}}$. \item The direct$\times$VMD events, which have the same properties as the direct $\gamma\p$ events. \item The direct$\times$anomalous events, in which a bare photon interacts with a parton from the anomalous photon. The lower cut-off for the hard scattering is given by $\pTmin^{\mrm{anom}}$. The typical structure is then two high-$\pT$ jets and a beam remnant. \item The VMD$\times$anomalous events, which have the same properties as the anomalous $\gamma\p$ events. \end{Itemize} In much of the literature, where a coarser classification us used, our direct$\times$direct is called direct, our direct$\times$VMD and direct$\times$anomalous is called 1-resolved since they both involve one resolved photon which gives a beam remnant, and the rest are called 2-resolves since both photons are resolved and give beam remnants. \clearpage \section{Physics Processes in PYTHIA} \label{s:pytproc} In this section we enumerate the physics processes that are available in {\Py}, introducing the ISUB code that can be used to select desired processes. A number of comments are made about the physics scenarios involved, in particular with respect to underlying assumptions and domain of validity. The section closes with a survey of interesting processes by machine. \subsection{The Process Classification Scheme} \label{ss:ISUBcode} A wide selection of fundamental $2 \to 1$ and $2 \to 2$ tree processes of the Standard Model (electroweak and strong) has been included in {\Py}, and slots are provided for many more, not yet implemented. In addition, a few `minimum-bias'-type processes (like elastic scattering), loop graphs, box graphs, $2 \to 3$ tree graphs and some non-Standard Model processes are included. The classification is not always unique. A process that proceeds only via an $s$-channel state is classified as a $2 \to 1$ process (e.g. $\q \qbar \to \gammaZ \to \ee$), but a $2 \to 2$ cross section may well have contributions from $s$-channel diagrams ($\g \g \to \g \g$ obtains contributions from $\g \g \to \g^* \to \g \g$). Also, in the program, $2 \to 1$ and $2 \to 2$ graphs may sometimes be folded with two $1 \to 2$ splittings to form effective $2 \to 3$ or $2 \to 4$ processes ($\W^+ \W^- \to \H^0$ is folded with $\q \to \q'' \W^+$ and $\q' \to \q''' \W^-$ to give $\q \q' \to \q'' \q''' \H^0$). It is possible to select a combination of subprocesses to simulate, and also afterwards to know which subprocess was actually selected in each event. For this purpose, all subprocesses are numbered according to an ISUB code. The list of possible codes is given in Tables \ref{t:procone}, \ref{t:proctwo}, \ref{t:procthree} and \ref{t:procfour}. Only processes marked with a `+' sign in the first column have been implemented in the program to date. Although ISUB codes were originally designed in a logical fashion, we must admit that subsequent developments of the program have tended to obscure the structure. For instance, the process numbers for Higgs production are spread out, in part as a consequence of the original classification, in part because further production mechanisms have been added one at a time, in whatever free slots could be found. At some future date the subprocess list will therefore be reorganized. In the thematic descriptions that follow the main tables, the processes of interest are repeated in a more logical order. If you want to look for a specific process, it will be easier to find it there. \begin{table}[pt] \caption{Subprocess codes, part 1. First column is `+' for processes implemented and blank for those that are only foreseen. Second is the subprocess number \ttt{ISUB}, and third the description of the process. The final column gives references from which the cross sections have been obtained. See text for further information. \protect\label{t:procone} } \begin{center} \begin{tabular}{|c|r|l|l|@{\protect\rule{0mm}{\tablinsep}}} \hline In & No. & Subprocess & Reference \\ \hline & & a) $2 \to 1$, tree & \\ + & 1 & $\f_i \fbar_i \to \gammaZ$ & \cite{Eic84} \\ + & 2 & $\f_i \fbar_j \to \W^+$ & \cite{Eic84} \\ + & 3 & $\f_i \fbar_i \to \H^0$ & \cite{Eic84} \\ & 4 & $\gamma \W^+ \to \W^+$ & \\ + & 5 & $\Z^0 \Z^0 \to \H^0$ & \cite{Eic84,Cha85} \\ & 6 & $\Z^0 \W^+ \to \W^+$ & \\ & 7 & $\W^+ \W^- \to \Z^0$ & \\ + & 8 & $\W^+ \W^- \to \H^0$ & \cite{Eic84,Cha85} \\ \hline & & b) $2 \to 2$, tree & \\ + & 10 & $\f_i \f_j \to \f_i \f_j$ (QFD) & \cite{Ing87b} \\ + & 11 & $\f_i \f_j \to \f_i \f_j$ (QCD) & \cite{Com77,Ben84,Eic84,Chi90} \\ + & 12 & $\f_i \fbar_i \to \f_k \fbar_k$ & \cite{Com77,Ben84,Eic84,Chi90} \\ + & 13 & $\f_i \fbar_i \to \g \g$ & \cite{Com77,Ben84} \\ + & 14 & $\f_i \fbar_i \to \g \gamma$ & \cite{Hal78,Ben84} \\ + & 15 & $\f_i \fbar_i \to \g \Z^0$ & \cite{Eic84} \\ + & 16 & $\f_i \fbar_j \to \g \W^+$ & \cite{Eic84} \\ & 17 & $\f_i \fbar_i \to \g \H^0$ & \\ + & 18 & $\f_i \fbar_i \to \gamma \gamma$ & \cite{Ber84} \\ + & 19 & $\f_i \fbar_i \to \gamma \Z^0$ & \cite{Eic84} \\ + & 20 & $\f_i \fbar_j \to \gamma \W^+$ & \cite{Eic84,Sam91} \\ & 21 & $\f_i \fbar_i \to \gamma \H^0$ & \\ + & 22 & $\f_i \fbar_i \to \Z^0 \Z^0$ & \cite{Eic84,Gun86} \\ + & 23 & $\f_i \fbar_j \to \Z^0 \W^+$ & \cite{Eic84,Gun86} \\ + & 24 & $\f_i \fbar_i \to \Z^0 \H^0$ & \cite{Ber85} \\ + & 25 & $\f_i \fbar_i \to \W^+ \W^-$ & \cite{Bar94,Gun86} \\ + & 26 & $\f_i \fbar_j \to \W^+ \H^0$ & \cite{Eic84} \\ & 27 & $\f_i \fbar_i \to \H^0 \H^0$ & \\ + & 28 & $\f_i \g \to \f_i \g$ & \cite{Com77,Ben84} \\ + & 29 & $\f_i \g \to \f_i \gamma$ & \cite{Hal78,Ben84} \\ + & 30 & $\f_i \g \to \f_i \Z^0$ & \cite{Eic84} \\ + & 31 & $\f_i \g \to \f_k \W^+$ & \cite{Eic84} \\ & 32 & $\f_i \g \to \f_i \H^0$ & \\ + & 33 & $\f_i \gamma \to \f_i \g$ & \cite{Duk82} \\ + & 34 & $\f_i \gamma \to \f_i \gamma$ & \cite{Duk82} \\ + & 35 & $\f_i \gamma \to \f_i \Z^0$ & \cite{Gab86} \\ + & 36 & $\f_i \gamma \to \f_k \W^+$ & \cite{Gab86} \\ & 37 & $\f_i \gamma \to \f_i \H^0$ & \\ & 38 & $\f_i \Z^0 \to \f_i \g$ & \\ & 39 & $\f_i \Z^0 \to \f_i \gamma$ & \\ & 40 & $\f_i \Z^0 \to \f_i \Z^0$ & \\ \hline \end{tabular} \end{center} \end{table} \begin{table}[pt] \caption{Subprocess codes, part 2. First column is `+' for processes implemented and blank for those that are only foreseen. Second is the subprocess number \ttt{ISUB}, and third the description of the process. The final column gives references from which the cross sections have been obtained. See text for further information. \protect\label{t:proctwo} } \begin{center} \begin{tabular}{|c|r|l|l|@{\protect\rule{0mm}{\tablinsep}}} \hline In & No. & Subprocess & Reference \\ \hline & & b) $2 \to 2$, tree (cont'd) & \\ & 41 & $\f_i \Z^0 \to \f_k \W^+$ & \\ & 42 & $\f_i \Z^0 \to \f_i \H^0$ & \\ & 43 & $\f_i \W^+ \to \f_k \g$ & \\ & 44 & $\f_i \W^+ \to \f_k \gamma$ & \\ & 45 & $\f_i \W^+ \to \f_k \Z^0$ & \\ & 46 & $\f_i \W^+ \to \f_k \W^+$ & \\ & 47 & $\f_i \W^+ \to \f_k \H^0$ & \\ & 48 & $\f_i \H^0 \to \f_i \g$ & \\ & 49 & $\f_i \H^0 \to \f_i \gamma$ & \\ & 50 & $\f_i \H^0 \to \f_i \Z^0$ & \\ & 51 & $\f_i \H^0 \to \f_k \W^+$ & \\ & 52 & $\f_i \H^0 \to \f_i \H^0$ & \\ + & 53 & $\g \g \to \f_k \fbar_k$ & \cite{Com77,Ben84} \\ + & 54 & $\g \gamma \to \f_k \fbar_k$ & \cite{Duk82} \\ & 55 & $\g \Z^0 \to \f_k \fbar_k$ & \\ & 56 & $\g \W^+ \to \f_k \fbar_l$ & \\ & 57 & $\g \H^0 \to \f_k \fbar_l$ & \\ + & 58 & $\gamma \gamma \to \f_k \fbar_k$ & \cite{Bar90} \\ & 59 & $\gamma \Z^0 \to \f_k \fbar_k$ & \\ & 60 & $\gamma \W^+ \to \f_k \fbar_l$ & \\ & 61 & $\gamma \H^0 \to \f_k \fbar_k$ & \\ & 62 & $\Z^0 \Z^0 \to \f_k \fbar_k$ & \\ & 63 & $\Z^0 \W^+ \to \f_k \fbar_l$ & \\ & 64 & $\Z^0 \H^0 \to \f_k \fbar_k$ & \\ & 65 & $\W^+ \W^- \to \f_k \fbar_k$ & \\ & 66 & $\W^+ \H^0 \to \f_k \fbar_l$ & \\ & 67 & $\H^0 \H^0 \to \f_k \fbar_k$ & \\ + & 68 & $\g \g \to \g \g$ & \cite{Com77,Ben84} \\ + & 69 & $\gamma \gamma \to \W^+ \W^-$ & \cite{Kat83} \\ + & 70 & $\gamma \W^+ \to \Z^0 \W^+$ & \cite{Kun87} \\ + & 71 & $\Z^0 \Z^0 \to \Z^0 \Z^0$ (longitudinal) & \cite{Abb87} \\ + & 72 & $\Z^0 \Z^0 \to \W^+ \W^-$ (longitudinal) & \cite{Abb87} \\ + & 73 & $\Z^0 \W^+ \to \Z^0 \W^+$ (longitudinal) & \cite{Dob91} \\ & 74 & $\Z^0 \H^0 \to \Z^0 \H^0$ & \\ & 75 & $\W^+ \W^- \to \gamma \gamma$ & \\ + & 76 & $\W^+ \W^- \to \Z^0 \Z^0$ (longitudinal) & \cite{Ben87b} \\ + & 77 & $\W^+ \W^{\pm} \to \W^+ \W^{\pm}$ (longitudinal) & \cite{Dun86,Bar90a} \\ & 78 & $\W^+ \H^0 \to \W^+ \H^0$ & \\ & 79 & $\H^0 \H^0 \to \H^0 \H^0$ & \\ + & 80 & $\q_i \gamma \to \q_k \pi^{\pm}$ & \cite{Bag82} \\ \hline \end{tabular} \end{center} \end{table} \begin{table}[pt] \caption{Subprocess codes, part 3. First column is `+' for processes implemented and blank for those that are only foreseen. Second is the subprocess number \ttt{ISUB}, and third the description of the process. The final column gives references from which the cross sections have been obtained. See text for further information. \protect\label{t:procthree} } \begin{center} \begin{tabular}{|c|r|l|l|@{\protect\rule{0mm}{\tablinsep}}} \hline In & No. & Subprocess & Reference \\ \hline & & c) $2 \to 2$, tree, massive final quarks & \\ + & 81 & $\f_i \fbar_i \to \Q_k \Qbar_k$ & \cite{Com79} \\ + & 82 & $\g \g \to \Q_k \Qbar_k$ & \cite{Com79} \\ + & 83 & $\q_i \f_j \to \Q_k \f_l$ & \cite{Dic86} \\ + & 84 & $\g \gamma \to \Q_k \Qbar_k$ & \cite{Fon81} \\ + & 85 & $\gamma \gamma \to \F_k \Fbar_k$ & \cite{Bar90} \\ + & 86 & $\g \g \to \Jpsi \g$ & \cite{Bai83} \\ + & 87 & $\g \g \to \chi_{0 \c} \g$ & \cite{Gas87} \\ + & 88 & $\g \g \to \chi_{1 \c} \g$ & \cite{Gas87} \\ + & 89 & $\g \g \to \chi_{2 \c} \g$ & \cite{Gas87} \\ + & 106 & $\g \g \to \Jpsi \gamma$ & \cite{Dre91} \\ + & 107 & $\g \gamma \to \Jpsi \g$ & \cite{Ber81} \\ + & 108 & $\gamma \gamma \to \Jpsi \gamma$ & \cite{Jun97} \\ \hline & & d) `minimum bias' & \\ + & 91 & elastic scattering & \cite{Sch94} \\ + & 92 & single diffraction ($AB \to XB$) & \cite{Sch94} \\ + & 93 & single diffraction ($AB \to AX$) & \cite{Sch94} \\ + & 94 & double diffraction & \cite{Sch94} \\ + & 95 & low-$\pT$ production & \cite{Sjo87} \\ \hline & & e) $2 \to 1$, loop & \\ & 101 & $\g \g \to \Z^0$ & \\ + & 102 & $\g \g \to \H^0$ & \cite{Eic84} \\ + & 103 & $\gamma \gamma \to \H^0$ & \cite{Dre89} \\ \hline & & f) $2 \to 2$, box & \\ + & 110 & $\f_i \fbar_i \to \gamma \H^0$ & \cite{Ber85a} \\ + & 111 & $\f_i \fbar_i \to \g \H^0$ & \cite{Ell88} \\ + & 112 & $\f_i \g \to \f_i \H^0$ & \cite{Ell88} \\ + & 113 & $\g \g \to \g \H^0$ & \cite{Ell88} \\ + & 114 & $\g \g \to \gamma \gamma$ & \cite{Con71,Ber84,Dic88} \\ + & 115 & $\g \g \to \g \gamma$ & \cite{Con71,Ber84,Dic88} \\ & 116 & $\g \g \to \gamma \Z^0$ & \\ & 117 & $\g \g \to \Z^0 \Z^0$ & \\ & 118 & $\g \g \to \W^+ \W^-$ & \\ & 119 & $\gamma \gamma \to \g \g$ & \\ \hline & & g) $2 \to 3$, tree & \\ + & 121 & $\g \g \to \Q_k \Qbar_k \H^0$ & \cite{Kun84} \\ + & 122 & $\q_i \qbar_i \to \Q_k \Qbar_k \H^0$ & \cite{Kun84} \\ + & 123 & $\f_i \f_j \to \f_i \f_j \H^0$ ($\Z \Z$ fusion) & \cite{Cah84} \\ + & 124 & $\f_i \f_j \to \f_k \f_l \H^0$ ($\W^+\W^-$ fusion) & \cite{Cah84} \\ + & 131 & $\g \g \to \Z^0 \Q_k \br{\Q}_k$ & \cite{Eij90} \\ \hline \end{tabular} \end{center} \end{table} \begin{table}[pt] \caption{Subprocess codes, part 4. First column is `+' for processes implemented and blank for those that are only foreseen. Second is the subprocess number \ttt{ISUB}, and third the description of the process. The final column gives references from which the cross sections have been obtained. See text for further information. \protect\label{t:procfour} } \begin{center} \begin{tabular}{|c|r|l|l|@{\protect\rule{0mm}{\tablinsep}}} \hline In & No. & Subprocess & Reference \\ \hline & & h) non-Standard Model, $2 \to 1$ & \\ + & 141 & $\f_i \fbar_i \to \gamma/\Z^0/\Z'^0$ & \cite{Alt89} \\ + & 142 & $\f_i \fbar_j \to \W'^+$ & \cite{Alt89} \\ + & 143 & $\f_i \fbar_j \to \H^+$ & \cite{Gun87} \\ + & 144 & $\f_i \fbar_j \to \R$ & \cite{Ben85a} \\ + & 145 & $\q_i \ell_j \to \L_{\Q}$ & \cite{Wud86} \\ + & 147 & $\d \g \to \d^*$ & \cite{Bau90} \\ + & 148 & $\u \g \to \u^*$ & \cite{Bau90} \\ + & 149 & $\g \g \to \eta_{\mrm{techni}}$ & \cite{Eic84,App92} \\ + & 151 & $\f_i \fbar_i \to \H'^0$ & \cite{Eic84} \\ + & 152 & $\g \g \to \H'^0$ & \cite{Eic84} \\ + & 153 & $\gamma \gamma \to \H'^0$ & \cite{Dre89} \\ + & 156 & $\f_i \fbar_i \to \A^0$ & \cite{Eic84} \\ + & 157 & $\g \g \to \A^0$ & \cite{Eic84} \\ + & 158 & $\gamma \gamma \to \A^0$ & \cite{Dre89} \\ \hline & & i) non-Standard Model, $2 \to 2$ and $2 \to 3$ & \\ + & 161 & $\f_i \g \to \f_k \H^+$ & \cite{Bar88} \\ + & 162 & $\q \g \to \ell \L_{\Q}$ & \cite{Hew88} \\ + & 163 & $\g \g \to \L_{\Q} \br{\L}_{\Q}$ & \cite{Hew88,Eic84} \\ + & 164 & $\q_i \qbar_i \to \L_{\Q} \br{\L}_{\Q}$ & \cite{Hew88} \\ + & 165 & $\f_i \fbar_i \to \f_k \fbar_k$ (via $\gammaZ$) & \cite{Eic84,Lan91} \\ + & 166 & $\f_i \fbar_j \to \f_k \fbar_l$ (via $\W^{\pm}$) & \cite{Eic84,Lan91} \\ + & 167 & $\q \q' \to \q'' \d^*$ & \cite{Bau90} \\ + & 168 & $\q \q' \to \q'' \u^*$ & \cite{Bau90} \\ + & 171 & $\f_i \fbar_i \to \Z^0 \H'^0$ & \cite{Eic84} \\ + & 172 & $\f_i \fbar_j \to \W^+ \H'^0$ & \cite{Eic84} \\ + & 173 & $\f_i \f_j \to \f_i \f_j \H'^0$ ($\Z \Z$ fusion) & \cite{Cah84} \\ + & 174 & $\f_i \f_j \to \f_k \f_l \H'^0$ ($\W^+\W^-$ fusion) & \cite{Cah84} \\ + & 176 & $\f_i \fbar_i \to \Z^0 \A^0$ & \cite{Eic84} \\ + & 177 & $\f_i \fbar_j \to \W^+ \A^0$ & \cite{Eic84} \\ + & 178 & $\f_i \f_j \to \f_i \f_j \A^0$ ($\Z \Z$ fusion) & \cite{Cah84} \\ + & 179 & $\f_i \f_j \to \f_k \f_l \A^0$ ($\W^+\W^-$ fusion) & \cite{Cah84} \\ + & 181 & $\g \g \to \Q_k \Qbar_k \H'^0$ & \cite{Kun84} \\ + & 182 & $\q_i \qbar_i \to \Q_k \Qbar_k \H'^0$ & \cite{Kun84} \\ + & 186 & $\g \g \to \Q_k \Qbar_k \A^0$ & \cite{Kun84} \\ + & 187 & $\q_i \qbar_i \to \Q_k \Qbar_k \A^0$ & \cite{Kun84} \\ \hline \end{tabular} \end{center} \end{table} In the following, $\f_i$ represents a fundamental fermion of flavour $i$, i.e. $\d$, $\u$, $\s$, $\c$, $\b$, $\t$, $\lrm$, $\hrm$, $\e^-$, $\nu_{\e}$, $\mu^-$, $\nu_{\mu}$, $\tau^-$, $\nu_{\tau}$, $\chi^-$ or $\nu_{\chi}$. A corresponding antifermion is denoted by $\fbar_i$. In several cases, some classes of fermions are explicitly excluded, since they do not couple to the $\g$ or $\gamma$ (no $\ee \to \g \g$, e.g.). When processes have only been included for quarks, while leptons might also have been possible, the notation $\q_i$ is used. A lepton is denoted by $\ell$; in a few cases neutrinos are also lumped under this heading. In processes where fermion masses are explicitly included in the matrix elements, an $\F$ is used to denote an arbitrary fermion and a $\Q$ a quark. Flavours appearing already in the initial state are denoted by indices $i$ and $j$, whereas new flavours in the final state are denoted by $k$ and $l$. Charge-conjugate channels are always assumed included as well (where separate), and processes involving a $\W^+$ also imply those involving a $\W^-$. Wherever $\Z^0$ is written, it is understood that $\gamma^*$ and $\gammaZ$ interference should be included as well (with possibilities to switch off either, if so desired). In some cases this is not fully implemented, see further below. Correspondingly, $\Z'^0$ denotes the complete set $\gamma^*/\Z^0/\Z'^0$ (or some subset of it). Thus the notation $\gamma$ is only used for a photon on the mass shell. In the last column of the tables below, references are given to works from which formulae have been taken. Sometimes these references are to the original works on the subject, sometimes only to the place where the formulae are given in the most convenient or accessible form, or where chance lead us. Apologies to all matrix-element calculators who are not mentioned. However, remember that this is not a review article on physics processes, but only a way for readers to know what is actually found in the program, for better or worse. In several instances, errata have been obtained from the authors. Often the formulae given in the literature have been generalized to include trivial radiative corrections, Breit--Wigner line shapes with $\hat{s}$-dependent widths (see section \ref{ss:kinemreson}), etc. The following sections contain some useful comments on the processes included in the program, grouped by physics interest rather than sequentially by ISUB or \ttt{MSEL} code (see \ref{ss:PYswitchkin} for further information on the \ttt{MSEL} code). The different ISUB and \ttt{MSEL} codes that can be used to simulate the different groups are given. ISUB codes within brackets indicate the kind of processes that indirectly involve the given physics topic, although only as part of a larger whole. Some obvious examples, such as the possibility to produce jets in just about any process, are not spelled out in detail. The text at times contains information on which special switches or parameters are of particular interest to a given process. All these switches are described in detail in section \ref{ss:PYswitchpar}, but are alluded to here so as to provide a more complete picture of the possibilities available for the different subprocesses. However, the list of possibilities is certainly not exhausted by the text below. \subsection{QCD Processes} In this section we discuss scatterings exclusively between coloured partons --- a process like $\ee \to \gammaZ \to \q\qbar$ is also traditionally called a QCD event, but is here book-kept as $\gammaZ$ production. \subsubsection{QCD jets} \label{sss:QCDjetclass} \ttt{MSEL} = 1, 2 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 11 & $\q_i \q_j \to \q_i \q_j$ \\ 12 & $\q_i \qbar_i \to \q_k \qbar_k$ \\ 13 & $\q_i \qbar_i \to \g \g$ \\ 28 & $\q_i \g \to \q_i \g$ \\ 53 & $\g \g \to \q_k \qbar_k$ \\ 68 & $\g \g \to \g \g$ \\ \end{tabular} No higher-order processes are explicitly included, nor any higher-order loop corrections to the $2 \to 2$ processes. However, by initial- and final-state QCD radiation, multijet events are being generated, starting from the above processes. The shower rate of multijet production is clearly uncertain by some amount, especially for well-separated jets. A string-based fragmentation scheme such as the Lund model needs cross sections for the different colour flows; these have been calculated in \cite{Ben84} and differ from the usual calculations by interference terms of the order $1/N_C^2$. By default, the standard QCD expressions for the differential cross sections are used. In this case, the interference terms are distributed on the various colour flows according to the pole structure of the terms. However, the interference terms can be excluded, by changing \ttt{MSTP(34)} As an example, consider subprocess 28, $\q \g \to \q \g$. The total cross section for this process, obtained by summing and squaring the Feynman $\hat{s}$-, $\hat{t}$-, and $\hat{u}$-channel graphs, is \cite{Com77} \begin{equation} 2 \left( 1 - \frac{\hat{u}\hat{s}}{\hat{t}^2} \right) - \frac{4}{9} \left( \frac{\hat{s}}{\hat{u}} + \frac{\hat{u}}{\hat{s}} \right) - 1 ~. \end{equation} (An overall factor $\pi \alphas^2/\hat{s}^2$ is ignored.) Using the identity of the Mandelstam variables for the massless case, $\hat{s} + \hat{t} + \hat{u} = 0$, this can be rewritten as \begin{equation} \frac{\hat{s}^2 + \hat{u}^2}{\hat{t}^2} - \frac{4}{9} \left( \frac{\hat{s}}{\hat{u}} + \frac{\hat{u}}{\hat{s}} \right) ~. \end{equation} On the other hand, the cross sections for the two possible colour flows of this subprocess are \cite{Ben84} \begin{eqnarray} A: & & \frac{4}{9} \left( 2 \frac{\hat{u}^2}{\hat{t}^2} - \frac{\hat{u}}{\hat{s}} \right) ~; \nonumber \\ B: & & \frac{4}{9} \left( 2 \frac{\hat{s}^2}{\hat{t}^2} - \frac{\hat{s}}{\hat{u}} \right) ~. \end{eqnarray} Colour configuration $A$ is one in which the original colour of the $\q$ annihilates with the anticolour of the $\g$, the $\g$ colour flows through, and a new colour--anticolour is created between the final $\q$ and $\g$. In colour configuration $B$, the gluon anticolour flows through, but the $\q$ and $\g$ colours are interchanged. Note that these two colour configurations have different kinematics dependence. For \ttt{MSTP(34)=0}, these are the cross sections actually used. The sum of the $A$ and $B$ contributions is \begin{equation} \frac{8}{9} \frac{\hat{s}^2 + \hat{u}^2}{\hat{t}^2} - \frac{4}{9} \left( \frac{\hat{s}}{\hat{u}} + \frac{\hat{u}}{\hat{s}} \right) ~. \end{equation} The difference between this expression and that of \cite{Com77}, corresponding to the interference between the two colour-flow configurations, is then \begin{equation} \frac{1}{9} \frac{\hat{s}^2 + \hat{u}^2}{\hat{t}^2} ~, \end{equation} which can be naturally divided between colour flows $A$ and $B$: \begin{eqnarray} A: & & \frac{1}{9} \frac{\hat{u}^2}{\hat{t}^2} ~; \nonumber \\ B: & & \frac{1}{9} \frac{\hat{s}^2}{\hat{t}^2} ~. \end{eqnarray} For \ttt{MSTP(34)=1}, the standard QCD matrix element is therefore used, with the same relative importance of the two colour configurations as above. Similar procedures are followed also for the other QCD subprocesses. All the matrix elements in this group are for massless quarks (although final-state quarks are of course put on the mass shell). As a consequence, cross sections are divergent for $\pT \to 0$, and some kind of regularization is required. Normally you are expected to set the desired $\pTmin$ value in \ttt{CKIN(3)}. The new flavour produced in the annihilation processes (ISUB = 12 and 53) is determined by the flavours allowed for gluon splitting into quark--antiquark; see switch \ttt{MDME}. \subsubsection{Heavy flavours} \label{sss:heavflavclass} \ttt{MSEL} = 4, 5, 6, 7, 8 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 81 & $\q_i \qbar_i \to \Q_k \Qbar_k$ \\ 82 & $\g \g \to \Q_k \Qbar_k$ \\ (83) & $\q_i \f_j \to Q_k f_l$ \\ \end{tabular} The matrix elements in this group differ from the corresponding ones in the group above in that they correctly take into account the quark masses. As a consequence, the cross sections are finite for $\pT \to 0$. It is therefore not necessary to introduce any special cuts. The two first processes that appear here are the dominant lowest-order graphs in hadron colliders --- a few other graphs will be mentioned later, such as process 83, which is important for a heavy top. The choice of flavour to produce is according to a hierarchy of options: \begin{Enumerate} \item if \ttt{MSEL=4-8} then the flavour is set by the \ttt{MSEL} value; \item else if \ttt{MSTP(7)=1-8} then the flavour is set by the \ttt{MSTP(7)} value; \item else the flavour is determined by the heaviest flavour allowed for gluon splitting into quark--antiquark; see switch \ttt{MDME}. \end{Enumerate} Note that only one heavy flavour is allowed at a time; if more than one is turned on in \ttt{MDME}, only the heaviest will be produced (as opposed to the case for ISUB = 12 and 53 above, where more than one flavour is allowed simultaneously). The lowest-order processes listed above just represent one source of heavy-flavour production. Heavy quarks can also be present in the parton distributions at the $Q^2$ scale of the hard interaction, leading to processes like $\Q \g \to \Q \g$, so-called flavour excitation, or they can be created by gluon splittings $\g \to \Q \Qbar$ in initial- or final-state shower evolution. In fact, as the c.m. energy is increased, these other processes gain in importance relative to the lowest-order production graphs above. As as example, only 10\% of the $\b$ production at LHC energies come from the lowest-order graphs. The figure is even smaller for charm, while it is at or above 50\% for top. At LHC energies, the specialized treatment described in this subsection is therefore only of interest for top (and potential fourth-generation quarks) --- the higher-order corrections can here be approximated by an effective $K$ factor, except possibly in some rare corners of phase space. For charm and bottom, on the other hand, it is necessary to simulate the full event sample (within the desired kinematics cuts), and then only keep those events with $\b/\c$ either from lowest-order production, or flavour excitation, or gluon splitting. Obviously this may be a time-consuming enterprise --- although the probability for a high-$\pT$ event to contain (at least) one charm or bottom pair is fairly large, most of these heavy flavours are carrying a small fraction of the total $\pT$ flow of the jets, and therefore do not survive normal experimental cuts. As an aside, it is not only for the lowest-order graphs that events may be generated with a guaranteed heavy-flavour content. One may also generate the flavour excitation process by itself, in the massless approximation, using ISUB = 28 and setting the \ttt{KFIN} array appropriately. No trick exists to force the gluon splittings without introducing undesirable biases, however. The cross section for a heavy quark pair close to threshold can be modified according to the formulae of \cite{Fad90}, see \ttt{MSTP(35)}. Here threshold effects due to $\Q\Qbar$ bound-state formation are taken into account in a smeared-out, average sense. Then the na\"{\i}ve cross section is multiplied by the squared wave function at the origin. In a colour-singlet channel this gives a net enhancement of the form \begin{equation} |\Psi^{(s)}(0)|^2 = \frac{X_{(s)}}{1 - \exp(- X_{(s)})} ~ , ~~~ \mrm{where}~ X_{(s)} = \frac{4}{3} \frac{\pi \alphas}{\beta} ~, \label{pp:threshenh} \end{equation} while in a colour octet channel there is a net suppression given by \begin{equation} |\Psi^{(8)}(0)|^2 = \frac{X_{(8)}}{\exp(- X_{(8)}) -1} ~ , ~~~ \mrm{where}~ X_{(8)} = \frac{1}{6} \frac{\pi \alphas}{\beta} ~. \label{pp:threshsup} \end{equation} The $\alphas$ factor in this expression is related to the energy scale of bound-state formation; it is selected independently from the one of the standard production cross section. The presence of a threshold factor affects the total rate and also kinematical distributions. Heavy flavours, i.e. top and fourth generation, are assumed to be so short-lived that they decay before they have time to hadronize. This means that the light quark in the decay $\Q \to \W^{\pm} \q$ inherits the colour of the heavy one. The new {\Py} description represents a change of philosophy compared to previous versions, formulated at a time when the top was thought to be much lighter than is believed currently. However, optionally the old description may still be used, where top hadrons are formed and these subsequently allowed to decay; see \ttt{MSTP(48)} and \ttt{MSTP(49)}. For event shapes the difference between the two time orderings normally has only marginal effects \cite{Sjo92a}. It should be noted that cross section calculations are different in the two cases. If the top (or the fourth generation fermion) is assumed short-lived, then it is treated like a resonance in the sense of section \ref{sss:resdecaycross}, i.e. the cross-section is reduced so as only to correspond to the channels left open by the user. This also includes the restrictions on secondary decays, i.e. on the decays of a $\W^+$ or a $\H^+$ produced in the top decay. If the top is allowed to form hadrons, no such reduction takes place. Branching ratios then have to be folded in by hand to get the correct cross sections. The logic behind this difference is that if hadronization takes place, one would be allowed e.g. to decay the $\T^0$ and $\T^+$ meson according to different branching ratios. But which $\T$ mesons are to be formed is not known at the top quark creation, so one could not weight for that. For a $\t$ quark which decays rapidly this ambiguity does not exist, and so a reduction factor can be introduced directly coupled to the $\t$ quark production process. This rule about cross-section calculations applies to all the processes explicitly set up to handle heavy flavour creation. In addition to the ones above, this means all the ones in Tables \ref{t:procone}--\ref{t:procfour} where the fermion final state is given as capital letters (`$\Q$' and `$\F$') and also flavours produced in resonance decays ($\Z^0$, $\W^{\pm}$, $\H^0$, etc., including processes 165 and 166). However, heavy flavours can also be produced in a process such as 31, $\q_i \g \to \q_k \W^{\pm}$, where $\q_k$ could be a top quark. In this case, the thrust of the description is clearly on light flavours --- the kinematics of the process is formulated in the massless fermion limit --- so any top production is purely incidental. Since here the choice of scattered flavour is only done at a later stage, the top branching ratios are not correctly folded in to the hard scattering cross section. So, for applications like these, it is not recommended to restrict the allowed top decay modes. Often one might like to get rid of the possibility of producing top together with light flavours. This can be done by switching off (i.e. setting \ttt{MDME(I,1)=0}) the `channels' $\d \to \W^- \t$, $\s \to \W^- \t$, $\b \to \W^- \t$, $\g \to \t\tbar$ and $\gamma \to \t\tbar$. Also any heavy flavours produced by parton shower evolution would not be correctly weighted into the cross section. However, currently top production is switched off in both initial (see \ttt{KFIN} array) and final (see \ttt{MSTJ(45)}) state radiation. \subsubsection{J/$\psi$} \label{sss:Jpsiclass} ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 86 & $\g \g \to \Jpsi \g$ \\ 87 & $\g \g \to \chi_{0 \c} \g$ \\ 88 & $\g \g \to \chi_{1 \c} \g$ \\ 89 & $\g \g \to \chi_{2 \c} \g$ \\ 106 & $\g \g \to \Jpsi \gamma$ \\ 107 & $\g \gamma \to \Jpsi \g$ \\ 108 & $\gamma \gamma \to \Jpsi \gamma$ \\ \end{tabular} One may distinguish three main sources of $\Jpsi$ production. \begin{Enumerate} \item Decays of $\B$ mesons and baryons. \item Parton-shower evolution, wherein a $\c$ and a $\cbar$ quark produced in adjacent branchings (e.g. $\g \to \g \g \to \c \cbar \c \cbar$) turn out to have so small an invariant mass that the pair collapses to a single particle. \item Direct production, where a $\c$ quark loop gives a coupling between a set of gluons and a $\c\cbar$ bound state. Higher-lying states, like the $\chi_c$ ones, may subsequently decay to $\Jpsi$. \end{Enumerate} In this section are given the main processes for the third source, intended for applications at hadron colliders at non-vanishing transverse momenta --- in the limit of $\pT \to 0$ it is necessary to include a number of $2 \to 1$ processes and to regularize divergences in the $2 \to 2$ graphs above. The cross sections depend on wave function values at the origin, see \ttt{PARP(38)} and \ttt{PARP(39)}. A review of the physics issues involved may be found in \cite{Glo88} (note, however, that the choice of $Q^2$ scale is different in {\Py}). \subsubsection{Minimum bias} \label{sss:minbiasclass} \ttt{MSEL} = 1, 2 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 91 & elastic scattering \\ 92 & single diffraction ($AB \to XB$) \\ 93 & single diffraction ($AB \to AX$) \\ 94 & double diffraction \\ 95 & low-$\pT$ production \\ \end{tabular} These processes are briefly discussed in section \ref{ss:nonpertproc}. Currently they are mainly intended for interactions between hadrons, although one may also consider $\gamma \p$ interactions in the option where the incoming photon is assumed resolved, \ttt{MSTP(14)=1} or \ttt{=2}. A possible extension to $\gamma \gamma$ interactions is not yet available. Uncertainties come from a number of sources, e.g. from the parametrizations of the various cross sections and slope parameters. In diffractive scattering, the structure of the selected hadronic system may be regulated with \ttt{MSTP(101)}. No high-$\pT$ jet production in diffractive events is included so far. The subprocess 95, low-$\pT$ events, is somewhat unique in that no meaningful physical border-line to high-$\pT$ events can be defined. Even if the QCD $2 \to 2$ high-$\pT$ processes are formally switched off, some of the generated events will be classified as belonging to this group, with a $\pT$ spectrum of interactions to match the `minimum-bias' event sample. Only with the option \ttt{MSTP(82)=0} will subprocess 95 yield strictly low-$\pT$ events, events which will then probably not be compatible with any experimental data. A number of options exist for the detailed structure of low-$\pT$ events, see in particular \ttt{MSTP(81)} and \ttt{MSTP(82)}. Further details on the model(s) for minimum-bias events are found in section \ref{ss:multint}. \subsection{Electroweak Gauge Bosons} This section covers the production and/or exchange of $\gamma$, $\Z^0$ and $\W^{\pm}$ gauge bosons, singly and in pairs. The topic of longitudinal gauge-boson scattering at high energies is deferred to the Higgs section, since the presence or absence of a Higgs here makes a big difference. \subsubsection{Prompt photon production} \label{sss:promptgammaclass} \ttt{MSEL} = 10 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 14 & $\q_i \qbar_i \to \g \gamma$ \\ 18 & $\f_i \fbar_i \to \gamma \gamma$ \\ 29 & $\q_i \g \to \q_i \gamma$ \\ 114 & $\g \g \to \gamma \gamma$ \\ 115 & $\g \g \to \g \gamma$ \\ \end{tabular} In hadron colliders, processes ISUB = 14 and 29 give the main source of single-$\gamma$ production, with ISUB = 115 giving an additional contribution which, in some kinematics regions, may become important. For $\gamma$-pair production, the process ISUB = 18 is often overshadowed in importance by ISUB = 114. Another source of photons is bremsstrahlung off incoming or outgoing quarks. This has to be treated on an equal footing with QCD parton showering. For time-like parton-shower evolution, i.e. in the final-state showering and in the side branches of the initial-state showering, photon emission may be switched on or off with \ttt{MSTJ(41)}. Photon radiation off the space-like incoming quark legs is not yet included, but should be of lesser importance for production at reasonably large $\pT$ values. Radiation off an incoming electron is included in a leading-log approximation. {\bf Warning:} the cross sections for the box graphs 114 and 115 become very complicated, numerically unstable and slow when the full quark mass dependence is included. For quark masses much below the $\hat{s}$ scale, the simplified massless expressions are therefore used --- a fairly accurate approximation. However, there is another set of subtle numerical cancellations between different terms in the massive matrix elements in the region of small-angle scattering. The associated problems have not been sorted out yet. There are therefore two possible solutions. One is to use the massless formulae throughout. The program then becomes faster and numerically stable, but does not give, for example, the characteristic dip (due to destructive interference) at top threshold. This is the current default procedure, with five flavours assumed, but this number can be changed in \ttt{MSTP(38)}. The other possibility is to impose cuts on the scattering angle of the hard process, see \ttt{CKIN(27)} and \ttt{CKIN(28)}, since the numerically unstable regions are when $|\cos\hat{\theta}|$ is close to unity. It is then also necessary to change \ttt{MSTP(38)} to 0. \subsubsection{Photoproduction and $\gamma\gamma$ physics} \label{sss:photoprodclass} \ttt{MSEL} = 1, 2, 4, 5, 6, 7, 8 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 33 & $\q_i \gamma \to \q_i \g$ \\ 34 & $\f_i \gamma \to \f_i \gamma$ \\ 54 & $\g \gamma \to \q_k \qbar_k$ \\ 58 & $\gamma \gamma \to \f_k \fbar_k$ \\ 80 & $\q_i \gamma \to \q_k \pi^{\pm}$ \\ 84 & $\g \gamma \to \Q_k \Qbar_k$ \\ 85 & $\gamma \gamma \to \F_k \Fbar_k$ \\ \end{tabular} An (almost) real photon has both a point-like component and a hadron-like one. This means that several classes of processes may be distinguished, see section \ref{sss:photoprod}. \begin{Enumerate} \item The processes listed above are possible when the photon interacts as a point-like particle, i.e. couples directly to quarks and leptons. \item When the photon acts like a hadron, i.e. is resolved in a partonic substructure, then high-$\pT$ parton--parton interactions are possible, as already described in sections \ref{sss:QCDjetclass} and \ref{sss:promptgammaclass}. These interactions may be further subdivided into VMD and anomalous ones \cite{Sch93,Sch93a}. \item A hadron-like photon can also produce the equivalent of the minimum bias processes of section \ref{sss:minbiasclass}. \end{Enumerate} For $\gamma\p$ events, we believe that the best description can be obtained when three separate event classes are combined, one for direct, one for VMD and one for anomalous events, see the detailed description in \cite{Sch93,Sch93a}. These correspond to \ttt{MSTP(14)} being 0, 2 and 3, respectively. The direct and anomalous components are high-$\pT$ only, while VMD contains both high-$\pT$ and low-$\pT$ events. The option \ttt{MSTP(14)=1} combines the VMD and anomalous parts of the photon into one single resolved photon concept, which therefore is less precise than the full subdivision. When combining three runs to obtain the totality of $\gamma\p$ interactions, to the best of our knowledge, it is necessary to choose the $\pT$ cut-offs with some care, so as to represent the expected total cross section. \begin{Itemize} \item The direct processes only depend on the \ttt{CKIN(3)} cut-off of the generation, with preferred value 0.5 GeV \cite{Sch93,Sch93a}. Since this value is so low, one must remember to reduce a few other defaults values: \ttt{CKIN(1)=2.*CKIN(3)}, \ttt{CKIN(5)=CKIN(6)=0.5*CKIN(3)}. For the same reason it is recommended to include a dampening of proton parton distributions, \ttt{MSTP(57)=2}. \item The VMD processes work as ordinary hadron--hadron ones, i.e. one obtains both low- and high-$\pT$ events by default, with dividing line set by \ttt{PARP(81)} (or \ttt{PARP(82)}, depending on minijet unitarization scheme). \item For the anomalous, finally, the minimal $\pT$ of the $\gamma \to \q\qbar$ branching is set in \ttt{PARP(15)}. The default is 0.5 GeV, in agreement with the recommended cutoff for the same vertex in direct proccesses. In addition, a lower \ttt{CKIN(3)} cut-off should be selected for the hard interactions. This needs some fine-tuning, which in principle should be done separately for each c.m. energy. A good first approximation in the HERA energy range (but not beyond 300 GeV) is \ttt{CKIN(3)}$=1.50 + 0.0035 \, E_{\mrm{cm}}$. \end{Itemize} The processes in points 1 and 2 can be simulated either with a photon beam or with an electron beam. For a photon beam it is necessary to use option \ttt{MSTP(14)} to switch between a point-like and a resolved photon --- it is not possible to simulate the two sets of processes in a single run. An electron by default is assumed to contain photons, but this can be switched off by \ttt{MSTP(11)=0}. To have quark and gluon distributions inside the photon (itself inside the electron), \ttt{MSTP(12)=1} must be used. For the electron, the two kinds of processes may be generated together, unlike for the photon. It is not possible to have also the low-$\pT$ physics (including multiple interactions in high-$\pT$ events) for an electron beam. Kindly note that subprocess 34 contains both the scattering of an electron off a photon and the scattering of a quark (inside a photon inside an electron) off a photon; the former can be switched off with the help of the \ttt{KFIN} array. If you are only concerned with standard QCD physics, the option \ttt{MSTP(14)=10} gives an automatic mixture of the VMD, direct and anomalous event classes. The mixture is properly given according to the relative cross sections. Whenever possible, this option is therefore preferrable in terms of user-friendliness. However, it can only work because of a completely new layer of administration, not found anywhere else in {\Py}. For instance, a subprocess like $\q\g \to \q\g$ is allowed in several of the classes, but appears with different sets of parton distributions and different $\pT$ cut-offs in each of these, so that it is necessary to switch gears between each event in the generation. It is therefore not possible to avoid a number of restrictions on what you can do in this case: \begin{Itemize} \item The \ttt{MSTP(14)=10} option can only be used for incoming photon beams, i.e. when \ttt{'gamma'} is the argument in the \ttt{PYINIT} call. A convolution with the bremsstrahlung photon spectrum in an electron beam may come one day, but not in the immediate future. \item The machinery has only been set up to generate standard QCD physics, specifically either `minimum-bias' one or high-$\pT$ jets. For minimum bias, you are not allowed to use the \ttt{CKIN} variables at all. This is not a major limitation, since it is in the spirit of minimum-bias physics not to impose any contraints on allowed jet production. (If you still do, these cuts will be ineffective for the VMD processes but take effect for the other ones, giving inconsistencies.) The minimum-bias physics option is obtained by default; by switching from \ttt{MSEL=1} to \ttt{MSEL=2} also the elastic and diffractive components of the VMD part are included. High-$\pT$ jet production is obtained by setting the \ttt{CKIN(3)} cut-off larger than each of the (energy-dependent) cut-off scales for the VMD, direct and anomalous components; typically this means at least 3 GeV. For lower input \ttt{CKIN(3)} values the program will automatically switch back to minimum-bias physics. \item Some variables are internally recalculated and reset: \ttt{CKIN(1)}, \ttt{CKIN(3)}, \ttt{CKIN(5)}, \ttt{CKIN(6)}, \ttt{MSTP(57)}, \ttt{MSTP(85)}, \ttt{PARP(2)}, \ttt{PARP(81)}, \ttt{PARP(82)}, \ttt{PARU(115)} and \ttt{MDME(22,J)}. This is because they must have values that depend on the component studied. These variables can therefore not be modified without changing \ttt{PYINPR} and recompiling the program, which obviously is a major exercise. \item Pileup events are not at all allowed. \end{Itemize} Also, a warning about the usage of \tsc{Pdflib} for photons. So long as \ttt{MSTP(14)=1}, i.e. the photon is not split up, \tsc{Pdflib} is accessed by \ttt{MSTP(56)=2} and \ttt{MSTP(55)} as the parton distribution set. However, when the VMD and anomalous pieces are split, the VMD part is based on a rescaling of pion distributions by VMD factors (except for the SaS sets, that already come with a separate VMD piece). Therefore, to access \tsc{Pdflib} for \ttt{MSTP(14)=10}, it is not correct to set \ttt{MSTP(56)=2} and a photon distribution in \ttt{MSTP(55)}. Instead, one should put \ttt{MSTP(56)=2}, \ttt{MSTP(54)=2} and a pion distribution code in \ttt{MSTP(53)}, while \ttt{MSTP(55)} has no function. The anomalous part is still based on the SaS parametrization, with \ttt{PARP(15)} as main free parameter. Currently, hadrons are not defined with any photonic content. None of the processes are therefore relevant in hadron--hadron collisions. In $\e\p$ collisions, the electron can emit an almost real photon, which may interact directly or be resolved. In $\ee$ collisions, one may have direct, singly-resolved or doubly-resolved processes. The $\gamma\gamma$ equivalent to the $\gamma\p$ description involves six different event classes, see section \ref{sss:photoprod}. These classes can be obtained by setting \ttt{MSTP(14)} to 0, 2, 3, 5, 6 and 7, respectively. If one combines the VMD and anomalous parts of the parton distributions of the photon, in a more coarse description, it is enough to use the \ttt{MSTP(14)} options 0, 1 and 4. The cut-off procedures follows from the ones used for the $\gamma\p$ ones above. Thus the direct$\times$direct and direct$\times$VMD processes require the same cut-offs as used for direct $\gamma\p$ events, the VMD$\times$VMD ones the same as used for VMD $\gamma\p$ events, and the rest (anomalous$\times$anomalous, direct$\times$anomalous and VMD$\times$anomalous) the same as used for anomalous $\gamma\p$ events. As with $\gamma\p$ events, the option \ttt{MSTP(14)=10} gives a mixture of the six possible $\gamma\gamma$ event classes. The same complications and restrictions exist here as already listed above. For normal use the advantages should outweight the disadvantages. It is hoped to extend the formalism also to mildly virtual photons. Currently this is not done. The interaction of a highly virtual photon with a real photon is included in the deep inelastic scattering formalism below, however. Process 54 generates a mixture of quark flavours; allowed flavours are set by the gluon \ttt{MDME values}. Process 58 can generate both quark and lepton pairs, according to the \ttt{MDME} values of the photon. Processes 84 and 85 are variants of these matrix elements, with fermion masses included in the matrix elements, but where only one flavour can be generated at a time. This flavour is selected as described for processes 81 and 82 in section \ref{sss:heavflavclass}, with the exception that for process 85 the `heaviest' flavour allowed for photon splitting takes to place of the heaviest flavour allowed for gluon splitting. Since lepton KF codes come after quark ones, they are counted as being `heavier', and thus take precedence if they have been allowed. Process 80 is a higher twist one. The theory for such processes is rather shaky, so results should not be taken too literally. The messy formulae given in \cite{Bag82} have not been programmed in full, instead the pion form factor has been parametrized as $Q^2 F_{\pi}(Q^2) \approx 0.55 / \ln Q^2$, with $Q$ in GeV. \subsubsection{Deep inelastic scattering} \label{sss:DISclass} \ttt{MSEL} = 1, 2, 35, 36, 37, 38 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 10 & $\f_i \f_j \to \f_k \f_l$ \\ 83 & $\q_i \f_j \to \Q_k \f_l$ \\ \end{tabular} The `deep inelastic scattering' (DIS) processes, i.e. $t$-channel electroweak gauge boson exchange, are traditionally associated with interactions between a lepton or neutrino and a hadron, but processes 10 and 83 can equally well be applied for $\q\q$ scattering in hadron colliders (with a cross section much smaller than corresponding QCD processes, however). If applied to incoming $\ee$ beams, process 10 corresponds to Bhabha scattering. For process 10 both $\gamma$, $\Z^0$ and $\W^{\pm}$ exchange contribute, including interference between $\gamma$ and $\Z^0$. The switch \ttt{MSTP(21)} may be used to restrict to only some of these, e.g. neutral or charged current only. The option \ttt{MSTP(14)=10} (see previous section) has now been extended so that it also works for deep inelastic sacattering of an electron off a (real) photon, i.e. process 10. What is obtained is a mixture of the photon acting as a vector meson and it acting as an anomalous state. This should therefore be the sum of what can be obtained with \ttt{MSTP(14)=2} and \ttt{=3}. It is distinct from \ttt{MSTP(14)=1} in that different sets are used for the parton distributions --- in \ttt{MSTP(14)=1} all the contributions to the photon distributions are lumped together, while they are split in VMD and anomalous parts for \ttt{MSTP(14)=10}. Also the beam remnant treatment is different, with a simple Gaussian distribution (at least by default) for \ttt{MSTP(14)=1} and the VMD part of \ttt{MSTP(14)=10}, but a powerlike distribution $\d k_{\perp}^2 / k_{\perp}^2$ between \ttt{PARP(15)} and $Q$ for the anomalous part of \ttt{MSTP(14)=10}. To access this option for $\e$ and $\gamma$ as incoming beams, it is only necessary to set \ttt{MSTP(14)=10} and keep \ttt{MSEL} at its default value. Unlike the corresponding option for $\gamma\p$ and $\gamma\gamma$, no cuts are overwritten, i.e. it is still the responsability of the user to set these appropriately. Cuts especially appropriate for DIS usage include either \ttt{CKIN(21)-CKIN(22)} or \ttt{CKIN(23)-CKIN(24)} for the $x$ range (former or latter depending on which side is the incoming real photon), \ttt{CKIN(35)-CKIN(36)} for the $Q^2$ range, and \ttt{CKIN(39)-CKIN(40)} for the $W^2$ range. In principle, the DIS $x$ variable of an event corresponds to the $x$ value stored in \ttt{PARI(33)} or \ttt{PARI(34)}, depending on which side the incoming hadron is on, while the DIS $Q^2 = -\hat{t} = $\ttt{-PARI(15)}. However, just like initial- and final-state radiation can shift jet momenta, they can modify the momentum of the scattered lepton. Therefore the DIS $x$ and $Q^2$ variables are not automatically conserved. An option, on by default, exists in \ttt{MSTP(23)}, where the event can be `modified back' so as to conserve $x$ and $Q^2$, but this option is still rather primitive and should not be taken too literally. Process 83 is the equivalent of process 10 for $\W^{\pm}$ exchange only, but with the heavy-quark mass included in the matrix element. In hadron colliders it is mainly of interest for the production of very heavy flavours, where the possibility of producing just one heavy quark is kinematically favoured over pair production. The selection of the heavy flavour is already discussed in section \ref{sss:heavflavclass}. \subsubsection{Single $\W/\Z$ production} \label{sss:WZclass} \ttt{MSEL} = 11, 12, 13, 14, 15, (21) \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 1 & $\f_i \fbar_i \to \gammaZ$ \\ 2 & $\f_i \fbar_j \to \W^+$ \\ 15 & $\f_i \fbar_i \to \g (\gammaZ)$ \\ 16 & $\f_i \fbar_j \to \g \W^+$ \\ 19 & $\f_i \fbar_i \to \gamma (\gammaZ)$ \\ 20 & $\f_i \fbar_j \to \gamma \W^+$ \\ 30 & $\f_i \g \to \f_i (\gammaZ)$ \\ 31 & $\f_i \g \to \f_k \W^+$ \\ 35 & $\f_i \gamma \to \f_i (\gammaZ)$ \\ 36 & $\f_i \gamma \to \f_k \W^+$ \\ 131 & $\g \g \to \Z^0 \Q_k \Qbar_k$ \\ (141) & $\f_i \fbar_i \to \gamma/\Z^0/\Z'^0$ \\ \end{tabular} This group consists of $2 \to 1$ processes, i.e. production of a single resonance, and $2 \to 2$ processes, where the resonance is recoiling against a jet or a photon. The process 141, which also is listed here, is described further elsewhere. With initial-state showers turned on, the $2 \to 1$ processes also generate additional jets; in order to avoid double-counting, the corresponding $2 \to 2$ processes should therefore not be turned on simultaneously. The basic rule is to use the $2 \to 1$ processes for inclusive generation of $\W/\Z$, i.e. where the bulk of the events studied have $\pT \ll m_{\W/\Z}$, which is where parton showers may be expected to do a good job. For dedicated studies of $\W/\Z$ production at larger transverse momenta, the parton showers tend to underestimate the event rates. It is here better to start from the $2 \to 2$ matrix elements and add showers to these. However, the $2 \to 2$ matrix elements are divergent for $\pT \to 0$, and should not be used down to the low-$\pT$ region, or one may get unphysical cross sections. The problem of double-counting applies not only to $\W/\Z$ production in hadron colliders, but also to a process like $\ee \to \Z^0 \gamma$, which clearly is part of the initial-state radiation corrections to $\ee \to \Z^0$ obtained for \ttt{MSTP(11)=1}. As is the case for $\Z$ production in association with jets, the $2 \to 2$ process should therefore only be used for the high-$\pT$ region. The $\Z^0$ of subprocess 1 includes the full interference structure $\gammaZ$; via \ttt{MSTP(43)} you can select to produce only $\gamma^*$, only $\Z^0$, or the full $\gammaZ$. The same holds true for the $\Z'^0$ of subprocess 141; via \ttt{MSTP(44)} any combination of $\gamma^*$, $\Z^0$ and $\Z'^0$ can be selected. Thus, subprocess 141 with \ttt{MSTP(44)=4} is essentially equivalent to subprocess 1 with \ttt{MSTP(43)=3}; however, process 141 also includes the possibility of a decay into Higgses. Also processes 15, 19, 30 and 35 contain the full mixture of $\gammaZ$, with \ttt{MSTP(43)} available to change this. Only the $\Z^0$ that appears in process 131 does not contain the $\gamma^*$ contribution. Note that process 1, with only $\q\qbar \to \gamma^* \to \ell^+ \ell^-$ allowed, and studied in the region well below the $\Z^0$ mass, is what is conventionally called Drell--Yan. This latter process therefore does not appear under a separate heading, but can be obtained by a suitable setting of switches and parameters. A process like $\f_i \fbar_j \to \gamma \W^+$ is only included in the limit that the $\gamma$ is emitted in the `initial state', while the possibility of a final-state radiation off the $\W^+$ decay products is not explicitly included (but can be obtained implicitly by the parton-shower machinery) and various interference terms are not at all present. Some caution must therefore be exercised; see also section \ref{sss:WZpairclass} for related comments. For the $2 \to 1$ processes, the Breit--Wigner includes an $\hat{s}$-dependent width, which should provide an improved description of line shapes. In fact, from a line-shape point of view, process 1 should provide a more accurate simulation of $\ee$ annihilation events than the dedicated $\ee$ generation scheme of {\Je} (see section \ref{ss:eematrix}). However, the $\pT$ distribution of radiated initial-state photons is probably still better modelled in the {\Je} routines. Another difference is that {\Je} only allows the generation of $\gammaZ \to \q\qbar$, while process 1 additionally contains $\gammaZ \to \ell^+ \ell^-$ and $\gammaZ \to \nu \br{\nu}$. The parton-shower and fragmentation descriptions are the same, but the {\Py} implementation has not been interfaced with the first- and second-order matrix-element options available in {\Je}. Almost all processes in this group have been included with the correct angular distribution in the subsequent $\W/\Z \to \f \fbar$ decays. The exception is process 36, where currently the $\W$ decays isotropically. The process $\ee \to \e^+ \e^- \Z^0$ can be simulated in two different ways. One is to make use of the $\e$ `sea' distribution inside $\e$, i.e. have splittings $\e \to \gamma \to \e$. This can be obtained, together with ordinary $\Z^0$ production, by using subprocess 1, with \ttt{MSTP(11)=1} and \ttt{MSTP(12)=1}. Then the contribution of the type above is 5.0 pb for a 500 GeV $\ee$ collider, compared with the correct 6.2 pb \cite{Hag91}. Alternatively one may use process 35, with \ttt{MSTP(11)=1} and \ttt{MSTP(12)=0}. To catch the singularity in the forward direction, regularized by the electron mass, it is necessary to set \ttt{CKIN(3)=CKIN(5)=0.01} --- using lower values will only slow down execution, not significantly increasing the cross section. One then obtains 5.1 pb, i.e. again 20\% below the correct value, but now also generates a $\pT$ distribution for the $\Z^0$; this is therefore to be preferred. Process 36, $\f \gamma \to \f' \W^{\pm}$ may have corresponding problems; except that in $\ee$ the forward scattering amplitude for $\e \gamma \to \nu \W$ is killed (radiation zero), which means that the differential cross section is vanishing for $\pT \to 0$. It is therefore feasible to use the default \ttt{CKIN(3)} and \ttt{CKIN(5)} values in $\ee$, and one also comes closer to the correct cross section. One single true $2 \to 3$ process is included in this class as well; namely $\g \g \to \Z^0 \Q \Qbar$, with full massive matrix elements. The more complicated phase space and the lengthy matrix-element evaluations make this process extremely slow. With the quark flavour picked to be $\b$, it may form an important background to intermediate mass Higgs searches in the multilepton channel. The quark flavour is stored in \ttt{KFPR(131,2)}; the default is $5 = \b$. The kinematics is set up in terms of a $\Z^0$ recoiling against the $\Q \Qbar$ system, and all ordinary kinematics cut for a $2 \to 2$ process can be used on this level, including \ttt{CKIN(43)} and \ttt{CKIN(44)} to restrict the range of the $\Q \Qbar$ invariant mass. In addition, for this process alone, \ttt{CKIN(51) - CKIN(54)} can be used to set the $\pT$ range of the two quarks; as is to be expected, that of the $\Z^0$ is set by \ttt{CKIN(3) - CKIN(4)}. Since the optimization procedure is not set up to probe the full multidimensional phase space allowed in this process, maximum violations may be quite large. It may then be useful to make a preliminary run to find how big the violations are in total, and then use the \ttt{MSTP(121)=1} option in the full run. \subsubsection{$\W/\Z$ pair production} \label{sss:WZpairclass} \ttt{MSEL} = 15 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 22 & $\f_i \fbar_i \to (\gammaZ) (\gammaZ)$ \\ 23 & $\f_i \fbar_j \to \Z^0 \W^+$ \\ 25 & $\f_i \fbar_i \to \W^+ \W^-$ \\ 69 & $\gamma \gamma \to \W^+ \W^-$ \\ 70 & $\gamma \W^+ \to \Z^0 \W^+$ \\ \end{tabular} In this section we mainly consider the production of $\W/\Z$ pairs by fermion--antifermion annihilation, but also include two processes which involve $\gamma/\W$ beams. Scatterings between gauge-boson pairs, i.e. processes like $\W^+ \W^- \to \Z^0 \Z^0$, depend so crucially on the assumed Higgs scenario that they are considered separately in section \ref{sss:heavySMHclass}. The cross sections used for the above processes are those derived in the narrow-width limit, but have been extended to include Breit--Wigner shapes with mass-dependent widths. However, one should realize that other graphs, not included here, can contribute in regions away from the $\W/\Z$ mass. This problem is especially important if several flavours coincide in the four-fermion final state. Consider, as an example, $\ee \to \mu^+ \mu^- \nu_{\mu} \br{\nu}_{\mu}$. Not only would such a final state receive contributions from intermediate $\Z^0\Z^0$ and $\W^+\W^-$ states, but also from processes $\ee \to \Z^0 \to \mu^+ \mu^-$, followed either by $\mu^+ \to \mu^+ \Z^0 \to \mu^+ \nu_{\mu} \br{\nu}_{\mu}$, or by $\mu^+ \to \br{\nu}_{\mu} \W^+ \to \br{\nu}_{\mu} \mu^+ \nu_{\mu}$. In addition, all possible interferences should be considered. Since this is not done, the processes have to be used with some sound judgement. Very often, one may wish to constrain a lepton pair mass to be close to $m_{\Z}$, in which case a number of the possible `other' processes are negligible. Of the above processes, the first contains the full $\f_i \fbar_i \to (\gammaZ)(\gammaZ)$ structure, obtained by a straightforward generalization of the formulae in ref. \cite{Gun86} (done by the present author). Of course, the possibility of there being significant contributions from graphs that are not included is increased, in particular if one $\gamma^*$ is very light and therefore could be a bremsstrahlung-type photon. It is possible to use \ttt{MSTP(43)} to recover the pure $\Z^0$ case, i.e. $\f_i \fbar_i \to \Z^0 \Z^0$ exclusively. In processes 23 and 70, only the pure $\Z^0$ contribution is included. Full angular correlations are included for the first three processes, i.e. the full $2 \to 2 \to 4$ matrix elements are included in the resonance decays, including the appropriate $\gammaZ$ interference in process 22. In the latter two processes no spin information is currently preserved, i.e. the $\W/\Z$ bosons are allowed to decay isotropically. We remind you that the mass ranges of the two resonances may be set with the \ttt{CKIN(41) - CKIN(44)} parameters; this is particularly convenient, for instance, to pick one resonance almost on the mass shell and the other not. \subsection{Higgs Production} A fair fraction of all the processes in {\Py} deal with Higgs production in one form or another. This multiplication is caused by the need to consider production by several different processes, depending on Higgs mass and machine type. Further, the program contains a full two-Higgs-multiplet scenario, as predicted for example in the Minimal Supersymmetric extension of the Standard Model (MSSM). Therefore the continued discussion is, somewhat arbitrarily, subdivided into a few different scenarios. \subsubsection{Light Standard Model Higgs} \label{sss:lightSMHclass} \ttt{MSEL} = 16, 17, 18 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 3 & $\f_i \fbar_i \to \H^0$ \\ 24 & $\f_i \fbar_i \to \Z^0 \H^0$ \\ 26 & $\f_i \fbar_j \to \W^+ \H^0$ \\ 102 & $\g \g \to \H^0$ \\ 103 & $\gamma \gamma \to \H^0$ \\ 110 & $\f_i \fbar_i \to \gamma \H^0$ \\ 111 & $\f_i \fbar_i \to \g \H^0$ \\ 112 & $\f_i \g \to \f_i \H^0$ \\ 113 & $\g \g \to \g \H^0$ \\ 121 & $\g \g \to \Q_k \Qbar_k \H^0$ \\ 122 & $\q_i \qbar_i \to \Q_k \Qbar_k \H^0$ \\ 123 & $\f_i \f_j \to \f_i \f_j \H^0$ ($\Z^0 \Z^0$ fusion) \\ 124 & $\f_i \f_j \to \f_k \f_l \H^0$ ($\W^+ \W^-$ fusion) \\ \end{tabular} In this section we discuss the production of a reasonably light Standard Model Higgs, below 700 GeV, say, so that the narrow width approximation can be used with some confidence. Below 400 GeV there would certainly be no trouble, while above that the narrow width approximation is gradually starting to break down. In a hadron collider, the main production processes are 102, 123 and 124, i.e. $\g\g$, $\Z^0 \Z^0$ and $\W^+ \W^-$ fusion. In the latter two processes, it is also necessary to take into account the emission of the space-like $\W/\Z$ bosons off quarks, which in total gives the $2 \to 3$ processes above. Further processes of lower cross sections may be of interest because of easier signals. For instance, processes 24 and 26 give associated production of a $\Z$ or a $\W$ together with the $\H^0$. There is also the processes 3, 121 and 122, which involve production of heavy flavours. Process 3 contains contributions from all flavours, but is completely dominated by the subprocess $\t \tbar \to \H^0$, i.e. by the contribution from the top sea distributions. This process is by now known to overestimate the cross section for Higgs production as compared with a more careful calculation based on the subprocess $\g \g \to \t \tbar \H^0$ (121). The difference between the two is that in process 3 the $\t$ and $\tbar$ are added by the initial-state shower, while in 121 the full matrix element is used. The price to be paid is that the complicated multibody phase space in process 121 makes the program run slower than with most other processes. One should therefore think twice before using it. As usual, it would be double-counting to include both 3 and 121. Process 122 is similar in structure to 121, but is less important. In both process 121 and 122 the produced quark is assumed to be a $\t$; this can be changed in \ttt{KFPR(121,2)} and \ttt{KFPR(122,2)} before initialization, however. A subprocess like 113, with a Higgs recoiling against a gluon jet, is also effectively generated by initial-state corrections to subprocess 102; thus, in order to avoid double-counting, just as for the case of $\Z^0/\W^+$ production, section \ref{sss:WZclass}, these subprocesses should not be switched on simultaneously. Process 102 should be used for inclusive production of Higgs, and 111--113 for the study of the Higgs subsample with high transverse momentum. In $\ee$ annihilation, associated production of an $\H^0$ with a $\Z^0$, process 24, is usually the dominant one close to threshold, while the $\Z^0 \Z^0$ and $\W^+ \W^-$ fusion processes 123 and 124 win out at high energies. Process 103, $\gamma\gamma$ fusion, may also be of interest, in particular when the possibilities of beamstrahlung photons and backscattered photons are included. Process 110, which gives an $\H^0$ in association with a $\gamma$, is a loop process and is therefore suppressed in rate. Only for a rather massive $\H^0$ (mass above 60 GeV at LEP 1) can it start to compete with the associated production of a $\Z^0$, since phase space suppression is less severe for the former than for the latter. The branching ratios of the Higgs are very strongly dependent on the mass. In principle, the program is set up to calculate these correctly, as a function of the actual Higgs mass, i.e. not just at the nominal mass. However, higher-order corrections may at times be important and not fully unambiguous; see for instance \ttt{MSTP(37)}. Since the Higgs is a spin-0 particle it decays isotropically. In decay processes such as $\H^0 \to \W^+ \W^- \to 4$ fermions angular correlations are included. Also in processes 24 and 26, $\Z^0$ and $\W^{\pm}$ decay angular distributions are correctly taken into account. \subsubsection{Heavy Standard Model Higgs} \label{sss:heavySMHclass} ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 5 & $\Z^0 \Z^0 \to \H^0$ \\ 8 & $\W^+ \W^- \to \H^0$ \\ 71 & $\Z^0 \Z^0 \to \Z^0 \Z^0$ (longitudinal) \\ 72 & $\Z^0 \Z^0 \to \W^+ \W^-$ (longitudinal) \\ 73 & $\Z^0 \W^+ \to \Z^0 \W^+$ (longitudinal) \\ 76 & $\W^+ \W^- \to \Z^0 \Z^0$ (longitudinal) \\ 77 & $\W^+ \W^{\pm} \to \W^+ \W^{\pm}$ (longitudinal) \\ \end{tabular} Processes 5 and 8 are the simple $2 \to 1$ versions of what is now available in 123 and 124 with the full $2 \to 3$ kinematics. For low Higgs masses processes 5 and 8 overestimate the correct cross sections and should not be used, whereas good agreement between the $2 \to 1$ and $2 \to 3$ descriptions is observed when heavy Higgs production is studied. The subprocesses 5 and 8, $V V \to \H^0$, which contribute to the processes $V V \to V' V'$, show a bad high-energy behaviour. Here $V$ denotes a longitudinal intermediate gauge boson, $\Z^0$ or $\W^{\pm}$. This can be cured only by the inclusion of all $V V \to V' V'$ graphs, as is done in subprocesses 71, 72, 73, 76 and 77. In particular, subprocesses 5 and 8 give rise to a fictitious high-mass tail of the Higgs. If this tail is thrown away, however, the agreement between the $s$-channel graphs only (subprocesses 5 and 8) and the full set of graphs (subprocesses 71 etc.) is very good: for a Higgs of nominal mass 300 (800) GeV, a cut at 600 (1200) GeV retains 95\% (84\%) of the total cross section, and differs from the exact calculation, cut at the same values, by only 2\% (11\%) (numbers for SSC energies). With this prescription there is therefore no need to use subprocesses 71 etc. rather than subprocesses 5 and 8. For subprocess 77, there is an option, see \ttt{MSTP(45)}, to select the charge combination of the scattering $\W$'s: like-sign, opposite-sign (relevant for Higgs), or both. Process 77 contains a divergence for $\pT \to 0$ due to $\gamma$-exchange contributions. This leads to an infinite total cross section, which is entirely fictitious, since the simple parton-distribution function approach to the longitudinal $\W$ flux is not appropriate in this limit. For this process, it is therefore necessary to make use of a cut, e.g. $\pT > m_{\W}$. For subprocesses 71, 72, 76 and 77, an option is included (see \ttt{MSTP(46)}) whereby the user can select only the $s$-channel Higgs graph; this will then be essentially equivalent to running subprocess 5 or 8 with the proper decay channels (i.e. $\Z^0\Z^0$ or $\W^+\W^-$) set via \ttt{MDME}. The difference is that the Breit--Wigners in subprocesses 5 and 8 contain a mass-dependent width, whereas the width in subprocesses 71--77 is calculated at the nominal Higgs mass; also, higher-order corrections to the widths are treated more accurately in subprocesses 5 and 8. Further, processes 71--77 assume the incoming $\W/\Z$ to be on the mass shell, with associated kinematics factors, while processes 5 and 8 have $\W/\Z$ correctly space-like. All this leads to differences in the cross sections by up to a factor of 1.5. In the absence of a Higgs, the sector of longitudinal $\Z$ and $\W$ scattering will become strongly interacting at energies above 1 TeV. The models proposed by Dobado, Herrero and Terron \cite{Dob91} to describe this kind of physics have been included as alternative matrix elements for subprocesses 71, 72, 73, 76 and 77, selectable by \ttt{MSTP(46)}. From the point of view of the general classification scheme for subprocesses, this kind of models should appropriately be included as separate subprocesses with numbers above 100, but the current solution allows a more efficient reuse of existing code. By a proper choice of parameters, it is also here possible to simulate the production of a techni-$\rho$. Currently, the scattering of transverse gauge bosons has not been included, neither that of mixed transverse--longitudinal scatterings. These are expected to be less important at high energies, and do not contain an $\H^0$ resonance peak, but need not be entirely negligible in magnitude. As a rule of thumb, processes 71--77 should not be used for $VV$ invariant masses below 500 GeV. The decay products of the longitudinal gauge bosons are correctly distributed in angle. \subsubsection{Extended neutral Higgs sector} \label{sss:extneutHclass} \ttt{MSEL} = 19 \\ ISUB = \\ \begin{tabular}{rrrl@{\protect\rule{0mm}{\tablinsep}}} $\H^0$ & $\H'^0$ & $\A^0$ & \\ 3 & 151 & 156 & $\f_i \fbar_i \to X$ \\ 102 & 152 & 157 & $\g \g \to X$ \\ 103 & 153 & 158 & $\gamma \gamma \to X$ \\ 24 & 171 & 176 & $\f_i \fbar_i \to \Z^0 X$ \\ 26 & 172 & 177 & $\f_i \fbar_j \to \W^+ X$ \\ 123 & 173 & 178 & $\f_i \f_j \to \f_i \f_j X$ ($\Z \Z$ fusion) \\ 124 & 174 & 179 & $\f_i \f_j \to \f_k \f_l X$ ($\W^+\W^-$ fusion) \\ 121 & 181 & 186 & $\g \g \to \Q_k \Qbar_k X$ \\ 122 & 182 & 187 & $\q_i \qbar_i \to \Q_k \Qbar_k X$ \\ \end{tabular} \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} (141) & $\f_i \fbar_i \to \gamma/\Z^0/\Z'^0$ \\ \end{tabular} In {\Py}, the particle content of a two-Higgs-doublet scenario is included: two neutral scalar particles, 25 and 35, one pseudoscalar one, 36, and a charged doublet, $\pm 37$. (Of course, these particles may also be associated with corresponding Higgs states in larger multiplets.) By convention, we choose to call the lighter scalar Higgs $\H^0$ and the heavier $\H'^0$ --- this differs from the convention in the MSSM, where the lighter is called $\hrm^0$ and the heavier $\H^0$, but allows us to call the Higgs of the one-Higgs scenario $\H^0$. The pseudoscalar is called $\A^0$ and the charged $\H^{\pm}$. Charged-Higgs production is covered in section \ref{sss:chHclass}. A number of $\H^0$ processes have been duplicated for $\H'^0$ and $\A^0$. The correspondence between ISUB numbers is shown in the table above: the first column of ISUB numbers corresponds to $X = \H^0$, the second to $X = \H'^0$, and the third to $X = \A^0$. Note that several of these processes are not expected to take place at all, owing to vanishing Born term couplings. We have still included them for flexibility in simulating arbitrary couplings at the Born or loop level. A few Standard Model Higgs processes have no correspondence in the scheme above. These include \begin{Itemize} \item 5 and 8, which anyway have been superseded by 123 and 124; \item 71, 72, 73, 76 and 77, which deal with what happens if there is no light Higgs, and so is a scenario complementary to the one above, where several light Higgses are assumed; \item 110, which is mainly of interest in Standard Model Higgs searches; and \item 111, 112 and 113, which describe the high-$\pT$ tail of the Higgs production, and are less interesting for most Higgs studies. \end{Itemize} In processes 121, 122, 181, 182, 186 and 187 the recoiling heavy flavour is assumed to be top, which is the only one of interest in the Standard Model, and the one where the parton-distribution-function approach invoked in processes 3, 151 and 156 is least reliable. However, it is possible to change the quark flavour in 121 etc.; for each process ISUB this flavour is given by \ttt{KFPR(ISUB,2)}. This may become relevant if couplings to $\b\bbar$ states are enhanced, e.g. if $\tan\beta \gg 1$ in the MSSM. By default, the $\H^0$ has the couplings of the Standard Model Higgs, while the $\H'^0$ and $\A^0$ have couplings set in \ttt{PARU(171) - PARU(178)} and \ttt{PARU(181) - PARU(190)}, respectively. The default values for the $\H'^0$ and $\A^0$ have no deep physics motivation, but are set just so that the program will not crash due to the absence of any couplings whatsoever. You should therefore set the above couplings to your desired values if you want to simulate either $\H'^0$ or $\A^0$. Also the couplings of the $\H^0$ particle can be modified, in \ttt{PARU(161) - PARU(165)}, provided that \ttt{MSTP(4)} is set to 1. For \ttt{MSTP(4)=2}, the mass of the $\H^0$ (in \ttt{PMAS(25,1)}) and the $\tan\beta$ value (in \ttt{PARU(141)}) are used to derive the masses of the other Higgses, as well as all Higgs couplings. \ttt{PMAS(35,1) - PMAS(37,1)} and \ttt{PARU(161) - PARU(195)} are overwritten accordingly. The relations used are the ones of the Born-level MSSM \cite{Gun90}. Today, loop corrections to those expressions have been calculated, and are known to have non-negligible effects on the resulting phenomenology. Eventually the modified relations will be included as an additional option, but this has not yet been done. Note that not all combinations of $m_{\H}$ and $\tan\beta$ are allowed; the requirement of a finite $\A^0$ mass imposes the constraint \begin{equation} m_{\H} < m_{\Z} \, \frac{\tan^2\beta - 1}{\tan^2\beta + 1}, \end{equation} or, equivalently, \begin{equation} \tan^2\beta > \frac{m_{\Z} + m_{\H}}{m_{\Z} - m_{\H}}. \end{equation} If this condition is not fulfilled, the program will crash. Process 141 can also be used to simulate $\Z^0 \to \H^0 \A^0$ and $\Z^0 \to \H'^0 \A^0$ for associated neutral Higgs production. The fact that we here make use of the $\Z'^0$ can easily be discounted, either by letting the relevant couplings vanish, or by the option \ttt{MSTP(44)=4}. Finally, heavier Higgses may decay into lighter ones, if kinematically allowed, in processes like $\A^0 \to \Z^0 \H^0$ or $\H^+ \to \W^+ \H^0$. Such modes are included as part of the general mixture of decay channels, but they can be enhanced if the uninteresting channels are switched off. \subsubsection{Charged Higgs sector} \label{sss:chHclass} \ttt{MSEL} = 23 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 143 & $\f_i \fbar_j \to \H^+$ \\ 161 & $\f_i \g \to \f_k \H^+$ \\ (141) & $\f_i \fbar_i \to \gamma/\Z^0/\Z'^0$ \\ \end{tabular} A charged Higgs doublet, $\H^{\pm}$, is included in the program. This doublet may be the one predicted in the MSSM scenario, see section \ref{sss:extneutHclass}, or in any other scenario. The $\tan\beta$ parameter, which is relevant also for charged Higgs couplings, is set via \ttt{PARU(141)}. The basic subprocess for charged Higgs production in hadron colliders is ISUB = 143. However, this process is dominated by $\t \bbar \to \H^+$, and so depends on the choice of $\t$ parton distribution. A better representation is provided by subprocess 161, $\f \g \to \f' \H^+$; i.e. actually $\bbar \g \to \tbar \H^+$. It is therefore recommended to use 161 and not 143; to use both would be double-counting. In subprocess 141, the decay $\gamma^*/\Z^0/\Z'^0 \to \H^+ \H^-$ allows the production of a pair of charged Higgs particles. This process is especially important in $\ee$ colliders. The coupling of the $\gamma^*$ to $\H^+ \H^-$ is determined by the charge alone, while the $\Z^0$ coupling is regulated by \ttt{PARU(142)}, and that of the $\Z'^0$ by \ttt{PARU(143)}. The $\Z'^0$ piece can be switched off, e.g. by \ttt{MSTP(44)=4}. An ordinary $\Z^0$, i.e. particle code 23, cannot be made to decay into $\H^+ \H^-$, however. A major potential source of charged Higgs production is top decay. When the top is treated as a resonance (the default option), it is possible to switch on the decay channel $\t \to \b \H^+$. Top will then decay to $\H^+$ a fraction of the time, whichever way it is produced. The branching ratio is automatically calculated, based on the $\tan\beta$ value and masses. It is possible to only have the $\H^+$ decay mode switched on, in which case the cross section is reduced accordingly. If one instead assumes that top hadrons are formed, branching ratios are not automatically calculated. However, you can set, for the generic top hadron 86, the branching ratios for the two main channels $\t \to \b \H^+$ and $\t \to \b \W^+$. In this option the cross section for top production will not be reduced if only the $\t \to \b \H^+$ decay is switched on, cf. section \ref{sss:resdecaycross}. \subsection{Non-Standard Physics} The number of possible non-Standard Model scenarios is essentially infinite, but many of the studied scenarios still share a lot of aspects. For instance, new $\W'$ and $\Z'$ gauge bosons can arise in a number of different ways. Therefore it still makes sense to try to cover a few basic classes of particles, with enough freedom in couplings that many kinds of detailed scenarios can be accommodated by suitable parameter choices. We have already seen one example of this, in the extended Higgs sector above. In this section a few other kinds of non-standard generic physics is discussed. Clearly many others could have been included, but there is probably only one glaring omission: currently no supersymmetric particle production has been included. One main reason for this is the large number of particles, processes, possible mass hierarchies and decay chains. \subsubsection{Fourth-generation fermions} \ttt{MSEL} = 7, 8, 37, 38 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 1 & $\f_i \fbar_i \to \gammaZ$ \\ 2 & $\f_i \fbar_j \to \W^+$ \\ 81 & $\q_i \qbar_i \to \Q_k \Qbar_k$ \\ 82 & $\g \g \to \Q_k \Qbar_k$ \\ 83 & $\q_i \f_j \to \Q_k \f_l$ \\ 84 & $\g \gamma \to \Q_k \Qbar_k$ \\ 85 & $\gamma \gamma \to \F_k \Fbar_k$ \\ 141 & $\f_i \fbar_i \to \gamma/\Z^0/\Z'^0$ \\ 142 & $\f_i \fbar_j \to \W'^+$ \\ \end{tabular} The prospects of a fourth generation currently seem rather dim, but the appropriate flavour content is still found in the program. In fact, the fourth generation is included on an equal basis with the first three, provided \ttt{MSTP(1)=4}. Also processes other than the ones above can therefore be used, e.g. all other processes with gauge bosons, including non-standard ones such as the $\Z'^0$. We therefore do not repeat the descriptions found elsewhere, e.g. how to set only the desired flavour in processes 81--85. Note that it may be convenient to set \ttt{CKIN(1)} and other cuts such that the mass of produced gauge bosons is enough for the wanted particle production --- in principle the program will cope even without that, but possibly at the expense of very slow execution. \subsubsection{New gauge bosons} \ttt{MSEL} = 21, 22, 24 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 141 & $\f_i \fbar_i \to \gamma/\Z^0/\Z'^0$ \\ 142 & $\f_i \fbar_j \to \W'^+$ \\ 144 & $\f_i \fbar_j \to \R$ \\ \end{tabular} The $\Z'^0$ of subprocess 141 contains the full $\gamma^*/\Z^0/\Z'^0$ interference structure for couplings to fermion pairs. With \ttt{MSTP(44)} it is possible to pick only a subset, e.g. only the pure $\Z'^0$ piece. The couplings of the $\Z'^0$ to quarks and leptons can be set via \ttt{PARU(121) - PARU(128)}. The eight numbers correspond to the vector and axial couplings of down-type quarks, up-type quarks, leptons and neutrinos, respectively. The default corresponds to the same couplings as that of the Standard Model $\Z^0$, with axial couplings $a_{\f} = \pm 1$ and vector couplings $v_{\f} = a_{\f} - 4 e_{\f} \ssintw$. This implies a resonance width that increases linearly with the mass. By a suitable choice of the parameters, it is possible to simulate just about any imaginable $\Z'^0$ scenario, with full interference effects in cross sections and decay angular distributions. The coupling to the decay channel $\Z'^0 \to \W^+ \W^-$ is regulated by \ttt{PARU(129) - PARU(130)}. The former gives the strength of the coupling, which determines the rate. The default, \ttt{PARU(129)=1.}, corresponds to the `extended gauge model' of \cite{Alt89}, wherein the $\Z^0 \to \W^+ \W^-$ coupling is used, scaled down by a factor $m_{\W}^2/m_{\Z'}^2$, to give a $\Z'^0$ partial width into this channel that again increases linearly. If this factor is cancelled, by having \ttt{PARU(129)} proportional to $m_{\Z'}^2/m_{\W}^2$, one obtains a partial width that goes like the fifth power of the $\Z'^0$ mass, the `reference model' of \cite{Alt89}. In the decay angular distribution one could imagine a much richer structure than is given by the one parameter \ttt{PARU(130)}. Other decay modes include $\Z'^0 \to \Z^0 \H^0$, predicted in left--right symmetric models (see \ttt{PARU(145)} and ref. \cite{Coc91}), and a number of other Higgs decay channels, see sections \ref{sss:extneutHclass} and \ref{sss:chHclass}. The $\W'^{\pm}$ of subprocess 142 so far does not contain interference with the Standard Model $\W^{\pm}$ --- in practice this should not be a major limitation. The couplings of the $\W'$ to quarks and leptons are set via \ttt{PARU(131) - PARU(134)}. Again one may set vector and axial couplings freely, separately for the $\q \qbar'$ and the $\ell \nu_{\ell}$ decay channels. The defaults correspond to the $V-A$ structure of the Standard Model $\W$, but can be changed to simulate a wide selection of models. One possible limitation is that the same Cabibbo--Kobayashi--Maskawa quark mixing matrix is assumed as for the standard $\W$. The coupling $\W' \to \Z^0 \W$ can be set via \ttt{PARU(135) - PARU(136)}. Further comments on this channel as for $\Z'$; in particular, default couplings again agree with the `extended gauge model' of \cite{Alt89}. A $\W' \to \W \H^0$ channel is also included, in analogy with the $\Z'^0 \to \Z^0 \H^0$ one, see \ttt{PARU(146)}. The $\R$ boson (particle code 40) of subprocess 144 represents one possible scenario for a horizontal gauge boson, i.e. a gauge boson that couples between the generations, inducing processes like $\s \dbar \to \R^0 \to \mu^- \e^+$. Experimental limits on flavour-changing neutral currents forces such a boson to be fairly heavy. The model implemented is the one described in \cite{Ben85a}. \subsubsection{Leptoquarks} \label{sss:LQclass} \ttt{MSEL} = 25 \\ ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 145 & $\q_i \ell_j \to \L_{\Q}$ \\ 162 & $\q \g \to \ell \L_{\Q}$ \\ 163 & $\g \g \to \L_{\Q} \br{\L}_{\Q}$ \\ 164 & $\q_i \qbar_i \to \L_{\Q} \br{\L}_{\Q}$ \\ \end{tabular} Several processes that can generate a leptoquark have been included. Currently only one leptoquark has been implemented, as particle 39, denoted $\L_{\Q}$. The leptoquark is assumed to carry specific quark and lepton quantum numbers, by default $\u$ quark plus electron. These flavour numbers are conserved, i.e. a process such as $\u \e^- \to \L_{\Q} \to \d \nu_{\e}$ is not allowed. This may be a bit restrictive, but it represents one of many leptoquark possibilities. The spin of the leptoquark is assumed to be zero, i.e. its decay is isotropical. Although only one leptoquark is implemented, its flavours may be changed arbitrarily to study the different possibilities. The flavours of the leptoquark are defined by the quark and lepton flavours in the decay mode list. Since only one decay channel is allowed, this means that the quark flavour is stored in \ttt{KFDP(MDCY(39,2),1)} and the lepton one in \ttt{KFDP(MDCY(39,2),2)}. The former must always be a quark, while the latter could be a lepton or an antilepton; a charge-conjugate partner is automatically defined by the program. At initialization, the charge is recalculated as a function of the flavours defined; also the leptoquark name is redefined to be of the type \ttt{'LQ\_(q)(l)'}, where actual quark \ttt{(q)} and lepton \ttt{(l)} flavours are displayed. The $\L_{\Q} \to \q \ell$ vertex contains an undetermined Yukawa coupling strength, which affects both the width of the leptoquark and the cross section for many of the production graphs. This strength may be changed in \ttt{PARU(151)}. The definition of \ttt{PARU(151)} corresponds to the $k$ factor of \cite{Hew88}, i.e. to $\lambda^2/(4\pi\alphaem)$, where $\lambda$ is the Yukawa coupling strength of \cite{Wud86}. Note that \ttt{PARU(151)} is thus quadratic in the coupling. The leptoquark is likely to be fairly long-lived, in which case it has time to fragment into a mesonic- or baryonic-type state, which would decay later on. This is a bit tedious to handle; therefore the leptoquark is always assumed to decay before fragmentation has to be considered. This may give some imperfections in the event generation, but should not be off by much in the final analysis. Inside the program, the leptoquark is treated as a resonance. Since it carries colour, some extra care is required. In particular, it is not allowed to put the leptoquark stable, by modifying either \ttt{MDCY(39,1)} or \ttt{MSTP(41)}: then the leptoquark would be handed undecayed to {\Je}, which would try to fragment it (as it does with any other coloured object), and most likely crash. \subsubsection{Compositeness and anomalous couplings} \label{sss:ancoupclass} ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 11 & $\f_i \f_j \to \f_i \f_j$ (QCD) \\ 12 & $\f_i \fbar_i \to \f_k \fbar_k$ \\ 20 & $\f_i \fbar_j \to \gamma \W^+$ \\ 165 & $\f_i \fbar_i \to \f_k \fbar_k$ (via $\gammaZ$) \\ 166 & $\f_i \fbar_j \to \f_k \fbar_l$ (via $\W^{\pm}$) \\ \end{tabular} Some processes have been set up to allow anomalous coupling to be introduced, in addition to the Standard Model ones. These can be switched on by \ttt{MSTP(5)}$\geq 1$; the default \ttt{MSTP(5)=0} corresponds to the Standard Model behaviour. In processes 11 and 12, the quark substructure is included in the left--left isoscalar model \cite{Eic84,Chi90} for \ttt{MSTP(5)=1}, with compositeness scale $\Lambda$ given in \ttt{PARU(155)} (default 1000~GeV) and sign $\eta$ of interference term in \ttt{PARU(156)} (default $+1$; only other alternative $-1$). The above model assumes that only $\u$ and $\d$ quarks are composite (at least at the scale studied); with \ttt{MSTP(5)=2} compositeness terms are included in the interactions between all quarks. The processes 165 and 166 are basically equivalent to 1 and 2, i.e. $\gammaZ$ and $\W^{\pm}$ exchange, respectively, but a bit less fancy (no mass-dependent width etc.). The reason for this duplication is that the resonance treatment formalism of processes 1 and 2 could not easily be extended to include other than $s$-channel graphs. In processes 165 and 166, only one final-state flavour is generated at the time; this flavour should be set in \ttt{KFPR(165,1)} and \ttt{KFPR(166,1)}, respectively. For process 166 one gives the down-type flavour, and the program will associate the up-type flavour of the same generation. Defaults are 11 in both cases, i.e. $\ee$ and $\e^+ \nu_{\e}$ ($\e^- \br{\nu}_{\e}$) final states. While \ttt{MSTP(5)=0} gives the Standard Model results, \ttt{MSTP(5)=1} contains the left--left isoscalar model (which does not affect process 166), and \ttt{MSTP(5)=3} the helicity-non-conserving model (which affects both) \cite{Eic84,Lan91}. Both models above assume that only $\u$ and $\d$ quarks are composite; with \ttt{MSTP(5)=} 2 or 4, respectively, contact terms are included for all quarks in the initial state. Parameters are \ttt{PARU(155)} and \ttt{PARU(156)}, as above. Note that processes 165 and 166 are bookkept as $2 \to 2$ processes, while 1 and 2 are $2 \to 1$ ones. This means that the default $\Q^2$ scale in parton distributions is $\pT^2$ for the former and $\hat{s}$ for the latter. To make contact between the two, it is recommended to set \ttt{MSTP(32)=4}, so as to use $\hat{s}$ as scale also for processes 165 and 166. In process 20, for $\W \gamma$ pair production, it is possible to set an anomalous magnetic moment for the $\W$ in \ttt{PARU(153)} ($= \eta = \kappa-1$; where $\kappa = 1$ is the Standard Model value). The production process is affected according to the formulae of \cite{Sam91}, while $\W$ decay currently remains unaffected. It is necessary to set \ttt{MSTP(5)=1} to enable this extension. \subsubsection{Excited fermions} \label{sss:qlstarclass} ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 147 & $\d \g \to \d^*$ \\ 148 & $\u \g \to \u^*$ \\ 167 & $\q \q' \to \q'' \d^*$ \\ 168 & $\q \q' \to \q'' \u^*$ \\ \end{tabular} Compositeness scenarios may also give rise to sharp resonances of excited quarks and leptons. If \ttt{MSTP(6)=1}, then at initialization the standard fourth generation of fermions will be overwritten, and made to correspond to an excited copy of the first generation, consisting of spin $1/2$ particles $\d^*$ (code 7), $\u^*$ (8), $\e^*$ (17) and $\nu^*_{\e}$ (18). Since the original fourth-generation information is lost, it is then not possible to generate fourth-generation particles in the same run. The current implementation contains gauge interaction production by quark--gluon fusion (processes 147 and 148) and contact interaction production by quark--quark or quark--antiquark scattering (processes 167 and 168) . The couplings $f$, $f'$ and $f_s$ to the {\bf SU(2)}, {\bf U(1)} and {\bf SU(3)} groups are stored in \ttt{PARU(157) - PARU(159)}, the scale parameter $\Lambda$ in \ttt{PARU(155)}; you are also expected to change the $\f^*$ masses in accordance with what is desired --- see \cite{Bau90} for details on conventions. Decay processes are of the types $\q^* \to \q \g$, $\q^* \to \q \gamma$, $\q^* \to \q \Z^0$ or $\q^* \to \q' \W^{\pm}$. A non-trivial angular dependence is included in the $\q^*$ decay for processes 147 and 148, but has not been included for processes 167 and 168. \subsubsection{Technicolor} \label{sss:technicolorclass} ISUB = \\ \begin{tabular}{rl@{\protect\rule{0mm}{\tablinsep}}} 149 & $\g \g \to \eta_{\mrm{techni}}$ \\ \end{tabular} The technicolor scenario offers an alternative to the ordinary Higgs mechanism for giving masses to the $\W$ and $\Z$. The technicolor gauge group is an analogue of QCD, with a rich spectrum of technimesons made out of techniquarks. Three of the technipions assume the role of the longitudinal components of the $\W$ and $\Z$ bosons, but many other states remain as separate particles. No fully realistic model has been found so far, however, so any phenomenology has to be taken as indicative only. In section \ref{sss:heavySMHclass} it is discussed how processes 71--77, in some of its options, can be used to simulate a scenario with techni-$\rho$ resonances in longitudinal gauge boson scattering. Here we present another process, that of the production of a techni-$\eta$. This particle has zero spin, is a singlet under electroweak {\bf SU(2)}$\times${\bf U(1)}, but carries octet colour charge. It is one of the possible techni-$\pi$ particles; the name techni-$\eta$ is part of a subclassification not used by all authors. The techni-$\eta$ couples to ordinary fermions according to the fermion squared mass. The dominant decay mode is therefore $\t \tbar$, if allowed. The coupling to a $\g \g$ state is roughly comparable with that to $\b \bbar$. Production at hadron colliders is therefore predominantly through $\g \g$ fusion, as implemented in process 149. The two main free parameters are the techni-$\eta$ mass and the decay constant $F_{\pi}$. The latter appears inversely quadratically in all the partial widths. Also the total cross section is affected, since the cross section is proportional to the $\g \g$ partial width. $F_{\pi}$ is stored in \ttt{PARP(46)} and has the default value 123 GeV, which is the number predicted in some models. \subsection{Main Processes by Machine} In the previous section we have already commented on which processes have limited validity, or have different meanings (according to conventional terminology) in different contexts. Let us just repeat a few of the main points to be remembered for different machines. \subsubsection{$\ee$ collisions} The main annihilation process is number 1, $\ee \to \Z^0$, where in fact the full $\gamma^*/\Z^0$ interference structure is included. This process can be used, with some confidence, for c.m. energies from about 4 GeV upwards, i.e. at DORIS/CESR, PETRA/PEP, TRISTAN, LEP, and any future linear colliders. (To get below 10 GeV, you have to change \ttt{PARP(2)}, however.) This is the default process obtained when \ttt{MSEL=1}, i.e. when you do not change anything yourself. Process 141 contains a $\Z'^0$, including full interference with the standard $\gammaZ$. With the value \ttt{MSTP(44)=4} in fact one is back at the standard $\gammaZ$ structure, i.e. the $\Z'^0$ piece has been switched off. Even so, this process may be useful, since it can simulate e.g. $\ee \to \H^0 \A^0$. Since the $\H^0$ may in its turn decay to $\Z^0 \Z^0$, a decay channel of the ordinary $\Z^0$ to $\H^0 \A^0$, although physically correct, would be technically confusing. In particular, it would be messy to set the original $\Z^0$ to decay one way and the subsequent ones another. So, in this sense, the $\Z'^0$ could be used as a copy of the ordinary $\Z^0$, but with a distinguishable label. The process $\ee \to \Upsilon$ does not exist as a separate process in {\Py}, but can be simulated by using \ttt{LUONIA}, see section \ref{ss:oniadecays}. At LEP 2 and even higher energy machines, the simple $s$-channel process 1 will lose out to other processes, such as $\ee \to \Z^0 \Z^0$ and $\ee \to \W^+ \W^-$, i.e. processes 22 and 25. The former process in fact includes the structure $\ee \to (\gammaZ)(\gammaZ)$, which means that the cross section is singular if either of the two $\gammaZ$ masses is allowed to vanish. A mass cut therefore needs to be introduced, and is actually also used in other processes, such as $\ee \to \W^+ \W^-$. For practical applications, both with respect to cross sections and to event shapes, it is imperative to include initial-state radiation effects. Therefore \ttt{MSTP(11)=1} is the default, wherein exponentiated electron-inside-electron distributions are used to give the momentum of the actually interacting electron. By radiative corrections to process 1, such processes as $\ee \to \gamma \Z^0$ are therefore automatically generated. If process 19 were to be used at the same time, this would mean that radiation were to be double-counted. In the alternative \ttt{MSTP(11)=0}, electrons are assumed to deposit their full energy in the hard process, i.e. initial-state QED radiation is not included. This option is very useful, since it often corresponds to the `ideal' events that one wants to correct back to. Resolved electrons also means that one may have interactions between photons. This opens up the whole field of $\gamma\gamma$ processes, which is described in section \ref{sss:photoprodclass}. In particular, with \ttt{MSTP(12)=1} photons may be resolved, i.e. photons need not only interact point-like, but can also interact like a hadron with a partonic substructure. The whole menagerie of hadron--hadron collider processes can then be accessed. However, it is not yet possible to include the low-$\pT$ processes with a variable photon energy spectrum. That is, to generate the `total' $\gamma\gamma$ spectrum, the program also has to be initialized for a $\gamma\gamma$ collider. The thrust of the {\PyJe} programs is towards processes that involve hadron production, one way or another. Because of generalizations from other areas, also a few completely non-hadronic processes are available. These include Bhabha scattering, $\ee \to \ee$ in process 10, and photon pair production, $\ee \to \gamma \gamma$ in process 18. However, note that the precision that could be expected in a {\Py} simulation of those processes is certainly far less than that of dedicated programs. For one thing, electroweak loop effects are not included. For another, nowhere is the electron mass taken into account, which means that explicit cut-offs at some minimum $\pT$ are always necessary. \subsubsection{Lepton--hadron collisions} The issue of applications to $\e\p$ colliders has been covered in a recent report \cite{Sjo92b}. The default process for a lepton--hadron collider is deep inelastic scattering, $\ell \q \to \ell' \q'$, of process 10. This includes $\gamma^0/\Z^0/\W^{\pm}$ exchange, with full interference, as described in section \ref{sss:DISclass}. Radiation off the incoming lepton leg is included by \ttt{MSTP(11)=1} and off the outgoing one by \ttt{MSTJ(41)=2} (both are default). Note that both QED and QCD radiation (off the $\e$ and the $\q$ legs, respectively) are allowed to modify the $x$ and $Q^2$ values of the process, while the conventional approach in the literature is to allow only the former. Therefore an option (on by default) has been added to preserve these values by a post-facto rescaling, \ttt{MSTP(23)=1}. In terms of cross sections, a more important set of processes are related to photoproduction, either with a point-like or with a resolved photon, see section \ref{sss:photoprodclass}. A complete description of photoproduction is available \cite{Sch93,Sch93a}, but needs three separate runs for the three distinct behaviours of a photon: point-like, VMD resolved and anomalous resolved. \subsubsection{Hadron--hadron collisions} The default is to include QCD jet production by $2 \to 2$ processes, see section \ref{sss:QCDjetclass}. Since the differential cross section is divergent for $\pT \to 0$, a lower cut-off has to be introduced. Normally that cut-off is given by the user-set $\pTmin$ value in \ttt{CKIN(3)}. If \ttt{CKIN(3)} is chosen smaller than a given value of the order of 2 GeV (see \ttt{PARP(81)} and \ttt{PARP(82)}), then low-$\pT$ events are also switched on. The jet cross section is regularized at low $\pT$, so as to obtain a smooth joining between the high-$\pT$ and the low-$\pT$ descriptions, see further section \ref{ss:multint}. As \ttt{CKIN(3)} is varied, the jump from one scenario to another is abrupt, in terms of cross section: in a high-energy hadron collider, the cross section for jets down to a $\pTmin$ scale of a few GeV can well reach values much larger than the total inelastic, non-diffractive cross section. Clearly this is nonsense; therefore either $\pTmin$ should be picked so large that the jet cross section be only a fraction of the total one, or else one should select $\pTmin = 0$ and make use of the full description. If one switches to \ttt{MSEL=2}, also elastic and diffractive processes are switched on, see section \ref{sss:minbiasclass}. However, the simulation of these processes is fairly primitive, and should not be used for dedicated studies, but only to estimate how much they may contaminate the class of non-diffractive minimum bias events. Most processes can be simulated in hadron colliders, since the bulk of {\Py} processes can be initiated by quarks or gluons. However, there are limits. Currently we include no photon or lepton parton distributions, which means that a process like $\gamma \q \to \gamma \q$ is not accessible. Further, the possibility of having $\Z^0$ and $\W^{\pm}$ interacting in processes such as 71--77 has been hardwired process by process, and does not mean that there is a generic treatment of $\Z^0$ and $\W^{\pm}$ distributions. The emphasis in the hadron--hadron process description is on high energy hadron colliders. The program can be used also at fixed-target energies, but the multiple interaction model for underlying events then breaks down and should not be used. The limit of applicability is somewhere at around 100 GeV. Below that, one is also recommended to change to \ttt{MSTP(92)=3}, to obtain a reasonable amount of beam remnant particle production in the absence of multiple interactions. \clearpage \section{The PYTHIA Program Elements} In the previous two sections, the physics processes and the event-generation schemes of {\Py} have been presented. Here, finally, the event-generation routines and the common block variables are described. However, routines and variables related to initial- and final-state showers, beam remnants and underlying events, and fragmentation and decay are relegated to subsequent sections on these topics. Further, for historical reasons, many adjustable coupling constants are found in the \ttt{LUDAT1} common block in {\Je}, rather than somewhere in the {\Py} common blocks; these parameters are described in section \ref{ss:coupcons}. In the presentation in this section, information less important for an efficient use of {\Py} has been put closer to the end. We therefore begin with the main event generation routines, and follow this by the main common block variables. It is useful to distinguish three phases in a normal run with {\Py}. In the first phase, the initialization, the general character of the run is determined. At a minimum, this requires the specification of the incoming hadrons and the energies involved. At the discretion of the user, it is also possible to select specific final states, and to make a number of decisions about details in the subsequent generation. This step is finished by a \ttt{PYINIT} call, at which time several variables are initialized in accordance with the values set. The second phase consists of the main loop over the number of events, with each new event being generated by a \ttt{PYEVNT} call. This event may then be analysed, using information stored in some common blocks, and the statistics accumulated. In the final phase, results are presented. This may often be done without the invocation of any {\Py} routines. From \ttt{PYSTAT}, however, it is possible to obtain a useful list of cross sections for the different subprocesses. \subsection{The Main Subroutines} \label{ss:PYTmainroutines} There are two routines that you must know: \ttt{PYINIT} for initialization and \ttt{PYEVNT} for the subsequent generation of each new event. In addition, the cross section and other kinds of information available with \ttt{PYSTAT} are frequently useful. The other three routines described here, \ttt{PYFRAM}, \ttt{PYKCUT}, and \ttt{PYEVWT}, are of more specialized interest. \drawbox{CALL PYINIT(FRAME,BEAM,TARGET,WIN)}\label{p:PYINIT} \begin{entry} \itemc{Purpose:} to initialize the generation procedure. \iteme{FRAME :} a character variable used to specify the frame of the experiment. Upper-case and lower-case letters may be freely mixed. \begin{subentry} \iteme{= 'CMS' :} colliding beam experiment in c.m. frame, with beam momentum in $+z$ direction and target momentum in $-z$ direction. \iteme{= 'FIXT' :} fixed-target experiment, with beam particle momentum pointing in $+z$ direction. \iteme{= 'USER' :} full freedom to specify frame by giving beam momentum in \ttt{P(1,1)}, \ttt{P(1,2)} and \ttt{P(1,3)} and target momentum in \ttt{P(2,1)}, \ttt{P(2,2)} and \ttt{P(2,3)} in common block \ttt{LUJETS}. Particles are assumed on the mass shell, and energies are calculated accordingly. \iteme{= 'FOUR' :} as \ttt{'USER'}, except also energies should be specified, in \ttt{P(1,4)} and \ttt{P(2,4)}, respectively. The particles need not be on the mass shell; effective masses are calculated from energy and momentum. (But note that numerical precision may suffer; if you know the masses the option \ttt{'FIVE'} below is preferrable.) \iteme{= 'FIVE' :} as \ttt{'USER'}, except also energies and masses should be specified, i.e the full momentum information in \ttt{P(1,1) - P(1,5)} and \ttt{P(2,1) - P(2,5)} should be given for beam and target, respectively. Particles need not be on the mass shell. Space-like virtualities should be stored as $-\sqrt{-m^2}$. Four-momentum and mass information must match. \iteme{= 'NONE' :} there will be no initialization of any processes, but only of resonance widths and a few other process-independent variables. Subsequent to such a call, \ttt{PYEVNT} cannot be used to generate events, so this option is mainly intended for those who will want to construct their own events afterwards, but still want to have access to some of the {\Py} facilities. In this option, the \ttt{BEAM}, \ttt{TARGET} and \ttt{WIN} arguments are dummy. \end{subentry} \iteme{BEAM, TARGET :} character variables to specify beam and target particles. Upper-case and lower-case letters may be freely mixed. An antiparticle may be denoted either by `$\sim$' or `bar' at the end of the name. It is also possible to leave out the underscore (`\_') directly after `nu' in neutrino names, and the charge for proton and neutron. \begin{subentry} \iteme{= 'e-' :} electron. \iteme{= 'e+' :} positron. \iteme{= 'nu\_e' :} $\nu_{\e}$. \iteme{= 'nu\_e$\sim$' :} $\br{\nu}_{\e}$. \iteme{= 'mu-' :} $\mu^-$. \iteme{= 'mu+' :} $\mu^+$. \iteme{= 'nu\_mu' :} $\nu_{\mu}$. \iteme{= 'nu\_mu$\sim$' :} $\br{\nu}_{\mu}$. \iteme{= 'tau-' :} $\tau^-$. \iteme{= 'tau+' :} $\tau^+$. \iteme{= 'nu\_tau' :} $\nu_{\tau}$. \iteme{= 'nu\_tau$\sim$' :} $\br{\nu}_{\tau}$. \iteme{= 'gamma' :} photon (real, i.e. on the mass shell). \iteme{= 'pi0' :} $\pi^0$. \iteme{= 'pi+' :} $\pi^+$. \iteme{= 'pi-' :} $\pi^-$. \iteme{= 'n0' :} neutron. \iteme{= 'n$\sim$0' :} antineutron. \iteme{= 'p+' :} proton. \iteme{= 'p$\sim$-' :} antiproton. \iteme{= 'Lambda0' :} $\Lambda$ baryon. \iteme{= 'Sigma-' :} $\Sigma^-$ baryon. \iteme{= 'Sigma0' :} $\Sigma^0$ baryon. \iteme{= 'Sigma+' :} $\Sigma^+$ baryon. \iteme{= 'Xi-' :} $\Xi^-$ baryon. \iteme{= 'Xi0' :} $\Xi^0$ baryon. \iteme{= 'Omega-' :} $\Omega^-$ baryon. \iteme{= 'pomeron' :} the pomeron $\pomeron$; since pomeron parton distribution functions have not been defined this option can not be used currently. \iteme{= 'reggeon' :} the reggeon $\reggeon$, with comments as for the pomeron above. \end{subentry} \iteme{WIN :} related to energy of system, exact meaning depends on \ttt{FRAME}. \begin{subentry} \iteme{FRAME='CMS' :} total energy of system (in GeV). \iteme{FRAME='FIXT' :} momentum of beam particle (in GeV/$c$). \iteme{FRAME='USER' :} dummy (information is taken from the \ttt{P} vectors, see above). \end{subentry} \end{entry} \drawbox{CALL PYEVNT}\label{p:PYEVNT} \begin{entry} \itemc{Purpose:} to generate one event of the type specified by the \ttt{PYINIT} call. (This is the main routine, which calls a number of other routines for specific tasks.) \end{entry} \drawbox{CALL PYSTAT(MSTAT)}\label{p:PYSTAT} \begin{entry} \itemc{Purpose:} to print out cross-sections statistics, decay widths, branching ratios, status codes and parameter values. \ttt{PYSTAT} may be called at any time, after the \ttt{PYINIT} call, e.g. at the end of the run, or not at all. \iteme{MSTAT :} specification of desired information. \begin{subentry} \iteme{= 1 :} prints a table of how many events of the different kinds that have been generated and the corresponding cross sections. All numbers already include the effects of cuts required by the user in \ttt{PYKCUT}. \iteme{= 2 :} prints a table of the resonances defined in the program, with their particle codes (KF), and all allowed decay channels. (If the number of generations in \ttt{MSTP(1)} is 3, however, channels involving fourth-generation particles are not displayed.) For each decay channel is shown the sequential channel number (IDC) of the {\Je} decay tables, the partial decay width, branching ratio and effective branching ratio (in the event some channels have been excluded by the user). \iteme{= 3 :} prints a table with the allowed hard interaction flavours \ttt{KFIN(I,J)} for beam and target particles. \iteme{= 4 :} prints a table of the kinematical cuts \ttt{CKIN(I)} set by the user in the current run. \iteme{= 5 :} prints a table with all the values of the status codes \ttt{MSTP(I)} and the parameters \ttt{PARP(I)} used in the current run. \end{subentry} \end{entry} \drawbox{CALL PYFRAM(IFRAME)}\label{p:PYFRAM} \begin{entry} \itemc{Purpose:} to transform an event listing between different reference frames, if so desired. \iteme{IFRAME :} specification of frame the event is to be boosted to. \begin{subentry} \iteme{= 1 :} frame specified by user in the \ttt{PYINIT} call. \iteme{= 2 :} c.m. frame of incoming particles. \iteme{= 3 :} hadronic c.m. frame of lepton--hadron interaction events. Mainly intended for deep inelastic scattering, but can also be used in photoproduction. Note that both the lepton and any photons radiated off the lepton remain in the event listing, and have to be removed separately if you only want to study the hadronic subsystem. \end{subentry} \end{entry} \drawbox{CALL PYKCUT(MCUT)}\label{p:PYKCUT} \begin{entry} \itemc{Purpose:} to enable you to reject a given set of kinematic variables at an early stage of the generation procedure (before evaluation of cross sections), so as not to spend unnecessary time on the generation of events that are not wanted. The routine will not be called unless you require is by setting \ttt{MSTP(141)=1}, and never if `minimum-bias'-type events (including elastic and diffractive scattering) are to be generated as well. A dummy routine \ttt{PYKCUT} is included in the program file, so as to avoid unresolved external references when the routine is not used. \iteme{MCUT :} flag to signal effect of user-defined cuts. \begin{subentry} \iteme{= 0 :} event is to be retained and generated in full. \iteme{= 1 :} event is to be rejected and a new one generated. \end{subentry} \itemc{Remark :} at the time of selection, several variables in the \ttt{MINT} and \ttt{VINT} arrays in the \ttt{PYINT1} common block contain information that can be used to make the decision. The routine provided in the program file explicitly reads the variables that have been defined at the time \ttt{PYKCUT} is called, and also calculates some derived quantities. The information available includes subprocess type ISUB, $E_{\mrm{cm}}$, $\hat{s}$, $\hat{t}$, $\hat{u}$, $\hat{p}_{\perp}$, $x_1$, $x_2$, $x_{\mrm{F}}$, $\tau$, $y$, $\tau'$, $\cos\hat{\theta}$, and a few more. Some of these may not be relevant for the process under study, and are then set to zero. \end{entry} \drawbox{CALL PYEVWT(WTXS)}\label{p:PYEVWT} \begin{entry} \itemc{Purpose:} to allow you to reweight event cross sections, by process type and kinematics of the hard scattering. There exists two separate modes of usage, described in the following. \\ For \ttt{MSTP(142)=1}, it is assumed that the cross section of the process is correctly given by default in {\Py}, but that one wishes to generate events biased to a specific region of phase space. While the \ttt{WTXS} factor therefore multiplies the na\"{\i}ve cross section in the choice of subprocess type and kinematics, the produced event comes with a compensating weight \ttt{PARI(10)=1./WTXS}, which should be used when filling histograms etc. In the \ttt{PYSTAT(1)} table, the cross sections are unchanged (up to statistical errors) compared with the standard cross sections, but the relative composition of events may be changed and need no longer be in proportion to relative cross sections. A typical example of this usage is if one wishes to enhance the production of high-$\pT$ events; then a weight like \ttt{WTXS}$=(\pT/p_{\perp 0})^2$ (with $p_{\perp 0}$ some fixed number) might be appropriate. \\ For \ttt{MSTP(142)=2}, on the other hand, it is assumed that the true cross section is really to be modifed by the multiplicative factor \ttt{WTXS}. The generated events therefore come with unit weight, just as usual. This option is really equivalent to replacing the basic cross sections coded in {\Py}, but allows more flexibility: no need to recompile the whole of {\Py}. \\ The routine will not be called unless \ttt{MSTP(142)}$\geq 1$, and never if `minimum-bias'-type events (including elastic and diffractive scattering) are to be generated as well. Further, cross sections for additional multiple interactions or pile-up events are never affected. A dummy routine \ttt{PYEVWT} is included in the program file, so as to avoid unresolved external references when the routine is not used. \iteme{WTXS:} multiplication factor to ordinary event cross section; to be set (by you) in \ttt{PYEVWT} call. \itemc{Remark :} at the time of selection, several variables in the \ttt{MINT} and \ttt{VINT} arrays in the \ttt{PYINT1} common block contain information that can be used to make the decision. The routine provided in the program file explicitly reads the variables that have been defined at the time \ttt{PYEVWT} is called, and also calculates some derived quantities. The given list of information includes subprocess type ISUB, $E_{\mrm{cm}}$, $\hat{s}$, $\hat{t}$, $\hat{u}$, $\hat{p}_{\perp}$, $x_1$, $x_2$, $x_{\mrm{F}}$, $\tau$, $y$, $\tau'$, $\cos\hat{\theta}$, and a few more. Some of these may not be relevant for the process under study, and are then set to zero. \itemc{Warning:} the weights only apply to the hard scattering subprocesses. There is no way to reweight the shape of initial- and final-state showers, fragmentation, or other aspects of the event. \end{entry} \subsection{Switches for Event Type and Kinematics Selection} \label{ss:PYswitchkin} By default, if {\Py} is run for a hadron collider, only QCD $2 \to 2$ processes are generated, composed of hard interactions above $\pTmin=$\ttt{PARP(81)}, with low-$\pT$ processes added on so as to give the full (parametrized) inelastic, non-diffractive cross section. In an $\ee$ collider, $\gammaZ$ production is the default, and in an $\ep$ one it is deep inelastic scattering. With the help of the common block \ttt{PYSUBS}, it is possible to select the generation of another process, or combination of processes. It is also allowed to restrict the generation to specific incoming partons/particles at the hard interaction. This often automatically also restricts final-state flavours but, in processes such as resonance production or QCD/QED production of new flavours, switches in the {\Je} program may be used to this end; see section \ref{ss:parapartdat}. The \ttt{CKIN} array may be used to impose specific kinematics cuts. You should here be warned that, if kinematical variables are too strongly restricted, the generation time per event may become very long. In extreme cases, where the cuts effectively close the full phase space, the event generation may run into an infinite loop. The generation of $2 \to 1$ resonance production is performed in terms of the $\hat{s}$ and $y$ variables, and so the ranges \ttt{CKIN(1) - CKIN(2)} and \ttt{CKIN(7) - CKIN(8)} may be arbitrarily restricted without a significant loss of speed. For $2 \to 2$ processes, $\cos\hat{\theta}$ is added as a third generation variable, and so additionally the range \ttt{CKIN(27) - CKIN(28)} may be restricted without any danger. Effects from initial- and final-state radiation are not included, since they are not known at the time the kinematics at the hard interaction is selected. The sharp kinematical cut-offs that can be imposed on the generation process are therefore smeared, both by QCD radiation and by fragmentation. A few examples of such effects follow. \begin{Itemize} \item Initial-state radiation implies that each of the two incoming partons has a non-vanishing $\pT$ when they interact. The hard scattering subsystem thus receives a net transverse boost, and is rotated with respect to the beam directions. In a $2 \to 2$ process, what typically happens is that one of the scattered partons receives an increased $\pT$, while the $\pT$ of the other parton is reduced. \item Since the initial-state radiation machinery assigns space-like virtualities to the incoming partons, the definitions of $x$ in terms of energy fractions and in terms of momentum fractions no longer coincide, and so the interacting subsystem may receive a net longitudinal boost compared with na\"{\i}ve expectations, as part of the parton-shower machinery. \item Initial-state radiation gives rise to additional jets, which in extreme cases may be mistaken for either of the jets of the hard interaction. \item Final-state radiation gives rise to additional jets, which smears the meaning of the basic $2 \to 2$ scattering. The assignment of soft jets is not unique. The energy of a jet becomes dependent on the way it is identified, e.g. what jet cone size is used. \item The beam remnant description assigns primordial $k_{\perp}$ values, which also gives a net $\pT$ shift of the hard-interaction subsystem; except at low energies this effect is overshadowed by initial-state radiation, however. Beam remnants may also add further activity under the `perturbative' event. \item Fragmentation will further broaden jet profiles, and make jet assignments and energy determinations even more uncertain. \end{Itemize} In a study of events within a given window of experimentally defined variables, it is up to you to leave such liberal margins that no events are missed. In other words, cuts have to be chosen such that a negligible fraction of events migrate from outside the simulated region to inside the interesting region. Often this may lead to low efficiency in terms of what fraction of the generated events are actually of interest to you. See also section \ref{ss:PYTstarted}. In addition to the variables found in \ttt{PYSUBS}, also those in the \ttt{PYPARS} common block may be used to select exactly what one wants to have simulated. These possibilities will be described in the following subsection. The notation used above and in the following is that `$\hat{~}$' denotes internal variables in the hard scattering subsystem, while `$^*$' is for variables in the c.m. frame of the event as a whole. \drawbox{COMMON/PYSUBS/MSEL,MSUB(200),KFIN(2,-40:40),CKIN(200)}% \label{p:PYSUBS} \begin{entry} \itemc{Purpose:} to allow the user to run the program with any desired subset of processes, or restrict flavours or kinematics. If the default values, denoted below by (D=\ldots), are not satisfactory, they must be changed before the \ttt{PYINIT} call. \boxsep \iteme{MSEL :}\label{p:MSEL} (D=1) a switch to select between full user control and some preprogrammed alternatives. \begin{subentry} \iteme{= 0 :} desired subprocesses have to be switched on in \ttt{MSUB}, i.e. full user control. \iteme{= 1 :} depending on incoming particles, different alternatives are used. \\ Lepton--lepton: $\Z$ or $\W$ production (ISUB = 1 or 2). \\ Lepton--hadron: deep inelastic scattering (ISUB = 10). \\ Hadron--hadron: QCD high-$\pT$ processes (ISUB = 11, 12, 13, 28, 53, 68); additionally low-$\pT$ production if \ttt{CKIN(3)}$<$\ttt{PARP(81)} or \ttt{PARP(82)}, depending on \ttt{MSTP(82)} (ISUB = 95). If low-$\pT$ is switched on, the other \ttt{CKIN} cuts are not used. \\ A resolved photon counts as hadron, except that an anomalous photon cannot have low-$\pT$ interactions. When the photon is not resolved, the following cases are possible. \\ Photon--lepton: Compton scattering (ISUB = 34). \\ Photon--hadron: photon-parton scattering (ISUB = 33, 34, 54). \\ Photon--photon: fermion pair production (ISUB = 58). \iteme{= 2 :} as \ttt{MSEL = 1} for lepton--lepton, lepton--hadron and unresolved photons. For hadron--hadron (including resolved photons) all QCD processes, including low-$\pT$, single and double diffractive and elastic scattering, are included (ISUB = 11, 12, 13, 28, 53, 68, 91, 92, 93, 94, 95). The \ttt{CKIN} cuts are here not used. \iteme{= 4 :} charm ($\c\cbar$) production with massive matrix elements (ISUB = 81, 82, 84, 85). \iteme{= 5 :} bottom ($\b\bbar$) production with massive matrix elements (ISUB = 81, 82, 84, 85). \iteme{= 6 :} top ($\t\tbar$) production with massive matrix elements (ISUB = 81, 82, 84, 85). \iteme{= 7 :} low ($\lrm\br{\lrm}$) production with massive matrix elements (ISUB = 81, 82, 84, 85). \iteme{= 8 :} high ($\hrm\br{\hrm}$) production with massive matrix elements (ISUB = 81, 82, 84, 85). \iteme{= 10 :} prompt photons (ISUB = 14, 18, 29). \iteme{= 11 :} $\Z^0$ production (ISUB = 1). \iteme{= 12 :} $\W^{\pm}$ production (ISUB = 2). \iteme{= 13 :} $\Z^0$ + jet production (ISUB = 15, 30). \iteme{= 14 :} $\W^{\pm}$ + jet production (ISUB = 16, 31). \iteme{= 15 :} pair production of different combinations of $\gamma$, $\Z^0$ and $\W^{\pm}$ (except $\gamma\gamma$; see \ttt{MSEL} = 10) (ISUB = 19, 20, 22, 23, 25). \iteme{= 16 :} $\H^0$ production (ISUB = 3, 102, 103, 123, 124). \iteme{= 17 :} $\H^0 \Z^0$ or $\H^0 \W^{\pm}$ (ISUB = 24, 26). \iteme{= 18 :} $\H^0$ production, combination relevant for $\ee$ annihilation (ISUB = 24, 103, 123, 124). \iteme{= 19 :} $\H^0$, $\H'^0$ and $\A^0$ production, excepting pair production (ISUB = 24, 103, 123, 124, 153, 158, 171, 173, 174, 176, 178, 179). \iteme{= 21 :} $\Z'^0$ production (ISUB = 141). \iteme{= 22 :} $\W'^{\pm}$ production (ISUB = 142). \iteme{= 23 :} $\H^{\pm}$ production (ISUB = 143). \iteme{= 24 :} $\R^0$ production (ISUB = 144). \iteme{= 25 :} $\L_{\Q}$ (leptoquark) production (ISUB = 145, 162, 163, 164). \iteme{= 35:} single bottom production by $\W$ exchange (ISUB = 83). \iteme{= 36:} single top production by $\W$ exchange (ISUB = 83). \iteme{= 37:} single low production by $\W$ exchange (ISUB = 83). \iteme{= 38:} single high production by $\W$ exchange (ISUB = 83). \end{subentry} \boxsep \iteme{MSUB :}\label{p:MSUB} (D=200*0) array to be set when \ttt{MSEL=0} (for \ttt{MSEL}$\geq 1$ relevant entries are set in \ttt{PYINIT}) to choose which subset of subprocesses to include in the generation. The ordering follows the ISUB code given in section \ref{ss:ISUBcode} (with comments as given there). \begin{subentry} \iteme{MSUB(ISUB) = 0 :} the subprocess is excluded. \iteme{MSUB(ISUB) = 1 :} the subprocess is included. \itemc{Note:} when \ttt{MSEL=0}, the \ttt{MSUB} values set by the user are never changed by {\Py}. If you want to combine several different `subruns', each with its own \ttt{PYINIT} call, into one single run, it is up to you to remember not only to switch on the new processes before each new \ttt{PYINIT} call, but also to switch off the old ones that are no longer desired. \end{subentry} \boxsep \iteme{KFIN(I,J) :}\label{p:KFIN} provides an option to selectively switch on and off contributions to the cross sections from the different incoming partons/particles at the hard interaction. In combination with the {\Je} resonance decay switches, this also allows you to set restrictions on flavours appearing in the final state. \begin{subentry} \iteme{I :} is 1 for beam side of event and 2 for target side. \iteme{J :} enumerates flavours according to the KF code; see section \ref{ss:codes}. \iteme{KFIN(I,J) = 0 :} the parton/particle is forbidden. \iteme{KFIN(I,J) = 1 :} the parton/particle is allowed. \itemc{Note:} By default, the following are switched on: $\d$, $\u$, $\s$, $\c$, $\b$, $\e^-$, $\nu_{\e}$, $\mu^-$, $\nu_{\mu}$, $\tau^-$, $\nu_{\tau}$, $\g$, $\gamma$, $\Z^0$, $\W^+$ and their antiparticles. In particular, top is off, and has to be switched on explicitly if needed. \end{subentry} \boxsep \iteme{CKIN :}\label{p:CKIN} kinematics cuts that can be set by you before the \ttt{PYINIT} call, and that affect the region of phase space within which events are generated. Some cuts are `hardwired' while most are `softwired'. The hardwired ones are directly related to the kinematical variables used in the event selection procedure, and therefore have negligible effects on program efficiency. The most important of these are \ttt{CKIN(1) - CKIN(8)}, \ttt{CKIN(27) - CKIN(28)}, and \ttt{CKIN(31) - CKIN(32)}. The softwired ones are most of the remaining ones, that cannot be fully taken into account in the kinematical variable selection, so that generation in constrained regions of phase space may be slow. In extreme cases the phase space may be so small that the maximization procedure fails to find any allowed points at all (although some small region might still exist somewhere), and therefore switches off some subprocesses, or aborts altogether. \iteme{CKIN(1), CKIN(2) :} (D=2.,-1. GeV) range of allowed $\hat{m} = \sqrt{\hat{s}}$ values. If \ttt{CKIN(2)}$ < 0.$, the upper limit is inactive. \iteme{CKIN(3), CKIN(4) :} (D=0.,-1. GeV) range of allowed $\hat{p}_{\perp}$ values for hard $2 \to 2$ processes, with transverse momentum $\hat{p}_{\perp}$ defined in the rest frame of the hard interaction. If \ttt{CKIN(4)}$ < 0.$, the upper limit is inactive. For processes that are singular in the limit $\hat{p}_{\perp} \to 0$ (see \ttt{CKIN(6)}), \ttt{CKIN(5)} provides an additional constraint. The \ttt{CKIN(3)} and \ttt{CKIN(4)} limits can also be used in $2 \to 1 \to 2$ processes. Here, however, the product masses are not known and hence are assumed to be vanishing in the event selection. The actual $\pT$ range for massive products is thus shifted downwards with respect to the nominal one. \iteme{CKIN(5) :} (D=1. GeV) lower cut-off on $\hat{p}_{\perp}$ values, in addition to the \ttt{CKIN(3)} cut above, for processes that are singular in the limit $\hat{p}_{\perp} \to 0$ (see \ttt{CKIN(6)}). \iteme{CKIN(6) :} (D=1. GeV) hard $2 \to 2$ processes, which do not proceed only via an intermediate resonance (i.e. are $2 \to 1 \to 2$ processes), are classified as singular in the limit $\hat{p}_{\perp} \to 0$ if either or both of the two final-state products has a mass $m < $\ttt{CKIN(6)}. \iteme{CKIN(7), CKIN(8) :} (D=-10.,10.) range of allowed scattering subsystem rapidities $y = y^*$ in the c.m. frame of the event, where $y = (1/2) \ln(x_1/x_2)$. (Following the notation of this section, the variable should be given as $y^*$, but because of its frequent use, it was called $y$ in section \ref{ss:kinemtwo}.) \iteme{CKIN(9), CKIN(10) :} (D=-10.,10.) range of allowed (true) rapidities for the product with largest rapidity in a $2 \to 2$ or a $2 \to 1 \to 2$ process, defined in the c.m. frame of the event, i.e. $\max(y^*_3, y^*_4)$. Note that rapidities are counted with sign, i.e. if $y^*_3 = 1$ and $y^*_4 = -2$ then $\max(y^*_3, y^*_4) = 1$. \iteme{CKIN(11), CKIN(12) :} (D=-10.,10.) range of allowed (true) rapidities for the product with smallest rapidity in a $2 \to 2$ or a $2 \to 1 \to 2$ process, defined in the c.m. frame of the event, i.e. $\min(y^*_3, y^*_4)$. Consistency thus requires \ttt{CKIN(11)}$\leq$\ttt{CKIN(9)} and \ttt{CKIN(12)}$\leq$\ttt{CKIN(10)}. \iteme{CKIN(13), CKIN(14) :} (D=-10.,10.) range of allowed pseudorapidities for the product with largest pseudorapidity in a $2 \to 2$ or a $2 \to 1 \to 2$ process, defined in the c.m. frame of the event, i.e. $\max(\eta^*_3, \eta^*_4)$. Note that pseudorapidities are counted with sign, i.e. if $\eta^*_3 = 1$ and $\eta^*_4 = -2$ then $\max(\eta^*_3, \eta^*_4) = 1$. \iteme{CKIN(15), CKIN(16) :} (D=-10.,10.) range of allowed pseudorapidities for the product with smallest pseudorapidity in a $2 \to 2$ or a $2 \to 1 \to 2$ process, defined in the c.m. frame of the event, i.e. $\min(\eta^*_3, \eta^*_4)$. Consistency thus requires \ttt{CKIN(15)}$\leq$\ttt{CKIN(13)} and \ttt{CKIN(16)}$\leq$\ttt{CKIN(14)}. \iteme{CKIN(17), CKIN(18) :} (D=-1.,1.) range of allowed $\cos\theta^*$ values for the product with largest $\cos\theta^*$ value in a $2 \to 2$ or a $2 \to 1 \to 2$ process, defined in the c.m. frame of the event, i.e. $\max(\cos\theta^*_3,\cos\theta^*_4)$. \iteme{CKIN(19), CKI