CalcHEP reference
Here is the CalcHEP batch mode reference. You should find description for every possible parameter the batch mode accepts except if it is redundant with some HEPMDB function.
This document is organised as follows: entries concerning similar or close information are gathered together. Each subsection is a parameter name. Sometimes only the main parameter is in the subsection title but the other sub-parameters are described in the same subsection.
Contents
Model information
Model
This line corresponds to the model used. When using HEPMDB, each batch file is associated with a specific model. As a consequence, the value of this line should not be changed.
Gauge
CalcHEP is able to use two different gauges for computation: Feynman gauge and unitary gauge. Some models require a specific gauge. CalcHEP is better suited to in Feynman gauge, as such it is the default setting. It is recommended that this should not be changed.
Model changed
Each time the batch interface is run, it checks initially whether or not the sub-process numerical code exists. If it does, CalcHEP reuses the code and skips the often long process of code generation. If the code does not already exist, the numerical code is then generated and added to the library. If the model is changed, the numerical codes are regenerated as appropriate.
Process description
Process
Using the process keyword, it is possible to specify which process to compute. Multiple processes can be required. The general syntax is:
This is in the form: incoming particles -> outgoing particles. Particles can be particles from the model you are using or composite particles. It is recommended that the number of outgoing particles does not exceed 6.
Decay
It is possible to specify decays for the outgoing particles. Each decay will be written as follow:
Decays will automatically be connected to outgoing particles if possible. Decays will even be connected with one another.
Important note: make sure the same decay does not appear twice.
Composite
When specifying processes and decays, you can use composite particles, i.e. labels that refer to various possible particles. This is particularly useful when colliding protons or when studying jets.
The syntax is:
Remove
Sometimes, only specific processes will be of interest. It is possible to tell CalcHEP which particle you do not want as virtual particles in the processes. The syntax is:
To remove a particular decay, the syntax is:
Beam description
pdf1/pdf2
The parton density functions of incoming protons can be specified with pdf1 and pdf2. A list of the typical pdfs can be found in the comments of the template batch file, however the main pdfs and corresponding parameters are described here. For the LHC, the standard pdf setting is:
The default setting is None.
It is also possible to set pdfs for electron-positron beams. The ISR & Beamstrahlung setting is exclusive to electron-positron collisions. For these processes, the beam parameters may be specified, the default values are:
If the Equiv. Photon setting is chosen, then the photon particle and maximum Q value must be specified. The defaults are:
If Proton Photon is chosen, then the following parameters must be specified:
p1/p2
These two parameters define the energies of the beams in GeV. When using pdf, it can also be used as an input parameter for the pdf. For instance, when using proton photon, this would corresponds to the energy of the initial proton.
Model parameters
Parameter
It is possible to change some parameters of a model using Parameter keyword. The parameters are model specific, any parameters unspecified here will be read from the default values of the model. Here is an example for selecting the elementary charge in the Standard Model:
Run parameter
It is usual for a model to have some free parameters not completely fixed by experiment. For that kind of situation, you have the possibility to run several times the same computation with a different value for a specific parameter.
In order to use this possibility, you have to write four consecutive lines. The first one specifies which parameter to study. To study the Higgs mass using the Standard Model, you would write:
Then you must specify the initial value and the increase of the value between each run:
Finally, the number of steps is defined by:
In this specific example, you will get 6 runs using the following value for the Higgs mass: 100, 110, 120, 130, 140, 150.
It is possible to mark several parameters for running. But it is only possible to explore hyperrectangle in the parameter space.
QCD parameters
alpha Q
There are a number of QCD parameters that can be included in the batch file, however they need not all be included and most can be commented out. The main parameter to change is the QCD scale, specified in terms of the invariant mass of the final state particles. For example, in a process with two final state particles, the QCD scale would be defined as:
It may also be specified by a formula in terms of a parameter of the model, for example, to make the QCD scale half the value of the Higgs mass in the Standard Model:
So far this parameter has been applied to all final state particles. For events with a larger number of final state particles, different values of the QCD scale can be set for different sets of particles. This is done with the addition of a double colon specifying which process this is applied to.
Cuts
Cuts can be implemented on the final state particles to avoid unwanted values appearing in the calculation. In order to specify the cut of a certain value, there are four parameters that must always be present.
Although all phrases must be present, they do not all have to contain a value. As with the QDC scale, these parameters can be applied to a single process by :n: and to all processes by a single colon. Standard CalcHEP notation is used for all of these specifications, except for Cut invert, which must be True or False. In most cases, it is set to False. Several parameter cuts may be applied to a process at once.
Kinematics and regularization
Kinematics
In this part of the batch file the user needs to specify which kinematics are needed. The numbers in the kinematics refer to the particles in the process in order. For example, 12 relates to the first and second particles in the process. Here is an example of some kinematics:
To set the kinematics to the CalcHEP default, comment out all kinematics lines, the default settings will be applied automatically.
Regularization momentum
Applying regularization means that the phase space is adjusted so that resonances are properly accounted for. Applying regularization will mean that the result is far more accurate.
There are four lines needed in the batch file for each resonance. They are:
The Regularization momentum refers to the final state particles, using standard CalHEP notation, for example ' : 34'.
Regularization can be applied for as many resonances as needed, and can be specified for different processes by :n:. In order to add regularization to the decay processes, include the word Decay to the beginning of each key phrase.
Events
Number of events (per run step)
This is totally up to the user and what they wish to calculate. Please note that this number of events are being created for each run step. The number of events can be set to zero, in which case the cross sections and distributions are determined, but no events are produced. If events are not needed, set this to 0.
Filename
This is self-explanatory. All files produced will be given the name specified.
NTuple
This only works when the nt_maker has been installed in the bin directory. NTuple determines whether PAW ntuples have been created. The default is False, we recommend keeping it in this setting.
Cleanup
This determines whether the individual files will be deleted once the final event file has been created, in order to save space on the hard drive. The default setting is True. If you would like to keep the individual event files, set:
Parallelization
Parallelization method
There are several parallelization methods which determine whether the calculation is run on a local computer or on a pbs cluster. The default mode is Local, which is recommended.
For larger calculations, it may be better to select pbs for the method. In this case, there are several parameters that must be present, however they can be left empty.
The Que specifies which pbs que to submit the jobs to. Walltime specifies the maximum runtime of the calculation, after this amount of time the job will be killed. Memory specifies the maximum amount of memory the jobs can use in G, once this memory is exceeded the job will be killed. email specifies the address to send an email in the event of a prematurely killed job.
There are a few parameters that must be set regardless of which method is chosen. These are, in default settings:
Max number of cpus
The maximum number of cpus depends on the computer/cluster you are about to run this batch file on. Typically, this value is 4, 8 or 12.
sleep time
The sleep time specifies the amount of time in seconds that the batch file waits to check the submitted jobs and update the html progress reports. If the job submitted is very large, this should be set very high (e.g tens of minutes).
nice level
The nice level sets the priority of the job if several jobs are running at once. This can be set between 0 and 19, where 19 is the lowest priority. Unless it is certain that the job won't disturb others, then it should be kept at the 'nicest' level, i.e the lowest priority.
Vegas session
nSess_1/2
This defines the number of Vegas sessions the batch will run. Normally, 5 should suffice.
nCalls_1/2
This gives the number of calls in each session. A typical value would be 100,000.
