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: https://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

https://whizard.hepforge.org

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

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.6 for details).
  • The OCaml system. OCaml is a functional and object-oriented language. Version 4.02.3 or newer 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.7.
  • The HOPPET structure-function matching tool. See Sec. ‍2.2.8.
  • The HepMC event-format package. See Sec. ‍2.2.9.
  • The FastJet jet-algorithm package. See Sec. ‍2.2.12.
  • The LCIO event-format package. See Sec. ‍2.2.14.

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.13, particularly on the need to install the libtirpc headers for the legacy support of this event format. Once these prerequisites are met, you may unpack the package in a directory of your choice

some-directory> tar xzf whizard-3.1.4.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-3.1.4 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. Note that since a couple of years our development is now via a Git revision control system hosted at the University of Siegen, cf. the next subsection.

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. automake is needed with version 1.12.2 or newer.
  • 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
  svn+ssh://vcs@phab.hepforge.org/source/whizardsvn/trunk \;\; .

Note that for the time being after the HepForge system modernization early September 2018, a HepForge account with a local ssl key is necessary to checkout the subversion repository. This is enforced by the phabricator framework of HepForge, and will hopefully be relaxed in the future. 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. In order to build the configure script, the autotools package autoreconf has to be run. On some Unix systems the RPC headers needed for the legacy support of the STDHEP event format are provided by the TIRPC library (cf. Sec. ‍2.2.13). To easily check for them, configure.ac processed by autoreconf makes use of the pkg-config tool which needs to be installed for the developer version. So now, run5

  your-src-directory> autoreconf

This will generate a configure script.

2.2.4 Public Git Repository Version

Since a couple of years, development of WHIZARD is done by means of a Git revision system, hosted at the University of Siegen. There is a public mirror of that Git repository available at

https://gitlab.tp.nt.uni-siegen.de/whizard/public

Cloning via HTTPS brings the user to the same change as the SVN checkout from HepForge described in the previous subsection:

git clone https://gitlab.tp.nt.uni-siegen.de/whizard/public.git

The next steps are the same as described in the previous subsection.

2.2.5 Nightly development snapshots

Nightly development snapshots that are pre-packaged in the same way as an official distribution are available from

https://whizard.tp.nt.uni-siegen.de/

Building WHIZARD works the way as described in Sec. ‍2.2.2.

2.2.6 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 9.5.0 or higher6. We recommend to use at least version 5.4 or higher, as especially the the early version of the gfortran experience some bugs. gfortran 6.5.0 has a severe regression and cannot be used. Before WHIZARD version 3.1.3, gfortran 7 and 8 could be used.
  • nagfor (NAG). You will need version 7.1 or higher.
  • ifort (Intel). You will need version 21.10 or higher

2.2.7 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

https://lhapdf.hepforge.org

for the most recent LHAPDF version 6 and newer, or

https://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.2.1
   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... 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.8 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
checking the HOPPET version... 1.2.0
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.9 HepMC

With version 2.8.1, WHIZARD supports both the "classical" version 2 as well as the newly designed version 3 (release 2019). The configure step can successfully recognize the two different versions, the user do not have to specify which version is installed.

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://hepmc.web.cern.ch/hepmc/

or

http://hepmc.web.cern.ch/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.

The latest version of HepMC (2.6.10) as well as the new relase series use cmake for their build process. For more information, confer the HepMC webpage.

A WHIZARD configuration for HepMC looks like this:

   configure: --------------------------------------------------------------
   configure: --- HepMC ---
   configure:
   checking for HepMC-config... no
   checking HepMC3 or newer... no
   configure: HepMC3 not found, incompatible, or HepMC-config not found
   configure: looking for HepMC2 instead ...
   checking the HepMC version... 2.06.10
   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.

A typical configuration of HepMC3 will look like this:

configure: --------------------------------------------------------------
configure: --- ROOT ---
configure:
checking for root-config... /usr/local/bin/root-config
checking for root... /usr/local/bin/root
checking for rootcint... /usr/local/bin/rootcint
checking for dlopen in -ldl... (cached) yes
configure: --------------------------------------------------------------
configure: --- HepMC ---
configure:
checking for HepMC3-config... /usr/local/bin/HepMC3-config
checking if HepMC3 is built with ROOT interface... yes
checking if HepMC3 is functional... yes
checking for HepMC3... yes
checking the HepMC3 version... 3.02.01
configure: --------------------------------------------------------------

As can be seen, WHIZARD will check for the ROOT environment as well as whether HepMC3 has been built with support for the ROOT and RootTree writer classes. This is an easy option to use WHIZARD to write out ROOT events. For more information see Sec. ‍13.1.

2.2.10 PYTHIA6

The WHIZARD package ships with the final version of the old PYTHIA6 release series, v6.427. This is no longer maintained, but many analyses are still set up for this shower and hadronization tool, so WHIZARD offers the possibility of backwards compatibility here.

configure: ————————————————————– configure: — SHOWERS PYTHIA6 PYTHIA8 MPI — configure: checking whether we want to enable PYTHIA6... yes checking for PYTHIA6... (enabled) checking for PYTHIA6 eh settings... (disabled)

WHIZARD automatically compiles PYTHIA6, it has not to be specifically enabled by the user.

In order to properly use PYTHIA6 for high-energy electron-hadron collisions which allow much further forward regions to be explored as old experiments like HERA, there is a special switch to enable those specific settings for eh-colliders:

--enable-pythia6_ep

Those settings have been provided by ‍[59].

2.2.11 PYTHIA8

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.12 FastJet

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
checking the FastJet version... 3.3.4
configure: --------------------------------------------------------------

Note that when compiling on Darwin/macOS it might be necessary to set the option --disable-auto-ptr when compiling with clang++.

2.2.13 STDHEP

STDHEP is a library for handling collider scattering events ‍[60]. 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. Note that the mcfio framework makes use of the RPC headers. These come – provided by SunOS/Oracle America, Inc. – together with the system headers, but on some Unix systems (e.g. ArchLinux, Fedora) have been replaced by the libtirpc headers . The configure script searches for these headers so these have to be installed mandatorily.

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:
checking for pkg-config... /opt/local/bin/pkg-config
checking pkg-config is at least version 0.9.0... yes
checking for libtirpc... no
configure: for StdHEP legacy code: using SunRPC headers and library
configure: StdHEP v5.06.01 is included internally
configure: --------------------------------------------------------------

2.2.14 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.12.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. ‍3.3.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  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.
  • --enable-fc-mpi: Enable parallel executing via MPI on a single machine using several cores or several machines. This works only if a MPI library is installed (e.g. OpenMPI) and FC=mpifort CC=mpicc CXX=mpic++ is set. Without this option, WHIZARD will run in serial mode on a single core. The flag can be combined with --enable-fc-openmp. See Sec. ‍3.3.2 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 https://whizard.hepforge.org/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.7) 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 Building on Darwin/macOS

The easiest way to build WHIZARD on Darwin/macOS is to install the complete GNU compiler suite (gcc/g++/gfortran). This can be done with one of the code repositories like MacPorts, HomeBrew or Fink. In order to include ROOT which natively should be built using the intrinsic clang/clang++ for the graphics support, there is also the possibility to build external tools like HepMC3, PYTHIA8, FastJet, and LCIO with clang++, and set in the configure option for WHIZARD C and C++ compiler accordingly:

../configure CC=clang CXX=clang++ [...]

Note that FastJet might need to be configured with the --disable-auto-ptr option when compiling with clang++ and strict C++17 standard.

Since Darwin v10.11, the security measures of the new Darwin systems do not allow e.g. environment variables passed to subprocesses. This does not change anything for the installed WHIZARD, but the testsuite (make check) will not work before make install has been executed. make distcheck will not work on El Capitan. There is also the option to disable the System Integrity Protocol (SIP) of modern OSX by booting in Recovery Mode, open a terminal and type csrutil disable. However, we do not recommend to do so.

2.3.6 Building on Windows

For Windows, from Windows 10 onwards, there is the possibility to install and use an underlying Linux operating system, e.g. Ubuntu. Installation and usage of WHIZARD works then the same way as described above.

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


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. ‍3.4.1. WHIZARD versions up to 2.7.1 were still backwards compatible with OCaml 3.12.0
2
Without GNU tar, this would read gunzip -c whizard-3.1.4.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.0 on until version 2.6.5 made a switch to gfortran 4.8.4 or higher necessary. In the same way, since version 2.7.0, gfortran 5.1.0 or newer is needed
7
Note that PDF sets which contain photons as partons are only supported with WHIZARD for LHAPDF version 5.7.1 or higher

Previous Up Next