MadGraph5 Processes

Here we will describe two special ways to make use of MadGraph5 and MadGraph5_aMC@NLO [Alw11,Alw14]inside PYTHIA, either by exporting Madgraph process code or by wrapping the MadGraph5_aMC@NLO generator as a PYTHIA Les Houches interface.

Of course, MadGraph5 can also output files of parton-level events according to the LHEF standard, that can be read in and processed further by PYTHIA 8. This is the most commonly used approach, and requires no further description here.

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_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 Parameters_modelname.h/cc and 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 Sigma_modelname_processname.h/cc. The directory also contains a makefile and a model parameter file param_card_modelname.dat.
An example main program in the directory examples/ (in the 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 examples/ directory and run
make -f Makefile_modelname_N
or run launch directly 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 the 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

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 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 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.