1 %% Computer Physics Communications class file, slightly modified
2 %% for reduced inter-paragraph and inter-section spacing.
3 \documentclass{elsartmod}
5 % Include graphics package.
8 % Standardised indentation.
9 \newcommand{\cindent}{\hspace*{10mm}~}
11 %Vertical positioning of page
12 %\setlength{\topmargin}{20mm}
21 FERMILAB-PUB-07-512-CD-T\\
25 \title{A Brief Introduction to PYTHIA 8.1}
27 \author[a,b]{Torbj\"orn Sj\"ostrand\thanksref{author}},
28 \author[c]{Stephen Mrenna},
29 \author[a,c]{Peter Skands}
31 \thanks[author]{Corresponding author, e-mail: torbjorn@thep.lu.se}
33 \address[a]{CERN/PH, CH--1211 Geneva 23, Switzerland}
34 \address[b]{Department of Theoretical Physics, Lund University,\\
35 S\"olvegatan 14A, SE-223 62 Lund, Sweden}
36 \address[c]{Fermi National Accelerator Laboratory, Batavia,
40 The \textsc{Pythia} program is a standard tool for the generation
41 of high-energy collisions, comprising a coherent set of physics
42 models for the evolution from a few-body hard process to a complex
43 multihadronic final state. It contains a library of hard processes
44 and models for initial- and final-state parton showers, multiple
45 parton-parton interactions, beam remnants, string fragmentation and
46 particle decays. It also has a set of utilities and interfaces to
47 external programs. While previous versions were written in Fortran,
48 \textsc{Pythia}~8 represents a complete rewrite in C++. The current
49 release is the first main one after this transition, and does not yet
50 in every respect replace the old code. It does contain some new physics
51 aspects, on the other hand, that should make it an attractive option
52 especially for LHC physics studies.
54 %Insert your suggested PACS number here
55 PACS: 13.66.-a, 13.85.-t, 12.38.-t, 12.15.-y, 12.60.-i
59 event generators, multiparticle production,
60 parton showers, multiple interactions, hadronisation
65 \dedicated{\rule{0mm}{8mm}Dedicated to the memory of\\[3mm]
66 \textbf{\textit{\Large Hans-Uno Bengtsson}}\\[1mm]
74 % Computer program descriptions should contain the following
77 {\bf NEW VERSION PROGRAM SUMMARY}
78 %Delete as appropriate.
82 {\em Manuscript Title:A Brief Introduction to \textsc{Pythia} 8.1} \\
83 {\em Authors:Torbj\"orn Sj\"ostrand, Stephen Mrenna, Peter Skands} \\
84 {\em Program Title: \textsc{Pythia} 8.1} \\
85 {\em Journal Reference:} \\
86 %Leave blank, supplied by Elsevier.
87 {\em Catalogue identifier:} \\
88 %Leave blank, supplied by Elsevier.
89 {\em Licensing provisions: GPL version 2} \\
90 %enter "none" if CPC non-profit use license is sufficient.
91 {\em Programming language: C++} \\
92 {\em Computer: commodity PCs} \\
93 %Computer(s) for which program has been designed.
94 {\em Operating systems: Linux; should also work on other systems} \\
95 %Operating system(s) for which program has been designed.
96 {\em RAM: 8} megabytes \\
97 %RAM in bytes required to execute program with typical data.
98 %{\em Number of processors used:} \\
99 % %If more than one processor.
100 %{\em Supplementary material:} \\
101 % % Fill in if necessary, otherwise leave out.
102 {\em Keywords: event generators, multiparticle production,
103 parton showers, multiple interactions, hadronisation} \\
104 % Please give some freely chosen keywords that we can use in a
105 % cumulative keyword index.
106 {\em PACS: 13.66.-a, 13.85.-t, 12.38.-t, 12.15.-y, 12.60.-i} \\
107 % see http://www.aip.org/pacs/pacs.html
108 {\em Classification: 11.2 Phase Space and Event Simulation} \\
109 %Classify using CPC Program Library Subject Index, see (
110 % http://cpc.cs.qub.ac.uk/subjectIndex/SUBJECT_index.html)
111 %e.g. 4.4 Feynman diagrams, 5 Computer Algebra.
112 %{\em External routines/libraries: none} \\
113 % % Fill in if necessary, otherwise leave out.
114 %{\em Subprograms used:} \\
115 % %Fill in if necessary, otherwise leave out.
116 {\em Catalogue identifier of previous version: ADNN\_v1\_0} \\
117 %Only required for a New Version summary, otherwise leave out.
118 {\em Journal reference of previous version: T. Sj\"ostrand, P. Ed\'en,
119 C. Friberg, L. L\"onnblad, G. Miu, S. Mrenna and E. Norrbin,
120 Computer Physics Commun. {\bf 135} (2001) 238} \\
121 %Only required for a New Version summary, otherwise leave out.
122 {\em Does the new version supersede the previous version?: yes, partly} \\
123 %Only required for a New Version summary, otherwise leave out.
125 {\em Nature of problem: high-energy collisions between
126 elementary particles normally give rise to complex final states,
127 with large multiplicities of hadrons, leptons, photons and neutrinos.
128 The relation between these final states and the underlying
129 physics description is not a simple one, for two main reasons.
130 Firstly, we do not even in principle have a complete understanding
131 of the physics. Secondly, any analytical approach is made
132 intractable by the large multiplicities. }\\
133 %Describe the nature of the problem here.
135 {\em Solution method: complete events are generated by Monte Carlo
136 methods. The complexity is mastered by a subdivision of the full
137 problem into a set of simpler separate tasks.
138 All main aspects of the events are simulated, such as
139 hard-process selection, initial- and final-state radiation, beam
140 remnants, fragmentation, decays, and so on. Therefore events should be
141 directly comparable with experimentally observable ones. The programs
142 can be used to extract physics from comparisons with existing
143 data, or to study physics at future experiments.}\\
144 %Describe the method solution here.
146 {\em Reasons for the new version: improved and expanded physics models,
147 transition from Fortran to C++}\\
148 %Only required for a New Version summary, otherwise leave out.
150 {\em Summary of revisions: new user interface,
151 transverse-momentum-ordered showers, interleaving with multiple
152 interactions, and much more}\\
153 %Only required for a New Version summary, otherwise leave out.
155 {\em Restrictions: depends on the problem studied}\\
156 %Describe any restrictions on the complexity of the problem here.
158 {\em Unusual features: none}\\
159 %Describe any unusual features of the program/problem here.
161 %{\em Additional comments:}\\
162 %Provide any additional comments here.
164 {\em Running time: 10--1000 events per second, depending on
166 %Give an indication of the typical running time here.
170 %\item Reference 1 % This is the reference list of the Program Summary
171 %\item Reference 2 % Type references in text as [1], [2], etc.
172 %\item Reference 3 % This list is different from the bibliography, which
173 % % you can use in the Long Write-Up.
179 % In program descriptions the main text of the paper is listed under
180 % the heading LONG WRITE-UP.
185 \section{Introduction}
187 The development of \textsc{Jetset} \cite{jetset}, containing several
188 of the components that later were merged with \textsc{Pythia}
189 \cite{pythiaearly}, was begun in 1978. Thus the current
190 \textsc{Pythia}~6 generator \cite{pythiasixone, pythiasixfour}
191 is the product of almost thirty years of development,
192 and some of the code has not been touched in a very long time. New
193 options have been added, but old ones seldom removed. The basic
194 structure has been expanded in different directions, well beyond
195 what it was once intended for, making it rather cumbersome by now.
197 {}From the onset, all code has been written in Fortran~77. For the
198 LHC era, the experimental community has made the decision to
199 move heavy computing completely to C++. Fortran support
200 may be poor to non-existing, and young experimenters will not
201 be conversant in Fortran any longer. Therefore it is logical
202 also to migrate \textsc{Pythia} to C++, and in the process clean
203 up and modernise various aspects.
205 A first attempt in this direction was the \textsc{Pythia}~7 project
206 \cite{pythiaseven}. However, priority came to be given to the
207 development of a generic administrative structure, renamed
208 \textsc{ThePEG} \cite{thepeg} and adopted by the \textsc{Herwig++}
209 \cite{herwigpp} group, while the physics parts of \textsc{Pythia}~7
210 remained underdeveloped.
212 \textsc{Pythia}~8 is a clean new start, to provide a successor to
213 \textsc{Pythia}~6. It is a completely standalone generator, thus not
214 relying on \textsc{ThePEG} or any other external library. Some
215 optional hooks for links to other programs are provided, however.
217 The version presented here is the first operational one in the
218 \textsc{Pythia}~8 series. As such it is not yet tested and tuned
219 enough to have reached the same level of maturity as \textsc{Pythia}~6,
220 so we expect the two to coexist for a while. It is only by an
221 increasing use of the new version that it will mature, however,
222 so we encourage a critical try-out, and look forward to feedback.
224 The intention is to release a version in time for comparisons
225 with first LHC data. Thus some areas, like $\gamma\mathrm{p}$ and
226 $\gamma\gamma$ physics, are not yet addressed. Further, some
227 intended processes remain to be implemented. Actually, with the
228 rise of automatic matrix-element code generation and phase-space
229 sampling, input of process-level events via the Les Houches Accord
230 (LHA) \cite{lha} and with Les Houches Event Files (LHEF) \cite{lhef}
231 reduces the need to have an extensive process library inside
232 \textsc{Pythia} itself. Thus emphasis is more on providing a good
233 description of subsequent steps of the story, involving elements
234 such as initial- and final-state parton showers, multiple
235 parton--parton interactions, string fragmentation, and decays.
237 The current article provides an introduction to \textsc{Pythia}~8.
238 The programming aspects are covered in more detail in a set
239 of interlinked HTML (or alternatively PHP) pages that comes in the
240 same package as the program files, see below.
241 Much of the physics aspects are unchanged
242 relative to the \textsc{Pythia}~6.4 manual \cite{pythiasixfour}, and
243 so we refer to it and to other physics articles for that. Instead
244 what we here give is an overview for potential users who already
245 have some experience with event generators and want to understand
246 how to get going with \textsc{Pythia}~8.
248 Section \ref{sec:physics} contains an ultra-brief summary of the
249 physics of \textsc{Pythia}~8, with particular emphasis on aspects that
250 are different relative to \textsc{Pythia}~6. The program
251 structure (including flow, files, documentation, and a few important
252 warnings) is described in section \ref{sec:structure}; summaries of
253 the main user methods, including the event record and particle
254 classes, in section \ref{sec:main}. Section
255 \ref{sec:databases} is concerned with the databases of flags, modes,
256 parameters, processes, and particle data which exist in \textsc{Pythia}~8.
257 Those who wish to link to external programs, e.g.\ to gain access
258 to external parton distributions, standard input/output formats, and
259 much more, will find the relevant information in section
260 \ref{sec:external}. A brief how-to on getting going is then included
261 in section \ref{sec:how-to}. Section \ref{sec:outlook} rounds off with
264 \section{Physics Summary \label{sec:physics}}
266 This article is not intended to provide a complete description of
267 the physics content. For this we primarily refer to the
268 \textsc{Pythia}~6 manual \cite{pythiasixfour} and associated
269 literature. We would like to draw attention to some key points of
270 difference, however. Further details are available on the HTML/PHP
271 pages in the program distribution. Some new physics aspects will
272 eventually be covered in separate articles.
274 The physics components are controlled by many parameters. These have
275 been assigned sensible default values, based on previous experience
276 with \textsc{Pythia}~6 and some first studies with the new code. We
277 look forward to more extensive tunes by the experimental community,
280 \subsection{Hard processes}
282 Currently the program only works with $\mathrm{p}\mathrm{p}$,
283 $\overline{\mathrm{p}}\mathrm{p}$, $\mathrm{e}^+\mathrm{e}^-$
285 incoming beams. In particular, there is no provision for
286 $\mathrm{e}\mathrm{p}$ collisions or for incoming photon beams,
287 neither on their own nor as flux around an electron.
289 The list of processes currently implemented is summarised further
290 down; it corresponds to most of the ones in \textsc{Pythia}~6,
291 with the exception of the Supersymmetry and Technicolor sectors,
292 which are yet to come. The cross-section expressions should be
293 identical, but default scale choices have been changed, so that
294 cross sections may be somewhat different for that reason.
296 The default parton distribution remains CTEQ 5L, but ones found in the
297 \textsc{LhaPdf} library \cite{lhapdf} can easily be linked. It is now
298 possible to use separate PDF sets for the hard interaction, on one
299 hand, and for the subsequent showers and multiple interactions, on the
302 \subsection{Parton showers}
304 The initial- and final-state algorithms are based on the
305 new $p_{\perp}$-ordered evolution introduced in \textsc{Pythia}~6.3
306 \cite{ptshowers}, while the older mass-ordered ones have not been
307 implemented. It is now additionally possible to have a branching
308 of a photon to a fermion pair as part of the final-state evolution.
310 Already in \textsc{Pythia}~6.3 the initial-state evolution and
311 the multiple interactions were interleaved into one common
312 decreasing $p_{\perp}$ sequence. Now also the final-state evolution
313 is interleaved with the other two. In this context, some of that
314 final-state radiation gets to be associated with dipoles stretched
315 between a final-state parton and the ``hole'' left by an
316 initial-state one, which therefore now can take a recoil.
317 The initial-state-radiation algorithm remains unchanged in this
318 respect, with recoils always taken by the hard scattering subsystem
321 \subsection{Multiple interactions and beam remnants}
323 The multiple-interactions machinery as such contains the full
324 functionality introduced in \textsc{Pythia}~6.3 \cite{newremnants}.
325 Rescaled parton densities are defined after the first interaction,
326 that take into account the nature of the previous partons extracted.
327 Currently there is only one scenario for colour-reconnection in the
328 final state, in which there is a certain probability for the partons of
329 two subscatterings to have their colours interarranged in a way that
330 reduces the total string length. (This is intermediate in character
331 between the original strategy \cite{zijl} and the more recent ones
332 \cite{wicke}.) The description of beam remnants is based on the
335 In addition to the standard QCD $2 \to 2$ processes, the possibility
336 of multiple interactions producing prompt photons, charmonia and
337 bottomonia, low-mass Drell-Yan pairs, and $t$-channel
338 $\gamma^*/\mathrm{Z}^0/\mathrm{W}^{\pm}$ exchange is now also
341 For dedicated studies of two low-rate processes in coincidence, two
342 hard interactions can now be set in the same event. There are no
343 Sudakov factors included for these two interactions, similarly to
344 normal events with one hard interaction.
346 \subsection{Hadronisation}
348 Hadronisation is based solely on the Lund string fragmentation
349 framework \cite{lundreview}; older alternative descriptions have
352 Particle data have been updated in agreement with the 2006 PDG
353 tables \cite{pdg}. This also includes a changed content of the scalar
354 meson multiplet. Some updated charm and bottom decay tables have been
355 obtained from the DELPHI and LHCb collaborations.
357 The BE$_{32}$ model for Bose--Einstein effects \cite{boseeinstein}
358 has been implemented, but is not on by default.
360 \subsection{Other program components}
362 Standardised procedures have been introduced to link the program
363 to various external programs for specific tasks, see section
366 Finally, some of the old jet finders and other analysis routines are
367 made available. Also included is a utility to generate, display and
368 save simple one-dimensional histograms.
370 \section{Program Structure \label{sec:structure}}
372 \subsection{Program flow}
374 The physics topics that have to come together in a complete
375 event generator can crudely be subdivided into three stages:
377 \item The generation of a ``process'' that decides the nature of the
378 event. Often it would be a ``hard process'', such as $\mathrm{g}
379 \mathrm{g} \to \mathrm{h}^0 \to \mathrm{Z}^0 \mathrm{Z}^0 \to \mu^+
380 \mu^- \mathrm{q} \overline{\mathrm{q}}$, that is calculated in
381 perturbation theory, but a priori we impose no requirement that a hard
382 scale must be involved. Only a very small set of
383 partons/particles is defined at this level, so only the main aspects
384 of the event structure are covered.
385 \item The generation of all subsequent activity on the partonic level,
386 involving initial- and final-state radiation, multiple parton--parton
387 interactions and the structure of beam remnants. Much of the phenomena
388 are under an (approximate) perturbative control, but nonperturbative
389 physics aspects are also important. At the end of this step, a realistic
390 partonic structure has been obtained, e.g. with broadened jets and
391 an underlying-event activity.
392 \item The hadronisation of this parton configuration, by string
393 fragmentation, followed by the decays of unstable particles. This
394 part is almost completely nonperturbative, and so requires extensive
395 modelling and tuning or, especially for decays, parametrisations of
396 existing data. It is only at the end of this step that realistic events
397 are available, as they could be observed by a detector.
399 This division of tasks is not watertight --- parton distributions span
400 and connect the two first steps, to give one example --- but it still
401 helps to focus the discussion.
404 \begin{picture}(430,370)(-215,10)
405 \GBox(-215,350)(215,380){0.9}
406 \Text(0,365)[]{The User ($\approx$ Main Program)}
407 \GBox(-215,300)(215,330){0.9}
408 \Text(0,315)[]{\texttt{Pythia}}
409 \GBox(-215,250)(-170,280){0.9}
410 \Text(-192.5,265)[]{\texttt{Info}}
411 \GBox(-130,250)(-20,280){0.9}
412 \Text(-75,265)[]{\texttt{Event~~process}}
413 \GBox(20,250)(215,280){0.9}
414 \Text(105,265)[]{\texttt{Event~~event}}
415 \GBox(-215,110)(-85,230){0.9}\Line(-215,200)(-85,200)
416 \Text(-150,215)[]{\texttt{ProcessLevel}}
417 \Text(-150,185)[]{\texttt{ProcessContainer}}
418 \Text(-150,165)[]{\texttt{PhaseSpace}}
419 \Text(-150,145)[]{\texttt{LHAinit, LHAevnt}}
420 \Text(-150,125)[]{\texttt{ResonanceDecays}}
421 \GBox(-65,110)(65,230){0.9}\Line(-65,200)(65,200)
422 \Text(0,215)[]{\texttt{PartonLevel}}
423 \Text(0,185)[]{\texttt{TimeShower}}
424 \Text(0,165)[]{\texttt{SpaceShower}}
425 \Text(0,145)[]{\texttt{MultipleInteractions}}
426 \Text(0,125)[]{\texttt{BeamRemnants}}
427 \GBox(85,110)(215,230){0.9}\Line(85,200)(215,200)
428 \Text(150,215)[]{\texttt{HadronLevel}}
429 \Text(150,185)[]{\texttt{StringFragmentation}}
430 \Text(150,165)[]{\texttt{MiniStringFrag\ldots}}
431 \Text(150,145)[]{\texttt{ParticleDecays}}
432 \Text(150,125)[]{\texttt{BoseEinstein}}
433 \GBox(-130,60)(-20,90){0.9}
434 \Text(-75,75)[]{\texttt{BeamParticle}}
435 \GBox(20,60)(200,90){0.9}
436 \Text(110,75)[]{\texttt{SigmaProcess, SigmaTotal}}
437 \GBox(-215,10)(215,40){0.9}
438 \Text(0,25)[]{\texttt{Vec4, Rndm, Hist, Settings, %
439 ParticleDataTable, ResonanceWidths, \ldots}}
441 \LongArrow(0,350)(0,332)
442 \LongArrow(-150,300)(-150,232)
443 \LongArrow(0,300)(0,232)
444 \Line(150,300)(150,280)
445 \DashLine(150,280)(150,250){4}
446 \LongArrow(150,250)(150,232)
448 \LongArrow(-192.5,230)(-192.5,248)
449 \Line(-192.5,280)(-192.5,300)
450 \DashLine(-192.5,300)(-192.5,330){4}
451 \LongArrow(-192.5,330)(-192.5,348)
452 \LongArrow(-107.5,230)(-107.5,248)
453 \LongArrow(-42.5,250)(-42.5,232)
454 \Line(-42.5,280)(-42.5,300)
455 \DashLine(-42.5,300)(-42.5,330){4}
456 \LongArrow(-42.5,330)(-42.5,348)
457 \LongArrow(42.5,230)(42.5,248)
458 \LongArrow(107.5,250)(107.5,232)
459 \LongArrow(182.5,230)(182.5,248)
460 \Line(182.5,280)(182.5,300)
461 \DashLine(182.5,300)(182.5,330){4}
462 \LongArrow(182.5,330)(182.5,348)
463 \LongArrow(-107.5,100)(-107.5,108)
464 \LongArrow(-107.5,100)(-107.5,92)
465 \LongArrow(-42.5,100)(-42.5,108)
466 \LongArrow(-42.5,100)(-42.5,92)
467 \LongArrow(42.5,100)(42.5,108)
468 \LongArrow(42.5,100)(42.5,92)
469 \LongArrow(-160,50)(-160,108)
471 \LongArrow(0,50)(19,59)
473 \caption{The relationship between the main classes in
474 \textsc{Pythia}~8. The thick arrows show the flow of commands
475 to carry out different physics tasks, whereas the thinner show
476 the flow of information between the tasks. The bottom box
477 contains common utilities that may be used anywhere. Obviously
478 the picture is strongly simplified.
479 \label{fig:generatorstructure}}
483 The structure of the \textsc{Pythia}~8 generator, as illustrated in
484 Fig.~\ref{fig:generatorstructure}, is based on this subdivision.
485 The main class for all user interaction is called \texttt{Pythia}.
486 It calls on the three classes \texttt{ProcessLevel},
487 \texttt{PartonLevel} and \texttt{HadronLevel}, corresponding
488 to points 1, 2 and 3 above. Each of these, in their turn, call on
489 further classes that perform the separate kinds of physics tasks.
491 Information is flowing between the different program elements in
492 various ways, the most important being the event record, represented
493 by the \texttt{Event} class. Actually, there are two objects of this
494 class, one called \texttt{process}, that only covers the few partons
495 of the ``hard'' process of point 1 above (i.e., containing information
496 corresponding to what might be termed the ``matrix element'' level),
497 and another called \texttt{event}, that covers the full story from the
498 incoming beams to the final hadrons. A small \texttt{Info} class keeps
499 track of useful one-of-a-kind information, such as kinematical
500 variables of the hard process.
502 There are also two incoming \texttt{BeamParticle}s, that keep track
503 of the partonic content left in the beams after a number of
504 interactions and initial-state radiations, and rescales parton
505 distributions accordingly.
507 The process library, as well as parametrisations of total, elastic
508 and diffractive cross sections, are used both by the hard-process
509 selection machinery and the multiple-interactions one.
511 The \texttt{Settings} database keeps track of all integer, double,
512 boolean and string variables that can be changed by the user to steer
513 the performance of \textsc{Pythia}, except that
514 \texttt{ParticleDataTable} is its own separate database.
516 Finally, a number of utilities can be used just about anywhere,
517 for Lorentz four-vectors, random numbers, jet finding and simple
518 histograms, and for a number of other ``minor'' tasks.
520 Orthogonally to the subdivision above, there is another, more
521 technical classification, whereby the user interaction with the
522 generator occurs in three phases:
524 \item Initialisation, where the tasks to be performed are specified.
525 \item Generation of individual events (the ``event loop'').
526 \item Finishing, where final statistics is made available.
528 Again the subdivision (and orthogonality) is not strict, with many
529 utilities and tasks stretching across the borders, and with no
530 finishing step required for many aspects. Nevertheless, as a rule,
531 these three phases are represented by different methods
532 inside the class of a specific physics task.
534 \subsection{Program files and documentation}
536 The code is subdivided into a set of files, mainly by physics
537 task. Each file typically contains one main class, but often
538 with a few related helper classes that are not used elsewhere in
539 the program. Normally the files come in pairs.
541 \item A header file, \texttt{.h} in the \texttt{include}
542 subdirectory, where the public interface of the class is declared,
543 and inline methods are defined.
544 \item A source code file, \texttt{.cc} in the \texttt{src}
545 subdirectory, where the lengthier methods are implemented.
547 During compilation, related dependency files, \texttt{.d}, and
548 compiled code, \texttt{.o} are created in the \texttt{tmp}
551 In part the \texttt{.xml} documentation files in the \texttt{xmldoc}
552 subdirectory have matching names, but the match is broken by the
553 desire to group topics more by user interaction than internal
554 operation. These files contain information on all settings and
555 particle data, but not in a convenient-to-read format. Instead they
556 are translated into a corresponding set of \texttt{.html} files
557 in the \texttt{htmldoc} subdirectory and a set of \texttt{.php}
558 files in \texttt{phpdoc}. The former set can easily be read if
559 you open the \texttt{htmldoc/Welcome.html} file in your favourite
560 web browser, but offers no interactivity. The latter set must be
561 installed under a webserver (like a homepage) to function properly,
562 and then provides a simple Graphical User Interface if you open the
563 \texttt{phpdoc/Welcome.php} file in a web browser.
565 For output to the \textsc{HepMC} event record format \cite{hepmc},
566 an interface is provided in the \texttt{hepmcinterface} subdirectory.
567 There are also interfaces to allow parton distribution functions
568 to be used from the \textsc{LhaPdf} library \cite{lhapdf} and hard
569 processes from external programs.
571 The installation procedure is described in a \texttt{README} file; it
572 involves running a \texttt{configure} script, whereafter an ordinary
573 \texttt{Makefile} is used. The former should be invoked with
574 command-line arguments (or be edited) to provide the path to the
575 \textsc{HepMC} library if this is going to be used. Compiled
576 libraries are put in the \texttt{lib} subdirectory. Default is to
577 build archive libraries, but optionally also shared-object ones can be
578 built. The standard setup is intended for Linux systems, but a
579 simplified alternative is provided for Windows users.
581 Finally, some examples of main programs, along with input files, or
582 ``cards'', for them, are found in the \texttt{examples}
583 subdirectory. This directory contains its own
584 \texttt{configure} script and \texttt{Makefile} which will allow you
585 to build executables, see the \texttt{examples/README} file.
586 As above, command-line arguments or brute-force editing allows you
587 to set the \textsc{LhaPdf} and \textsc{Pythia}~6.4 paths, if so required.
588 The executables are placed in the \texttt{bin} directory, but with
589 links from \texttt{examples}.
591 \subsection{Important warnings}
593 Playing with the files in the \texttt{examples} subdirectory is
594 encouraged, to familiarise oneself with the program. Modifying the
595 \texttt{configure} files may be required during installation. For
596 the rest, files should not be modified, at least not without
597 careful consideration of consequences.
599 In particular, the \texttt{.xml} files are set read-only, and should
600 not be tampered with. Interspersed in them, there are lines beginning
601 with \texttt{<flag}, \texttt{<mode}, \texttt{<parm}, \texttt{<word},
602 \texttt{<particle}, \texttt{<channel}, or \texttt{<a}. They contain
603 instructions from which \texttt{Settings} and \texttt{ParticleDataTable}
604 build up their respective databases of user-accessible variables,
605 see further below. Any stupid changes here will cause
606 difficult-to-track errors!
608 Further, sometimes you will see two question marks, ``??'', in the
609 text or code. This is for internal usage, to indicate loose ends or
610 preliminary thoughts. Please disregard.
612 \section{Main Program and Event Information \label{sec:main}}
614 \subsection{The \texttt{Pythia} class}
616 The \texttt{Pythia} class is the main means of communication between
617 the user and the event-generation process. We here present the key
618 methods for the user to call, ordered by context.
620 Firstly, at the top of the main program, the proper header file must
622 \cindent \texttt{\#include "Pythia.h"}\\
623 To simplify typing, it also makes sense to declare\\
624 \cindent \texttt{using namespace Pythia8;}\\
625 Given this, the first step in the main program is to create a
626 generator object, e.g. with\\
627 \cindent \texttt{Pythia pythia;}\\
628 In the following we will assume that the \texttt{pythia} object
629 has been created with this name, but of course you are free to
632 When this object is declared,
633 the \texttt{Pythia} constructor initialises all
634 the default values for the \texttt{Settings} and the
635 \texttt{ParticleDataTable} data bases. These data are now present in
636 memory and can be modified in a number of ways before the generator is
637 initialised (see below).
638 Most conveniently, \textsc{Pythia}'s settings and parameters can be
639 changed by the two methods\\
640 \cindent \texttt{pythia.readString(string);}\\
641 for changing a single variable, and\\
642 \cindent \texttt{pythia.readFile(fileName);}\\
643 for changing a set of variables, one per line in the input file.
644 The allowed form for a string/line will be explained as we consider
645 the databases in the next section. Further, methods will be introduced
646 to list all or only the changed settings and particle data.
648 At this stage you can also optionally hook up with some external
649 facilities, see section \ref{sec:external}.
651 After this, in the initialisation call all remaining details of the
652 generation are to be specified. The \texttt{pythia.init(...)} method
653 allows a few different input formats, so you can pick the one
654 convenient for you:\\
655 \cindent \texttt{pythia.init(idA, idB, eA, eB);}\\
656 lets you specify the identities and energies of the two incoming
657 beam particles, with A (B) assumed moving in the $+z$ ($-z$)
659 \cindent \texttt{pythia.init(idA, idB, eCM);}\\
660 is similar, but you specify the CM energy, and you are assumed
662 \cindent \texttt{pythia.init(LHAinit*, LHAevnt*);}\\
663 assumes LHA initialisation information is available
664 in an \texttt{LHAinit} class object, and that LHA event information
665 will be provided by the \texttt{LHAevnt} class object, see below;\\
666 \cindent \texttt{pythia.init(fileName);}\\
667 assumes that the file obeys the LHEF standard format and that
668 information can be extracted from it accordingly;
670 \cindent \texttt{pythia.init();}\\
671 will take its values from the beam specification stored in the
672 \texttt{Settings} database.
674 It is when the \texttt{init(...)} call is executed that all the
675 settings values are propagated to the various program elements, and
676 used to precalculate quantities that will be used at later
677 stages of the generation. Further settings changed after the
678 \texttt{init(...)} call will be ignored (unless methods are used to force
679 a partial or complete re-initialisation). By contrast, the particle
680 properties database is queried all the time, and so a later change
681 would take effect immediately, for better or worse.
683 The bulk of the code is concerned with the event generation proper.
684 However, all the information on how this should be done has already
685 been specified. Therefore only a command\\
686 \cindent \texttt{pythia.next();}\\
687 is required to generate the next event. This method would be located
688 inside an event loop, where a required number of events are to be
691 The key output of the \texttt{pythia.next()} command is the event
692 record found in \texttt{pythia.event}, see below. A process-level
693 summary of the event is stored in \texttt{pythia.process}.
695 When problems are encountered, in \texttt{init(...)} or
696 \texttt{next()}, they can be assigned one of three degrees of
697 severity. Abort is the highest. In that case the call could not
698 complete its tasks, and returns the value \texttt{false}. If this
699 happens in \texttt{init(...)} it is then not possible to generate any
700 events at all. If it happens in \texttt{next()} only the current event
701 must be skipped. In a few cases the abort may be predictable and
702 desirable, e.g.\ when a file of LHA events comes to an end. Errors are
703 less severe, and the program can usually work around them, e.g.\ by
704 backing up one step and trying again. Should that not succeed, an
705 abort may result. Warnings are of informative character only, and do
706 not require any corrective actions (except, in the longer term, to
707 find more reliable algorithms).
709 At the end of the generation process, you can call\\
710 \cindent \texttt{pythia.statistics();}\\
711 to get some run statistics, both on cross sections for the
712 subprocesses generated and on the number of aborts, errors and
715 \subsection{The event record}
717 The \texttt{Event} class for event records is not much more than
718 a wrapper for a vector of \texttt{Particle}s. This vector can expand
719 to fit the event size. The index operator is overloaded, so that
720 \texttt{event[i]} corresponds to the \texttt{i}'th particle of an
721 \texttt{Event} object called \texttt{event}. For instance, given
722 that the PDG identity code \cite{pdg} of a particle is provided by
723 the \texttt{id()} method, \texttt{event[i].id()} returns the identity
724 of the \texttt{i}'th particle.
726 Line 0 is used to represent the event as a whole, with its total
727 four-momentum and invariant mass, but does not form part of the
728 event history, and only contains redundant information. When you
729 translate to another event-record format where the first particle is
730 assigned index 1, such as \textsc{HepMC}, this line should therefore
731 be dropped so as to keep the rest of the indices synchronised.
732 It is only with lines 1 and 2, which contain the two incoming beams,
733 that the history tracing begins. That way unassigned mother and
734 daughter indices can be put 0 without ambiguity.
736 In this section, first the \texttt{Particle} methods are surveyed,
737 and then the further aspects of the event record.
739 \subsubsection{The particle}
741 A \texttt{Particle} corresponds to one entry/slot/line in the event
742 record. Its properties therefore mix ones belonging to a
743 particle-as-such, like its identity code or four-momentum, and ones
744 related to the event-as-a-whole, like which mother it has.
746 The following properties are stored for each particle, listed by the
747 member functions you can use to extract the information:
749 \item \texttt{id()} :
750 the identity of a particle, according to the PDG particle codes.
751 \item \texttt{status()} :
752 status code. The full set of codes provides information on where and why
753 a given particle was produced. The key feature is that a particle is
754 assigned a positive status code when it is created, which then is negated
755 if later it branches into other particles. The mechanism of this branching
756 can be inferred from the status code of the daughters. Thus, at any given
757 stage of the event-generation process, the current final state consists of
758 the particles with positive status code.
759 \item \texttt{mother1(), mother2()} :
760 the indices in the event record where the first and last mothers are
761 stored, if any. A few different cases are possible, to allow for one
762 or many mothers. The \texttt{motherList(i)} method (see below) can
763 return a vector with all the mother indices, based on this info.
764 \item \texttt{daughter1(), daughter2()} :
765 the indices in the event record where the first and last daughters are
766 stored, if any. A few different cases are possible, to allow for one
767 or many daughters. The \texttt{daughterList(i)} method (see below)
768 can return a vector with all the daughter indices, based on this info.
769 \item \texttt{col(), acol()} :
770 the colour and anticolour tags, LHA style.
771 \item \texttt{px(), py(), pz(), e()} :
772 the particle four-momentum components (in GeV, with $c = 1$),
773 alternatively extracted as a \texttt{Vec4 p()}.
775 the particle mass (in GeV).
776 \item \texttt{scale()} :
777 the scale at which a parton was produced (in GeV); model-specific
778 but relevant in the processing of an event.
779 \item \texttt{xProd(), yProd(), zProd(), tProd()} :
780 the production vertex coordinates (in mm or mm/$c$), alternatively
781 extracted as a \texttt{Vec4 vProd()}.
782 \item \texttt{tau()} : the proper lifetime (in mm/$c$).
784 The same method names, with a value inserted between the brackets,
785 set these quantities.
787 In addition, a number of derived quantities can easily be obtained,
788 but cannot be set, such as:
790 \item \texttt{isFinal()} :
791 \texttt{true} for a remaining particle, i.e. one with positive status
792 code, else \texttt{false}.
793 \item \texttt{pT(), pT2()} :
794 (squared) transverse momentum.
795 \item \texttt{mT(), mT2()} :
796 (squared) transverse mass.
797 \item \texttt{pAbs(), pAbs2()} :
798 (squared) three-momentum magnitude.
799 \item \texttt{theta(), phi()} :
800 polar and azimuthal angle (in radians).
801 \item \texttt{y(), eta()} : rapidity and pseudorapidity.
802 \item \texttt{xDec(), yDec(), zDec(), tDec()} :
803 the decay vertex coordinates, assuming free-streaming propagation,
804 alternatively extracted as a \texttt{Vec4 vDec()}.
807 Each \texttt{Particle} contains a pointer to the respective
808 \texttt{ParticleDataEntry} object in the particle data tables. This
809 pointer gives access to properties of the particle species as such.
810 It is there mainly for convenience, and should be thrown if an event
811 is written to disk, to avoid any problems of object persistency.
812 This pointer is used by member functions such as:
814 \item \texttt{name()} :
815 the name of the particle, as a string.
816 \item \texttt{spinType()} : $2 s + 1$, or 0 where undefined spin.
817 \item \texttt{charge(), chargeType()} : charge, and three times it
819 \item \texttt{isCharged(), isNeutral()} : \texttt{bool}s for charged
821 \item \texttt{colType()} : 0 for colour singlets, 1 for triplets,
822 $-1$ for antitriplets and 2 for octets.
823 \item \texttt{m0()} :
824 the nominal mass of the particle species.
827 \subsubsection{Other methods in the event record}
829 While the \texttt{Particle} vector is the key component of an
830 \texttt{Event}, a few further methods are available.
831 The event size can be found with \texttt{size()}, i.e. valid particles
832 are stored in the range $0 \leq $\texttt{i}$ <$ \texttt{event.size()}.
834 A listing of the whole event is obtained with \texttt{list()}. The
835 basic identity, status, mother, daughter, colour, four-momentum and
836 mass data are always given, but optional arguments can be set to provide
837 further information, on the complete lists of mothers and daughters,
838 and on production vertices.
840 The user would normally be concerned with the \texttt{Event} object that
841 is a public member \texttt{event} of the \texttt{Pythia} class. Thus
842 \texttt{pythia.event[i].id()} would be used to return the identity of
843 the \texttt{i}'th particle, and \texttt{pythia.event.size()} to give
844 the size of the event record.
846 A \texttt{Pythia} object contains a second event record for the
847 hard process alone, similar to the LHA process specification,
848 called \texttt{process}. This record is used as input for the
849 generation of the complete event. Thus one may e.g. call either
850 \texttt{pythia.process.list()} or \texttt{pythia.event.list()}. To
851 distinguish those two rapidly at visual inspection, the
852 ``Pythia Event Listing'' header is printed out differently, adding
853 either ``(hard process)'' or ``(complete event)''.
855 There are also a few methods with an individual particle index
856 \texttt{i} as input, but requiring some search operations in the
857 event record, and therefore not possible to define as methods of
858 the \texttt{Particle} class. The most important ones are
859 \texttt{motherList(i)}, \texttt{daughterList(i)} and
860 \texttt{sisterList(i)}. These return a \texttt{vector<int>} containing
861 a list of all the mothers, daughters or sisters of a particle. This
862 list may be empty or arbitrarily large, and is given in ascending order.
864 One data member in an Event object is used to keep track of the
865 largest \texttt{col()} or \texttt{acol()} tag set so far, so that new
868 The event record also contains two further sets of vectors. These are
869 intended for the expert user only, so only a few words on each.
870 The first is a vector of junctions, i.e.\ vertices where three string
871 pieces meet. This list is often empty or else contains only a very few
872 per event. The second is a storage area for parton indices, classified
873 by subsystem. Such information is needed to interleave multiple
874 interactions, initial-state showers, final-state showers and beam
875 remnants. It can also be used in the hadronisation.
877 \subsection{Other event information}
879 A set of one-of-a-kind pieces of event information is stored in the
880 \texttt{info} object (an instance of the class
881 \texttt{Info}) in the \texttt{Pythia} class. This is mainly
882 intended for processes generated internally, but some of the information
883 is also available for external processes.
885 You can use \texttt{pythia.info.method()} to extract e.g.\ the
886 following information:
888 \item \texttt{list()} : list some information on the current event.
889 \item \texttt{eCM(), s()} : the cm energy and its square.
890 \item \texttt{name(), code()} : the name and code of the subprocess.
891 \item \texttt{id1(), id2()} : the identities of the two partons
892 coming in to the hard subprocess.
893 \item \texttt{x1(), x2()} : $x$ fractions of the two partons coming
894 in to the hard subprocess.
895 \item \texttt{pdf1(), pdf2(), QFac(), Q2Fac()} : parton densities
896 $x \, f_i(x,Q^2 )$ evaluated for the two incoming partons, and the
897 associated factorisation scale $Q$ and its square.
898 \item \texttt{mHat(), sHat(), tHat(), uHat()} : the invariant mass of
899 the hard subprocess and the Mandelstam variables for $2 \to 2$
901 \item \texttt{pTHat(), thetaHat()} : transverse momentum and polar
902 scattering angle of the hard subprocess for $2 \to 2$ processes.
903 \item \texttt{alphaS(), alphaEM(), QRen(), Q2Ren()} :
904 $\alpha_{\mathrm{s}}$ and $\alpha_{\mathrm{em}}$ values for the
905 hard process, and the associated renormalisation scale $Q$ and its square.
906 \item \texttt{nTried(), nAccepted(), sigmaGen(), sigmaErr()} :
907 the number of trial and accepted events, and the resulting estimated
908 cross section and estimated statistical error, in units of mb, summed
909 over the included processes.
912 In other classes there are also methods that can be called to do a
913 sphericity or thrust analysis or search for jets with a clustering
914 or simple cone jet finder. These take the event record as input.
916 \section{Databases \label{sec:databases}}
918 Inevitably one wants to be able to modify the default behaviour of a
919 generator. Currently there are two \textsc{Pythia}~8 databases with
920 modifiable values. One deals with general settings, the other
921 specifically with particle data.
923 The key method to set a new value is\\
924 \cindent \texttt{pythia.readString(string);}\\
925 The typical form of a string is\\
926 \cindent \texttt{"variable = value"}\\
927 where the equal sign is optional and the variable begins with a letter
928 for settings and a digit for particle data. A string not beginning with
929 either is considered as a comment and ignored. Therefore inserting an
930 initial !, \#, \$, \%, or another such character, is a good way to
931 comment out a command. For non-commented strings, the match of the name
932 to the database is case-insensitive. Strings that do begin with a letter
933 or digit and still are not recognised cause a warning to be issued, unless
934 a second argument \texttt{false} is used in the call. Any further text
935 after the value is ignored, so the rest of the string can be used for
936 any comments. For variables with an allowed range, values below the minimum
937 or above the maximum are set at the respective border. For \texttt{bool}
938 values, the following notation may be used interchangeably:
939 \texttt{true} = \texttt{on} = \texttt{yes} = \texttt{ok} = 1. Everything
940 else gives \texttt{false} (including but not limited to \texttt{false},
941 \texttt{off}, \texttt{no} and \texttt{0}).
943 The \texttt{readString(...)} method is convenient for changing one or two
944 settings, but becomes cumbersome for more extensive modifications. In
945 addition, a recompilation and relinking of the main program is
946 necessary for any change of values. Alternatively, the changes can
947 therefore be collected in a file, for historical reasons
948 often called a ``card file'', where each line is a
949 character string defined in the same manner as above (without
951 The whole file can then be read and processed with a command\\
952 \cindent \texttt{pythia.readFile(fileName);}\\
953 As above, comments can be freely interspersed.
955 \subsection{Settings}
957 We distinguish four kinds of user-modifiable variables, by the way
958 they have to be stored:
960 \item A \texttt{Flag} is an on/off switch, and is stored as a
962 \item A \texttt{Mode} corresponds to an enumeration of
963 separate options, and is stored as an \texttt{int}.
964 \item A \texttt{Parm} --- short for parameter --- takes a continuum
965 of values, and is stored as a \texttt{double}.
966 \item A \texttt{Word} is a text string (with no embedded blanks)
967 and is stored as as a \texttt{string}.
969 Collectively the four above kinds of variables are called
970 settings. Not surprisingly, the class that stores them
971 is called \texttt{Settings}.
973 Each variable stored in \texttt{Settings} is associated
974 with a few pieces of information. These are:
977 The variable name, of the form \texttt{class:name} (or
978 \texttt{file:name}, or \texttt{task:name}, usually these agree), e.g.
979 \texttt{TimeShower:pTmin}.
981 The default value, set in the original declaration, and intended
982 to represent a reasonable choice. This value
983 is not user modifiable.
985 The current value. During construction of the \texttt{Settings}
986 object, this value is set equal to the default value. It can
987 subsequently be modified, e.g.\ by the
988 \texttt{pythia.readString()} or \texttt{pythia.readFile()} methods
989 discussed above. During the \texttt{pythia.init()} initialisation
990 this value will be stored as a local copy in the class(es) where it
991 is used, and thereby also control the subsequent generation.
993 An allowed range of values, represented by meaningful minimum and
994 maximum values. This has no sense for a flag or a word, is usually
995 rather well-defined for a mode, but less so for a parameter. Either
996 of the minimum and maximum may be left free, giving an open-ended
997 range. Often the allowed range exaggerates the uncertainty in our
998 current knowledge, so as not to restrict too much what the user can
999 do. All the same, this information should not be modified by the
1003 Technically, the \texttt{Settings} class is implemented with the help
1004 of four separate maps, one for each kind of variable, with the name
1005 used as key. The default values are taken from the \texttt{.xml}
1006 files in the \texttt{xmldoc} subdirectory. The \texttt{Settings} class
1007 is purely static, i.e.\ exists only as one global copy, that you can
1008 interact with directly by \texttt{Settings::command(argument)}.
1009 However, a \texttt{settings} object is a public member of the
1010 \texttt{Pythia} class, so an alternative notation would be
1011 \texttt{pythia.settings.command(argument)}. As already mentioned,
1012 for input the \texttt{pythia.readString(...)} method is to be preferred,
1013 since it also can handle particle data. A typical example would be\\
1014 \cindent\texttt{pythia.readString("TimeShower:pTmin = 1.0");}
1016 You may obtain a listing of all variables in the database by calling\\
1017 \cindent \texttt{pythia.settings.listAll();}\\
1018 The listing is strictly alphabetical, which at least means that names
1019 in the same area are kept together, but otherwise may not be so
1020 well-structured: important and unimportant ones will appear mixed.
1021 A useful alternative is\\
1022 \cindent \texttt{pythia.settings.listChanged();}\\
1023 which will only print out a list of
1024 those variables that differ from their defaults.
1026 \subsection{Processes}
1028 All internal processes available in \textsc{Pythia}~8
1029 can be switched on and off via the ordinary settings machinery
1030 just discussed, using flags of the generic type
1031 \texttt{ProcessGroup:ProcessName}. A complete list of processes
1032 currently implemented is given in Table~\ref{processes}. By
1033 default all processes are off. A whole group can be turned on by a
1034 \texttt{ProcessGroup:all = on} command, then overriding the individual
1038 \caption{Currently implemented processes, complete with respect to
1039 groups, but with some individual processes missing for lack of space
1040 (represented by ``...'').
1041 In the names, a ``2'' separates initial and final state, an ``(s:X)'',
1042 ``(t:X)'' or ``(l:X)'' occasionally appends info on an $s$- or
1043 $t$-channel- or loop-exchanged particle $X$.
1044 \protect\label{processes}}
1047 \begin{tabular}{|l|l|@{\protect\rule[-1mm]{0mm}{6mm}}}
1049 ProcessGroup & ProcessName\\
1051 SoftQCD & minBias,elastic, singleDiffractive,\\
1052 & doubleDiffractive\\
1054 HardQCD & gg2gg, gg2qqbar, qg2qg, qq2qq, qqbar2gg,\\
1055 & qqbar2qqbarNew, gg2ccbar, qqbar2ccbar,\\
1056 & gg2bbbar, qqbar2bbbar\\
1058 PromptPhoton & qg2qgamma, qqbar2ggamma, gg2ggamma,\\
1059 & ffbar2gammagamma, gg2gammagamma\\
1061 WeakBosonExchange & ff2ff(t:gmZ), ff2ff(t:W)\\
1063 WeakSingleBoson & ffbar2gmZ, ffbar2W, ffbar2ffbar(s:gm)\\
1065 WeakDoubleBoson & ffbar2gmZgmZ, ffbar2ZW, ffbar2WW\\
1067 WeakBosonAndParton & qqbar2gmZg, qg2gmZq, ffbar2gmZgm, fgm2gmZf\\
1068 & qqbar2Wg, qg2Wq, ffbar2Wgm, fgm2Wf\\
1070 Charmonium & gg2QQbar[3S1(1)]g, qg2QQbar[3PJ(8)]q, \ldots\\
1072 Bottomonium & gg2QQbar[3S1(1)]g, gg2QQbar[3P2(1)]g, \ldots\\
1074 Top & gg2ttbar, qqbar2ttbar, qq2tq(t:W), \\
1075 & ffbar2ttbar(s:gmZ), ffbar2tqbar(s:W) \\
1077 \multicolumn{2}{|l|@{\protect\rule[-1mm]{0mm}{6mm}}}%
1078 {FourthBottom, FourthTop, FourthPair \textrm{(fourth generation)}} \\
1080 HiggsSM & ffbar2H, gg2H, ffbar2HZ, ff2Hff(t:WW), \ldots\\
1082 HiggsBSM & \textrm{h, H and A as above, charged Higgs, pairs}\\
1084 SUSY & qqbar2chi0chi0 \textrm{(not yet completed)}\\
1086 NewGaugeBoson & ffbar2gmZZprime, ffbar2Wprime, ffbar2R0\\
1088 LeftRightSymmmetry & ffbar2ZR, ffbar2WR, ffbar2HLHL, \ldots\\
1090 LeptoQuark & ql2LQ, qg2LQl, gg2LQLQbar, qqbar2LQLQbar\\
1092 ExcitedFermion & dg2dStar, qq2uStarq, qqbar2muStarmu, \ldots\\
1094 ExtraDimensionsG* & gg2G*, qqbar2G*, \ldots\\
1100 Note that processes in the \texttt{SoftQCD} group are of a kind
1101 that cannot be input via the LHA, while essentially all other kinds
1104 Each process is assigned an integer code. This code is not used in
1105 the internal administration of events; it is only intended to allow
1106 a simpler user separation of different processes. Also the process
1107 name is available, as a string.
1109 For many processes it makes sense to apply phase space cuts. The ones
1110 currently available (in the \texttt{Settings} database) in particular
1113 \item \texttt{PhaseSpace:mHatMin, PhaseSpace:mHatMax} :
1114 the range of invariant masses of the scattering process.
1115 \item \texttt{PhaseSpace:pTHatMin, PhaseSpace:pTHatMax} :
1116 the range of transverse momenta in the rest frame of the
1117 process for $2 \to 2$ and $2 \to 3$ processes (for each of the
1120 In addition, for any resonance with a Breit-Wigner mass distribution,
1121 the allowed mass range of that particle species is taken into
1122 account, both for $2 \to 1$, $2 \to 2$ and $2 \to 3$ processes,
1123 thereby providing a further cut possibility. Note that the
1124 \texttt{SoftQCD} processes do not use any cuts but generate their
1125 respective cross sections in full.
1127 \subsection{Particle data}
1129 The following particle properties are stored in the
1130 \texttt{ParticleDataTable} class for a given PDG particle identity code
1131 \texttt{id}, here presented by the method used to access this property:
1133 \item \texttt{name(id)} :
1134 particle and antiparticle names are stored separately,
1135 the sign of \texttt{id} determines which of the two is returned, with
1136 ``void'' used to indicate the absence of an antiparticle.
1137 \item \texttt{hasAnti(id)} :
1138 \texttt{bool} whether a distinct antiparticle exists or not.
1139 \item \texttt{spinType(id)} : $2 s + 1$ for particles with defined spin,
1141 \item \texttt{chargeType(id)} :
1142 three times the charge (to make it an integer); can also be read as a
1143 \texttt{double charge(id) = chargeType(id)/3}.
1144 \item \texttt{colType(id)} :
1145 the colour type, with 0 uncoloured, 1 triplet, $-1$ antitriplet
1147 \item \texttt{m0(id)} :
1148 the nominal mass $m_0$ (in GeV).
1149 \item \texttt{mWidth(id)} :
1150 the width $\Gamma$ of the Breit-Wigner mass distribution (in GeV).
1151 \item \texttt{mMin(id), mMax(id)} :
1152 the allowed mass range generated by the Breit-Wigner,
1153 $m_{\mathrm{min}} < m < m_{\mathrm{max}}$ (in GeV).
1154 \item \texttt{tau0(id)} :
1155 the nominal proper lifetime $\tau_0$ (in mm/$c$).
1156 \item \texttt{constituentMass(id)} :
1157 the constituent mass for a quark, hardcoded as
1158 $m_{\mathrm{u}} = m_{\mathrm{d}} = 0.325$, $m_{\mathrm{s}} = 0.50$,
1159 $m_{\mathrm{c}} = 1.60$ and $m_{\mathrm{b}} = 5.0$ GeV, for a diquark
1160 the sum of quark constituent masses, and for everything else the same
1161 as the ordinary mass.
1162 \item \texttt{mRun(id, massScale)} : the running mass for quarks,
1163 else the same as the nominal mass.
1164 \item \texttt{mayDecay(id)} :
1165 a flag telling whether a particle species may decay or not, offering
1166 the main user switch (whether a given particle of this kind then
1167 actually will decay also depends on other flags in the
1168 \texttt{ParticleDecays} class).
1170 Similar methods can also be used to set most of these properties.
1172 Each particle kind in the \texttt{ParticleDataTable} also has a
1173 a vector of \texttt{DecayChannel}s associated with it. The following
1174 properties are stored for each decay channel:
1176 \item \texttt{onMode()} :
1177 whether a channel is on (1) or off (0), or on only for particles
1178 (2) or antiparticles (3).
1179 \item \texttt{bRatio()} :
1180 the branching ratio.
1181 \item \texttt{meMode()} :
1182 the mode of processing this channel, possibly with
1183 matrix-element information; 0 gives isotropic phase space.
1184 \item \texttt{multiplicity()} :
1185 the number of decay products in a channel, at most 8.
1186 \item \texttt{product(i)} :
1187 a list of the decay products, 8 products $0 \leq $\texttt{i}$ < 8$,
1188 with trailing unused ones set to 0.
1191 The original particle data and decay table is read in from the
1192 \texttt{ParticleData.xml} file.
1194 The \texttt{ParticleDataTable} class is purely static, i.e. exists as
1195 one global copy, that you can interact directly with by
1196 \texttt{ParticleDataTable::command(argument)}. However, a
1197 \texttt{particleData} object of the \texttt{ParticleDataTable} class
1198 is a public member of the \texttt{Pythia} class, which offers an
1199 alternatively notation. As already mentioned, for input the
1200 \texttt{pythia.readString(string)} method is to be preferred, since it
1201 also can handle settings.
1203 It is only the form of the \texttt{string} that needs to be specified
1204 slightly differently than for settings, as\\
1205 \cindent \texttt{id:property = value}.\\
1206 The \texttt{id} part is the standard PDG particle code, i.e.\ a number,
1207 and \texttt{property} is one of the ones already described above,
1208 with a few minor differences: \texttt{name}, \texttt{antiName},
1209 \texttt{spinType}, \texttt{chargeType}, \texttt{colType}, \texttt{m0},
1210 \texttt{mWidth}, \texttt{mMin}, \texttt{mMax}, \texttt{tau0},
1211 \texttt{mayDecay}, \texttt{isResonance}, \texttt{isVisible},
1212 \texttt{doExternalDecay}, and \texttt{doForceWidth}. As before, several
1213 commands can be stored as separate lines in a file, say\\
1214 \cindent \texttt{111:name = piZero ! normal notation pi0}\\
1215 \cindent \texttt{3122:mayDecay = false ! Lambda0 stable}\\
1216 \cindent \texttt{431:tau0 = 0.15 ! D\_s proper lifetime}\\
1217 and then be read with \texttt{pythia.readFile(fileName)}.
1219 For major changes of the properties of a particle, the above
1220 one-at-a-time changes can become rather cumbersome. Therefore
1221 a few extended input formats are available, where a whole
1222 set of properties can be given after the equal sign, separated
1223 by blanks and/or by commas. One line like\\
1224 \cindent \texttt{id:all = name antiName spinType chargeType %
1225 colType m0 mWidth mMin mMax tau0}\\
1226 replaces all the current information on the particle itself, but
1227 keeps its decay channels, if any, while using \texttt{new} instead
1228 of \texttt{all} also removes any previous decay channels. (The
1229 flags \texttt{mayDecay}, \texttt{isResonance}, \texttt{isVisible},
1230 \texttt{doExternalDecay}, and \texttt{doForceWidth} are in either
1231 case reset to their defaults and would have to be changed separately.)
1233 In order to change the decay data, the decay channel number needs
1234 to be given right after the particle number, i.e. the command form
1236 \cindent \texttt{id:channel:property = value}.\\
1237 Recognised properties are \texttt{onMode}, \texttt{bRatio},
1238 \texttt{meMode} and \texttt{products}, where the latter expects a
1239 list of all the decay products, separated by blanks, up until the
1240 end of the line, or until a non-number is encountered.
1241 The property \texttt{all} will replace all the information on the
1243 \cindent \texttt{id:channel:all = onMode bRatio meMode products }\\
1244 To add a new channel at the end, use\\
1245 \cindent \texttt{id:addChannel = onMode bRatio meMode products } \\
1246 To remove all existing channels and force decays into one new channel,
1248 \cindent \texttt{id:oneChannel = onMode bRatio meMode products } \\
1249 A first \texttt{oneChannel} command could be followed by several
1250 subsequent \texttt{addChannel} ones, to build up a completely new decay
1251 table for an existing particle.\\
1252 It is currently not possible to remove a channel selectively, but setting
1253 its branching ratio vanishing is as effective.
1255 Often one may want to allow only a specific subset of decay channels
1256 for a particle. This can be achieved e.g.\ by a repeated use of
1257 \texttt{id:channel:onMode} commands, but there also is a set of commands
1258 that initiates a loop over all decay channels and allows a matching to be
1259 carried out. The \texttt{id:onMode} command can switch \texttt{on} or
1260 \texttt{off} all channels. The \texttt{id:onIfAny} and \texttt{id:offIfAny}
1261 will switch on/off all channels that contain any of the enumerated
1262 particles. For instance\\
1263 \cindent \texttt{23:onMode = off}\\
1264 \cindent \texttt{23:onIfAny = 1 2 3 4 5}\\
1265 first switches off all $\mathrm{Z}^0$ decay modes and then switches
1266 back on any that contains one of the five lighter quarks. Other
1267 methods are \texttt{id:onIfAll} and \texttt{id:offIfAll}, and
1268 \texttt{id:onIfMatch} and \texttt{id:offIfMatch},
1269 where all the enumerated products must be present for a decay channel
1270 to be switched on/off. The difference is that the former two allow further
1271 non-matched particles in a decay channel while the latter two do not.
1272 There are also further methods to switch on channels selectively either
1273 for the particle or for the antiparticle.
1275 When a particle is to be decayed, the branching ratios of the allowed
1276 channels are always rescaled to unit sum. There are also methods for
1277 by-hand rescaling of branching ratios.
1279 You may obtain a listing of all the particle data by calling\\
1280 \cindent \texttt{pythia.particleData.listAll()}.\\
1281 The listing is by increasing \texttt{id} number. To list only those
1282 particles that have been changed, instead use\\
1283 \cindent \texttt{pythia.particleData.listChanged()}.\\
1284 To list only one specific particle \texttt{id}, use \texttt{list(id)}.
1285 It is also possible to \texttt{list} a \texttt{vector<int>} of
1288 \section{Links to external programs \label{sec:external}}
1290 While \textsc{Pythia}~8 itself is self-contained and can be
1291 run without reference to any external library, often one does
1292 want to make use of other programs that are specialised on some aspect
1293 of the generation process. The HTML/PHP documentation accompanying the
1294 code contains full information on how the different links should be set
1295 up. Here the purpose is mainly to point out the possibilities that
1298 \subsection{The Les Houches interface}
1300 The Les Houches Accord for user processes (LHA) \cite{lha} is the
1301 standard way to input parton-level information from a
1302 matrix-elements-based generator into \textsc{Pythia}. The conventions
1303 for which information should be stored has been defined in a Fortran
1304 context, as two commonblocks. Here a C++ equivalent is defined,
1305 as two separate classes.
1307 The \texttt{LHAinit} and \texttt{LHAevnt} classes are base classes,
1308 containing reading and printout methods, plus a pure virtual
1309 method \texttt{set()} each. Derived classes have to provide these two
1310 virtual methods to do the actual work. Currently the only examples
1311 are for reading information at runtime from the respective
1312 Fortran commonblock or for reading it from a Les Houches Event File
1315 The \texttt{LHAinit} class stores information equivalent to the
1316 \texttt{/HEPRUP/} commonblock, as required to initialise the
1317 event-generation chain.
1318 The \texttt{LHAevnt} class stores information equivalent to the
1319 \texttt{/HEPEUP/} commonblock, as required to hand in the next
1320 parton-level configuration for complete event generation.
1322 The \texttt{LHAinitFortran} and \texttt{LHAevntFortran} are two
1323 derived classes, containing \texttt{set()} members that read the
1324 respective LHA Fortran commonblock for initialisation and event
1325 information. This can be used for a runtime link to a Fortran
1326 library. As an example, an interface is provided to the
1327 \textsc{Pythia}~6.4 process library.
1329 The \texttt{LHAinitLHEF} and \texttt{LHAevntLHEF} are two
1330 other derived classes, that can read a file with initialisation and
1331 event information, assuming that the file has been written in the
1332 LHEF format. You do not need to declare these classes yourself,
1333 since a shortcut is provided by the \texttt{pythia.init(fileName)}
1336 If you create \texttt{LHAinit} and \texttt{LHAevnt} objects yourself,
1337 pointers to those should be handed in with the \texttt{init(...)} call,
1338 then of the form \texttt{pythia.init(LHAinit*, LHAevnt*)}.
1340 \subsection{Semi-internal processes and resonances}
1342 When you implement new processes via the Les Houches Accord you do all
1343 flavour, colour and phase-space selection externally, before your
1344 process-level events are input for further processing by \textsc{Pythia}.
1345 However, it is also possible to implement a new process in exactly the
1346 same way as the internal \textsc{Pythia} ones, thus making use of the
1347 internal phase-space selection machinery to sample an externally provided
1348 cross-section expression.
1350 The matrix-element information has to be put in a new class that derives
1351 from one of the existing classes, \texttt{Sigma1Process} for $2 \to 1$
1352 processes, \texttt{Sigma2Process} for $2 \to 2$ ones, and
1353 \texttt{Sigma3Process} for $2 \to 3$ ones, which in their turn derive
1354 from the \texttt{SigmaProcess} base class. Note that \texttt{Pythia} is
1355 rather good at handling the phase space of $2 \to 1$ and $2 \to 2$
1356 processes, is more primitive for $2 \to 3$ ones and does not at all address
1357 higher multiplicities. This limits the set of processes that you can
1358 implement in this framework. The produced particles may be resonances,
1359 however, so it is possible to end up with bigger "final" multiplicities
1360 through sequential decays, and to include further matrix-element weighting
1363 In your new class you have to implement a number of methods. Chief among
1364 them is one to return the matrix-element weight for an already specified
1365 kinematics configuration and another one to set up the final-state flavours
1366 and colour flow of the process. Further methods exist, some of more
1367 informative character, such as providing the name of the process.
1368 Should you actually go ahead, it is strongly recommended to shop around
1369 for a similar process that has already been implemented, and to use that
1370 existing code as a template.
1372 Once a class has been written, a pointer of type \texttt{SigmaProcess*}
1373 to a \texttt{new} instance of your class needs to be created in the main
1374 program, and handed in with the \texttt{pythia.setSigmaPtr(...)} method.
1375 {}From there on the process will be handled on equal footing with internally
1376 implemented processes.
1378 If your new process introduces a new particle you have to add it and its
1379 decay channels to the particle database, as already explained. This only
1380 allows for a fixed width and fixed branching ratios, however, with only
1381 some minor generalisations. To obtain a dynamical calculation, where the
1382 width and the branching ratios can vary as a function of the currently
1383 chosen mass, you must also create a new class for it that derives from the
1384 \texttt{ResonanceWidths} class. In it you have to implement a method
1385 that returns the partial width for each of the possible decay channels.
1386 The structure is simpler than for the \texttt{SigmaProcess} case, but
1387 again it may be convenient to use a similar existing resonance as a
1388 template. You then hand in a pointer to an instance of this new class
1389 with the \texttt{pythia.setResonancePtr(...)} method.
1391 \subsection{Parton distribution functions}
1393 The \texttt{PDF} class is the base class for all parton distribution
1394 function parametrisations, from which specific \texttt{PDF} classes
1395 are derived. Currently the selection of sets that comes with the
1396 program is very limited; for protons only CTEQ 5L (default) and
1397 GRV 94L are available. However, a built-in interface to the
1398 \textsc{LhaPdf} library \cite{lhapdf} allows a much broader selection,
1399 if only \textsc{LhaPdf} is linked together with \textsc{Pythia}.
1401 Should this not be enough, it is possible to write your own class
1402 derived from the \texttt{PDF} base class, wherein you implement the
1403 \texttt{xfUpdate(...)} member to do the actual updating of PDFs.
1404 Once you have created two distinct \texttt{PDF} objects, \texttt{pdfA}
1405 and \texttt{pdfB}, you should supply pointers to these as arguments in
1406 a \texttt{pythia.setPDFPtr(pdfA*, pdfB*)} call.
1408 A word of warning: to switch to a new PDF set implies that a complete
1409 retuning of the generator may be required, since the underlying-event
1410 activity from multiple interactions and parton showers is changed. There
1411 is an option that allows a replacement of the PDF for the hard process
1412 only, so that this is not required. Inconsistent but convenient.
1414 \subsection{External decay packages}
1416 While \texttt{Pythia} is set up to handle any particle decays,
1417 decay products are often (but not always) distributed isotropically
1418 in phase space, i.e.\ polarisation effects and nontrivial matrix
1419 elements usually are neglected in \textsc{Pythia}. Especially for the
1420 $\tau$ lepton and for some $\mathrm{B}$ mesons it is therefore common
1421 practice to rely on dedicated decay packages \cite{tauola, evtgen}.
1423 To this end, \texttt{DecayHandler} is a base class for the external
1424 handling of decays. The user-written derived class is called if a
1425 pointer to it has been given with the
1426 \texttt{pythia.setDecayPtr(DecayHandler*, vector<int>)} method.
1427 The second argument to this method should contain the \texttt{id}
1428 codes of all the particles that should be decayed by the external
1429 program. It is up to the author of the derived class to send different
1430 of these particles on to separate packages, if so desired.
1432 The \texttt{decay(...)} method in the user-written \texttt{DecayHandler}
1433 class should do the decay, or return \texttt{false} if it fails. In the
1434 latter case \texttt{Pythia} will try to do the decay itself. Thus one
1435 may implement some decay channels externally and leave the rest for
1436 \texttt{Pythia}, assuming the \texttt{Pythia} decay tables are adjusted
1439 \subsection{User hooks}
1441 Sometimes it may be convenient to step in during the generation process:
1442 to modify the built-in cross sections, to veto undesirable events or
1443 simply to collect statistics at various stages of the evolution. There is
1444 a base class \texttt{UserHooks} that gives you this access at a few
1445 selected places. This class in itself does nothing; the idea is that you
1446 should write your own derived class for your task. A few very simple
1447 derived classes come with the program, mainly as illustration.
1449 There are four distinct sets of routines. Ordered by increasing
1450 complexity, rather than by their appearance in the event-generation
1453 \item Ones that gives you access to the event record in between the
1454 process-level and parton-level steps, or in between the parton-level
1455 and hadron-level ones. You can study the event record and decide whether
1457 \item Ones that allow you to set a scale at which the combined
1458 multiple-interactions, initial-state and final-state parton-shower
1459 downwards evolution in $p_{\perp}$ is temporarily interrupted, so the
1460 event can be studied and either vetoed or allowed to continue the
1462 \item Similar ones that instead gives you access after the first few
1463 parton-shower branchings of the hardest subprocess.
1464 \item Ones that gives you access to the properties of the trial
1465 hard process, so that you can modify the internal \textsc{Pythia}
1466 cross section by your own correction factors.
1469 \subsection{Random-number generators}
1471 \texttt{RndmEngine} is a base class for the external handling of
1472 random-number generation. The user-written derived class is called
1473 if a pointer to it has been handed in with the
1474 \texttt{pythia.setRndmEnginePtr(RndmEngine*)} method.
1475 Since the default Marsaglia-Zaman algorithm is quite good, there is
1476 absolutely no physics reason to replace it, but this may still be
1477 required for consistency with other program elements in big
1478 experimental frameworks.
1480 \subsection{The \textsc{HepMC} event format}
1482 The \textsc{HepMC} event format \cite{hepmc} is a standard format
1483 for the storage of events in several major experiments. The translation
1484 from the \textsc{Pythia}~8 \texttt{Event} format should be done
1485 after \texttt{pythia.next()} has generated an event. Therefore there
1486 is no need for a tight linkage, but only to call the\\
1487 \texttt{HepMC::I\_Pythia8::fill\_next\_event( pythia.event, hepmcevt )}\\
1488 conversion routine from the main program written by the user.
1489 Version 1 of \textsc{HepMC} makes use of the \textsc{CLHep} library
1490 \cite{clhep} for four-vectors, while version 2 is standalone; this
1491 requires some adjustments in the interface code based on which version
1494 \subsection{SUSY parameter input}
1496 \textsc{Pythia}~8 does not contain a machinery for calculating
1497 masses and couplings of supersymmetric particles from some small set
1498 of input parameters. Instead the SUSY Les Houches Accord (SLHA)
1499 \cite{slha} is used to provide this information, as calculated by
1500 some external program. You need to supply the name of the file where
1501 the SLHA information is stored, in an appropriate setting, and then
1502 the rest is taken care of automatically. (Or at least will be, once
1503 SUSY processes are implemented.)
1505 \subsection{Parton showers}
1507 It is possible to replace the existing timelike and/or spacelike showers
1508 in the program by your own. This is truly for experts, since it requires
1509 a rather strict adherence to a wide set of rules. These are described
1510 in detail in the HTML/PHP documentation accompanying the code.
1511 The \textsc{Vincia} program \cite{vincia} offers a first example of
1512 a plug-in of an external (timelike) shower.
1514 \section{Getting Going \label{sec:how-to}}
1516 After you download the \texttt{pythia8100.tgz} (or later) package
1517 from the \textsc{Pythia} webpage,\\
1518 \cindent \texttt{http://www.thep.lu.se/}$\sim$%
1519 \texttt{torbjorn/Pythia.html}\\
1520 you can unpack it with \texttt{tar xvfz pythia8100.tgz}, into a new
1521 subdirectory \texttt{pythia8100}. The rest of the installation procedure
1522 is described in the \texttt{README} file in that directory.
1523 It is assumed you are on a Linux system; so far there is hardly any
1524 multiplatform support.
1526 After this, the main program is up to the user to write. A worksheet
1527 (found on the webpage) takes you through as step-by-step procedure,
1528 and sample main programs are provided in the \texttt{examples}
1529 subdirectory. These programs are included to serve as inspiration when
1530 starting to write your own program, by illustrating the principles
1533 The information available if you open
1534 \texttt{htmldoc/Welcome.html} in your web browser will help you
1535 explore the program possibilities further. If you install the
1536 \texttt{phpdoc} subdirectory under a web server you will also get
1537 extra help to build a file of commands to the \texttt{Settings} and
1538 \texttt{ParticleDataTable} machineries, to steer the execution of
1541 Such "cards files" are separate from the main programs proper, so that
1542 minor changes can be made without any recompilation. It is then
1543 convenient to collect in the same place some run parameters, such as
1544 the number of events to generate, that could be used inside the
1545 main program. Therefore some such have been predefined, e.g.\
1546 \texttt{Main:numberOfEvents}. Whether they actually are used is up to
1547 the author of a main program to decide.
1549 \section{Outlook \label{sec:outlook}}
1551 As already explained in the introduction, \textsc{Pythia}~8.1 is
1552 not yet a complete replacement of \textsc{Pythia}~6.4, but it is
1553 getting there, and already contains some new features not found
1554 elsewhere. In many cases the quality of the physics should be
1555 comparable between the two versions, but obviously the objective
1556 is that soon \textsc{Pythia}~8 should offer the overall better
1557 alternative. This will occur by further improvements of the
1558 existing framework and by the gradual addition of new features.
1562 The support and kind hospitality of the SFT group at CERN is
1563 gratefully acknowledged by TS. Mikhail Kirsanov has developed
1564 the configure files, the makefiles and the interface to
1565 \textsc{HepMC}, and made several valuable suggestions. Ben Lloyd
1566 has written the PHP webpage framework. Bertrand Bellenot has provided
1567 a simple makefile for Win32/NMAKE. Marc Montull has helped write
1568 the extended Higgs sector. SM and PS are supported by Fermi Research
1569 Alliance, LLC, under Contract No.~DE-AC02-07CH11359 with the United
1570 States Department of Energy. This work was supported in part by
1571 the European Union Marie Curie Research Training Network MCnet
1572 under contract MRTN-CT-2006-035606.
1574 \begin{thebibliography}{99}
1577 T. Sj\"ostrand, Computer Physics Commun. {\bf 27} (1982) 243,
1578 {\bf 28} (1983) 229, {\bf 39} (1986) 347;\\
1579 T. Sj\"ostrand and M. Bengtsson, Computer Physics Commun.
1582 \bibitem{pythiaearly}
1583 H.-U. Bengtsson, Computer Physics Commun. {\bf 31} (1984) 323;\\
1584 H.-U. Bengtsson and G. Ingelman, Computer Physics Commun. {\bf 34}
1586 H.-U. Bengtsson and T. Sj\"ostrand, Computer Physics Commun.
1587 {\bf 46} (1987) 43;\\
1588 T. Sj\"ostrand, Computer Physics Commun. {\bf 82} (1994) 74
1590 \bibitem{pythiasixone}
1591 T. Sj\"ostrand, P. Ed\'en, C. Friberg, L. L\"onnblad, G. Miu,
1592 S. Mrenna and E. Norrbin, Computer Physics Commun. {\bf 135} (2001) 238
1594 \bibitem{pythiasixfour}
1595 T. Sj\"ostrand, S. Mrenna and P. Skands, JHEP {\bf 05} (2006) 026
1598 \bibitem{pythiaseven}
1599 L. L\"onnblad, Computer Physics Commun. {\bf 118} (1999) 213;\\
1600 M. Bertini, L. L\"onnblad and T. Sj\"ostrand,
1601 Computer Physics Commun. {\bf 134} (2001) 365
1604 see webpage \texttt{http://www.thep.lu.se/ThePEG/}
1607 S. Gieseke, A. Ribon, M.H. Seymour, P. Stephens and B.R. Webber,
1608 JHEP {\bf 02} (2004) 005;\\
1609 see webpage \texttt{http://hepforge.cedar.ac.uk/herwig/}
1612 E. Boos et al., in the Proceedings of the Workshop on Physics
1614 Les Houches, France, 21 May - 1 Jun 2001 [hep-ph/0109068]
1617 J. Alwall et al., Computer Physics Comm. {\bf 176} (2007) 300
1620 M.R. Whalley, D. Bourilkov and R.C. Group, in `HERA and the LHC',\\
1621 eds. A. De Roeck and H. Jung, CERN-2005-014, p. 575 [hep-ph/0508110]
1624 T. Sj\"ostrand and P. Skands, Eur. Phys. J {\bf C39} (2005) 129
1626 \bibitem{newremnants}
1627 T. Sj\"ostrand and P. Skands, JHEP {\bf 03} (2004) 053
1630 T. Sj\"ostrand and M. van Zijl, Phys. Rev. {\bf D36} (1987) 2019
1633 P. Skands and D. Wicke, Eur. Phys. J. {\bf C52} (2007) 133
1635 \bibitem{lundreview}
1636 B. Andersson, G. Gustafson, G. Ingelman and T. Sj\"ostrand,
1637 Phys. Rep. {\bf 97} (1983) 31
1640 Particle Data Group, W.-M. Yao et al., J. Phys. {\bf G33} (2006) 1
1642 \bibitem{boseeinstein}
1643 L. L\"onnblad and T. Sj\"ostrand, Eur. Phys. J. {\bf C2} (1998) 165
1646 M. Dobbs and J.B. Hansen, Computer Physics Comm. {\bf 134} (2001) 41
1649 P. Skands et al., JHEP {\bf 07} (2004) 036
1652 S. Jadach, Z. W\c{a}s, R. Decker and J.H. K\"uhn,
1653 Computer Physics Commun. {\bf 76} (1993) 361
1656 D.J. Lange, Nucl. Instrum. Meth. {\bf A462} (2001) 152
1659 see webpage \texttt{http://proj-clhep.web.cern.ch/proj-clhep/}
1662 W.T. Giele, D.A. Kosower and P.Z. Skands, arXiv:0707.3652
1664 \end{thebibliography}