Installation

3	Installation

3.1

Sources

WHIZARD is Free Software and the sources can be obtained from

http://www-ttp.physik.uni-karlsruhe.de/whizard/

The command

gzip -cd whizard.tgz | tar xf -

will unpack the sources in the current working directory. After unpacking, the following subdirectories will exist:

doc: contains the manual
conf: contains the configuration file and default input files
kinds-src: contains the definition of the Fortran REAL kinds
chep-src: contains the CompHEP sources
mad-src: contains the MadGraph sources
helas-src: contains the HELAS library which is used by MadGraph
omega-src: contains files needed for running O'Mega together with WHIZARD; the actual O'Mega distribution is not part of the WHIZARD distribution
circe-src: contains the CIRCE beamstrahlung library
circe2-src: contains the CIRCE2 library
vamp-src: contains the VAMP integration library
gml-src: contains the gamelan sources which allow a graphical representation of WHIZARD results
whizard-src: contains the actual WHIZARD sources
bin: contains the scripts needed for running WHIZARD and, after compilation, the WHIZARD executable
lib: is created during compilation and holds the resulting program libraries which when linked make up the WHIZARD executable.
processes-src: is created during compilation and holds the source code for the generated matrix elements and corresponding Feynman graph pictures
results: contains the WHIZARD executable and input files after installation

3.2

Prerequisites

3.2.1

Necessary

The following programs must be available on the host system in order to successfully compile and run WHIZARD:

GNU Make: Required for compiling WHIZARD. The scripts in WHIZARD also make use of standard UNIX tools such as grep, sed, etc.
PERL 5: Matrix element generation (calling external programs) is controlled by PERL scripts.
Fortran 95: The programming language of the actual WHIZARD code. Be aware that some Fortran compilers, unfortunately, still have internal bugs that prevent successful compilation of WHIZARD.
Fortran 77: This is required only for interoperability with pre-compiled Fortran 77 libraries such as the CERNLIB. If this is not needed, a symlink to the Fortran 95 compiler should suffice.
C: The C compiler is needed by CompHEP.⁷
O'Mega: This program for automatic matrix element generation is available from
http://theorie.physik.uni-wuerzburg.de/~ohl/omega/
For the compilation of O'Mega you need a recent version of the interpreter/compiler of the Objective Caml programming language (a.k.a. O'Caml). This has become part of Linux distributions (e.g., SuSE), so it may already be installed on your system. Otherwise, or if the installed version is too old, you can get it from
http://pauillac.inria.fr/ocaml/
When installing O'Mega, you have to make either one (or both) of
make binormake opt
for the executables, and
make f95
for the run-time library. Note that O'Mega and WHIZARD have to be compiled by the same Fortran 95 compiler, and WHIZARD needs access to O'Mega executables, libraries and module information.

3.2.2

Optional

The following programs are not needed for compiling and running WHIZARD, but only for some additional features:

The STDHEP library for writing events in STDHEP format. This library is contained in the CERN library in pre-compiled version only. (Using it may require the corresponding Fortran77 runtime library, which is determined automatically by configure.)
The PDFLIB library from the CERN library (CERNLIB) which accounts for parton distribution functions. (Using it may require the corresponding Fortran77 runtime library, which is determined automatically by configure.)
PYTHIA can be used for decaying and hadronizing the events generated by WHIZARD. If the PYTHIA library is present on the host system, it will be called for that purpose from inside WHIZARD, so no external interface is needed. The library is contained in the CERN library in pre-compiled version. (Using it may require the corresponding Fortran77 runtime library, which is determined automatically by configure.)
L^AT_EX for typesetting the documentation (including this manual)
H^EV^EA for making the HTML version of the manual
MetaPost for on-line generation of histogram and data plots
noweb for weaving the program sources.
autoconf for creating a configure script in the restricted bundle.

3.2.3

Included

The following programs are included in the WHIZARD distribution and need not be obtained separately. The URLs below should be inspected for the documentation, references, and license conditions:

CompHEP:
http://theory.npi.msu.su/comphep/
The CompHEP version which is included in WHIZARD is completely out-of-date (version 3.2.18), but has an additional Fortran 95 interface. It is kept mainly for the possibility of generating spin-summed matrix element for simple processes, which the other methods (which use helicity amplitudes) cannot provide as efficiently. Furthermore, with CompHEP the definition of new models is straightforward and does not require programming.
MadGraph/HELAS:
http://www-pheno.physics.wisc.edu/Software/MadGraph(old version)http://madgraph.physics.uiuc.edu(new version)
Again, only the old version with a modified Fortran 95 interface is currently supported by WHIZARD.
CIRCE and CIRCE2
http://heplix.ikp.physik.tu-darmstadt.de/lc/beam.html
with an additional WHIZARD interface.
VAMP by Thorsten Ohl

It should be stressed that the current CompHEP and MadGraph versions are much more powerful than the versions included within the WHIZARD distribution and are full-fledged event generators by themselves.

3.3

Configuration

Running the configure script

./configure

will check the availability of programs and utilities and generate the Makefiles appropriate for the host system. At the end of the configuration, a summary of the available/enabled and unavailable/disabled features is printed.

If desired, configure can be re-run. This is useful if you change environment variables or configure options (see below). If you would like to make the changes active and you have already made or run the WHIZARD executable, it may be necessary to do a make clean before you redo make prg or similar.

If you only wish to re-generate the Makefiles without changing anything else, you can run config.status. You may also use the command

make distclean

in order to remove everything including the files whizard.prc and whizard.in and thus restore the original status of the package.

3.3.1

Configure options

According to the standard, the available options to configure can be viewed by typing

./configure --help

However, although this prints a long list of standard options, none of them are relevant except for the ones which enable or disable parts of the WHIZARD package. If you wish to disable a module, type

./configure --disable-MODULE

where MODULE is the tag of one of the modules in the list below. There can be multiple disable options in the command line. Conversely, the command

./configure --enable-MODULE

will configure WHIZARD with module MODULE enabled.

Here is the list of modules that can be switched on or off in this way:

Module	Tag	Purpose	Enabled by default
`CompHEP`	`chep`	Matrix elements	yes
`MadGraph`	`mad`	Matrix elements	yes
`O'Mega`	`omega`	Matrix elements	yes
`CIRCE`	`circe`	Beamstrahlung	yes
`CIRCE`2	`circe2`	Beamstrahlung	yes
`ISAJET`	`isajet`	SUSY parameters	no
`PDFLIB`	`pdflib`	Parton structure functions	yes
`PYTHIA`	`pythia`	Fragmentation and hadronization	yes
`STDHEP`	`stdhep`	Binary event files for further processing	yes
`MetaPost`	`metapost`	PostScript Histograms	yes

The ISAJET interface is superseded by the standard Les Houches Accord interface.

3.3.2

Configure environment

The following environment variables are recognized by configure. They need to be set only if configure cannot find a program or library, or if a choice different from the default one is desired. Path and program names should be specified absolute, not relative to the working directory.

GMAKE:: GNU Make.
F95:: The Fortran 95 compiler. (The alias F90 also works.)
F95FLAGS:: Flags to be passed to the Fortran 95 compiler. (The alias F95FLAGS also works.)
F77:: The Fortran 77 compiler. This is needed for correctly linking precompiled Fortran 77 libraries (see below). By default, configure looks first for g77, then f77, then f2c. If the libraries have been compiled by a different compiler, set F77 appropriately (e.g., F77=f77 if g77 is present, but f77 has been used for compiling the libraries).
FFLAGS:: Flags to be passed to the Fortran 77 compiler.
PERL:: The PERL executable.
TMPDIR:: Directory where temporary files are stored. By default, /tmp is used.
OMEGA_DIR:: The directory where O'Mega is installed (optional). If O'Mega is disabled or the O'Mega binaries are missing on the host system, WHIZARD can still be used with CompHEP and MadGraph matrix elements only.
CERNLIB_DIR:: The directory where the precompiled (F77) CERN libraries reside (optional). This includes the STDHEP, PDFLIB and PYTHIA libraries together with auxiliary libraries. If necessary, individual environment variables STDHEP_DIR, PDFLIB_DIR and PYTHIA_DIR can be used to override the setting of CERNLIB_DIR. If CERNLIB_DIR is not set, /cern/pro/lib is assumed.
NOWEB_DIR:: Directory where the notangle, noweave, cpif executables reside (optional). With these programs the Fortran 95 sources and a documented program listing can be (re-)generated from the ultimate source whizard.nw.
GTAR:: GNU tar (optional).
PRECISION:: Set this to quadruple if quadruple precision code is desired. This will be applied to all parts of the program and may result in a considerable increase in execution time. Obviously, this works only if the Fortran compiler supports quadruple precision.
CHEP_MAXDIAG:: Maximum number of diagrams contained in one CompHEP-generated file. If there are more diagrams, files will be split. A value too large may lead to memory overflow for particular compilers. Default value: 100.

Instead of specifying configure options and environment variables on the command line, they may be defined in the script config.site which is executed each time configure is run.

3.3.3

Test runs

After configuration is complete, one can test if the whole system works by executing

make test

This will set up several Standard Model processes using all activated matrix element generators, compile the whole package and start the program for the process e⁺e^--> n_e^_n_e H in the Standard Model (in up to three versions of the same process, but compiled by different generators). With the parameter set taken from the default input file, this should result in equal cross sections for all activated matrix elements, about 85 fb each.⁸ Finally, a small sample of 100 events is generated and, if the PYTHIA module is activated, fragmented by JETSET.

While the above test is more like a demo, there are actually self-tests provided that check whether the results obtained with the three different matrix-element generators actually agree. Currently, the possibilities are

make test-QED make test-QCD make test-SM make test-MSSM

Only the SM test should report a few disagreements. These come from the fact that currently O'Mega does not couple the Higgs to muons or strange quarks, while Madgraph does not treat Higgs pairs correctly. The MSSM test currently has just O'Mega matrix elements, since the built-in CompHEP and MadGraph versions do not support the MSSM. However, the results can be compared with the numbers in the appendix of [11].

3.3.4

Cleanup

Unnecessary intermediate files will be removed if you say

make clean

If the process configuration file is modified to hold a new list of processes for the same or a different physics model, new make calls will remake the system as needed, so under normal circumstances no files have to be deleted explicitly. If you are not sure about the current status, you may remove the process-dependent files by

make proclean

To do a thorough cleanup, type

make realclean

This will also remove the CompHEP and MadGraph executables used for generating matrix elements, recovering the state just after configuration.

Finally,

make distclean

removes also the files resulting from configuration, thus recovering the initial state of the package as it comes in the distribution. Note that this also deletes some files which you may have edited yourself: whizard.prc and whizard.in in the conf directory, the input files in the results directory, and the file user.f90 in the whizard-src directory, so save them elsewhere if you do not want to lose their contents. After make distclean has been executed, you have to run configure before any further make command can be executed.

For further options, see the comments in the header of the master Makefile.