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:
EVENTS: 100M
BEAMS: 2212
BEAM_ENERGIES: 7000
...
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:
HARD_DECAYS:
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:
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:
SCALE_VARIATIONS:
- 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
M_PILudolph’s Number to a precision of 12 digits.
M_CThe speed of light in the vacuum.
E_CMSThe 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
Mass(v)The invariant mass of
vin GeV.Abs2(v)The invariant mass squared of
vin GeV^2.PPerp(v)The transverse momentum of
vin GeV.PPerp2(v)The transverse momentum squared of
vin GeV^2.MPerp(v)The transverse mass of
vin GeV.MPerp2(v)The transverse mass squared of
vin GeV^2.Theta(v)The polar angle of
vin radians.Eta(v)The pseudorapidity of
v.Y(v)The rapidity of
v.Phi(v)The azimuthal angle of
vin radians.Comp(v,i)Thei’th component of the vectorv.i= 0 is the energy/time component,i= 1, 2, and 3 are the x, y, and z components.PPerpR(v1,v2)The relative transverse momentum between
v1andv2in GeV.ThetaR(v1,v2)The relative angle between
v1andv2in radians.DEta(v1,v2)The pseudo-rapidity difference between
v1andv2.DY(v1,v2)The rapidity difference between
v1andv2.DPhi(v1,v2)The relative polar angle between
v1andv2in radians.
