Notes on Madgraph syntax and examples for NIU PHYS 474/790

You can find these notes online at You can also review how to start Madgraph at, and notes on the tutorial are here: .

Adding another process

Often, one wants to combine more than one process in the same event sample. For example, you can do combined top and bottom production:

Note that if you do another "generate", it will just overwrite the first generate. That's why you have to do "add process" instead.

Now you can output the resulting combined processes:

and launch:
    launch MY_SECOND_RUN

The resulting events generated will be correctly weighted according to their individual cross-sections. This time we will only be interested in the cross-sections, and not want to look at plots of kinematic variables. So we won't run Pythia, or either of the detector simulators. So when Madgraph asks what switches you want to turn on, you say

which means none. Madgraph will now give you the option of editing the parameter card, the run card, or the plot card. We'll just be looking at the total cross-section, so we just need a very quick run. So let's edit the run card to only ask for 1000 events. Type
and then change "10000" to "1000" on line 32. Save the file, and then type
to start the run.

When Madgraph is finished, you should see that the cross-section is something like 4.41e+08 pb, which is huge! To see the individual contributions, you can type:

    open index.html
and click on "Results and Event Database". If you click on the cross-section number link, it will bring up a page that lists all of the individual partonic subprocesses, and how much they contributed. You can see that almost all of the cross-section is due to gluon+gluon > bottom+antibottom.

Putting cuts at generator level

Part of the reason the huge bottom+antibottom cross-section happened is because of very "soft" (low-pT) bottom quarks, and from soft gluons splitting into bottom-antibottom pairs. In many cases, you will not be interested in such events anyway, and they will be cut out later at the analysis stage. To avoid them, go back to the Madgraph interactive terminal window and type

    launch MY_SECOND_RUN
again. Again, type:
But this time, we will further edit the run card. On line 106, you will see:
0 = ptb
which means that no cut is being imposed on the transverse momentum of the bottom or the antibottom. Change this to:
25 = ptb
so that we are imposing a generator-level cut that the transverse momentum of each bottom or antibottom parton has to be at least 25 GeV. Further down, you will see on line 132:
-1 = etab
Change this to:
5 = etab
so that |eta| has to be at most 5, in other words not too close to the beampipe. Finally, a little further down, on line 144, change:
0 = drbb
0.4 = drbb
to impose a cut that deltaR has to be at least 0.4 for the bottom-antibottom pair, so that they can be clearly distinguished in the detector. These cuts are somewhat redundant with each other, but give us a chance to see how to implement them. Now save and quit from the editor, and type
to start the run.

This time, you should see a cross-section of something like 1.34e+06 pb, so more than a factor of 300 smaller. It is still dominated by the bottom-antibottom process, simply because the bottom quark is so mugh lighter than the top quark.

The cuts we have put in above are at "generator level". Their main purpose is to avoid having Madgraph waste time generating events that we are just going to cut later anyway. You can impose similar cuts on ordinary (non-b) jets, leptons, and photons, by making similar edits in the run_card.dat. Cuts can also be imposed after the events have passed through the detector simulator, which is how they would be imposed on real data.


In principle, you can add as many processes as you want, say like:

    generate p p > u u~
    add process p p > d d~
    add process p p > s s~
    add process p p > c c~
    add process p p > g g~
all of which would produce events with two jets. However, this can get tedious, so it is better to use multiparticles, a built-in Madgraph features.

You may have noticed that when you started up Madgraph, it said something like:

"Defined multiparticle p = g u c d s u~ c~ d~ s~
Defined multiparticle j = g u c d s u~ c~ d~ s~
Defined multiparticle l+ = e+ mu+
Defined multiparticle l- = e- mu-
Defined multiparticle vl = ve vm vt
Defined multiparticle vl~ = ve~ vm~ vt~
Defined multiparticle all = g u c d s u~ c~ d~ s~ a ve vm vt e- mu- ve~ vm~ vt~ e+ mu+ t b t~ b~ z w+ h w- ta- ta+"

The multiparticle "p" is the proton, which we've already used. The jet multiparticle "j" means to sum over all of the same gluon, quark, and antiquark partons, but in the final state. The multiparticle "l-" means to sum over electrons and muons, and the multiparticle "l+" means to sum over their antiparticles. The multiparticles "vl" and "vl~" are for all neutrinos and anti-neutrinos. You can also define your own multiparticles for convenience, for example:

    define k = g u u~ c c~ d d~ s s~ b b~
would define a multiparticle similar to j, but that also includes bottom and antibottom.

So you can do things like:

    generate p p > j j
which will generate the same thing as the previous combination. You can also generate all 3-jets events, like this:
    generate p p > j j j
etc. When you get up to 4 or 5 or more jets, Madgraph can take a very long time to run.

Jet matching

However, there is a tricky point here. If you do this:

    generate p p > j j
    add process p p > j j j
you will actually be double-counting events. This is because when Pythia does the parton shower and hadronization of the 2-jet final state, it will automatically produce some additional jets, which would be partially redundant with the 3-jet events. To avoid this is an advanced topic; you need to "match" the two samples. If you need to become an expert on this, start at these links:

The same issue arises, for example, in top quark production. This is fine:

    generate p p > t t~ j
(usually with a cut on the pT of the extra jet, imposed in the run_card.dat file) but doing this:
    generate p p > t t~
    add process p p > t t~ j
requires that you understand the jet matching procedure to avoid double-counting.

How to put restrictions on decays

Sometimes you might be interested in only a subset of events with special properties, like events that have leptons in them. Here's an example. Suppose you want to produce a W boson at the LHC. The command would be:

    generate p p > W+
But perhaps you only care about the subset of events where the W boson decays to an antimuon and a muon neutrino. The command would be:
    generate p p > W+, W+ > mu+ vm
This tells Madgraph that it should only produce, and only calculate the cross-section for, events in which the W decays to a muon. You can also use multiparticles with this syntax (but only for the final particle in the decay, not the decaying particles). So, for example, you could generate events where a W is produced with a jet, and then the jet decays to a lepton:
    generate p p > W+ j, W+ > l+ vl
This sort of thing is useful because the decays to jets have huge backgrounds compared to the decays to leptons. You don't want to have Madgraph waste time producing a bunch of events that you are just going to ignore anyway.

Here's a more complicated example involving a decay chain:

    generate p p > t t~, (t > W+ b, W+ > j j), (t~ > W- b~, W- > l- vl~)
This tells Madgraph to produce a top+antitop pair, but only keep events where the top decays to a W and a bottom (which it almost always does anyway), and where the antitop decays to a W and a bottom with the W decaying leptonically.

We'll do another example later when we discuss the Higgs decay to two photons. In general, the restrictions on decays are most useful when the decays involved are both important to the signal you are trying to observe and relatively rare.

How to require the presence or absence of particles in Feynman diagrams

Sometimes you might want to exclude Feynman diagrams that contain a particular particle. For example, suppose you wanted to generate a sample of electron + positron production, but you wanted to exclude any Feynman diagrams that contain a Z boson. You could do this by:

    generate p p > e+ e- / Z
The "/ Z" means to exclude a Feynman diagram if it has a Z boson in it. You can also exclude a particle from appearing in the s-channel, by
    generate p p > e+ e- $ Z
Finally, you can include only those Feynman diagrams in which a certain particle is present in the s-channel, for example by
    generate p p > Z > e+ e-
Each of these should be used with care, because they can result in violating gauge invariance or unitarity if you aren't careful.

Other examples of Madgraph syntax can be found here:
Beware of Madgraph 4 syntax; it often doesn't work in Madgraph 5.

Importing new models

One of the main uses of Madgraph is to study hypothetical particles that can exist in theories like supersymmetry, which is an extension of the Standard Model. It has a bunch of new particles, with new interactions. To include them, you need to import the information about the model into Madgraph. Madgraph comes with several different versions of supersymmetry, including mssm (the Minimal Supersymmetric Standard Model). If you want to do something with supersymmetry, first make your own copy of the model directory that contains all of the particle mass and coupling information. Before starting Madgraph, you would do this:

    cd /xdata/$USER/madgraph/models
    cp -rfvp mssm mssm_$USER
    cd /xdata/$USER/madgraph

Now when you start Madgraph, you can do:

    import model mssm_$USER
This replaces the default model ("sm", the Standard Model).

In supersymmetry, there is a particle called the gluino, with symbol "go". So, for example, to simulate the production of a pair of gluinos, you would do:

    generate p p > go go
There are a lot of other particles in the mssm too. To use this model, you would want to be able to change the masses of the supersymmetric particles. (The default for the gluino mass, for example, is set at 607 GeV, which is ruled out now.) Unfortunately, at the moment this seems to require registration at the Madgraph web site to use a tool they have online for producing a parameter_card.dat for this model. You can also modify the default parameter_card.dat file by hand, but this is tricky and dangerous.

Choosing your plots

By default, Madgraph produces a lot of plots that may not be very interesting. Conversely, it may not produce some plots that you might want, or it might produce them with axes that don't have the appropriate scale, or histogram bin sizes that are too large or too small. You can modify the plot_card.dat to customize the plots. Here's an example.

Let's do muon + antimuon production at the LHC. We would start with:

    generate p p > mu+ mu-
    output MUON_PROD
    launch MUON_PROD
We will want to see the plots of the invariant mass of the mu+ mu- pair first at parton level, and then from Delphes at detector level. So we select switches according to:
Now select
to edit the plot card. This will allow us to choose what plots we want. There are some instructions inside the file. In this case, we want to add a new "class" of particles for the muons. After line 83, insert a new line:

mu 13 -13 #Class number 3

Here, 13 and -13 are the Particle Data Group codes for a muon and antimuon respectively.

Now, starting on line 128 is the list of plots that Madgraph will produce. In this example, we don't care about any of them; we only want to make a plot of the invariant mass of the muon+antimuon pair. So, delete all of the lines between "Begin PlotDefs" and "End PlotDefs". In their place, put just one line that reads

mij 3 2

This tells Madgraph that we want to plot the invariant masses of all pairs in class 3 (muons), up to the first 2 (ordered by pT).

Finally, you will see lines sandwiched between "Begin PlotRange" and "End PlotRange". Change the mij entry to read

mij 4 0 200

This means that we want histogram bins that are 4 GeV wide, and we want the axis to go from 0 to 200 GeV. Now, save the file and exit, and start the run. When done, inspect the invariant mass plot. You should be able to pick out the Z boson mass peak. Here's what it looks like at parton level (Madevent output):


and here's what it looks like after the events have been through the detector simulator Delphes:


Next: A look at Higgs production.