whizard is hosted by Hepforge, IPPP Durham
Previous Up Next

Chapter 2  Getting Started

While the full details of WHIZARD’s capabilities are explained in the later chapters, a simple working example should give some flavor of the program.

2.1  Evaluating a total cross section

First of all, WHIZARD has to be installed on your computer. It is designed to run on UNIX systems and has been successfully tested on several Linux OS as well as MAC OS X. While many features it uses are standard nowadays (see Sec.3), some are not, and you should check first:

  • For the O’Mega matrix element generator you need the Objective Caml (O’Caml) language and compiler. See p.??.
  • You must have a Fortran compiler which supports the Fortran 95 standard.1

WHIZARD has been extensively tested only on Linux PC and Alpha (DEC/Compaq) systems; feedback for other platforms is welcome.

When these conditions are met, you should switch to an empty directory, e.g. whizard, and unpack the source there:

cd whizard
tar xzf whizard-1.xx.tgz

Next, the package has to be configured:


Inspect the output of configure and look for warnings and errors. It may happen that some environment variables have to be set so that the configure script can find all it is looking for (see Sec. 3.3.2). (Except for very old systems, WHIZARD compiles with the system Fortran 95 compiler, and on most operating system, O’Caml is also available as a package.)

After configuration, you have to choose the physics model and the processes you are interested in. You are free to specify an arbitrary list of scattering processes, which you write into the configuration file conf/whizard.prc. The file conf/whizard.prc.default is intended as a guideline: the processes listed there are just examples.

After this is done, the compilation procedure (see below) results in an executable named whizard. This will be an integration program and Monte-Carlo event generator for exactly those processes you have specified. So, in principle, there can be as many different WHIZARD versions as there are possible process lists.

To be specific, let us consider W pair production with a four-fermion final state:

e+ e → µνµud     (1)

The corresponding configuration file conf/whizard.prc reads

# The selected model
model   SM

# Processes
# Tag           In      Out             Method  Option
cc10            e1,E1   e2,N2,u,D       omega

The lines beginning with # signs are comments, so the only relevant information are the model definition (the Standard Model in this case) and the lines defining the processes. In the example, there is only one process definition. The particle names follow the CompHEP convention, but other conventions may be adopted as well. (You can find all definitions of particle properties and names, as well as the physics parameters of the selected model, in the corresponding model file located in the conf/models subdirectory. In the present case, this is SM.mdl.)

The keyword omega selects the O’Mega matrix element generator. Again, the current WHIZARD version comes in principle with three different matrix element generators one can choose from (O’Mega, MadGraph, and CompHEP). But note that the latter two would have to be enabled with corresponding configure options to be available.

Next, the following command makes the executable and installs it in the subdirectory named results:

make prg install

This runs fully automatically, but it will take some time: The O’Mega matrix element generator has to be compiled, then the process matrix element has to be constructed as a Fortran program and compiled, auxiliary programs have to be compiled as well, and so on. Finally, everything is linked into the single program named whizard.

The subdirectory results is self-contained: Along with the executable, the make scripts put there all necessary input files, so the contents of this directory may be moved anywhere else without affecting the functionality of the program.

The whizard executable is now a Monte-Carlo generator for the process (1). To run it, change into the results directory

cd results

and edit the input file whizard.in there. This file consists of several input blocks, each one beginning with a & keyword and terminated by a slash.2 The process ID ("cc10" in our case) and the total energy are specified in the first input block. Apart from this, we set the muon mass to zero3 but leave everything else empty for the moment:

 process_id = "cc10"
 sqrts = 500

 &integration_input /
 &simulation_input /
 &diagnostics_input /
 Mmu = 0 
 &beam_input /
 &beam_input /

When this is done, we can start the program:


On screen, WHIZARD will first display a header

 ! WHIZARD 1.97 (May 31 2011)
 ! Reading process data from file whizard.in
 ! Wrote whizard.out
 ! Process cc10:
 !    e a-e ->  mu a-nu_mu   u a-d
 !   32  16 ->   1       2   4   8

This states that, at the very beginning, an output file whizard.out is written. This file contains the full list of input parameters you have specified along with the default values chosen for the other parameters. Next, the process is listed. The codes below the particle names are binary codes which will become useful when cuts for kinematical variables are specified.

There follow several informational lines which you may ignore since the program takes care of all necessary steps by itself. Nevertheless, some explanation might be in order:

Before starting integration, WHIZARD constructs a phase-space setup. The program uses an adaptive multi-channel integration method. This involves the simultaneous use of multiple phase-space parameterizations (channels), which roughly correspond to dominant Feynman diagrams of the selected process. (Note that the absence of a channel only means that it is not taken into account for a specific phase space mapping, but the corresponding Feynman diagrams are nevertheless contained in the evaluated O’Mega amplitude.) Therefore, the physics model is taken into account:

 ! Reading vertices from file whizard.mdl ...
 ! Model file:       54 trilinear vertices found.
 ! Model file:       54 vertices usable for phase space setup.

The model file whizard.mdl is a copy of the original SM.mdl before; it contains a list of all vertices relevant for constructing phase space integration channels. Next, these channels are constructed:

 ! Generating phase space channels for process cc10...
 ! Phase space:       8 phase space channels generated.
 ! Scanning phase space channels for equivalences ...
 ! Phase space:       8 equivalence relations found.
 ! Note: This cross section may be infinite without cuts.
 ! Wrote default cut configuration file whizard.cc10.cut0
 ! Wrote phase space configurations to file whizard.phx

The resulting set of channels is written to a file whizard.phx which is in plain ASCII format. Furthermore, when constructing the phase space the program has found some indication that cuts might be needed, because the final state contains two massless quark jets. (Strictly speaking, in the present case of unequal quark flavors, this is unnecessary, but it is a standard choice.) The corresponding default cut on the dijet invariant mass is written into the file whizard.cc10.cut0 for informational purposes, and it will be used in the integration.

The weights of the channels will be adapted iteratively. Furthermore, each integration dimension is binned, and the location of bins (the grid) will also be iteratively adapted for each channel. In the present case, this amounts to

 ! Created grids:      8 channels,  8 dimensions with 20 bins

After these preliminaries, the program starts integration. It chooses 20,000 calls for each iteration of the adaptive iteration procedure, which takes some time to evaluate. Finally, the output looks like this:

 ! WHIZARD run for process cc10:
 ! It      Calls  Integral[fb]  Error[fb]   Err[%]    Acc  Eff[%]   Chi2 N[It]
 ! Reading cut configuration data from file whizard.cut1
 ! No cut data found for process cc10
 ! Using default cuts.
 cut M of   12      within  1.00000E+01  1.00000E+99
 ! Preparing (fixed weights):   1 sample of      20000 calls ...
    1      20000  2.8867607E+02  1.17E+01    4.05    5.73*  1.59    0.00   1
 ! Adapting (variable wgts.):  10 samples of      20000 calls ...
    2      20000  2.7061501E+02  1.03E+01    3.82    5.40*  1.69
    3      20000  2.7528866E+02  1.99E+00    0.72    1.02*  6.88
    4      20000  2.7296493E+02  1.55E+00    0.57    0.80* 12.27
    5      20000  2.7147754E+02  1.34E+00    0.49    0.70* 16.73
    6      20000  2.7038028E+02  1.29E+00    0.48    0.67* 16.04
    7      20000  2.7298452E+02  1.27E+00    0.46    0.66* 14.17
    8      20000  2.7065951E+02  1.26E+00    0.47    0.66  14.94
    9      20000  2.7150651E+02  1.25E+00    0.46    0.65* 14.46
   10      20000  2.6996907E+02  1.28E+00    0.47    0.67  11.30
   11      20000  2.6978351E+02  1.26E+00    0.47    0.66  13.35
 ! Integrating (fixed wgts.):   3 samples of      20000 calls ...
   12      60000  2.7082438E+02  7.23E-01    0.27    0.65  12.12    0.26   3

At the beginning of each integration pass, the kinematical cuts are read, which are either specified by the user in a cut definition file or, if this information is absent as in the present case, the default set of cuts is used. (The letter M stands for the invariant mass, while the code 12 stands for the quark pair – add the binary codes 4 [u] and 8 [d] to get 12.)

The next lines allow the user to follow the convergence of the integral during the adaptation procedure. For each iteration, the display shows the iteration index, the number of phase space points sampled, the total cross section estimate, and the error estimate: the absolute value, the relative percentage, and the relative error multiplied by the square root of the number of calls. The latter number should be of order one; in our example it is slightly below one in the final iterations.

During this procedure, the currently best result is always marked by an asterisk. Note that each integral estimate is independent of each other; no accumulated integrals are shown. In some iterations the accuracy apparently does not improve, but after 12 iterations the grid and weight adaptation has nevertheless reduced the error estimate for a single sample by a factor 5. The last column shows an estimate for the reweighting efficiency when generating actual Monte-Carlo events. Since we have not yet enabled event generation, it is for informational purpose only. Note that this number tends to be less stable than the integration error, but adapting the grids has nevertheless considerably improved this value.

The final result in the last row is evaluated by averaging three further iterations of 20,000 events each. The preceding results are discarded since (at early stages of the adaptation) they may be systematically off the correct result. The total cross section is thus estimated as

σtot = 270.82(72)  fb     (2)

There is also a χ2 value given which results from comparing the three independent samplings which make up the final integration step. If this value is much larger than 1, we should mistrust the error estimate. Here, the value 0.26 indicates a well-behaved result.

There are a few more lines in the output:

 ! Time estimate for generating 10000 unweighted events:    0h 00m 04s
 ! Summary (all processes):
 ! Process ID     Integral[fb]  Error[fb]   Err[%]        Frac[%]
   cc10           2.7082438E+02  7.23E-01    0.27         100.00
   sum            2.7082438E+02  7.23E-01    0.27         100.00
 ! Wrote whizard.out
 ! Integration complete.
 ! No event generation requested

The time estimate for event generation (see below) may be taken as a rough guideline, based on the previous reweighting efficiency estimate. Then, the result is repeated – if we had selected more than one process for integration, the individual cross sections would be summarized here. Finally, we get reminded that the input and output data have been saved in the file whizard.out. Actually, this file contains only the summary. The process-specific data are collected in the process-specific output file whizard.cc10.out.

2.2  Generating events

The results we have obtained can be used for event generation. Apart from the total cross section which is displayed on screen, the adaptive integration procedure produces a set of sampling grids, tailored to the given process and parameter set, which are written on disk and allow the generation of true Monte-Carlo events.

To this end, we restart the program (of course, we could have done it in a single step). We do not like to repeat the lengthy adaptation procedure, therefore we tell WHIZARD to reuse the grids. Furthermore, we specify a certain luminosity, say, 10 fb−1. The modified input file whizard.in looks like

 process_id = "cc10"
 sqrts = 500
 luminosity = 10

 read_grids = T
 &simulation_input /
 &diagnostics_input /
 Mmu = 0 
 &beam_input /
 &beam_input /

The output looks as before (recall that the results are now read from file), but after displaying the integral the program continues and generates the appropriate number of Monte-Carlo events:

 ! Reading analysis configuration data from file whizard.cut5
 ! No analysis data found for process cc10
 ! Event sample corresponds to luminosity [fb-1] =   9.999
 ! Event sample corresponds to       22344  weighted events
 ! Generating       2708 unweighted events ...

When this is finished, the program displays a summary:

 ! Event generation finished.
 ! Analysis results for process cc10:
 ! It      Events Integral[fb]  Error[fb]   Err[%]    Acc  Eff[%]   Chi2 N[It]
   13       2708  2.7082438E+02  5.20E+00    1.92    1.00 100.00
 ! Warning: Excess events:    5.1       (    0.19% )  | Maximal weight:  1.95

The integral is unchanged (by definition), but the given error is now the statistical error which corresponds to the size of the event sample (2708 events). The 100 % efficiency just tells us that there were no additional cuts in the event generation pass; if there were some, it would be the percentage of events that passed the cuts.

The excess events (the sum of all weights exceeding 1) are few enough that they can be safely ignored. Actually, the largest event weight was 1.95 which tells us that the reweighting efficiency estimate – the ratio of the average and the highest weight – has been slightly too optimistic. (In a Monte-Carlo approach of this complexity, it is impossible to calculate the highest possible event weight; it can only be approximated, and there is always a chance for fluctuations.)

2.3  Analyzing events

Clearly, such a run is not very useful without doing anything with the generated events. Fortunately, they have been written to file (in a compressed machine-dependent format) and can be reread in a subsequent run (again, we could also have done it in a single run).

We might like to investigate the distributions of the hadronic invariant mass near the W pole and of the muon energy in our event sample. To achieve this, we set up a file named whizard.cut5 (the file defining cuts – and histograms – for the 5th pass of the program). It could read

# Analysis configuration file for the process ee -> mu nu u d
process cc10
   histogram M of 12 within 70 90 nbin 20
   histogram E of  1 within 0 500 nbin 25

Again, the binary codes of the particles come into play. Recall that they are in the present example

  3216 1248

The muon is thus assigned the number 1, and the combination ud is assigned the number 12=4+8.

We have still to tell the program to reuse the previous event sample. In the input file, we change the block

  &simulation_input /


 read_events = T

and restart the program. In the output, the program now says

 ! Found  2 analysis configuration datasets

and shows two identical summaries, one for each dataset. However, it has also generated the required distributions. Those are in the file whizard.cc10.dat and can be inspected there:

 ! WHIZARD 1.97 (May 31 2011)
 ! Process cc10:
 !    e a-e ->  mu a-nu_mu   u a-d
 !   32  16 ->   1       2   4   8
 ! Analysis results for process cc10:
 ! Histograms:
 histogram M of  12     within  7.00000E+01  9.00000E+01  nbin   20
   70.5000000        5.00000000        2.23606798        0.00000000    
   71.5000000        13.0000000        3.60555128        0.00000000    
   72.5000000        10.0000000        3.16227766        0.00000000    
   73.5000000        17.0000000        4.12310563        0.00000000    

The first column shows the bin midpoints, the second column the number of events, and the third column the statistical error √nevt. The fourth column shows excess events if there are any.

The contents of this file can be displayed graphically by standard analysis packages. For convenience, WHIZARD is able to do this by itself, using a macro package for the MetaPost drawing program4. The simple command 5

make plots

will execute all necessary steps automatically. The result is a PostScript file called whizard-plots.ps. For the case at hand, the plots are shown here: As expected, the hadronic invariant mass concentrates around the W mass, while the muon energy shows a smooth distribution.

2.4  Further options

The above example covers only basic features of WHIZARD. Some further possibilities, which are explained in the subsequent chapters of this manual, are:

  • Evaluate and sum over arbitrary processes.
  • Change physical parameters (masses, couplings)
  • Calculate processes in the MSSM (or other BSM models)
  • Reweight matrix elements by user-defined functions.
  • Insert parton structure functions (hadron collider) from the LHAPDF (or alternatively PDFLIB), beamstrahlung/ISR (e+e collider), or the Weizsäcker-Williams approximation for photons.
  • Choose polarized beams.
  • Insert user-defined cuts.
  • Analyze the final-state polarization.
  • Mix several processes in event generation.
  • Fragment the full system including beam remnants using PYTHIA.
  • Fragment the final-state particles using JETSET.
  • Write events to file in ASCII or STDHEP format and analyze them by external programs.
  • [For historical reasons and cross-checks: use different matrix-element generators (CompHEP and MadGraph besides O’Mega).]

WHIZARD has been checked to work with recent versions of the g95, NAG, Lahey/Fujitsu, Portland (PGF) and Intel compilers (Intel/Linux) and the Compaq compiler (Alpha architecture). If you experience problems, first check the compiler version, since some compiler bugs may have been fixed only very recently. For more information about compilers confer http://projects.hepforge.org/whizard/compilers.html
This is the NAMELIST format as defined by the Fortran language standard.
Otherwise, the matrix element would contain the unphysical decay µ+νµud since the u and d quark masses are always zero.
The macro package is called gamelan and is included in the distribution. MetaPost must be available on the system; this is determined by configure when WHIZARD is installed.
Doing this the first time, this make, or make gml has to be issued in the main directory, so gamelan is compiled. Later, it also works in the results subdirectory where the files reside.

Previous Up Next