Update to pythi8.170
[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8170 / htmldoc / LesHouchesAccord.html
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 <h2>Les Houches Accord</h2>
10
11 The Les Houches Accord (LHA) for user processes [<a href="Bibliography.html" target="page">Boo01</a>] is the 
12 standard way to input parton-level information from a 
13 matrix-elements-based generator into PYTHIA. The conventions for 
14 which information should be stored has been defined in a Fortran context, 
15 as two commonblocks. Here a C++ equivalent is defined, as a single class.
16
17 <p/>
18 The <code>LHAup</code> class is a base class, containing reading and 
19 printout functions, plus two pure virtual functions, one to set 
20 initialization information and one to set information on each new event. 
21 Derived classes have to provide these two virtual functions to do 
22 the actual work. The existing derived classes are for reading information 
23 from a Les Houches Event File (LHEF), from the respective Fortran 
24 commonblocks, or from PYTHIA 8 itself. 
25
26 <p/>
27 You are free to write your own derived classes, using the rules and 
28 methods to be described below. Normally, pointers to objects of such 
29 derived classes should be handed in with the 
30 <code><a href="ProgramFlow.html" target="page">Pythia::init( LHAup*)</a></code> 
31 method. However, with the LHEF format a filename can replace the 
32 pointer, see further below. 
33
34 <p/>
35 Let us now describe the methods at your disposal to do the job.
36
37 <a name="method1"></a>
38 <p/><strong>LHAup::LHAup( int strategy = 3) &nbsp;</strong> <br/>
39 the base class constructor takes the choice of mixing/weighting 
40 strategy as optional input argument, and calls <code>setStrategy</code>,
41 see below. It also reserves some space for processes and particles.
42   
43
44 <a name="method2"></a>
45 <p/><strong>virtual LHAup::~LHAup() &nbsp;</strong> <br/>
46 the destructor does not need to do anything.
47   
48
49 <a name="method3"></a>
50 <p/><strong>void LHAup::setPtr(Info* infoPtr) &nbsp;</strong> <br/>
51 this method only sets the pointer that allows some information
52 to be accessed, and is automatically called by 
53 <code>Pythia::init(...)</code>. 
54   
55
56 <h3>Initialization</h3>
57
58 The <code>LHAup</code> class stores information equivalent to the 
59 <code>/HEPRUP/</code> commonblock, as required to initialize the event 
60 generation chain. The main difference is that the vector container 
61 now allows a flexible number of subprocesses to be defined. For the 
62 rest, names have been modified, since the 6-character-limit does not 
63 apply, and variables have been regrouped for clarity, but nothing 
64 fundamental is changed.
65
66 <a name="method4"></a>
67 <p/><strong>virtual bool LHAup::setInit() &nbsp;</strong> <br/>
68 this pure virtual method has to be implemented in the derived class, 
69 to set relevant information when called. It should return false if it 
70 fails to set the info.
71   
72
73 <p/>
74 Inside <code>setInit()</code>, such information can be set by the following 
75 methods:
76 <a name="method5"></a>
77 <p/><strong>void LHAup::setBeamA( int identity, double energy, int pdfGroup, int pdfSet) &nbsp;</strong> <br/>
78   
79 <strong>void LHAup::setBeamB( int identity, double energy, int pdfGroup, int pdfSet) &nbsp;</strong> <br/>
80 sets the properties of the first and second incoming beam, respectively
81 (cf. the Fortran <code>IDBMUP(1), EBMUP(i), PDFGUP(i), PDFSUP(i)</code>,
82 with <code>i</code> 1 or 2). The parton distribution information 
83 defaults to zero. These numbers can be used to tell which PDF sets were 
84 used when the hard process was generated, while the normal 
85 <a href="PDFSelection.html" target="page">PDF Selection</a> is used for the further 
86 event generation in PYTHIA.
87   
88
89 <a name="method6"></a>
90 <p/><strong>void LHAup::setStrategy( int strategy) &nbsp;</strong> <br/>
91 sets the event weighting and cross section strategy. The default, 
92 provided in the class constructor, is 3, which is the natural value 
93 e.g. for an LHEF.
94 <br/><code>argument</code><strong> strategy </strong>  : 
95 chosen strategy (cf. <code>IDWTUP</code>; see [<a href="Bibliography.html" target="page">Sjo06</a>] 
96 section 9.9.1 for extensive comments).
97 <br/><code>argumentoption </code><strong> 1</strong> :  events come with non-negative weight, given in units 
98 of pb, with an average that converges towards the cross section of the
99 process. PYTHIA is in charge of the event mixing, i.e. for each new
100 try decides which process should be generated, and then decides whether
101 is should be kept, based on a comparison with <code>xMax</code>.
102 Accepted events therefore have unit weight.  
103 <br/><code>argumentoption </code><strong> -1</strong> :  as option 1, except that cross sections can now be
104 negative and events after unweighting have weight +-1. You can use 
105 <code><a href="EventInformation.html" target="page">Info::weight()</a></code> 
106 to find the weight of the current event. A correct event mixing requires 
107 that a process that can take both signs should be split in two, one limited 
108 to positive or zero and the other to negative or zero values, with 
109 <code>xMax</code> chosen appropriately for the two.  
110 <br/><code>argumentoption </code><strong> 2</strong> :  events come with non-negative weight, in unspecified 
111 units, but such that <code>xMax</code> can be used to unweight the events
112 to unit weight. Again PYTHIA is in charge of the event mixing.
113 The total cross section of a process is stored in 
114 <code>xSec</code>.  
115 <br/><code>argumentoption </code><strong> -2</strong> :  as option 2, except that cross sections can now be
116 negative and events after unweighting have weight +-1. As for option -1
117 processes with indeterminate sign should be split in two.  
118 <br/><code>argumentoption </code><strong> 3</strong> :  events come with unit weight, and are thus accepted 
119 as is. The total cross section of the process is stored in 
120 <code>xSec</code>.  
121 <br/><code>argumentoption </code><strong> -3</strong> :  as option 3, except that events now come with weight 
122 +-1. Unlike options -1 and -2 processes with indeterminate sign need not be 
123 split in two, unless you intend to mix with internal PYTHIA processes 
124 (see below).  
125 <br/><code>argumentoption </code><strong> 4</strong> :  events come with non-negative weight, given in units 
126 of pb, with an average that converges towards the cross section of the
127 process, like for option 1. No attempt is made to unweight the events, 
128 however, but all are generated in full, and retain their original weight.
129 For consistency with normal PYTHIA units, the weight stored in 
130 <code>Info::weight()</code> has been converted to mb, however.
131   
132 <br/><code>argumentoption </code><strong> -4</strong> :  as option 4, except that events now can come 
133 either with positive or negative weights.   
134 <br/><b>Note 1</b>: if several processes have already been mixed and 
135 stored in a common event file, either LHEF or some private format, it 
136 would be problematical to read back events in a different order. Since it 
137 is then not feasible to let PYTHIA pick the next process type, strategies 
138 +-1 and +-2 would not work. Instead strategy 3 would be the recommended
139 choice, or -3 if negative-weight events are required.
140 <br/><b>Note 2</b>: it is possible to switch on internally implemented 
141 processes and have PYTHIA mix these with LHA ones according to their relative 
142 cross sections for strategies +-1, +-2 and 3. It does not work for strategy 
143 -3 unless the positive and negative sectors of the cross sections are in 
144 separate subprocesses (as must always be the case for -1 and -2), since 
145 otherwise the overall mixture of PYTHIA and LHA processes will be off. 
146 Mixing is not possible for strategies +-4, since the weighting procedure 
147 is not specified by the standard. (For instance, the intention may be to 
148 have events biased towards larger <i>pT</i> values in some particular 
149 functional form.)
150   
151   
152
153 <a name="method7"></a>
154 <p/><strong>void LHAup::addProcess( int idProcess, double xSec, double xErr, double xMax) &nbsp;</strong> <br/>
155 sets info on an allowed process (cf. <code>LPRUP, XSECUP, XERRUP, 
156 XMAXUP</code>). 
157 Each new call will append one more entry to the list of processes.
158 The choice of strategy determines which quantities are mandatory:
159 <code>xSec</code> for strategies +-2 and +-3, 
160 <code>xErr</code> never, and
161 <code>xMax</code> for strategies +-1 and +-2. 
162   
163
164 <br/><b>Note</b>: PYTHIA does not make active use of the (optional)
165 <code>xErr</code> values, but calculates a statistical cross section 
166 error based on the spread of event-to-event weights. This should work 
167 fine for strategy options +-1, but not for the others. Specifically, 
168 for options +-2 and +-3 the weight spread may well vanish, and anyway 
169 is likely to be an underestimate of the true error. If the author of the 
170 LHA input information does provide error information you may use that -
171 this information is displayed at initialization. If not, then a relative
172 error decreasing like <i>1/sqrt(n_acc)</i>, where <i>n_acc</i>     
173 is the number of accepted events, should offer a reasonable estimate.
174
175 <a name="method8"></a>
176 <p/><strong>void LHAup::setXSec( int i, double xSec) &nbsp;</strong> <br/>
177 update the <code>xSec</code> value of the <code>i</code>'th process
178 added with <code>addProcess</code> method (i.e. <code>i</code> runs
179 from 0 through <code>sizeProc() - 1</code>, see below).
180   
181
182 <a name="method9"></a>
183 <p/><strong>void LHAup::setXErr( int i, double xErr) &nbsp;</strong> <br/>
184 update the <code>xErr</code> value of the <code>i</code>'th process
185 added with <code>addProcess</code> method.
186   
187
188 <a name="method10"></a>
189 <p/><strong>void LHAup::setXMax( int i, double xMax) &nbsp;</strong> <br/>
190 update the <code>xMax</code> value of the <code>i</code>'th process
191 added with <code>addProcess</code> method.
192   
193
194 <a name="method11"></a>
195 <p/><strong>void LHAup::setInfoHeader(string &key, string &val) &nbsp;</strong> <br/>
196 set the header <code>key</code> to have value <code>val</code>.
197 This is a wrapper function to the
198 <a href="EventInformation.html" target="page">Info::setHeader</a> function that
199 should be used in any classes derived from LHAup.
200   
201
202 <p/>
203 Information is handed back by the following methods 
204 (that normally you would not need to touch):
205 <a name="method12"></a>
206 <p/><strong>int LHAup::idBeamA() &nbsp;</strong> <br/>
207   
208 <strong>int LHAup::idBeamB() &nbsp;</strong> <br/>
209   
210 <strong>double LHAup::eBeamA() &nbsp;</strong> <br/>
211   
212 <strong>double LHAup::eBeamB() &nbsp;</strong> <br/>
213   
214 <strong>int LHAup::pdfGroupBeamA() &nbsp;</strong> <br/>
215   
216 <strong>int LHAup::pdfGroupBeamB() &nbsp;</strong> <br/>
217   
218 <strong>int LHAup::pdfSetBeamA() &nbsp;</strong> <br/>
219   
220 <strong>int LHAup::pdfSetBeamB() &nbsp;</strong> <br/>
221 for the beam properties.
222   
223 <a name="method13"></a>
224 <p/><strong>int LHAup::strategy() &nbsp;</strong> <br/>
225 for the strategy choice.
226   
227 <a name="method14"></a>
228 <p/><strong>int LHAup::sizeProc() &nbsp;</strong> <br/>
229 for the number of subprocesses.
230   
231 <a name="method15"></a>
232 <p/><strong>int LHAup::idProcess(i) &nbsp;</strong> <br/>
233   
234 <strong>double LHAup::xSec(i) &nbsp;</strong> <br/>
235   
236 <strong>double LHAup::xErr(i) &nbsp;</strong> <br/>
237   
238 <strong>double LHAup::xMax(i) &nbsp;</strong> <br/>
239 for process <code>i</code> in the range <code>0 &lt;= i &lt; 
240 sizeProc()</code>.   
241
242   
243 <a name="method16"></a>
244 <p/><strong>double LHAup::xSecSum() &nbsp;</strong> <br/>
245   
246 <strong>double LHAup::xErrSum() &nbsp;</strong> <br/>
247 the sum of the cross sections and errors (the latter added quadratically).
248 Note that cross section errors are only meaningful for strategies +-3.
249   
250
251 <a name="method17"></a>
252 <p/><strong>void LHAup::listInit(ostream& os = cout) &nbsp;</strong> <br/>
253 prints the above initialization information. This method is
254 automatically called from <code>Pythia::init(...)</code>, 
255 so would normally not need to be called directly by the user.
256   
257
258 <p/>
259
260
261 <h3>Event input</h3>
262
263 The <code>LHAup</code> class also stores information equivalent to the 
264 <code>/HEPEUP/</code> commonblock, as required to hand in the next 
265 parton-level configuration for complete event generation. The main 
266 difference is that the vector container now allows a flexible number 
267 of partons to be defined. For the rest, names have been modified, 
268 since the 6-character-limit does not apply, and variables have been 
269 regrouped for clarity, but nothing fundamental is changed.
270
271 <p/>
272 The LHA standard is based on Fortran arrays beginning with
273 index 1, and mother information is defined accordingly. In order to 
274 be compatible with this convention, the zeroth line of the C++ particle
275 array is kept empty, so that index 1 also here corresponds to the first
276 particle. One small incompatibility is that the <code>sizePart()</code> 
277 method returns the full size of the particle array, including the 
278 empty zeroth line, and thus is one larger than the true number of 
279 particles (<code>NUP</code>). 
280
281 <a name="method18"></a>
282 <p/><strong>virtual bool LHAup::setEvent(int idProcess = 0) &nbsp;</strong> <br/>
283 this pure virtual method has to be implemented in the derived class, 
284 to set relevant information when called. For strategy options +-1 
285 and +-2 the input <code>idProcess</code> value specifies which process 
286 that should be generated, while <code>idProcess</code> is irrelevant 
287 for strategies +-3 and +-4. The method should return false if it fails 
288 to set the info, i.e. normally that the supply of events in a file is 
289 exhausted. If so, no event is generated, and <code>Pythia::next()</code> 
290 returns false. You can then interrogate 
291 <code><a href="EventInformation.html" target="page">Info::atEndOfFile()</a></code> 
292 to confirm that indeed the failure is caused in this method, and decide 
293 to break out of the event generation loop.
294
295 <p/>
296 Inside a normal <code>setEvent(...)</code> call, information can be set 
297 by the following methods:
298 <a name="method19"></a>
299 <p/><strong>void LHAup::setProcess( int idProcess, double weight, double scale, double alphaQED, double alphaQCD) &nbsp;</strong> <br/>
300 tells which kind of process occured, with what weight, at what scale, 
301 and which <i>alpha_EM</i> and <i>alpha_strong</i> were used
302 (cf. <code>IDPRUP, XWTGUP, SCALUP, AQEDUP, AQCDUP</code>). This method 
303 also resets the size of the particle list, and adds the empty zeroth 
304 line, so it has to be called before the <code>addParticle</code> method below.
305   
306 <a name="method20"></a>
307 <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/>
308 gives the properties of the next particle handed in (cf. <code>IDUP, ISTUP, 
309 MOTHUP(1,..), MOTHUP(2,..), ICOLUP(1,..), ICOLUP(2,..),  PUP(J,..), 
310 VTIMUP, SPINUP</code>) .
311   
312
313 <p/>
314 Information is handed back by the following methods:
315 <a name="method21"></a>
316 <p/><strong>int LHAup::idProcess() &nbsp;</strong> <br/>
317 process number.
318   
319
320 <a name="method22"></a>
321 <p/><strong>double LHAup::weight() &nbsp;</strong> <br/>
322 Note that the weight stored in <code>Info::weight()</code> as a rule
323 is not the same as the above <code>weight()</code>: the method here gives
324 the value before unweighting while the one in <code>info</code> gives
325 the one after unweighting and thus normally is 1 or -1. Only with strategy
326 options +-3 and +-4 would the value in <code>info</code> be the same as 
327 here, except for a conversion from pb to mb for +-4. 
328   
329
330 <a name="method23"></a>
331 <p/><strong>double LHAup::scale() &nbsp;</strong> <br/>
332   
333 <strong>double LHAup::alphaQED() &nbsp;</strong> <br/>
334   
335 <strong>double LHAup::alphaQCD() &nbsp;</strong> <br/>
336 scale and couplings at that scale.
337   
338
339 <a name="method24"></a>
340 <p/><strong>int LHAup::sizePart() &nbsp;</strong> <br/>
341 the size of the particle array, which is one larger than the number 
342 of particles in the event, since the zeroth entry is kept empty 
343 (see above). 
344   
345
346 <a name="method25"></a>
347 <p/><strong>int LHAup::id(int i) &nbsp;</strong> <br/>
348   
349 <strong>int LHAup::status(int i) &nbsp;</strong> <br/>
350   
351 <strong>int LHAup::mother1(int i) &nbsp;</strong> <br/>
352   
353 <strong>int LHAup::mother2(int i) &nbsp;</strong> <br/>
354   
355 <strong>int LHAup::col1(int i) &nbsp;</strong> <br/>
356   
357 <strong>int LHAup::col2(int i) &nbsp;</strong> <br/>
358   
359 <strong>double LHAup::px(int i) &nbsp;</strong> <br/>
360   
361 <strong>double LHAup::py(int i) &nbsp;</strong> <br/>
362   
363 <strong>double LHAup::pz(int i) &nbsp;</strong> <br/>
364   
365 <strong>double LHAup::e(int i) &nbsp;</strong> <br/>
366   
367 <strong>double LHAup::m(int i) &nbsp;</strong> <br/>
368   
369 <strong>double LHAup::tau(int i) &nbsp;</strong> <br/>
370   
371 <strong>double LHAup::spin(int i) &nbsp;</strong> <br/>
372 for particle <code>i</code> in the range 
373 <code>0 &lt;= i &lt; sizePart()</code>. (But again note that 
374 <code>i = 0</code> is an empty line, so the true range begins at 1.)   
375   
376
377 <p/>
378 From the information in the event record it is possible to set 
379 the flavour and <i>x</i> values of the initiators 
380 <a name="method26"></a>
381 <p/><strong>void LHAup::setIdX(int id1, int id2, double x1, double x2) &nbsp;</strong> <br/>
382   
383
384 <p/>
385 This information is returned by the methods
386 <a name="method27"></a>
387 <p/><strong>int LHAup::id1() &nbsp;</strong> <br/>
388   
389 <strong>int LHAup::id2() &nbsp;</strong> <br/>
390   
391 <strong>double LHAup::x1() &nbsp;</strong> <br/>
392   
393 <strong>double LHAup::x2() &nbsp;</strong> <br/>
394   
395
396 <p/>
397 In the LHEF description [<a href="Bibliography.html" target="page">Alw06</a>] an extension to 
398 include information on the parton densities of the colliding partons
399 is suggested. This optional further information can be set by
400 <a name="method28"></a>
401 <p/><strong>void LHAup::setPdf( int id1pdf, int id2pdf, double x1pdf, double x2pdf, double scalePDF, double pdf1, double pdf2, bool pdfIsSet) &nbsp;</strong> <br/>
402 which gives the flavours , the <i>x</i> and the <ie>Q</i> scale 
403 (in GeV) at which the parton densities <i>x*f_i(x, Q)</i> have been
404 evaluated. The last argument is normally <code>true</code>.
405   
406
407 <p/>
408 This information is returned by the methods
409 <a name="method29"></a>
410 <p/><strong>bool LHAup::pdfIsSet() &nbsp;</strong> <br/>
411   
412 <strong>int LHAup::id1pdf() &nbsp;</strong> <br/>
413   
414 <strong>int LHAup::id2pdf() &nbsp;</strong> <br/>
415   
416 <strong>double LHAup::x1pdf() &nbsp;</strong> <br/>
417   
418 <strong>double LHAup::x2pdf() &nbsp;</strong> <br/>
419   
420 <strong>double LHAup::scalePDF() &nbsp;</strong> <br/>
421   
422 <strong>double LHAup::pdf1() &nbsp;</strong> <br/>
423   
424 <strong>double LHAup::pdf2() &nbsp;</strong> <br/>
425 where the first one tells whether this optional information has been set
426 for the current event. (<code>setPdf(...)</code> must be called after the
427 <code>setProcess(...)</code> call of the event for this to work.)
428 Note that the flavour and <i>x</i> values usually but not always 
429 agree with those obtained by the same methods without <code>pdf</code>
430 in their names, see explanation in the 
431 <a href="EventInformation.html" target="page">Event Information</a> description.
432   
433
434 <p/>
435 <a name="method30"></a>
436 <p/><strong>void LHAup::listEvent(ostream& os = cout) &nbsp;</strong> <br/>
437 prints the above information for the current event.  In cases where the
438 <code>LHAup</code> object is not available to the user, the 
439 <code>Pythia::LHAeventList(ostream& os = cout)</code> method can 
440 be used, which is a wrapper for the above. 
441   
442
443 <a name="method31"></a>
444 <p/><strong>virtual bool LHAup::skipEvent(int nSkip) &nbsp;</strong> <br/>
445 skip ahead <code>nSkip</code> events in the Les Houches generation
446 sequence, without doing anything further with them. Mainly
447 intended for debug purposes, e.g. when an event at a known 
448 location in a Les Houches Event File is causing problems.
449 Will return false if operation fails, specifically if the 
450 end of an LHEF has been reached. The implementation in the base class
451 simply executes <code>setEvent()</code> the requested number of times.
452 The derived <code>LHAupLHEF</code> class (see below) only uses the
453 <code>setNewEventLHEF(...)</code> part of its <code>setEvent()</code> 
454 method, and other derived classes could choose other shortcuts.
455   
456
457 <p/>
458 The LHA expects the decay of resonances to be included as part of the 
459 hard process, i.e. if unstable particles are produced in a process then
460 their decays are also described. This includes <i>Z^0, W^+-, H^0</i> 
461 and other short-lived particles in models beyond the Standard Model.
462 Should this not be the case then PYTHIA will perform the decays of all
463 resonances it knows how to do, in the same way as for internal processes.
464 Note that you will be on slippery ground if you then restrict the decay of
465 these resonances to specific allowed channels since, if this is not what 
466 was intended, you will obtain the wrong cross section and potentially the
467 wrong mix of different event types. (Since the original intention is
468 unknown, the cross section will not be corrected for the fraction of
469 open channels, i.e. the procedure used for internal processes is not
470 applied in this case.) 
471
472 <p/>
473 Even if PYTHIA can select resonance decay modes according to its 
474 internal tables, there is normally no way for it to know which 
475 decay angular correlations should exist in the simulated process.
476 Therefore almost all decays are isotropic. The exceptions are Higgs and
477 top decays, in the decay chains <i>H -> WW/ZZ -> f fbar f' fbar'</i> 
478 and <i>t -> b W -> b f fbar</i>, where the process-independent 
479 correlations implemented for internal processes are used. If part of 
480 the decay chain has already been set, however (e.g. <i>H -> WW/ZZ</i> 
481 or <i>t -> b W</i>), then decay is still isotropic.
482
483 <h3>An interface to Les Houches Event Files</h3>
484
485 The LHEF standard [<a href="Bibliography.html" target="page">Alw06</a>] specifies a format where a single file 
486 packs initialization and event information. This has become the most 
487 frequently used procedure to process external parton-level events in 
488 Pythia. Therefore a special 
489 <code><a href="ProgramFlow.html" target="page">Pythia::init(fileName)</a></code>
490 initialization option exists, where the LHEF name is provided as input. 
491 Internally this name is then used to create an instance of the derived 
492 class <code>LHAupLHEF</code>, which can do the job of reading an LHEF.
493
494 <p/>
495 The LHEF reader can also read in and store header blocks. By default
496 this option is switched on, but may be controlled through the
497 <a href="BeamParameters.html" target="page">Beams:readLHEFheaders</a> flag if
498 necessary. The information can later be read out through the
499 <a href="EventInformation.html" target="page">Info</a> class for further processing.
500 Due to the non-standard nature of the information in these blocks they
501 are stored whole, and PYTHIA itself makes no further attempt to process
502 their meaning.
503
504 <p/>
505 Because Les Houches Event files tend not to adhere strictly to XML
506 conventions, to consistently read in header information, certain
507 choices must be made. The primary goal is to make as much information
508 available as possible. First, information sitting directly in the
509 &lt;header&gt; block is stored under the key "base". Second, the tags
510 starting and ending each sub block must be on their own line. Finally,
511 the contents of comment blocks, &lt;!-- --&gt;, are still stored. The
512 header keys are formed hierarchically from the names of the header
513 blocks. This behaviour is illustrated in the following example:
514 <pre>
515   &lt;header&gt;
516     BaseA
517     &lt;hblock1&gt;
518       1A
519       &lt;hblock11&gt;
520         11A &lt;hblock111&gt;
521         &lt;/hblock111&gt; 11B
522       &lt;/hblock11&gt;
523       1B
524     &lt;/hblock1&gt;
525     &lt;hblock2&gt;
526       2A
527       &lt;!-- 2B --&gt;
528     &lt;/hblock2&gt;
529     BaseB
530   &lt;/header&gt;
531 </pre>
532 which would lead to the following information being stored in the
533 <a href="EventInformation.html" target="page">Info</a> class:
534 <table border="1">
535   <tr> <th>Key</th> <th>Value</th> </tr>
536   <tr>
537     <td>base</td>
538     <td>BaseA<br/>BaseB</td>
539   </tr>
540   <tr>
541     <td>hblock1</td>
542     <td>1A<br/>1B</td>
543   </tr>
544   <tr>
545     <td>hblock1.hblock11</td>
546     <td>11A &lt;hblock111&gt;<br/>&lt;/hblock111&gt; 11B</td>
547   </tr>
548   <tr>
549     <td>hblock2</td>
550     <td>2A<br/>&lt;!-- 2B --&gt;</td>
551   </tr>
552 </table> 
553 <br/>
554 <p/>
555 Normally the LHEF would be in uncompressed format, and thus human-readable
556 if opened in a text editor. A possibility to read gzipped files has 
557 been added, based on the Boost and zlib libraries, which therefore
558 have to be linked appropriately in order for this option to work.
559 See the <code>README</code> file in the main directory for details 
560 on how to do this. 
561
562 <p/>
563 An example how to generate events from an LHEF is found in 
564 <code>main11.cc</code>. Note the use of 
565 <code>Info::atEndOfFile()</code> to find out when the whole
566 LHEF has been processed. 
567
568 <p/>
569 To allow the sequential use of several event files the 
570 <code>Pythia::init(...)</code> method has an optional second argument: 
571 <code>Pythia::init(fileName, bool skipInit = false)</code>.
572 If called with this argument <code>true</code> then there will be no 
573 initialization, except that the existing <code>LHAupLHEF</code> class 
574 instance will be deleted and replaced by ones pointing to the new file. 
575 It is assumed (but never checked) that the initialization information is 
576 identical, and that the new file simply contains further events of 
577 exactly the same kind as the previous one. An example of this possibility, 
578 and the option to mix with internal processes, is found in 
579 <code>main12.cc</code>. A variant, based on input in a command file,
580 is given in <code>main13.cc</code>.
581
582 <p/>
583 In C++, real numbers are printed with an 'E' to denote the exponent part, 
584 e.g. 1.23E+04, and are read in accordingly. Other languges may use other
585 letters, e.g. Fortran allows either 'E' or 'D'. A file using
586 the latter convention would not be readable by the standard routines.
587 In case you have such an "incorrectly formatted" file, a conversion to 
588 a new corrected file could be done e.g. using <code>sed</code>, as a
589 one-line command
590 <pre>
591   sed -e 's/\([0-9]\.\{0,1\}\)[dD]\([+-]\{0,1\}[0-9]\)/\1E\2/g' old.lhe &gt; new.lhe
592 </pre>
593 This replaces a 'd' or 'D' with an 'E' only when it occurs in the combination
594 <br/><i>(digit) ('.' or absent) ('d' or 'D') ('+', '-' or absent) (digit)</i>
595 <br/>It will work on all parts of the file, also inside a 
596 <code>&lt;header&gt;...&lt;/header&gt;</code> block. For conversion only 
597 inside the <code>&lt;init&gt;...&lt;/init&gt;</code> and
598 <code>&lt;event&gt;...&lt;/event&gt;</code> blocks, create a file 
599 <code>convert.sed</code> containing
600 <pre>
601   /&lt;init&gt;/,/&lt;\/init&gt;/bconv
602   /&lt;event&gt;/,/&lt\/event&gt;/bconv
603   b
604   :conv
605   s/\([0-9]\.\{0,1\}\)[dD]\([+-]\{0,1\}[0-9]\)/\1E\2/g
606 </pre>
607 and run it with
608 <pre>
609   sed -f convert.sed old.lhe &gt; new.lhe
610 </pre>
611
612 <p/>
613 The workhorses of the <code>LHAupLHEF</code> class are three methods
614 found in the base class, so as to allow them to be reused in other
615 contexts. Specifically, it allows derived classes where one parton-level 
616 configuration can be reused several times, e.g. in the context of 
617 matrix-element-to-parton-shower matching (example in preparation).
618 Also two small utility routines.
619
620 <a name="method32"></a>
621 <p/><strong>bool LHAup::setInitLHEF(ifstream& is, bool readHeaders = false) &nbsp;</strong> <br/>
622 read in and set all required initialization information from the 
623 specified stream. With second argument true it will also read and store
624 header information, as described above. Return false if it fails.
625   
626
627 <a name="method33"></a>
628 <p/><strong>bool LHAup::setNewEventLHEF(ifstream& is) &nbsp;</strong> <br/>
629 read in event information from the specified stream into a staging area 
630 where it can be reused by <code>setOldEventLHEF</code>.
631   
632
633 <a name="method34"></a>
634 <p/><strong>bool LHAup::setOldEventLHEF() &nbsp;</strong> <br/>
635 store the event information from the staging area into the normal 
636 location. Thus a single <code>setNewEventLHEF</code> call can be 
637 followed by several <code>setOldEventLHEF</code> ones, so as to 
638 process the same configuration several times. This method currently 
639 only returns true, i.e. any errors should be caught by the preceding 
640 <code>setNewEventLHEF</code> call.
641   
642
643 <a name="method35"></a>
644 <p/><strong>bool LHAup::fileFound() &nbsp;</strong> <br/>
645 always returns true in the base class, but in <code>LHAupLHEF</code>
646 it returns false if the LHEF provided in the constructor is not
647 found and opened correctly.
648   
649
650 <a name="method36"></a>
651 <p/><strong>void LHAup::setInfoHeader(const string &key, const string &val) &nbsp;</strong> <br/>
652 is used to send header information on to the <code>Info</code> class. 
653   
654
655 <p/>
656 A few other methods, most of them derived from the base class, 
657 streamlines file opening and closing, e.g. if several LHE files are 
658 to be read consecutively, without the need for a complete 
659 reinitialization. This presupposes that the events are of the same 
660 kind, only split e.g. to limit file sizes.
661
662 <a name="method37"></a>
663 <p/><strong>bool LHAup::newEventFile(const char* fileIn) &nbsp;</strong> <br/>
664 close current event input file/stream and open a new one, to
665 continue reading events of the same kind as before.
666   
667
668 <a name="method38"></a>
669 <p/><strong>istream* LHAup::openFile(const char *fn, ifstream &ifs) &nbsp;</strong> <br/>
670   
671 <strong>void LHAup::closeFile(istream *&is, ifstream &ifs) &nbsp;</strong> <br/>
672 open and close a file, also gzip files, where an intermediate
673 decompression layer is needed.
674   
675
676 <a name="method39"></a>
677 <p/><strong>void LHAupLHEF::closeAllFiles() &nbsp;</strong> <br/>
678 close main event file (LHEF) and, if present, separate header file.
679   
680  
681 <h3>A runtime Fortran interface</h3>
682
683 The runtime Fortran interface requires linking to an external Fortran
684 code. In order to avoid problems with unresolved external references
685 when this interface is not used, the code has been put in a separate
686 <code>LHAFortran.h</code> file, that is not included in any of the
687 other library files. Instead it should be included in the 
688 user-supplied main program, together with the implementation of two
689 methods below that call the Fortran program to do its part of the job. 
690
691 <p/>
692 The <code>LHAupFortran</code> class derives from <code>LHAup</code>. 
693 It reads initialization and event information from the LHA standard 
694 Fortran commonblocks, assuming these commonblocks behave like two 
695 <code>extern "C" struct</code> named <code>heprup_</code> and
696 <code>hepeup_</code>. (Note the final underscore, to match how the 
697 gcc compiler internally names Fortran files.) 
698
699 <p/>
700 The instantiation does not require any arguments. 
701
702 <p/>
703 The user has to supply implementations of the <code>fillHepRup()</code>
704 and <code>fillHepEup()</code> methods, that is to do the actual calling 
705 of the external Fortran routines that fill the <code>HEPRUP</code> and 
706 <code>HEPEUP</code> commonblocks. The translation of this information to 
707 the C++ structure is provided by the existing <code>setInit()</code> and
708 <code>setEvent()</code> code. 
709
710 <p/>
711 Up to and including version 8.125 the <code>LHAupFortran</code> class
712 was used to construct a runtime interface to PYTHIA 6.4. This was 
713 convenient in the early days of PYTHIA 8 evolution, when this program 
714 did not yet contain hard-process generation, and the LHEF standard 
715 did not yet exist. Nowadays it is more of a bother, since a full
716 cross-platform support leads to many possible combinations. Therefore
717 the support has been reduced in the current version. Only the 
718 <code>main91.cc</code> example remains as an illustration, where the
719 previously separate interface code 
720 (<code>include/Pythia6Interface.h</code>) has been inserted in the 
721 beginning. You also need to modify the <code>examples/Makefile</code> 
722 to link <code>main91.cc</code> properly also to a PYTHIA 6.4 library
723 version, see commented-out section for ideas how to to this.
724
725 <h3>Methods for LHEF output</h3>
726
727 The main objective of the <code>LHAup</code> class is to feed information
728 from an external program into PYTHIA. It can be used to export information
729 as well, however. Specifically, there are four routines in the base class
730 that can be called to write a Les Houches Event File. These should be 
731 called in sequence in order to build up the proper file structure. 
732
733 <a name="method40"></a>
734 <p/><strong>bool LHAup::openLHEF(string filename) &nbsp;</strong> <br/>
735 Opens a file with the filename indicated, and writes a header plus a brief
736 comment with date and time information.
737   
738
739 <a name="method41"></a>
740 <p/><strong>bool LHAup::initLHEF() &nbsp;</strong> <br/>
741 Writes initialization information to the file above. Such information should
742 already have been set with the methods described in the "Initialization"
743 section above.
744   
745
746 <a name="method42"></a>
747 <p/><strong>bool LHAup::eventLHEF(bool verbose = true) &nbsp;</strong> <br/>
748 Writes event information to the file above. Such information should
749 already have been set with the methods described in the "Event input"
750 section above. This call should be repeated once for each event to be 
751 stored. By default the event information is lined up in columns.
752 To save space, the alternative <code>verbose = false</code> only 
753 leaves a single blank between the information fields.
754   
755
756 <a name="method43"></a>
757 <p/><strong>bool LHAup::closeLHEF(bool updateInit = false) &nbsp;</strong> <br/>
758 Writes the closing tag and closes the file. Optionally, if 
759 <code>updateInit = true</code>, this routine will reopen the file from
760 the beginning, rewrite the same header as <code>openLHEF()</code> did,
761 and then call <code>initLHEF()</code> again to overwrite the old 
762 information. This is especially geared towards programs, such as PYTHIA
763 itself, where the cross section information is not available at the 
764 beginning of the run, but only is obtained by Monte Carlo integration 
765 in parallel with the event generation itself. Then the 
766 <code>setXSec( i, xSec)</code>, <code>setXErr( i, xSec)</code> and
767 <code>setXMax( i, xSec)</code> can be used to update the relevant 
768 information before <code>closeLHEF</code> is called.
769 <br/><b>Warning:</b> overwriting the beginning of a file without 
770 upsetting anything is a delicate operation. It only works when the new 
771 lines require exactly as much space as the old ones did. Thus, if you add 
772 another process in between, the file will be corrupted. 
773   
774
775 <h3>PYTHIA 8 output to an LHEF</h3>
776
777 The above methods could be used by any program to write an LHEF. 
778 For PYTHIA 8 to do this, a derived class already exists,
779 <code>LHAupFromPYTHIA8</code>. In order for it to do its job,
780 it must gain access to the information produced by PYTHIA, 
781 specifically the <code>process</code> event record and the
782 generic information stored in <code>info</code>. Therefore, if you
783 are working with an instance <code>pythia</code> of the 
784 <code>Pythia</code> class, you have to instantiate
785 <code>LHAupFromPYTHIA8</code> with pointers to the 
786 <code>process</code> and <code>info</code> objects of 
787 <code>pythia</code>:
788 <br/><code>LHAupFromPYTHIA8 myLHA(&pythia.process, &pythia.info);</code>
789
790 <p/>
791 The method <code>setInit()</code> should be called to store the
792 <code>pythia</code> initialization information in the LHA object,
793 and <code>setEvent()</code> to store event information. 
794 Furthermore, <code>updateSigma()</code> can be used at the end 
795 of the run to update cross-section information, cf.
796 <code>closeLHEF(true)</code> above. An example how the 
797 generation, translation and writing methods should be ordered is
798 found in <code>main20.cc</code>.
799
800 <p/>
801 Currently there are some limitations, that could be overcome if
802 necessary. Firstly, you may mix many processes in the same run,
803 but the cross-section information stored in <code>info</code> only 
804 refers to the sum of them all, and therefore they are all classified 
805 as a common process 9999. Secondly, you should generate your events 
806 in the CM frame of the collision, since this is the assumed frame of
807 stored Les Houches events, and no boosts have been implemented 
808 for the case that <code>Pythia::process</code> is not in this frame. 
809
810 <p/>
811 The LHEF standard is the agreed format to store the particles of a 
812 hard process, as input to generators, whereas output of final states
813 is normally handled using the <a href="HepMCInterface.html" target="page">HepMC</a> 
814 standard. It is possible to use LHEF also here, however. It requires
815 that the above initialization is replaced by 
816 <br/><code>LHAupFromPYTHIA8 myLHA(&pythia.event, &pythia.info);</code>
817 <br/> i.e. that <code>process</code> is replaced by <code>event</code>.
818 In addition, the <code>PartonLevel:all = off</code> command found in
819 <code>main20.cc</code> obviously must be removed if one wants to
820 obtain complete events.
821  
822 </body>
823 </html>
824
825 <!-- Copyright (C) 2012 Torbjorn Sjostrand -->