= Generating Event Output in Les-Houches Format =

The default procedure for generating particle-level event output in GiBUU is via the "Les Houches" event-file standard, which is described in detail in the following papers:

 * J. Alwall et al., A Standard format for Les Houches event files [http://inspirehep.net/record/725284 Inspire],
 * E. Boos et al., Generic user process interface for event generators [http://inspirehep.net/record/562546 Inspire].

To generate event output in Les-Houches format, your jobcard should contain a part which sets the switches in the namelist '!EventOutput':

{{{
&EventOutput
  WriteRealParticles = T           ! print out real particle vector
  WritePerturbativeParticles = T   ! print out perturbative particle vector
  EventFormat = 1                  ! 1=LesHouches, 2=OSCAR, 3=Shanghai
/
}}}

Setting the first switch to T (.true.) will produce files called '!LesHouches.Real.*.xml' (with * being the run number) containing events which list all real particles, while setting the second switch to T will produce files called '!LesHouches.Pert.*.xml' containing events which list all perturbative particles. The files have an XML-like format which will be described below.

== Les Houches file structure ==

The rough structure of a Les-Houches event file looks like this:

{{{
<LesHouchesEvents version="1.0">
  <header>
    ...
  </header>
  <init>
    ...
  </init>
  <event>
    ...
  </event>
  ... (any number of <event> blocks can follow) ...
</LesHouchesEvents>
}}}

After the <header> and <init> blocks, the file essentially contains a list of event blocks, each of which begins with an opening <event> tag and ends with a corresponding </event> tag. There can be an arbitrary number of events in one file (depending on the input parameters of the simulation). The specific contents of the blocks will be described below. Note that the <header> and <init> blocks do not contain any relevant information in the current GiBUU implementation (and therefore can be ignored). Note that the closing </!LesHouchesEvents> tag may be missing in some cases.

== The <event> block ==

Each event block contains the full description of a single event, which basically consists of a list of produced particles (with their corresponding four-momentum vectors etc). An example event might look like this:

{{{
<event>
   3  0  1.  0.  0.  0.
  2212  0  0  0  0  0 -0.264  0.275  3.468  3.613  0.938  0. 9.
  2112  0  0  0  0  0  0.267 -0.052  0.138  0.986  0.938  0. 9.
   211  0  0  0  0  0 -0.003 -0.222  0.730  0.776  0.138  0. 9.
</event>
}}}

The first line in the <event> block has a special meaning: In the first column it contains the number of particles (N) and in the third column the weight (w) of the event, while the other columns can contain additional parameters (which are not used in the current GiBUU implementation). For real events, the weight w equals 1 (i.e. all events have the same weighting). For perturbative events, on the other hand, the weight is usually related to the total cross section for the process (and can be different for each event).

Each of the following lines represents one particle. The columns of these lines have the following meaning:

 * 1: ID code of the particle (in [http://pdg.lbl.gov/2013/reviews/rpp2012-rev-monte-carlo-numbering.pdf PDG numbering scheme], which differs from our internal [wiki:ParticleIDs GiBUU numbering scheme]). This number determines the identity and charge of the particle.
 * 2-6: Unused (always 0).
 * 7-9: 3-momentum (px, py, pz) of the particle in GeV. Usually the z-axis corresponds to the beam direction.
 * 10: Energy E of the particle in GeV.
 * 11: Mass m of the particle in GeV.
 * 12: Unused (0).
 * 13: Spin of the particle ('9'=unknown).

The example event shown above contains a three-body final state, consisting of a proton, neutron and pi+ (produced in a pp collision).

== Additional process-specific information in the <event> block ==

There can be one additional line at the end of the <event> block (after the list of particles), which starts with a "#" and contains process-specific information for different event types:

 * In the case of !HiLepton events, this line is:
{{{
# 14 nu Q2 eps phiLepton Eventtype
}}}
   * 14 is the magic number of high-energy lepton-induced events
   * cf. Electron_origin.f90 for a list of Eventtypes
 * In the case of neutrino events, the line line is given as:
{{{
# 5 Eventtype Weight momLepIn(0:3) momLepOut(0:3) momNuc(0:3)
}}}
   * 5 is the magic number of neutrino-induced events
   * Eventtype: 1=QE, 2-31=res ID, 32,33=1pi, 34=DIS, 35,36=2p2h, 37=2pi
   * 'Weight' is the same event weight that also appear in the general event-block header
   * 'momLepIn' is the four-momentum of the incoming lepton (neutrino)
   * 'momLepOut' is the four-momentum of the outgoing lepton
   * 'momNuc' is the four-momentum of the outgoing struck nucleon
 * In the case of heavy-ion events, the line is:
{{{
# 1 b
}}}
   * 1 is the magic number of heavy-ion collisions
   * 'b' is the impact parameter in fm
 * In the case of hadron-induced events, the line is: 
{{{
# 300 b
}}}
   * 300 is the magic number of hadron-induced events
   * 'b' is the impact parameter in fm 
 * For all other event types, this line is absent.