PYTHIA8/pythia8145/phpdoc/LesHouchesAccord.php

   1 <html>
   2 <head>
   3 <title>Les Houches Accord</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 <script language=javascript type=text/javascript>
  10 function stopRKey(evt) {
  11 var evt = (evt) ? evt : ((event) ? event : null);
  12 var node = (evt.target) ? evt.target :((evt.srcElement) ? evt.srcElement : null);
  13 if ((evt.keyCode == 13) && (node.type=="text"))
  14 {return false;}
  15 }
  16
  17 document.onkeypress = stopRKey;
  18 </script>
  19 <?php
  20 if($_POST['saved'] == 1) {
  21 if($_POST['filepath'] != "files/") {
  22 echo "<font color='red'>SETTINGS SAVED TO FILE</font><br/><br/>"; }
  23 else {
  24 echo "<font color='red'>NO FILE SELECTED YET.. PLEASE DO SO </font><a href='SaveSettings.php'>HERE</a><br/><br/>"; }
  25 }
  26 ?>
  27
  28 <form method='post' action='LesHouchesAccord.php'>
  29
  30 <h2>Les Houches Accord</h2>
  31
  32 The Les Houches Accord (LHA) for user processes [<a href="Bibliography.php" target="page">Boo01</a>] is the
  33 standard way to input parton-level information from a
  34 matrix-elements-based generator into PYTHIA. The conventions for
  35 which information should be stored has been defined in a Fortran context,
  36 as two commonblocks. Here a C++ equivalent is defined, as a single class.
  37
  38 <p/>
  39 The <code>LHAup</code> class is a base class, containing reading and
  40 printout functions, plus two pure virtual functions, one to set
  41 initialization information and one to set information on each new event.
  42 Derived classes have to provide these two virtual functions to do
  43 the actual work. The existing derived classes are for reading information
  44 from a Les Houches Event File (LHEF), from the respective Fortran
  45 commonblocks, or from PYTHIA 8 itself.
  46
  47 <p/>
  48 You are free to write your own derived classes, using the rules and
  49 methods to be described below. Normally, pointers to objects of such
  50 derived classes should be handed in with the
  51 <code><?php $filepath = $_GET["filepath"];
  52 echo "<a href='ProgramFlow.php?filepath=".$filepath."' target='page'>";?>Pythia::init( LHAup*)</a></code>
  53 method. However, with the LHEF format a filename can replace the
  54 pointer, see further below.
  55
  56 <p/>
  57 Let us now describe the methods at your disposal to do the job.
  58
  59 <a name="method1"></a>
  60 <p/><strong>LHAup::LHAup( int strategy = 3) &nbsp;</strong> <br/>
  61 the base class constructor takes the choice of mixing/weighting
  62 strategy as optional input argument, and calls <code>setStrategy</code>,
  63 see below. It also reserves some space for processes and particles.
  64
  65
  66 <a name="method2"></a>
  67 <p/><strong>virtual LHAup::~LHAup() &nbsp;</strong> <br/>
  68 the destructor does not need to do anything.
  69
  70
  71 <a name="method3"></a>
  72 <p/><strong>void LHAup::setPtr(Info* infoPtr) &nbsp;</strong> <br/>
  73 this method only sets the pointer that allows some information
  74 to be accessed, and is automatically called by
  75 <code>Pythia::init(...)</code>.
  76
  77
  78 <h3>Initialization</h3>
  79
  80 The <code>LHAup</code> class stores information equivalent to the
  81 <code>/HEPRUP/</code> commonblock, as required to initialize the event
  82 generation chain. The main difference is that the vector container
  83 now allows a flexible number of subprocesses to be defined. For the
  84 rest, names have been modified, since the 6-character-limit does not
  85 apply, and variables have been regrouped for clarity, but nothing
  86 fundamental is changed.
  87
  88 <a name="method4"></a>
  89 <p/><strong>virtual bool LHAup::setInit() &nbsp;</strong> <br/>
  90 this pure virtual method has to be implemented in the derived class,
  91 to set relevant information when called. It should return false if it
  92 fails to set the info.
  93
  94
  95 <p/>
  96 Inside <code>setInit()</code>, such information can be set by the following
  97 methods:
  98 <a name="method5"></a>
  99 <p/><strong>void LHAup::setBeamA( int identity, double energy, int pdfGroup, int pdfSet) &nbsp;</strong> <br/>
 100
 101 <strong>void LHAup::setBeamB( int identity, double energy, int pdfGroup, int pdfSet) &nbsp;</strong> <br/>
 102 sets the properties of the first and second incoming beam, respectively
 103 (cf. the Fortran <code>IDBMUP(1), EBMUP(i), PDFGUP(i), PDFSUP(i)</code>,
 104 with <code>i</code> 1 or 2). The parton distribution information
 105 defaults to zero. These numbers can be used to tell which PDF sets were
 106 used when the hard process was generated, while the normal
 107 <?php $filepath = $_GET["filepath"];
 108 echo "<a href='PDFSelection.php?filepath=".$filepath."' target='page'>";?>PDF Selection</a> is used for the further
 109 event generation in PYTHIA.
 110
 111
 112 <a name="method6"></a>
 113 <p/><strong>void LHAup::setStrategy( int strategy) &nbsp;</strong> <br/>
 114 sets the event weighting and cross section strategy. The default,
 115 provided in the class constructor, is 3, which is the natural value
 116 e.g. for an LHEF.
 117 <br/><code>argument</code><strong> strategy </strong>  :
 118 chosen strategy (cf. <code>IDWTUP</code>; see [<a href="Bibliography.php" target="page">Sjo06</a>]
 119 section 9.9.1 for extensive comments).
 120 <br/><code>argumentoption </code><strong> 1</strong> :  events come with non-negative weight, given in units
 121 of pb, with an average that converges towards the cross section of the
 122 process. PYTHIA is in charge of the event mixing, i.e. for each new
 123 try decides which process should be generated, and then decides whether
 124 is should be kept, based on a comparison with <code>xMax</code>.
 125 Accepted events therefore have unit weight.
 126 <br/><code>argumentoption </code><strong> -1</strong> :  as option 1, except that cross sections can now be
 127 negative and events after unweighting have weight +-1. You can use
 128 <code><?php $filepath = $_GET["filepath"];
 129 echo "<a href='EventInformation.php?filepath=".$filepath."' target='page'>";?>Info::weight()</a></code>
 130 to find the weight of the current event. A correct event mixing requires
 131 that a process that can take both signs should be split in two, one limited
 132 to positive or zero and the other to negative or zero values, with
 133 <code>xMax</code> chosen appropriately for the two.
 134 <br/><code>argumentoption </code><strong> 2</strong> :  events come with non-negative weight, in unspecified
 135 units, but such that <code>xMax</code> can be used to unweight the events
 136 to unit weight. Again PYTHIA is in charge of the event mixing.
 137 The total cross section of a process is stored in
 138 <code>xSec</code>.
 139 <br/><code>argumentoption </code><strong> -2</strong> :  as option 2, except that cross sections can now be
 140 negative and events after unweighting have weight +-1. As for option -1
 141 processes with indeterminate sign should be split in two.
 142 <br/><code>argumentoption </code><strong> 3</strong> :  events come with unit weight, and are thus accepted
 143 as is. The total cross section of the process is stored in
 144 <code>xSec</code>.
 145 <br/><code>argumentoption </code><strong> -3</strong> :  as option 3, except that events now come with weight
 146 +-1. Unlike options -1 and -2 processes with indeterminate sign need not be
 147 split in two, unless you intend to mix with internal PYTHIA processes
 148 (see below).
 149 <br/><code>argumentoption </code><strong> 4</strong> :  events come with non-negative weight, given in units
 150 of pb, with an average that converges towards the cross section of the
 151 process, like for option 1. No attempt is made to unweight the events,
 152 however, but all are generated in full, and retain their original weight.
 153 For consistency with normal PYTHIA units, the weight stored in
 154 <code>Info::weight()</code> has been converted to mb, however.
 155
 156 <br/><code>argumentoption </code><strong> -4</strong> :  as option 4, except that events now can come
 157 either with positive or negative weights.
 158 <br/><b>Note 1</b>: if several processes have already been mixed and
 159 stored in a common event file, either LHEF or some private format, it
 160 would be problematical to read back events in a different order. Since it
 161 is then not feasible to let PYTHIA pick the next process type, strategies
 162 +-1 and +-2 would not work. Instead strategy 3 would be the recommended
 163 choice, or -3 if negative-weight events are required.
 164 <br/><b>Note 2</b>: it is possible to switch on internally implemented
 165 processes and have PYTHIA mix these with LHA ones according to their relative
 166 cross sections for strategies +-1, +-2 and 3. It does not work for strategy
 167 -3 unless the positive and negative sectors of the cross sections are in
 168 separate subprocesses (as must always be the case for -1 and -2), since
 169 otherwise the overall mixture of PYTHIA and LHA processes will be off.
 170 Mixing is not possible for strategies +-4, since the weighting procedure
 171 is not specified by the standard. (For instance, the intention may be to
 172 have events biased towards larger <i>pT</i> values in some particular
 173 functional form.)
 174
 175
 176
 177 <a name="method7"></a>
 178 <p/><strong>void LHAup::addProcess( int idProcess, double xSec, double xErr, double xMax) &nbsp;</strong> <br/>
 179 sets info on an allowed process (cf. <code>LPRUP, XSECUP, XERRUP,
 180 XMAXUP</code>).
 181 Each new call will append one more entry to the list of processes.
 182 The choice of strategy determines which quantities are mandatory:
 183 <code>xSec</code> for strategies +-2 and +-3,
 184 <code>xErr</code> never, and
 185 <code>xMax</code> for strategies +-1 and +-2.
 186
 187
 188 <br/><b>Note</b>: PYTHIA does not make active use of the (optional)
 189 <code>xErr</code> values, but calculates a statistical cross section
 190 error based on the spread of event-to-event weights. This should work
 191 fine for strategy options +-1, but not for the others. Specifically,
 192 for options +-2 and +-3 the weight spread may well vanish, and anyway
 193 is likely to be an underestimate of the true error. If the author of the
 194 LHA input information does provide error information you may use that -
 195 this information is displayed at initialization. If not, then a relative
 196 error decreasing like <i>1/sqrt(n_acc)</i>, where <i>n_acc</i>
 197 is the number of accepted events, should offer a reasonable estimate.
 198
 199 <a name="method8"></a>
 200 <p/><strong>void LHAup::setXSec( int i, double xSec) &nbsp;</strong> <br/>
 201 update the <code>xSec</code> value of the <code>i</code>'th process
 202 added with <code>addProcess</code> method (i.e. <code>i</code> runs
 203 from 0 through <code>sizeProc() - 1</code>, see below).
 204
 205
 206 <a name="method9"></a>
 207 <p/><strong>void LHAup::setXErr( int i, double xErr) &nbsp;</strong> <br/>
 208 update the <code>xErr</code> value of the <code>i</code>'th process
 209 added with <code>addProcess</code> method.
 210
 211
 212 <a name="method10"></a>
 213 <p/><strong>void LHAup::setXMax( int i, double xMax) &nbsp;</strong> <br/>
 214 update the <code>xMax</code> value of the <code>i</code>'th process
 215 added with <code>addProcess</code> method.
 216
 217
 218 <p/>
 219 Information is handed back by the following methods
 220 (that normally you would not need to touch):
 221 <a name="method11"></a>
 222 <p/><strong>int LHAup::idBeamA() &nbsp;</strong> <br/>
 223
 224 <strong>int LHAup::idBeamB() &nbsp;</strong> <br/>
 225
 226 <strong>double LHAup::eBeamA() &nbsp;</strong> <br/>
 227
 228 <strong>double LHAup::eBeamB() &nbsp;</strong> <br/>
 229
 230 <strong>int LHAup::pdfGroupBeamA() &nbsp;</strong> <br/>
 231
 232 <strong>int LHAup::pdfGroupBeamB() &nbsp;</strong> <br/>
 233
 234 <strong>int LHAup::pdfSetBeamA() &nbsp;</strong> <br/>
 235
 236 <strong>int LHAup::pdfSetBeamB() &nbsp;</strong> <br/>
 237 for the beam properties.
 238
 239 <a name="method12"></a>
 240 <p/><strong>int LHAup::strategy() &nbsp;</strong> <br/>
 241 for the strategy choice.
 242
 243 <a name="method13"></a>
 244 <p/><strong>int LHAup::sizeProc() &nbsp;</strong> <br/>
 245 for the number of subprocesses.
 246
 247 <a name="method14"></a>
 248 <p/><strong>int LHAup::idProcess(i) &nbsp;</strong> <br/>
 249
 250 <strong>double LHAup::xSec(i) &nbsp;</strong> <br/>
 251
 252 <strong>double LHAup::xErr(i) &nbsp;</strong> <br/>
 253
 254 <strong>double LHAup::xMax(i) &nbsp;</strong> <br/>
 255 for process <code>i</code> in the range <code>0 &lt;= i &lt;
 256 sizeProc()</code>.
 257
 258
 259 <a name="method15"></a>
 260 <p/><strong>void LHAup::listInit(ostream& os = cout) &nbsp;</strong> <br/>
 261 prints the above initialization information. This method is
 262 automatically called from <code>Pythia::init(...)</code>,
 263 so would normally not need to be called directly by the user.
 264
 265
 266 <h3>Event input</h3>
 267
 268 The <code>LHAup</code> class also stores information equivalent to the
 269 <code>/HEPEUP/</code> commonblock, as required to hand in the next
 270 parton-level configuration for complete event generation. The main
 271 difference is that the vector container now allows a flexible number
 272 of partons to be defined. For the rest, names have been modified,
 273 since the 6-character-limit does not apply, and variables have been
 274 regrouped for clarity, but nothing fundamental is changed.
 275
 276 <p/>
 277 The LHA standard is based on Fortran arrays beginning with
 278 index 1, and mother information is defined accordingly. In order to
 279 be compatible with this convention, the zeroth line of the C++ particle
 280 array is kept empty, so that index 1 also here corresponds to the first
 281 particle. One small incompatibility is that the <code>sizePart()</code>
 282 method returns the full size of the particle array, including the
 283 empty zeroth line, and thus is one larger than the true number of
 284 particles (<code>NUP</code>).
 285
 286 <a name="method16"></a>
 287 <p/><strong>virtual bool LHAup::setEvent(int idProcess = 0) &nbsp;</strong> <br/>
 288 this pure virtual method has to be implemented in the derived class,
 289 to set relevant information when called. For strategy options +-1
 290 and +-2 the input <code>idProcess</code> value specifies which process
 291 that should be generated, while <code>idProcess</code> is irrelevant
 292 for strategies +-3 and +-4. The method should return false if it fails
 293 to set the info, i.e. normally that the supply of events in a file is
 294 exhausted. If so, no event is generated, and <code>Pythia::next()</code>
 295 returns false. You can then interrogate
 296 <code><?php $filepath = $_GET["filepath"];
 297 echo "<a href='EventInformation.php?filepath=".$filepath."' target='page'>";?>Info::atEndOfFile()</a></code>
 298 to confirm that indeed the failure is caused in this method, and decide
 299 to break out of the event generation loop.
 300
 301 <p/>
 302 Inside a normal <code>setEvent(...)</code> call, information can be set
 303 by the following methods:
 304 <a name="method17"></a>
 305 <p/><strong>void LHAup::setProcess( int idProcess, double weight, double scale, double alphaQED, double alphaQCD) &nbsp;</strong> <br/>
 306 tells which kind of process occured, with what weight, at what scale,
 307 and which <i>alpha_EM</i> and <i>alpha_strong</i> were used
 308 (cf. <code>IDPRUP, XWTGUP, SCALUP, AQEDUP, AQCDUP</code>). This method
 309 also resets the size of the particle list, and adds the empty zeroth
 310 line, so it has to be called before the <code>addParticle</code> method below.
 311
 312 <a name="method18"></a>
 313 <p/><strong>void LHAup::addParticle( int id, int status, int mother1, int mother2, int colourTag1, int colourTag2, double p_x, double p_y, double p_z, double e, double m, double tau, double spin) &nbsp;</strong> <br/>
 314 gives the properties of the next particle handed in (cf. <code>IDUP, ISTUP,
 315 MOTHUP(1,..), MOTHUP(2,..), ICOLUP(1,..), ICOLUP(2,..),  PUP(J,..),
 316 VTIMUP, SPINUP</code>) .
 317
 318
 319 <p/>
 320 Information is handed back by the following methods:
 321 <a name="method19"></a>
 322 <p/><strong>int LHAup::idProcess() &nbsp;</strong> <br/>
 323 process number.
 324
 325
 326 <a name="method20"></a>
 327 <p/><strong>double LHAup::weight() &nbsp;</strong> <br/>
 328 Note that the weight stored in <code>Info::weight()</code> as a rule
 329 is not the same as the above <code>weight()</code>: the method here gives
 330 the value before unweighting while the one in <code>info</code> gives
 331 the one after unweighting and thus normally is 1 or -1. Only with strategy
 332 options +-3 and +-4 would the value in <code>info</code> be the same as
 333 here, except for a conversion from pb to mb for +-4.
 334
 335
 336 <a name="method21"></a>
 337 <p/><strong>double LHAup::scale() &nbsp;</strong> <br/>
 338
 339 <strong>double LHAup::alphaQED() &nbsp;</strong> <br/>
 340
 341 <strong>double LHAup::alphaQCD() &nbsp;</strong> <br/>
 342 scale and couplings at that scale.
 343
 344
 345 <a name="method22"></a>
 346 <p/><strong>int LHAup::sizePart() &nbsp;</strong> <br/>
 347 the size of the particle array, which is one larger than the number
 348 of particles in the event, since the zeroth entry is kept empty
 349 (see above).
 350
 351
 352 <a name="method23"></a>
 353 <p/><strong>int LHAup::id(int i) &nbsp;</strong> <br/>
 354
 355 <strong>int LHAup::status(int i) &nbsp;</strong> <br/>
 356
 357 <strong>int LHAup::mother1(int i) &nbsp;</strong> <br/>
 358
 359 <strong>int LHAup::mother2(int i) &nbsp;</strong> <br/>
 360
 361 <strong>int LHAup::col1(int i) &nbsp;</strong> <br/>
 362
 363 <strong>int LHAup::col2(int i) &nbsp;</strong> <br/>
 364
 365 <strong>double LHAup::px(int i) &nbsp;</strong> <br/>
 366
 367 <strong>double LHAup::py(int i) &nbsp;</strong> <br/>
 368
 369 <strong>double LHAup::pz(int i) &nbsp;</strong> <br/>
 370
 371 <strong>double LHAup::e(int i) &nbsp;</strong> <br/>
 372
 373 <strong>double LHAup::m(int i) &nbsp;</strong> <br/>
 374
 375 <strong>double LHAup::tau(int i) &nbsp;</strong> <br/>
 376
 377 <strong>double LHAup::spin(int i) &nbsp;</strong> <br/>
 378 for particle <code>i</code> in the range
 379 <code>0 &lt;= i &lt; sizePart()</code>. (But again note that
 380 <code>i = 0</code> is an empty line, so the true range begins at 1.)
 381
 382
 383 <p/>
 384 In the LHEF description [<a href="Bibliography.php" target="page">Alw06</a>] an extension to
 385 include information on the parton densities of the colliding partons
 386 is suggested. This optional further information can be set by
 387 <a name="method24"></a>
 388 <p/><strong>void LHAup::setPdf( int id1, int id2, double x1, double x2, double scalePDF, double xpdf1, double xpdf2) &nbsp;</strong> <br/>
 389 which gives the flavours , the <i>x</i> and the <ie>Q</i> scale
 390 (in GeV) at which the parton densities <i>x*f_i(x, Q)</i> have been
 391 evaluated.
 392
 393
 394 <p/>
 395 This information is returned by the methods
 396 <a name="method25"></a>
 397 <p/><strong>bool LHAup::pdfIsSet() &nbsp;</strong> <br/>
 398
 399 <strong>int LHAup::id1() &nbsp;</strong> <br/>
 400
 401 <strong>int LHAup::id2() &nbsp;</strong> <br/>
 402
 403 <strong>double LHAup::x1() &nbsp;</strong> <br/>
 404
 405 <strong>double LHAup::x2() &nbsp;</strong> <br/>
 406
 407 <strong>double LHAup::scalePDF() &nbsp;</strong> <br/>
 408
 409 <strong>double LHAup::xpdf1() &nbsp;</strong> <br/>
 410
 411 <strong>double LHAup::xpdf2() &nbsp;</strong> <br/>
 412 where the first one tells whether this optional information has been set
 413 for the current event. (<code>setPdf(...)</code> must be called after the
 414 <code>setProcess(...)</code> call of the event for this to work.)
 415
 416
 417 <p/>
 418 <a name="method26"></a>
 419 <p/><strong>void LHAup::listEvent(ostream& os = cout) &nbsp;</strong> <br/>
 420 prints the above information for the current event.  In cases where the
 421 <code>LHAup</code> object is not available to the user, the
 422 <code>Pythia::LHAeventList(ostream& os = cout)</code> method can
 423 be used, which is a wrapper for the above.
 424
 425
 426 <a name="method27"></a>
 427 <p/><strong>virtual bool LHAup::skipEvent(int nSkip) &nbsp;</strong> <br/>
 428 skip ahead <code>nSkip</code> events in the Les Houches generation
 429 sequence, without doing anything further with them. Mainly
 430 intended for debug purposes, e.g. when an event at a known
 431 location in a Les Houches Event File is causing problems.
 432 Will return false if operation fails, specifically if the
 433 end of an LHEF has been reached. The implementation in the base class
 434 simply executes <code>setEvent()</code> the requested number of times.
 435 The derived <code>LHAupLHEF</code> class (see below) only uses the
 436 <code>setNewEventLHEF(...)</code> part of its <code>setEvent()</code>
 437 method, and other derived classes could choose other shortcuts.
 438
 439
 440 <p/>
 441 The LHA expects the decay of resonances to be included as part of the
 442 hard process, i.e. if unstable particles are produced in a process then
 443 their decays are also described. This includes <i>Z^0, W^+-, H^0</i>
 444 and other short-lived particles in models beyond the Standard Model.
 445 Should this not be the case then PYTHIA will perform the decays of all
 446 resonances it knows how to do, in the same way as for internal processes.
 447 Note that you will be on slippery ground if you then restrict the decay of
 448 these resonances to specific allowed channels since, if this is not what
 449 was intended, you will obtain the wrong cross section and potentially the
 450 wrong mix of different event types. (Since the original intention is
 451 unknown, the cross section will not be corrected for the fraction of
 452 open channels, i.e. the procedure used for internal processes is not
 453 applied in this case.)
 454
 455 <h3>An interface to Les Houches Event Files</h3>
 456
 457 The LHEF standard [<a href="Bibliography.php" target="page">Alw06</a>] specifies a format where a single file
 458 packs initialization and event information. This has become the most
 459 frequently used procedure to process external parton-level events in
 460 Pythia. Therefore a special
 461 <code><?php $filepath = $_GET["filepath"];
 462 echo "<a href='ProgramFlow.php?filepath=".$filepath."' target='page'>";?>Pythia::init(fileName)</a></code>
 463 initialization option exists, where the LHEF name is provided as input.
 464 Internally this name is then used to create an instance of the derived
 465 class <code>LHAupLHEF</code>, which can do the job of reading an LHEF.
 466
 467 <p/>
 468 An example how to generate events from an LHEF is found in
 469 <code>main12.cc</code>. Note the use of
 470 <code>Info::atEndOfFile()</code> to find out when the whole
 471 LHEF has been processed.
 472
 473 <p/>
 474 To allow the sequential use of several event files the
 475 <code>Pythia::init(...)</code> method has an optional second argument:
 476 <code>Pythia::init(fileName, bool skipInit = false)</code>.
 477 If called with this argument <code>true</code> then there will be no
 478 initialization, except that the existing <code>LHAupLHEF</code> class
 479 instance will be deleted and replaced by ones pointing to the new file.
 480 It is assumed (but never checked) that the initialization information is
 481 identical, and that the new file simply contains further events of
 482 exactly the same kind as the previous one. An example of this possibility,
 483 and the option to mix with internal processes, is found in
 484 <code>main13.cc</code>.
 485
 486 <p/>
 487 The workhorses of the <code>LHAupLHEF</code> class are three methods
 488 found in the base class, so as to allow them to be reused in other
 489 contexts. Specifically, it allows derived classes where one parton-level
 490 configuration can be reused several times, e.g. in the context of
 491 matrix-element-to-parton-shower matching (example in preparation).
 492 To begin with also a small utility routine.
 493
 494 <a name="method28"></a>
 495 <p/><strong>bool LHAup::fileFound() &nbsp;</strong> <br/>
 496 always returns true in the base class, but in <code>LHAupLHEF</code>
 497 it returns false if the LHEF provided in the constructor is not
 498 found and opened correctly.
 499
 500
 501 <a name="method29"></a>
 502 <p/><strong>bool LHAup::setInitLHEF(ifstream& is) &nbsp;</strong> <br/>
 503 read in and set all required initialization information from the
 504 specified stream. Return false if it fails.
 505
 506
 507 <a name="method30"></a>
 508 <p/><strong>bool LHAup::setNewEventLHEF(ifstream& is) &nbsp;</strong> <br/>
 509 read in event information from the specified stream into a staging area
 510 where it can be reused by <code>setOldEventLHEF</code>.
 511
 512
 513 <a name="method31"></a>
 514 <p/><strong>bool LHAup::setOldEventLHEF() &nbsp;</strong> <br/>
 515 store the event information from the staging area into the normal
 516 location. Thus a single <code>setNewEventLHEF</code> call can be
 517 followed by several <code>setOldEventLHEF</code> ones, so as to
 518 process the same configuration several times. This method currently
 519 only returns true, i.e. any errors should be caught by the preceding
 520 <code>setNewEventLHEF</code> call.
 521
 522
 523
 524 <h3>A runtime Fortran interface</h3>
 525
 526 The runtime Fortran interface requires linking to an external Fortran
 527 code. In order to avoid problems with unresolved external references
 528 when this interface is not used, the code has been put in a separate
 529 <code>LHAFortran.h</code> file, that is not included in any of the
 530 other library files. Instead it should be included in the
 531 user-supplied main program, together with the implementation of two
 532 methods below that call the Fortran program to do its part of the job.
 533
 534 <p/>
 535 The <code>LHAupFortran</code> class derives from <code>LHAup</code>.
 536 It reads initialization and event information from the LHA standard
 537 Fortran commonblocks, assuming these commonblocks behave like two
 538 <code>extern "C" struct</code> named <code>heprup_</code> and
 539 <code>hepeup_</code>. (Note the final underscore, to match how the
 540 gcc compiler internally names Fortran files.)
 541
 542 <p/>
 543 The instantiation does not require any arguments.
 544
 545 <p/>
 546 The user has to supply implementations of the <code>fillHepRup()</code>
 547 and <code>fillHepEup()</code> methods, that is to do the actual calling
 548 of the external Fortran routines that fill the <code>HEPRUP</code> and
 549 <code>HEPEUP</code> commonblocks. The translation of this information to
 550 the C++ structure is provided by the existing <code>setInit()</code> and
 551 <code>setEvent()</code> code.
 552
 553 <p/>
 554 Up to and including version 8.125 the <code>LHAupFortran</code> class
 555 was used to construct a runtime interface to PYTHIA 6.4. This was
 556 convenient in the early days of PYTHIA 8 evolution, when this program
 557 did not yet contain hard-process generation, and the LHEF standard
 558 did not yet exist. Nowadays it is more of a bother, since a full
 559 cross-platform support leads to many possible combinations. Therefore
 560 the support has been reduced in the current version. Only the
 561 <code>main51.cc</code> example remains as an illustration, where the
 562 previously separate interface code
 563 (<code>include/Pythia6Interface.h</code>) has been inserted in the
 564 beginning. You also need to modify the <code>examples/Makefile</code>
 565 to link <code>main51.cc</code> properly also to a PYTHIA 6.4 library
 566 version, see commented-out section for ideas how to to this.
 567
 568 <h3>Methods for LHEF output</h3>
 569
 570 The main objective of the <code>LHAup</code> class is to feed information
 571 from an external program into PYTHIA. It can be used to export information
 572 as well, however. Specifically, there are four routines in the base class
 573 that can be called to write a Les Houches Event File. These should be
 574 called in sequence in order to build up the proper file structure.
 575
 576 <a name="method32"></a>
 577 <p/><strong>bool LHAup::openLHEF(string filename) &nbsp;</strong> <br/>
 578 Opens a file with the filename indicated, and writes a header plus a brief
 579 comment with date and time information.
 580
 581
 582 <a name="method33"></a>
 583 <p/><strong>bool LHAup::initLHEF() &nbsp;</strong> <br/>
 584 Writes initialization information to the file above. Such information should
 585 already have been set with the methods described in the "Initialization"
 586 section above.
 587
 588
 589 <a name="method34"></a>
 590 <p/><strong>bool LHAup::eventLHEF() &nbsp;</strong> <br/>
 591 Writes event information to the file above. Such information should
 592 already have been set with the methods described in the "Event input"
 593 section above. This call should be repeated once for each event to be
 594 stored.
 595
 596
 597 <a name="method35"></a>
 598 <p/><strong>bool LHAup::closeLHEF(bool updateInit = false) &nbsp;</strong> <br/>
 599 Writes the closing tag and closes the file. Optionally, if
 600 <code>updateInit = true</code>, this routine will reopen the file from
 601 the beginning, rewrite the same header as <code>openLHEF()</code> did,
 602 and then call <code>initLHEF()</code> again to overwrite the old
 603 information. This is especially geared towards programs, such as PYTHIA
 604 itself, where the cross section information is not available at the
 605 beginning of the run, but only is obtained by Monte Carlo integration
 606 in parallel with the event generation itself. Then the
 607 <code>setXSec( i, xSec)</code>, <code>setXErr( i, xSec)</code> and
 608 <code>setXMax( i, xSec)</code> can be used to update the relevant
 609 information before <code>closeLHEF</code> is called.
 610 <br/><b>Warning:</b> overwriting the beginning of a file without
 611 upsetting anything is a delicate operation. It only works when the new
 612 lines require exactly as much space as the old ones did. Thus, if you add
 613 another process in between, the file will be corrupted.
 614
 615
 616 <h3>PYTHIA 8 output to an LHEF</h3>
 617
 618 The above methods could be used by any program to write an LHEF.
 619 For PYTHIA 8 to do this, a derived class already exists,
 620 <code>LHAupFromPYTHIA8</code>. In order for it to do its job,
 621 it must gain access to the information produced by PYTHIA,
 622 specifically the <code>process</code> event record and the
 623 generic information stored in <code>info</code>. Therefore, if you
 624 are working with an instance <code>pythia</code> of the
 625 <code>Pythia</code> class, you have to instantiate
 626 <code>LHAupFromPYTHIA8</code> with pointers to the
 627 <code>process</code> and <code>info</code> objects of
 628 <code>pythia</code>:
 629 <br/><code>LHAupFromPYTHIA8 myLHA(&pythia.process, &pythia.info);</code>
 630
 631 <p/>
 632 The method <code>setInit()</code> should be called to store the
 633 <code>pythia</code> initialization information in the LHA object,
 634 and <code>setEvent()</code> to store event information.
 635 Furthermore, <code>updateSigma()</code> can be used at the end
 636 of the run to update cross-section information, cf.
 637 <code>closeLHEF(true)</code> above. An example how the
 638 generation, translation and writing methods should be ordered is
 639 found in <code>main20.cc</code>.
 640
 641 <p/>
 642 Currently there are some limitations, that could be overcome if
 643 necessary. Firstly, you may mix many processes in the same run,
 644 but the cross-section information stored in <code>info</code> only
 645 refers to the sum of them all, and therefore they are all classified
 646 as a common process 9999. Secondly, you should generate your events
 647 in the CM frame of the collision, since this is the assumed frame of
 648 stored Les Houches events, and no boosts have been implemented
 649 for the case that <code>Pythia::process</code> is not in this frame.
 650
 651 </body>
 652 </html>
 653
 654 <!-- Copyright (C) 2010 Torbjorn Sjostrand -->