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 LHCGenerator

How is this LHCGenerator set up? In fact, many, many objects are put together to finally build this LHCGenerator. 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 LHCGenerator in HerwigDefaults.in. The first line you find says

create ThePEG::EventGenerator LHCGenerator

In fact, now one instance of an object ThePEG::EventGenerator is created and given the name LHCGenerator 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 LHCGenerator 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/LHCGenerator

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

cd /Herwig/Generators
create ThePEG::EventGenerator LHCGenerator

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 LHCGenerator:EventHandler /Herwig/EventHandlers/LHCHandler

newdef simply means that here we have a new, or first, definition of a parameter. We set the parameter EventHandler of the object LHCGenerator, addressed as LHCGenerator:EventHandler to the value /Herwig/EventHandlers/LHCHandler. So, the parameter EventHandler has to be an object of the type EventHandler. The LHCHandler 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 LHCHandler is the object that handles a single hadron collider event, as you could have guessed.

Now, you can look at how the LHCHandler, 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 FixedLHCLuminosity: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 FixedLHCLuminosity:Energy 13000.0*GeV

or

set /Herwig/EventHandlers/FixedLHCLuminosity: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 LHCHandler:SubProcessHandlers[0] /Herwig/MatrixElements/SimpleQCD

Here, the actual parameter to set is a vector. So the object Herwig/MatrixElements/SimpleQCD is inserted into the vector of SubProcessHandlers of the LHCHandler. 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 Matchbox/PPCollider.in

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

cd /Herwig/EventHandlers
set EventHandler:LuminosityFunction:Energy 8000*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.

## 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-

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

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

read Matchbox/MadGraph-OpenLoops.in

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

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

##################################################
## 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

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

read Matchbox/FiveFlavourScheme.in
read Matchbox/MMHT2014.in

##################################################
## 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

Even though the snippets can be inserted practically anywhere, just take good 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.