4. Input structure

A Sherpa setup is steered by various parameters, associated with the different components of event generation.

These have to be specified in a configuration file which by default is named Sherpa.yaml in the current working directory. If you want to use a different setup directory for your Sherpa run, you have to specify it on the command line as -p <dir> or 'PATH: <dir>' (including the quotes).

To read parameters from a configuration file with a different name, you may give the file name as a positional argument on the command line like this: Sherpa <file>. Note that you can also pass more than one file like this: Sherpa <file1> <file2> ... In this case, settings in files to the right take precedence. This can be useful to reduce duplication in the case that you have several setups that share a common set of settings.

Note that you can also pass filenames using the legacy syntax -f <file> or 'RUNDATA: [<file1>, <file2>]'. However, this is deprecated. Use positional arguments instead. Mixing this legacy syntax and positional arguments for specifying configuration files is undefined behaviour.

Sherpa’s configuration files are written in the YAML format. Most settings are just written as the settings’ name followed by its value, like this:

BEAMS: 2212

In other words, they are key-value pairs of the top-level mapping. For some settings, the value is itself a mapping. Hence, we get a nested structure, for example:

  Enabled: true
  Apply_Branching_Ratios: false

where Enabled and Apply_Branching_Ratios are sub-settings of the top-level HARD_DECAYS setting. The hierarchy is denoted by indentation here. In YAML, this is called block style and relies on proper formatting (i.e. each element must be on a separate line, and indentation must be consistent). Alternatively, one can use flow style, using indicators such as braces instead of whitespace to indicate structure. For the previous example, the inner mapping can be written with curly braces and commas:

HARD_DECAYS: { Enabled: true, Apply_Branching_Ratios: false }

Other settings are sequences of elements. An example would be a sequence of two scale variations:

- 0.25
- 4.00

In block style, each sequential items is prepended with a single dash. Equivalently, the snippet can be rewritten in flow style using square brackets (line breaks are completely optional then, and are omitted here):

SCALE_VARIATIONS: [0.25, 4.00]

Each SCALE_VARIATIONS item can itself be a sequence (to specify different variations for the factorisation and renormalisation scale). Block and flow style can be freely mixed in the different levels:

- 0.25
- [0.25, 1.00]
- [1.00, 0.25]

The different settings and their structure are described in detail in another chapter of this manual, see Parameters.

All parameters can be overwritten on the command line, i.e. command-line input has the highest priority. Each argument is parsed as a single YAML line. This usually means that you have to quote each argument:

$ <prefix>/bin/Sherpa 'KEYWORD1: value1' 'KEYWORD2: value2' ...

Because each argument is parsed as YAML, you can also specify nested settings, e.g. to disable hard decays (even if it is enabled in the config file) you can write:

$ <prefix>/bin/Sherpa 'HARD_DECAYS: {Enabled: false}'

Or you can specify the list of matrix-element generators writing:

$ <prefix>/bin/Sherpa 'ME_GENERATORS: [Comix, Amegic]'

Note that we have used flow style here, because block style would require line breaks, which are difficult to deal with on the command line.

All over Sherpa, particles are defined by the particle code proposed by the PDG. These codes and the particle properties will be listed during each run with OUTPUT: 2 for the elementary particles and OUTPUT: 4 for the hadrons. In both cases, antiparticles are characterized by a minus sign in front of their code, e.g. a mu- has code 13, while a mu+ has -13.

All quantities have to be specified in units of GeV and millimeter. The same units apply to all numbers in the event output (momenta, vertex positions). Scattering cross sections are denoted in pico-barn in the output.

There are a few extra features for an easier handling of the parameter file(s), namely global tag replacement, see Tags, and algebra interpretation, see Interpreter.

4.1. Interpreter

Sherpa has a built-in interpreter for algebraic expressions, like cos(5/180*M_PI). This interpreter is employed when reading integer and floating point numbers from input files, such that certain parameters can be written in a more convenient fashion. For example it is possible to specify the factorisation scale as sqr(91.188).

There are predefined tags to alleviate the handling


Ludolph’s Number to a precision of 12 digits.


The speed of light in the vacuum.


The total centre of mass energy of the collision.

The expression syntax is in general C-like, except for the extra function sqr, which gives the square of its argument. Operator precedence is the same as in C. The interpreter can handle functions with an arbitrary list of parameters, such as min and max.

The interpreter can be employed to construct arbitrary variables from four momenta, like e.g. in the context of a parton level selector, see Selectors. The corresponding functions are


The invariant mass of v in GeV.


The invariant mass squared of v in GeV^2.


The transverse momentum of v in GeV.


The transverse momentum squared of v in GeV^2.


The transverse mass of v in GeV.


The transverse mass squared of v in GeV^2.


The polar angle of v in radians.


The pseudorapidity of v.


The rapidity of v.


The azimuthal angle of v in radians.

Comp(v,i) The i’th component of the vector

v. i = 0 is the energy/time component, i = 1, 2, and 3 are the x, y, and z components.


The relative transverse momentum between v1 and v2 in GeV.


The relative angle between v1 and v2 in radians.


The pseudo-rapidity difference between v1 and v2.


The rapidity difference between v1 and v2.


The relative polar angle between v1 and v2 in radians.

4.2. Tags

Tag replacement in Sherpa is performed through the data reading routines, which means that it can be performed for virtually all inputs. Specifying a tag on the command line or in the configuration file using the syntax TAGS: {<Tag>: <Value>} will replace every occurrence of $(<Tag>) in all files during read-in. An example tag definition could read

$ <prefix>/bin/Sherpa 'TAGS: {QCUT: 20, NJET: 3}'

and then be used in the configuration file like:

- 93 93 -> 11 -11 93{$(NJET)}:
    Order: {QCD: 0, EW: 2}
    CKKW: $(QCUT)