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.

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
create ThePEG::LesHouchesFileReader myReader
set myReader:FileName myEvents.lhe

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/Cuts

Completely open cuts can be set with

create ThePEG::Cuts NoCuts
set myReader: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
set myReader:PDFA firstBeamPDF
set myReader:PDFB secondBeamPDF

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:CascadeHandler /Herwig/Shower/ShowerHandler
set myLesHouchesHandler:HadronizationHandler /Herwig/Hadronization/ClusterHadHandler
set myLesHouchesHandler:DecayHandler /Herwig/Decays/DecayHandler
set myLesHouchesHandler:PartonExtractor /Herwig/Partons/QCDExtractor
insert myLesHouchesHandler:PreCascadeHandlers 0 /Herwig/NewPhysics/DecayHandler
insert myLesHouchesHandler:PostSubProcessHandlers 0 /Herwig/QEDRadiation/QEDRadiationHandler

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
insert myLesHouchesHandler:LesHouchesReaders 1 myOtherReader
...

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 EventGenerator 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.

In addition in SUSY models we can read the SLHA file from the header of the Les Houches event file. You should select the relevant SUSY model, for example for the MSSM, using

read MSSM.model

and instruct it to read the SLHA information from the header using

setup /Herwig/NewPhysics/MSSM/Model myEvents.lhe

For some of the simplified model scenarios which are currently used the SLHA files are not consistent and it is advisable to switch to phase space decays and guard against missing information using

set /Herwig/NewPhysics/NewModel:WhichOffshell Selected
clear /Herwig/NewPhysics/NewModel:DecayParticles
set /Herwig/NewPhysics/MSSM/Model:CreateDiagonalMixingMatrices Yes

N.B. these commands should be executed before the setup command for the model and after the model is read. We would advise the commands are just after the selection of the collider type at the top of the input file.

Output and analysis 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

read snippets/HepMC.in
set HepMC:PrintEvent NNN

where NNN ist the number of events stored in the file NameOfEventGenerator.hepmc. Caution: If you run fixed order, ie NO shower, you should use instead

read snippets/HepMCFixedOrder.in
set HepMCFixedOrder:Print NNN

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

read snippets/Rivet.in
insert Rivet: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. Caution: If you run fixed order, ie NO shower, you should use instead

read snippets/RivetFixedOrder.in
insert RivetFixedOrder:Analyses 0 name_of_rivet_analysis

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 EventGenerator: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. Then run, for example, the following:

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

The Delphes output file is test.root.

User-defined ROOT files

There is no built-in interface to ROOT. Interested users may have a look at the example analysis code HwSim.