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. While many features it uses are
standard nowadays (see Sec.3), some are not, and you
should check first:
-
The O'Mega matrix element generator should be installed, which in
turn needs the Objective Caml language and compiler. See
p.??.
- You must have a Fortran compiler which supports the Fortran 95
standard.2
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
gzip -cd whizard.tgz | tar xf -
Next, the package has to be configured:
./configure
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).
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:
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. The current WHIZARD version comes with
three different matrix element generators you can choose from
(O'Mega, MadGraph, and CompHEP).
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 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.3 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
zero4 but leave everything else empty for the
moment:
&process_input
process_id = "cc10"
sqrts = 500
/
&integration_input /
&simulation_input /
&diagnostics_input /
¶meter_input
Mmu = 0
/
&beam_input /
&beam_input /
When this is done, we can start the program:
./whizard
On screen, WHIZARD will first display a header
! WHIZARD 1.30 (Sep 20 2004)
! 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. Therefore, the
physics model is taken into account:
! Reading vertices from file whizard.mdl ...
! Model file: 48 vertices found.
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: 2 phase space channels generated.
! Scanning phase space channels for equivalences ...
! Phase space: 2 equivalence relations found.
! Warning: The 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
it 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: 2 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.6828066E+02 6.17E+00 2.30 3.25* 0.96 0.00 1
!-----------------------------------------------------------------------------
! Adapting (variable wgts.): 10 samples of 20000 calls ...
2 20000 2.7700821E+02 5.84E+00 2.11 2.98* 2.03
3 20000 2.6888325E+02 1.72E+00 0.64 0.91* 4.55
4 20000 2.6916491E+02 1.49E+00 0.55 0.78* 4.16
5 20000 2.7159055E+02 1.91E+00 0.70 0.99 1.93
6 20000 2.7006872E+02 1.61E+00 0.60 0.84 4.38
7 20000 2.7435582E+02 1.38E+00 0.50 0.71* 4.80
8 20000 2.7090569E+02 1.23E+00 0.45 0.64* 7.63
9 20000 2.7182660E+02 1.24E+00 0.46 0.64 9.37
10 20000 2.7080780E+02 1.17E+00 0.43 0.61* 8.66
11 20000 2.7167616E+02 1.30E+00 0.48 0.68 4.47
!-----------------------------------------------------------------------------
! Integrating (fixed wgts.): 3 samples of 20000 calls ...
12 60000 2.7259737E+02 6.92E-01 0.25 0.62 7.82 0.24 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
stot = 272.60(69) fb
(2)
There is also a c2 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.24 indicates a well-behaved result.
There are a few more lines in the output:
!
! Time estimate for generating 10000 unweighted events: 0h 00m 54s
!=============================================================================
! Total cross section summary (all processes):
!-----------------------------------------------------------------------------
! Process ID Integral[fb] Error[fb] Err[%] Eff[%] Chi2
!-----------------------------------------------------------------------------
cc10 2.7259737E+02 6.92E-01 0.25 7.82 0.24
!-----------------------------------------------------------------------------
sum 2.7259737E+02 6.92E-01 0.25 7.82
!=============================================================================
! Wrote whizard.out
! Integration complete.
! No event generation requested
! WHIZARD run finished.
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.
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_input
process_id = "cc10"
sqrts = 500
luminosity = 10
/
&integration_input
read_grids = T
/
&simulation_input /
&diagnostics_input /
¶meter_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] = 10.00
! Event sample corresponds to 34859 weighted events
! Generating 2726 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 2726 2.7259737E+02 5.22E+00 1.92 1.00 100.00
!-----------------------------------------------------------------------------
! Warning: Excess events: 0.1 ( 0.01% ) | Maximal weight: 1.12
! There were no errors and 3 warning(s).
! WHIZARD run finished.
The integral is unchanged (by definition), but the given error is now
the statistical error which corresponds to the size of the event
sample (2726 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.12 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.)
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
and
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
|
|
| e- |
e+ |
-> |
µ- |
|
u |
|
| 32 |
16 |
|
1 |
2 |
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 /
to
&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.30 (Sep 20 2004)
! 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 9.00000000 3.00000000 0.00000000
71.5000000 13.0000000 3.60555128 0.00000000
72.5000000 8.00000000 2.82842712 0.00000000
73.5000000 14.0000000 3.74165739 0.00000000
...
The first column shows the bin midpoints, the second column the number
of events, and the third column the statistical error nevt1/2. 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
program5. The
simple command
make plots
will execute all necessary steps automatically.6 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.
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.
- Use different matrix-element generators (CompHEP, MadGraph,
O'Mega).
- Calculate processes in the MSSM.
- Reweight matrix elements by user-defined functions.
- Change physical parameters (masses, couplings)
- Insert parton structure functions (hadron collider) from the 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 final-state particles using JETSET.
- Fragment the full system including beam remnants using PYTHIA.
- Write events to file in ASCII or STDHEP format and analyze them by
external programs.