A look at input files

An excursion to our repository system

The event generator Herwig is programmed in a way that all modules can be configured and put together at runtime in the Repository system of ThePEG. What happens when Herwig is run is that an EventGenerator object is asked for events. Which event generator it really is, is configured only in the input files and finally prepared for running with the last line of your input file that says

saverun LHC-Matchbox EventGenerator

How is this EventGenerator set up? In fact, many, many objects are put together to finally build this EventGenerator. You don’t have to understand all the details in order to use Herwig, though. In fact, the average user gets by with knowing very little about the repository system. Nevertheless, it’s worth spending some time to learn about it in order to understand possible mistakes when you set your own parameters.

All objects are set up from a default repository that is set up from the file

<HERWIGPATH>/share/Herwig/defaults/HerwigDefaults.in

Note: You should never change the Herwig default repository. Instead you can easily make each necessary change in your own Herwig input file while using the default repository.

The Herwig default repository in turn reads in several other files with the statement

read <otherfile>.in

In this way all generators are set up. Search for EventGenerator in HerwigDefaults.in. The first line you find says

create ThePEG::EventGenerator EventGenerator

In fact, now one instance of an object ThePEG::EventGenerator is created and given the name EventGenerator at this point. You could look at the actual code for the ThePEG::EventGenerator in the subdirectory Repository of your ThePEG installation later. Now, the name of the EventGenerator is not quite its full name, please read on to understand why.

Where is this strange file system?

In fact, if you scroll a few lines up from the create command we have just inspected, you find the lines

mkdir /Herwig/Generators
cd /Herwig/Generators

but perhaps you have not found the actual files that you would expect. This is because the repository system allows us to put virtual prefixes in front of the object names that are given. The two lines above just create one prefix /Herwig/Generators and then, with the cd command this prefix is chosen as the default for all coming objects, unless they are addressed globally. This is just to keep the tons of objects that we are creating for our generators nice and tidy in groups.

Given this logic, you may now understand that the line

create ThePEG::EventGenerator /Herwig/Generators/EventGenerator

inserted anywhere in an input file, is equivalent to our two lines

cd /Herwig/Generators
create ThePEG::EventGenerator EventGenerator

So, there is no real file system!

Putting objects together and setting parameters

Now, with only these lines there is not much but a bare EventGenerator object. In order to fill it with life, physics in our case, we have to give it some more parameters, mostly other objects. This is done with the lines following the create command, that start with the directive newdef. For example, the line

newdef EventGenerator:EventHandler /Herwig/EventHandlers/EventHandler

newdef simply means that here we have a new, or first, definition of a parameter. We set the parameter EventHandler of the object EventGenerator, addressed as EventGenerator:EventHandler to the value /Herwig/EventHandlers/EventHandler. So, the parameter EventHandler has to be an object of the type EventHandler. The EventHandler is one of these objects. You can find that this was created a bit further up in the default Herwig repository. By the way, the EventHandler is the object that handles a single hadron collider event, as you could have guessed.

Now, you can look at how the EventHandler, with prefix /Herwig/EventHandlers/ is given the parameters it expects, further above, and so forth. If you think about this a little bit you can perhaps imagine that this leads to a huge tree of such definitions that are all hidden behind the various read commands in this file.

You will perhaps never use the newdef command. Instead, you usually change parameters with the set command. Look at the command line

newdef Luminosity:Energy 8000.0

that sets the centre-of-mass energy to 8 TeV by default. You can easily change this with

cd /Herwig/EventHandlers
set Luminosity:Energy 13000.0*GeV

or

set /Herwig/EventHandlers/Luminosity:Energy 13000.0*GeV

to 13 TeV (note the usage of units, which is safer, only we sometimes omit the units because we think that we really know what we’re doing ;-) ). Take good care of the cd commands, because results can be confusing if you forget that the prefixes are always needed or better use absolute paths whenever possible.

There is only one more command that appears in order to configure the objects in the repository, in HerwigDefaults.in you find the line

insert EventHandler:SubProcessHandlers[0] /Herwig/MatrixElements/SubProcess

Here, the actual parameter to set is a vector. So the object Herwig/MatrixElements/SubProcess is inserted into the vector of SubProcessHandlers of the EventHandler. The index [0] inserts it into the next free spot, like on a stack. Other indices are normally not needed.

Rather than use the EventHandler and EventGenerator objects which are set up for specific colliders the Matchbox input files create their own EventGenerator and EventHandler objects in the snippet read at the top of the input file, for example by reading

read Matchbox/PPCollider.in

for hadron-hadron collisions.

Have a look at the configuration of the generator

Now we can go back and have a look at the LHC-Matchbox.in file. At this point it looks like the following

# -*- ThePEG-repository -*-

##################################################
## Herwig/Matchbox example input file
##################################################

##################################################
## Collider type
##################################################
read snippets/Matchbox.in
read snippets/PPCollider.in

##################################################
## Beam energy sqrt(s)
##################################################

cd /Herwig/EventHandlers
set EventHandler:LuminosityFunction:Energy 13000*GeV

##################################################
## Process selection
##################################################

## Note that event generation may fail if no matching matrix element has
## been found.  Coupling orders are with respect to the Born process,
## i.e. NLO QCD does not require an additional power of alphas.

## Model assumptions
read Matchbox/StandardModelLike.in
read Matchbox/DiagonalCKM.in

## Set the order of the couplings
cd /Herwig/MatrixElements/Matchbox
set Factory:OrderInAlphaS 0
set Factory:OrderInAlphaEW 2

## Select the process
## You may use identifiers such as p, pbar, j, l, mu+, h0 etc.
do Factory:Process p p -> e+ e-

## Special settings required for on-shell production of unstable particles
## enable for on-shell top production
# read Matchbox/OnShellTopProduction.in
## enable for on-shell W, Z or h production
# read Matchbox/OnShellWProduction.in
# read Matchbox/OnShellZProduction.in
# read Matchbox/OnShellHProduction.in
# Special settings for the VBF approximation
# read Matchbox/VBFDiagramsOnly.in

##################################################
## Matrix element library selection
##################################################

## Select a generic tree/loop combination or a
## specialized NLO package

# read Matchbox/MadGraph-GoSam.in
# read Matchbox/MadGraph-MadGraph.in
# read Matchbox/MadGraph-NJet.in
# read Matchbox/MadGraph-OpenLoops.in
# read Matchbox/HJets.in
# read Matchbox/VBFNLO.in

## Uncomment this to use ggh effective couplings
## currently only supported by MadGraph-GoSam

# read Matchbox/HiggsEffective.in

##################################################
## Cut selection
## See the documentation for more options
##################################################

set /Herwig/Cuts/ChargedLeptonPairMassCut:MinMass 60*GeV
set /Herwig/Cuts/ChargedLeptonPairMassCut:MaxMass 120*GeV

## cuts on additional jets

# read Matchbox/DefaultPPJets.in

# insert JetCuts:JetRegions 0 FirstJet
# insert JetCuts:JetRegions 1 SecondJet
# insert JetCuts:JetRegions 2 ThirdJet
# insert JetCuts:JetRegions 3 FourthJet

##################################################
## Scale choice
## See the documentation for more options
##################################################

cd /Herwig/MatrixElements/Matchbox
set Factory:ScaleChoice /Herwig/MatrixElements/Matchbox/Scales/LeptonPairMassScale

##################################################
## Matching and shower selection
## Please also see flavour scheme settings
## towards the end of the input file.
##################################################

read Matchbox/MCatNLO-DefaultShower.in
# read Matchbox/Powheg-DefaultShower.in
## use for strict LO/NLO comparisons
# read Matchbox/MCatLO-DefaultShower.in
## use for improved LO showering
# read Matchbox/LO-DefaultShower.in

# read Matchbox/MCatNLO-DipoleShower.in
# read Matchbox/Powheg-DipoleShower.in
## use for strict LO/NLO comparisons
# read Matchbox/MCatLO-DipoleShower.in
## use for improved LO showering
# read Matchbox/LO-DipoleShower.in

# read Matchbox/NLO-NoShower.in
# read Matchbox/LO-NoShower.in

##################################################
## Scale uncertainties
##################################################

# read Matchbox/MuDown.in
# read Matchbox/MuUp.in

##################################################
## Shower scale uncertainties
##################################################

# read Matchbox/MuQDown.in
# read Matchbox/MuQUp.in

##################################################
## PDF choice
##################################################

read Matchbox/FiveFlavourScheme.in
## required for dipole shower and fixed order in five flavour scheme
# read Matchbox/FiveFlavourNoBMassScheme.in
read Matchbox/MMHT2014.in

##################################################
## Analyses
##################################################

# cd /Herwig/Analysis
# insert Rivet:Analyses 0 XXX_2015_ABC123
# insert /Herwig/Generators/EventGenerator:AnalysisHandlers 0 Rivet
# insert /Herwig/Generators/EventGenerator:AnalysisHandlers 0 HepMC

##################################################
## Save the generator
##################################################

do /Herwig/MatrixElements/Matchbox/Factory:ProductionMode

cd /Herwig/Generators
saverun LHC-Matchbox EventGenerator

Note: You should never, never ever, edit the Herwig default repository and setup. Maybe look at it, but you should set parameters in your own input file only, like the LHC-Matchbox.in. You will find that only quite obvious paramaters are adjusted here. In fact, every parameter of Herwig, even those who are not meant to be changed could be changed in an .in file.

Often we will now only talk about extra snippets of single input lines or specific snippet files which can be additionally included by the command

read [Snippet file name].in

The first two snippets specify that we using the NLO Matchbox machinary for the matrix element calculations and set up the type of collider. These snippets should always be at the start of the input file., although other snippets can be inserted practically anywhere. You should take care that you cd back to the correct prefix that was needed by the next commands. Moreover, we recommend you to enter your own snippets and changes at the end into a special section of the input file, right before the saverun command.

In fact, rather than using saverun which generates a .run file, so that you have to start the event generation process by the command

[example] $ Herwig run LHC-Matchbox.run -N 100

you could also simply run the generator from the input file with the given number of events (search for it in the LHC-Matchbox.in file). For example in you change saverun to run at the end of the input file, i.e.

run LHC-Matchbox EventGenerator

and then read it

[example] $ Herwig read LHC-Matchbox.in

then all the setup of the event generator and the generation of the events will happen in one go. You can have a chain of runs after only changing few parameters by inserting subsequent sections in the .in file with a concluding run. Likewise you could produce several .run files with multiple saverun commands in one read step, each would differ only by some parameters in the corresponding section. There are , however, better ways to do this.

In the next section we will change some typical parameters of the run in the input file and look at the effect.