<chapter name="Les Houches Event Files"> 
 
<h2>Les Houches Event Files</h2> 
 
The most common application of the 
Les Houches Accord (LHA) for user processes <ref>Boo01</ref> 
is to read input from a Les Houches Event File 
(LHEF) <ref>Alw06</ref>, but it is also possible to have a runtime 
interface to another program. 
 
<p/> 
A "no-beams" extension, currently not part of the standard, has been 
implemented. In this case only one part of a complete event is studied, 
and so no meaningful beam information can be set. The prime example is 
to study the decay properties of a resonance, where a parton-level decay 
chain is provided as input, and then showers and nadronization should be 
added. This simplified option does not cover <ei>R</ei>-hadron formation 
and may not handle junction topologies in baryon-number-violating decays. 
Normally it is assumed that parton showers in the decays are fully 
handled by PYTHIA, but you can also specify multiparton configurations 
as the starting point. Then it is important to avoid doublecounting 
between emissions accounted for by matrix elements and by shower, by a 
judicious choice of scales or by a rejection of unwanted emissions in a 
user hook. Another example would be where a given partonic configuration 
would be hadronized, without any previous showers. See further below and 
in the <aloc href="HadronLevelStandalone">Hadron-Level Standalone</aloc> 
description. 
 
<p/> 
Another unofficial extension is the support for Double Parton Scattering 
(DPS), i.e. when two hard scatterings should be defined. This is allowed 
by letting one follow after the other in the event listing, such 
that two <ei>2 &rarr; 2</ei> scatterings are specified by eight lines. 
It is here required that daughters are located below mothers strictly 
within each scattering separately, since the logic needed to sort out 
an arbitrary ordering is deemed overkill for such a peripheral case. 
An additional line <code>#scaleShowers scale1 scale2</code> can be 
attached after the event proper, where the starting shower scale can be 
defined for each scattering separately; if not present both scatterings 
evolve down from the standard scale value. The <code>LHAup</code> 
method <code>bool scaleShowersIsSet()</code> tells whether such information 
has been set for the current event and, if so, 
<code>double scaleShowers(int i)</code> return the two scale values for 
arguments 0 and 1. 
 
<h3>Event input</h3> 
 
<p/> 
The maximum scale for parton-shower evolution of a Les Houches event is 
regulated by the 
<code><aloc href="TimelikeShowers">TimeShower:pTmaxMatch</aloc></code> 
and 
<code><aloc href="SpacelikeShowers">SpaceShower:pTmaxMatch</aloc></code> 
modes. If you want to guarantee that the input <code>scale</code> value 
is respected, as is often the case in matching/merging procedures, you 
should set both of these modes to 1. That only affects the hard process, 
while resonance decays are still processed using the resonance mass to 
set the upper limit. However, the optional 
<code><aloc href="BeamParameters">Beams:strictLHEFscale = on</aloc></code> 
setting restricts also resonance-decay emissions to be below the input 
<code>scale</code> value. 
 
<p/> 
As a further non-standard feature, it is also possible to read in the 
separate scale values of all final particles. Such scale values could be used 
e.g. to restrict the maximum scale for shower evolutions for each parton 
separately. This reading will only be applied if the <code> 
Beams:setProductionScaleFromLHEF</code> switch is true (see <code> 
<aloc href="BeamParameters">Beam Parameters</aloc></code> for details). 
This information is returned by the method 
<code>double LHAup::scale(int i)</code>. When no such information 
has been read from the LHEF, the scale defaults to -1. 
 
<p/> 
The LHA standard only allows for one hard subcollision in an event. 
Further multiparton interactions are supposed to be handled by the 
internal MPI machinery. As a nonstandard feature, it is possible 
to input two hard subcollisions in the same event, to match the internal 
<aloc href="SecondHardProcess">second hard process</aloc> machinery. 
In such cases two partons are extracted from each of the two incoming 
hadrons. A restriction is that, unlike the single-subprocess case, 
it is important that the partons are input in the order that PYTHIA 
later would need. That is, the two subcollisions should follow each 
other, with instate preceding outstate. Any resonance decay chain 
should be put at the end, after both interactions. As illustration, 
consider double <ei>W</ei> production. With <ei>1</ei> and <ei>2</ei> 
labelling the two subcollisions, and <ei>A</ei> and <ei>B</ei> the two 
incoming hadron beams, the event record ordering should be 
<ei>in_A1 - in_B1 - W_1 - in_A2 - in_B2 - W_2 - f_1 - fbar_1 - f_2 - 
fbar_2</ei>, where <ei>f fbar</ei> is the fermion decay products of 
the respective <ei>W</ei>. A limitation is that currently only one 
input scale is used, that thereby limits all further partonic activity 
in the same way for both processes. 
 
<h3>Transfer to the PYTHIA process record</h3> 
 
There are a few settings available for event input. They take effect when 
the LHA event record is translated to the PYTHIA <code>process</code> 
event record, but leaves the LHA event record itself unchanged. 
 
<modeopen name="LesHouches:idRenameBeams" default="1000022" min="0"> 
PYTHIA only implements a certain number of incoming beam particles. 
Specifically it needs to have PDFs for every composite particle to 
be used. Sometimes exotic beam particles are used, e.g. when a 
neutralino is supposed to be the Dark Matter particle and therefore 
neutralino pairs can collide and annihilate. Such a particle identity 
code, picked by this mode, is mapped onto an incoming tau neutrino 
beam (or antineutrino for the second beam), to bring it to a familiar 
situation. The trick cannot be used for composite particles, nor for 
a pair of different particles. 
</modeopen> 
 
<modepick name="LesHouches:setLifetime" default="1" min="0" max="2"> 
handling of the decay time information stored in <code>VTIMUP</code> 
when the Les Houches event record is stored into the PYTHIA 
<code>process</code> one. The reason is that some matrix-element 
generators (like POWHEG) do not set decay times, so that it is up to 
PYTHIA to make that selection. This is particularly important for 
the <ei>tau</ei> lepton. 
<option value="0"> all decay times are taken from the Les Houches input. 
</option> 
<option value="1"> the decay time of <ei>tau</ei> leptons is generated 
like for internal PYTHIA <ei>tau</ei>s, whereas all other decay times 
are taken from the Les Houches input. 
</option> 
<option value="2"> all decay times are generated by PYTHIA, thus 
completely disregarding the Les Houches values. This option could 
go wrong in BSM scenarios with long-lived particles, if PYTHIA 
has not been provided with the information to select those lifetimes 
correctly. 
</option> 
</modepick> 
 
<modepick name="LesHouches:setLeptonMass" default="1" min="0" max="2"> 
setting of mass for final-state charged leptons. The reason here is that 
some matrix-element generators assume leptons to be massless, so as to 
simplify calculations. This is particularly common for the <ei>e</ei> and 
<ei>mu</ei> leptons, but sometimes also the <ei>tau</ei> lepton is 
afflicted. Incoming leptons are not affected by this procedure. 
<option value="0"> all lepton masses are taken from the Les Houches input. 
</option> 
<option value="1"> if the input lepton mass deviates by more than 10% 
from the PYTHIA (data table) mass then its mass is reset according to the 
PYTHIA value. This should catch weird masses, while allowing sensible 
variations. 
</option> 
<option value="2"> each lepton mass is reset according to the PYTHIA value. 
</option> 
<note>Warning:</note> when the mass is changed, also energy and/or momentum 
need to be shifted. This cannot be done for the lepton in isolation, 
but should be made so as to preserve the energy and momentum of the event 
as a whole. An attempt is therefore made to find another final-state 
particle recoiler that can transfer the appropriate amount of energy 
and momentum. The recoiler may be unstable, and if so the transfer is 
inherited by its decay products. The choice is straightforward if only 
two final-state particles exist, or in a two-body decay of an intermediate 
resonance, else a matching (anti)neutrino or (anti)lepton is searched for. 
These rules catch most of the standard cases for lepton production, such as 
<ei>gamma^*/Z^0/W^+-</ei>, but not necessarily all. Should they all fail 
the potential final-state recoiler with largest relative invariant mass 
is picked. In either case, if the transfer fails because the intended 
recoiler has too little energy to give up, then instead the energy is 
recalculated for the new mass without any transfer. The energy violation 
is partly compensated by changed energies for the incoming partons to 
the hard collision if <code>LesHouches:matchInOut = on</code>, but not 
always perfectly. One possibility then is to change the 
<aloc href="ErrorChecks">tolerance</aloc> to reduce such errors. 
</modepick> 
 
<modepick name="LesHouches:setQuarkMass" default="1" min="0" max="2"> 
setting of mass for final-state quarks. The reason here is that some 
matrix-element generators assume all quarks to be massless, except for 
the top, so as to simplify calculations. Especially for <ei>c</ei> and 
<ei>b</ei> quarks this is a poor approximation, although PYTHIA most of 
the time still manages to shower and hadronize even such events. The 
reason is the resilience of the string fragmentation model, where 
the excess gluons near (in colour and momentum) to a massless <ei>b</ei> 
are "eaten up" when string fragmentation needs to gather enough invariant 
mass to give to the <ei>B</ei> hadron. Nevertheless it is an uncomfortable 
situation, to be avoided where possible. For <ei>d</ei>, <ei>u</ei> and 
<ei>s</ei> quarks the issue is less critical. Incoming or intermediate 
quarks are not affected by this procedure. 
<option value="0"> all quark masses are taken from the Les Houches input. 
</option> 
<option value="1"> if the input <ei>c</ei> or <ei>b</ei> mass is 
more than 50% away from the PYTHIA (data table) mass then its mass is 
reset according to the PYTHIA value. 
</option> 
<option value="2">if the input mass, for all quarks except the top, is 
more than 50% away from the PYTHIA (data table) mass then its mass is 
reset according to the PYTHIA value. 
</option> 
<note>Warning:</note> when the mass is changed, also energy and/or momentum 
need to be shifted. This cannot be done for the quark in isolation, 
but should be made so as to preserve the energy and momentum of the event 
as a whole. An attempt is therefore made to find another final-state 
particle recoiler that can transfer the appropriate amount of energy 
and momentum. The recoiler may be unstable, and if so the transfer is 
inherited by its decay products. The choice is straightforward if only 
two final-state particles exist, or in a two-body decay of an intermediate 
resonance. If no recoiler is found this way a matching opposite-coloured 
parton is searched for. Should also this fail the potential final-state 
recoiler with largest relative invariant mass is picked. In either case, 
if the transfer fails because the intended recoiler has too little energy 
to give up, then instead the energy is recalculated for the new mass 
without any transfer. The energy violation is partly compensated by 
changed energies for the incoming partons to the hard collision if 
<code>LesHouches:matchInOut = true</code>, but not always perfectly. 
One possibility then is to change the 
<aloc href="ErrorChecks">tolerance</aloc> to such errors. 
</modepick> 
 
<modepick name="LesHouches:smearHadronMass" default="0" min="0" max="2"> 
setting of mass for a selection of hadrons. The reason here is that some 
matrix-element generators fix hadrons to be on the mass shell, so as to 
simplify calculations. One problem is that such hadrons then are 
easily distinguished from internally generated hadrons of the same 
species, which may fool machine learning tools for the separation of 
signal from background. 
<option value="0"> all hadron masses are taken unchanged from the 
Les Houches input. 
</option> 
<option value="1"> the hadrons listed in the 
<code>LesHouches:idSmearHadrons</code> vector below are assigned a new 
mass according to the internal PYTHIA prescription. A warning is issued 
if the original mass lies outside the mass range set in PYTHIA, and then 
nothing is done. 
</option> 
<option value="2"> as option 1, but there is no mass range check, so 
relevant hadrons will always receive a smeared mass. 
</option> 
<note>Warning:</note> when the mass is changed, also energy and momentum 
need to be shifted. This cannot be done for the hadron in isolation, 
but should be made so as to preserve the energy and momentum of the event 
as a whole. An attempt is therefore made to find another outgoing 
particle recoiler that can transfer the appropriate amount of energy 
and momentum. The recoiler may be unstable, and if so the transfer is 
inherited by its decay products. The choice is straightforward if only 
two final-state particles exist, or in a two-body decay of an intermediate 
resonance. If no recoiler is found this way then the potential final-state 
recoiler with largest relative invariant mass is picked. In either case, 
if the transfer fails because the intended recoiler has too little energy 
to give up, then instead the energy is recalculated for the new mass 
without any transfer. The energy violation is partly compensated by 
changed energies for the incoming partons to the hard collision if 
<code>LesHouches:matchInOut = true</code>, but not always perfectly. 
One possibility then is to change the 
<aloc href="ErrorChecks">tolerance</aloc> to such errors. 
</modepick> 
 
<mvec name="LesHouches:idSmearHadrons" default="{113,213}" min="0"> 
list of hadron identity codes, whose masses will be smeared if 
<code>LesHouches:smearHadronMass &gt; 0</code>, see above. Only 
(positive) particle codes should be given, with their antiparticles 
automatically included. It is assumed that the hadron to be smeared 
has not yet been decayed. 
</mvec> 
 
<parm name="LesHouches:mRecalculate" default="-1."> 
Does not have any effect by default, or more generally when it is negative. 
If it is positive then all particles with an input mass above this 
value will have the mass recalculated and reset from the four-momentum, 
<ei>m^2 = E^2 - p^2</ei>. This step is prompted by an unforeseen choice 
made in some programs (like CalcHEP) of storing the nominal mass of a 
particle species rather than the mass of the current member of that 
species, a choice that is likely to induce energy-momentum nonconservation 
when the event is further processed. Obviously such a recalculation is 
problematic numerically for light particles, so it should only be used for 
the programs and particles where it is needed. Thus the value ought to be 
at least 10 GeV, so that only massive particles like <ei>W^+-</ei>, 
<ei>Z^0</ei> and <ei>t</ei> are affected. If a particle does not have 
its mass recalculated, currently instead the energy is recalculated 
from its three-momntum and mass. This is to avoid spurious mismatches 
from limited numerical precision in an LHEF. 
</parm> 
 
<flag name="LesHouches:matchInOut" default="on"> 
The energies and longitudinal momenta of the two incoming partons are 
recalculated from the sum of the outgoing final (i.e. status 1) particles. 
The incoming partons are set massless. There are two main applications 
for this option. Firstly, if there is a mismatch in the Les Houches 
input itself, e.g. owing to limited precision in the stored momenta. 
Secondly, if a mismatch is induced by PYTHIA recalculations, notably when 
an outgoing lepton, quark or hadron is assigned a mass although assumed 
massless (or with a different mass than wanted) in the Les Houches input. 
<note>Warning:</note> it is assumed that the incoming partons are along 
the <ei>+-z</ei> axis; else the kinematics construction will fail. 
</flag> 
 
<h3>Structure of Les Houches Event Files</h3> 
 
The LHEF standard (<ref>Alw06</ref>, <ref>But14</ref>) specifies a format 
where a single file packs initialization and event information. This has 
become the most frequently used procedure to process external parton-level 
events in Pythia. To access this, you must set 
<code>Beams:frameType = 4</code> and <code>Beams:LHEF</code> to be the file 
name, see <aloc href="BeamParameters">Beam Parameters</aloc>. Internally 
this name is then used to create an instance of the derived class 
<code>LHAupLHEF</code>, which can do the job of reading an LHEF. 
 
<p/> 
As some information in a Les Houches Event File init block is only known 
at the end of generation, some programs choose to output this as a 
separate file. If so, the name of this file can be specified by 
<code><aloc href="BeamParameters">Beams:LHEFheader</aloc></code>. 
 
<p/> 
The two key compulsory parts of an LHEF is the initialization information 
stored in an init block, enclosed by a matching <code>&lt;init&gt;</code> 
- <code>&lt;/init&gt;</code> pair of lines, and the event input, with each 
event enclosed by a matching <code>&lt;event&gt;</code> - 
<code>&lt;/event&gt;</code> pair of lines. In the case of the no-beams 
extension the init block may be empty, but the <code>&lt;init&gt;</code> 
and <code>&lt;/init&gt;</code> lines must be included for the file parsing 
to work as expected. It is also possible to have a non-empty init block, 
with the beams assigned code 0, and optionally a number of specified 
"processes". 
 
<p/> 
The latest update of the LHEF format <ref>But14</ref> introduced a 
multitude of different optional features. This means that apart 
from the <code>&lt;init&gt;</code> and <code>&lt;event&gt;</code> 
tags, a plethora of new, optional information is available. 
Furthermore, the inclusion of an arbitrary number of attributes into 
the tags should be supported. The LHEF reader in Pythia adheres to 
the updated LHEF format without any restriction. The new generation 
information available through the updated LHEF format can be 
retrieved by using Pythia's <code>Info</code> class. For a detailed 
description, please consult the section "Les Houches Event File 3.0 
information" in <aloc href="EventInformation">Event Information</aloc>. 
 
<p/> 
The LHEF reader can also read in and store header blocks. By default 
this option is switched on, but may be controlled through the 
<code><aloc href="BeamParameters">Beams:readLHEFheaders</aloc></code> 
flag if necessary. The information can later be read out through the 
<aloc href="EventInformation">Info</aloc> class for further processing. 
Due to the non-standard nature of the information in these blocks they 
are stored whole, and PYTHIA itself makes no further attempt to process 
their meaning. 
 
<p/> 
Because Les Houches Event files tend not to adhere strictly to XML 
conventions, to consistently read in header information, certain 
choices must be made. The primary goal is to make as much information 
available as possible. First, information sitting directly in the 
&lt;header&gt; block is stored under the key "base". Second, the tags 
starting and ending each sub block must be on their own line. Finally, 
the contents of comment blocks, &lt;!-- --&gt;, are still stored. The 
header keys are formed hierarchically from the names of the header 
blocks. This behaviour is illustrated in the following example: 
<pre> 
  &lt;header&gt; 
    BaseA 
    &lt;hblock1&gt; 
      1A 
      &lt;hblock11&gt; 
        11A &lt;hblock111&gt; 
        &lt;/hblock111&gt; 11B 
      &lt;/hblock11&gt; 
      1B 
    &lt;/hblock1&gt; 
    &lt;hblock2&gt; 
      2A 
      &lt;!-- 2B --&gt; 
    &lt;/hblock2&gt; 
    BaseB 
  &lt;/header&gt; 
</pre> 
which would lead to the following information being stored in the 
<aloc href="EventInformation">Info</aloc> class: 
<table border="1"> 
  <tr> <th>Key</th> <th>Value</th> </tr> 
  <tr> 
    <td>base</td> 
    <td>BaseA<br/>BaseB</td> 
  </tr> 
  <tr> 
    <td>hblock1</td> 
    <td>1A<br/>1B</td> 
  </tr> 
  <tr> 
    <td>hblock1.hblock11</td> 
    <td>11A &lt;hblock111&gt;<br/>&lt;/hblock111&gt; 11B</td> 
  </tr> 
  <tr> 
    <td>hblock2</td> 
    <td>2A<br/>&lt;!-- 2B --&gt;</td> 
  </tr> 
</table> 
<br/> 
<p/> 
Normally the LHEF would be in uncompressed format, and thus human-readable 
if opened in a text editor. A possibility to read gzipped files has 
been added, based on the Boost and zlib libraries, which therefore 
have to be linked appropriately in order for this option to work. 
See the <code>README</code> file in the main directory for details 
on how to do this. 
 
<p/> 
An example how to generate events from an LHEF is found in 
<code>main121.cc</code>. Note the use of 
<code>Info::atEndOfFile()</code> to find out when the whole 
LHEF has been processed. 
 
<p/> 
To allow the sequential use of several event files, the 
<code><aloc href="BeamParameters">Beams:newLHEFsameInit</aloc></code> 
can be set <code>true</code>. Then there will be no 
initialization, except that the existing <code>LHAupLHEF</code> class 
instance will be deleted and replaced by one pointing to the new file. 
It is assumed (but never checked) that the initialization information is 
identical, and that the new file simply contains further events of 
exactly the same kind as the previous one. An example of this possibility, 
and the option to mix with internal processes, is found in 
<code>main122.cc</code>. A variant, based on input in a command file, 
is given in <code>main123.cc</code>. 
 
<p/> 
In C++, real numbers are printed with an 'E' to denote the exponent part, 
e.g. 1.23E+04, and are read in accordingly. Other languages may use other 
letters, e.g. Fortran allows either 'E' or 'D'. A file using 
the latter convention would not be readable by the standard routines. 
In case you have such an "incorrectly formatted" file, a conversion to 
a new corrected file could be done e.g. using <code>sed</code>, as a 
one-line command 
<pre> 
  sed -e 's/\([0-9]\.\{0,1\}\)[dD]\([+-]\{0,1\}[0-9]\)/\1E\2/g' old.lhe &gt; new.lhe 
</pre> 
This replaces a 'd' or 'D' with an 'E' only when it occurs in the combination 
<br/> 
<ei>(digit) ('.' or absent) ('d' or 'D') ('+', '-' or absent) (digit)</ei> 
<br/>It will work on all parts of the file, also inside a 
<code>&lt;header&gt;...&lt;/header&gt;</code> block. For conversion only 
inside the <code>&lt;init&gt;...&lt;/init&gt;</code> and 
<code>&lt;event&gt;...&lt;/event&gt;</code> blocks, create a file 
<code>convert.sed</code> containing 
<pre> 
  /&lt;init&gt;/,/&lt;\/init&gt;/bconv 
  /&lt;event&gt;/,/&lt\/event&gt;/bconv 
  b 
  :conv 
  s/\([0-9]\.\{0,1\}\)[dD]\([+-]\{0,1\}[0-9]\)/\1E\2/g 
</pre> 
and run it with 
<pre> 
  sed -f convert.sed old.lhe &gt; new.lhe 
</pre> 
 
<h4>Header information</h4> 
 
A simple string key/value store, mainly intended for accessing 
information that is stored in the header block of Les Houches Event 
(LHE) files. In principle, any <code>LHAup</code> derived class can set 
this header information, which can then be read out later. Although the 
naming convention is arbitrary, in practice, it is dictated by the 
XML-like format of LHE files. 
 
<method name="string Info::header(string key)"> 
return the header named <code>key</code> 
</method> 
 
<method name="vector &lt;string&gt; Info::headerKeys()"> 
return a vector of all header key names 
</method> 
 
<method name="void Info::setHeader(string key, string val)"> 
set the header named <code>key</code> with the contents of <code>val</code> 
</method> 
 
<h3>Retrieving the information read from LHEF</h3> 
 
Information passed to PYTHIA through LHE files is handled in, and can 
be retrieved by two ways. The collection of particles transferred through 
the Les Houches event is directly accessible through the event record. A 
copy of the hard scattering event (i.e. the hard particle identifiers, colors, 
momenta etc. read from the Les Houches event file) is stored in the 
<code>process</code> data member of the <code>Pythia</code> instance. It can 
for example be printed to the terminal by calling 
<code>pythia.process.list()</code>. 
 
All other information (e.g. stored in headers, the LHEF init block, 
or non-particle tags of the current event, such as weight information) is 
accessible through the <code>Info</code> class. 
 
<p> 
 
If some information has been 
 
<p/> 
Les Houches Event files can conform to version 1.0 
(as agreed upon in <ref>Alw06</ref>) and version 3.0 
of the standard (version 2.0 having been extended to 3.0 in <ref>But14</ref>). 
The LHEF version of an input file can can be accessed by 
<br/><methodmore name="int Info::LHEFversion()"> 
</methodmore> 
 
 
 
<h4>LHEF 1.0 information</h4> 
 
Please find below the documentation of LHEF 1.0 information as stored in 
the <code>Info</code> class. 
Note also the description of some settings in the 
<aloc href="BeamParameters">Beam Parameters</aloc> section. 
Theinformation is divided into the 
<code>header</code>, <code>init</code> and <code>event</code> blocks. 
The information stored in the <code>header</code> and <code>init</code> 
is: 
 
<ol class="listextraspace"> 
<ul class="listnoextraspace"> 
<li> To check if the process information has been generated by 
external Les Houches Accord, you can infer the function <code>bool 
Info::isLHA()</code>.  As convenience feature, it is also possible to 
check if the end of the file from which events have been read in has 
been reached by calling <code>bool Info::atEndOfFile()</code>. 
</li> 
</ul> 
<ul class="listnoextraspace"> 
<li> 
If the process has been transferred through LHEF, then you can retrieve 
the cross section values and errors by calling 
<code>double Info::sigmaGen(int i = 0)</code> and 
<code>double Info::sigmaErr(int i = 0)</code>. Please consult the 
<aloc href="EventInformation">Event Information</aloc> section for further 
details. Alternatively, you may use the functions 
<method name="int Info::nProcessesLHEF()"> 
to retrieve the number of cross sections stored in the LHEF <code>init</code> 
block 
</method> 
<method name="double Info::sigmaLHEF(int i=0)"> 
to retrieve the value of i'th cross sections stored in the LHEF 
<code>init</code> block 
</method> 
</li> 
</ul> 
<ul class="listnoextraspace"> 
<li> 
The weighting strategy indicated in the <code>init</code> block can be 
retrieved by calling <code>int Info::lhaStrategy()</code>. 
</li> 
</ul> 
</ol> 
 
</p> 
The event-by-event information read from the <code>event</code> block is: 
 
<ol class="listextraspace"> 
<ul class="listnoextraspace"> 
<li> 
The scale associated with the event, which can be obtained from a 
call to <code>double Info::scalup()</code>, see the 
<aloc href="EventInformation">Event Information</aloc> section for further 
details. 
</li> 
</ul> 
<ul class="listnoextraspace"> 
<li> 
The weight associated with the event can be retrieved from a call to 
<code>double Info::weight()</code>, see the 
<aloc href="EventInformation">Event Information</aloc> section for further 
details. 
</li> 
</ul> 
</ol> 
 
<h4>LHEF 3.0 information</h4> 
 
Please find below the documentation of LHEF 3.0 information as stored in 
the <code>Info</code> class. An example main program using LHEF 3.0 
information is <code>main127.cc</code>. Note also the description of some 
settings in the <aloc href="BeamParameters">Beam Parameters</aloc> section. 
 
LHEF 3.0 offers new features both in the initialisation and the event sections 
of the input files. Possible information include extended 
use of XML tags in the <code>&lt;header&gt;</code> and 
<code>&lt;init&gt;</code> and <code>event</code> blocks. This LHEF 3.0 
information is stored in the <code>Info</code> class in a series 
<code>struct</code>'s: 
 
<ol class="listextraspace"> 
<ul class="listnoextraspace"> 
<li> 
The <code>&lt;initrwgt&gt;</code> tag is a container 
tag for weight and weightgroup tags.   This information is stored 
internally in <code>LHAinitrwgt</code>. 
Currently, there is no dedicated 
output for this tag. However, all the information stored in the tag can 
be retrieved by using the <code>Info</code> class member pointer 
<code>LHAinitrwgt Info::initrwgt</code>. 
</li> 
</ul> 
<ul class="listnoextraspace"> 
<li> 
Multiple <code>&lt;weightgroup&gt;</code> tags: 
Container tag for weight tags. Currently, there is no dedicated 
output for this tag. However, all the information stored in the tag can 
be retrieved by using the <code>Info</code> class member pointer 
<code>vector&lt;LHAweightgroups&gt; * Info::weightgroups</code>. 
</li> 
</ul> 
<ul class="listnoextraspace"> 
<li> 
Multiple <code>&lt;weight&gt;</code> tags: Tag defining 
auxiliary information on an event weight, e.g. the identifier and information 
on what the weight represents. All the information stored in the tag can 
be retrieved by using the <code>Info</code> class member pointer 
<code>vector&lt;LHAweightgroups&gt; * Info::init_weights</code>. This vector 
contains all <code>&lt;weight&gt;</code> tags in the 
<code>&lt;initrwgt&gt;</code> container and its subcontainer 
<code>&lt;weightgroup&gt;</code> tags. The size of the vector can be accessed 
through the method 
<br/><methodmore name="int Info::getInitrwgtSize()"> 
</methodmore> 
</li> 
</ul> 
<ul class="listnoextraspace"> 
<li> 
Multiple <code>&lt;generator&gt;</code> tags: Store 
information on the generators used in the event generation. All the 
information stored in the tag can be retrieved by using the 
<code>Info</code> class member pointer 
<code>vector&lt;LHAgenerators&gt; * Info::generators</code>. More easy-to-use 
output functions are available. The size of this vector can be obtained from 
<br/><methodmore name="int Info::getGeneratorSize()"> 
</methodmore> 
<p/> 
The contents of an individual <code>&lt;generator&gt;</code> tag can 
be accessed through the method 
<br/><methodmore name="string Info::getGeneratorValue(unsigned int n = 0)"> 
Return the contents of the n'th <code>&lt;generator&gt;</code> tag in 
the vector of tags. 
</methodmore> 
 
<p/> 
Attributes of the <code>&lt;generator&gt;</code> tag (e.g. the generator 
<code>name</code> and <code>version</code>) can be accessed via 
<br/><methodmore name="string Info::getGeneratorAttribute(unsigned int n, 
string key, bool doRemoveWhitespace = false)"> 
Return the value of the generator attribute named <code>key</code> for 
the n'th generator in the vector. Setting <code>doRemoveWhitespace</code> to 
true will return the value, stripped of any whitespace. An empty string is 
returned if the attribute named <code>key</code> does not exist. 
</methodmore> 
</li> 
</ul> 
</ol> 
 
<p/> 
Note that the complete header can be obtained with the <code>Info</code> class 
member <code>string getHeaderBlock()</code>. For more information 
on the header block, please see the <ei>Header information</ei> paragraph 
above. Finally, to obtain information on cross sections, the following two 
methods can be used 
<br/><methodmore name="int Info::nProcessesLHEF()"> 
return the number of processes for which the cross section is stored. 
</methodmore> 
<br/><methodmore name="double Info::sigmaLHEF(int iProcess)"> 
return the cross section of the <code>iProcess</code>'th process. 
</methodmore> 
 
<p/> 
LHEF 3 also greatly extended the possible information stored within 
<code>&lt;event&gt;</code> blocs. In particular, multiple weights are 
supported, as are multiple scale values. Possible information from extended 
use of XML tags in the <code>&lt;event&gt;</code> block is: 
 
<ol class="listextraspace"> 
<ul class="listnoextraspace"> 
<li> 
The <code>&lt;rwgt&gt;</code> tag is a container 
tag for wgt tags. Currently, there is no dedicated 
output for this tag. It can however be retrieved by using the 
<code>Info</code> class member pointer 
<code>LHArwgt Info::rwgt</code>. 
</li> 
</ul> 
<ul class="listnoextraspace"> 
<li> 
Multiple <code>&lt;wgt&gt;</code> tags: Tag defining 
the event weight in the detailed version of LHEF 3.0.  All the information 
stored in the tag can be retrieved by using the <code>Info</code> class 
member pointer <code>vector&lt;LHAwgt&gt; * Info::weights_detailed</code>. 
More easy-to-use output functions are available. The size of this vector 
can be obtained from 
<br/><methodmore name="unsigned int Info::getWeightsDetailedSize()"> 
</methodmore> 
 
A convenient access point to the information stored in the 
<code>&lt;wgt&gt;</code> tags is the <code>Info</code> class member 
<code>vector&lt;double&gt; Info::weights_detailed_vector</code>. The 
entries of this vector are ordered according to how <code>&lt;wgt&gt;</code> 
tags appear in the event block. 
 
<p/> 
The contents of a <code>&lt;wgt&gt;</code> tag can be accessed through the 
method 
<br/><methodmore name="double Info::getWeightsDetailedValue(string n)"> 
Return the value of the n'th <code>&lt;wgt&gt;</code> tag in the 
event. 
</methodmore> 
 
<p/> 
Attributes of the <code>&lt;wgt&gt;</code> tag (e.g. the weight 
<code>id</code>) can be accessed via 
<br/> 
<methodmore name="string Info::getWeightsDetailedAttribute(string n, 
string key, bool doRemoveWhitespace = false)"> 
Return the value of the wgt attribute named <code>key</code> for 
the n'th wgt in the vector. Setting <code>doRemoveWhitespace</code> to 
true will return the value, stripped of any whitespace. An empty string is 
returned if the attribute named <code>key</code> does not exist. 
</methodmore> 
 
</li> 
</ul> 
<ul class="listnoextraspace"> 
<li> 
The <code>&lt;weights&gt;</code> tag: Tag containing 
 a vector of <code>double</code> entries for weights in the compressed version 
 of LHEF 3.0. All the information stored in the tag can be retrieved by using 
 the <code>Info</code> class member pointer <code> LHAweights * 
 Info::weights</code> and the vector <code> vector&lt;double&gt; 
 Info::weights_compressed</code>. More easy-to-use output functions are 
 available. The size of this vector can be obtained from 
<br/><methodmore name="unsigned int Info::getWeightsCompressedSize()"> 
</methodmore> 
 
<p/> 
The n'th weight can be accessed through the method 
<br/> 
<methodmore name="double Info::getWeightsCompressedValue(unsigned int n)"> 
</methodmore> 
 
<p/> 
Attributes of the <code>&lt;weights&gt;</code> tag (not normally used) can be 
accessed via 
<br/> 
<methodmore name="string Info::getWeightsCompressedAttribute(string key, 
bool doRemoveWhitespace = false)"> 
Return the value of the <code>&lt;weights&gt;</code> tag's attribute 
named <code>key</code>. Setting <code>doRemoveWhitespace</code> to 
true will return the value, stripped of any whitespace. An empty string is 
returned if the attribute named <code>key</code> does not exist. 
</methodmore> 
 
</li> 
</ul> 
<ul class="listnoextraspace"> 
<li> 
The <code>&lt;scales&gt;</code> tag: Contains information 
 on different scales used by the matrix element generator. All the information 
 stored in the tag can be retrieved by using the <code>Info</code> class 
 member pointer <code> LHAweights * Info::scales</code>. More easy-to-use 
 output functions are available. The contents of the scales tag can be 
 obtained from 
<br/><methodmore name="string Info::getScalesValue()"> 
</methodmore> 
 
<p/> 
However, note that the actual scale values are stored as attributes (called 
e.g. <code>muf</code> or <code>mur</code>). Attributes of the 
<code>&lt;scales&gt;</code> tag can be accessed via 
<br/><methodmore name="double Info::getScalesAttribute(string key)"> 
Return the value of the <code>&lt;scales&gt;</code> tag's attribute 
named <code>key</code>. Not-a-number will be returned if the attribute 
named <code>key</code> does not exist. 
</methodmore> 
 
</li> 
</ul> 
<ul class="listnoextraspace"> 
<li> 
Finally, arbitrary attributes of the <code>&lt;event&gt;</code> tag are 
supported. Attributes of the <code>&lt;event&gt;</code> tag can be accessed by 
<br/> 
<methodmore name="string Info::getEventAttribute(string key, 
bool doRemoveWhitespace = false)"> 
return the value of the event attribute named <code>key</code>. Setting 
<code>doRemoveWhitespace</code> to true will return the value, stripped of 
any whitespace. An empty string is returned if the attribute named 
<code>key</code> does not exist. 
</methodmore> 
Additional comments appearing in the <code>&lt;event&gt;</code> tag 
can be obtained with the <code>Info</code> class member 
<code>string getEventComments()</code>. 
 
</li> 
</ul> 
</ol> 
 
<h3>PYTHIA 8 output to a Les Houches Event File version 1.0</h3> 
 
The above methods could be used by any program to write an LHEF. 
For PYTHIA 8 to do this, a derived class already exists, 
<code>LHAupFromPYTHIA8</code>. In order for it to do its job, 
it must gain access to the information produced by PYTHIA, 
specifically the <code>process</code> event record and the 
generic information stored in <code>info</code>. Therefore, if you 
are working with an instance <code>pythia</code> of the 
<code>Pythia</code> class, you have to instantiate 
<code>LHAupFromPYTHIA8</code> with pointers to the 
<code>process</code> and <code>info</code> objects of 
<code>pythia</code>: 
<br/><code>LHAupFromPYTHIA8 myLHA(&pythia.process, &pythia.info);</code> 
 
<p/> 
The method <code>setInit()</code> should be called to store the 
<code>pythia</code> initialization information in the LHA object, 
and <code>setEvent()</code> to store event information. 
Furthermore, <code>updateSigma()</code> can be used at the end 
of the run to update cross-section information, cf. 
<code>closeLHEF(true)</code> above. An example how the 
generation, translation and writing methods should be ordered is 
found in <code>main124.cc</code>. 
 
<p/> 
Currently there are some limitations, that could be overcome if 
necessary. Firstly, you may mix many processes in the same run, 
but the cross-section information stored in <code>info</code> only 
refers to the sum of them all, and therefore they are all classified 
as a common process 9999. Secondly, you should generate your events 
in the CM frame of the collision, since this is the assumed frame of 
stored Les Houches events, and no boosts have been implemented 
for the case that <code>Pythia::process</code> is not in this frame. 
 
<p/> 
The LHEF standard is the agreed format to store the particles of a 
hard process, as input to generators, whereas output of final states 
is normally handled using the <aloc href="HepMCInterface">HepMC</aloc> 
standard. It is possible to use LHEF also here, however. It requires 
that the above initialization is replaced by 
<br/><code>LHAupFromPYTHIA8 myLHA(&pythia.event, &pythia.info);</code> 
<br/> i.e. that <code>process</code> is replaced by <code>event</code>. 
In addition, the <code>PartonLevel:all = off</code> command found in 
<code>main124.cc</code> obviously must be removed if one wants to 
obtain complete events. 
 
<h3>PYTHIA 8 output to a Les Houches Event File version 3.0</h3> 
 
PYTHIA 8 also supports LHEF 3.0 output, and we include a 
general LHEF3 writer (<code>Pythia::Writer</code> of LHEF3.h and 
LHEF3.cc) for this purpose. The functions of this 
file writer are used in the <code>LHEF3FromPYTHIA8</code>. 
This latter class allows users to output PYTHIA events 
in LHEF3 format from a PYTHIA main program. An example of how to use 
<code>LHEF3FromPYTHIA8</code> is found in the 
<code>main125.cc</code> example. Please note that, although 
similar, the usage of <code>LHEF3FromPYTHIA8</code> differs from 
the usage of <code>LHAupFromPYTHIA8</code>, with  <code>LHEF3FromPYTHIA8 
</code> requiring fewer function calls. 
 
<p/> 
To print a comprehensive LHE file, <code>LHEF3FromPYTHIA8</code> 
is constructed with pointers to an <code>Event</code> object, 
as well as pointers to instances of <code>Settings</code>, 
<code>Info</code> and <code>ParticleData</code>, giving e.g. 
a constructor call 
<br/><code>LHEF3FromPYTHIA8 myLHEF3(&pythia.event, &pythia.settings, 
&pythia.info, &pythia.particleData);</code> 
 
<p/> 
As a next step, you should open the output file by using the 
<code>LHAupFromPYTHIA8</code> member function 
<br/><code>openLHEF(string name)</code> 
<br/> 
where <code>name</code> is the output file name. 
 
<p/> 
Then, the method <code>setInit()</code> should be called to store the 
initialization information (read from <code>settings</code> and 
<code>info</code>) and write the header and init blocks into the 
output file. Note that at this stage, the cross section printed 
in the init block is not sensible, as no integration has yet 
taken place. The init block can be updated at the end of 
the event generation (see below). 
 
<p/> 
During event generation, you should use <code>setEvent()</code> to 
write the event information (as read from <code>info</code> and 
<code>event</code>) to the output file. 
 
<p/> 
Finally, before leaving your main program, it is necessary to 
close the output file by using the 
<code>LHAupFromPYTHIA8</code> member function 
<br/><code>closeLHEF( bool doUpdate = false)</code> 
<br/> 
The boolean variable <code>doUpdate</code> is optional. 
If <code>doUpdate</code> is used, and if 
<code>doUpdate = true</code>, then the init block of the output 
file will be updated with the latest cross section information. 
 
<p/> 
Currently there are some limitations, that could be overcome if 
necessary. Firstly, you may mix many processes in the same run, 
but the cross-section information stored in <code>info</code> only 
refers to the sum of them all, and therefore they are all classified 
as a common process 9999. Secondly, you should generate your events 
in the CM frame of the collision, since this is the assumed frame of 
stored Les Houches events, and no boosts have been implemented 
for the case that <code>Pythia::process</code> is not in this frame. 
 
</chapter> 
 
<!-- Copyright (C) 2026 Torbjorn Sjostrand --> 
