Chapter 1 Introduction
This is a preliminary version of the WHIZARD manual. Many parts are still missing or incomplete, and some parts will be rewritten and improved soon. To find updated versions of the manual, visit the WHIZARD website
or consult the current version in the svn repository on https://whizard.hepforge.org directly. Note, that the most recent version of the manual might contain information about features of the current svn version, which are not contained in the last official release version!
For information that is not (yet) written in the manual, please consult the examples in the WHIZARD distribution. You will find these in the subdirectory share/examples of the main directory where WHIZARD is installed. More information about the examples can be found on the WHIZARD Wiki page
WHIZARD is a multi-purpose event generator that covers all parts of event generation (unweighted and weighted), either through intrinsic components or interfaces to external packages. Realistic collider environments are covered through sophisticated descriptions for beam structures at hadron colliders, lepton colliders, lepton-hadron colliders, both circular and linear machines. Other options include scattering processes e.g. for dark matter annihilation or particle decays. WHIZARD contains its in-house generator for (tree-level) high-multiplicity matrix elements, O’Mega that supports the whole Standard Model (SM) of particle physics and basically all possibile extensions of it. QCD parton shower describe high-multiplicity partonic jet events that can be matched with matrix elements. At the moment, only hadron collider parton distribution functions (PDFs) and hadronization are handled by packages not written by the main authors.
This manual is organized mainly along the lines of the way how to run WHIZARD: this is done through a command language, SINDARIN (Scripting INtegration, Data Analysis, Results display and INterfaces.) Though this seems a complication at first glance, the user is rewarded with a large possibility, flexibility and versatility on how to steer WHIZARD.
After some general remarks in the follow-up sections, in Chap. 2 we describe how to get the program, the package structure, the prerequisites, possible external extensions of the program and the basics of the installation (both as superuser and locally). Also, a first technical overview how to work with WHIZARD on single computer, batch clusters and farms are given. Furthermore, some rare uncommon possible build problems are discussed, and a tour through options for debugging, testing and validation is being made.
A first dive into the running of the program is made in Chap. 3. This is following by an extensive, but rather technical introduction into the steering language SINDARIN in Chap. 4. Here, the basic elements of the language like commands, statements, control structures, expressions and variables as well as the form of warnings and error messages are explained in detail.
Chap. 5 contains the application of the SINDARIN command language to the main tasks in running WHIZARD in a physics framework: the defintion of particles, subevents, cuts, and event selections. The specification of a particular physics models is
discussed, while the next sections are devoted to the setup and compilation of code for particular processes, the specification of beams, beam structure and polarization. The next step is the integration, controlling the integration, phase space, generator cuts, scales and weights, proceeding further to event generation and decays. At the end of this chapter, WHIZARD’s internal data analysis methods and graphical visualization options are documented.
The following chapters are dedicated to the physics implemented in WHIZARD: methods for hard matrix interactions in Chap. 9. Then, in Chap. 10, implemented methods for adaptive multi-channel integration, particularly the integrator VAMP are explained, together with the algorithms for the generation of the phase-space in WHIZARD. Finally, an overview is given over the physics models implemented in WHIZARD and its matrix element generator O’Mega, together with possibilities for their extension. After that, the next chapter discusses parton showering, matching and hadronization as well as options for event normalizations and supported event formats. Also weighted event generation is explained along the lines with options for negative weights. Then, in Chap. 12, options for user to plug-in self-written code into the WHIZARD framework are detailed, e.g. for observables, selections and cut functions, or for spectra and structure functions. Also, static executables are discussed.
Chap. 13 is a stand-alone documentation of GAMELAN, the interal graphics support for the visualization of data and analysis. The next chapter, Chap. 14 details user interfaces: how to use more options of the WHIZARD command on the command line, how to use WHIZARD interactively, and how to include WHIZARD as a library into the user’s own program.
Then, an extensive list of examples in Chap. 15 documenting physics examples from the LEP, SLC, HERA, Tevatron, and LHC colliders to future linear and circular colliders. This chapter is a particular good reference for the beginning, as the whole chain from choosing a model, setting up processes, the beam structure, the integration, and finally simulation and (graphical) analysis are explained in detail.
More technical details about efficiency, tuning and advance usage of WHIZARD are collected in Chap. 16. Then, Chap. 17 shows how to set up your own new physics model with the help of external programs like SARAH or FeynRules program or the Universal Feynrules Output, UFO, and include it into the WHIZARD event generator.
In the appendices, we e.g. give an exhaustive reference list of SINDARIN commands and built-in variables.
Please report any inconsistencies, bugs, problems or simply pose open questions to our contact firstname.lastname@example.org.
1.3 Historical remarks
This section gives a historical overview over the development of WHIZARD and can be easily skipped in a (first) reading of the manual. WHIZARD has been developed in a first place as a tool for the physics at the then planned linear electron-positron collider TESLA around 1999. The intention was to have a tool at hand to describe electroweak physics of multiple weak bosons and the Higgs boson as precise as possible with full matrix elements. Hence, the acronym: WHiZard, which stood for W, Higgs, Z, and respective decays.
Several components of the WHIZARD package that are also available as independent sub-packages have been published already before the first versions of the WHIZARD generator itself: the multi-channel adaptive Monte-Carlo integration package VAMP has been released mid 1998 . The dedicated packages for the simulation of linear lepton collider beamstrahlung and the option for a photon collider on Compton backscattering (CIRCE1/2) date back even to mid 1996 . Also parts of the code for WHIZARD’s internal graphical analysis (the gamelan module) came into existence already around 1998.
After first inofficial versions, the official version 1 of WHIZARD was release in the year 2000. The development, improvement and incorporation of new features continued for roughly a decade. Major milestones in the development were the full support of all kinds of beyond the Standard Model (BSM) models including spin 3/2 and spin 2 particles and the inclusion of the MSSM, the NMSSM, Little Higgs models and models for anomalous couplings as well as extra-dimensional models from version 1.90 on. In the beginning, several methods for matrix elements have been used, until the in-house matrix element generator O’Mega became available from version 1.20 on. It was included as a part of the WHIZARD package from version 1.90 on. The support for full color amplitudes came with version 1.50, but in a full-fledged version from 2.0 on. Version 1.40 brought the necessary setups for all kinds of collider environments, i.e. asymmetric beams, decay processes, and intrinsic pT in structure functions.
Version 2.0 was released in April 2010 as an almost complete rewriting of the original code. It brought the construction of an internal density-matrix formalism which allowed the use of factorized production and (cascade) decay processes including complete color and spin correlations. Another big new feature was the command-line language SINDARIN for steering all parts of the program. Also, many performance improvement have taken place in the new release series, like OpenMP parallelization, speed gain in matrix element generation etc. Version 2.2 came out in May 2014 as a major refactoring of the program internals but keeping (almost everywhere) the same user interface. New features are inclusive processes, reweighting, and more interfaces for QCD environments (BLHA/HOPPET).
The following tables shows some of the major steps (physics implementation and/or technical improvements) in the development of WHIZARD:
For a detailed overview over the historical development of the code confer the ChangeLog file and the commit messages in our revision control system repository.
1.4 About examples in this manual
Although WHIZARD has been designed as a Monte Carlo event generator for LHC physics, several elementary steps and aspects of its usage throughout the manual will be demonstrated with the famous textbook example of e+e− → µ+ µ−. This is the same process, the textbook by Peskin/Schroeder  uses as a prime example to teach the basics of quantum field theory. We use this example not because it is very special for WHIZARD or at the time being a relevant physics case, but simply because it is the easiest fundamental field theoretic process without the complications of structured beams (which can nevertheless be switched on like for ISR and beamstrahlung!), the need for jet definitions/algorithms and flavor sums; furthermore, it easily accomplishes a demonstration of polarized beams. After the basics of WHIZARD usage have been explained, we move on to actual physics cases from LHC (or Tevatron).