5.1. General parameters

The following parameters describe general run information. See Input structure for how to use them in a configuration file or on the command line.

5.1.1. EVENTS

This parameter specifies the number of events to be generated.

It can alternatively be set on the command line through option -e, see Command Line Options.

5.1.2. EVENT_TYPE

This parameter specifies the kind of events to be generated. It can alternatively be set on the command line through option -t, see Command Line Options.

• The default event type is StandardPerturbative, which will generate a hard event through exact matrix elements matched and/or merged with the parton shower, eventually including hadronisation, hadron decays, etc..

Alternatively there are two more specialised modes, namely:

• MinimumBias, which generates minimum bias events through the SHRIMPS model implemented in Sherpa, see Minimum bias events

• HadronDecay, which allows to simulate the decays of a specific hadron.

5.1.3. SHERPA_VERSION

This parameter ties a config file to a specific Sherpa version, e.g. SHERPA_VERSION: 2.2.0. If two parameters are given they are interpreted as a range of Sherpa versions: SHERPA_VERSION: [2.2.0, 2.2.5] specifies that this config file can be used with any Sherpa version between (and including) 2.2.0 and 2.2.5.

5.1.4. TUNE

Warning

This parameter is currently not supported.

5.1.5. OUTPUT

This parameter specifies the screen output level (verbosity) of the program. If you are looking for event file output options please refer to section Event output formats.

It can alternatively be set on the command line through option -O, see Command Line Options. A different output level can be specified for the event generation step through EVT_OUTPUT or command line option -o, see Command Line Options

The value can be any sum of the following:

• 0: Error messages (-> always displayed).

• 1: Event display.

• 2: Informational messages during the run.

• 4: Tracking messages (lots of output).

• 8: Debugging messages (even more output).

E.g. OUTPUT=3 would display information, events and errors. Use OUTPUT_PRECISION to set the default output precision (default 6). Note: this may be overridden in specific functions’ output.

For expert users: The output level can be overridden for individual functions, e.g. like this

FUNCTION_OUTPUT:
  "void SHERPA::Matrix_Element_Handler::BuildProcesses()": 8
  ...

where the function signature is given by the value of __PRETTY_FUNCTION__ in the function block. Another expert parameter is EVT_OUTPUT_START, with which the first event affected by EVT_OUTPUT can be specified. This can be useful to generate debugging output only for events affected by a certain issue.

5.1.6. LOG_FILE

This parameter specifies the log file. If set, the standard output from Sherpa is written to the specified file, but output from child processes is not redirected. This option is particularly useful to produce clean log files when running the code in MPI mode, see MPI parallelization. A file name can alternatively be specified on the command line through option -l, see Command Line Options.

5.1.7. RANDOM_SEED

Sherpa uses different random-number generators. The default is the Ran3 generator described in [PTVF07]. Alternatively, a combination of George Marsaglias KISS and SWB [MZ91] can be employed, see this website. The integer-valued seeds of the generators are specified by RANDOM_SEED: [A, .., D]. They can also be set individually using RANDOM_SEED1: A through RANDOM_SEED4: D. The Ran3 generator takes only one argument (in this case, you can simply use RANDOM_SEED: A). This value can also be set using the command line option -R, see Command Line Options.

5.1.8. EVENT_SEED_MODE

The tag EVENT_SEED_MODE can be used to enforce the same seeds in different runs of the generator. When set to 1, existing random seed files are read and the seed is set to the next available value in the file before each event. When set to 2, seed files are written to disk. These files are gzip compressed, if Sherpa was compiled with option -DSHERPA_ENABLE_GZIP=ON. When set to 3, Sherpa uses an internal bookkeeping mechanism to advance to the next predefined seed. No seed files are written out or read in.

5.1.9. ANALYSIS

Analysis routines can be switched on or off using the ANALYSIS parameter. The default is no analysis. This parameter can also be specified on the command line using option -a, see Command Line Options.

The following analysis handlers are currently available

Internal

Sherpa’s internal analysis handler.

To use this option, the package must be configured with option

-DSHERPA_ENABLE_ANALYSIS=ON. An output directory can

be specified using ANALYSIS_OUTPUT.

Rivet

The Rivet package, see Rivet Website.

To enable it, Rivet and HepMC have to be installed and Sherpa must be configured

as described in Rivet analyses.

Multiple options can also be specified, e.g. ANALYSIS: [Internal, Rivet].

5.1.10. ANALYSIS_OUTPUT

Name of the directory for histogram files when using the internal analysis and name of the Yoda file when using Rivet, see ANALYSIS. The directory/file will be created w.r.t. the working directory. The default value is Analysis/. This parameter can also be specified on the command line using option -A, see Command Line Options.

5.1.11. TIMEOUT

A run time limitation can be given in user CPU seconds through TIMEOUT. This option is of some relevance when running SHERPA on a batch system. Since in many cases jobs are just terminated, this allows to interrupt a run, to store all relevant information and to restart it without any loss. This is particularly useful when carrying out long integrations. Alternatively, setting the TIMEOUT variable to -1, which is the default setting, translates into having no run time limitation at all. The unit is seconds.

5.1.12. RLIMIT_AS

A memory limitation can be given to prevent Sherpa to crash the system it is running on as it continues to build up matrix elements and loads additional libraries at run time. Per default the maximum RAM of the system is determined and set as the memory limit. This can be changed by giving RLIMIT_AS: where the size is given as e.g. 500 MB, 4 GB, or 10 %. When running with MPI parallelization it might be necessary to divide the total maximum by the number of cores. This can be done by setting RLIMIT_BY_CPU: true.

Sherpa checks for memory leaks during integration and event generation. If the allocated memory after start of integration or event generation exceeds the parameter MEMLEAK_WARNING_THRESHOLD, a warning is printed. Like RLIMIT_AS, MEMLEAK_WARNING_THRESHOLD can be set using units. The warning threshold defaults to 16MB.

5.1.13. BATCH_MODE

Whether or not to run Sherpa in batch mode. The default is 1, meaning Sherpa does not attempt to save runtime information when catching a signal or an exception. On the contrary, if option 0 is used, Sherpa will store potential integration information and analysis results, once the run is terminated abnormally. All possible settings are:

0

Sherpa attempts to write out integration and analysis results when catching an exception.

1

Sherpa does not attempt to write out integration and analysis results when catching an exception.

2

Sherpa outputs the event counter continuously, instead of overwriting the previous one (default when using LOG_FILE).

4

Sherpa increases the on-screen event counter in constant steps of 100 instead of an increase relative to the current event number. The interval length can be adjusted with EVENT_DISPLAY_INTERVAL.

8

Sherpa prints the name of the hard process for the last event at each print out.

16

Sherpa prints the elapsed time and time left in seconds only.

The settings are additive such that multiple settings can be employed at the same time.

Note

When running the code on a cluster or in a grid environment, BATCH_MODE should always contain setting 1 (i.e. BATCH_MODE: 1 or 3 or 5 etc.).

The command line option -b should therefore not be used in this case, see Command Line Options.

5.1.14. INIT_ONLY

This can be used to skip cross section integration and event generation phases. Note that these phases are always skipped if Sherpa detects that libraries are missing and need to be compiled first, see Running Sherpa. The following values can be used for INIT_ONLY:

0

The default. Sherpa will normally attempt to proceed after initialisation to integrate cross sections (or read in cached results) and generate events.

1

Sherpa will always exit after initialisation, skipping integration and event generation.

2

Sherpa skips cross section integration. This is useful when Sherpa is used to calculate specific matrix element values, see Calculating matrix element values for externally given configurations.

5.1.15. NUM_ACCURACY

The targeted numerical accuracy can be specified through NUM_ACCURACY, e.g. for comparing two numbers. This might have to be reduced if gauge tests fail for numerical reasons. The default is 1E-10.

5.1.16. SHERPA_CPP_PATH

The path in which Sherpa will eventually store dynamically created C++ source code. If not specified otherwise, sets SHERPA_LIB_PATH to $SHERPA_CPP_PATH/Process/lib. This value can also be set using the command line option -L, see Command Line Options. Both settings can also be set using environment variables.

5.1.17. SHERPA_LIB_PATH

The path in which Sherpa looks for dynamically linked libraries from previously created C++ source code, cf. SHERPA_CPP_PATH.

5.1.18. Event output formats

Sherpa provides the possibility to output events in various formats, e.g. the HepMC format. The authors of Sherpa assume that the user is sufficiently acquainted with these formats when selecting them.

If the events are to be written to file, the parameter EVENT_OUTPUT must be specified together with a file name. An example would be EVENT_OUTPUT: HepMC3[MyFile], where MyFile stands for the desired file base name. More than one output can also be specified:

EVENT_OUTPUT:
  - HepMC3[MyFile]
  - Root[MyFile]

The following formats are currently available:

HepMC3

Generates output using HepMC3 library. The format of the output is controlled with the HEPMC3_IO_TYPE setting. The default value is 0 and corresponds to ASCII GenEvent output. Other available options are: 1 (HepEvt output), 2 (HepMC2 ASCII output), 3 (ROOT file output with every event written as an object of class GenEvent), and 4 (ROOT file output with GenEvent objects written into TTree).

The HepMC::GenEvent::m_weights weight vector stores the following items: [0] event weight, [1] combined matrix element and PDF weight (missing only phase space weight information, thus directly suitable for evaluating the matrix element value of the given configuration), [2] event weight normalisation (in case of unweighted events event weights of ~ +/-1 can be obtained by (event weight)/(event weight normalisation)), and [3] number of trials. The total cross section of the simulated event sample can be computed as the sum of event weights divided by the sum of the number of trials. This value must agree with the total cross section quoted by Sherpa at the end of the event generation run, and it can serve as a cross-check on the consistency of the HepMC event file. Note that Sherpa conforms to the Les Houches 2013 suggestion (http://phystev.in2p3.fr/wiki/2013:groups:tools:hepmc) of indicating interaction types through the GenVertex type-flag. Multiple event weights can also be used, cf. On-the-fly event weight variations. The following additional customisations can be used.

HEPMC_USE_NAMED_WEIGHTS: <true|false> Enable filling weights with an associated name. The nominal event weight has the key Weight. MEWeight, WeightNormalisation and NTrials provide additional information for each event as described above. The default value is true.

HEPMC_EXTENDED_WEIGHTS: <false|true> Write additional event weight information needed for a posteriori reweighting into the WeightContainer, cf. A posteriori scale and PDF variations using the HepMC GenEvent Output. Necessitates the use of HEPMC_USE_NAMED_WEIGHTS. The default value is false.

HEPMC3_SHORT: <false|true> Generates output in HepMC::IO_GenEvent format, however, only incoming beams and outgoing particles are stored. Intermediate and decayed particles are not listed. The default value is false.

HEPMC_TREE_LIKE: <false|true> Force the event record to be strictly tree-like. Please note that this removes some information from the matrix-element-parton-shower interplay which would be otherwise stored. The default value is false. Has no effect if HEPMC3_SHORT is used.

Requires -DHepMC3_DIR=/path/to/hepmc3 (or -DSHERPA_ENABLE_HEPMC3=ON, if HepMC3 is installed in a standard location).

LHEF

Generates output in Les Houches Event File format. This output format is intended for output of matrix element configurations only. Since the format requires PDF information to be written out in the outdated PDFLIB/LHAGLUE enumeration format this is only available automatically if LHAPDF is used, the identification numbers otherwise have to be given explicitly via LHEF_PDF_NUMBER (LHEF_PDF_NUMBER_1 and LHEF_PDF_NUMBER_2 if both beams carry different structure functions). This format currently outputs matrix element information only, no information about the large-Nc colour flow is given as the LHEF output format is not suited to communicate enough information for meaningful parton showering on top of multiparton final states.

Root

Generates output in ROOT ntuple format for NLO event generation only. For details on the ntuple format, see A posteriori scale and PDF variations using the ROOT NTuple Output. ROOT ntuples can be read back into Sherpa and analyzed using the option EVENT_INPUT. This feature is described in Production of NTuples.

Requires -DROOT_DIR=/path/to/root (or -DSHERPA_ENABLE_ROOT=ON, if ROOT is installed in a standard location).

The output can be further customized using the following options:

FILE_SIZE

Number of events per file (default: unlimited).

EVENT_FILE_PATH

Directory where the files will be stored.

EVENT_OUTPUT_PRECISION

Steers the precision of all numbers written to file (default: 12).

For all output formats except ROOT, events can be written directly to gzipped files instead of plain text. The option -DSHERPA_ENABLE_GZIP=ON must be given during installation to enable this feature.

5.1.19. On-the-fly event weight variations

Sherpa can compute alternative event weights on-the-fly [BSS16], resulting in alternative weights for the generated event. An important example is the variation of QCD scales and input PDF. There are also on-the-fly variations for approximate electroweak corrections, this is discussed in its own section, Approximate Electroweak Corrections.

5.1.19.1. Specifying variations

There are two ways to specify scale and PDF variations. Either using the unified VARIATIONS list, and/or by using the specialised SCALE_VARIATIONS and PDF_VARIATIONS, and QCUT_VARIATIONS lists. Only the VARIATIONS list allows to specify correlated variations (i.e. varying both scales and PDFs at the same time), but it is more verbose and therefore harder to remember. Therefore, we suggest to use the more specialised variants whenever uncorrelated variations are required.

They are evoked using the following syntax:

SCALE_VARIATIONS:
- [<muF2-fac-1>, <muR2-fac-1>]
- [<muF2-fac-2>, <muR2-fac-2>]
- <mu2-fac-3>

PDF_VARIATIONS:
- <PDF-1>
- <PDF-2>

QCUT_VARIATIONS:
- <qcut-fac-1>
- <qcut-fac-2>

This example specifies a total of seven on-the-fly variations.

Scale factors in SCALE_VARIATIONS can be given as a list of two numbers, or as a single number. When two numbers are given, they are applied to the factorisation and the renormalisation scale, respectively. If only a single number is given, it is applied to both scales at the same time. The factors for the renormalisation and factorisation scales must be given in their quadratic form, i.e. a “4.0” in the settings means that the (unsquared) scale is to be multiplied by a factor of 2.0.

For the PDF_VARIATIONS, any set present in any of the PDF library interfaces loaded through PDF_LIBRARY can be used. If no PDF set is given it defaults to the nominal one. Specific PDF members can be specified by appending the PDF set name with /<member-id>.

It can be painful to write every variation explicitly, e.g. for 7-point scale factor variations or if one wants variations for all members of a PDF set. Therefore an asterisk can be appended to some values, which results in an expansion. For PDF sets, this means that the variation is repeated for each member of that set. For scale factors, 4.0* is expanded to itself, unity, and its inverse: 1.0/4.0, 1.0, 4.0. A special meaning is reserved for specifying a single number 4.0* as a SCALE_VARIATIONS list item, which expands to a 7-point scale variation:

SCALE_VARIATIONS:
- 4.0*

is therefore equivalent to

SCALE_VARIATIONS:
- [0.25, 0.25]
- [0.25, 1.00]
- [1.00, 0.25]
- [1.00, 1.00]
- [4.00, 1.00]
- [1.00, 4.00]
- [4.00, 4.00]

Equivalently, one can even just write SCALE_VARIATIONS: 4.0*, because a single scalar on the right-hand side will automatically be interpreted as the first item of a list when the setting expects a list.

Such expansions may include trivial scale variations and the central PDF set, resulting in the specification of a completely trivial variation, which would just repeat the nominal calculation. Per default, these trivial variations are automatically omitted during the calculation, since the nominal calculation is anyway included in the Sherpa output. If required (e.g. for debugging), this filtering can be explicitly disabled using VARIATIONS_INCLUDE_CV: true.

We now discuss the alternative VARIATIONS syntax. The following snippet specifies two on-the-fly variations, where scales and PDFs are varied simultaneously:

VARIATIONS:
- ScaleFactors:
    MuR2: <muR2-fac-1>
    MuF2: <muF2-fac-1>
    QCUT: <qcut-fac-1>
  PDF: <PDF-1>
- ScaleFactors:
    MuR2: <muR2-fac-2>
    MuF2: <muF2-fac-2>
    QCUT: <qcut-fac-2>
  PDF: <PDF-2>
...

The key word VARIATIONS takes a list of variations. Each variation is specified by a set of scale factors, and a PDF choice (or AlphaS(MZ) choice, see below).

Scale factors can be given for the renormalisation, factorisation and for the merging scale. The corresponding keys are MuR2, MuF2 and QCUT, respectively. The factors for the renormalisation and factorisation scales must be given in their quadratic form, i.e. a MUR2: 4.0 means that the (unsquared) renormalisation scale is to be multiplied by a factor of 2.0. All scale factors can be omitted (they default to 1.0). Instead of MuR2 and MuF2, one can also use the keyword Mu2. In this case, the given factor is applied to both the renormalisation and the factorisation scale.

Instead of using PDF: <PDF> (which consistently also varies the strong coupling if the PDF has a different specification of it!), one can also specify a pure AlphaS variation by giving its value at the Z mass scale: AlphaS(MZ): <alphas(mz)-value>. This can be useful e.g. for leptonic productions, and is currently exclusive to the VARIATIONS syntax.

Also VARIATIONS can expand values using the star syntax:

VARIATIONS:
  - ScaleFactors:
      Mu2: 4.0*

is therefore equivalent to

VARIATIONS:
  - ScaleFactors:
      MuF2: 0.25
      MuR2: 0.25
  - ScaleFactors:
      MuF2: 1.0
      MuR2: 0.25
  - ScaleFactors:
      MuF2: 0.25
      MuR2: 1.0
  - ScaleFactors:
      MuF2: 1.0
      MuR2: 1.0
  - ScaleFactors:
      MuF2: 4.0
      MuR2: 1.0
  - ScaleFactors:
      MuF2: 1.0
      MuR2: 4.0
  - ScaleFactors:
      MuF2: 4.0
      MuR2: 4.0

As another example, a complete variation using the PDF4LHC convention would read

VARIATIONS:
  - ScaleFactors:
      Mu2: 4.0*
  - PDF: CT10nlo*
  - PDF: MMHT2014nlo68cl*
  - PDF: NNPDF30_nlo_as_0118*

Please note, this syntax will create \(6+52+50+100=208\) additional weights for each event. Even though reweighting is used to reduce the amount of additional calculation as far as possible, this can still necessitate a considerable amount of additional CPU hours, in particular when parton-shower reweighting is enabled (see below).

The rest of this section applies to both the combined VARIATIONS and the individual SCALE_VARIATIONS etc. syntaxes.

5.1.19.2. Variation output

The total cross section for all variations along with the nominal cross section are written to the standard output after the event generation has finalized. Additionally, some event output (see Event output formats) and analysis methods (see ANALYSIS) are able to process alternate event weights. Currently, the only supported event output method is HepMC3 (requires configuration with HepMC version 3 or later). The supported analysis methods are Rivet and Internal.

The alternative event weight names follow the MC naming convention, i.e. they are named MUR=<fac>__MUF=<fac>__LHAPDF=<id>. When using Sherpa’s interface to Rivet, Rivet analyses, the internal multi-weight handling capabilities are used, such that there is only one histogram file containing histograms all variations. Extending the naming convention, for pure strong coupling variations, an additional tag ASMZ=<val> is appended. If shower scale variations are disabled (either implicitly, because SHOWER_GENERATOR: None, or explicitly, see below), you will find ME.MUR/ME.MUF tags instead of the simple ones to make explicit that the parton-shower scales are not varied with the ME scales.

If parton-shower variations are enabled, SHOWER:REWEIGHT: true (the default if parton showering is enabled), then pure ME-only variations are included along with the full variations in the HepMC/Rivet output by default. This can be disabled using OUTPUT_ME_ONLY_VARIATIONS: false. All weight names of ME-only variations include a “ME” as part of the keys to indicate that only the ME part of the calculation has been varied, e.g. ME:MUR=<fac>__ME:MUF=<fac>__ME:LHAPDF=<id>.

The user must also be aware that, of course, the cross section of the event sample, changes when using an alternative event weight as compared to the nominal one. Any histogramming therefore has to account for this and recompute the total cross section as the sum of weights divided by the number of trials, cf. Cross section determination. For HepMC 3, Sherpa writes alternate cross sections directly to the GenCrossSection entry of the event record, such that no manual intervention is required (as long as the correct cross section variation is picked in downstream processing steps).

5.1.19.3. Varying the PDFs of a single beam

The PDF_VARIATION_BEAMS setting can be used to restrict for which beams a PDF variation is applied. Its default is [1, 2], i.e. both beams will undergo a given PDF variation. Use 1 or 2 to only apply it to a single beam. This is a global setting for all PDF variations, i.e. it is currently not possible to do this on the basis of a single PDF variation.

When using PDF_VARIATION_BEAMS, there is an ambiguity which beam’s PDF should be used to evaluate the strong coupling. For that, the setting PDF_VARIATION_ALPHAS_BEAM can be used. Its default is 0, which means that the first available beam’s PDF is used. Use 1 or 2 to select a specific beam’s PDF instead.

Having different PDFs for each beam will be reflected in the Variation output. Consider the following example: MUR=1__MUF=1__LHAPDF.BEAM1=93300__LHAPDF.BEAM2=93301, where the beams’ LHAPDF IDs are specified individually.

5.1.19.4. Variations for different event generation modes

The on-the-fly reweighting works for all event generation modes (weighted or (partially) unweighted) and all calculation types (LO, LOPS, NLO, NLOPS, NNLO, NNLOPS, MEPS@LO, MEPS@NLO and MENLOPS).

5.1.19.4.1. NLO calculations

For NLO calculations, note that some loop providers (e.g. Recola) do not provide the pole coefficients, while others do (e.g. OpenLoops). For the former, Sherpa will automatically exclude the IR pole coefficients from the scale variation. One can also manually exclude them using NLO_MUR_COEFFICIENT_FROM_VIRTUAL: false. If they are excluded, then IR pole cancellation is assumed and, thus, only the UV renormalisation term pole coefficient is considered in the scale variation.

5.1.19.4.2. Parton shower emissions

By default, the reweighting of parton shower emissions is included in the variations. It can be disabled explicitly, using SHOWER:REWEIGHT: false. This should work out of the box for all types of variations. However, parton-shower reweighting (even though formally exact), tends to be numerically less stable than the reweighting of the hard process. If numerical issues are encountered, one can try to increase SHOWER:REWEIGHT_SCALE_CUTOFF (default: 5, measured in GeV). This disables shower variations for emissions at scales below the value. An additional safeguard against rare spuriously large shower variation weights is implemented as SHOWER:MAX_REWEIGHT_FACTOR (default: 1e3). Any variation weights accumulated during an event and larger than this factor will be ignored and reset to 1.

5.1.20. MPI parallelization

MPI parallelization in Sherpa can be enabled using the configuration option -DSHERPA_ENABLE_MPI=ON. Sherpa supports OpenMPI and MPICH2 . For detailed instructions on how to run a parallel program, please refer to the documentation of your local cluster resources or the many excellent introductions on the internet. MPI parallelization is mainly intended to speed up the integration process, as event generation can be parallelized trivially by starting multiple instances of Sherpa with different random seed, cf. RANDOM_SEED. However, both the internal analysis module and the Root NTuple writeout can be used with MPI. Note that these require substantial data transfer.

Please note that the process information contained in the Process directory for both Amegic and Comix needs to be generated without MPI parallelization first. Therefore, first run

$ Sherpa INIT_ONLY=1 <Sherpa.yaml>

and, in case of using Amegic, compile the libraries. Then start your parallelized integration, e.g.

$ mpirun -n <n> Sherpa -e 0 <Sherpa.yaml>

After the integration has finished, you can submit individual jobs to generate event samples (with a different random seed for each job). Upon completion, the results can be merged.