]>
Commit | Line | Data |
---|---|---|
63ba5337 | 1 | %% Computer Physics Communications class file, slightly modified |
2 | %% for reduced inter-paragraph and inter-section spacing. | |
3 | \documentclass{elsartmod} | |
4 | ||
5 | % Include graphics package. | |
6 | \usepackage{axodraw} | |
7 | ||
8 | % Standardised indentation. | |
9 | \newcommand{\cindent}{\hspace*{10mm}~} | |
10 | ||
11 | %Vertical positioning of page | |
12 | %\setlength{\topmargin}{20mm} | |
13 | ||
14 | \begin{document} | |
15 | \begin{frontmatter} | |
16 | ||
17 | \begin{flushright} | |
18 | arXiv:0710.3820\\ | |
19 | CERN-LCGAPP-2007-04\\ | |
20 | LU TP 07-28\\ | |
21 | FERMILAB-PUB-07-512-CD-T\\ | |
22 | October 2007\\ | |
23 | \end{flushright} | |
24 | ||
25 | \title{A Brief Introduction to PYTHIA 8.1} | |
26 | ||
27 | \author[a,b]{Torbj\"orn Sj\"ostrand\thanksref{author}}, | |
28 | \author[c]{Stephen Mrenna}, | |
29 | \author[a,c]{Peter Skands} | |
30 | ||
31 | \thanks[author]{Corresponding author, e-mail: torbjorn@thep.lu.se} | |
32 | ||
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, | |
37 | IL 60510, USA} | |
38 | ||
39 | \begin{abstract} | |
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. | |
53 | \begin{flushleft} | |
54 | %Insert your suggested PACS number here | |
55 | PACS: 13.66.-a, 13.85.-t, 12.38.-t, 12.15.-y, 12.60.-i | |
56 | \end{flushleft} | |
57 | ||
58 | \begin{keyword} | |
59 | event generators, multiparticle production, | |
60 | parton showers, multiple interactions, hadronisation | |
61 | \end{keyword} | |
62 | ||
63 | \end{abstract} | |
64 | ||
65 | \dedicated{\rule{0mm}{8mm}Dedicated to the memory of\\[3mm] | |
66 | \textbf{\textit{\Large Hans-Uno Bengtsson}}\\[1mm] | |
67 | 1953 -- 2007\\ | |
68 | The father of PYTHIA} | |
69 | ||
70 | \end{frontmatter} | |
71 | ||
72 | \clearpage | |
73 | ||
74 | % Computer program descriptions should contain the following | |
75 | % PROGRAM SUMMARY. | |
76 | ||
77 | {\bf NEW VERSION PROGRAM SUMMARY} | |
78 | %Delete as appropriate. | |
79 | ||
80 | \begin{small} | |
81 | \noindent | |
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. | |
124 | \\ | |
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. | |
134 | \\ | |
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. | |
145 | \\ | |
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. | |
149 | \\ | |
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. | |
154 | \\ | |
155 | {\em Restrictions: depends on the problem studied}\\ | |
156 | %Describe any restrictions on the complexity of the problem here. | |
157 | \\ | |
158 | {\em Unusual features: none}\\ | |
159 | %Describe any unusual features of the program/problem here. | |
160 | \\ | |
161 | %{\em Additional comments:}\\ | |
162 | %Provide any additional comments here. | |
163 | % \\ | |
164 | {\em Running time: 10--1000 events per second, depending on | |
165 | process studied}\\ | |
166 | %Give an indication of the typical running time here. | |
167 | % \\ | |
168 | %{\em References:} | |
169 | %\begin{refnummer} | |
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. | |
174 | %\end{refnummer} | |
175 | ||
176 | \end{small} | |
177 | \clearpage | |
178 | ||
179 | % In program descriptions the main text of the paper is listed under | |
180 | % the heading LONG WRITE-UP. | |
181 | ||
182 | \hspace{1pc} | |
183 | {\bf LONG WRITE-UP} | |
184 | ||
185 | \section{Introduction} | |
186 | ||
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. | |
196 | ||
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. | |
204 | ||
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. | |
211 | ||
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. | |
216 | ||
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. | |
223 | ||
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. | |
236 | ||
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. | |
247 | ||
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 | |
262 | an outlook. | |
263 | ||
264 | \section{Physics Summary \label{sec:physics}} | |
265 | ||
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. | |
273 | ||
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, | |
278 | however. | |
279 | ||
280 | \subsection{Hard processes} | |
281 | ||
282 | Currently the program only works with $\mathrm{p}\mathrm{p}$, | |
283 | $\overline{\mathrm{p}}\mathrm{p}$, $\mathrm{e}^+\mathrm{e}^-$ | |
284 | and $\mu^+\mu^-$ | |
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. | |
288 | ||
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. | |
295 | ||
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 | |
300 | other. | |
301 | ||
302 | \subsection{Parton showers} | |
303 | ||
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. | |
309 | ||
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 | |
319 | as a whole. | |
320 | ||
321 | \subsection{Multiple interactions and beam remnants} | |
322 | ||
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 | |
333 | new framework. | |
334 | ||
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 | |
339 | included. | |
340 | ||
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. | |
345 | ||
346 | \subsection{Hadronisation} | |
347 | ||
348 | Hadronisation is based solely on the Lund string fragmentation | |
349 | framework \cite{lundreview}; older alternative descriptions have | |
350 | been left out. | |
351 | ||
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. | |
356 | ||
357 | The BE$_{32}$ model for Bose--Einstein effects \cite{boseeinstein} | |
358 | has been implemented, but is not on by default. | |
359 | ||
360 | \subsection{Other program components} | |
361 | ||
362 | Standardised procedures have been introduced to link the program | |
363 | to various external programs for specific tasks, see section | |
364 | \ref{sec:external}. | |
365 | ||
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. | |
369 | ||
370 | \section{Program Structure \label{sec:structure}} | |
371 | ||
372 | \subsection{Program flow} | |
373 | ||
374 | The physics topics that have to come together in a complete | |
375 | event generator can crudely be subdivided into three stages: | |
376 | \begin{enumerate} | |
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. | |
398 | \end{enumerate} | |
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. | |
402 | ||
403 | \begin{figure}[t] | |
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}} | |
440 | \SetWidth{2} | |
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) | |
447 | \SetWidth{1} | |
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) | |
470 | \Line(-160,50)(0,50) | |
471 | \LongArrow(0,50)(19,59) | |
472 | \end{picture} | |
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}} | |
480 | \hrulefill | |
481 | \end{figure} | |
482 | ||
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. | |
490 | ||
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. | |
501 | ||
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. | |
506 | ||
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. | |
510 | ||
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. | |
515 | ||
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. | |
519 | ||
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: | |
523 | \begin{itemize} | |
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. | |
527 | \end{itemize} | |
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. | |
533 | ||
534 | \subsection{Program files and documentation} | |
535 | ||
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. | |
540 | \begin{enumerate} | |
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. | |
546 | \end{enumerate} | |
547 | During compilation, related dependency files, \texttt{.d}, and | |
548 | compiled code, \texttt{.o} are created in the \texttt{tmp} | |
549 | subdirectory. | |
550 | ||
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. | |
564 | ||
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. | |
570 | ||
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. | |
580 | ||
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}. | |
590 | ||
591 | \subsection{Important warnings} | |
592 | ||
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. | |
598 | ||
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! | |
607 | ||
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. | |
611 | ||
612 | \section{Main Program and Event Information \label{sec:main}} | |
613 | ||
614 | \subsection{The \texttt{Pythia} class} | |
615 | ||
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. | |
619 | ||
620 | Firstly, at the top of the main program, the proper header file must | |
621 | be included:\\ | |
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 | |
630 | pick another one. | |
631 | ||
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. | |
647 | ||
648 | At this stage you can also optionally hook up with some external | |
649 | facilities, see section \ref{sec:external}. | |
650 | ||
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$) | |
658 | direction;\\ | |
659 | \cindent \texttt{pythia.init(idA, idB, eCM);}\\ | |
660 | is similar, but you specify the CM energy, and you are assumed | |
661 | in the rest frame;\\ | |
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; | |
669 | and finally\\ | |
670 | \cindent \texttt{pythia.init();}\\ | |
671 | will take its values from the beam specification stored in the | |
672 | \texttt{Settings} database. | |
673 | ||
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. | |
682 | ||
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 | |
689 | generated. | |
690 | ||
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}. | |
694 | ||
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). | |
708 | ||
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 | |
713 | warnings issued. | |
714 | ||
715 | \subsection{The event record} | |
716 | ||
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. | |
725 | ||
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. | |
735 | ||
736 | In this section, first the \texttt{Particle} methods are surveyed, | |
737 | and then the further aspects of the event record. | |
738 | ||
739 | \subsubsection{The particle} | |
740 | ||
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. | |
745 | ||
746 | The following properties are stored for each particle, listed by the | |
747 | member functions you can use to extract the information: | |
748 | \begin{itemize} | |
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()}. | |
774 | \item \texttt{m()} : | |
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$). | |
783 | \end{itemize} | |
784 | The same method names, with a value inserted between the brackets, | |
785 | set these quantities. | |
786 | ||
787 | In addition, a number of derived quantities can easily be obtained, | |
788 | but cannot be set, such as: | |
789 | \begin{itemize} | |
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()}. | |
805 | \end{itemize} | |
806 | ||
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: | |
813 | \begin{itemize} | |
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 | |
818 | to make an integer. | |
819 | \item \texttt{isCharged(), isNeutral()} : \texttt{bool}s for charged | |
820 | or not. | |
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. | |
825 | \end{itemize} | |
826 | ||
827 | \subsubsection{Other methods in the event record} | |
828 | ||
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()}. | |
833 | ||
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. | |
839 | ||
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. | |
845 | ||
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)''. | |
854 | ||
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. | |
863 | ||
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 | |
866 | ones do not clash. | |
867 | ||
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. | |
876 | ||
877 | \subsection{Other event information} | |
878 | ||
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. | |
884 | ||
885 | You can use \texttt{pythia.info.method()} to extract e.g.\ the | |
886 | following information: | |
887 | \begin{itemize} | |
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$ | |
900 | processes. | |
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. | |
910 | \end{itemize} | |
911 | ||
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. | |
915 | ||
916 | \section{Databases \label{sec:databases}} | |
917 | ||
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. | |
922 | ||
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}). | |
942 | ||
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 | |
950 | quotation marks). | |
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. | |
954 | ||
955 | \subsection{Settings} | |
956 | ||
957 | We distinguish four kinds of user-modifiable variables, by the way | |
958 | they have to be stored: | |
959 | \begin{enumerate} | |
960 | \item A \texttt{Flag} is an on/off switch, and is stored as a | |
961 | \texttt{bool}. | |
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}. | |
968 | \end{enumerate} | |
969 | Collectively the four above kinds of variables are called | |
970 | settings. Not surprisingly, the class that stores them | |
971 | is called \texttt{Settings}. | |
972 | ||
973 | Each variable stored in \texttt{Settings} is associated | |
974 | with a few pieces of information. These are: | |
975 | \begin{itemize} | |
976 | \item | |
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}. | |
980 | \item | |
981 | The default value, set in the original declaration, and intended | |
982 | to represent a reasonable choice. This value | |
983 | is not user modifiable. | |
984 | \item | |
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. | |
992 | \item | |
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 | |
1000 | user. | |
1001 | \end{itemize} | |
1002 | ||
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");} | |
1015 | ||
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. | |
1025 | ||
1026 | \subsection{Processes} | |
1027 | ||
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 | |
1035 | flags. | |
1036 | ||
1037 | \begin{table} | |
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}} | |
1045 | \vspace{2mm} | |
1046 | \texttt{ | |
1047 | \begin{tabular}{|l|l|@{\protect\rule[-1mm]{0mm}{6mm}}} | |
1048 | \hline | |
1049 | ProcessGroup & ProcessName\\ | |
1050 | \hline | |
1051 | SoftQCD & minBias,elastic, singleDiffractive,\\ | |
1052 | & doubleDiffractive\\ | |
1053 | \hline | |
1054 | HardQCD & gg2gg, gg2qqbar, qg2qg, qq2qq, qqbar2gg,\\ | |
1055 | & qqbar2qqbarNew, gg2ccbar, qqbar2ccbar,\\ | |
1056 | & gg2bbbar, qqbar2bbbar\\ | |
1057 | \hline | |
1058 | PromptPhoton & qg2qgamma, qqbar2ggamma, gg2ggamma,\\ | |
1059 | & ffbar2gammagamma, gg2gammagamma\\ | |
1060 | \hline | |
1061 | WeakBosonExchange & ff2ff(t:gmZ), ff2ff(t:W)\\ | |
1062 | \hline | |
1063 | WeakSingleBoson & ffbar2gmZ, ffbar2W, ffbar2ffbar(s:gm)\\ | |
1064 | \hline | |
1065 | WeakDoubleBoson & ffbar2gmZgmZ, ffbar2ZW, ffbar2WW\\ | |
1066 | \hline | |
1067 | WeakBosonAndParton & qqbar2gmZg, qg2gmZq, ffbar2gmZgm, fgm2gmZf\\ | |
1068 | & qqbar2Wg, qg2Wq, ffbar2Wgm, fgm2Wf\\ | |
1069 | \hline | |
1070 | Charmonium & gg2QQbar[3S1(1)]g, qg2QQbar[3PJ(8)]q, \ldots\\ | |
1071 | \hline | |
1072 | Bottomonium & gg2QQbar[3S1(1)]g, gg2QQbar[3P2(1)]g, \ldots\\ | |
1073 | \hline | |
1074 | Top & gg2ttbar, qqbar2ttbar, qq2tq(t:W), \\ | |
1075 | & ffbar2ttbar(s:gmZ), ffbar2tqbar(s:W) \\ | |
1076 | \hline | |
1077 | \multicolumn{2}{|l|@{\protect\rule[-1mm]{0mm}{6mm}}}% | |
1078 | {FourthBottom, FourthTop, FourthPair \textrm{(fourth generation)}} \\ | |
1079 | \hline | |
1080 | HiggsSM & ffbar2H, gg2H, ffbar2HZ, ff2Hff(t:WW), \ldots\\ | |
1081 | \hline | |
1082 | HiggsBSM & \textrm{h, H and A as above, charged Higgs, pairs}\\ | |
1083 | \hline | |
1084 | SUSY & qqbar2chi0chi0 \textrm{(not yet completed)}\\ | |
1085 | \hline | |
1086 | NewGaugeBoson & ffbar2gmZZprime, ffbar2Wprime, ffbar2R0\\ | |
1087 | \hline | |
1088 | LeftRightSymmmetry & ffbar2ZR, ffbar2WR, ffbar2HLHL, \ldots\\ | |
1089 | \hline | |
1090 | LeptoQuark & ql2LQ, qg2LQl, gg2LQLQbar, qqbar2LQLQbar\\ | |
1091 | \hline | |
1092 | ExcitedFermion & dg2dStar, qq2uStarq, qqbar2muStarmu, \ldots\\ | |
1093 | \hline | |
1094 | ExtraDimensionsG* & gg2G*, qqbar2G*, \ldots\\ | |
1095 | \hline | |
1096 | \end{tabular} | |
1097 | } | |
1098 | \end{table} | |
1099 | ||
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 | |
1102 | could. | |
1103 | ||
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. | |
1108 | ||
1109 | For many processes it makes sense to apply phase space cuts. The ones | |
1110 | currently available (in the \texttt{Settings} database) in particular | |
1111 | include | |
1112 | \begin{itemize} | |
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 | |
1118 | products). | |
1119 | \end{itemize} | |
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. | |
1126 | ||
1127 | \subsection{Particle data} | |
1128 | ||
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: | |
1132 | \begin{itemize} | |
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, | |
1140 | else 0. | |
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 | |
1146 | and 2 octet. | |
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). | |
1169 | \end{itemize} | |
1170 | Similar methods can also be used to set most of these properties. | |
1171 | ||
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: | |
1175 | \begin{itemize} | |
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. | |
1189 | \end{itemize} | |
1190 | ||
1191 | The original particle data and decay table is read in from the | |
1192 | \texttt{ParticleData.xml} file. | |
1193 | ||
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. | |
1202 | ||
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)}. | |
1218 | ||
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.) | |
1232 | ||
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 | |
1235 | becomes\\ | |
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 | |
1242 | channel, i.e.\\ | |
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, | |
1247 | use\\ | |
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. | |
1254 | ||
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. | |
1274 | ||
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. | |
1278 | ||
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 | |
1286 | \texttt{id}'s. | |
1287 | ||
1288 | \section{Links to external programs \label{sec:external}} | |
1289 | ||
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 | |
1296 | exist. | |
1297 | ||
1298 | \subsection{The Les Houches interface} | |
1299 | ||
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. | |
1306 | ||
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 | |
1313 | (LHEF) \cite{lhef}. | |
1314 | ||
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. | |
1321 | ||
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. | |
1328 | ||
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)} | |
1334 | command. | |
1335 | ||
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*)}. | |
1339 | ||
1340 | \subsection{Semi-internal processes and resonances} | |
1341 | ||
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. | |
1349 | ||
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 | |
1361 | in those decays. | |
1362 | ||
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. | |
1371 | ||
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. | |
1377 | ||
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. | |
1390 | ||
1391 | \subsection{Parton distribution functions} | |
1392 | ||
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}. | |
1400 | ||
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. | |
1407 | ||
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. | |
1413 | ||
1414 | \subsection{External decay packages} | |
1415 | ||
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}. | |
1422 | ||
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. | |
1431 | ||
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 | |
1437 | accordingly. | |
1438 | ||
1439 | \subsection{User hooks} | |
1440 | ||
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. | |
1448 | ||
1449 | There are four distinct sets of routines. Ordered by increasing | |
1450 | complexity, rather than by their appearance in the event-generation | |
1451 | sequence, they are: | |
1452 | \begin{itemize} | |
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 | |
1456 | to veto this event. | |
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 | |
1461 | evolution. | |
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. | |
1467 | \end{itemize} | |
1468 | ||
1469 | \subsection{Random-number generators} | |
1470 | ||
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. | |
1479 | ||
1480 | \subsection{The \textsc{HepMC} event format} | |
1481 | ||
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 | |
1492 | is used. | |
1493 | ||
1494 | \subsection{SUSY parameter input} | |
1495 | ||
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.) | |
1504 | ||
1505 | \subsection{Parton showers} | |
1506 | ||
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. | |
1513 | ||
1514 | \section{Getting Going \label{sec:how-to}} | |
1515 | ||
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. | |
1525 | ||
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 | |
1531 | involved. | |
1532 | ||
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 | |
1539 | your main program. | |
1540 | ||
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. | |
1548 | ||
1549 | \section{Outlook \label{sec:outlook}} | |
1550 | ||
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. | |
1559 | ||
1560 | \ack | |
1561 | ||
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. | |
1573 | ||
1574 | \begin{thebibliography}{99} | |
1575 | ||
1576 | \bibitem{jetset} | |
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. | |
1580 | {\bf 43} (1987) 367 | |
1581 | ||
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} | |
1585 | (1985) 251;\\ | |
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 | |
1589 | ||
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 | |
1593 | ||
1594 | \bibitem{pythiasixfour} | |
1595 | T. Sj\"ostrand, S. Mrenna and P. Skands, JHEP {\bf 05} (2006) 026 | |
1596 | [hep-ph/0603175] | |
1597 | ||
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 | |
1602 | ||
1603 | \bibitem{thepeg} | |
1604 | see webpage \texttt{http://www.thep.lu.se/ThePEG/} | |
1605 | ||
1606 | \bibitem{herwigpp} | |
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/} | |
1610 | ||
1611 | \bibitem{lha} | |
1612 | E. Boos et al., in the Proceedings of the Workshop on Physics | |
1613 | at TeV Colliders,\\ | |
1614 | Les Houches, France, 21 May - 1 Jun 2001 [hep-ph/0109068] | |
1615 | ||
1616 | \bibitem{lhef} | |
1617 | J. Alwall et al., Computer Physics Comm. {\bf 176} (2007) 300 | |
1618 | ||
1619 | \bibitem{lhapdf} | |
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] | |
1622 | ||
1623 | \bibitem{ptshowers} | |
1624 | T. Sj\"ostrand and P. Skands, Eur. Phys. J {\bf C39} (2005) 129 | |
1625 | ||
1626 | \bibitem{newremnants} | |
1627 | T. Sj\"ostrand and P. Skands, JHEP {\bf 03} (2004) 053 | |
1628 | ||
1629 | \bibitem{zijl} | |
1630 | T. Sj\"ostrand and M. van Zijl, Phys. Rev. {\bf D36} (1987) 2019 | |
1631 | ||
1632 | \bibitem{wicke} | |
1633 | P. Skands and D. Wicke, Eur. Phys. J. {\bf C52} (2007) 133 | |
1634 | ||
1635 | \bibitem{lundreview} | |
1636 | B. Andersson, G. Gustafson, G. Ingelman and T. Sj\"ostrand, | |
1637 | Phys. Rep. {\bf 97} (1983) 31 | |
1638 | ||
1639 | \bibitem{pdg} | |
1640 | Particle Data Group, W.-M. Yao et al., J. Phys. {\bf G33} (2006) 1 | |
1641 | ||
1642 | \bibitem{boseeinstein} | |
1643 | L. L\"onnblad and T. Sj\"ostrand, Eur. Phys. J. {\bf C2} (1998) 165 | |
1644 | ||
1645 | \bibitem{hepmc} | |
1646 | M. Dobbs and J.B. Hansen, Computer Physics Comm. {\bf 134} (2001) 41 | |
1647 | ||
1648 | \bibitem{slha} | |
1649 | P. Skands et al., JHEP {\bf 07} (2004) 036 | |
1650 | ||
1651 | \bibitem{tauola} | |
1652 | S. Jadach, Z. W\c{a}s, R. Decker and J.H. K\"uhn, | |
1653 | Computer Physics Commun. {\bf 76} (1993) 361 | |
1654 | ||
1655 | \bibitem{evtgen} | |
1656 | D.J. Lange, Nucl. Instrum. Meth. {\bf A462} (2001) 152 | |
1657 | ||
1658 | \bibitem{clhep} | |
1659 | see webpage \texttt{http://proj-clhep.web.cern.ch/proj-clhep/} | |
1660 | ||
1661 | \bibitem{vincia} | |
1662 | W.T. Giele, D.A. Kosower and P.Z. Skands, arXiv:0707.3652 | |
1663 | ||
1664 | \end{thebibliography} | |
1665 | ||
1666 | \end{document} |