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.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
The distribution is a single file, say whizard-2.5.0.tgz for version 2.5.0.
You need the additional prerequisites:
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.
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
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:
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
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:
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.
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
for the most recent LHAPDF version 6 and newer, or
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.
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
to the configure options above. For more details, please confer the HOPPET manual.
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:
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.
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
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
to configure. If PYTHIA8 is installed in a non-default directory where WHIZARD would not find it, specify also
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: --------------------------------------------------------------
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
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
to configure. If FastJet is installed in a non-default directory where WHIZARD would not find it, specify also
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: --------------------------------------------------------------
STDHEP is a library for handling collider scattering events . 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: --------------------------------------------------------------
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:
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.
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).
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).
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
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.
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 (firstname.lastname@example.org) 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
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.
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.
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:
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:
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
will lead to a SINDARIN syntax error:
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:
This will solve your problem:
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:
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.
then a fatal error will be issued:
What now? Either a structure function providing a tensor structure in flavors has to be provided like
or, if the partonic process was intended, a specific flavor has to be singled out,
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
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):
Mismatch in beams
Sometimes you get a rather long error output statement followed by a fatal error:
As WHIZARD indicates, this could have happened because the hard process setup did not match the specification of the beams as in:
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:
This happens basically only for processes in testing/validation (like t t → b b). In principle, it could also happen in a real physics setup, e.g. when simulating electron pairs at a muon collider:
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:
Impossible beam polarization
If you specify a beam polarization that cannot correspond to any physically allowed spin density matrix, e.g.,
WHIZARD will throw a fatal error like this:
Beams with crossing angle
Specifying a crossing angle (e.g. at a linear lepton collider) without explicitly setting the beam momenta,
triggers a fatal:
In that case the single beam momenta have to be explicitly set:
Phase-space generation failed
Sometimes an error might be issued that WHIZARD could not generate a valid phase-space parameterization:
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
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 pp → jj 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:
Why is the event file empty?
In order to get events, you need to set either a desired number of events:
or you have to specify a certain integrated luminosity (the default unit being inverse femtobarn:
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).