PYTHIA8/pythia8145/htmldoc/ProgramFlow.html

   1 <html>
   2 <head>
   3 <title>Program Flow</title>
   4 <link rel="stylesheet" type="text/css" href="pythia.css"/>
   5 <link rel="shortcut icon" href="pythia32.gif"/>
   6 </head>
   7 <body>
   8
   9 <h2>Program Flow</h2>
  10
  11 Recall that, to first order, the event generation process can be
  12 subdivided into three stages:
  13 <ol>
  14 <li>Initializaion.</li>
  15 <li>The event loop.</li>
  16 <li>Finishing.</li>
  17 </ol>
  18 This is reflected in how the top-level <code>Pythia</code> class should
  19 be used in the user-supplied main program, further outlined in the
  20 following. Since the nature of the run is defined at the initialization
  21 stage, this is where most of the PYTHIA user code has to be written.
  22 So as not to confuse the reader unduly, the description of initialization
  23 options has been subdivided into what would normally be used and what is
  24 intended for more special applications.
  25
  26 <p/>
  27 At the bottom of this webpge is a complete survey of all public
  28 <code>Pythia</code> methods and data members, in a more formal style
  29 than the task-oriented descriptions found in the preceding sections.
  30 This offers complementary information.
  31
  32 <h3>Initialization - normal usage</h3>
  33
  34 <ol>
  35
  36 <li>
  37 Already at the top of the main program file, you need to include the proper
  38 header file
  39 <pre>
  40     #include "Pythia.h"
  41 </pre>
  42 To simplify typing, it also makes sense to declare
  43 <pre>
  44     using namespace Pythia8;
  45 </pre>
  46 </li>
  47
  48 <p/>
  49 <li>
  50 The first step is to create a generator object,
  51 e.g. with
  52 <pre>
  53      Pythia pythia;
  54 </pre>
  55 It is this object that we will use from now on. Normally a run
  56 will only contain one <code>Pythia</code> object. (But you can
  57 use several <code>Pythia</code> objects, which then will be
  58 independent of each other.)<br/>
  59 By default all output from <code>Pythia</code> will be on the
  60 <code>cout</code> stream, but the <code>list</code> methods below do
  61 allow output to alternative streams or files.
  62 </li>
  63
  64 <p/>
  65 <li>
  66 You next want to set up the character of the run.
  67 The pages under the "Setup Run Tasks" heading in the index
  68 describe all the options available (with some very few exceptions,
  69 found on the other pages).
  70 The default values and your modifications are stored in two databases,
  71 one for <a href="SettingsScheme.html" target="page">generic settings</a>
  72 and one for <a href="ParticleDataScheme.html" target="page">particle data</a>.
  73 Both of these are initialized with their default values by the
  74 <code>Pythia</code> constructor. The default values can then be
  75 changed, primarily by one of the two ways below, or by a combination
  76 of them.
  77
  78 <p/>
  79 a) You can use the
  80 <pre>
  81     pythia.readString(string);
  82 </pre>
  83 method repeatedly to do a change of a property at a time.
  84 The information in the string is case-insensitive, but upper- and
  85 lowercase can be combined for clarity. The rules are that<br/>
  86 (i) if the first nonblank character of the string is a letter
  87 it is assumed to contain a setting, and is sent on to
  88 <code>pythia.settings.readString(string)</code>;<br/>
  89 (ii) if instead the string begins with a digit it is assumed to
  90 contain particle data updates, and so sent on to
  91 <code>pythia.particleData.readString(string)</code>;<br/>
  92 (iii) if none of the above, the string is assumed to be a comment,
  93 i.e. nothing will be done.<br/>
  94 In the former two cases, a warning is issued whenever a string
  95 cannot be recognized (maybe because of a spelling mistake).<br/>
  96 Some examples would be
  97 <pre>
  98     pythia.readString("TimeShower:pTmin = 1.0");
  99     pythia.readString("111:mayDecay = false");
 100 </pre>
 101 The <code>readString(string)</code> method is intended primarily for
 102 a few changes. It can also be useful if you want to construct a
 103 parser for input files that contain commands both to PYTHIA and to
 104 other libraries.<br/>
 105
 106 <p/>
 107 b) You can read in a file containing a list of those variables
 108 you want to see changed, with a
 109 <pre>
 110     pythia.readFile(fileName);
 111 </pre>
 112 Each line in this file with be processes by the
 113 <code>readString(string)</code> method introduced above. You can thus
 114 freely mix comment lines and lines handed on to <code>Settings</code>
 115 or to <code>ParticleData</code>.<br/>
 116 This approach is better suited for more extensive changes than a direct
 117 usage of <code>readString(string)</code>, and can also avoid having to
 118 recompile and relink your main program between runs.<br/>
 119 It is also possible to read input from an <code>istream</code>, by
 120 default <code>cin</code>, rather than from a file. This may be convenient
 121 if information is generated on-the-fly, within the same run.
 122
 123 <p/>
 124 Changes are made sequentially in the order the commands are encountered
 125 during execution, meaning that if a parameter is changed several times
 126 it is the last one that counts. The two special
 127 <code><a href="Tunes.html" target="page">Tune:ee</a></code> and
 128 <code><a href="Tunes.html" target="page">Tune:pp</a></code>
 129 modes are expanded to change several settings in one go, but these obey
 130 the same ordering rules.
 131 <br/>
 132 </li>
 133
 134 <p/>
 135 <li>
 136 Next comes the initialization stage, where all
 137 remaining details of the generation are to be specified. The
 138 <code>init(...)</code> method allows a few different input formats,
 139 so you can pick the one convenient for you:
 140
 141 <p/>
 142 a) <code>pythia.init( idA, idB, eCM);</code><br/>
 143 lets you specify the identities and the CM energy of the two incoming
 144 beam particles, with A (B) assumed moving in the <i>+z (-z)</i>
 145 direction.
 146
 147 <p/>
 148 b) <code>pythia.init( idA, idB, eA, eB);</code><br/>
 149 is similar, but the two beam energies can be different, so the
 150 collisions do not occur in the CM frame. If one of the beam energies
 151 is below the particle mass you obtain a fixed-target topology.
 152
 153 <p/>
 154 c) <code>pythia.init( idA, idB, pxA, pyA, pzA, pxB, pyB, pzB);</code><br/>
 155 is similar, but here you provide the three-momenta
 156 <i>(p_x, p_y, p_z)</i> of the two incoming particles,
 157 to allow for arbitrary beam directions.
 158
 159 <p/>
 160 d) <code>pythia.init(fileName);</code> <br/>
 161 assumes a file in the <a href="LesHouchesAccord.html" target="page">Les Houches
 162 Event File</a> format is provided.
 163
 164 <p/>
 165 e) <code>pythia.init();</code><br/>
 166 with no arguments will read the beam parameters from the
 167 <code><a href="MainProgramSettings.html" target="page">Main</a></code>
 168 group of variables, which provides you with the same possibilities as
 169 the above options a, b, c and d. If you don't change any of those you will
 170 default to proton-proton collisions at 14 TeV, i.e. the nominal LHC
 171 values.
 172
 173 <p/>
 174 f) <code>pythia.init( LHAup*);</code> <br/>
 175 assumes <a href="LesHouchesAccord.html" target="page">Les Houches Accord</a>
 176 initialization and event information is available in an <code>LHAup</code>
 177 class object, and that a pointer to this object is handed in.
 178
 179 <p/>
 180 <li>
 181 If you want to have a list of the generator and particle data used,
 182 either only what has been changed or everything, you can use
 183 <pre>
 184     pythia.settings.listChanged();
 185     pythia.settings.listAll();
 186     pythia.particleData.listChanged();
 187     pythia.particleData.listAll();
 188 </pre>
 189 </li>
 190
 191 </ol>
 192
 193 <h3>The event loop</h3>
 194
 195 <ol>
 196
 197 <li>
 198 Inside the event generation loop you generate the
 199 next event using the <code>next()</code> method,
 200 <pre>
 201     pythia.next();
 202 </pre>
 203 This method takes no arguments; everything has already been specified.
 204 It does return a bool value, however, <code>false</code> when the
 205 generation failed. This can be a "programmed death" when the
 206 supply of input parton-level configurations on file is exhausted.
 207 It can alternatively signal a failure of <code>Pythia</code> to
 208 generate an event, or unphysical features in the event record at the
 209 end of the generation step. It makes sense to allow a few <code>false</code>
 210 values before a run is aborted, so long as the related faulty
 211 events are skipped.
 212 </li>
 213
 214 <p/>
 215 <li>
 216 The generated event is now stored in the <code>event</code>
 217 object, of type <code><a href="EventRecord.html" target="page">Event</a></code>,
 218 which is a public member of <code>pythia</code>. You therefore have
 219 access to all the tools described on the pages under the "Study Output"
 220 header in the index. For instance, an event can be listed with
 221 <code>pythia.event.list()</code>, the identity of the <i>i</i>'th
 222 <a href="ParticleProperties.html" target="page">particle</a> is given by
 223 <code>pythia.event[i].id()</code>, and so on.<br/>
 224 The hard process - roughly the information normally stored in the
 225 Les Houches Accord event record - is available as a second object,
 226 <code>process</code>, also of type <code>Event</code>.<br/>
 227 A third useful public object is
 228 <code><a href="EventInformation.html" target="page">info</a></code>, which offers
 229 a set of one-of-a kind pieces of information about the most recent
 230 event.
 231 </li>
 232
 233 </ol>
 234
 235 <h3>Finishing</h3>
 236
 237 <ol>
 238
 239 <li>At the end of the generation process, you can call
 240 <pre>
 241     pythia.statistics();
 242 </pre>
 243 to get some run statistics, on cross sections and the number of errors
 244 and warnings encountered.
 245 </li>
 246
 247 </ol>
 248
 249 <h3>Advanced usage, mainly for initialization</h3>
 250
 251 A) Necessary data are automatically loaded when you use the
 252 default PYTHIA installation directory structure and run the main
 253 programs in the <code>examples</code> subdirectory. However, in the
 254 general case, you must provide the path of the <code>xmldoc</code>
 255 directory, where default settings and particle data are found.
 256 This can be done in two ways.
 257
 258 <ol>
 259
 260 <li>
 261 You can set the environment variable <code>PYTHIA8DATA</code> to
 262 contain the location of the <code>xmldoc</code> directory. In the
 263 <code>csh</code> and <code>tcsh</code> shells this could e.g. be
 264 <pre>
 265      setenv PYTHIA8DATA /home/myname/pythia81xx/xmldoc
 266 </pre>
 267 while in other shells it could be
 268 <pre>
 269      export PYTHIA8DATA=/home/myname/pythia81xx/xmldoc
 270 </pre>
 271 where xx is the subversion number.<br/>
 272 Recall that environment variables set locally are only defined in the
 273 current instance of the shell. The above lines should go into your
 274 <code>.cshrc</code> and <code>.bashrc</code> files, respectively,
 275 if you want a more permanant assignment.
 276 </li>
 277
 278 <p/>
 279 <li>
 280 You can provide the path as argument to the <code>Pythia</code>
 281 constructor, e.g.
 282 <pre>
 283      Pythia pythia("/home/myname/pythia81xx/xmldoc");
 284 </pre>
 285 </li>
 286 </ol>
 287 where again xx is the subversion number.<br/>
 288 When <code>PYTHIA8DATA</code> is set it takes precedence, else
 289 the path in the constructor is used, else one defaults to the
 290 <code>../xmldoc</code> directory.
 291
 292 <p/>
 293 B) You can override the default behaviour of PYTHIA not only by the
 294 settings and particle data, but also by replacing some of the
 295 PYTHIA standard routines by ones of your own. Of course, this is only
 296 possible if your routines fit into the general PYTHIA framework.
 297 Therefore they must be coded according to the the rules relevant
 298 in each case, as a derived class of a PYTHIA base class, and a pointer
 299 to such an object must be handed in by one of the methods below.
 300 These calls must be made before the <code>pythia.init(...)</code> call.
 301
 302 <ol>
 303
 304 <li>
 305 If you are not satisfied with the list of parton density functions that
 306 are implemented internally or available via the LHAPDF interface
 307 (see the <a href="PDFSelection.html" target="page">PDF Selection</a> page), you
 308 can suppy your own by a call to the <code>setPDFPtr(...)</code> method
 309 <pre>
 310       pythia.setPDFptr( pdfAPtr, pdfBPtr);
 311 </pre>
 312 where <code>pdfAPtr</code> and <code>pdfBPtr</code> are pointers to
 313 two <code>Pythia</code> <a href="PartonDistributions.html" target="page">PDF
 314 objects</a>. Note that <code>pdfAPtr</code> and <code>pdfBPtr</code>
 315 cannot point to the same object; even if the PDF set is the same,
 316 two copies are needed to keep track of two separate sets of <i>x</i>
 317 and density values.<br/>
 318 If you further wish to use separate PDF's for the hard process of an
 319 event than the ones being used for everything else, the extended form
 320 <pre>
 321       pythia.setPDFptr( pdfAPtr, pdfBPtr, pdfHardAPtr, pdfHardBPtr);
 322 </pre>
 323 allows you to specify those separately, and then the first two sets
 324 would only be used for the showers and for multiple interactions.
 325 </li>
 326
 327 <p/>
 328 <li>
 329 If you want to perform some particle decays with an
 330 external generator, you can call the <code>setDecayPtr(...)</code>
 331 method
 332 <pre>
 333       pythia.setDecayPtr( decayHandlePtr, particles);
 334 </pre>
 335 where the <code>decayHandlePtr</code> derives from the
 336 <code><a href="ExternalDecays.html" target="page">DecayHandler</a></code> base
 337 class and <code>particles</code> is a vector of particle codes to be
 338 handled.
 339 </li>
 340
 341 <p/>
 342 <li>
 343 If you want to use an external random number generator,
 344 you can call the <code>setRndmEnginePtr(...)</code> method
 345 <pre>
 346       pythia.setRndmEnginePtr( rndmEnginePtr);
 347 </pre>
 348 where <code>rndmEnginePtr</code> derives from the
 349 <code><a href="RandomNumbers.html" target="page">RndmEngine</a></code> base class.
 350 The <code>Pythia</code> default random number generator is perfectly
 351 good, so this is only intended for consistency in bigger frameworks.
 352 </li>
 353
 354 <p/>
 355 <li>
 356 If you want to interrupt the evolution at various stages,
 357 to interrogate the event and possibly veto it, or you want to
 358 reweight the cross section, you can use
 359 <pre>
 360       pythia.setUserHooksPtr( userHooksPtr);
 361 </pre>
 362 where <code>userHooksPtr</code> derives from the
 363 <code><a href="UserHooks.html" target="page">UserHooks</a></code> base class.
 364 </li>
 365
 366 <p/>
 367 <li>
 368 If you want to use your own parametrization of beam momentum spread and
 369 interaction vertex, rather than the provided simple Gaussian
 370 parametrization (off by default), you can call
 371 <pre>
 372       pythia.setBeamShapePtr( beamShapePtr);
 373 </pre>
 374 where <code>beamShapePtr</code> derives from the
 375 <code><a href="BeamShape.html" target="page">BeamShape</a></code> base class.
 376 </li>
 377
 378 <p/>
 379 <li>
 380 If you want to implement a cross section of your own, but still make use
 381 of the built-in phase space selection machinery, you can use
 382 <pre>
 383       pythia.setSigmaPtr( sigmaPtr);
 384 </pre>
 385 where <code>sigmaPtr</code> of type <code>SigmaProcess*</code> is an
 386 instance of a class derived from one of the <code>Sigma1Process</code>,
 387 <code>Sigma2Process</code> and  <code>Sigma3Process</code> base classes
 388 in their turn derived from
 389 <code><a href="SemiInternalProcesses.html" target="page">SigmaProcess</a></code>.
 390 This call can be used repeatedly to hand in several different processes.
 391 </li>
 392
 393 <p/>
 394 <li>
 395 If your cross section contains the production of a new resonance
 396 with known analytical expression for all the relevant partial widths,
 397 you can make this resonance available to the program with
 398 <pre>
 399       pythia.setResonancePtr( resonancePtr);
 400 </pre>
 401 where <code>resonancePtr</code> of type <code>ResonanceWidths*</code>
 402 is an instance of a class derived from the
 403 <code><a href="SemiInternalResonances.html" target="page">ResonanceWidths</a></code>
 404 base class. In addition you need to add the particle to the normal
 405 <a href="ParticleDataScheme.html" target="page">particle and decay database</a>.
 406 This procedure can be used repeatedly to hand in several different
 407 resonances.
 408 </li>
 409
 410 <p/>
 411 <li>
 412 If you are a real expert and want to <a href="ImplementNewShowers.html" target="page">replace
 413 the PYTHIA initial- and final-state showers</a>, you can use
 414 <pre>
 415       pythia.setShowerPtr( timesDecPtr, timesPtr, spacePtr);
 416 </pre>
 417 where <code>timesDecPtr</code> and <code>timesPtr</code>
 418 derive from the <code>TimeShower</code> base class, and
 419 <code>spacePtr</code> from <code>SpaceShower</code>.
 420 </li>
 421
 422 </ol>
 423
 424 <p/>
 425 C) Some comments on collecting several tasks in the same run.
 426 <ol>
 427
 428 <li>
 429 PYTHIA has not been written for threadsafe execution on multicore
 430 processors. If you want to use all cores,
 431 the most efficient way presumably is to start correspondingly many jobs,
 432 with different random number seeds, and add the statistics at the end.
 433 </li>
 434
 435 <p/>
 436 <li>
 437 In some cases it is convenient to use more than one <code>Pythia</code>
 438 object. The key example would be the simultaneous generation of signal
 439 and pileup events, see <code>main19.cc</code>. The two objects are then
 440 set up and initialized separately, and generate events completely
 441 independently of each other. It is only afterwards that the event records
 442 are combined into one single super-event per beam crossing.
 443 </li>
 444
 445 <p/>
 446 <li>
 447 When time is not an issue, it may be that you want to perform several
 448 separate subruns sequentially inside a run, e.g. to combine results for
 449 several kinematical regions or to compare results for some different
 450 tunes of the underlying event. One way to go is to create (and destroy)
 451 one <code>pythia</code> object for each subrun, in which case they are
 452 completely separate. You can also use the same <code>pythia</code> object,
 453 only doing a new <code>init(...)</code> call for each subrun. In that
 454 case, the settings and particle databases remain as they were in the
 455 previous subrun, only affected by the specific changes you introduced in
 456 the meantime. You can put those changes in the main program, with
 457 <code>pythia.readString(string)</code>, using your own logic to decide
 458 which ones to execute in which subrun. A corresponding possibility
 459 exists with <code>pythia.readFile(fileName, subrun)</code> (or an
 460 <code>istream</code> instead of a <code>fileName</code>), which as second
 461 argument can take a non-negative subrun number. Then only those
 462 sections of the file before any <code>Main:subrun = ...</code> line
 463 or with matching <code>subrun</code> number will be read. That is, the
 464 file could have a structure like
 465 <pre>
 466     ( lines always read, i.e. "default values" always (re)set )
 467     Main:subrun = 1
 468     ( lines only read with readFile(fileName, 1) )
 469     Main:subrun = 2
 470     ( lines only read with readFile(fileName, 2) )
 471 </pre>
 472 Both of these possibilities are illustrated in <code>main08.cc</code>.
 473 </li>
 474
 475 <p/>
 476 <li>
 477 When working with Les Houches Event Files, it may well be that your
 478 intended input event sample is spread over several files, that you all
 479 want to turn into complete events in one and the same run. There is no
 480 problem with looping over several subruns, where each new subrun
 481 is initialized with a new file. However, in that case you will do
 482 a complete re-initialization each time around. If you want to avoid
 483 this, note that there is an optional second argument for LHEF
 484 initialization: <code>pythia.init(fileName, skipInit)</code>.
 485 Alternatively, the tag <code>Main:LHEFskipInit</code> can be put
 486 in a file of commands to obtain the same effect.
 487 Here <code>skipInit</code> defaults to <code>false</code>,
 488 but if set <code>true</code> then the new file will be simulated
 489 with the same initialization data as already set in a previous
 490 <code>pythia.init(...)</code> call. The burden rests on you to ensure
 491 that this is indeed correct, e.g. that the two event samples have not
 492 been generated for different beam energies.
 493 </li>
 494
 495 </ol>
 496
 497 <h2>The Pythia Class</h2>
 498
 499 Here follows the complete survey of all public <code>Pythia</code>
 500 methods and data members.
 501
 502 <h3>Constructor and destructor</h3>
 503
 504 <a name="method1"></a>
 505 <p/><strong>Pythia::Pythia(string xmlDir = &quot;../xmldoc&quot;) &nbsp;</strong> <br/>
 506 creates an instance of the <code>Pythia</code> event generators,
 507 and sets initial default values, notably for all settings and
 508 particle data. You may use several <code>Pythia</code> instances
 509 in the same run; only when you want to access external static
 510 libraries could this cause problems. (This includes in particular
 511 Fortran libraries such as <a href="PDFSelection.html" target="page">LHAPDF</a>.)
 512 <br/><code>argument</code><strong> xmlDir </strong> (<code>default = <strong>../xmldoc</strong></code>) : allows you to choose
 513 from which directory the default settings and particle data values
 514 are read in. If the <code>PYTHIA8DATA</code> environment variable
 515 has been set it takes precedence. Else this optional argument allows
 516 you to choose another directory location than the default one. Note
 517 that it is only the directory location you can change, its contents
 518 must be the ones of the <code>xmldoc</code> directory in the
 519 standard distribution.
 520
 521
 522
 523 <a name="method2"></a>
 524 <p/><strong>Pythia::~Pythia &nbsp;</strong> <br/>
 525 the destructor deletes the objects created by the constructor.
 526
 527 <h3>Set up run</h3>
 528
 529 <a name="method3"></a>
 530 <p/><strong>bool Pythia::readString(string line, bool warn = true) &nbsp;</strong> <br/>
 531 reads in a single string, that is interpreted as an instruction to
 532 modify the value of a <a href="SettingsScheme.html" target="page">setting</a> or
 533 <a href="ParticleDataScheme.html" target="page">particle data</a>, as already described
 534 above.
 535 <br/><code>argument</code><strong> line </strong>  :
 536 the string to be interpreted as an instruction.
 537
 538 <br/><code>argument</code><strong> warn </strong> (<code>default = <strong>true</strong></code>) :
 539 write a warning message or not whenever the instruction does not make
 540 sense, e.g. if the variable does not exist in the databases.
 541
 542 <br/><b>Note:</b> the method returns false if it fails to
 543 make sense out of the string.
 544
 545
 546 <a name="method4"></a>
 547 <p/><strong>bool Pythia::readFile(string fileName, bool warn = true, int subrun = SUBRUNDEFAULT) &nbsp;</strong> <br/>
 548
 549 <strong>bool Pythia::readFile(string fileName, int subrun = SUBRUNDEFAULT) &nbsp;</strong> <br/>
 550
 551 <strong>bool Pythia::readFile(istream& inStream = cin,  bool warn = true, int subrun = SUBRUNDEFAULT) &nbsp;</strong> <br/>
 552
 553 <strong>bool Pythia::readFile(istream& inStream = cin, int subrun = SUBRUNDEFAULT) &nbsp;</strong> <br/>
 554 reads in a whole file, where each line is interpreted as an instruction
 555 to modify the value of a <a href="SettingsScheme.html" target="page">setting</a> or
 556 <a href="ParticleDataScheme.html" target="page">particle data</a>, cf. the above
 557 <code>readString</code> method. All four forms of the
 558 <code>readFile</code> command share code for actually reading a file.
 559 <br/><code>argument</code><strong> fileName </strong>  :
 560 the file from which instructions are read.
 561
 562 <br/><code>argument</code><strong> inStream </strong>  :
 563 an istream from which instructions are read.
 564
 565 <br/><code>argument</code><strong> warn </strong> (<code>default = <strong>true</strong></code>) :
 566 write a warning message or not whenever the instruction does not make
 567 sense, e.g. if the variable does not exist in the databases. In the
 568 command forms where <code>warn</code> is omitted it is true.
 569
 570 <br/><code>argument</code><strong> subrun </strong>  :
 571 allows you have several optional sets of commands within the same file.
 572 Only those sections of the file before any <code>Main:subrun = ...</code>
 573 line or following such a line with matching subrun number will be read.
 574 The subrun number should not be negative; negative codes like
 575 <code>SUBRUNDEFAULT</code> corresponds to no specific subrun.
 576
 577 <br/><b>Note:</b> the method returns false if it fails to
 578 make sense out of any one line.
 579
 580
 581 <a name="method5"></a>
 582 <p/><strong>bool Pythia::setPDFPtr( PDF* pdfAPtr, PDF* pdfBPtr, PDF* pdfHardAPtr = 0, PDF* pdfHardBPtr = 0) &nbsp;</strong> <br/>
 583 offers the possibility to link in external PDF sets for usage inside
 584 the program. The rules for constructing your own class from
 585 the <code>PDF</code> base class are described
 586 <a href="PartonDistributions.html" target="page">here</a>.
 587 <br/><code>argument</code><strong> pdfAPtr, pdfBPtr </strong>  :
 588 pointers to two <code>PDF</code>-derived objects, one for each of
 589 the incoming beams. The two objects have to be instantiated by you
 590 in your program. Even if the two beam particles are the same
 591 (protons, say) two separate instances are required, since current
 592 information is cached in the objects. If both arguments are zero
 593 then any previous linkage to external PDF's is disconnected,
 594 see further Note 2 below.
 595
 596 <br/><code>argument</code><strong> pdfHardAPtr, pdfHardBPtr </strong> (<code>default = <strong>0</strong></code>) :
 597 pointers to two further <code>PDF</code>-derived objects, one for each
 598 of the incoming beams. Normally only the first two arguments above would
 599 be used, and then the same PDF sets would be invoked everywhere. If you
 600 provide these two further pointers then two different sets of PDF's are
 601 used. This second set is then exclusively for the generation of the hard
 602 process from the process matrix elements library. The first set above
 603 is for everything else, notably parton showers and multiple interactions.
 604
 605 <br/><b>Note 1:</b> The method returns false if the input is obviously
 606 incorrect, e.g. if two (nonzero) pointers agree.
 607 <br/><b>Note 2:</b> If you want to combine several subruns you can
 608 call <code>setPDFPtr</code> with new arguments before each
 609 <code>Pythia::init(...)</code> call. To revert from external PDF's
 610 to the normal internal PDF selection you must call
 611 <code>setPDFPtr(0, 0)</code> before <code>Pythia::init(...)</code>.
 612
 613
 614 <a name="method6"></a>
 615 <p/><strong>bool Pythia::setDecayPtr( DecayHandler* decayHandlePtr, vector&lt;int&gt; handledParticles) &nbsp;</strong> <br/>
 616 offers the possibility to link to an external program that can do some
 617 of the particle decays, instad of using the internal decay machinery.
 618 With particles we here mean the normal hadrons and leptons, not
 619 top quarks, electroweak bosons or new particles in BSM scenarios.
 620 The rules for constructing your own class from the
 621 <code>DecayHandler</code> base class are described
 622 <a href="ExternalDecays.html" target="page">here</a>. Note that you can only
 623 provide one external object, but this object in its turn could
 624 very well hand on different particles to separate decay libraries.
 625 <br/><code>argument</code><strong> decayHandlePtr </strong>  :
 626 pointer to a <code>DecayHandler</code>-derived object. This object
 627 must be instantiated by you in your program.
 628
 629 <br/><code>argument</code><strong> handledParticles </strong>  :  vector with the PDG identity codes
 630 of the particles that should be handled by the external decay package.
 631 You should only give the particle (positive) codes; the respective
 632 antiparticle is always included as well.
 633
 634 <br/><b>Note:</b> The method currently always returns true.
 635
 636
 637 <a name="method7"></a>
 638 <p/><strong>bool Pythia::setRndmEnginePtr( RndmEngine* rndmEnginePtr) &nbsp;</strong> <br/>
 639 offers the possibility to link to an external random number generator.
 640 The rules for constructing your own class from the
 641 <code>RndmEngine</code> base class are described
 642 <a href="RandomNumbers.html" target="page">here</a>.
 643 <br/><code>argument</code><strong> rndmEnginePtr </strong>  :
 644 pointer to a <code>RndmEngine</code>-derived object. This object
 645 must be instantiated by you in your program.
 646
 647 <br/><b>Note:</b> The method returns true if the pointer is different
 648 from 0.
 649
 650
 651 <a name="method8"></a>
 652 <p/><strong>bool Pythia::setUserHooksPtr( UserHooks* userHooksPtr) &nbsp;</strong> <br/>
 653 offers the possibility to interact with the generation process at
 654 a few different specified points, e.g. to reject undesirable events
 655 at an early stage to save computer time. The rules for constructing
 656 your own class from the <code>UserHooks</code> base class are described
 657 <a href="UserHooks.html" target="page">here</a>. You can only hand in one such
 658 pointer, but this may be to a class that implements several of the
 659 different allowed possibilities.
 660 <br/><code>argument</code><strong> userHooksPtr </strong>  :
 661 pointer to a <code>userHooks</code>-derived object. This object
 662 must be instantiated by you in your program.
 663
 664 <br/><b>Note:</b> The method currently always returns true.
 665
 666
 667 <a name="method9"></a>
 668 <p/><strong>bool Pythia::setBeamShapePtr( BeamShape* beamShapePtr) &nbsp;</strong> <br/>
 669 offers the possibility to provide your own shape of the momentum and
 670 space-time spread of the incoming beams. The rules for constructing
 671 your own class from the <code>BeamShape</code> base class are described
 672 <a href="BeamShape.html" target="page">here</a>.
 673 <br/><code>argument</code><strong> BeamShapePtr </strong>  :
 674 pointer to a <code>BeamShape</code>-derived object. This object
 675 must be instantiated by you in your program.
 676
 677 <br/><b>Note:</b> The method currently always returns true.
 678
 679
 680 <a name="method10"></a>
 681 <p/><strong>bool Pythia::setSigmaPtr( SigmaProcess* sigmaPtr) &nbsp;</strong> <br/>
 682 offers the possibility to link your own implementation of a process
 683 and its cross section, to make it a part of the normal process
 684 generation machinery, without having to recompile the
 685 <code>Pythia</code> library itself.  The rules for constructing your
 686 own class from the <code>SigmaProcess</code> base class are described
 687 <a href="SemiInternalProcesses.html" target="page">here</a>. You may call this
 688 routine repeatedly, to add as many new processes as you wish.
 689 <br/><code>argument</code><strong> sigmaPtr </strong>  :
 690 pointer to a <code>SigmaProcess</code>-derived object. This object
 691 must be instantiated by you in your program.
 692
 693 <br/><b>Note:</b> The method currently always returns true.
 694
 695
 696 <a name="method11"></a>
 697 <p/><strong>bool Pythia::setResonancePtr( ResonanceWidths* resonancePtr) &nbsp;</strong> <br/>
 698 offers the possibility to link your own implementation of the
 699 calculation of partial resonance widths, to make it a part of the
 700 normal process generation machinery, without having to recompile the
 701 <code>Pythia</code> library itself.  This allows the decay of new
 702 resonances to be handled internally, when combined with new particle
 703 data. Note that the decay of normal hadrons cannot be modelled here;
 704 this is for New Physics resonances. The rules for constructing your
 705 own class from the <code>ResonanceWidths</code> base class are described
 706 <a href="SemiInternalResonances.html" target="page">here</a>. You may call this
 707 routine repeatedly, to add as many new resonances as you wish.
 708 <br/><code>argument</code><strong> resonancePtr </strong>  :
 709 pointer to a <code>ResonanceWidths</code>-derived object. This object
 710 must be instantiated by you in your program.
 711
 712 <br/><b>Note:</b> The method currently always returns true.
 713
 714
 715 <a name="method12"></a>
 716 <p/><strong>bool Pythia::setShowerPtr( TimeShower* timesDecPtr, TimeShower* timesPtr = 0, SpaceShower* spacePtr = 0) &nbsp;</strong> <br/>
 717 offers the possibility to link your own parton shower routines as
 718 replacements for the default ones. This is much more complicated
 719 since the showers are so central and are so interlinked with other
 720 parts of the program. Therefore it is also possible to do the
 721 replacement in stages, from the more independent to the more
 722 intertwined. The rules for constructing your own classes from the
 723 <code>TimeShower</code> and <code>SpaceShower</code>base classes
 724 are described <a href="ImplementNewShowers.html" target="page">here</a>. These
 725 objects must be instantiated by you in your program.
 726 <br/><code>argument</code><strong> timesDecPtr </strong>  :
 727 pointer to a <code>TimeShower</code>-derived object for doing
 728 timelike shower evolution in resonance decays, e.g. of a
 729 <i>Z^0</i>. This is decoupled from beam remnants and parton
 730 distributions, and is therefore the simplest kind of shower
 731 to write. If you provide a value 0 then the internal shower
 732 routine will be used.
 733
 734 <br/><code>argument</code><strong> timesPtr </strong> (<code>default = <strong>0</strong></code>) :
 735 pointer to a <code>TimeShower</code>-derived object for doing
 736 all other timelike shower evolution, which is normally interleaved
 737 with multiple interactions and spacelike showers, introducing
 738 both further physics and further technical issues. If you retain
 739 the default value 0 then the internal shower routine will be used.
 740 You are allowed to use the same pointer as above for the
 741 <code>timesDecPtr</code> if the same shower can fulfill both tasks.
 742
 743 <br/><code>argument</code><strong> spacePtr </strong> (<code>default = <strong>0</strong></code>) :
 744 pointer to a <code>SpaceShower</code>-derived object for doing
 745 all spacelike shower evolution, which is normally interleaved
 746 with multiple interactions and timelike showers. If you retain
 747 the default value 0 then the internal shower routine will be used.
 748
 749 <br/><b>Note:</b> The method currently always returns true.
 750
 751
 752 <h3>Initialize</h3>
 753
 754 At the initialization stage all the information provided above is
 755 processed, and the stage is set up for the subsequent generation
 756 of events. Several alterative forms of the <code>init</code> method
 757 are available for this stage; pick the one most convenient.
 758
 759 <a name="method13"></a>
 760 <p/><strong>bool Pythia::init( int idA, int idB, double eCM) &nbsp;</strong> <br/>
 761 initialize for collisions in the center-of-mass frame, with the
 762 beams moving in the <i>+-z</i> directions.
 763 <br/><code>argument</code><strong> idA, idB </strong>  :
 764 particle identity code for the two incoming beams.
 765
 766 <br/><code>argument</code><strong> eCM </strong>  :
 767 the CM energy of the collisions.
 768
 769 <br/><b>Note:</b> The method returns false if the
 770 initialization fails. It is then not possible to generate any
 771 events.
 772
 773
 774 <a name="method14"></a>
 775 <p/><strong>bool Pythia::init( int idA, int idB, double eA, double eB) &nbsp;</strong> <br/>
 776 initialize for collisions with back-to-back beams,
 777 moving in the <i>+-z</i> directions, but with different energies.
 778 <br/><code>argument</code><strong> idA, idB </strong>  :
 779 particle identity code for the two incoming beams.
 780
 781 <br/><code>argument</code><strong> eA, eB </strong>  :
 782 the energies of the two beams. If an energy is set to be below
 783 the mass of the respective beam particle that particle is taken to
 784 be at rest. This offers a simple possibility to simulate
 785 fixed-target collisions.
 786
 787 <br/><b>Note:</b> The method returns false if the
 788 initialization fails. It is then not possible to generate any
 789 events.
 790
 791
 792 <a name="method15"></a>
 793 <p/><strong>bool Pythia::init( int idA, int idB, double pxA, double pyA, double pzA, double pxB, double pyB, double pzB) &nbsp;</strong> <br/>
 794 initialize for collisions with arbitrary beam directions.
 795 <br/><code>argument</code><strong> idA, idB </strong>  :
 796 particle identity code for the two incoming beams.
 797
 798 <br/><code>argument</code><strong> pxA, pyA, pzA </strong>  :
 799 the three-momntum vector <i>(p_x, p_y, p_z)</i> of the first
 800 incoming beam.
 801
 802 <br/><code>argument</code><strong> pxB, pyB, pzB </strong>  :
 803 the three-momntum vector <i>(p_x, p_y, p_z)</i> of the second
 804 incoming beam.
 805
 806 <br/><b>Note:</b> The method returns false if the
 807 initialization fails. It is then not possible to generate any
 808 events.
 809
 810
 811 <a name="method16"></a>
 812 <p/><strong>bool Pythia::init( string LesHouchesEventFile, bool skipInit = false) &nbsp;</strong> <br/>
 813 initialize for hard-process collisions fed in from an external file
 814 with events, written according to the
 815 <a href="LesHouchesAccord.html" target="page">Les Houches Event File</a>
 816 standard.
 817 <br/><code>argument</code><strong> LesHouchesEventFile </strong>  :
 818 the file name (including path, where required) where the
 819 events are stored, including relevant information on beam
 820 identities and energies.
 821
 822 <br/><code>argument</code><strong> skipInit </strong> (<code>default = <strong>false</strong></code>) :
 823 By default this method does a complete reinitialization of the
 824 generation process. If you set this argument to true then
 825 no reinitialization will occur, only the pointer to the event
 826 file is updated. This may come in handy if the full event sample
 827 is split across several files generated under the same conditions
 828 (except random numbers, of course). You then do the first
 829 initialization with the default, and all subsequent ones with
 830 true. Note that things may go wrong if the files are not created
 831 under the same conditions.
 832
 833 <br/><b>Note:</b> The method returns false if the
 834 initialization fails. It is then not possible to generate any
 835 events.
 836
 837
 838 <a name="method17"></a>
 839 <p/><strong>bool Pythia::init() &nbsp;</strong> <br/>
 840 initialize for collisions, in any of the four above possibilities.
 841 In this option the beams are not specified by input arguments,
 842 but instead by the settings in the
 843 <a href="BeamParameters.html" target="page">Beam Parameters</a> section.
 844 This allows the beams to be specified in the same file as other
 845 run instructions. The default settings give pp collisions at 14 TeV.
 846 <br/><b>Note:</b> The method returns false if the
 847 initialization fails. It is then not possible to generate any
 848 events.
 849
 850
 851 <a name="method18"></a>
 852 <p/><strong>bool Pythia::init( LHAup* lhaUpPtr) &nbsp;</strong> <br/>
 853 initialize for hard-process collisions fed in from an external
 854 source of events, consistent with the Les Houches Accord standard.
 855 The rules for constructing your own class from the <code>LHAup</code>
 856 base class are described <a href="LesHouchesAccord.html" target="page">here</a>.
 857 This class is also required to provide the beam parameters.
 858 <br/><code>argument</code><strong> lhaUpPtr </strong>  :
 859 pointer to a <code>LHAup</code>-derived object. This object
 860 must be instantiated by you in your program.
 861
 862 <br/><b>Note:</b> The method returns false if the
 863 initialization fails. It is then not possible to generate any
 864 events.
 865
 866
 867 <h3>Generate events</h3>
 868
 869 The <code>next()</code> method is the main one to generate events.
 870 In this section we also put a few other specialized methods that
 871 may be useful in some circumstances.
 872
 873 <a name="method19"></a>
 874 <p/><strong>bool Pythia::next() &nbsp;</strong> <br/>
 875 generate the next event. No input parameters are required; all
 876 instructions have already been set up in the initialization stage.
 877 <br/><b>Note:</b> The method returns false if the event generation
 878 fails. The event record is then not consistent and should not be
 879 studied. When reading in hard collisions from a Les Houches Event File
 880 the problem may be that the end of the file has been reached. This
 881 can be checked with the
 882 <code><a href="EventInformation.html" target="page">Info::atEndOfFile()</a></code>
 883 method.
 884
 885
 886 <a name="method20"></a>
 887 <p/><strong>bool Pythia::forceHadronLevel() &nbsp;</strong> <br/>
 888 hadronize the existing event record, i.e. perform string fragmentation
 889 and particle decays. There are two main applications. Firstly,
 890 you can use the same parton-level content as a basis for repeated
 891 hadronization attempts, in schemes intended to save computer time.
 892 Secondly, you may have an external program that can simulate the full
 893 partonic level of the event - hard process, parton showers, multiple
 894 interactions, beam remnants, colour flow, and so on - but not
 895 hadronization. Further details are found
 896 <a href="HadronLevelStandalone.html" target="page">here</a>.
 897 <br/><b>Note:</b> The method returns false if the hadronization
 898 fails. The event record is then not consistent and should not be
 899 studied.
 900
 901
 902 <a name="method21"></a>
 903 <p/><strong>bool Pythia::moreDecays() &nbsp;</strong> <br/>
 904 perform decays of all particles in the event record that have not been
 905 decayed but should have been done so. This can be used e.g. for
 906 repeated decay attempts, in schemes intended to save computer time.
 907 Further details are found <a href="HadronLevelStandalone.html" target="page">here</a>.
 908 <br/><b>Note:</b> The method returns false if the decays fail. The
 909 event record is then not consistent and should not be studied.
 910
 911
 912 <a name="method22"></a>
 913 <p/><strong>void Pythia::LHAeventList(ostream& os = cout) &nbsp;</strong> <br/>
 914 list the Les Houches Accord information on the current event, see
 915 <code><a href="LesHouchesAccord.html" target="page">LHAup::listEvent(...)</a></code>.
 916 (Other listings are available via the class members below, so this
 917 listing is a special case that would not fit elsewhere.)
 918 <br/><code>argument</code><strong> os </strong> (<code>default = <strong>cout</strong></code>) :
 919 output stream where the listing occurs.
 920
 921
 922
 923 <a name="method23"></a>
 924 <p/><strong>bool Pythia::LHAeventSkip(int nSkip) &nbsp;</strong> <br/>
 925 skip ahead a number of events in the Les Houches generation
 926 sequence, without doing anything further with them, see
 927 <code><a href="LesHouchesAccord.html" target="page">LHAup::skipEvent(nSkip)</a></code>.
 928 Mainly intended for debug purposes, e.g. when an event at a known
 929 location in a Les Houches Event File is causing problems.
 930 <br/><code>argument</code><strong> nSkip </strong>  :
 931 number of events to skip.
 932
 933 <br/><b>Note:</b> The method returns false if the operation fails,
 934 specifically if the end of a LHEF has been reached, cf.
 935 <code>next()</code> above.
 936
 937
 938 <h3>Finalize</h3>
 939
 940 There is no required finalization step; you can stop generating events
 941 when and how you want. It is still recommended that you make it a
 942 routine to call the following method at the end.
 943
 944 <a name="method24"></a>
 945 <p/><strong>void Pythia::statistics(bool all = false, bool reset = false) &nbsp;</strong> <br/>
 946 list statistics on the event generation, specifically total and partial
 947 cross sections and the number of different errors. For more details see
 948 <a href="EventStatistics.html" target="page">here</a>.
 949 <br/><code>argument</code><strong> all </strong> (<code>default = <strong>false</strong></code>) :
 950 if true also statistics on multiple interactions is shown, by default not.
 951
 952 <br/><code>argument</code><strong> reset </strong> (<code>default = <strong>false</strong></code>) :  if true then all counters,
 953 e.g on events generated and errors experienced, are reset to zero
 954  whenever the routine is called. The default instead is that
 955 all stored statistics information is unaffected by the call. Counters
 956 are automatically reset in each new <code>Pythia::init(...)</code>
 957 call, however, so the only time the <code>reset</code> option makes a
 958 difference is if <code>statistics(...)</code> is called several times
 959 in a (sub)run.
 960
 961
 962
 963 <h3>Interrogate settings</h3>
 964
 965 Normally settings are used in the setup and initialization stages
 966 to determine the character of a run, e.g. read from a file with the
 967 above-described <code>Pythia::readFile(...)</code> method.
 968 There is no strict need for a user to interact with the
 969 <code>Settings</code> database in any other way. However, as an option,
 970 some settings variables have been left free for the user to set in
 971 such a file, and then use in the main program to directly affect the
 972 performance of that program, see
 973 <a href="MainProgramSettings.html" target="page">here</a>. A typical example would
 974 be the number of events to generate. For such applications the
 975 following shortcuts to some <code>Settings</code> methods may be
 976 convenient.
 977
 978 <a name="method25"></a>
 979 <p/><strong>bool Pythia::flag(string key) &nbsp;</strong> <br/>
 980 read in a boolean variable from the <code>Settings</code> database.
 981 <br/><code>argument</code><strong> key </strong>  :
 982 the name of the variable to be read.
 983
 984
 985
 986 <a name="method26"></a>
 987 <p/><strong>int Pythia::mode(string key) &nbsp;</strong> <br/>
 988 read in an integer variable from the <code>Settings</code> database.
 989 <br/><code>argument</code><strong> key </strong>  :
 990 the name of the variable to be read.
 991
 992
 993
 994 <a name="method27"></a>
 995 <p/><strong>double Pythia::parm(string key) &nbsp;</strong> <br/>
 996 read in a double-precision variable from the <code>Settings</code>
 997 database.
 998 <br/><code>argument</code><strong> key </strong>  :
 999 the name of the variable to be read.
1000
1001
1002
1003 <a name="method28"></a>
1004 <p/><strong>string Pythia::word(string key) &nbsp;</strong> <br/>
1005 read in a string variable from the <code>Settings</code> database.
1006 <br/><code>argument</code><strong> key </strong>  :
1007 the name of the variable to be read.
1008
1009
1010
1011 <h3>Data members</h3>
1012
1013 The <code>Pythia</code> class contains a few public data members,
1014 several of which play a central role. We list them here, with
1015 links to the places where they are further described.
1016
1017 <a name="method29"></a>
1018 <p/><strong>Event Pythia::process &nbsp;</strong> <br/>
1019 the hard-process event record, see <a href="EventRecord.html" target="page">here</a>
1020 for further details.
1021
1022
1023 <a name="method30"></a>
1024 <p/><strong>Event Pythia::event &nbsp;</strong> <br/>
1025 the complete event record, see <a href="EventRecord.html" target="page">here</a>
1026 for further details.
1027
1028
1029 <a name="method31"></a>
1030 <p/><strong>Info Pythia::info &nbsp;</strong> <br/>
1031 further information on the event-generation process, see
1032 <a href="EventInformation.html" target="page">here</a> for further details.
1033
1034
1035 <a name="method32"></a>
1036 <p/><strong>Settings Pythia::settings &nbsp;</strong> <br/>
1037 the settings database, see <a href="SettingsScheme.html" target="page">here</a>
1038 for further details.
1039
1040
1041 <a name="method33"></a>
1042 <p/><strong>ParticleData Pythia::particleData &nbsp;</strong> <br/>
1043 the particle properties and decay tables database, see
1044 <a href="ParticleDataScheme.html" target="page">here</a> for further details.
1045
1046
1047 <a name="method34"></a>
1048 <p/><strong>Rndm Pythia::rndm &nbsp;</strong> <br/>
1049 the random number generator, see <a href="RandomNumberSeed.html" target="page">here</a>
1050 and <a href="RandomNumbers.html" target="page">here</a> for further details.
1051
1052
1053 <a name="method35"></a>
1054 <p/><strong>CoupSM Pythia::coupSM &nbsp;</strong> <br/>
1055 Standard Model couplings and mixing matrices, see
1056 <a href="StandardModelParameters.html" target="page">here</a> for further details.
1057
1058
1059 <a name="method36"></a>
1060 <p/><strong>SusyLesHouches Pythia::slha &nbsp;</strong> <br/>
1061 parameters and particle data in the context of supersymmetric models,
1062 see <a href="SUSYLesHouchesAccord.html" target="page">here</a> for further details.
1063
1064
1065 <a name="method37"></a>
1066 <p/><strong>PartonSystems Pythia::partonSystems &nbsp;</strong> <br/>
1067 a grouping of the partons in the event record by subsystem,
1068 see <a href="AdvancedUsage.html" target="page">here</a> for further details.
1069
1070
1071 </body>
1072 </html>
1073
1074 <!-- Copyright (C) 2010 Torbjorn Sjostrand -->