# Event generation workflow¶

Event generation within Herwig is generically separated into a phase of building an event generator object starting from an input file, a warm-up phase (or grid adaption) of the hard subprocess integrator and the actual event generation step. In previous Herwig releases, the first steps could not be separated and have been referred to as the read step, while the last phase is called the run step. With the new capabilities of Herwig to handle more complicated processes at leading or next-to-leading order, we have made these steps more flexible, providing parallelization as far as possible for an efficient workflow. Please note that functionality beyond the standard event generation is applicable only when using the GeneralSampler integration framework, which is the default for all *-Matchbox.in input files.

## Standard event generation¶

Standard event generation proceeds through the read and run steps as for previous versions of Herwig:

Herwig read LHC-Matchbox.in
Herwig run LHC-Matchbox.run


## Separating build and integration¶

Especially in the presence of external amplitude libraries to be compiled, as well as for processes with a large number of jets at NLO, building the event generator object can be time consuming. In order to prevent excessive build steps, when only parameters need to be changed, or, when a parallel integration of the hard subprocesses is desirable, Herwig 7.0 allows to separate the read step into a build step dedicated to setting up the event generator, and an integrate step, which can both be parallelized and allows for changing parameters of the event generation such as scale choices, generation cuts etc. Similar to the read step, the build steps expect an input file to be read, e.g.:

Herwig build LHC-Matchbox.in


After this, a .run file has been created, but subprocess integration has been postponed to the next step, which can then be run via:

Herwig integrate LHC-Matchbox.run


Notice that this step is expecting a ready .run file. After this step, event generation proceeds through the run command as discussed above. We will introduce changing parameters and parallel integration as the main motivation for this separation below.

## Modifying event generators¶

Parameters for event generators which have been prepared in a build step can be modified in the integrate and run steps by passing additional input file statements, contained in a so-called setup file, to Herwig:

Herwig build LHC-Matchbox.in
Herwig integrate --setupfile=parameters.in LHC-Matchbox.run
Herwig run --setupfile=parameters.in LHC-Matchbox.run


Here, parameters.in is an input file containing the desired parameter changes with respect to those made in the input file from which the event generator has been build. If the parameter changes contained in the setup file will not affect the hard subprocess (e.g. changing hadronization parameters), or are expected to not change hard cross sections dramatically, then passing the --setupfile argument to the run command is sufficient.

## Parallel subprocess integration¶

For simulations involving a large number of subprocesses, the integrate step can be parallelized to provide n integration jobs which can readily be executed in parallel:

Herwig build --maxjobs=n LHC-Matchbox.in


will instruct Herwig to build the event generator from the given input file and postpone integrator initialization, distributed to n integration jobs which can be executed as:

Herwig integrate --jobid=k LHC-Matchbox.run


where k ranges, from 0 to n-1.

In bash we can then integrate all them using

for k in {0..n-1}; do (./Herwig integrate --jobid=\$k LHC-Matchbox.run &); done


Herwig is then able to generate events using the run command, as before. Note that if a --setupfile argument has been passed to the integrate command, then the same argument has to be provided to when running in order to determine the right subgrids to be merged. See Higgs Production in Vector Boson Fusion using VBFNLO for a concrete example how to use parallel subprocess integration.

## Merging grid files¶

When the subprocess integration has been split into several jobs, their results have to be merged before event generation. This is done automatically the first time the run step is executed, so in general no special user action is needed. When submitting several run-step jobs in parallel, it can be useful to perform the grid merging manually beforehand. This is done by running

Herwig mergegrids LHC-Matchbox.run


Again, if a --setupfile argument has been passed to the integrate command, it also needs to be included in the command line above so that the correct subgrids are merged.

## Parallel event generation¶

Parallel event generation can be performed by using a number of jobs with different random seeds,:

Herwig run --seed=426738 LHC-Matchbox.run


and the statistically independent results from these different runs can then be combined. In the Contrib directory, we provide two collections of helper scripts for easing parallel event generation and parameter variations. On top of this straightforward parallelization, Herwig also has the option of forking event generation jobs on the same machine:

Herwig run --jobs=10 LHC-Matchbox.run


will fork ten event generation jobs with different seeds.