Here we will describe two special ways PYTHIA can make use of MadGraph5 and
MadGraph5_aMC@NLO [Alw11,Alw14], either by
exporting Madgraph process code or by wrapping the MadGraph5_aMC@NLO
generator as a PYTHIA Les Houches interface.
Of course, PYTHIA can also read in Les Houches Event
Files (LHEF) generated by MadGraph. This is the
most commonly used approach, and requires no further description here.
- MadGraph5 matrix-element plugins
- MadGraph5 code inside PYTHIA
- MadGraph5_aMC@NLO executable inside PYTHIA
MadGraph5 matrix-element plugins
Runtime plugin loading of matrix elements generated by Madgraph is
available. A small set of pre-generated ones covering most Born-level
SM processes and decays are included with the baseline Pythia
distribution; see below for how to determine which ones are available and
how to generate further ones.
Configuration and Build Procedure
MG5 ME plugin loading must first of all be enabled, by passing the
--enable-mg5mes to the Pythia
configure script. This ensures that the MG5 ME plugin
libraries are compiled during the
make stage and thus
that they will be available at runtime.
Optionally, a custom directory path,
--enable-mg5mes=DIR, can be provided to tell Pythia to look
for user-generated matrix-element plugins in a non-standard
If no argument is supplied (normal usage), then Pythia will
use the default location
DIR=plugins/mg5mes/ which contains the
pre-generated MG5 ME libraries that are included with Pythia.
You can do an
ls in this
directory to see which pre-generated libraries are available.
Each folder corresponds to a plugin, with the Madgraph
configuration and commands used to generate it available in
PLUGIN.card in the corresponding
folder. At build time, each
PLUGIN is compiled into a
library of the form
libpythia8mg5PLUGIN.so in the Pythia
Currently, the MG5 ME plugins are used for matrix-element corrections in
Dire and Vincia, and to determine Born-level helicities for polarised
parton showers. The Pythia Settings words
which plugin library to load, for Dire and Vincia, respectively.
The same libraries are compatible between Dire and Vincia and are named as
one of the matrix-element folders specified by the path optionally
How to generate further MadGraph5 matrix-element plugins
Additional MG5 matrix-element libraries can be created by the user. Note
however, that the runtime plugin loading relies on a dedicated MG5
output format which is not yet available in the public MG5
distribution. Instead, use the included
plugins/mg5mes, to generate new plugin
libraries for Pythia. This script relies on Docker, so note that you
must have Docker installed on your system to use this.
As an example,
./generate --model=sm --output=example --process="p p > e+ e-"
will build all SM matrix elements for the process p p → e+
e-. The general usage requires three options as
follows. Arguments to the options are indicated in caps, and default
arguments are given in square brackets.
Advanced usage is possible where the
--model=MODEL : Model to use, either internal or
[sm]. When external, specify either the
./sm, or absolute path.
--output=OUT: Output directory for the generated
--process=PROC: Process or processes to generate
["p p > e+ e-"]. Multiple processes can be passed,
./generate --process="p p > e+ e-" --process="p p >
--process option is
no longer used. The
--model option, however, is still
required if using any external models, and
required to specify the output directory.
--card=FILE: Run a full MadGraph command card.
--interactive : Run MadGraph in interactive
MadGraph5 code inside PYTHIA
By far the easiest way to implement new processes into PYTHIA 8 is
by using the matrix-element generator MadGraph5. This program has
an option to output the results of a matrix-element calculation
as a set of PYTHIA 8 C++ classes (plus further auxiliary code),
that can then be linked and used as
meaning they are handled identically with normal internal ones.
This way, MadGraph5 can be used to implement processes from
any model that can be written in terms of a Lagrangian. Any
2 → 1, 2 → 2 and 2 → 3 processes
can be implemented, the limit being set by the absence of efficient
phase space generator algorithms for higher multiplicities in
PYTHIA. Features such as s-channel resonances are
automatically implemented in the process classes. Besides the process
library and necessary model files, also an example main program is
generated for each set of processes, which can be easily modified to
perform the desired analyses.
In order to create a PYTHIA 8 process library with MadGraph5, first
download the MadGraph5 package from
https://launchpad.net/madgraph5, and untar the package. You can
then specify the location of your
in the file
pythia8_path = ./pythia81xx
The location can be either relative (to the directory
MadGraph5_v_x_x_x/.) or absolute.
For any model that is already implemented in the MadGraph5 package,
you can directly use the model. Start the MadGraph5 interface
bin/mg5, and do:
import model model_name
add process your_next_process_in_mg5_syntax
output pythia8 [path_to_pythia81xx_directory]
For examples of MG5 process syntax, please see
help generate. If you specified the path to the
pythia81xx directory in the
file, you do not need to enter it in the
If your preferred model is found on the FeynRules model wiki page,
download the UFO (Universal FeynRules Output) tar file for the model,
untar in the
models/ directory, and use as above.
If you want to implement a new model which has not yet been implemented,
you can do this either using the Mathematica package FeynRules (see
http://feynrules.irmp.ucl.ac.be/) or directly edit the UFO model
files of the most similar model in the
The resulting output from the
output pythia8 command is:
Note that in order for PYTHIA 8 to be able to automatically decay any
new particles, it is necessary to specify the branching ratios of the
particles in the
- A process directory
Processes_modelname with the
model information and the files needed for all processes defined for
this model, placed in the
pythia81xx main directory.
The model files are
HelAmps_modelname.h/cc, and the process files for each
process class (with the same mass, spin and color of the initial/final
state particles) are called
The directory also contains a
makefile and a model parameter
- An example main program in the directory
pythia81xx main directory) called
main_modelname_N.cc and a corresponding makefile
Makefile_modelname_N. This main program links in the
process classes in the process directory described above. To run the
example main program, just go to the
directory and run
make -f Makefile_modelname_N
launch directly inside the MadGraph5
command line interface.
param_card file, see
[Ska04,Alw07] for details.
For further technical details, please see the MadGraph5 release paper
[Alw11] and the
semi-internal processes page.
Currently the standard way of interfacing is to use the LHEF standard
with an intermediate event file. The advantage is that then the
MadGraph5 phase space generator can be used, which opens up for
processes with more than three particles in the final state. The
disadvantages are that it is less easy to mix and match with existing
PYTHIA processes, and that one needs to regenerate and store large LHEF
files for different kinematics cuts or parameter values.
Please cite the MadGraph5 release paper [Alw11] if you use
MadGraph5 to generate process libraries for PYTHIA 8.
MadGraph5_aMC@NLO executable inside PYTHIA
Pythia::setLHAupPtr(LHAup* lhaUpPtr) method allows
a Pythia generator to accept a pointer to an object derived from the
LHAup base class.
Such an object will be initialized from within Pythia, and be called
repeatedly to generate the next parton-level event, using the LHA
specification as a standard to transfer the relevant information back
to Pythia. Properly constructed, the operation of an
object thus is almost completely hidden from the user, and generates
events almost like an ordinary internal Pythia process.
LHAupMadgraph is precisely such a class, derived from
LHAup, that contains the code needed to wrap a
MadGraph5_aMC@NLO executable. Thereby the generation of Madgraph
processes from within Pythia becomes straightforward. An explicit
example is provided in
main34.cc. We describe some of the
key elements used there and in the general case.
LHAupMadgraph::LHAupMadgraph(Pythia* pythia, bool match = true, string dir = "madgraphrun", string exe = "mg5_aMC")
creates an instance of the
argument pythia : pointer to the
such that some of its facilities can be used inside the interface.
argument match (
default = on) : should be true if jet matching is
requested. For tree-level generation MLM matching is used, while
FxFx matching is used for aMC@NLO generation. This is set up in
LHAupMadgraph::setInit(), which could be modified to
represent other matching strategies or parameter values.
argument dir (
default = madgraphrun) : the name of the run
directory, into which MadGraph puts its (intermediate) results.
argument exe (
default = mg5_aMC) : the name of the MadGraph5_aMC@NLO
LHAupMadgraph is meant to wrap. In additon
it may be necessary to prepend the full pathname of the executable:
bool LHAupMadgraph::readString(string line, Stage stage = Auto)
allows the user to send commands to MadGraph.
argument line : the command to be sent to MadGraph.
Any string begining with
"configure " is used for the initial
MadGraph configuration with
"configure " stripped from the
begining. In general, only the process and run settings need to be
provided. Run settings must begin with
" set"; note the
leading space. The output and launch commands, random seed, and shower
choice are automatically handled. For example, the following will produce
di-muon events from 13 TeV proton proton collisions at NLO in QCD:
readString("generate p p > mu+ mu- [QCD]");
argument stage (
default = Auto) : if the stage is set to Auto,
commands beginning with
" set" are used in the launch
stage, commands begining with
"configure" are used in the
configuration stage, and all remaining commands
launch) are used in the generate stage. Output, launch, seed,
and shower commands are automatically handled. If the user wishes to
override commands, then the stage can be specified. This will prevent any
automatically generated commands from being used for that stage. This
should only be done if the user understands what additional commands are
void LHAupMadgraph::setEvents(int events)
the number of events to generate per MadGraph run. Normally does not
need to be set, but defaults to 10000.
void LHAupMadgraph::setSeed(int seed, int runs = 30081)
the random seed (sequence), normally not needed to be set explicitly.
If the random seed is negative (default of -1), then the MadGraph
seed is taken as the Pythia parameter
must be greater than 0. If the maximum number of allowed runs is exceeded
(default of 30081) an error is thrown. The seed for a MadGraph run is set as:
(random seed - 1) * (maximum runs) + (number of runs) + 1.
MadGraph can only handle random seeds up to 30081 * 30081. So, with
this strategy, one can generate Pythia jobs with seeds from 1 to 30081,
with each job running MadGraph less than 30081 times, and ensure a fully
statistically independent sample. If more than 30081 jobs are needed, then
the maximum allowed runs can be lowered accordingly, and if need be,
setEvents can be used to increase the number of events generated per run.
void LHAupMadgraph::setJets(int jets)
Set the number maximum number of jets generated by MadGraph.
If negative (default of -1) then the number of jets is determined
automatically, to be the maximum number of jets produced at leading order.
Note that GZIP support must be enabled in the Pythia executable, so use
--with-gzip option in the
before Pythia compilation.
Events are generated with MadGraph utilizing the
gridpack method for MadGraph5 and an
equivalent method for aMC@NLO. Consequently the run
"madgraphrun" by default, does not need to be deleted
between independent runs with the same configuration (excluding random
seeds). Indeed, keeping the directory significantly speeds the generation
process, particularly for NLO generation with aMC@NLO as the grid
initialization can be skipped after the initial run.