Update to pythi8.170
[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8170 / xmldoc / ProgramFiles.xml
1 <chapter name="Program Files">
2
3 <h2>Program Files</h2>
4
5 The code is subdivided into a set of files, mainly by physics 
6 task. Each file typically contains one main class, but often
7 with a few related helper classes that are not used elsewhere in 
8 the program. Normally the files come in pairs.
9 <ul>
10 <li>A header file, <code>.h</code> in the <code>include</code> 
11 subdirectory, where the public interface of the class is declared, 
12 and inline methods are defined.</li>
13 <li>A source code file, <code>.cc</code> in the <code>src</code> 
14 subdirectory, where most of the methods are implemented.</li>
15 </ul>
16 During compilation, related dependency files, <code>.d</code>, and 
17 compiled code, <code>.o</code> are created in the <code>tmp</code>
18 subdirectory.
19
20 <p/>
21 In part the <code>.xml</code> documentation files in the 
22 <code>xmldoc</code> subdirectory have matching names, but the match 
23 is broken by the desire to group topics more by user interaction than 
24 internal operation. On these pages the function of the different code 
25 files is summarized. Currently, each <code>.xml</code> file is also 
26 translated into an <code>.html</code> one in the 
27 <code>htmldoc</code> subdirectory, to allow easy viewing of the 
28 contents in a web browser, and an <code>.php</code> one in 
29 <code>phpdoc</code>, for more sophisticated interactivity
30 if that subdirectory is installed on a web server.
31
32 <p/>
33 Here is the current list of files, ordered alphabetically, with a brief
34 description of contents.
35
36 <file name="Analysis">
37 contains routines to analyze events. Currently it can do sphericity, 
38 thrust, Lund/Jade/Durham jet clustering, cone-jet finding, and the 
39 <ei>kT</ei>, anti-<ei>kT</ei> and Cambridge/Aachen algorithms for
40 hadron colliders.
41 </file>
42
43 <file name="Basics">
44 contains some basic facilities of general use: a random number
45 generator <code>Rndm</code>, a four-vector class <code>Vec4</code>, and a 
46 histogram class <code>Hist</code>.  
47 </file>
48
49 <file name="BeamParticle"> 
50 contains information on all partons extracted from one of the two
51 beams. Defines modified parton distributions accordingly during the
52 showering and multiparton interactions processing, thereby extending on 
53 the one-particle-inclusive distributions defined by the previous class.
54 Finds the internal structure for a beam remnant.
55 </file>
56
57 <file name="BeamRemnants"> 
58 adds primordial <ei>kT</ei> to the set of hard subsystems,
59 and combines these subsystems with the two beam remnants to provide 
60 the overall energy-momentum picture. Also ties together all the 
61 colour lines into consistent singlets. 
62 </file>
63
64 <file name="BeamShape">
65 generates momentum spread of beams, and spread of collision vertex
66 position. 
67 </file>
68
69 <file name="BoseEinstein"> 
70 provides a simple method to impose Bose-Einstein correlations on 
71 pairs of identical mesons.
72 </file>
73
74 <file name="Event"> 
75 contains the event record, which basically is a vector of particles.
76 This file also contains the <code>Particle</code> class, used by 
77 <code>Event</code>. <code>Pythia</code> uses two <code>Event</code> 
78 objects, one for the process-level record (<code>process</code>) and 
79 one for the complete event (<code>event</code>).
80 </file>
81
82 <file name="FragmentationFlavZpT">
83 contains the classes for describing the fragmentation steps in
84 flavour and in longitudinal and transverse momentum.
85 </file>
86
87 <file name="FragmentationSystems">
88 defines some containers of parton systems, for use in 
89 the fragmentation routines.
90 </file>
91
92 <file name="HadronLevel">
93 turns the parton-level event above into a set of outgoing particles,
94 by applying string fragmentation (with special treatment for low-mass
95 systems) and secondary decays, and optionally Bose-Einstein corrections.
96 </file>
97
98 <file name="HelicityBasics">
99 basic classes for the handling of helicities in tau lepton decays.
100 </file>
101
102 <file name="HelicityMatrixElements">
103 helicity-dependent decay matrix elements for the tau lepton.
104 </file>
105
106 <file name="HepMCInterface">
107 contains an interface to convert the PYTHIA 8 event record into the 
108 HepMC format. The <code>HepMCInterface.cc</code> file is located in
109 the subdirectory <code>hepmcinterface</code> and is used to build a 
110 separate <code>libhepmcinterface</code> library. 
111 </file>
112
113 <file name="HiddenValleyFragmentation">
114 hadronization in models with a hidden sector that contains an unbroken
115 <ei>SU(N)</ei>, which gives confinement. The model and code is largely
116 derived from the normal fragmentation classes.
117 </file>
118
119 <file name="History">
120 methods to reconstruct the imagined shower history of a 
121 matrix-element-generated multiparton configuration, as part of 
122 the CKKW-L matrix element merging.
123 </file>
124
125 <file name="Info">
126 is a simple container that gives access to some information on the
127 nature of the current process, such as Mandelstam variables.
128 Also contains a small database for errors and warnings encountered 
129 during program execution.
130 </file>
131
132 <file name="LesHouches">
133 gives the possibility to feed in parton configurations for the 
134 subsequent event generation. One base class is defined, with containers
135 for initialization and event information, that can be read from 
136 <code>Pythia</code>. Derived classes allow for a few different cases.
137 </file>
138
139 <file name="LHAFortran">
140 is a header file only, for a class derived from the above LesHouches 
141 one, to be used for runtime interfacing to Fortran programs, such as
142 PYTHIA 6. 
143 </file>
144
145 <file name="LHAPDFInterface"> 
146 is a header file only, with interfaces to the key LHAPDF routines,
147 as needed for a runtime interface. There is a file
148 <code>lhapdfdummy/LHAPDFdummy.cc</code> with matching dummy
149 implementations, however. This file is used to build a separate 
150 <code>liblhapdfdummy</code> library, to be linked when the LHAPDF 
151 library is not used, so as to avoid problems with undefined references. 
152 </file>
153
154 <file name="MergingHooks"> 
155 intercede in the normal shower evolution to construct the relevant
156 Sudakov form factor suppressions as part of the CKKW-L matrix element
157 merging.
158 </file>
159
160 <file name="MiniStringFragmentation"> 
161 performs string fragmentation in cases where the colour singlet
162 subsystem mass is so small that one or at most two primary hadrons 
163 should be produced from it.
164 </file>
165
166 <file name="MultipartonInteractions"> 
167 performs multiparton interactions.
168 </file>
169
170 <file name="ParticleData">
171 contains a database of all necessary particle data (masses, names, ..)
172 and decay channels.
173 </file>
174
175 <file name="ParticleDecays">
176 performs the decays of all normal unstable hadrons and leptons, i.e. 
177 in mass up to and including <ei>b bbar</ei> systems. It is not 
178 intended for decays of electroweak resonances, like <ei>Z^0</ei>.  
179 </file>
180
181 <file name="PartonDistributions"> 
182 contains parton distribution functions for the proton and electron. 
183 Currently very simple, with only two <ei>p</ei> parametrizations 
184 and one <ei>e</ei> ditto available, but it is possible to link in 
185 external sets.
186 </file>
187
188 <file name="PartonLevel">
189 turns the (hard) process above into a complete set of partons, by 
190 adding initial- and final-state radiation, multiparton
191 interactions, and beam remnants.
192 </file>
193
194 <file name="PartonSystems">
195 keeps track of which partons belong to which partonic subsystem,
196 i.e. one of the multiparton (semi)hard interactions with associated
197 showers.
198 </file>
199
200 <file name="PhaseSpace">
201 selects a point in phase space for the hard-process generation,
202 optimized separately for each process to give improved Monte Carlo 
203 efficiency.
204 </file>
205
206 <file name="ProcessContainer">
207 packages the information on a given subprocess, combining the 
208 phase-space selection and cross-section evaluation machineries
209 with some statistics information. Also sets up the list of processes
210 to be studied in a run.  
211 </file>
212
213 <file name="ProcessLevel">
214 handles the generation of the (hard) process that sets the character 
215 of the event. This involves either using internally implemented 
216 processes or linking to Les Houches information. The latter can
217 be by runtime interfaces or by reading in a file. This step also 
218 includes resonance decays. 
219 </file>
220
221 <file name="Pythia"> 
222 is the main class, that administrates the whole event generation 
223 process by making use of all the others classes. Objects of most
224 other classes reside (directly or indirectly) inside <code>Pythia</code>, 
225 so only a <code>Pythia</code> object needs to be explicitly instantiated 
226 and addressed   by the user.
227 </file>
228
229 <file name="PythiaComplex">
230 is only a <code>.h</code> file, containing a <code>typedef</code> for 
231 double precision complex numbers.
232 </file>
233
234 <file name="PythiaStdlib">
235 contains most of the <code>Stdlib</code> headers used in PYTHIA 8, 
236 with <code>using</code> directives. It defines <code>M_PI</code> if 
237 this is not already done. Also a few simple inline methods: 
238 <code>pow2(x)</code>, <code>pow3(x)</code>, <code>pow4(x)</code>,
239 <code>pow5(x)</code> and <code>pow6(x)</code> for small integer 
240 powers, and <code>sqrtpos(x)</code> where a <code>max(0., x)</code> 
241 ensures that one does not take the square root of a negative number. 
242 Also non-inlined <code>GammaReal(x)</code> for the <ei>Gamma</ei>
243 function value of a real argument.
244 </file>
245
246 <file name="ResonanceDecays"> 
247 decays resonances as part of the hard-process stage, in many cases 
248 (but not all) including angular correlations between the decay products.
249 </file>
250
251 <file name="ResonanceWidths"> 
252 encodes some properties of resonances, in particular the dynamic 
253 calculation of widths.
254 </file>
255
256 <file name="RHadrons"> 
257 handles the production and decay of hadrons formed by long-lived
258 gluinos, stops or sbottoms.
259 </file>
260
261 <file name="Settings"> 
262 contains a database of all flags, modes, parameters and words that 
263 determine the performance of the generator. Initial values are obtained 
264 from the contents of the <code>.xml</code> files, but these values can 
265 then be changed by the user.
266 </file>
267
268 <file name="SigmaCompositeness">
269 contains the cross sections and matrix elements for production of
270 some particles in compositeness scenarios, specifically excited 
271 fermions.
272 </file>
273
274 <file name="SigmaEW">
275 contains the cross sections and matrix elements for electroweak
276 processes involving photons, <ei>Z^0</ei>'s and <ei>W^+-</ei>'s.
277 </file>
278
279 <file name="SigmaExtraDim">
280 contains the cross sections and matrix elements for processes in
281 scenarios involving extra dimensions.
282 </file>
283
284 <file name="SigmaGeneric">
285 contains the cross sections and matrix elements for some generic
286 processes, to be used as building blocks for a few BSM scenarios.
287 </file>
288
289 <file name="SigmaHiggs">
290 contains the cross sections and matrix elements for Higgs production.
291 </file>
292
293 <file name="SigmaLeftRightSym">
294 contains the cross sections and matrix elements for particle production
295 in left-right-symmetry scenarios, specifically righthanded <ei>Z</ei> 
296 and <ei>W</ei> bosons and doubly-charged Higgs bosons. 
297 </file>
298
299 <file name="SigmaLeptoquark">
300 contains the cross sections and matrix elements for leptoquark production.
301 </file>
302
303 <file name="SigmaNewGaugeBosons">
304 contains the cross sections and matrix elements for a <ei>Z'^0</ei>,
305 a <ei>W^+-</ei> and a horizontal gauge boson <ei>R^0</ei>.
306 </file>
307
308 <file name="SigmaOnia">
309 contains the cross sections and matrix elements for charmonium and 
310 bottomonium production.
311 </file>
312
313 <file name="SigmaProcess">
314 contains the base class and derived classes for the evaluation of
315 different matrix elements. Also keeps track of allowed incoming
316 parton configurations and their cross sections, including parton
317 densities. In order to keep this file from becoming too big, actual 
318 cross sections are found in several separate files of derived classes:
319 <code>SigmaQCD</code>, <code>SigmaEW</code>, <code>SigmaOnia</code>, 
320 <code>SigmaHiggs</code>, <code>SigmaSUSY</code>,  
321 <code>SigmaNewGaugeBosons</code>, <code>SigmaLeftRightSym</code>,
322 <code>SigmaLeptoquark</code>, <code>SigmaCompositeness</code>,
323 <code>SigmaExtraDim</code> and <code>SigmaGeneric</code>.
324 </file>
325
326 <file name="SigmaQCD">
327 contains the cross sections and matrix elements for soft and hard
328 QCD processes.
329 </file>
330
331 <file name="SigmaSUSY">
332 contains the cross sections and matrix elements for Supersymmetric
333 processes.
334 </file>
335
336 <file name="SigmaTotal"> 
337 contains parametrizations of total, elastic and diffractive hadronic 
338 cross sections.
339 </file>
340
341 <file name="SpaceShower"> 
342 performs spacelike initial-state transverse-momentum-ordered 
343 shower evolution.
344 </file>
345
346 <file name="StandardModel"> 
347 contains the running <ei>alpha_strong</ei>, with <ei>Lambda</ei> 
348 matching at flavour thresholds, the running <ei>alpha_em</ei>,
349 CKM mixing matrices, and a few other parameters such as
350 <ei>sin^2(theta_W)</ei>.
351 </file>
352
353 <file name="StringFragmentation"> 
354 performs string fragmentation of a given set of partons.
355 </file>
356
357 <file name="SusyCouplings">
358 stores the various couplings used for SUSY cross sections and
359 decays, as calculated from input e.g. based on the SUSY Les Houches 
360 Accord.
361 </file>
362
363 <file name="SusyLesHouches">
364 contains information on SUSY parameters and particle data as specified
365 by the SUSY Les Houches Accord.
366 </file>
367
368 <file name="TauDecays"> 
369 the main routines for handling tau lepton decays with helicity
370 information.
371 </file>
372
373 <file name="TimeShower"> 
374 performs timelike final-state transverse-momentum-ordered 
375 shower evolution.
376 </file>
377
378 <file name="UserHooks"> 
379 Provides a way for a user to study the event at a few intermediate
380 stages of evolution, to reject the event as a whole or to modify
381 its cross-section weight. 
382 </file>
383
384 </chapter>
385
386 <!-- Copyright (C) 2012 Torbjorn Sjostrand -->