Introduction

In order to compute the systematics error, one need to recompute the cross-section/differential cross-section for various PDF and scale choice. Running all those computation is parallel is a waste of time and a more appropriate method is to use re-weighting approach to re-use the same sample generated to estimate those systematics. For full efficiency, it requires to store some additional information in the lhe file at the time of the generation such that the computation of those systematics can take a very small amount of time.

For more information concerning the implementation in our framework (such method exists in all MC code), please read: [[​https://arxiv.org/pdf/1110.4738.pdf R. Frederix, S. Frixione, V. Hirschi, F. Maltoni, R. Pit- tau, P. Torrielli, JHEP 02, 099 (2012).]]

LO

At LO, you have two code able to compute the systematics: SysCalc and the "systematics" module of MG5aMC. They have basically the same feature but use different interface approach to perform the computation

1. SysCalc is a standalone C++ code. (not recomanded anymore)
2. "systematics" is a python module which need to have lhapdf6 compiled for python support. Requiring the Python development headers to be installed (e.g. via the python-dev Ubuntu package).

None of the those code is able to handle correctly cases with interference only generation.

How to run the code

To use either of those code, you need first to set in the run_card the parameter

   True = use_syst

which is going to ask MG5aMC to add the additional information in the lhef such that those module can read the information and add the weights in the event file. At leading order this is actually the default behavior (but for case which are not supported).

With that line, the code will automatically run SysCalc. if that code is not installed/link to madgraph then we will automatically run the "systematics" module. You can change this behavior via the (hidden) parameter of the run_card systematics_program you give it one of the three following value:

1. none: no program will be used (but the event will still have the additional information written inside the file)
2. syscalc: use the syscalc program
3. systematics: use the systematics program [even if SysCalc is installed]

Note that both program can also be runned in standalone

Various parameter of the run_card allow you to control which type of variation you want to perform:

0.5 1 2 = sys_scalefact  # factorization/renormalization scale factor
None = sys_alpsfact  # \alpha_s emission scale factors
auto = sys_matchscale # variation of merging scale
# PDF sets and number of members (0 or none for all members).
NNPDF23_lo_as_0130_qed = sys_pdf # separate by && if more than one set.
# MSTW2008nlo68cl.LHgrid 1  = sys_pdf
#

SysCalc

Description of SysCalc is available here: https://cp3.irmp.ucl.ac.be/projects/madgraph/wiki/SysCalc For all question related to SysCalc please contact Alexis Kalogeropoulos.

Systematics (python) module

The "systematics" module can be called externally. It is callable via the Madevent interface (either accessible via launch -i from the MG5aMC interface or via ./bin/madevent) Here is the details on the syntax (as given by the help command)

INFO: syntax: systematics RUN_NAME [OUTPUT] [options]
INFO: -- Run the systematics run on the RUN_NAME run.
INFO:    RUN_NAME can be a path to a lhef file.
INFO:    OUTPUT can be the path to the output lhe file, otherwise the input file will be overwritten
INFO:
INFO: options: (values written are the default)
INFO:
INFO:    --mur=0.5,1,2     # specify the values for renormalisation scale variation
INFO:    --muf=0.5,1,2     # specify the values for factorisation scale variation
INFO:    --alps=1          # specify the values for MLM emission scale variation (LO only)
INFO:    --dyn=-1,1,2,3,4  # specify the dynamical schemes to use.
INFO:                      #   -1 is the one used by the sample.
INFO:                      #   > 0 correspond to options of dynamical_scale_choice of the run_card.
INFO:    --pdf=errorset    # specify the pdfs to use for pdf variation. (see below)
INFO:    --together=mur,muf,dyn # lists the parameter that must be varied simultaneously so as to
INFO:                           # compute the weights for all combinations of their variations.
INFO:    --from_card       # use the information from the run_card (LO only).
INFO:    --remove_weights= # remove previously written weights matching the descriptions
INFO:    --keep_weights=   # force to keep the weight even if in the list of remove_weights
INFO:    --start_id=       # define the starting digit for the additial weight. If not specify it is determine automatically
INFO:    --only_beam=0     # only apply the new pdf set to the beam selected. [New in 2.6.2]
INFO:    --ion_scaling=True# if original sample was using rescaled PDF: apply the same rescaling for all PDF sets. [New in 2.6.2]
INFO:
INFO:    Allowed value for the pdf options:
INFO:        central  : Do not perform any pdf variation
INFO:        errorset : runs over the all the members of the PDF set used to generate the events
INFO:        244800   : runs over the associated set and all its members
INFO:        244800@0 : runs over the central member of the associated set
INFO:        CT10     : runs over the associated set and all its members
INFO:        CT10@0   : runs over the central member of the associated set
INFO:        CT10@X   : runs over the Xth member of the associated PDF set
INFO:        XX,YY,ZZ : runs over the sets for XX,YY,ZZ (those three follows above syntax)
INFO:
INFO:    Allowed value for the keep/remove_wgts options:
INFO:        all      : keep/remove all weights
INFO:        name     : keep/remove that particular weight
INFO:        id1,id2  : keep/remove all the weights between those two values --included--
INFO:        PATTERN  : keep/remove all the weights matching the (python) regular expression.
INFO:        note that multiple entry of those arguments are allowed

Note that the run_card do not have any entry for the type of dynamical scale (since SysCalc does not support it). So it is default all the possible value. One can also specify the argument of the "systematics" module by putting in the run_card an entry for systematics_arguments (as a list of string For example

   ['--pdf=central', '--dyn=-1,3', '--together=mur,muf'] = systematics_arguments

in that case the other entry of the run_card related to the systematics computation are just ignored.

NLO

At NLO, you have two options to compute the systematics error. on the flight this methods performs the re-weighting during the generation of the events. The output file contain the additional weight but NOT the information to perform an additional re-weighting (by default) forbidding to perform a different re-weighting later (different pdf/scale choice/...) The second method is the "systematics" module of MG5aMC, where additional information will be written in the file in order to compute systematics weight independently of the event generation.

On the flight method

In order to use this mode, you can set in the run_card those two parameters:

 True = reweight_scale ! Reweight to get scale variation using the
            ! rw_rscale and rw_fscale factors. Should be a list of
            ! booleans of equal length to dynamical_scale_choice to
            ! specify for which choice to include scale dependence.
 False = reweight_PDF  ! Reweight to get PDF uncertainty. Should be a
            ! list booleans of equal length to lhaid to specify for
            !  which PDF set to include the uncertainties.

You can specify inside the run_card the list of pdf requested/ the list of dynamical scale /...

For example in order to have multiple dynamical_scale you have to have the line in the run_card

 -1,2,3 = dynamical_scale_choice ! Choose one (or more) of the predefined
           ! dynamical choices. Can be a list; scale choices beyond the
           ! first are included via reweighting

The option 2 and 3 for the dynamical scale will then be include via the re-weighting approach

Systematics (python) module

In order to use this module you have to set the run_card parameter "store_reweight_info" to True (i.e. having the following line in the run_card)

 True = store_reweight_info

This is not the default value of this parameter. If you want that this module is directly called after the event generation you have to add the following line in the run_card:

  systematics = systematics_program

parameter of the systematics module can be specified in systematics_argument for example with the following line in the run_card:

   ['--pdf=central', '--dyn=-1,3', '--together=mur,muf'] = systematics_arguments

The list of available options are the same as the one at LO (see above)

As for the LO case, a dedicated function exists in the aMC@NLO interface (available via either launch -i or via the ./bin/aMC@NLO script)