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