WHIZARD is hosted by Hepforge, IPPP Durham
Previous Up Next

Chapter 2  Installation

2.1  Package Structure

WHIZARD is a software package that consists of a main executable program (which is called whizard), libraries, auxiliary executable programs, and machine-independent data files. The whole package can be installed by the system administrator, by default, on a central location in the file system (/usr/local with its proper subdirectories). Alternatively, it is possible to install it in a user’s home directory, without administrator privileges, or at any other location.

A WHIZARD run requires a workspace, i.e., a writable directory where it can put generated code and data. There are no constraints on the location of this directory, but we recommend to use a separate directory for each WHIZARD project, or even for each WHIZARD run.

Since WHIZARD generates the matrix elements for scattering and decay processes in form of Fortran code that is automatically compiled and dynamically linked into the running program, it requires a working Fortran compiler not just for the installation, but also at runtime.

The previous major version WHIZARD1 did put more constraints on the setup. In a nutshell, not just the matrix element code was compiled at runtime, but other parts of the program as well, so the whole package was interleaved and had to be installed in user space. The workflow was controlled by make and PERL scripts. These constraints are gone in the present version in favor of a clean separation of installation and runtime workspace.

2.2  Prerequisites

2.2.1  No Binary Distribution

WHIZARD is currently not distributed as a binary package, nor is it available as a debian or RPM package. This might change in the future. However, compiling from source is very simple (see below). Since the package needs a compiler also at runtime, it would not work without some development tools installed on the machine, anyway.

Note, however, that we support an install script, that downloads all necessary prerequisites, and does the configuration and compilation described below automatically. This is called the “instant WHIZARD” and is accessible through the WHIZARD webpage from version 2.1.1 on: http://whizard.hepforge.org/versions/install/install-whizard-2.X.X.sh. Download this shell script, make it executable by

  chmod +x install-whizard-2.X.X.sh

and execute it. Note that this also involves compilation of the required Fortran compiler which takes 1-3 hours depending on your system. Darwin operating systems (a.k.a. as Mac OS X) have a very similar general system for all sorts of software, called MacPorts (http://www.macports.org). This offers to install WHIZARD as one of its software ports, and is very similar to “instant WHIZARD” described above.

2.2.2  Tarball Distribution

This is the recommended way of obtaining WHIZARD. You may download the current stable distribution from the WHIZARD webpage, hosted at the HepForge webpage

http://whizard.hepforge.org

The distribution is a single file, say whizard-2.5.0.tgz for version 2.5.0.

You need the additional prerequisites:

  • GNU tar (or gunzip and tar) for unpacking the tarball.
  • The make utility. Other standard Unix utilities (sed, grep, etc.) are usually installed by default.
  • A modern Fortran compiler (see Sec. 2.2.4 for details).
  • The OCaml system. OCaml is a functional and object-oriented language. Version 3.12 or later is required to compile all components of WHIZARD. The package is freely available either as a debian/RPM package on your system (it might be necessary to install it from the usual repositories), or you can obtain it directly from
    http://caml.inria.fr
    and install it yourself. If desired, the package can be installed in user space without administrator privileges1.

The following optional external packages are not required, but used for certain purposes. Make sure to check whether you will need any of them, before you install WHIZARD.

  • LATEX and MetaPost for data visualization. Both are part of the TEX program family. These programs are not absolutely necessary, but WHIZARD will lack the tools for visualization without them.
  • The LHAPDF structure-function library. See Sec. 2.2.5.
  • The HOPPET structure-function matching tool. See Sec. 2.2.6.
  • The HepMC event-format package. See Sec. 2.2.7.
  • The FastJet jet-algorithm package. See Sec. 2.2.9.
  • The LCIO event-format package. See Sec. 2.2.11.

Until version v2.2.7 of WHIZARD, the event-format package STDHEP used to be available as an external package. As their distribution is frozen with the final version v5.06.01, and it used to be notoriously difficult to compile and link STDHEP into WHIZARD, it was decided to include STDHEP into WHIZARD. This is the case from version v2.2.8 of WHIZARD on. Linking against an external version of STDHEP is precluded from there on. Nevertheless, we list some explanations in Sec. 2.2.10. Once these prerequisites are met, you may unpack the package in a directory of your choice

some-directory> tar xzf whizard-2.5.0.tgz

and proceed.2

For using external physics models that are directly supported by WHIZARD and O’Mega, the user can use tools like SARAH or FeynRules. There installation and linking to WHIZARD will be explained in Chap. 17. Besides this, also new models can be conveniently included via UFO files, which will be explained as well in that chapter.

The directory will then contain a subdirectory whizard-2.5.0 where the complete source tree is located. To update later to a new version, repeat these steps. Each new version will unpack in a separate directory with the appropriate name.

2.2.3  SVN Repository Version

If you want to install the latest development version, you have to check it out from the WHIZARD SVN repository.

In addition to the prerequisites listed in the previous section, you need:

  • The subversion package (svn), the tool for dealing with SVN repositories.
  • The autoconf package, part of the autotools development system.
  • The noweb package, a light-weight tool for literate programming. This package is nowadays often part of Linux distributions3. You can obtain the source code from4
    http://www.cs.tufts.edu/~nr/noweb/

To start, go to a directory of your choice and execute

  your-src-directory> svn checkout http://whizard.hepforge.org/svn/trunk/ .

The SVN source tree will appear in the current directory. To update later, you just have to execute

  your-src-directory> svn update

within that directory.

After checking out the sources, you first have to create configure.ac by executing the shell script build_master.sh. Afterwards, run5

  your-src-directory> autoreconf

This will generate a configure script.

2.2.4  Fortran Compilers

WHIZARD is written in modern Fortran. To be precise, it uses a subset of the Fortran2003 standard. At the time of this writing, this subset is supported by, at least, the following compilers:

  • gfortran (GNU, Open Source). You will need version 4.8.0 or higher6. We recommend to use at least version 4.8.4 or 4.9.4, as especially the the early version of 4.8.X and 4.9.X experience some severe bugs.
  • nagfor (NAG). You will need version 6.0 or higher.
  • ifort (Intel). You will need version 16.0.0 or higher. Unfortunately, versions 17.0.0, 17.0.1 and 17.0.2 show a severe regression and cannot be used.

There are some commercial compilers that might be able to compile WHIZARD 2.4 in the near future, but at the time of writing, all of the compilers listed below contained compiler bugs. Consult the WHIZARD website for updates on this situation.

  • pgfortran (PGI). You will need a more modern version than 17.1.
  • ekopath. You will need a more modern version than 4.0.

2.2.5  LHAPDF

For computing scattering processes at hadron colliders such as the LHC, WHIZARD has a small set of standard structure-function parameterizations built in, cf. Sec. 5.5.4. For many applications, this will be sufficient, and you can skip this section.

However, if you need structure-function parameterizations that are not in the default set (e.g. PDF error sets), you can use the LHAPDF structure-function library, which is an external package. It has to be linked during WHIZARD installation. For use with WHIZARD, version 5.3.0 or higher of the library is required7. The LHAPDF package has undergone a major rewriting from Fortran version 5 to C++ version 6. While still maintaining the interface for the LHAPDF version 5 series, from version 2.2.2 of WHIZARD on, the new release series of LHAPDF, version 6.0 and higher, is also supported.

If LHAPDF is not yet installed on your system, you can download it from

http://lhapdf.hepforge.org

for the most recent LHAPDF version 6 and newer, or

http://lhapdf.hepforge.org/lhapdf5

for version 5 and older, and install it. The website contains comprehensive documentation on the configuring and installation procedure. Make sure that you have downloaded and installed not just the package, but also the data sets. Note that LHAPDF version 5 needs both a Fortran and a C++ compiler.

During WHIZARD configuration, WHIZARD looks for the script lhapdf (which is present in LHAPDF series 6) first, and then for lhapdf-config (which is present since LHAPDF version 4.1.0): if those are in an executable path (or only the latter for LHAPDF version 5), the environment variables for LHAPDF are automatically recognized by WHIZARD, as well as the version number. This should look like this in the configure output (for LHAPDF version 6 or newer),

   configure: --------------------------------------------------------------
   configure: --- LHAPDF ---
   configure:
   checking for lhapdf... /usr/local/bin/lhapdf
   checking for lhapdf-config... /usr/local/bin/lhapdf-config
   checking the LHAPDF version... 6.1.6
   checking the major version... 6
   checking the LHAPDF pdfsets path... /usr/local/share/LHAPDF
   checking the standard PDF sets...  all standard PDF sets installed
   checking if LHAPDF is functional (may take a while)... yes
   checking LHAPDF... yes
   configure: --------------------------------------------------------------

while for LHAPDF version 5 and older it looks like this:

   configure: --------------------------------------------------------------
   configure: --- LHAPDF ---
   configure: 
   checking for lhapdf... no
   checking for lhapdf-config... /usr/local/bin/lhapdf-config
   checking the LHAPDF version... 5.9.1
   checking the major version... 5
   checking the LHAPDF pdfsets path... /usr/local/share/lhapdf/PDFsets
   checking the standard PDF sets...  all standard PDF sets installed
   checking for getxminm in -lLHAPDF... yes
   checking for has_photon in -lLHAPDF... yes
   configure: --------------------------------------------------------------

If you want to use a different LHAPDF (e.g. because the one installed on your system by default is an older one), the preferred way to do so is to put the lhapdf (and/or lhapdf-config) scripts in an executable path that is checked before the system paths, e.g. <home>/bin.

For the old series, LHAPDF version 5, a possible error could arise if LHAPDF had been compiled with a different Fortran compiler than WHIZARD, and if the run-time library of that Fortran compiler had not been included in the WHIZARD configure process. The output then looks like this:

   configure: --------------------------------------------------------------
   configure: --- LHAPDF ---
   configure:
   checking for lhapdf... no
   checking for lhapdf-config... /usr/local/bin/lhapdf-config
   checking the LHAPDF version... 5.9.1
   checking the major version... 5
   checking the LHAPDF pdfsets path... /usr/local/share/lhapdf/PDFsets
   checking for standard PDF sets... all standard PDF sets installed
   checking for getxminm in -lLHAPDF... no
   checking for has_photon in -lLHAPDF... no
   configure: --------------------------------------------------------------

So, the WHIZARD configure found the LHAPDF distribution, but could not link because it could not resolve the symbols inside the library. In case of failure, for more details confer the config.log.

If LHAPDF is installed in a non-default directory where WHIZARD would not find it, set the environment variable LHAPDF_DIR to the correct installation path when configuring WHIZARD.

The check for the standard PDF sets are those sets that are used in the default WHIZARD self tests in the case LHAPDF is enabled and correctly linked. If some of them are missing, then this test will result in a failure. They are the CT10 set for LHAPDF version 6 (for version 5, cteq61.LHpdf, cteq6ll.LHpdf, cteq5l.LHgrid, and GSG961.LHgrid are demanded). If you want to use LHAPDF inside WHIZARD please install them such that WHIZARD could perform all its sanity checks with them. The last check is for the has_photon flag, which tests whether photon PDFs are available in the found LHAPDF installation.

2.2.6  HOPPET

HOPPET (not Hobbit) is a tool for the QCD DGLAP evolution of PDFs for hadron colliders. It provides possibilities for matching algorithms for 4- and 5-flavor schemes, that are important for precision simulations of b-parton initiated processes at hadron colliders. If you are not interested in those features, you can skip this section. Note that this feature is not enabled by default (unlike e.g. LHAPDF), but has to be explicitly during the configuration (see below):

  your-build-directory> your-src-directory/configure --enable-hoppet

If you configure messages like the following:

configure: --------------------------------------------------------------
configure: --- HOPPET ---
configure: 
checking for hoppet-config... /usr/local/bin/hoppet-config
checking for hoppetAssign in -lhoppet_v1... yes
configure: --------------------------------------------------------------

then you know that HOPPET has been found and was correctly linked. If that is not the case, you have to specify the location of the HOPPET library, e.g. by adding

  HOPPET=<hoppet\_directory>/lib

to the configure options above. For more details, please confer the HOPPET manual.

2.2.7  HepMC

HepMC is a C++ class library for handling collider scattering events. In particular, it provides a portable format for event files. If you want to use this format, you should link WHIZARD with HepMC, otherwise you can skip this section.

If it is not already installed on your system, you may obtain HepMC from one of these two webpages:

http://lcgapp.cern.ch/project/simu/HepMC/

or

https://sft.its.cern.ch/jira/browse/HEPMC

If the HepMC library is linked with the installation, WHIZARD is able to read and write files in the HepMC format.

Detailed information on the installation and usage can be found on the HepMC homepage. We give here only some brief details relevant for the usage with WHIZARD: For the compilation of HepMC one needs a C++ compiler. Then the procedure is the same as for the WHIZARD package, namely configure HepMC:

  configure --with-momentum=GEV --with-length=MM --prefix=<install dir> 

Note that the particle momentum and decay length flags are mandatory, and we highly recommend to set them to the values GEV and MM, respectively. After configuration, do make, an optional make check (which might sometimes fail for non-standard values of momentum and length), and finally make install.

A WHIZARD configuration for HepMC looks like this:

   configure: --------------------------------------------------------------
   configure: --- HepMC ---
   configure:
   checking the HepMC version... 2.06.09
   checking for GenEvent class in -lHepMC... yes
   configure: --------------------------------------------------------------    
  

If HepMC is installed in a non-default directory where WHIZARD would not find it, set the environment variable HEPMC_DIR to the correct installation path when configuring WHIZARD. Furthermore, the environment variable CXXFLAGS allows you to set specific C/C++ preprocessor flags, e.g. non-standard include paths for header files.

2.2.8  PYTHIA8

NOTE: This is at the moment not yet supported, but merely a stub with the only purpose to be recognized by the build system.

PYTHIA8 is a C++ class library for handling hadronization, showering and underlying event. If you want to use this feature (once it is fully supported in WHIZARD), you should link WHIZARD with PYTHIA8, otherwise you can skip this section.

If it is not already installed on your system, you may obtain PYTHIA8 from

http://home.thep.lu.se/~torbjorn/Pythia.html

If the PYTHIA8 library is linked with the installation, WHIZARD will be able to use its hadronization and showering, once this is fully supported within WHIZARD.

To link a PYTHIA8 installation to WHIZARD, you should specify the flag

--enable-pythia8

to configure. If PYTHIA8 is installed in a non-default directory where WHIZARD would not find it, specify also

--with-pythia8=<your-pythia8-installation-path>

A successful WHIZARD configuration should produce a screen output similar to this:

configure: --------------------------------------------------------------
configure: --- SHOWERS PYTHIA6 PYTHIA8 MPI ---
configure: 
[....]
checking for pythia8-config... /usr/local/bin/pythia8-config
checking if PYTHIA8 is functional... yes
checking PYTHIA8... yes
configure: WARNING: PYTHIA8 configure is for testing purposes at the moment.
configure: --------------------------------------------------------------

2.2.9  FastJet

NOTE: This is an experimental feature.

FastJet is a C++ class library for handling jet clustering. If you want to use this feature, you should link WHIZARD with FastJet, otherwise you can skip this section.

If it is not already installed on your system, you may obtain FastJet from

http://fastjet.fr

If the FastJet library is linked with the installation, WHIZARD is able to call the jet algorithms provided by this program for the purposes of applying cuts and analysis.

To link a FastJet installation to WHIZARD, you should specify the flag

--enable-fastjet

to configure. If FastJet is installed in a non-default directory where WHIZARD would not find it, specify also

--with-fastjet=<your-fastjet-installation-path>

A successful WHIZARD configuration should produce a screen output similar to this:

configure: --------------------------------------------------------------
configure: --- FASTJET ---
configure: 
checking for fastjet-config... /usr/local/bin/fastjet-config
checking if FastJet is functional... yes
checking FastJet... yes
configure: --------------------------------------------------------------

2.2.10  STDHEP

STDHEP is a library for handling collider scattering events [54]. In particular, it provides a portable format for event files. Until version 2.2.7 of WHIZARD, STDHEP that was maintained by Fermilab, could be linked as an externally compiled library. As the STDHEP package is frozen in its final release v5.06.1 and no longer maintained, it has from version 2.2.8 been included WHIZARD. This eases many things, as it was notoriously difficult to compile and link STDHEP in a way compatible with WHIZARD. Not the full package has been included, but only the libraries for file I/O (mcfio, the library for the XDR conversion), while the various translation tools for PYTHIA, HERWIG, etc. have been abandoned. Note that STDHEP has largely been replaced in the hadron collider community by the HepMC format, and in the lepton collider community by LCIO. WHIZARD might serve as a conversion tools for all these formats, but other tools also exist, of course.

If the STDHEP library is linked with the installation, WHIZARD is able to write files in the STDHEP format, the corresponding configure output notifies you that STDHEP is always included:

configure: --------------------------------------------------------------
configure: --- STDHEP ---
configure:
configure: StdHEP v5.06.01 is included internally
configure: -------------------------------------------------------------- 

2.2.11  LCIO

LCIO is a C++ class library for handling collider scattering events. In particular, it provides a portable format for event files. If you want to use this format, you should link WHIZARD with LCIO, otherwise you can skip this section.

If it is not already installed on your system, you may obtain LCIO from:

http://lcio.desy.de

If the LCIO library is linked with the installation, WHIZARD is able to read and write files in the LCIO format.

Detailed information on the installation and usage can be found on the LCIO homepage. We give here only some brief details relevant for the usage with WHIZARD: For the compilation of LCIO one needs a C++ compiler. LCIO is based on cmake. For the corresponding options please confer the LCIO manual.

A WHIZARD configuration for LCIO looks like this:

   configure: --------------------------------------------------------------
   configure: --- LCIO ---
   configure:
   checking the LCIO version... 2.7.1
   checking for LCEventImpl class in -llcio... yes
   configure: --------------------------------------------------------------    
  

If LCIO is installed in a non-default directory where WHIZARD would not find it, set the environment variable LCIO or LCIO_DIR to the correct installation path when configuring WHIZARD. The first one is the variable exported by the setup.sh script while the second one is analogous to the environment variables of other external packages. LCIO takes precedence over LCIO_DIR. Furthermore, the environment variable CXXFLAGS allows you to set specific C/C++ preprocessor flags, e.g. non-standard include paths for header files.

2.3  Installation

Once you have unpacked the source (either the tarball or the SVN version), you are ready to compile it. There are several options.

2.3.1  Central Installation

This is the default and recommended way, but it requires adminstrator privileges. Make sure that all prerequisites are met (Sec. 2.2).

  1. Create a fresh directory for the WHIZARD build. It is recommended to keep this separate from the source directory.
  2. Go to that directory and execute
        your-build-directory> your-src-directory/configure
      
    This will analyze your system and prepare the compilation of WHIZARD in the build directory. Make sure to set the proper options to configure, see Sec. 2.3.3 below.
  3. Call make to compile and link WHIZARD:
        your-build-directory> make
      
  4. If you want to make sure that everything works, run
        your-build-directory> make check
      
    This will take some more time.
  5. Become superuser and say
        your-build-directory> make install
      

WHIZARD should now installed in the default locations, and the executable should be available in the standard path. Try to call whizard --help in order to check this.

2.3.2  Installation in User Space

You may lack administrator privileges on your system. In that case, you can still install and run WHIZARD. Make sure that all prerequisites are met (Sec. 2.2).

  1. Create a fresh directory for the WHIZARD build. It is recommended to keep this separate from the source directory.
  2. Reserve a directory in user space for the WHIZARD installation. It should be empty, or yet non-existent.
  3. Go to that directory and execute
        your-build-directory> your-src-directory/configure 
                                   --prefix=your-install-directory
      
    This will analyze your system and prepare the compilation of WHIZARD in the build directory. Make sure to set the proper additional options to configure, see Sec. 2.3.3 below.
  4. Call make to compile and link WHIZARD:
        your-build-directory> make
      
  5. If you want to make sure that everything works, run
        your-build-directory> make check
      
    This will take some more time.
  6. Install:
        your-build-directory> make install
      

WHIZARD should now be installed in the installation directory of your choice. If the installation is not in your standard search paths, you have to account for this by extending the paths appropriately, see Sec. 2.4.1.

2.3.3  Configure Options

The configure script accepts environment variables and flags. They can be given as arguments to the configure program in arbitrary order. You may run configure --help for a listing; only the last part of this long listing is specific for the WHIZARD system. Here is an example:

  configure  FC=gfortran-4.8  FCFLAGS="-g -O3"  --enable-fc-openmp

The most important options are

  • FC (variable): The Fortran compiler. This is necessary if you need a compiler different from the standard compiler on the system, e.g., if the latter is too old.
  • FCFLAGS (variable): The flags to be given to the Fortran compiler. The main use is to control the level of optimization.
  • --prefix=directory-name⟩: Specify a non-default directory for installation.
  • --enable-fc-openmp: Enable parallel executing via OpenMP on a multi-processor/multi-core machine. This works only if OpenMP is supported by the compiler (e.g., gfortran). When running WHIZARD, the number of processors that are actually requested can be controlled by the user. Without this option, WHIZARD will run in serial mode on a single core. See Sec. 5.4.3 for further details.
  • LHADPF_DIR (variable): The location of the optional LHAPDF package, if non-default.
  • LOOPTOOLS_DIR (variable): The location of the optional LOOPTOOLS package, if non-default.
  • OPENLOOPS_DIR (variable): The location of the optional OpenLoops package, if non-default.
  • GOSAM_DIR (variable): The location of the optional Gosam package, if non-default.
  • HOPPET_DIR (variable): The location of the optional HOPPET package, if non-default.
  • HEPMC_DIR (variable): The location of the optional HepMC package, if non-default.
  • LCIO/LCIO_DIR (variable): The location of the optional LCIO package, if non-default.

Other flags that might help to work around possible problems are the flags for the C and C++ compilers as well as the Fortran77 compiler, or the linker flags and additional libraries for the linking process.

  • CC (variable): C compiler command
  • F77 (variable): Fortran77 compiler command
  • CXX (variable): C++ compiler command
  • CPP (variable): C preprocessor
  • CXXCPP (variable): C++ preprocessor
  • CFLAGS (variable): C compiler flags
  • FFLAGS (variable): Fortran77 compiler flags
  • CXXFLAGS (variable): C++ compiler flags
  • LIBS (variable): libraries to be passed to the linker as -llibrary
  • LDFLAGS (variable): non-standard linker flags

For other options (like e.g. --with-precision=... etc.) please see the configure --help option.

2.3.4  Details on the Configure Process

The configure process checks for the build and host system type; only if this is not detected automatically, the user would have to specify this by himself. After that system-dependent files are searched for, LaTeX and Acroread for documentation and plots, the Fortran compiler is checked, and finally the OCaml compiler. The next step is the checks for external programs like LHAPDF and HepMC. Finally, all the Makefiles are being built.

The compilation is done by invoking make and finally make install. You could also do a make check in order to test whether the compilation has produced sane files on your system. This is highly recommended.

Be aware that there be problems for the installation if the install path or a user’s home directory is part of an AFS file system. Several times problems were encountered connected with conflicts with permissions inside the OS permission environment variables and the AFS permission flags which triggered errors during the make install procedure. Also please avoid using make -j options of parallel execution of Makefile directives as AFS filesystems might not be fast enough to cope with this.

For specific problems that might have been encountered in rare circumstances for some FORTRAN compilers confer the webpage http://projects.hepforge.org/whizard/compilers.html.

Note that the PYTHIA bundle for showering and hadronization (and some other external legacy code pieces) do still contain good old Fortran77 code. These parts should better be compiled with the very same Fortran2003 compiler as the WHIZARD core. There is, however, one subtlety: when the configure flag FC gets a full system path as argument, libtool is not able to recognize this as a valid (GNU) Fortran77 compiler. It then searches automatically for binaries like f77, g77 etc. or a standard system compiler. This might result in a compilation failure of the Fortran77 code. A viable solution is to define an executable link and use this (not the full path!) as FC flag.

It is possible to compile WHIZARD without the OCaml parts of O’Mega, namely by using the --disable-omega option of the configure. This will result in a built of WHIZARD with the O’Mega Fortran library, but without the binaries for the matrix element generation. All selftests (cf. 2.3.5) requiring O’Mega matrix elements are thereby switched off. Note that you can install such a built (e.g. on a batch system without OCaml installation), but the try to build a distribution (all make distxxx targets) will fail.

2.3.5  WHIZARD self tests/checks

WHIZARD has a number of self-consistency checks and tests which assure that most of its features are running in the intended way. The standard procedure to invoke these self tests is to perform a make check from the build directory. If src and build directories are the same, all relevant files for these self-tests reside in the tests subdirectory of the main WHIZARD directory. In that case, one could in principle just call the scripts individually from the command line. Note, that if src and build directory are different as recommended, then the input files will have been installed in prefix/share/whizard/test, while the corresponding test shell scripts remain in the srcdir/test directory. As the main shell script run_whizard.sh has been built in the build directory, one now has to copy the files over by and set the correct paths by hand, if one wishes to run the test scripts individually. make check still correctly performs all WHIZARD self-consistency tests. The tests itself fall into two categories, unit self test that individually test the modular structure of WHIZARD, and tests that are run by SINDARIN files. In future releases of WHIZARD, these two categories of tests will be better separated than in the 2.2.1 release.

There are additional, quite extensiv numerical tests for validation and backwards compatibility checks for SM and MSSM processes. As a standard, these extended self tests are not invoked. However, they can be enabled by executing the corresponding specific make check operations in the subdirectories for these extensive tests.

As the new WHIZARD testsuite does very thorough and scrupulous tests of the whole WHIZARD structure, it is always possible that some tests are failing due to some weird circumstances or because of numerical fluctuations. In such a case do not panic, contact the developers (whizard@desy.de) and provide them with the logfiles of the failing test as well as the setup of your configuration.

2.4  Working With WHIZARD

2.4.1  Working on a Single Computer

After installation, WHIZARD is ready for use. There is a slight complication if WHIZARD has been installed in a location that is not in your standard search paths.

In that case, to successfully run WHIZARD, you may either

  • manually add your-install-directory/bin to your execution PATH
    and your-install-directory/lib to your library search path (LD_LIBRARY_PATH), or
  • whenever you start a project, execute
        your-workspace> . your-install-directory/bin/whizard-setup.sh
      
    which will enable the paths in your current environment, or
  • source whizard-setup.sh script in your shell startup file.

In either case, try to call whizard --help in order to check whether this is done correctly.

For a new WHIZARD project, you should set up a new (empty) directory. Depending on the complexity of your task, you may want to set up separate directories for each subproblem that you want to tackle, or even for each separate run. The location of the directories is arbitrary.

To run, WHIZARD needs only a single input file, a SINDARIN command script with extension .sin (by convention). Running WHIZARD is as simple as

  your-workspace> whizard your-input.sin

No other configuration files are needed. The total number of auxiliary and output files generated in a single run may get quite large, however, and they may clutter your workspace. This is the reason behind keeping subdirectories on a per-run basis.

Basic usage of WHIZARD is explained in Chapter 3, for more details, consult the following chapters. In Sec. 14.1 we give an account of the command-line options that WHIZARD accepts.

2.4.2  Stopping And Resuming WHIZARD Jobs

On a Unix-like system, it is possible to prematurely stop running jobs by a kill(1) command, or by entering Ctrl-C on the terminal.

If the system supports this, WHIZARD traps these signals. It also traps some signals that a batch operating system might issue, e.g., for exceeding a predefined execution time limit. WHIZARD tries to complete the calculation of the current event and gracefully close open files. Then, the program terminates with a message and a nonzero return code. Usually, this should not take more than a fraction of a second.

If, for any reason, the program does not respond to an interrupt, it is always possible to kill it by kill -9. A convenient method, on a terminal, would be to suspend it first by Ctrl-Z and then to kill the suspended process.

The program is usually able to recover after being stopped. Simply run the job again from start, with the same input, all output files generated so far left untouched. The results obtained so far will be quickly recovered or gathered from files written in the previous run, and the actual time-consuming calculation is resumed near the point where it was interrupted.8 If the interruption happened during an integration step, it is resumed after the last complete iteration. If it was during event generation, the previous events are taken from file and event generation is continued.

The same mechanism allows for efficiently redoing a calculation with similar, somewhat modified input. For instance, you might want to add a further observable to event analysis, or write the events in a different format. The time for rerunning the program is determined just by the time it takes to read the existing integration or event files, and the additional calculation is done on the recovered information.

By managing various checksums on its input and output files, WHIZARD detects changes that affect further calculations, so it does a real recalculation only where it is actually needed. This applies to all steps that are potentially time-consuming: matrix-element code generation, compilation, phase-space setup, integration, and event generation. If desired, you can set command-line options or SINDARIN parameters that explicitly discard previously generated information.

2.4.3  Submitting Batch Jobs With WHIZARD

There is a possibility to distribute WHIZARD from one machine to another, e.g. on a batch cluster. You can suggest WHIZARD to make a statically linked copy of itself, which includes all processes that you want to study, hard-coded. The external libraries (Fortran, and possibly HepMC and stdc++) must be available on the target system, and it must be binary-compatible, but there is no need for transferring the complete WHIZARD installation or relocating paths. The drawback is that generating, compiling and linking matrix element code is done on the submitting host.

Since this procedure is accomplished by SINDARIN commands, it is explained below in Sec. 5.4.7.

2.5  Troubleshooting

In this section, we list known issues or problems and give advice on what can be done in case something does not work as intended.

2.5.1  Possible (uncommon) build problems

OCaml versions and O’Mega builds

For the matrix element generator O’Mega of WHIZARD  the functional programming language OCaml is used. Unfortunately, the versions of the OCaml compiler from 3.12.0 on broke backwards compatibility. Therefore, versions of O’Mega/WHIZARD up to v2.0.2 only compile with older versions (3.04 to 3.11 works). This has been fixed in all WHIZARD versions from 2.0.3 on.

Identical Build and Source directories

There is a problem that only occurred with version 2.0.0 and has been corected for all follow-up versions. It can only appear if you compile the WHIZARD sources in the source directory. Then an error like this may occur:

...
libtool: compile:  gfortran -I../misc -I../vamp -g -O2 -c processes.f90 -fPIC -o 
          .libs/processes.o
libtool: compile:  gfortran -I../misc -I../vamp -g -O2 -c processes.f90 -o
          processes.o >/dev/null 2>&1
make[2]: *** No rule to make target `limits.lo', needed by `decays.lo'.  Stop.
...
make: *** [all-recursive] Error 1

In this case, please unpack a fresh copy of WHIZARD and configure it in a separate directory (not necessarily a subdirectory). Then the compilation will go through:

$ zcat whizard-2.0.0.tar.gz | tar xf - 
$ cd whizard-2.0.0
$ mkdir _build
$ cd _build
$ ../configure FC=gfortran
$ make  

The developers use this setup to be able to test different compilers. Therefore building in the same directory is not as thoroughly tested. This behavior has been patched from version 2.0.1 on. But note that in general it is always adviced to keep build and source directory apart from each other.

2.5.2  What happens if WHIZARD throws an error?

Particle name special characters in process declarations

Trying to use a process declaration like

process foo = e-, e+ => mu-, mu+  

will lead to a SINDARIN syntax error:

process foo = e-, e+ => mu-, mu+
               ^^
| Expected syntax: SEQUENCE    <cmd_process> = process <process_id> '=' <process_p
| Found token: KEYWORD:    '-'
******************************************************************************
******************************************************************************
*** FATAL ERROR:  Syntax error (at or before the location indicated above)
******************************************************************************
******************************************************************************  

WHIZARD tries to interpret the minus and plus signs as operators (KEYWORD: ’-’), so you have to quote the particle names: process foo = "e-", "e+" => "mu-", "mu+".

Missing collider energy

This happens if you forgot to set the collider energy in the integration of a scattering process:

******************************************************************************
******************************************************************************
*** FATAL ERROR:  Colliding beams: sqrts is zero (please set sqrts)
******************************************************************************
******************************************************************************  

This will solve your problem:

sqrts = <your_energy>   

Missing process declaration

If you try to integrate or simulate a process that has not declared before (and is also not available in a library that might be loaded), WHIZARD will complain:

******************************************************************************
******************************************************************************
*** FATAL ERROR: Process library doesn't contain process 'f00'
******************************************************************************
******************************************************************************  

Note that this could sometimes be a simple typo, e.g. in that case an integrate (f00) instead of integrate (foo)

Ambiguous initial state without beam declaration

When the user declares a process with a flavor sum in the initial state, e.g.

process qqaa = u:d, U:D => A, A
sqrts = <your_energy>
integrate (qqaa)

then a fatal error will be issued:

******************************************************************************
******************************************************************************
*** FATAL ERROR: Setting up process 'qqaa':
***                 --------------------------------------------
***              Inconsistent initial state. This happens if either
***              several processes with non-matching initial states
***              have been added, or for a single process with an
***              initial state flavor sum. In that case, please set beams
***              explicitly [singling out a flavor / structure function.]
******************************************************************************
******************************************************************************  

What now? Either a structure function providing a tensor structure in flavors has to be provided like

beams = p, pbar => pdf_builtin  

or, if the partonic process was intended, a specific flavor has to be singled out,

beams = u, U  

which would take only the up-quarks. Note that a sum over process components with varying initial states is not possible.

Invalid or unsupported beam structure

An error message like

******************************************************************************
******************************************************************************
*** FATAL ERROR: Beam structure: [.......] not supported
******************************************************************************
******************************************************************************  

This happens if you try to use a beam structure with is either not supported by WHIZARD (meaning that there is no phase-space parameterization for Monte-Carlo integration available in order to allow an efficient sampling), or you have chosen a combination of beam structure functions that do not make sense physically. Here is an example for the latter (lepton collider ISR applied to protons, then proton PDFs):

beams = p, p => isr => pdf_builtin

Mismatch in beams

Sometimes you get a rather long error output statement followed by a fatal error:

 Evaluator product
 First interaction
 Interaction: 6
 Virtual:
 Particle 1
  [momentum undefined]
[.......]
 State matrix:  norm =  1.000000000000E+00
 [f(2212)]
   [f(11)]
     [f(92) c(1 )]
       [f(-6) c(-1 )] => ME(1) = ( 0.000000000000E+00, 0.000000000000E+00)
[.......]
******************************************************************************
******************************************************************************
*** FATAL ERROR: Product of density matrices is empty
***                 --------------------------------------------
***              This happens when two density matrices are convoluted
***              but the processes they belong to (e.g., production
***              and decay) do not match. This could happen if the
***              beam specification does not match the hard
***              process. Or it may indicate a WHIZARD bug.
******************************************************************************
******************************************************************************  

As WHIZARD indicates, this could have happened because the hard process setup did not match the specification of the beams as in:

process neutral_current_DIS = e1, u => e1, u
beams_momentum = 27.5 GeV, 920 GeV
beams = p, e => pdf_builtin, none
integrate (neutral_current_DIS)  

In that case, the order of the beam particles simply was wrong, exchange proton and electron (together with the structure functions) into beams = e, p => none, pdf_builtin, and WHIZARD will be happy.

Unstable heavy beam particles

If you try to use unstable particles as beams that can potentially decay into the final state particles, you might encounter the following error message:

  
******************************************************************************
******************************************************************************
*** FATAL ERROR:  Phase space: Initial beam particle can decay
******************************************************************************
******************************************************************************

This happens basically only for processes in testing/validation (like t tb b). In principle, it could also happen in a real physics setup, e.g. when simulating electron pairs at a muon collider:

process mmee = "mu-", "mu+" => "e-", "e+"

However, WHIZARD at the moment does not allow a muon width, and so WHIZARD is not able to decay a muon in a scattering process. A possibile decay of the beam particle into (part of) the final state might lead to instabilities in the phase space setup. Hence, WHIZARD do not let you perform such an integration right away. When you nevertheless encounter such a rare occasion in your setup, there is a possibility to convert this fatal error into a simple warning by setting the flag:

?fatal_beam_decay = false

Impossible beam polarization

If you specify a beam polarization that cannot correspond to any physically allowed spin density matrix, e.g.,

beams = e1, E1
beams_pol_density = @(-1), @(1:1:.5, -1, 1:-1)  

WHIZARD will throw a fatal error like this:

 Trace of matrix square =    1.4444444444444444     
 Polarization: spin density matrix
   spin type     = 2
   multiplicity  = 2
   massive       = F
   chirality     = 0
   pol.degree    = 1.0000000
   pure state    = F
   @(+1: +1: ( 3.333333333333E-01, 0.000000000000E+00))
   @(-1: -1: ( 6.666666666667E-01, 0.000000000000E+00))
   @(-1: +1: ( 6.666666666667E-01, 0.000000000000E+00))
******************************************************************************
******************************************************************************
*** FATAL ERROR: Spin density matrix: not permissible as density matrix
******************************************************************************
******************************************************************************  

Beams with crossing angle

Specifying a crossing angle (e.g. at a linear lepton collider) without explicitly setting the beam momenta,

  sqrts = 1 TeV
  beams = e1, E1
  beams\_theta = 0, 10 degree

triggers a fatal:

******************************************************************************
******************************************************************************
*** FATAL ERROR: Beam structure: angle theta/phi specified but momentum/a p undefined
******************************************************************************
******************************************************************************  

In that case the single beam momenta have to be explicitly set:

  beams = e1, E1
  beams\_momentum = 500 GeV, 500 GeV
  beams\_theta = 0, 10 degree

Phase-space generation failed

Sometimes an error might be issued that WHIZARD could not generate a valid phase-space parameterization:

| Phase space: ... failed.  Increasing phs_off_shell ...
| Phase space: ... failed.  Increasing phs_off_shell ...
| Phase space: ... failed.  Increasing phs_off_shell ...
| Phase space: ... failed.  Increasing phs_off_shell ...
******************************************************************************
******************************************************************************
*** FATAL ERROR: Phase-space: generation failed
******************************************************************************
******************************************************************************  

You see that WHIZARD tried to increase the number of off-shell lines that are taken into account for the phase-space setup. The second most important parameter for the phase-space setup, phs_t_channel, however, is not increased automatically. Its default value is 6, so e.g. for the process e+ e → 8γ you will run into the problem above. Setting

phs_off_shell = <n>-1

where <n> is the number of final-state particles will solve the problem.

Non-converging process integration

There could be several reasons for this to happen. The most prominent one is that no cuts have been specified for the process (WHIZARD2 does not apply default cuts), and there are singular regions in the phase space over which the integration stumbles. If cuts have been specified, it could be that they are not sufficient. E.g. in ppjj a distance cut between the two jets prevents singular collinear splitting in their generation, but if no pT cut have been set, there is still singular collinear splitting from the beams.

Why is there no event file?

If no event file has been generated, WHIZARD stumled over some error and should have told you, or, you simply forgot to set a simulate command for your process. In case there was a simulate command but the process under consideration is not possible (e.g. a typo, e1, E1 => e2, E3 instead of e1, E1 => e3, E3), then you get an error like that:

******************************************************************************
*** ERROR: Simulate: no process has a valid matrix element.
******************************************************************************  

Why is the event file empty?

In order to get events, you need to set either a desired number of events:

n_events = <integer>

or you have to specify a certain integrated luminosity (the default unit being inverse femtobarn:

luminosity = <real> / 1 fbarn

In case you set both, WHIZARD will take the one that leads to the higher number of events.




2.5.3  Debugging, testing, and validation

Catching/tracking arithmetic exceptions

Catching arithmetic exceptions is not automatically supported by Fortran compilers. In general, flags that cause the compiler to keep track of arithmetic exceptions are diminishing the maximally possible performance, and hence they should not be used in production runs. Hence, we refrained from making these flags a default. They can be added using the FCFLAGS = <flags> settings during configuration. For the NAG Fortran compiler we use the flags -C=all -nan -gline for debugging purposes. For the gfortran compilers, the flags -ffpe-trap=invalid,zero,overflow are the corresponding debugging flags. For tests, debugging or first sanity checks on your setup, you might want to make use of these flags in order to track possible numerical exceptions in the produced code. Some compilers started to include IEEE exception handling support (Fortran 2008 status), but we do not use these implementations in the WHIZARD code (yet).


1
Unfortunately, the version of the OCaml compiler from 3.12.0 broke backwards compatibility. Therefore, versions of O’Mega/WHIZARD up to 2.0.2 only compile with older versions (3.11.x works). This has been fixed in versions 2.0.3 and later. See also Sec. 2.5.1.
2
Without GNU tar, this would read gunzip -c whizard-2.5.0.tgz | tar xz -
3
In Ubuntu from version 10.04 on, and in Debian since squeeze. For Mac OS X, noweb is available via the MacPorts system.
4
Please, do not use any of the binary builds from this webpage. Probably all of them are quite old and broken.
5
At least, version 2.65 of the autoconf package is required.
6
Note that WHIZARD versions 2.0.0 until 2.3.1 compiled with gfortran 4.7.4, but the object-oriented refactoring of the WHIZARD code from 2.4 on made a switch to gfortran 4.8.0 or higher necessary.
7
Note that PDF sets which contain photons as partons are only supported with WHIZARD for LHAPDF version 5.7.1 or higher
8
This holds for simple workflow. In case of scans and repeated integrations of the same process, there may be name clashes on the written files which prevent resuming. A future WHIZARD version will address this problem.

Previous Up Next