# Input and output formats¶

## Input formats¶

### Les Houches Event Files¶

In order to use partonic events generated by an external matrix-element generator, a LesHouchesEventHandler object has to be created in the repository. This object is supplied with at least one LesHouchesReader object. LesHouchesReader objects represent event files according to the Les Houches accord or the reading of events in the same format ‘on the fly’ using pipes.

Here we give an example on how to use LHA event files. Reading of events is performed by the LesHouchesReader. This class can handle arbitrary event files in the Les Houches format.

The corresponding libraries need to be loaded in the input file

library LesHouches.so


Suppose the event file is named myEvents.lhe. We assume it contains some process of interest at LHC. First, a LesHouchesReader object needs to be created and given the name of the sample file

cd /Herwig/EventHandlers


In principle, the information needed to generate full events, i.e. beam energies, incoming particles and parton distributions is extracted from the event file, but may also be set explicitly. For these switches, see the interface documentation of LesHouchesReader.

In some cases ThePEG has to scan through the file in order to get an idea about the weights appearing and to precalculate the cross section. In this a cache file has to be specified with e.g.

set myReader:CacheFileName cache.tmp


If the file is very long one can limit the effort of scanning e.g. to 1000 events with

set myReader:maxScan 1000


Cuts can not be extracted from event files in general. If the interface value

set myReader:InitCuts 0


is assigned, the reader expects to be given a Cuts object. For example, typical cuts for hadron collisions may be chosen

set myReader:Cuts /Herwig/Cuts/QCDCuts


Completely open cuts can be set with

create ThePEG::Cuts NoCuts


Several cuts can be found in the repository directory /Herwig/Cuts and cuts are discussed in more detail in the section on cuts.

Similar remarks apply to the use of parton distribution functions, which can be set explicitly using

set myReader:InitPDFs 0


where firstBeamPDF and secondBeamPDF are PDFBase objects. Here, either the build in PDF sets or LHAPDF may be used, see using LHAPDF. Note that the PDF sets have to match the ones being used for matrix element event generation.

Next an LesHouchesEventHandler object has to be created. Objects of this class inherit from EventHandler and provide the same interfaces. Thus the setup is similar to the setup of a usual event handler, which needs to be equipped with showering, hadronization and decay handlers

create ThePEG::LesHouchesEventHandler myLesHouchesHandler
set myLesHouchesHandler:DecayHandler /Herwig/Decays/DecayHandler
set myLesHouchesHandler:PartonExtractor /Herwig/Partons/QCDExtractor


A Cuts object applying to all processes may be set as for every EventHandler. Finally, the readers from which the event handler should draw events from have to be specified:

insert myLesHouchesHandler:LesHouchesReaders 0 myReader
...


An arbitrary number of readers may be used.

A default or custom EventGenerator object may now use the LesHouchesEventHandler object myLesHouchesHandler and a run file can be created from this event generator:

cd /Herwig/Generators
cp LHCGenerator myLesHouchesGenerator
set myLesHouchesGenerator:EventHandler /Herwig/EventHandlers/myLesHouchesHandler
saverun myLesHouches myLesHouchesGenerator


There is also support for multiple alternative weights according to the latest Les Houches accord (version 3). The supported files should include in their <init> block the following

<initrwgt>
<weightgroup type='type information' combine='combination information'>
<weight id='XXXX'> weight information </weight>
...
</weightgroup>
...
</initrwgt>


and each event should contain the relevant information in the form

<rwgt>
<wgt id='XXXX'> value_of_weight </wgt>
...
</rwgt>


An example analysis of weights is included in the Contrib MultiWeight library found in Contrib.

Herwig supports the option of using the QNumbers block to define new particles and their decays in Les Houches event files. This is switched off by default and can be enabled using

set myReader:QNumbers Yes


In addition a Decayer object is needed to perform the decays and can be specified using

set myReader:Decayer /Herwig/Decays/Mambo


Often the new particles have to be decayed as part of the showering process as their decays produce new coloured particles which must be showered. This must be done using

insert /Herwig/Shower/ShowerHandler:DecayInShower 0 PDG_NUMBER


where PDG_NUMBER is the particle’s PDG code.

## Output and analyses formats¶

While there is an internal mechanism for performing the analysis of the events generated by Herwig we would recommend that you only make use of it to either output the events to a file in the HepMC format, or call the Rivet package to analyse the events. This mechanism works by calling a number of AnalysisHandler classes from the EventGenerator.

### HepMC¶

The HepMCFile file analysis can be used to output the events in the file in the HepMC format

insert LHCEventGenerator:AnalysisHandlers 0 /Herwig/Analysis/HepMCFile
set /Herwig/Analysis/HepMCFile:PrintEvent 100
set /Herwig/Analysis/HepMCFile:Format GenEvent
set /Herwig/Analysis/HepMCFile:Units GeV_mm


which will output the events in the file NameOfEventGenerator.hepmc.

### Rivet Analysis¶

The ​Rivet package can be used to analyse events generated by Herwig by directly calling the Rivet code from within Herwig. In order to do this ThePEG should be configured with

--with-rivet=location of installed Rivet code
--with-hepmc=location of installed HepMC code


which is done by default with the booststrap script.

This is will ensure that the RivetAnalysis AnalysisHandler class is built as a dynamically loadable library. This AnalysisHandler can be used by adding

create ThePEG::RivetAnalysis /Herwig/Analysis/RivetAnalysis RivetAnalysis.so
insert /Herwig/Generators/LHCGenerator:AnalysisHandlers 0 /Herwig/Analysis/RivetAnalysis
insert /Herwig/Analysis/RivetAnalysis:Analyses 0 name_of_rivet_analysis


to your Herwig input files. Any number of Rivet analyses can then be enabled using the Analyses interface of the RivetAnalysis class.

### Delphes¶

Delphes is a C++ framework, performing a fast multipurpose detector response simulation. Herwig does not possess a custom interface to Delphes, however, a HepMC stream can be used for this purpose.

For example, one uses the LHC.in file to generate a .hepmc file called LHC.hepmc:

insert LHCGenerator:AnalysisHandlers 0 /Herwig/Analysis/HepMCFile
set /Herwig/Analysis/HepMCFile:PrintEvent 1000
set /Herwig/Analysis/HepMCFile:Format GenEvent
set /Herwig/Analysis/HepMCFile:Units GeV_mm
set /Herwig/Analysis/HepMCFile:Filename LHC.hepmc


run Herwig, e.g. for 1000 events:

Herwig read LHC.in; Herwig run LHC.run -N1000


This generates a .hepmc file: LHC.hepmc. One then needs to generate a fifo file:

rm test.fifo; mkfifo test.fifo


and run, for example, the following:

rm test.root; cat LHC.hepmc > /tmp/test.fifo & cat /tmp/test.fifo | [path_to_delphes]/DelphesHepMC [path_to_delphes]/cards/delphes_card_ATLAS.tcl test.root


The Delphes output file is test.root.