Notes for Madgraph tutorial for NIU PHYS 474/790

You can find these notes online at You can also review how to start Madgraph at After you finish reading these notes, the next lecture is based on

We will use the interactive version of Madgraph. It has a tutorial and help commands. We will first follow the Madgraph tutorial example. Below I will give information that is both complementary and redundant to what Madgraph gives you as you follow the tutorial. Commands that you should type are indented.

At the Madgraph prompt, start by typing:

To simulate top + antitop production in proton + proton collisions at the LHC: The ">" separates the initial state from the final state. In the initial state, p = proton. In the Madgraph language, it is a multiparticle, which means it contains as partons the gluon (g) and light quarks (u, d, s, c) and light antiquarks (u~, d~, s~, c~). Madgraph automatically sums over all of these with the appropriate parton distribution function (PDF) weights. It uses the CTEQ6L1 set of PDFs. The "~" means antiparticle. In the final state, t is a top quark, and t~ is an antitop quark. Note that spaces are required between the particle names.

So far, Madgraph has calculated the Feynman diagrams for the partonic processes gluon+gluon > top+antitop and quark+antiquark > top+antitop. Now, to output these results so that they can be used by MadEvent, Pythia, and the detector simulators:

    output MY_FIRST_MG5_RUN
This will create a subdirectory called MY_FIRST_MG5_RUN (or any other name you choose) with all of the run information and events and plots in it. To check that it is really there, you can type:
    !ls -ltr MY_FIRST_MG5_RUN
which will show you the contents of that directory. Here the ! is an escape, allowing you to run commands outside of Madgraph. The full location is:
/xdata/$USER/madgraph/MY_FIRST_MG5_RUN .
Madgraph keeps different runs in different directories so that you can keep them without overwriting them. However, they tend to be very large files, so please do delete the process directories when you are sure you're done with them.

If Xwindows is working on your machine, you can inspect the parton-level Feynman diagrams for the process you've chosen. First, be sure to make sure you've closed any web browsers you have open, including this one (sorry). Then, type at the Madgraph prompt:

    open index.html
and click on "Process Information" in the left column. The next page will have a list of Feynman diagrams. You can click on the "html" link to see them.

Now we're ready to generate events:

    launch MY_FIRST_MG5_RUN
First, Madgraph will ask us which parts of the program we want to run. By default, it only runs Madevent, which generates some random events and is enough to generate a cross-section. By turning on the switches for Pythia, and PGS and/or Delphes, we can get fully simulated detector output. Experts in ATLAS might only run Pythia, and then use the Pythia output file in their own, ATLAS-specific, GEANT-based, detector simulator. As a theorist, I just use PGS or Delphes, which are fast and simple. Another nice thing about them is that they are seamlessly integrated with Madgraph; if you select them, they just run automatically.

We'll choose to run Pythia, PGS, and Delphes. When we're done turning on our choice of switches 1, 2, 3, then we choose 0 to say that we're ready to proceed. So we type:

Next, we are given an opportunity to edit the "card" files, which are input files controlling different aspects of the generation of events. Madgraph asks you to choose 1, 2, 3, 4, 5, or 9 to edit, respectively, param_card.dat, run_card.dat, pythia_card.dat, pgs_card.dat, delphes_card.dat, or plot_card.dat. The card files are stored in the directory /xdata/$USER/madgraph/MY_FIRST_MG5_RUN/Cards/ . More generally, of course, MY_FIRST_MG5_RUN would be replaced by whatever name you gave to the run. When you select one of the options 1, 2, 3, 4, 5, or 9, Madgraph will start an editor, which by default is pico.

Here is a brief discussion of what's in each card file:

  • The file param_card.dat contains information about the model we're working with. In param_card.dat, we could change, for example, the value of the top quark mass from its default value of 173.0 GeV to anything we wanted. Or we could change the Higgs mass from its default value of 125.0 GeV. These are parameters of the default model, which is the Standard Model. If we had earlier selected a different model instead, then the parameter card would contain additional parameters, such as the masses of extra particles that might be included in that model. Later, we'll go back and do another run where we change the model to the Minimal Supersymmetric Standard Model (MSSM) or the Standard Model with Higgs effective couplings (HEFT). Note that this would have been done at an earlier step.

  • The file run_card.dat is the one we would most often modify. It contains information about how many events we are asking for (default = 10000; you probably shouldn't choose this to be more than 40000), and the collider beam particles (usually proton, anti-proton, or electron or positron) and the beam energies (always in GeV). For experts, it also allows us to put kinematic contraints on the events before generating them. Constraints can also be imposed at a later stage in the analysis.

  • The file pythia_card.dat controls the running of pythia, which takes the final state partons and makes them into hadrons. The default is fine for almost everyone. I've never touched this. I don't recommend messing with it unless you are an expert.

  • The files pgs_card.dat and/or delphes_card.dat control the detector simulation. The defaults are usually good, and changing them is mostly for experts. Here you can adjust things like the resolutions for energy and momentum for your detector simulation's response to various particles. Other parameters you can change directly or indirectly, are: What is the magnetic field within the detector? What is the granularity of the calorimeters? How often is a jet that contains a b-quark detected as a b-jet? How often is a jet that contains a non-b-quark detected as a b-jet? How often is a tau lepton detected as a tau lepton? How often does a jet "fake" a lepton? How often does a jet "fake" a photon? etc.

  • The file plot_card.dat controls what plots you want made when the event generation is finished. We will just leave it at the default, which is to produce almost every possible plot.

  • There is another card that you aren't asked to edit: the process card, proc_card.dat. This card just has the information about the process that you already generated, so it is mostly there just for reference in case you forget what process you asked for.

    As an example, let's just edit the run_card.dat, so that we'll generate 5000 events at the LHC with center-of-mass energy 8 TeV, which was the energy of the last run. To do this, type

    at the prompt.
    Now on line 32 change "10000 = nevents" to "5000 = nevents",
    and on line 41 change "6500 = ebeam1" to "4000 = ebeam1",
    and on line 42 change "6500 = ebeam2" to "4000 = ebeam1".
    Energies and masses are always in GeV. Then save and quit the editor (control X if you are using pico).

    We won't edit any of the other cards this time, so now back at the Madgraph prompt, type:

    to signal that we are done. This also immediately starts the generation of events. Now you just wait...

    Looking at the results

    When the event generation and detector simulation are done, you will see something like:

    === Results Summary for run: run_01 tag: tag_1 ===

    Cross-section : 134.3 +- 0.339 pb
    Nb of events : 5000

    This confirms that you generated 5000 events, and tells you what the total cross-section was for the process or processes that you selected. Warning: don't take the uncertainty of +- 0.339 pb seriously. At best, this is statistical uncertainty only, and the systematic uncertainty is always much higher.

    When the Madgraph prompt returns, you are ready to look at the results of the run. Issue the command:

      open index.html
    and then click on "Results and Event Database". (Warning: Xwindows might be slow, so you might have to be patient here. If nothing happens, it might be because you left another browser window open. Close the open browser window and try the above command again.) On the Results page, in the Output column, you will see links to plots.

    Plots at parton level:

    First, click on the plots link in the row that is labelled "parton madevent". You should see a page with lots of histogram plots. The first one is a plot of weights, which is trivial; the weights are always just 1. The second plot is just a histogram of the number of top quarks. This is also trivial in this case, because every event you generated had exactly one top quark. The third plot is a histogram of the number of antitop quarks, which is also trivial for the same reason.

    The next plot, of "Ecm", the center of mass energy, of the partonic collision is more interesting. It should look something like this:


    Note that Ecm has to be at least twice the top quark mass, so greater than 2 * 173 = 346 GeV. The Ecm is usually not much more that that, however, because the probability to find a parton with a given energy decreases sharply with the energy. There is a long tail at higher energies.

    Scrolling farther down, "pt(t1)" and "pt(t~1)" are the momentum transverse to the beam direction for the top and antitop quarks respectively. The graph of the transverse momentum of the top quark should look something like this:


    We can see that it is peaked from about 50 to 100 GeV. The graph of the transverse momentum of the antitop quark looks identical. That's because they are produced back-to-back in the center-of-mass reference frame.

    The last plot is of "m(t1,t~1)" which is the invariant mass of the top+antitop pair. The invariant mass is the mass of a single particle that could have decayed to those two partons, even if no such particle exists. In real data, if you see a strong peak in m(i,j), it might mean that such a particle does exist, and you discovered it. For just two partons, (top and antitop here), the invariant mass is the same as the partonic center-of-mass energy. It therefore looks the same as the Ecm plot above, except it is produced with different axis scales.

    Plots at detector level, using DELPHES:

    Before looking at some of these, note that there are very similar plots produced by PGS, and by Pythia. You can compare them and try to figure out the differences, which are often very slight. They each reconstruct jets and other objects in different ways, so it is expected that they don't agree with each other perfectly. But, for brevity, let's stick to the DELPHES results only. The DELPHES detector simulator reconstructs "objects" in each event as the following:

  • jets (j)

  • b-tagged jets (b) for jets that are likely (but not certain!) to have contained a real bottom or antibottom quark. These are a subset of the jets.

  • Leptons of various types: e+, e-, mu+, mu-, tau+, tau-

  • Photons

  • Missing transverse energy (MET). This is the component of the momentum transverse to the beam that is not matched by visible particles. It could be due to neutrinos, to detector mismeasurements, or to new exotic particles that don't interact with the detector.

    For each event, the objects of a given type (other than MET) are numbered in order of decreasing transverse momentum, pT. Thus "j1" means the jet that has the largest pT, "j2" has the second-largest pT, etc. This also applies to the lists of b-jets, electrons, muons, taus, and photons.

    The histogram of the number of jets looks like:


    We see that the most probable number of jets as reconstructed by DELPHES is 4, but there could be 0 or as many as 10.

    For b-jets:


    In principle, there "should" be 2 b-jets in each event. However, often one or both of the b-jets is not tagged. The most likely number of b-tags turns out to be 1 in this process. Also, note that occasionally 3 jets are b-tagged, even though there "should" only be 2. That is partly because the detector simulator has a small mistagging probability built into it, just like in the real world. Another source of additional b-tags is that a parton can radiate off another bottom-antibottom pair when hadronization occurs in the final state.

    Here are the plots of the pT of j1 and j2, the leading and sub-leading jets:

    picture picture

    and the same for the leading and sub-leading b-jets:

    picture picture

    Here is the invariant mass m(b1,b2) of the leading two b-jets, b1 and b2:


    This may look like it has a broad peak-like structure. But, remember that a b-jet would not be reconstructed at all if the energy were too small. So that means that there can't be many events with small m(b1,b2). And, kinematics makes it unlikely also to have very energetic partons, so there can't be too many events with large m(b1,b2), either. So somewhere in between, there is a "peak". But this does not mean that some new particle decayed to b1 and b2 in these events! Separating real peaks from "fake" peaks is an important skill.

    Here is the histogram of the Missing ET:


    The MET has a large tail at high values. This is mostly due to the presence of neutrinos in the event. It is also partly due to mismeasurements of jet energies, which lead to "fake" missing energy.

    Finally, here is the histogram of the kinematic quantity HT, which is defined to be the sum of the pT's of all of the jets, leptons, and photons in the event, plus the Missing ET:


    This quantity is often taken as a measure of the overall mass scale of the event. If you produce heavy particles, they are more like to give events with large HT.

    By default, there are many other plots produced, including: pT's of every particle type, pseudo-rapidities of every particle type, invariant masses of every pair of particle type, distances and angles between pairs of particles.

    You can also analyze the output files from Pythia, PGS or Delphes to make your own plots of kinematic quantities of interest. That's an advanced topic that we won't go into in this class, but it is essential if you end up doing your own analyses later. You can find those output files, compressed by gzip, in the directory: /xdata/$USER/madgraph/MY_FIRST_MG5_RUN/Events/run_01 .

    To continue learning about the basic Madgraph capabilities, continue here: