<chapter name="MadGraph5 Processes"> 
 
<h2>MadGraph5 Processes</h2> 
 
Here we will describe two special ways PYTHIA can make use of MadGraph5 and 
MadGraph5_aMC@NLO <ref>Alw11,Alw14</ref>, either by 
exporting Madgraph process code or by wrapping the MadGraph5_aMC@NLO 
generator as a PYTHIA Les Houches interface. 
 
<p/> 
Of course, PYTHIA can also read in <aloc href="LHEF">Les Houches Event 
Files</aloc> (LHEF) generated by MadGraph. This is the 
most commonly used approach, and requires no further description here. 
 
<h3>MadGraph5 matrix-element plugins</h3> 
 
<p/> 
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. 
 
<h4>Configuration and Build Procedure</h4> 
 
<p/> 
MG5 ME plugin loading must first of all be enabled, by passing the 
flag <code>--with-mg5mes</code> to the Pythia 
<code>configure</code> script. This ensures that the MG5 ME plugin 
libraries are compiled during the <code>make</code> stage and thus 
that they will be available at runtime. 
 
<p/> 
Optionally, a custom directory path, 
<code>--with-mg5mes=DIR</code>, can be provided to tell Pythia to look 
for user-generated matrix-element plugins in a non-standard 
location. 
 
<p/> 
If no argument is supplied (normal usage), then Pythia will 
use the default location <code>DIR=plugins/mg5mes/</code> which contains the 
pre-generated MG5 ME libraries that are included with Pythia. 
You can do an <code>ls</code> in this 
directory to see which pre-generated libraries are available. 
 
<p/> 
Each folder corresponds to a plugin, with the Madgraph 
configuration and commands used to generate it available in 
<code>PLUGIN.card</code> in the corresponding <code>PLUGIN</code> 
folder. At build time, each <code>PLUGIN</code> is compiled into a 
library of the form <code>libpythia8mg5PLUGIN.so</code> in the Pythia 
library folder. 
 
<h4>Runtime Initialisation</h4> 
 
<p/> 
Currently, the MG5 ME plugins are used for matrix-element corrections in 
Vincia, and to assign Born-level helicities for its helicity-dependent 
parton showers. The Pythia Settings word 
<aloc href="VinciaMECs"><code>Vincia:MEplugin</code></aloc> specify 
which plugin library to load. 
The libraries are named as 
<code>libpythia8mg5PLUGIN.so</code> where <code>PLUGIN</code> is 
one of the matrix-element folders specified by the path optionally 
passed to <code>--with-mg5mes=DIR</code>. 
 
 
<h4>How to generate further MadGraph5 matrix-element plugins</h4> 
 
<p/> 
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 <code>generate</code> script, 
located in <code>plugins/mg5mes</code>, 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. 
 
<p/> 
As an example, 
<pre> 
./generate --model=sm --output=example --process="p p &gt; e+ e-" 
</pre> 
will build all SM matrix elements for the process <ei>p p &rarr; e+ 
e-</ei>.  The general usage requires three options as 
follows. Arguments to the options are indicated in caps, and default 
arguments are given in square brackets. 
<ul> 
  <li><code>--model=MODEL</code> : Model to use, either internal or 
  external <code>[sm]</code>. When external, specify either the 
  relative, e.g. <code>./sm</code>, or absolute path.</li> 
  <li><code>--output=OUT</code>: Output directory for the generated 
  matrix elements <code>[kernels]</code>.</li> 
  <li><code>--process=PROC</code>: Process or processes to generate 
  <code>["p p &gt; e+ e-"]</code>. Multiple processes can be passed, 
  e.g. <code>./generate --process="p p &gt; e+ e-" --process="p p &gt; 
  mu+ mu-"</code>.</li> 
</ul> 
Advanced usage is possible where the <code>--process</code> option is 
no longer used. The <code>--model</code> option, however, is still 
required if using any external models, and <code>--output</code> is 
required to specify the output directory. 
<ul> 
  <li><code>--card=FILE</code>: Run a full MadGraph command card.</li> 
  <li><code>--interactive</code> : Run MadGraph in interactive 
  mode.</li> 
</ul> 
 
<h3>MadGraph5 code inside PYTHIA</h3> 
 
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 
<aloc href="SemiInternalProcesses">semi-internal</aloc> 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 
<ei>2 &rarr; 1</ei>, <ei>2 &rarr; 2</ei> and <ei>2 &rarr; 3</ei> 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 <ei>s</ei>-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. 
 
<p/> 
In order to create a PYTHIA 8 process library with MadGraph5, first 
download the MadGraph5 package from 
<a href="https://launchpad.net/madgraph5" target="page"> 
https://launchpad.net/madgraph5</a>, and untar the package. You can 
then specify the location of your <code>pythia81xx</code> directory 
in the file <code>input/mg5_configuration.txt</code>: 
<br/><code>pythia8_path = ./pythia81xx</code> 
<br/>The location can be either relative (to the directory 
<code>MadGraph5_v_x_x_x/.</code>) or absolute. 
 
<p/> 
For any model that is already implemented in the MadGraph5 package, 
you can directly use the model. Start the MadGraph5 interface 
<code>bin/mg5</code>, and do: 
<pre> 
import model model_name 
generate your_process_in_mg5_syntax 
add process your_next_process_in_mg5_syntax 
... 
output pythia8 [path_to_pythia81xx_directory] 
</pre> 
 
<p/> 
For examples of MG5 process syntax, please see 
<a href="http://madgraph.phys.ucl.ac.be/EXAMPLES/example_mg5.html" 
target="page">http://madgraph.phys.ucl.ac.be/EXAMPLES/example_mg5.html</a> 
or type <code>help generate</code>. If you specified the path to the 
<code>pythia81xx</code> directory in the <code>mg5_configuration</code> 
file, you do not need to enter it in the <code>output</code> command. 
 
<p/> 
If your preferred model is found on the FeynRules model wiki page, 
<a href="http://feynrules.irmp.ucl.ac.be/wiki/ModelDatabaseMainPage" 
target="page">http://feynrules.irmp.ucl.ac.be/wiki/ModelDatabaseMainPage</a>, 
download the UFO (Universal FeynRules Output) tar file for the model, 
untar in the <code>models/</code> directory, and use as above. 
 
<p/> 
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 
<a href="http://feynrules.irmp.ucl.ac.be/" target="page"> 
http://feynrules.irmp.ucl.ac.be/</a>) or directly edit the UFO model 
files of the most similar model in the <code>models/</code> directory. 
 
<p/> 
The resulting output from the <code>output pythia8</code> command is: 
<ul> 
<li>A process directory <code>Processes_modelname</code> with the 
model information and the files needed for all processes defined for 
this model, placed in the <code>pythia81xx</code> main directory. 
The model files are <code>Parameters_modelname.h/cc</code> and 
<code>HelAmps_modelname.h/cc</code>, and the process files for each 
process class (with the same mass, spin and color of the initial/final 
state particles) are called <code>Sigma_modelname_processname.h/cc</code>. 
The directory also contains a <code>makefile</code> and a model parameter 
file <code>param_card_modelname.dat</code>.</li> 
<li>An example main program in the directory <code>examples/</code> 
(in the <code>pythia81xx</code> main directory) called 
<code>main_modelname_N.cc</code> and a corresponding makefile 
<code>Makefile_modelname_N</code>. This main program links in the 
process classes in the process directory described above. To run the 
example main program, just go to the <code>examples/</code> 
directory and run 
<br/><code>make -f Makefile_modelname_N</code> 
<br/>or run <code>launch</code> directly inside the MadGraph5 
command line interface.</li> 
</ul> 
 
<p/> 
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 <code>param_card</code> file, see 
<ref>Ska04,Alw07</ref> for details. 
 
<p/> 
For further technical details, please see the MadGraph5 release paper 
<ref>Alw11</ref> and the 
<aloc href="SemiInternalProcesses">semi-internal</aloc> processes page. 
 
<p/> 
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. 
 
<p/> 
Please cite the MadGraph5 release paper <ref>Alw11</ref> if you use 
MadGraph5 to generate process libraries for PYTHIA 8. 
 
<h3>MadGraph5_aMC@NLO executable inside PYTHIA</h3> 
 
The <code>Pythia::setLHAupPtr(LHAup* lhaUpPtr)</code> method allows 
a Pythia generator to accept a pointer to an object derived from the 
<code><aloc href="LHA">LHAup</aloc></code> 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 <code>LHAup</code> 
object thus is almost completely hidden from the user, and generates 
events almost like an ordinary internal Pythia process. 
 
<p/> 
The <code>LHAupMadgraph</code> is precisely such a class, derived from 
<code>LHAup</code>, 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 <code>main153.cc</code>. We describe some of the 
key elements used there and in the general case. 
 
<method name="LHAupMadgraph::LHAupMadgraph(Pythia* pythia, 
bool match = true, string dir = &quot;madgraphrun&quot;, 
string exe = &quot;mg5_aMC&quot;)"> 
creates an instance of the <code>LHAupMadgraph</code> class. 
<argument name="pythia"> pointer to the <code>Pythia</code> instance, 
such that some of its facilities can be used inside the interface. 
</argument> 
<argument name="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 
<code>LHAupMadgraph::setInit()</code>, which could be modified to 
represent other matching strategies or parameter values. 
</argument> 
<argument name="dir" default="madgraphrun"> the name of the run 
directory, into which MadGraph puts its (intermediate) results. 
</argument> 
<argument name="exe" default="mg5_aMC"> the name of the MadGraph5_aMC@NLO 
executable that <code>LHAupMadgraph</code> is meant to wrap. In additon 
it may be necessary to prepend the full pathname of the executable: 
<code>"(something)/MG5_aMC_v2_3_3/bin/mg5_aMC"</code>. 
</argument> 
</method> 
 
<method name="bool LHAupMadgraph::readString(string line, 
Stage stage = Auto)"> 
allows the user to send commands to MadGraph. 
<argument name="line"> the command to be sent to MadGraph. 
Any string begining with <code>"configure "</code> is used for the initial 
MadGraph configuration with <code>"configure "</code> stripped from the 
begining. In general, only the process and run settings need to be 
provided. Run settings must begin with <code>" set"</code>; 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: 
<br/><code>readString("generate p p > mu+ mu- [QCD]");</code> 
</argument> 
<argument name="stage" default="Auto"> if the stage is set to Auto, 
commands beginning with <code>" set"</code> are used in the launch 
stage, commands begining with <code>"configure"</code> are used in the 
configuration stage, and all remaining commands 
(excluding <code>output</code> and 
<code>launch</code>) 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. 
</argument> 
</method> 
 
<method name="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. 
</method> 
 
<method name="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 <code>"Random:seed"</code>, 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: 
<br/> (random seed - 1) * (maximum runs) + (number of runs) + 1. 
<br/>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. 
</method> 
 
<method name="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. 
</method> 
 
<p/> 
Note that GZIP support must be enabled in the Pythia executable, so use 
the <code>--with-gzip</code> option in the <code>configure</code> step 
before Pythia compilation. 
 
<p/> 
Events are generated with MadGraph utilizing the 
<a href="https://cp3.irmp.ucl.ac.be/projects/madgraph/wiki/GridDevelopment" 
target="_top">gridpack</a> method for MadGraph5 and an 
<a href="https://answers.launchpad.net/mg5amcnlo/+question/243268" 
target="_top">equivalent method</a> for aMC@NLO. Consequently the run 
directory, <code>"madgraphrun"</code> 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. 
 
</chapter> 
 
<!-- Copyright (C) 2025 Torbjorn Sjostrand --> 
