CalcHEP tutorial

Jump to: navigation, search

In order to familiarise yourself with CalcHEP, we will study two examples, one sightly more complicated than the other. Hopefully, by the end of this tutorial, you will be able to use the majority of the functions of CalcHEP.

Please note that this is not a reference manual. If you wish to look at the reference manual, it is available here.

A simple leptonic process

Let's start with a simple process and try to compute the matrix elements using CalcHEP. In this section, we will study:

ee → μμττ

The process will be studied in the standard model framework.

Preparing HEPMDB

First, connect to HEPMDB and go to the Calculate section. In the left panel, under CalcHEP, check whether the Standard Model (CKM=1) line appears. If not, in the File menu, choose Import a model. When you find the line Standard Model (CKM=1) for CalcHEP (it should be model 43), select it and click Select. The model should now be accessible in your environment.

This model is the complete standard model without the CKM matrix. As a consequence, it is lighter and in situations where quark flavours don't matter, it gives the same results as the standard model.

A template batch file

Select the model and select Edit Batch File in the Selection menu. A new window will appear. You will be able to edit the batch file which is the file describing the process of interest. Click on the button Import Full Template.

You now have a template file with nearly every possible field already offered. You also have help in the comments. The comments are lines beginning with a #. They are ignored by CalcHEP and thanks to them, you can add any information you want for anybody reading the batch file.

Model information

The first three fields are information about the model.

  1. The first line states the model to be used. You should not touch it as this specifies the model in the CalcHEP local batch mode. There is no default for this setting so this line must be included. The model name should be exactly as it appears in the model selection menu.
  2. The second option is Model changed. This tells CalcHEP whether the model files have been changed or not.
  3. Finally, Gauge specifies which gauge is used, Feynman or unitary. Many models are built implicitly assuming that the gauge is Feynman's, so you should not change this field either.

Defining the process

We have several lines to define our process. Remove every Process, Decay and Composite field. You can now write:

Process: e,E -> m,M,l,L

In the standard model of CalcHEP, e refers to electrons, m to muons, l to taus and the capital letters to their anti-particle. The list of particle names and symbols to use can be viewed by selecting View Particles in the Selection drop-down menu. You cannot access it while editing the batch file however.

So we have set up an electron-positron scattering with a pair of muons and a pair of taus outgoing. No further information is needed to describe the process itself.

However, it is also possible to define decays e.g
Decay: h -> A,A
for the decay of the Higgs boson to two photons.

As well as exclude particles from the calculation e.g
Remove: b
to remove any processes involving bottom quarks.

Beams configuration

We now have to configure the beams. The next field is about the pdfs. While this is useful for protons or any composite particle scattering, we do not need it for electron-positron scattering. We can write:

pdf1: OFF

And the same thing for the second pdf.

Concerning the energy of the beam, let's set 100 GeV beams.

p1: 100
p2: 100

Changing model parameters

We now have the possibility to change some model parameters. Let's say you want to change the strength of the electromagnetic force. You would write:

Parameter: EE=0.31

with 0.31 being the new value of the electrical charge of the electron in natural units. Some models are more flexible than others on that kind of point. But for our tutorial, we are not going to change the well known parameters.

Instead, we're going to scan the possible Higgs masses. For this, you can write:

Run parameter: Mh
Run begin: 100
Run step size: 10
Run n steps: 6

This means we're going to scan the following values for Mh: 100 Gev, 110 GeV, 120 GeV, 130 GeV, 140 GeV, 150 GeV. This is of course a pretty useful possibility when studying a new model.

We then have the possibility to set some parameters about QCD but this will be studied in the next example.


Various cuts are possible. For our simple tutorial, we are not going to study them. Please refer to the reference manual if you are interested in them.

Kinematics and regularization

To tell CalcHEP how to handle the phase space, you should fill the kinematic information. Using this information, a nice parameterisation of the phase space is used.

In our case, the two incoming particles will give two bosons, each of them decaying into a lepton pair. Hence, our kinematics are written as:

Kinematics : 12 -> 34, 56
Kinematics : 34 -> 3 , 4
Kinematics : 56 -> 5 , 6

where the numbers refer to the particle in the process, in this case, 1 and 2 are the electron and positron, 3 and 4 are the muons etc.

To improve the precision of the computation, it is important to tell CalcHEP where the resonances are. In our case, we have a resonance on the dimuon and ditau masses for the Z boson and for the Higgs. So we will write:

Regularization momentum: 34
Regularization mass: MZ
Regularization width: wZ
Regularization power: 2

Regularization momentum: 34
Regularization mass: Mh
Regularization width: wh
Regularization power: 2

Regularization momentum: 56
Regularization mass: MZ
Regularization width: wZ
Regularization power: 2

Regularization momentum: 56
Regularization mass: Mh
Regularization width: wh
Regularization power: 2

Event generation

For event generation, we really have two main parameters:

  1. The number of events. We'll write: Number of events (per run step): 100000
  2. The output file name. Filename: tutorial_ee_mmll


When using the template file of HEPMDB, all parallelization parameters are good.

In order for the processes to run quickly and efficiently, it is recommended to set:

Max number of cpus: 24

This runs two processes on each of the 12 cores. Setting a higher number of cpus will overload the cluster, and the job will be killed.

For very large jobs, set:

Max number of cpus: 12

Vegas session

Finally, the Vegas session has some parameters. It will be used to compute the cross-section and to prepare the grid for event generation. Two sessions with 5 calls of 100,000 points is usually sufficient. With the number of calls there is a trade-off; the higher the number of calls means it will take longer to run the batch file on HEPMDB but reducing the number of calls leads to a decrease in accuracy of the cross sections. It is therefore worth experimenting with a couple of points in the batch interface of CalcHEP to see what optimization can be made.

nSess_1: 5
nCalls_1: 100000
nSess_2: 5
nCalls_2: 100000

Final words

The batch file is now complete and ready to run. Click Save Changes and return to the Selection drop-down menu, where you should select Run Batch File.

You can check the progress of your batch file by selecting Check Job Progress from the File drop-down menu, and a progress report will appear in the box at the bottom of the window. You can either click Cancel job to end the current job, or you can click Show Start to receive information on the estimated start time for the job (the time till it will reach the top of the queue and start running) and estimated finish time.

Involving partons

For a more complex interaction involving partons, we study the collision of protons to create a specified final state. To make this easier to understand, we will look at the example given in the template batch file, and explain each section and its relevance. Hence we study:

p,p → W,b,B

This investigates the interaction of two protons on the parton level to create a W boson (without specifying positive or negative charge), a bottom quark and its anti-quark. Again this process is in the Standard Model framework.

Model Information

The batch file should be loaded according to the instructions in the previous example. Again the gauge should be set to Feynman, and Model Changed set to False. This tells the batch file that the model files have not been altered.

Defining the process

For this process, all of the definitions available in this section of the batch file need to be included. First, specify the main process.

Process: p,p → W,b,B

As the W boson is a gauge boson, we need to include a decay mode of this particle. We will look at its decay to an unspecified charged lepton and its corresponding neutrino. To do this, new variable names need to be input, we will use le for any charged lepton, and n for any neutrino. The decay is written as follows:

Decay: W → le,n

Almost all of the particles we have introduced are composites, i.e they represent several particles that can be involved in this particular type of interaction. When the batch file is run it calculates all possible processes for every combination of these particles, so it is important to include all composites. We write:

Composite: p=u,U,d,D,s,S,c,C,b,B,G
Composite: W=W+,W-
Composite: le=e,E,m,M
Composite: n=ne,Ne,nm,Nm

There is also the possibility that there will be a quark/gluon jet in the final state, so this must also be added to the Composite decriptions:

Composite: jet=u,U,d,D,s,S,c,C,b,B,G

These are all of the necessary descriptions of the process itself.

Beam Configuration and PDFs

As this process involves partons inside the colliding protons, a Parton Density Function must be specified for each proton. This affects the cross section results, and is necessary to include for all parton-level processes. There are several choices for the PDFs, we will use:

pdf1: cteq61 (proton)
pdf2: cteq61 (proton)

The remaining lines of this section are commented out because they are not necessary for this computation, so it is best to ignore them.

In Momentum Info for this process we will set the energy of the beams to match that of the most recent LHC energy, so each beam is set to 6500GeV.

p1: 6500
p2: 6500

Model Parameters

Next we can change the model parameters, but for this example we will keep them as the default model values.

We will again scan over the Higgs masses, as in the previous example. The batch template gives the following values, but you are free to alter these to suit your needs.

Run parameter: Mh
Run begin: 120
Run step size: 5
Run n steps: 3

The QCD running info gives the strong coupling at the energy scale of the interaction, which we must define in terms of the bottom and anti-bottom quarks. This is done by writing:

alpha Q : M45

This again means that it is in terms of the 4th and 5th particles of the interactions, in this case b,B, as required. All other parts of this section can remain commented out.

Cut Information

There are several cuts that should be applied to this process. This is to avoid including divergences in the cross section calculations. The cuts only apply to the production processes, and not to the products of the decay. The template batch file has provided the cuts necessary for this process, but we should understand what they mean. The first is:

Cut parameter: M(b,B)
Cut invert: False
Cut min: 100
Cut max:

This means that there is a cut applied to the invariant mass of the bottom and anti-bottom quarks, where the minimum is taken at M(b,B)=100GeV. This is to avoid the low energy divergence that occurs below this invariant mass value. The next is:

Cut parameter: J(jet,jet)
Cut invert: False
Cut min: 0.5
Cut max:

This enforces a cut on the jet cone angle, or the minimum angle of a resulting jet in the production. Then we have:

Cut parameter: T(jet)
Cut invert: False
Cut min: 20
Cut max:

This defines the cut on the transverse momentum of the production jet to be greater than 20GeV.

Cut parameter: N(jet)
Cut invert: False
Cut min: -2.5
Cut max: 2.5

The final cut is to the pseudorapidity of the jet, this informs the range of the angle between the direction of emission of the jet and the x-y plane.

Each of these parameters are applied to the entire process by use of the colon. To specify a process for the cut : should be changed to :n:, where n is the process number at which to apply the cut. In this case it is fine to have all cuts apply to all processes.

Kinematics and Regularization

As before, the kinematical information is required in order to tell CalcHEP how to handle the phase space. Again, these can be commented out so that the default settings are used, however the kinematics required are:

Kinematics : 12 -> 3, 45
Kinematics : 45 -> 4 , 5

The first line represents the overall process of particles 1 and 2 combining to form particles 3, 4 and 5, where 4 and 5 are a combination of the bottom and anti-bottom quarks. The second line tells CalcHEP that these quarks then separate into the individual particles.

The regularization information must be in terms of the final state particles, in this case we want the momentum in terms of the quarks (particles 4 and 5) and the mass and width in terms of the Higgs properties. We also want this to apply only to the production process, and not the decay, using :1:. We specify the regularization as:

Regularization momentum:1: 45
Regularization mass:1: Mh
Regularization width:1: wh
Regularization power:1: 2

The regularization power should always be kept as squared.

Remaining Information

The rest of the batch file is explained in the previous example, and we use the same settings as before for Events Generation, Parallelization, Vegas and Event Generator.

Run the File

The batch file is now ready to run, set it running as instructed in the previous example. To check the progress of the job and whether it has finished, select the Check Job Progress option.