whizard is hosted by Hepforge, IPPP Durham
Previous Up Next

Chapter ‍1 Introduction

1.1 Disclaimer

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

1.2 Overview

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

Figure 1.1: General structure of the WHIZARD package.

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.

Chap. ‍12 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 whizard@desy.de.

There is now also a support page on Launchpad, which offers support that is easily visible for the whole user community: https://launchpad.net/whizard.

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 ‍[5]. 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 ‍[6]. 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(we break the table into logical and temporal blocks of WHIZARD development).

WHIZARD 1, first line of development, ca. 1998-2010:

0.9908/1999Beta version
1.0012/2000First public version
1.1003/2001Libraries; PYTHIA6 interface
1.1104/2001PDF support; anomalous couplings
1.2002/2002O’Mega matrix elements; CIRCE support
1.2203/2002QED ISR; beam remnants, phase space improvements
1.2505/2003MSSM; weighted events; user-code plug-in
1.2804/2004Improved phase space; SLHA interface; signal catching
1.3009/2004Major technical overhaul
1.4012/2004Asymmetric beams; decays; pT in structure functions
1.5002/2006QCD support in O’Mega (color flows); LHA format
1.5106/2006Hgg, Hγγ; Spin 3/2 + 2; BSM models
1.9011/2007O’Mega included; LHAPDF support; Z′; WW scattering
1.9203/2008LHE format; UED; parton shower beta version
1.9304/2009NMSSM; SLHA2 accord; improved color/flavor sums
1.9502/2010MLM matching; development stop in version 1
1.9705/2011Manual for version 1 completed.

WHIZARD 2.0-2.2: first major refactoring and early new release, ca. 2007-2015:

2.0.004/2010Major refactoring: automake setup; dynamic libraries
  improved speed; cascades; OpenMP; SINDARIN steering language
2.0.307/2010QCD ISR+FSR shower; polarized beams
2.0.505/2011Builtin PDFs; static builds; relocation scripts
2.0.612/2011Anomalous top couplings; unit tests
2.1.006/2012Analytic ISR+FSR parton shower; anomalous Higgs couplings
2.2.005/2014Major technical refactoring: abstract object-orientation; THDM;
  reweighting; LHE v2/3; BLHA; HOPPET interface; inclusive processes
2.2.105/2014CJ12 PDFs; FastJet interface
2.2.207/2014LHAPDF6 support; correlated LC beams; GuineaPig interface
2.2.311/2014O’Mega virtual machine; lepton collider top pair threshold;
  Higgs singlet extension
2.2.402/2015LCIO support; progress on NLO; many technical bug fixes
2.2.708/2015progress on POWHEG; fixed-order NLO events;
  revalidation of ILC event chain
2.2.811/2015support for quadruple precision; StdHEP included;
  SM dim 6 operators supported

WHIZARD 2.3-2.8, completion of refactoring, continuous development, ca. 2015-2020:

2.3.007/2016NLO: resonance mappings for FKS subtraction;
  more advanced cascade syntax;
  GUI (α version); UFO support (α version); ILC v1.9x-v2.x final validation
2.3.108/2016Complex mass scheme
2.4.011/2016Refactoring of NLO setup
2.4.103/2017α version of new VEGAS implementation
2.5.005/2017Full UFO support (SM-like models)
2.6.009/2017MPI parallel integration and event generation; resonance histories
  for showers; RECOLA support
2.6.111/2017EPA/ISR transverse distributions, handling of shower resonances;
  more efficient (alternative) phase space generation
2.6.212/2017Hee coupling, improved resonance matching
2.6.302/2018Partial NLO refactoring for quantum numbers,
  unified RECOLA 1/2 interface.
2.6.408/2018Gridpack functionality; Bug fixes: color flows, HSExt model, MPI setup
2.7.001/2019PYTHIA8 interface, process setup refactoring, RAMBO PS option;
   gfortran 5.0+ necessary
2.8.008/2019(Almost) complete UFO support, general Lorentz structures, n-point vertices
2.8.109/2019HepMC3, NLO QCD pp (almost) complete, b/c jet selection, photon isolation
2.8.210/2019Support for OCaml ≥ 4.06.0, UFO Spin-2 support, LCIO alternative weights
2.8.307/2020UFO Majorana feature complete, many e+e related improvements
2.8.407/2020Bug fix for UFO Majorana models
2.8.509/2020Bug fix for polarizations in H→ττ

WHIZARD 3.0 and onwards, the NLO series:

3.0.004/2021NLO QCD automation & UFO Majorana support released
3.0.107/2021MPI load balancer, rescan of ILC mass production samples
3.0.211/2021NLO EW for pp processes, sums/products in SINDARIN
3.0.304/2022NLO EW/QCD mixed processes, NLL electron PDFs
3.1.012/2022General POWHEG matching (hadron/lepton colliders)
3.1.203/2023Improved numerical stability for s-channel resonances
3.1.310/2023New compiler requirements: gfortran 9.1.0+, OCaml 4.08+
3.1.411/2023Bug fixes for Pythia8 v8.310+, UFO interface

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 [58] 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).

Previous Up Next