MadGraph5 Processes
 
  - MadGraph5 matrix-element plugins
- MadGraph5 code inside PYTHIA
- MadGraph5_aMC@NLO executable inside PYTHIA
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
 
 
 
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 
flag --with-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, 
--with-mg5mes=DIR, can be provided to tell Pythia to look 
for user-generated matrix-element plugins in a non-standard 
location. 
 
 
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 PLUGIN 
folder. At build time, each PLUGIN is compiled into a 
library of the form libpythia8mg5PLUGIN.so in the Pythia 
library folder. 
 
Runtime Initialisation
 
 
 
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 
Dire:MEplugin and 
Vincia:MEplugin specify 
which plugin library to load, for Dire and Vincia, respectively. 
The same libraries are compatible between Dire and Vincia and are named as 
libpythia8mg5PLUGIN.so where PLUGIN is 
one of the matrix-element folders specified by the path optionally 
passed to --with-mg5mes=DIR. 
 
 
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 generate script, 
located in 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. 
 
  - --model=MODEL: Model to use, either internal or 
  external- [sm]. When external, specify either the 
  relative, e.g.- ./sm, or absolute path.
- --output=OUT: Output directory for the generated 
  matrix elements- [kernels].
- --process=PROC: Process or processes to generate- ["p p > e+ e-"]. Multiple processes can be passed, 
  e.g.- ./generate --process="p p > e+ e-" --process="p p > 
  mu+ mu-".
Advanced usage is possible where the--process option is 
no longer used. The --model option, however, is still 
required if using any external models, and --output is 
required to specify the output directory. 
 
  - --card=FILE: Run a full MadGraph command card.
- --interactive: Run MadGraph in interactive 
  mode.
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 
semi-internal processes, 
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 pythia81xx directory 
in the file input/mg5_configuration.txt: 
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 
generate your_process_in_mg5_syntax 
add process your_next_process_in_mg5_syntax 
... 
output pythia8 [path_to_pythia81xx_directory] 
 
 
 
For examples of MG5 process syntax, please see 
http://madgraph.phys.ucl.ac.be/EXAMPLES/example_mg5.html 
or type help generate. If you specified the path to the 
pythia81xx directory in the mg5_configuration 
file, you do not need to enter it in the output command. 
 
 
If your preferred model is found on the FeynRules model wiki page, 
http://feynrules.irmp.ucl.ac.be/wiki/ModelDatabaseMainPage, 
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 models/ directory. 
 
 
The resulting output from the output pythia8 command is: 
 
- A process directory Processes_modelnamewith the 
model information and the files needed for all processes defined for 
this model, placed in thepythia81xxmain directory. 
The model files areParameters_modelname.h/ccandHelAmps_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 calledSigma_modelname_processname.h/cc. 
The directory also contains amakefileand a model parameter 
fileparam_card_modelname.dat.
- An example main program in the directory examples/(in thepythia81xxmain directory) calledmain_modelname_N.ccand a corresponding makefileMakefile_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 theexamples/directory and run
 make -f Makefile_modelname_N
 or runlaunchdirectly inside the MadGraph5 
command line interface.
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 theparam_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
 
 
The 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 LHAup 
object thus is almost completely hidden from the user, and generates 
events almost like an ordinary internal Pythia process. 
 
 
The 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 main153.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 LHAupMadgraph class. 
argument pythia   :  pointer to the Pythia instance, 
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 
executable that LHAupMadgraph is meant to wrap. In additon 
it may be necessary to prepend the full pathname of the executable: 
"(something)/MG5_aMC_v2_3_3/bin/mg5_aMC". 
   
   
 
 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 
(excluding output and 
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 
needed. 
   
   
 
 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 "Random:seed", which 
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 
the --with-gzip option in the configure step 
before Pythia compilation. 
 
 
Events are generated with MadGraph utilizing the 
gridpack method for MadGraph5 and an 
equivalent method for aMC@NLO. Consequently the run 
directory, "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.