PYTHIA8/pythia8130/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, and cone-jet finding.
  39 </file>
  40
  41 <file name="Basics">
  42 contains some basic facilities of general use: a random number
  43 generator <code>Rndm</code>, a four-vector class <code>Vec4</code>, and a
  44 histogram class <code>Hist</code>.
  45 </file>
  46
  47 <file name="BeamParticle">
  48 contains information on all partons extracted from one of the two
  49 beams. Defines modified parton distributions accordingly during the
  50 showering and multiple interactions processing, thereby extending on
  51 the one-particle-inclusive distributions defined by the previous class.
  52 Finds the internal structure for a beam remnant.
  53 </file>
  54
  55 <file name="BeamRemnants">
  56 adds primordial <ei>kT</ei> to the set of hard subsystems,
  57 and combines these subsystems with the two beam remnants to provide
  58 the overall energy-momentum picture. Also ties together all the
  59 colour lines into consistent singlets.
  60 </file>
  61
  62 <file name="BoseEinstein">
  63 provides a simple method to impose Bose-Einstein correlations on
  64 pairs of identical mesons.
  65 </file>
  66
  67 <file name="Event">
  68 contains the event record, which basically is a vector of particles.
  69 This file also contains the <code>Particle</code> class, used by
  70 <code>Event</code>. <code>Pythia</code> uses two <code>Event</code>
  71 objects, one for the process-level record (<code>process</code>) and
  72 one for the complete event (<code>event</code>).
  73 </file>
  74
  75 <file name="FragmentationFlavZpT">
  76 contains the classes for describing the fragmentation steps in
  77 flavour and in longitudinal and transverse momentum.
  78 </file>
  79
  80 <file name="FragmentationSystems">
  81 defines some containers of parton systems, for use in
  82 the fragmentation routines.
  83 </file>
  84
  85 <file name="HadronLevel">
  86 turns the parton-level event above into a set of outgoing particles,
  87 by applying string fragmentation (with special treatment for low-mass
  88 systems) and secondary decays, and optionally Bose-Einstein corrections.
  89 </file>
  90
  91 <file name="HepMCInterface">
  92 contains an interface to convert the PYTHIA 8 event record into the
  93 HepMC format. The <code>HepMCInterface.cc</code> file is located in
  94 the subdirectory <code>hepmcinterface</code> and is used to build a
  95 separate <code>libhepmcinterface</code> library.
  96 </file>
  97
  98 <file name="Info">
  99 is a simple container that gives access to some information on the
 100 nature of the current process, such as Mandelstam variables.
 101 Also contains a small database for errors and warnings encountered
 102 during program execution.
 103 </file>
 104
 105 <file name="LesHouches">
 106 gives the possibility to feed in parton configurations for the
 107 subsequent event generation. One base class is defined, with containers
 108 for initialization and event information, that can be read from
 109 <code>Pythia</code>. Derived classes allow for a few different cases.
 110 </file>
 111
 112 <file name="LHAFortran">
 113 is a header file only, for a class derived from the above LesHouches
 114 one, to be used for runtime interfacing to Fortran programs, such as
 115 PYTHIA 6.
 116 </file>
 117
 118 <file name="LHAPDFInterface">
 119 is a header file only, with interfaces to the key LHAPDF routines,
 120 as needed for a runtime interface. There is a file
 121 <code>lhapdfdummy/LHAPDFdummy.cc</code> with matching dummy
 122 implementations, however. This file is used to build a separate
 123 <code>liblhapdfdummy</code> library, to be linked when the LHAPDF
 124 library is not used, so as to avoid problems with undefined references.
 125 </file>
 126
 127 <file name="MiniStringFragmentation">
 128 performs string fragmentation in cases where the colour singlet
 129 subsystem mass is so small that one or at most two primary hadrons
 130 should be produced from it.
 131 </file>
 132
 133 <file name="MultipleInteractions">
 134 performs multiple parton-parton interactions.
 135 </file>
 136
 137 <file name="ParticleData">
 138 contains a database of all necessary particle data (masses, names, ..)
 139 and decay channels.
 140 </file>
 141
 142 <file name="ParticleDecays">
 143 performs the decays of all normal unstable hadrons and leptons, i.e.
 144 in mass up to and including <ei>b bbar</ei> systems. It is not
 145 intended for decays of electroweak resonances, like <ei>Z^0</ei>.
 146 </file>
 147
 148 <file name="PartonDistributions">
 149 contains parton distribution functions for the proton and electron.
 150 Currently very simple, with only two <ei>p</ei> parametrizations
 151 and one <ei>e</ei> ditto available, but it is possible to link in
 152 external sets.
 153 </file>
 154
 155 <file name="PartonLevel">
 156 turns the (hard) process above into a complete set of partons, by
 157 adding initial- and final-state radiation, multiple parton--parton
 158 interactions, and beam remnants.
 159 </file>
 160
 161 <file name="PhaseSpace">
 162 selects a point in phase space for the hard-process generation,
 163 optimized separately for each process to give improved Monte Carlo
 164 efficiency.
 165 </file>
 166
 167 <file name="ProcessContainer">
 168 packages the information on a given subprocess, combining the
 169 phase-space selection and cross-section evaluation machineries
 170 with some statistics information. Also sets up the list of processes
 171 to be studied in a run.
 172 </file>
 173
 174 <file name="ProcessLevel">
 175 handles the generation of the (hard) process that sets the character
 176 of the event. This involves either using internally implemented
 177 processes or linking to Les Houches information. The latter can
 178 be by runtime interfaces or by reading in a file. This step also
 179 includes resonance decays.
 180 </file>
 181
 182 <file name="Pythia">
 183 is the main class, that administrates the whole event generation
 184 process by making use of all the others classes. Objects of most
 185 other classes reside (directly or indirectly) inside <code>Pythia</code>,
 186 so only a <code>Pythia</code> object needs to be explicitly instantiated
 187 and addressed   by the user.
 188 </file>
 189
 190 <file name="Pythia6Interface">
 191 is a header file only, with interfaces to the key PYTHIA 6 routines,
 192 as needed for a runtime Les Houches interface to this program.
 193 </file>
 194
 195 <file name="PythiaComplex">
 196 is only a <code>.h</code> file, containing a <code>typedef</code> for
 197 double precision complex numbers.
 198 </file>
 199
 200 <file name="PythiaStdlib">
 201 is only a <code>.h</code> file, containing most of the <code>Stdlib</code>
 202 headers used in PYTHIA 8, with <code>using</code> directives. It defines
 203 <code>M_PI</code> if this is not already done. Also a few simple inline
 204 methods: <code>pow2(x)</code>, <code>pow3(x)</code>, <code>pow4(x)</code>
 205 and <code>pow5(x)</code> for small integer powers, and
 206 <code>sqrtpos(x)</code> where a <code>max(0., x)</code> ensures that one
 207 does not take the square root of a negative number.
 208 </file>
 209
 210 <file name="ResonanceDecays">
 211 decays resonances as part of the hard-process stage, in many cases
 212 (but not all) including angular correlations between the decay products.
 213 </file>
 214
 215 <file name="ResonanceWidths">
 216 encodes some properties of resonances, in particular the dynamic
 217 calculation of widths.
 218 </file>
 219
 220 <file name="Settings">
 221 contains a database of all flags, modes, parameters and words that
 222 determine the performance of the generator. Initial values are obtained
 223 from the contents of the <code>.xml</code> files, but these values can
 224 then be changed by the user.
 225 </file>
 226
 227 <file name="SigmaCompositeness">
 228 contains the cross sections and matrix elements for production of
 229 some particles in compositeness scenarios, specifically excited
 230 fermions.
 231 </file>
 232
 233 <file name="SigmaEW">
 234 contains the cross sections and matrix elements for electroweak
 235 processes involving photons, <ei>Z^0</ei>'s and <ei>W^+-</ei>'s.
 236 </file>
 237
 238 <file name="SigmaExtraDim">
 239 contains the cross sections and matrix elements for processes in
 240 scenarios involving extra dimensions.
 241 </file>
 242
 243 <file name="SigmaHiggs">
 244 contains the cross sections and matrix elements for Higgs production.
 245 </file>
 246
 247 <file name="SigmaLeftRightSym">
 248 contains the cross sections and matrix elements for particle production
 249 in left-right-symmetry scenarios, specifically righthanded <ei>Z</ei>
 250 and <ei>W</ei> bosons and doubly-charged Higgs bosons.
 251 </file>
 252
 253 <file name="SigmaLeptoquark">
 254 contains the cross sections and matrix elements for leptoquark production.
 255 </file>
 256
 257 <file name="SigmaNewGaugeBosons">
 258 contains the cross sections and matrix elements for a <ei>Z'^0</ei>,
 259 a <ei>W^+-</ei> and a horizontal gauge boson <ei>R^0</ei>.
 260 </file>
 261
 262 <file name="SigmaOnia">
 263 contains the cross sections and matrix elements for charmonium and
 264 bottomonium production.
 265 </file>
 266
 267 <file name="SigmaProcess">
 268 contains the base class and derived classes for the evaluation of
 269 different matrix elements. Also keeps track of allowed incoming
 270 parton configurations and their cross sections, including parton
 271 densities. In order to keep this file from becoming too big, actual
 272 cross sections are found in several separate files of derived classes:
 273 <code>SigmaQCD</code>, <code>SigmaEW</code>, <code>SigmaOnia</code>,
 274 <code>SigmaHiggs</code>, <code>SigmaSUSY</code>,
 275 <code>SigmaNewGaugeBosons</code>, <code>SigmaLeftRightSym</code>,
 276 <code>SigmaLeptoquark</code>, <code>SigmaCompositeness</code> and
 277 <code>SigmaExtraDim</code>.
 278 </file>
 279
 280 <file name="SigmaQCD">
 281 contains the cross sections and matrix elements for soft and hard
 282 QCD processes.
 283 </file>
 284
 285 <file name="SigmaSUSY">
 286 contains the cross sections and matrix elements for Supersymmetric
 287 processes.
 288 </file>
 289
 290 <file name="SigmaTotal">
 291 contains parametrizations of total, elastic and diffractive hadronic
 292 cross sections.
 293 </file>
 294
 295 <file name="SpaceShower">
 296 performs spacelike initial-state transverse-momentum-ordered
 297 shower evolution.
 298 </file>
 299
 300 <file name="StandardModel">
 301 contains the running <ei>alpha_strong</ei>, with <ei>Lambda</ei>
 302 matching at flavour thresholds, the running <ei>alpha_em</ei>,
 303 CKM mixing matrices, and a few other parameters such as
 304 <ei>sin^2(theta_W)</ei>.
 305 </file>
 306
 307 <file name="StringFragmentation">
 308 performs string fragmentation of a given set of partons.
 309 </file>
 310
 311 <file name="SusyLesHouches">
 312 contains information on SUSY parameters and particle data as specified
 313 by the SUSY Les Houches Accord.
 314 </file>
 315
 316 <file name="TimeShower">
 317 performs timelike final-state transverse-momentum-ordered
 318 shower evolution.
 319 </file>
 320
 321 <file name="UserHooks">
 322 Provides a way for a user to study the event at a few intermediate
 323 stages of evolution, to reject the event as a whole or to modify
 324 its cross-section weight.
 325 </file>
 326
 327 </chapter>
 328
 329 <!-- Copyright (C) 2008 Torbjorn Sjostrand -->