Chapter 3  Installation

• Sources
• Prerequisites
• Configuration

3.1  Sources

WHIZARD is Free Software (under the GPL Gnu Public License) and the sources can be obtained from

http://projects.hepforge.org/whizard

or alternatively from

http://whizard.event-generator.org

The command

tar xzf whizard-1.xx.tgz

will unpack the sources in the current working directory (note that the tarball does not generate a new 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

omega-src

contains the O’Mega distribution, the default matrix element generator of WHIZARD

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.

include

contains after compilation the Fortran include files and files containing the parameters of the model in use

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

fmf-src

contains the L^AT_EX macros for drawing Feynman diagrams

config.scripts

contains maintenance scripts

[chep-src

contains the CompHEP sources]

[mad-src

contains the MadGraph sources]

[helas-src

contains the HELAS library which is used by MadGraph]

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 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. Meanwhile, the gfortran shipped with the gcc bundle compiles WHIZARDfrom version 4.3 on (which is the oldest compiler version still supported by gcc).
• 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.
• O’Caml Objective Caml programming language: this is needed for the compilation of O’Mega in a recent version (3.04 or newer). This has become part of of most (if not all) Linux distributions. Otherwise, you can get it from

  http://pauillac.inria.fr/ocaml/

3.2.2  Optional

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

• The LHAPDF library for parton distribution functions. The package can be found here http://projects.hepforge.org/lhapdf. Although it is not mandatory, it is highly recommended to compile LHAPDF with the same Fortran95 compiler as WHIZARD, because otherwise you might need to link compiler libraries into the WHIZARD binary.
• 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.) Alternatively, if you do not want to rely on the CERNLIB, you could get the STDHEP library from here http://cepa.fnal.gov/psm/stdhep/getStdHep.shtml.
• 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.) Although this is still supported within WHIZARD 1, it is considered to be deprecated, and one should use LHAPDF instead.

  When you still want to use this feature, and there is a precompiled version on your system (e.g. compiled with f77 or g77), then you probably need to include FCFLAGS=-lg2c. Furthermore, you might need to compile the file f77_files.f in the whizard-src directory with the command <your f95 compiler> -c f77_files.f and include the object file in the following line in the file bin/whizard.ld:
  OBJ="$* processes-src/*.o whizard-src/f77_files.o".

• 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.) Important: Note that the WHIZARD 1 configure setup only supports the PYTHIA library as it is contained in the CERNLIB, using a version compiled by yourself might lead to the need to modify several configure options or Makefiles.
• L^AT_EX for typesetting the documentation (including this manual) Note that the cleanest and most complete way to get L^AT_EXis to install the TeXLive bundle.
• H^EV^EA for making the HTML version of the manual
• MetaPost for on-line generation of histogram and data plots. This is again contained in the TeXLive bundle.
• noweb for weaving the program sources.
• autoconf for creating a configure script in the restricted bundle.

3.2.3  Independent components

WHIZARD contains the following four sub-programs which are basically independent programs by themselves, but have been agreed upon by their authors to be merged into the WHIZARD bundle from version 1.90 on. This has been done in WHIZARD version 1.90 and the 1.9x distribution series by just attaching the code of these tools to the WHIZARD main core, while in WHIZARD 2 the sub-components have been recovered as completely, self-configurable and independently maintainable tools.

The four tools discussed above are

• O’Mega  the matrix element generator. This program is now steered also via the WHIZARD HepForge page http://www.hepforge.org/downloads/whizard. Note that only the O’Mega versions up to 0.xx are compatible with WHIZARD 1.xx. The newer versions carrying the same version number as WHIZARD 2.x.x have been designed and modified to work with WHIZARD 2 only. Again, only for WHIZARD up to version 1.51 a separate download of O’Mega is necessary, from 1.90 on the matrix element generator is included in the WHIZARD tarball.
• CIRCE and CIRCE2 (for lepton collider beam spectra and photon collider spectra) are now steered from the WHIZARD HepForge page as well, http://www.hepforge.org/downloads/whizard. They have been re-named there as CIRCE1 and CIRCE2, respectively. CIRCE itself has been included into WHIZARD from the very beginning, while CIRCE2 is part of the distribution since version 1.28. Both programs have been attached with an additional WHIZARD interface, which has been modernized and updated in WHIZARD 2.
• VAMP is the multi-channel adaptive integration routine of WHIZARD  which has been part of the WHIZARD core since the very beginning of the program. It is now as well steered via the WHIZARD HepForge page http://www.hepforge.org/downloads/whizard.

3.2.4  Alternative matrix element generators

The following two matrix element generators in modified versions 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://comphep.sinp.msu.ru

  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://madgraph.physics.uiuc.edu

  Again, only a very old version from the MadGraph 3 release series with a modified Fortran 95 interface is supported by WHIZARD. Especially, the version attached to the WHIZARD distribution does not contain any Higgs self couplings.

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:

There are a few more configure options that might be relevant, but are not sub-packages to be disabled or enabled. The most interesting option for the user, --enable-quadruple allows to use quadruple precision, if the compiler supports this (like e.g. the standard gfortram). As a default it is switched off. Note that in some earlier WHIZARD versions this was set by means of an environment flag (cf. next subsection), but has been changed into a configure option lately. The option --enable-fc-profiling is only intended for profiling monitoring for developpers, while the option |--enable-fc-impure would trigger a compilation of the O’Mega libraries with non-pure and non-elemental functions. This allows to use print statements in the matrix elements for debugging.

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.

FC:

The Fortran 90/95 compiler. (The aliases F95,F90 also work.)

FCFLAGS:

Flags to be passed to the Fortran 90/95 compiler. (The aliases F95FLAGS, F90FLAGS also work.)

F77:

The Fortran 77 compiler. This is needed for correctly linking precompiled Fortran 77 libraries (see below). It is highly recommended to use whenever possible the same compiler for the Fortran 95 and Fortran 77 code.

FFLAGS:

Flags to be passed to the Fortran 77 compiler.

PERL:

The PERL executable.

LIBS:

Libraries to pass to the linker, e.g. -l<library>.

USERLIBS:

To link additional libraries before the default ones.

SYSTEMLIBS:

To link additional libraries after the default ones.

LDFLAGS:

linker flags, e.g. -L<lib dir> if you have libraries in a nonstandard directory <lib dir>.

TMPDIR:

Directory where temporary files are stored. By default, /tmp is used.

LHAPDF_DIR:

The directory where the LHAPDF library resides. We strongly advice to compile LHAPDF with the same Fortran 90/95 compiler used for the compilation of WHIZARD.

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).

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.

There are a few more environment variables like CC, CFLAGS, CPP, CPPFLAGS concerning the C compiler, precompiler and their corresponding flags. As this is only relevant for compiling CompHEP we do not mention these flags here any further³.

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 a Standard Model standard candle process using all activated matrix element generators, i.e. per default O’Mega, compile the whole package and start the program for the process e⁺e⁻→ ν_eν_e H in the Standard Model (in up to three versions of the same process, but compiled by different generators if CompHEP or MadGraph are enabled.). 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

Note that the selftests compare the string expressions of the program output for the three different matrix element generators. As the numerical routines are slightly different, the results may deviate from each other and hence produce a fake failure of the self test. Just have a look at the numbers. Only the SM test should report a few real 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 [12].

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.

1

A C compiler is needed by CompHEP. The compiler and compiler flags are set in chep-src/unix_com/CC.

2

Note that when you have noweb installed on your system, make distclean will erase all Fortran90 files in the directory whizard-src including user.f90. This will lead after re-configuration and doing make prg install again to the error message make[1]: *** No rule to make target ‘user.f90’,needed by ‘.depend’. Stop.. In that case, just copy user.f90.default to user.f90 and repeat make prg install.

3

There is also CHEP_MAXDIAG, the 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.

4

If, for the selected Fortran compiler, command-line arguments are not supported, the program will just display the list of processes and exit.