The first run

Make yourself comfortable

During your Herwig installation you have chosen a specific path, that we refer to as <HERWIGPATH>. This is the same path that you choose during the configuration step of the installation as either ./configure --prefix=<HERWIGPATH> [--more-options] or ./herwig-bootstrap [--other-options] <HERWIGPATH>. If you have installed Herwig using the bootstrap script you can set all the required paths by sourcing the activate script supplied

source <HERWIGPATH>/bin/activate

as described in the message produced at the end of the bootstrap process. These variables can then be unset using


Alternatively if you wish to set the paths manually

Check whether or not your program can be executed with either

[example] $ Herwig


[example] $ ./Herwig

This will give you a simple message about the possible run modes of Herwig if it is installed properly:

Usage: Herwig (read|build|integrate|run) [OPTIONS]... [FILE]

Also try

[example] $ Herwig --help

to see further options. We will go through the different options below.

First events

In order to run Herwig you need an input file. Many example input files are provided in <HERWIGPATH>/share/Herwig/ with the suffix .in. Many input files are examples of leading-order simulations of specific processes for which matrix elements are provided with Herwig and some give a typical setup for the leading-order simulation at a specific collider.

As an example we study the Drell-Yan process at next-to-leading order (NLO). Copy the file into your working directory.

[example] $ cp <HERWIGPATH>/share/Herwig/ .

Let’s read it

[example] $ Herwig read

You see some output about the progress of the creation of subprocesses, preparation of matrix elements and finally the phase-space integration. The phase-space integration may take some time. Don’t be too impatient here, as a thorough exploration of the phase space in the integration step will lead to a better efficiency of the Monte Carlo sampling later.

If you check the output you find the newly created run-file in your working directory that contains all details of the event generator you have just set up. The subdirectory Herwig-scratch contains further output of the setup process.

We can now generate events with

[example] $ Herwig run -N 100

The option -N 100 defines that you are going to generate 100 events. After a short initialization you will see some output with an event counter. By default you will also see output from an analysis handler BasicConsistency that reports about the worst violation of momentum conservation. Normally this will be fractions of MeV which is only a result of some numerical inaccuracies in the simulation. Much larger violations should be alarming!

Note! to get started you might as well switch to LO matrix elements in This can be done a bit further down in the input file. Comment out the line

# read Matchbox/

and uncomment the following line

read Matchbox/

in order to switch off the real and virtual parts of the NLO calculation.

Both read and run will be finished much faster and for the following observations of output this is absolutely sufficient.

Both the read and the run step should be finished within several minutes. That’s it! You just generated a full simulation of Drell-Yan plus jets at NLO for the LHC.

The Herwig executable is designed so that if it receives the Ctrl-C signal then it will first finish the event it is generating, then do any final calculations, for example the output of histograms with Rivet, and only then stop. This can be useful if you have specified too many events and get bored waiting so you can still get any output.

In the next sections we will go further and learn how to adapt Herwig to various kinds of circumstances.

A first look at the output

Have a look at the output in three more files LHC-Matchbox.*. LHC-Matchbox.tex contains suggestions for references that should be cited if you plan to publish a paper with Herwig results. LHC-Matchbox.out contains some statistics and cross section information about individual subprocesses.

Detailed information about the simulation can be found in the log-file LHC-Matchbox.log. Increase the verbosity of the output with -d 1.

[example] $ Herwig run -N 100 -d 1

After a list of all active cuts you find detailed information about single events. Every event is organized in so-called Steps. Every step contains information about incoming, outgoing and intermediate particles. A single particle line could look similar to this

16         g      21 [15] (18,19)   {+4,-5}
                               -0.025    -1.181   -50.203    50.211    -0.798

All particles are numbered as they appear in the event. The gluon g in this example has number 16. 21 [15] (18,19) tell you the MC-ID of the particle, 21 in this case, which is a gluon, our gluon has been created with parent particle [15] and has children (18,19). You can check some parent child relationships in your log-file at this point. {+4,-5} indicate that the gluon belongs to colour line 4 and anti-colour line 5.

See whether you can find any colour partners of our gluon. The second line contains the four-momentum in the form px py pz E Q. Q is the signed invariant mass. In our case the gluon has space-like virtuality.

You can repeat the event generation and will find that you generate the exact same sequence of events. This is because the random number generator is always initialized in the same way. The command line option -s sets a different seed of the random number generator.

[example] $ Herwig run -N 100 -d 1 -s 314159

will produce a further statistically independent set of events.

Also try event generation with different input files and look at the output.