source: HiSusy/trunk/Pythia8/pythia8170/xmldoc/LesHouchesAccord.xml @ 1

Last change on this file since 1 was 1, checked in by zerwas, 11 years ago

first import of structure, PYTHIA8 and DELPHES

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