MadGraph Interface to CMSSW

Complete: 5


In the new CMSSW releases, a new interface has been written that substitutes and extends the MadGraphInterface. This interface takes as input LHE files and works also with other generators. The instructions on how to us it are here:


MadEvent is a multi-purpose, tree-level event generator which is powered by the matrix element generator MadGraph. A process-dependent, self-consistent code for a specific SM process is generated upon the user's request on a web form at Given the process, MadGraph automatically generates the amplitudes for all the relevant subprocesses and produces the mappings for the integration over the phase space. This process-dependent information is packaged into MadEvent, and a stand-alone code is produced that can be downloaded from the web site and allows the user to calculate cross sections and to obtain unweighted events automatically. Events can be also generated directly from the web, by filling a form and letting the code run over the MadGraph dedicated clusters.

Once the events have been generated - event information, (e.g. particle id's, momenta, spin, color connections) is stored in the Les Houches format, they may be passed directly to a shower Monte Carlo program. To interface MadGraph to CMSSW and pass the events to Pythia, the MadGraphInterface package has been written. MadGraphInterface is a CMSSW package in the GeneratorInterface subsystem that allows to read in events in the Les Houches format, perform parton shower and hadronization using Pythia and write CMSSW objects (edm::HepMCProduct) in the event (edm::Event).

This CMSSW interface is based on code written by Johan Alwall, who is also one of main the MadGraph developers.

Previous versions and configurations

  • Previously, MadGraphInterface read the events in another format. Since the code tag V00-01-01 of the MadGraph interface (GeneratorInterface/MadGraphInterface) in CMSSW, changes have been made to use the new Les Houches format. The previous code has been tagged and the instructions for using it can be found here
  • Python has become the official configuration tool for CMSSW jobs. The old style configuration files are deprecated. Their last copy is kept in GeneratorInterface/MadGraphInterface/test/OldStyleCfgs. The old instructions for those configuration files and older versions of CMSSW can be found here

Generating the sample

Sites and registration

There are three sites currently available for code and event generation:

Version 4 should be used. In Version 4 parton level events are written in the Les Houches Event File format (events.lhe). If you're using MadGraph for the first time you need to register at the site before you can begin. Registrations are valid only for the site where they were obtained from.

Generating and running code

For instance, go to the web page , click in the upper menu on 'Generate Process' and follow the instructions therein.

As an example, the process pp->ttbar is input as pp>tt~ where

  • " > " separates initial and final state particles.
  • " ~ " is used for fermion antiparticles.
  • " + " is used for leptons and charged boson antiparticles.

Particle names and examples are given on the web page. Code for your specific process will be produced which can be downloaded and run. Once the code is ready do the following

  • Create directory for the code before extracting. Decompress/unzip: gunzip madevent.dat.tar.gz
  • Unpack: tar -xvf madevent.tar
  • Build the code: go into the /Source directory and type Make
  • To generate a sample of unweighted events type: ./bin/generate_events from the top level directory.

Generating events from the web page

Parton-level (lhe) and pythia hadron-level events (sthep) can be generated directly from the web, if the user has clearance to run over the cluster. Permission can be obtained by sending an e-mail to

Reading the generated events in CMSSW using MadGraphInterface

The following examples have been tested to work with a CERN afs account on an lxplus machine. Some of the Les Houches files and the output in the examples below are big and one might run into problems with afs space. In lack of disk space, on lxplus the examples can be run also in the /tmp/$USER directory on the logging machine.

Setting up the Examples

Only the examples subdirectory has to be checked out since the code is already tagged and in the newest releases:

  • make your local release, for example: cmsrel CMSSW_2_2_2
  • go to the source directory of your release: cd CMSSW_2_2_2/src
  • set the cvs root and log in: cmscvsroot CMSSW; cvs login (password: 98passwd)
  • check out the package test directory
    • at the present, to have the new python configuration files, check out this tag: cvs co -r V08-00-08 GeneratorInterface/MadGraphInterface/test
    • (in general you need to check out the same release: cvs co -r CMSSW_2_2_2 GeneratorInterface/MadGraphInterface/test, or cmsenv; addpkg GeneratorInterface/MadGraphInterface)
  • cd to the examples subdirectory: cd GeneratorInterface/MadGraphInterface/test
  • set the shell environment: cmsenv

Example 1 - Run on an input Les Houches file


This example runs on the input example file that contains 1000 ttbar events: small_example_ttbar.lhe that resides in the same directory and produces an output POOL file MGtest.root . By default it runs on 100 events, this can be changed in the parameter maxEvents in the python file itself. If that parameter is set to '-1' it will run over all events of the input LH file (1K events). The full file is not put on CVS in order not to waste too much space. It can be found on castor on: /castor/ You can copy the full file and run on it (change the fileNames parameter in the configuration file) but is 6.1M big and that can be a problem on afs.

It might be useful to keep the output in a log file as it has information about the Pythia parameters and of the configuration of the MadGraph interface. This can be done as follows:

cmsRun >& logtest.txt &
One can watch the log file using the less command or if the execution is long, to monitor the log file in the meantime: tail -f logtest.txt. The same applies to the other examples.

Example 2 - Simple analyzer of the output from the above example


The output file (MGtest.root) produced with Example 1 is analyzed. The list of particles for each event is printed out on the screen. This analyzer uses the HepMCProduct object. There is not output root produced, you can extend this analyzer to fit your own needs. The code is in interface/HepMGProductAnalyzer.h and src/

Example 3 - Simple analyzer using GenParticles and printing a particle tree


In this example the HepMCProduct objects are first translated on the fly in GenParticle objects and then a utility is used which prints out the tree of particles and the decays. Nice tool provided by Luca Lista. Same as above if you want to put the output in a file. By default it will run on the first 100 events from the MGtest.root . This can be changed in the variable maxEvents of the PoolSource in the configuration file.

Example 4 - Run on an input Les Houches file from the Phantom MC

You can use the MadGraphInterface also to read input files in the Les Houches format from the Phantom MC or other Monte Carlos that out Les Houches event files. An example file is in the test directory: small_example_phantom_mc.lhe . It is enough to substitute the fileNames parameter and set minimalLH = True in (all of this is already in the python file, one just needs to comment/uncomment lines) . The minimalLH flag turns off reading of MadGraph specific information from the header of the Les Houches file.

Performing Matrix Element - Parton Shower Matching

The ME-PS matching between MadGraph and Pythia is part of the CMSSW interface of MadGraph.

Example 1: ttbar + jets

Warning: the LHE file and the output files are big so under afs you might fill up the whole space assigned to you and the job will crash because of that. Try this on a data disk or the '=/tmp/$USER=' directory on lxplus. In future releases there will be no extra tag needed. It only contains the python configuration files, no source code. Also, these examples take more time to run than the simple examples above.

Checkout, compile:

cmsrel CMSSW_2_2_2
cd CMSSW_2_2_2/src/
cmscvsroot CMSSW; cvs login; # same password as examples above
cvs co -r V08-00-08 GeneratorInterface/MadGraphInterface/test
scramv1 b ; # not sure if this is really necessary
cd GeneratorInterface/MadGraphInterface/test

Copy from castor the LesHouches file with the ttbar samples: ttbar + 0 jets, +1 jets, +2 jets, +3 jets and run the interface with matching, N.B.: if you want to produce the validation plot below, set produceEventTreeFile = True in the configuration file.

rfcp /castor/ .
cmsRun >& logmatching.txt &

In order to validate the matching procedure, apart from the usual POOL file an event tree with the matching information is produced. This event tree can be turned on setting produceEventTreeFile = True in the configuration file. The event tree file is called events.tree and is a plain ascii file. In production this flag should be kept 'False' as the code that produces this extra file messes up the status code of particles. Also the jobs become slower if you produce the validation file. For these reasons the flag is set to 'False' by default in the configuration files.

Run the root macro makentuple.C which will produce an ntuple and some histograms from the events.tree

root -l -b -q ./makentuple.C
then produce the validation plot:
root -l -b -q ./plotjetrate.C'("ttbar")'

It will produce a gif file with the following plot.

  • 1->2 Jet rates for ttbar + jets at LHC, MadGraph + Pythia:

The "ttbar" string parameter of the plotting macro is just a label for the process. If you do not give it, the process will be names "unknown".

Example 2: Zmumu + jets

Same as Example 1 for ttbar but different input lhe file and configuration script:
rfcp /castor/ .
root -l -b -q ./makentuple.C
then produce the validation plot:
root -l -b -q ./plotjetrate'("Zmumu")'


No special tags needed for code in the 2XX and 3XX releases. The python examples in the '/test' subdirectory are not yet included, though. You can get them with the tag V08-00-08 GeneratorInterface/MadGraphInterface/test



The MadGraphInterface package was originally developed by Hector Naves Sordo and Maria Forbord Hansen. It is presently developed and maintained by Dorian Kcira.

If you have any questions concerning the MadGraphInterface contact

Review Status

Editor/Review and date Comments
CMS.DorianKcira - 27 Mar 2007 Page current maintainer
JennyWilliams - 30 Mar 2007 moved madgraph documentation into SWGuide
CMS.DorianKcira - 23 May 2007 added documentation about ME-PS matching
CMS.DorianKcira - 14 Dec 2008 clean-up and new python configuration

Responsible: CMS.DorianKcira
Last reviewed by: Dorian Kcira

Topic attachments
I Attachment History Action Size Date Who Comment
GIFgif ttbarjetrate12.gif r2 r1 manage 12.5 K 2007-05-25 - 08:00 DorianKcira ttbar
Edit | Attach | Watch | Print version | History: r37 < r36 < r35 < r34 < r33 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r37 - 2009-04-14 - DorianKcira

    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback