Index: trunk/share/doc/manual.tex
===================================================================
--- trunk/share/doc/manual.tex (revision 8751)
+++ trunk/share/doc/manual.tex (revision 8752)
@@ -1,19057 +1,19126 @@
\documentclass[12pt]{book}
% \usepackage{feynmp}
\usepackage{microtype}
\usepackage{graphics,graphicx}
\usepackage{color}
\usepackage{amsmath,amssymb}
\usepackage[colorlinks,bookmarks,bookmarksnumbered=true]{hyperref}
\usepackage{thophys}
\usepackage{fancyvrb}
\usepackage{makeidx}
\usepackage{units}
\usepackage{ifpdf}
%HEVEA\pdftrue
\makeindex
\usepackage{url}
\usepackage[latin1]{inputenc}
%HEVEA\@def@charset{UTF-8}
%BEGIN LATEX
\usepackage{supertabular,fancyvrb}
\usepackage{hevea}
%END LATEX
\renewcommand{\topfraction}{0.9}
\renewcommand{\bottomfraction}{0.8}
\renewcommand{\textfraction}{0.1}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Macro section
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\email}[2]{\thanks{\ahref{#1@{}#2}{#1@{}#2}}}
\newcommand{\hepforgepage}{\url{https://whizard.hepforge.org}}
\newcommand{\whizardwiki}{\url{https://whizard.hepforge.org/trac/wiki}}
\tocnumber
%BEGIN LATEX
\DeclareMathOperator{\diag}{diag}
%END LATEX
%BEGIN LATEX
\makeatletter
\newif\if@preliminary
\@preliminaryfalse
\def\preliminary{\@preliminarytrue}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Changes referring to article.cls
%
%%% Title page
\def\preprintno#1{\def\@preprintno{#1}}
\def\address#1{\def\@address{#1}}
\def\email#1#2{\thanks{\tt #1@{}#2}}
\def\abstract#1{\def\@abstract{#1}}
\newcommand\abstractname{ABSTRACT}
\newlength\preprintnoskip
\setlength\preprintnoskip{\textwidth\@plus -1cm}
\newlength\abstractwidth
\setlength\abstractwidth{\textwidth\@plus -3cm}
%
\@titlepagetrue
\renewcommand\maketitle{\begin{titlepage}%
\let\footnotesize\small
\hfill\parbox{\preprintnoskip}{%
\begin{flushright}\@preprintno\end{flushright}}\hspace*{1cm}
\vskip 60\p@
\begin{center}%
{\Large\bf\boldmath \@title \par}\vskip 1cm%
{\sc\@author \par}\vskip 3mm%
{\@address \par}%
\if@preliminary
\vskip 2cm {\large\sf PRELIMINARY DRAFT \par \@date}%
\fi
\end{center}\par
\@thanks
\vfill
\begin{center}%
\parbox{\abstractwidth}{\centerline{\abstractname}%
\vskip 3mm%
\@abstract}
\end{center}
\end{titlepage}%
\setcounter{footnote}{0}%
\let\thanks\relax\let\maketitle\relax
\gdef\@thanks{}\gdef\@author{}\gdef\@address{}%
\gdef\@title{}\gdef\@abstract{}\gdef\@preprintno{}
}%
%
%%% New settings of dimensions
\topmargin -1.5cm
\textheight 22cm
\textwidth 17cm
\oddsidemargin 0cm
\evensidemargin 0cm
%
%%% Original Latex definition of citex, except for the removal of
%%% 'space' following a ','. \citerange replaces the ',' by '--'.
\def\@citex[#1]#2{\if@filesw\immediate\write\@auxout{\string\citation{#2}}\fi
\def\@citea{}\@cite{\@for\@citeb:=#2\do
{\@citea\def\@citea{,\penalty\@m}\@ifundefined
{b@\@citeb}{{\bf ?}\@warning
{Citation `\@citeb' on page \thepage \space undefined}}%
\hbox{\csname b@\@citeb\endcsname}}}{#1}}
\def\citerange{\@ifnextchar [{\@tempswatrue\@citexr}{\@tempswafalse\@citexr[]}}
\def\@citexr[#1]#2{\if@filesw\immediate\write\@auxout{\string\citation{#2}}\fi
\def\@citea{}\@cite{\@for\@citeb:=#2\do
{\@citea\def\@citea{--\penalty\@m}\@ifundefined
{b@\@citeb}{{\bf ?}\@warning
{Citation `\@citeb' on page \thepage \space undefined}}%
\hbox{\csname b@\@citeb\endcsname}}}{#1}}
%
%%% Captions set in italics
\long\def\@makecaption#1#2{%
\vskip\abovecaptionskip
\sbox\@tempboxa{#1: \emph{#2}}%
\ifdim \wd\@tempboxa >\hsize
#1: \emph{#2}\par
\else
\hbox to\hsize{\hfil\box\@tempboxa\hfil}%
\fi
\vskip\belowcaptionskip}
%
%%% Other useful macros
\def\fmslash{\@ifnextchar[{\fmsl@sh}{\fmsl@sh[0mu]}}
\def\fmsl@sh[#1]#2{%
\mathchoice
{\@fmsl@sh\displaystyle{#1}{#2}}%
{\@fmsl@sh\textstyle{#1}{#2}}%
{\@fmsl@sh\scriptstyle{#1}{#2}}%
{\@fmsl@sh\scriptscriptstyle{#1}{#2}}}
\def\@fmsl@sh#1#2#3{\m@th\ooalign{$\hfil#1\mkern#2/\hfil$\crcr$#1#3$}}
\makeatother
% Labelling command for Feynman graphs generated by package FEYNMF
%\def\fmfL(#1,#2,#3)#4{\put(#1,#2){\makebox(0,0)[#3]{#4}}}
%END LATEX
%%%% Environment for showing user input and program response
\newenvironment{interaction}%
{\begingroup\small
\Verbatim}%
{\endVerbatim
\endgroup\noindent}
%BEGIN LATEX
%%%% Environment for typesetting listings verbatim
\newenvironment{code}%
{\begingroup\footnotesize
\quote
\Verbatim}%
{\endVerbatim
\endquote
\endgroup\noindent}
%%%% Boxed environment for typesetting listings verbatim
\newenvironment{Code}%
{\begingroup\footnotesize
\quote
\Verbatim[frame=single]}%
{\endVerbatim
\endquote
\endgroup\noindent}
%%% Environment for displaying syntax
\newenvironment{syntax}%
{\begin{quote}
\begin{flushleft}\tt}%
{\end{flushleft}
\end{quote}}
\newcommand{\var}[1]{$\langle$\textit{#1}$\rangle$}
%END LATEX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Macros specific for this paper
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\ttt}[1]{\texttt{#1}}
\newcommand{\whizard}{\ttt{WHIZARD}}
\newcommand{\oMega}{\ttt{O'Mega}}
\newcommand{\vamp}{\ttt{VAMP}}
\newcommand{\vamptwo}{\ttt{VAMP2}}
\newcommand{\vegas}{\ttt{VEGAS}}
\newcommand{\madgraph}{\ttt{MadGraph}}
\newcommand{\CalcHep}{\ttt{CalcHep}}
\newcommand{\helas}{\ttt{HELAS}}
\newcommand{\herwig}{\ttt{HERWIG}}
\newcommand{\isajet}{\ttt{ISAJET}}
\newcommand{\pythia}{\ttt{PYTHIA}}
\newcommand{\pythiasix}{\ttt{PYTHIA6}}
\newcommand{\pythiaeight}{\ttt{PYTHIA8}}
\newcommand{\jetset}{\ttt{JETSET}}
\newcommand{\comphep}{\ttt{CompHEP}}
\newcommand{\circe}{\ttt{CIRCE}}
\newcommand{\circeone}{\ttt{CIRCE1}}
\newcommand{\circetwo}{\ttt{CIRCE2}}
\newcommand{\gamelan}{\textsf{gamelan}}
\newcommand{\stdhep}{\ttt{STDHEP}}
\newcommand{\lcio}{\ttt{LCIO}}
\newcommand{\pdflib}{\ttt{PDFLIB}}
\newcommand{\lhapdf}{\ttt{LHAPDF}}
\newcommand{\hepmc}{\ttt{HepMC}}
\newcommand{\hepmcthree}{\ttt{HepMC3}}
\newcommand{\fastjet}{\ttt{FastJet}}
\newcommand{\hoppet}{\ttt{HOPPET}}
\newcommand{\metapost}{\ttt{MetaPost}}
\newcommand{\sarah}{\ttt{SARAH}}
\newcommand{\spheno}{\ttt{SPheno}}
\newcommand{\Mathematica}{\ttt{Mathematica}}
\newcommand{\FeynRules}{\ttt{FeynRules}}
\newcommand{\UFO}{\ttt{UFO}}
\newcommand{\gosam}{\ttt{Gosam}}
\newcommand{\openloops}{\ttt{OpenLoops}}
\newcommand{\recola}{\ttt{Recola}}
\newcommand{\collier}{\ttt{Collier}}
\newcommand{\powheg}{\ttt{POWHEG}}
\newcommand{\delphes}{\ttt{Delphes}}
\newcommand{\geant}{\ttt{Geant}}
\newcommand{\ROOT}{\ttt{ROOT}}
\newcommand{\rivet}{\ttt{Rivet}}
%%%%%
\newcommand{\sindarin}{\ttt{SINDARIN}}
\newcommand{\cpp}{\ttt{C++}}
\newcommand{\fortran}{\ttt{Fortran}}
\newcommand{\fortranSeventySeven}{\ttt{FORTRAN77}}
\newcommand{\fortranNinetyFive}{\ttt{Fortran95}}
\newcommand{\fortranOThree}{\ttt{Fortran2003}}
\newcommand{\ocaml}{\ttt{OCaml}}
\newcommand{\python}{\ttt{Python}}
\newenvironment{commands}{\begin{quote}\tt}{\end{quote}}
\newcommand{\eemm}{$e^+e^- \to \mu^+\mu^-$}
%\def\~{$\sim$}
\newcommand{\sgn}{\mathop{\rm sgn}\nolimits}
\newcommand{\GeV}{\textrm{GeV}}
\newcommand{\fb}{\textrm{fb}}
\newcommand{\ab}{\textrm{ab}}
\newenvironment{parameters}{%
\begin{center}
\begin{tabular}{lccp{65mm}}
\hline
Parameter & Value & Default & Description \\
\hline
}{%
\hline
\end{tabular}
\end{center}
}
\newenvironment{options}{%
\begin{center}
\begin{tabular}{llcp{80mm}}
\hline
Option & Long version & Value & Description \\
\hline
}{%
\hline
\end{tabular}
\end{center}
}
%BEGIN LATEX
\renewenvironment{options}{%
\begin{center}
\tablehead{\hline
Option & Long version & Value & Description \\
\hline
}
\begin{supertabular}{llcp{80mm}}
}{%
\hline
\end{supertabular}
\end{center}
}
%END LATEX
%BEGIN LATEX
\renewenvironment{parameters}{%
\begin{center}
\tablehead{\hline
Parameter & Value & Default & Description \\
\hline
}
\begin{supertabular}{lccp{65mm}}
}{%
\hline
\end{supertabular}
\end{center}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%END LATEX
\newcommand{\thisversion}{3.0.1}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%BEGIN LATEX
\preprintno{}
%%%\preprintno{arXiv:0708.4233 (also based on LC-TOOL-2001-039 (revised))}
%END LATEX
\title{%
%HEVEA WHIZARD 3.0 \\
%BEGIN LATEX
\ttt{\huge WHIZARD 3.0} \\[\baselineskip]
%END LATEX
A generic \\ Monte-Carlo integration and event generation package \\
for multi-particle processes\\[\baselineskip]
MANUAL
\footnote{%
This work is supported by Helmholtz-Alliance ``Physics at the
Terascale''.
In former stages this work has also been supported by
the Helmholtz-Gemeinschaft VH--NG--005 \\
E-mail: \ttt{whizard@desy.de}
}
\\[\baselineskip]
}
% \def\authormail{\ttt{kilian@physik.uni-siegen.de},
% \ttt{ohl@physik.uni-wuerzburg.de},
% \ttt{juergen.reuter@desy.de}, \ttt{cnspeckn@googlemail.com}}
\author{%
Wolfgang Kilian, %
Thorsten Ohl, %
J\"urgen Reuter, %
with contributions from
Fabian Bach, %
Simon Bra\ss, %
Pia Bredt, %
Bijan Chokouf\'{e} Nejad, %
Christian Fleper, %
Vincent Rothe, %
Sebastian Schmidt, %
Marco Sekulla, %
Christian Speckner, %
So Young Shim, %
Florian Staub, %
Pascal Stienemeier, %
Christian Weiss}
%BEGIN LATEX
\address{%
Universit\"at Siegen, Emmy-Noether-Campus, Walter-Flex-Str. 3,
D--57068 Siegen, Germany \\
Universit\"at W\"urzburg, Emil-Hilb-Weg 22,
D--97074 W\"urzburg, Germany \\
Deutsches Elektronen-Synchrotron DESY, Notkestr. 85,
D--22603 Hamburg, Germany \\
%% \authormail
\vspace{1cm}
\begin{center}
\includegraphics[width=4cm]{Whizard-Logo}
\end{center}
\mbox{} \\
\vspace{2cm}
\mbox{} when using \whizard\ please cite: \\
W. Kilian, T. Ohl, J. Reuter, \\ {\em WHIZARD: Simulating Multi-Particle
Processes at LHC and ILC}, \\
Eur.Phys.J.{\bf C71} (2011) 1742, arXiv:
0708.4233 [hep-ph]; \\
M. Moretti, T. Ohl, J. Reuter, \\ {\em O'Mega: An Optimizing Matrix
Element Generator}, \\
arXiv: hep-ph/0102195
}
%END LATEX
%BEGIN LATEX
\abstract{%
\whizard\ is a program system designed for the efficient calculation
of multi-particle scattering cross sections and simulated event
samples. The generated events can be written to file in various formats
(including HepMC, LHEF, STDHEP, LCIO, and ASCII) or analyzed directly on the
parton or hadron level using a built-in \LaTeX-compatible graphics
package.
\\[\baselineskip]
Complete tree-level matrix elements are generated automatically for arbitrary
partonic multi-particle processes by calling the built-in matrix-element
generator \oMega. Beyond hard matrix elements, \whizard\ can generate
(cascade) decays with complete spin correlations.
Various models beyond the SM are implemented, in particular,
the MSSM is supported with an interface to the SUSY Les Houches Accord
input format. Matrix elements obtained by alternative methods (e.g.,
including loop corrections) may be interfaced as well.
\\[\baselineskip]
The program uses an adaptive multi-channel method for phase space
integration, which allows to calculate numerically stable signal and
background cross sections and generate unweighted event samples with
reasonable efficiency for processes with up to eight and more
final-state particles. Polarization is treated exactly for both the
initial and final states. Quark or lepton flavors can be
summed over automatically where needed.
\\[\baselineskip]
For hadron collider physics, we ship the package with the most recent
PDF sets from the MSTW/MMHT and CTEQ/CT10/CJ12/CJ15/CT14
collaborations. Furthermore, an interface to the \lhapdf\ library is
provided.
\\[\baselineskip]
For Linear Collider physics,
beamstrahlung (\circeone, \circetwo), Compton and ISR spectra are
included for electrons and photons, including the most recent ILC and
CLIC collider designs. Alternatively, beam-crossing events can be read
directly from file.
\\[\baselineskip]
For parton showering and matching/merging with hard matrix elements ,
fragmenting and hadronizing the final state, a first version of two
different parton shower algorithms are included in the \whizard\
package. This also includes infrastructure for the MLM matching and
merging algorithm. For hadronization and hadronic decays, \pythia\
and \herwig\ interfaces are provided which follow the Les Houches
Accord. In addition, the last and final version of (\fortran) \pythia\
is included in the package.
\\[\baselineskip]
The \whizard\ distribution is available at
%%% \begin{center}
%%% \ttt{http://whizard.event-generator.org}
%%% \end{center}
%%% or at
\begin{center}
\url{https://whizard.hepforge.org}
\end{center}
where also the \ttt{svn} repository is located.
}
%END LATEX
%
\maketitle
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Text
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\begin{fmffile}
\tableofcontents
\newpage
\chapter{Introduction}
\section{Disclaimer}
\emph{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}
\begin{center}
\hepforgepage
\end{center}
\emph{or consult the current version in the \ttt{svn} repository
on \hepforgepage\ directly. Note, that the most recent version of
the manual might contain information about features of the
current \ttt{svn} version, which are not contained in the last
official release version!}
\emph{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 \ttt{share/examples} of the main directory where
\whizard\ is installed. More information about the examples can be
found on the \whizard\ Wiki page}
\begin{center}
\whizardwiki .
\end{center}
%%%%%
\clearpage
\section{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, \oMega\, 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.~\ref{chap:installation} 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.~\ref{chap:start}. This is following by an extensive, but rather
technical introduction into the steering language \sindarin\ in
Chap.~\ref{chap:sindarinintro}. 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.~\ref{chap:sindarin} 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
\begin{figure}[t]
\centering
\includegraphics[width=0.9\textwidth]{whizstruct}
\caption{General structure of the \whizard\ package.}
\end{figure}
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.~\ref{chap:hardint}. Then, in Chap.~\ref{chap:physics},
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 \oMega, 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.~\ref{chap:visualization} is a stand-alone documentation of
GAMELAN, the interal graphics support for the visualization of data
and analysis. The next chapter, Chap.~\ref{chap:userint} 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.~\ref{chap:examples}
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.~\ref{chap:tuning}. Then,
Chap.~\ref{chap:extmodels} 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 \url{whizard@desy.de}.
There is now also a support page on \texttt{Launchpad}, which offers
support that is easily visible for the whole user community:
\url{https://launchpad.net/whizard}.
%%%%%
\section{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: \ttt{WHiZard}, which stood for $\mathbf{W}$, {\bf H}iggs,
$\mathbf{Z}$, {\bf a}nd {\bf r}espective {\bf d}ecays.
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~\cite{VAMP}. The dedicated packages for the simulation of linear
lepton collider beamstrahlung and the option for a photon collider on
Compton backscattering (\ttt{CIRCE1/2}) date back even to mid
1996~\cite{CIRCE}. 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 \oMega\ 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 $p_T$ 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).
\newpage
{
{\bf \whizard\ \texttt{1}}, first line of development, ca. 1998-2010:
\nopagebreak[4]
\begin{center}
\begin{tabular}{|l|l|l|}\hline
0.99 & 08/1999 & Beta version \\\hline
1.00 & 12/2000 & First public version \\\hline
1.10 & 03/2001 & Libraries; \pythiasix\ interface \\
1.11 & 04/2001 & PDF support; anomalous couplings \\ \hline
1.20 & 02/2002 & \oMega\ matrix elements; \ttt{CIRCE} support\\
1.22 & 03/2002 & QED ISR; beam remnants, phase space improvements \\
1.25 & 05/2003 & MSSM; weighted events; user-code plug-in \\
1.28 & 04/2004 & Improved phase space; SLHA interface; signal catching
\\\hline
1.30 & 09/2004 & Major technical overhaul \\\hline
1.40 & 12/2004 & Asymmetric beams; decays; $p_T$ in structure
functions \\\hline
1.50 & 02/2006 & QCD support in \oMega\ (color flows); LHA format \\
1.51 & 06/2006 & $Hgg$, $H\gamma\gamma$; Spin 3/2 + 2; BSM models
\\\hline
1.90 & 11/2007 & \oMega\ included; LHAPDF support; $Z'$; $WW$ scattering \\
1.92 & 03/2008 & LHE format; UED; parton shower beta version \\
1.93 & 04/2009 & NMSSM; SLHA2 accord; improved color/flavor sums \\
1.95 & 02/2010 & MLM matching; development stop in version 1
\\
1.97 & 05/2011 & Manual for version 1 completed. \\\hline\hline
\end{tabular}
\end{center}
}
\vspace{2cm}
{
{\bf \whizard\ \texttt{2.0-2.2}}: first major refactoring and early new
release, ca. 2007-2015:
\nopagebreak[4]
\begin{center}
\begin{tabular}{|l|l|l|}\hline
2.0.0 & 04/2010 & Major refactoring: automake setup; dynamic
libraries \\
& & improved speed; cascades; OpenMP; \sindarin\ steering language \\
2.0.3 & 07/2010 & QCD ISR+FSR shower; polarized beams \\
2.0.5 & 05/2011 & Builtin PDFs; static builds; relocation scripts \\
2.0.6 & 12/2011 & Anomalous top couplings; unit tests \\\hline
2.1.0 & 06/2012 & Analytic ISR+FSR parton shower; anomalous Higgs
couplings \\\hline
2.2.0 & 05/2014 & Major technical refactoring: abstract
object-orientation; THDM; \\
& & reweighting; LHE v2/3; BLHA; HOPPET interface; inclusive
processes \\
2.2.1 & 05/2014 & CJ12 PDFs; FastJet interface \\
2.2.2 & 07/2014 & LHAPDF6 support; correlated LC beams; GuineaPig
interface \\
2.2.3 & 11/2014 & O'Mega virtual machine; lepton collider top
pair threshold; \\
& & Higgs singlet extension \\
2.2.4 & 02/2015 & LCIO support; progress on NLO; many technical
bug fixes \\
2.2.7 & 08/2015 & progress on POWHEG; fixed-order NLO events; \\
& & revalidation of ILC event chain \\
2.2.8 & 11/2015 & support for quadruple precision; StdHEP included; \\
& & SM dim 6 operators supported
\\\hline
\end{tabular}
\end{center}
}
\newpage
{
{\bf \whizard\ \texttt{2.3-2.8}}, completion of refactoring, continuous
development, ca. 2015-2020:
\nopagebreak[4]
\begin{center}
\begin{tabular}{|l|l|l|}\hline
2.3.0 & 07/2016 & NLO: resonance mappings for FKS subtraction; \\
& & more advanced cascade syntax; \\
& & GUI ($\alpha$ version); UFO support
($\alpha$ version); ILC v1.9x-v2.x final validation \\
2.3.1 & 08/2016 & Complex mass scheme
\\\hline
2.4.0 & 11/2016 & Refactoring of NLO setup \\
2.4.1 & 03/2017 & $\alpha$ version of new VEGAS implementation
\\\hline
2.5.0 & 05/2017 & Full UFO support (SM-like models)
\\\hline
2.6.0 & 09/2017 & MPI parallel integration and event generation;
resonance histories \\
& & for showers; RECOLA support \\
2.6.1 & 11/2017 & EPA/ISR transverse distributions, handling of
shower resonances; \\
& & more efficient (alternative) phase space generation \\
2.6.2 & 12/2017 & $Hee$ coupling, improved resonance matching \\
2.6.3 & 02/2018 & Partial NLO refactoring for quantum numbers, \\
& & unified RECOLA 1/2 interface. \\
2.6.4 & 08/2018 & Gridpack functionality; Bug fixes: color flows,
HSExt model, MPI setup
\\\hline
2.7.0 & 01/2019 & PYTHIA8 interface, process setup refactoring,
RAMBO PS option; \\
& & \quad gfortran 5.0+ necessary
\\\hline
2.8.0 & 08/2019 & (Almost) complete UFO support, general Lorentz
structures, n-point vertices \\
2.8.1 & 09/2019 & HepMC3, NLO QCD pp (almost)
complete, b/c jet selection, photon isolation \\
2.8.2 & 10/2019 & Support for OCaml $\geq$ 4.06.0, UFO Spin-2 support,
LCIO alternative weights \\
2.8.3 & 07/2020 & UFO Majorana feature complete, many $e^+e^-$ related
improvements \\
2.8.4 & 07/2020 & Bug fix for UFO Majorana models \\
2.8.5 & 09/2020 & Bug fix for polarizations in $H\to\tau\tau$
\\\hline\hline
\end{tabular}
\end{center}
}
\vspace{2cm}
{
{\bf \whizard\ \texttt{3.0}} and onwards, the NLO series:
\nopagebreak[4]
\begin{center}
\begin{tabular}{|l|l|l|}\hline
3.0.0 & 04/2021 & NLO QCD automation \& UFO Majorana support
released
\\
3.0.1 & 07/2021 & MPI load balancer, rescan of ILC mass production
samples
\\\hline\hline
\end{tabular}
\end{center}
}
\vspace{.5cm}
For a detailed overview over the historical development of the code
confer the \ttt{ChangeLog} file and the commit messages in our
revision control system repository.
\newpage
%%%%%
\section{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^- \to \mu^+ \mu^-$. This is the same process, the
textbook by Peskin/Schroeder \cite{PeskinSchroeder} 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).
\newpage
\chapter{Installation}
\label{chap:installation}
\section{Package Structure}
\whizard\ is a software package that consists of a main executable
program (which is called \ttt{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 (\ttt{/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 \ttt{make} and PERL scripts. These
constraints are gone in the present version in favor of a clean
separation of installation and runtime workspace.
\section{\label{sec:prerequisites}Prerequisites}
\subsection{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:
\url{https://whizard.hepforge.org/versions/install/install-whizard-2.X.X.sh}.
Download this shell script, make it executable by
\begin{interaction}
chmod +x install-whizard-2.X.X.sh
\end{interaction}
and execute it. Note that this also involves compilation of the
required \fortran\ compiler which takes 1-3 hours depending on
your system.
\ttt{Darwin} operating systems (a.k.a. as \ttt{Mac OS X}) have a very
similar general system for all sorts of software, called
\ttt{MacPorts} (\url{http://www.macports.org}). This offers to install
\whizard\ as one of its software ports, and is very similar to
``instant WHIZARD'' described above.
\subsection{Tarball Distribution}
\label{sec:tarballdistr}
This is the recommended way of obtaining \whizard. You may download
the current stable distribution from the \whizard\ webpage,
hosted at the HepForge webpage
\begin{quote}
\hepforgepage
\end{quote}
The distribution is a single file, say \ttt{whizard-\thisversion.tgz} for
version \thisversion.
You need the additional prerequisites:
\begin{itemize}
\item
GNU \ttt{tar} (or \ttt{gunzip} and \ttt{tar}) for unpacking the
tarball.
\item
The \ttt{make} utility. Other standard Unix utilities (\ttt{sed},
\ttt{grep}, etc.) are usually installed by default.
\item
A modern \fortran\ compiler (see Sec.~\ref{sec:compilers} for
details).
\item
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
\begin{quote}
\url{http://caml.inria.fr}
\end{quote}
and install it yourself. If desired, the package can be installed
in user space without administrator privileges\footnote{
Unfortunately, the version of the \ocaml\
compiler from 3.12.0 broke backwards compatibility. Therefore,
versions of \oMega/\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.~\ref{sec:buildproblems}. \whizard\ versions up to 2.7.1 were
still backwards compatible with \ocaml\ 3.12.0}.
\end{itemize}
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.
\begin{itemize}
\item
\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.
\item
The \lhapdf\ structure-function library. See
Sec.~\ref{sec:lhapdf_install}.
\item
The \hoppet\ structure-function matching tool. See
Sec.~\ref{sec:hoppet}.
\item
The \hepmc\ event-format package. See Sec.~\ref{sec:hepmc}.
\item
The \fastjet\ jet-algorithm package. See Sec.~\ref{sec:fastjet}.
\item
The \lcio\ event-format package. See Sec.~\ref{sec:lcio}.
\end{itemize}
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.~\ref{sec:stdhep},
particularly on the need to install the \ttt{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
\begin{quote}\small\tt
some-directory> tar xzf whizard-\thisversion.tgz
\end{quote}
and proceed.\footnote{Without GNU \ttt{tar}, this would read
\ttt{\small gunzip -c whizard-\thisversion.tgz | tar xz -}}
For using external physics models that are directly supported by
\whizard\ and \oMega, the user can use tools like \sarah\ or
\FeynRules. There installation and linking to \whizard\ will be
explained in Chap.~\ref{chap:extmodels}. 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 \ttt{whizard-\thisversion}
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.
%%%%%
\subsection{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:
\begin{itemize}
\item
The \ttt{subversion} package (\ttt{svn}), the tool for dealing with
SVN repositories.
\item
The \ttt{autoconf} package, part of the \ttt{autotools} development
system. \ttt{automake} is needed with version \ttt{1.12.2} or newer.
\item
The \ttt{noweb} package, a light-weight tool for literate programming. This
package is nowadays often part of Linux distributions\footnote{In
Ubuntu from version 10.04 on, and in Debian since
squeeze. For \ttt{Mac OS X}, \ttt{noweb} is available via the
\ttt{MacPorts} system.}. You can obtain the source code
from\footnote{Please, do not use any of the binary builds from this
webpage. Probably all of them are quite old and broken.}
\begin{quote}
\url{http://www.cs.tufts.edu/~nr/noweb/}
\end{quote}
\end{itemize}
To start, go to a directory of your choice and execute
\begin{interaction}
your-src-directory> svn checkout
svn+ssh://vcs@phab.hepforge.org/source/whizardsvn/trunk \;\; .
\end{interaction}
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
\begin{interaction}
your-src-directory> svn update
\end{interaction}
within that directory.
After checking out the sources, you first have to create
\ttt{configure.ac} by executing the shell script
\ttt{build\_master.sh}. In order to build the \ttt{configure}
script, the \ttt{autotools} package \ttt{autoreconf} has to be run. On
some \ttt{Unix} systems the \ttt{RPC} headers needed for the legacy
support of the \stdhep\ event format are provided by the \ttt{TIRPC}
library (cf. Sec.~\ref{sec:stdhep}). To easily check for them,
\ttt{configure.ac} processed by \ttt{autoreconf} makes use of the
\ttt{pkg-config} tool which needs to be installed for the developer
version. So now, run\footnote{At least, version
2.65 of the \ttt{autoconf} package is required.}
\begin{interaction}
your-src-directory> autoreconf
\end{interaction}
This will generate a \ttt{configure} script.
%%%%%
\subsection{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
\begin{quote}
\url{https://gitlab.tp.nt.uni-siegen.de/whizard/public}
\end{quote}
Cloning via HTTPS brings the user to the same change as the SVN
checkout from HepForge described in the previous subsection:
\begin{quote}
git clone https://gitlab.tp.nt.uni-siegen.de/whizard/public.git
\end{quote}
The next steps are the same as described in the previous subsection.
%%%%%
\subsection{Nightly development snapshots}
Nightly development snapshots that are pre-packaged in the same way
as an official distribution are available from
\begin{quote}
\url{https://whizard.tp.nt.uni-siegen.de/}
\end{quote}
Building \whizard\ works the way as described in
Sec.~\ref{sec:tarballdistr}.
%%%%%
\subsection{\label{sec:compilers}Fortran Compilers}
\whizard\ is written in modern \fortran. To be precise, it uses a
subset of the \fortranOThree\ standard. At the time of this writing,
this subset is supported by, at least, the following compilers:
\begin{itemize}
\item
\ttt{gfortran} (GNU, Open Source). You will need version 5.1.0
or higher\footnote{Note that \whizard\ versions 2.0.0 until 2.3.1 compiled
with \ttt{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 \ttt{gfortran} 4.8.4 or higher necessary. In the
same way, since version 2.7.0, \ttt{gfortran} 5.1.0 or newer is
needed}. We recommend to use at least version 5.4 or higher, as
especially the the early version of the \texttt{gfortran} experience
some bugs. \ttt{gfortran} 6.5.0 has a severe regression and cannot
be used.
\item
\ttt{nagfor} (NAG). You will need version 6.2 or higher.
\item
\ttt{ifort} (Intel). You will need version 19.0.2 or
higher
\end{itemize}
%%%%%
\subsection{LHAPDF}
\label{sec:lhapdf_install}
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.~\ref{sec:built-in-pdf}. 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 required\footnote{ Note that
PDF sets which contain photons as partons are only supported with
\whizard\ for \lhapdf\ version 5.7.1 or higher}. The \lhapdf\
package has undergone a major rewriting from \fortran\ version 5
to \cpp\ 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
\begin{quote}
\url{https://lhapdf.hepforge.org}
\end{quote}
for the most recent LHAPDF version 6 and newer, or
\begin{quote}
\url{https://lhapdf.hepforge.org/lhapdf5}
\end{quote}
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 \cpp\ compiler.
During \whizard\ configuration, \whizard\ looks for the script
\ttt{lhapdf} (which is present in \lhapdf\ series 6) first, and then
for \ttt{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 \ttt{configure}
output (for \lhapdf\ version 6 or newer),
\begin{footnotesize}
\begin{verbatim}
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: --------------------------------------------------------------
\end{verbatim}
\end{footnotesize}
while for \lhapdf\ version 5 and older it looks like this:
\begin{footnotesize}
\begin{verbatim}
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: --------------------------------------------------------------
\end{verbatim}
\end{footnotesize}
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 \ttt{lhapdf} (and/or \ttt{lhapdf-config}) scripts in an
executable path that is checked before the system paths,
e.g. \ttt{<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:
\begin{footnotesize}
\begin{verbatim}
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: --------------------------------------------------------------
\end{verbatim}
\end{footnotesize}
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
\ttt{config.log}.
If \lhapdf\ is installed in a non-default directory where
\whizard\ would not find it, set the environment variable
\ttt{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 \ttt{CT10} set for \lhapdf\ version
6 (for version 5, \ttt{cteq61.LHpdf}, \ttt{cteq6ll.LHpdf},
\ttt{cteq5l.LHgrid}, and \ttt{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 \ttt{has\_photon} flag, which tests whether photon
PDFs are available in the found \lhapdf\ installation.
%%%%%
\subsection{HOPPET}
\label{sec: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):
\begin{interaction}
your-build-directory> your-src-directory/configure --enable-hoppet
\end{interaction}
If you \ttt{configure} messages like the following:
\begin{footnotesize}
\begin{verbatim}
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: --------------------------------------------------------------
\end{verbatim}
\end{footnotesize}
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
\begin{interaction}
HOPPET=<hoppet\_directory>/lib
\end{interaction}
to the \ttt{configure} options above. For more details, please confer
the \hoppet\ manual.
%%%%%
\subsection{HepMC}
\label{sec: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 \cpp\ 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:
\begin{quote}
\url{http://hepmc.web.cern.ch/hepmc/}
\end{quote}
or
\begin{quote}
\url{http://hepmc.web.cern.ch/hepmc/}
\end{quote}
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
\cpp\ compiler. Then the procedure is the same as for the
\whizard\ package, namely configure HepMC:
\begin{interaction}
configure --with-momentum=GEV --with-length=MM --prefix=<install dir>
\end{interaction}
Note that the particle momentum and decay length flags are mandatory, and
we highly recommend to set them to the values \ttt{GEV} and \ttt{MM},
respectively. After configuration, do \ttt{make}, an optional
\ttt{make check} (which might sometimes fail for non-standard values
of momentum and length), and finally \ttt{make install}.
The latest version of \hepmc\ (2.6.10) as well as the new relase
series use \texttt{cmake} for their build process. For more
information, confer the \hepmc\ webpage.
A \whizard\ configuration for \hepmc\ looks like this:
\begin{footnotesize}
\begin{verbatim}
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: --------------------------------------------------------------
\end{verbatim}
\end{footnotesize}
If \hepmc\ is installed in a non-default directory where \whizard\
would not find it, set the environment variable \ttt{HEPMC\_DIR} to
the correct installation path when configuring \whizard. Furthermore,
the environment variable \ttt{CXXFLAGS} allows you to set specific
\ttt{C/C++} preprocessor flags, e.g. non-standard include paths for
header files.
A typical configuration of \hepmcthree\ will look like this:
\begin{footnotesize}
\begin{verbatim}
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: --------------------------------------------------------------
\end{verbatim}
\end{footnotesize}
As can be seen, \whizard\ will check for the \ROOT\ environment as
well as whether \hepmcthree\ has been built with support for the
\ROOT\ and \ttt{RootTree} writer classes. This is an easy option to
use \whizard\ to write out \ROOT\ events. For more information see
Sec.~\ref{sec:root}.
%%%%%
\subsection{PYTHIA6}
\label{sec:pythia6_conf}
The \whizard\ package ships with the final version of the old
\pythiasix\ 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.
\begin{quote}
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)
\end{quote}
\whizard\ automatically compiles \pythiasix, it has not to be
specifically enabled by the user.
In order to properly use \pythiasix\ 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:
\begin{quote}
\ttt{--enable-pythia6\_ep}
\end{quote}
Those settings have been provided by~\cite{UtaKlein}.
%%%%%
\subsection{PYTHIA8}
\label{sec:pythia8}
\pythiaeight\ is a \cpp\ 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 \pythiaeight,
otherwise you can skip this section.
If it is not already installed on your system, you may obtain
\pythiaeight\ from
\begin{quote}
\url{http://home.thep.lu.se/~torbjorn/Pythia.html}
\end{quote}
If the \pythiaeight\ 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 \pythiaeight\ installation to \whizard, you should specify the flag
\begin{quote}
\ttt{--enable-pythia8}
\end{quote}
to \ttt{configure}. If \pythiaeight\ is installed in a non-default directory
where \whizard\ would not find it, specify also
\begin{quote}
\ttt{--with-pythia8=\emph{<your-pythia8-installation-path>}}
\end{quote}
A successful \whizard\ configuration should produce a screen output
similar to this:
\begin{footnotesize}
\begin{verbatim}
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: --------------------------------------------------------------
\end{verbatim}
\end{footnotesize}
%%%%%
\subsection{FastJet}
\label{sec:fastjet}
\fastjet\ is a \cpp\ 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
\begin{quote}
\url{http://fastjet.fr}
\end{quote}
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
\begin{quote}
\ttt{--enable-fastjet}
\end{quote}
to \ttt{configure}. If \fastjet\ is installed in a non-default directory
where \whizard\ would not find it, specify also
\begin{quote}
\ttt{--with-fastjet=\emph{<your-fastjet-installation-path>}}
\end{quote}
A successful \whizard\ configuration should produce a screen output
similar to this:
\begin{footnotesize}
\begin{verbatim}
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: --------------------------------------------------------------
\end{verbatim}
\end{footnotesize}
Note that when compiling on Darwin/macOS it might be necessary to
set the option \ttt{--disable-auto-ptr} when compiling with
\ttt{clang++}.
%%%%%
\subsection{STDHEP}
\label{sec:stdhep}
\stdhep\ is a library for handling collider scattering
events~\cite{stdhep}. 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 (\ttt{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 \ttt{mcfio} framework makes use of the \ttt{RPC}
headers. These come -- provided by \ttt{SunOS/Oracle America, Inc.} --
together with the system headers, but on some \ttt{Unix} systems
(e.g. \ttt{ArchLinux}, \ttt{Fedora}) have been replaced by the
\ttt{libtirpc} headers . The \ttt{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:
\begin{footnotesize}
\begin{verbatim}
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: --------------------------------------------------------------
\end{verbatim}
\end{footnotesize}
%%%%%
\subsection{LCIO}
\label{sec:lcio}
\lcio\ is a \cpp\ 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:
\begin{quote}
\url{http://lcio.desy.de}
\end{quote}
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
\cpp\ compiler. \lcio\ is based on \ttt{cmake}. For the
corresponding options please confer the \lcio\ manual.
A \whizard\ configuration for \lcio\ looks like this:
\begin{footnotesize}
\begin{verbatim}
configure: --------------------------------------------------------------
configure: --- LCIO ---
configure:
checking the LCIO version... 2.12.1
checking for LCEventImpl class in -llcio... yes
configure: --------------------------------------------------------------
\end{verbatim}
\end{footnotesize}
If \lcio\ is installed in a non-default directory where \whizard\
would not find it, set the environment variable \ttt{LCIO} or
\ttt{LCIO\_DIR} to the correct installation path when configuring
\whizard. The first one is the variable exported by the
\ttt{setup.sh} script while the second one is analogous to the
environment variables of other external packages. \ttt{LCIO} takes
precedence over \ttt{LCIO\_DIR}. Furthermore, the environment variable
\ttt{CXXFLAGS} allows you to set specific \ttt{C/C++} preprocessor
flags, e.g. non-standard include paths for header files.
%%%%%
\section{Installation}
\label{sec:installation}
Once you have unpacked the source (either the tarball or the SVN
version), you are ready to compile it. There are several options.
\subsection{Central Installation}
This is the default and recommended way, but it requires adminstrator
privileges. Make sure that all
prerequisites are met (Sec.~\ref{sec:prerequisites}).
\begin{enumerate}
\item
Create a fresh directory for the \whizard\ build. It is recommended
to keep this separate from the source directory.
\item
Go to that directory and execute
\begin{interaction}
your-build-directory> your-src-directory/configure
\end{interaction}
This will analyze your system and prepare the compilation of \whizard\
in the build directory. Make sure to set the proper options to
\ttt{configure}, see Sec.~\ref{sec:configure-options} below.
\item
Call \ttt{make} to compile and link \whizard:
\begin{interaction}
your-build-directory> make
\end{interaction}
\item
If you want to make sure that everything works, run
\begin{interaction}
your-build-directory> make check
\end{interaction}
This will take some more time.
\item
Become superuser and say
\begin{interaction}
your-build-directory> make install
\end{interaction}
\end{enumerate}
\whizard\ should now installed in the default locations, and the
executable should be available in the standard path. Try to call
\ttt{whizard --help} in order to check this.
\subsection{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.~\ref{sec:prerequisites}).
\begin{enumerate}
\item
Create a fresh directory for the \whizard\ build. It is recommended
to keep this separate from the source directory.
\item
Reserve a directory in user space for the \whizard\ installation.
It should be empty, or yet non-existent.
\item
Go to that directory and execute
\begin{interaction}
your-build-directory> your-src-directory/configure
--prefix=your-install-directory
\end{interaction}
This will analyze your system and prepare the compilation of \whizard\
in the build directory. Make sure to set the proper additional options to
\ttt{configure}, see Sec.~\ref{sec:configure-options} below.
\item
Call \ttt{make} to compile and link \whizard:
\begin{interaction}
your-build-directory> make
\end{interaction}
\item
If you want to make sure that everything works, run
\begin{interaction}
your-build-directory> make check
\end{interaction}
This will take some more time.
\item
Install:
\begin{interaction}
your-build-directory> make install
\end{interaction}
\end{enumerate}
\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.~\ref{sec:workspace}.
\subsection{Configure Options}
\label{sec:configure-options}
The configure script accepts environment variables and flags. They
can be given as arguments to the \ttt{configure} program in arbitrary
order. You may run \ttt{configure --help} for a listing; only the
last part of this long listing is specific for the \whizard\ system.
Here is an example:
\begin{interaction}
configure FC=gfortran-5.4 FCFLAGS="-g -O3" --enable-fc-openmp
\end{interaction}
The most important options are
\begin{itemize}
\item
\ttt{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.
\item
\ttt{FCFLAGS} (variable): The flags to be given to the \fortran\
compiler. The main use is to control the level of optimization.
\item
\ttt{--prefix=\var{directory-name}}: Specify a non-default directory
for installation.
\item
\ttt{--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., \ttt{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.~\ref{sec:openmp} for
further details.
\item
\ttt{--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. \ttt{OpenMPI}) and \ttt{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 \ttt{--enable-fc-openmp}. See Sec.~\ref{sec:mpi}
for further details.
\item
\ttt{LHADPF\_DIR} (variable): The location of the optional \lhapdf\
package, if non-default.
\item
\ttt{LOOPTOOLS\_DIR} (variable): The location of the optional \ttt{LOOPTOOLS}
package, if non-default.
\item
\ttt{OPENLOOPS\_DIR} (variable): The location of the optional \openloops\
package, if non-default.
\item
\ttt{GOSAM\_DIR} (variable): The location of the optional \gosam\
package, if non-default.
\item
\ttt{HOPPET\_DIR} (variable): The location of the optional \hoppet\
package, if non-default.
\item
\ttt{HEPMC\_DIR} (variable): The location of the optional \hepmc\ package, if
non-default.
\item
\ttt{LCIO}/\ttt{LCIO\_DIR} (variable): The location of the optional
\lcio\ package, if non-default.
\end{itemize}
Other flags that might help to work around possible problems are the
flags for the $C$ and \cpp\ compilers as well as the \ttt{Fortran77}
compiler, or the linker flags and additional libraries for the linking
process.
\begin{itemize}
\item
\ttt{CC} (variable): \ttt{C} compiler command
\item
\ttt{F77} (variable): \ttt{Fortran77} compiler command
\item
\ttt{CXX} (variable): \ttt{C++} compiler command
\item
\ttt{CPP} (variable): \ttt{C} preprocessor
\item
\ttt{CXXCPP} (variable): \ttt{C++} preprocessor
\item
\ttt{CFLAGS} (variable): \ttt{C} compiler flags
\item
\ttt{FFLAGS} (variable): \ttt{Fortran77} compiler flags
\item
\ttt{CXXFLAGS} (variable): \ttt{C++} compiler flags
\item
\ttt{LIBS} (variable): libraries to be passed to the linker as
\ttt{-l{\em library}}
\item
\ttt{LDFLAGS} (variable): non-standard linker flags
\end{itemize}
For other options (like e.g. \ttt{--with-precision=...} etc.) please
see the \ttt{configure --help} option.
%%%%%
\subsection{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 \ttt{HepMC}.
Finally, all the Makefiles are being built.
The compilation is done by invoking \ttt{make} and finally
\ttt{make install}. You could also do a \ttt{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 \ttt{make install}
procedure. Also please avoid using \ttt{make -j} options of parallel
execution of \ttt{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
\url{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
\ttt{Fortran77} code. These parts should better be
compiled with the very same \ttt{Fortran2003} compiler as the
\whizard\ core. There is, however, one subtlety:
when the \ttt{configure} flag \ttt{FC} gets a full system path as
argument, \ttt{libtool} is not able to recognize this as a valid (GNU)
\ttt{Fortran77} compiler. It then searches automatically for binaries
like \ttt{f77}, \ttt{g77} etc. or a standard system compiler. This
might result in a compilation failure of the \ttt{Fortran77} code. A
viable solution is to define an executable link and use this (not the
full path!) as \ttt{FC} flag.
It is possible to compile \whizard\ without the \ocaml\ parts of
\oMega, namely by using the \ttt{--disable-omega} option of the
configure. This will result in a built of \whizard\ with the \oMega\
\fortran\ library, but without the binaries for the matrix element
generation. All selftests (cf. \ref{sec:selftests}) requiring \oMega\
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 \ttt{make distxxx} targets) will fail.
%%%%%%%%%%%
\subsection{Building on Darwin/macOS}
The easiest way to build \whizard\ on Darwin/macOS is to install the
complete GNU compiler suite (\ttt{gcc/g++/gfortran}). This can be done
with one of the code repositories like \ttt{MacPorts}, \ttt{HomeBrew}
or \ttt{Fink}. In order to include \ROOT\ which natively should be
built using the intrinsic \ttt{clang/clang++} for the graphics
support, there is also the possibility to build external tools like
\hepmcthree, \pythiaeight, \fastjet, and \lcio\ with \ttt{clang++},
and set in the configure option for \whizard\ \ttt{C} and \ttt{C++}
compiler accordingly:
\begin{quote}
../configure CC=clang CXX=clang++ [...]
\end{quote}
Note that \fastjet\ might need to be configured with the
\ttt{--disable-auto-ptr} option when compiling with \ttt{clang++}
and strict \ttt{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 \ttt{csrutil
disable}. However, we do not recommend to do so.
%%%%%%%%%%%
\subsection{Building on Windows}
For Windows, from \ttt{Windows 10} onwards, there is the possibility
to install and use an underlying Linux operating system,
e.g. \ttt{Ubuntu}. Installation and usage of \whizard\ works then the
same way as described above.
%%%%%%%%%%%
\subsection{\whizard\ self tests/checks}
\label{sec:selftests}
\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
\ttt{make check} from the \ttt{build} directory. If \ttt{src}
and \ttt{build} directories are the same, all relevant files for
these self-tests reside in the \ttt{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 \ttt{src}
and \ttt{build} directory are different as recommended, then the
input files will have been installed in
\ttt{prefix/share/whizard/test}, while the corresponding test shell
scripts remain in the \ttt{srcdir/test} directory. As the main shell
script \ttt{run\_whizard.sh} has been built in the \ttt{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.
\ttt{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 \ttt{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 (\ttt{whizard@desy.de}) and provide them with the logfiles
of the failing test as well as the setup of your configuration.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage
\chapter{Working with \whizard}
\label{chap:start}
\whizard\ can run as a stand-alone program. You (the user) can steer
\whizard\ either interactively or by a script file. We will first
describe the latter method, since it will be the most common way to
interact with the \whizard\ system.
\section{Hello World}
The legacy version series 1 of the program relied on a bunch of input
files that the user had to provide in some obfuscated format. This
approach is sufficient for straightforward applications. However, once
you get experienced with a program, you start thinking about uses that
the program's authors did not foresee. In case of a Monte Carlo
package, typical abuses are parameter scans, complex patterns of cuts
and reweighting factors, or data analysis without recourse to external
packages. This requires more flexibility.
Instead of transferring control over data input to some generic
scripting language like \ttt{PERL} or \python\ (or even \cpp), which
come with their own peculiarities and learning curves, we decided to
unify data input and scripting in a dedicated steering language that
is particularly adapted to the needs of Monte-Carlo integration,
simulation, and simple analysis of the results. Thus we discovered
what everybody knew anyway: that W(h)izards communicate in \sindarin,
Scripting INtegration, Data Analysis, Results display and INterfaces.
\sindarin\ is a DSL -- a domain-specific scripting language -- that is
designed for the single purpose of steering and talking to \whizard.
Now since \sindarin\ is a programming language, we honor the old
tradition of starting with the famous Hello World program. In
\sindarin\ this reads simply
\begin{quote}
\begin{verbatim}
printf "Hello World!"
\end{verbatim}
\end{quote}
Open your favorite editor, type this text, and save it into a file
named \verb|hello.sin|.
\begin{figure}
\centering
\begin{scriptsize}
\begin{Verbatim}[frame=single]
| Writing log to 'whizard.log'
|=============================================================================|
| |
| WW WW WW WW WW WWWWWW WW WWWWW WWWW |
| WW WW WW WW WW WW WW WWWW WW WW WW WW |
| WW WW WW WW WWWWWWW WW WW WW WW WWWWW WW WW |
| WWWW WWWW WW WW WW WW WWWWWWWW WW WW WW WW |
| WW WW WW WW WW WWWWWW WW WW WW WW WWWW |
| |
| |
| W |
| sW |
| WW |
| sWW |
| WWW |
| wWWW |
| wWWWW |
| WW WW |
| WW WW |
| wWW WW |
| wWW WW |
| WW WW |
| WW WW |
| WW WW |
| WW WW |
| WW WW |
| WW WW |
| wwwwww WW WW |
| WWWWWww WW WW |
| WWWWWwwwww WW WW |
| wWWWwwwwwWW WW |
| wWWWWWWWWWWwWWW WW |
| wWWWWW wW WWWWWWW |
| WWWW wW WW wWWWWWWWwww |
| WWWW wWWWWWWWwwww |
| WWWW WWWW WWw |
| WWWWww WWWW |
| WWWwwww WWWW |
| wWWWWwww wWWWWW |
| WwwwwwwwwWWW |
| |
| |
| |
| by: Wolfgang Kilian, Thorsten Ohl, Juergen Reuter |
| with contributions from Christian Speckner |
| Contact: <whizard@desy.de> |
| |
| if you use WHIZARD please cite: |
| W. Kilian, T. Ohl, J. Reuter, Eur.Phys.J.C71 (2011) 1742 |
| [arXiv: 0708.4233 [hep-ph]] |
| M. Moretti, T. Ohl, J. Reuter, arXiv: hep-ph/0102195 |
| |
|=============================================================================|
| WHIZARD 3.0.1
|=============================================================================|
| Reading model file '/usr/local/share/whizard/models/SM.mdl'
| Preloaded model: SM
| Process library 'default_lib': initialized
| Preloaded library: default_lib
| Reading commands from file 'hello.sin'
Hello World!
| WHIZARD run finished.
|=============================================================================|
\end{Verbatim}
\end{scriptsize}
\caption{Output of the \ttt{"Hello world!"} \sindarin\ script.\label{fig:helloworld}}
\end{figure}
Now we assume that you -- or your kind system administrator -- has
installed \whizard\ in your executable path. Then you should open a
command shell and execute (we will come to the meaning of the
\verb|-r| option later.)
\begin{verbatim}
/home/user$ whizard -r hello.sin
\end{verbatim}
and if everything works well, you get the output (the complete output
including the \whizard\ banner is shown in Fig.~\ref{fig:helloworld})
\begin{footnotesize}
\begin{verbatim}
| Writing log to 'whizard.log'
\end{verbatim}
\centerline{[... here a banner is displayed]}
\begin{Verbatim}
|=============================================================================|
| WHIZARD 3.0.1
|=============================================================================|
| Reading model file '/usr/local/share/whizard/models/SM.mdl'
| Preloaded model: SM
! Process library 'default_lib': initialized
! Preloaded library: default_lib
| Reading commands from file 'hello.sin'
Hello World!
| WHIZARD run finished.
|=============================================================================|
\end{Verbatim}
\end{footnotesize}
If this has just worked for you, you can be confident that you have a working
\whizard\ installation, and you have been able to successfully run the
program.
\section{A Simple Calculation}
You may object that \whizard\ is not exactly designed for printing out
plain text. So let us demonstrate a more useful example.
Looking at the Hello World output, we first observe that the program
writes a log file named (by default) \verb|whizard.log|. This file
receives all screen output, except for the output of external programs
that are called by \whizard. You don't have to cache \whizard's screen
output yourself.
After the welcome banner, \whizard\ tells you that it reads a physics
\emph{model}, and that it initializes and preloads a \emph{process library}. The
process library is initially empty. It is ready for receiving
definitions of elementary high-energy physics processes (scattering or
decay) that you provide. The processes are set in the context of a
definite model of high-energy physics. By default this is the
Standard Model, dubbed \verb|SM|.
Here is the \sindarin\ code for defining a SM physics process, computing
its cross section, and generating a simulated event sample in Les Houches
event format:
\begin{quote}
\begin{Verbatim}
process ee = e1, E1 => e2, E2
sqrts = 360 GeV
n_events = 10
sample_format = lhef
simulate (ee)
\end{Verbatim}
\end{quote}
As before, you save this text in a file (named, e.g.,
\verb|ee.sin|) which is run by
\begin{verbatim}
/home/user$ whizard -r ee.sin
\end{verbatim}
(We will come to the meaning of the \verb|-r| option later.)
This produces a lot of output which looks similar to this:
\begin{footnotesize}
\begin{verbatim}
| Writing log to 'whizard.log'
[... banner ...]
|=============================================================================|
| WHIZARD 3.0.1
|=============================================================================|
| Reading model file '/usr/local/share/whizard/models/SM.mdl'
| Preloaded model: SM
| Process library 'default_lib': initialized
| Preloaded library: default_lib
| Reading commands from file 'ee.sin'
| Process library 'default_lib': recorded process 'ee'
sqrts = 3.600000000000E+02
n_events = 10
\end{verbatim}
\begin{verbatim}
| Starting simulation for process 'ee'
| Simulate: process 'ee' needs integration
| Integrate: current process library needs compilation
| Process library 'default_lib': compiling ...
| Process library 'default_lib': writing makefile
| Process library 'default_lib': removing old files
rm -f default_lib.la
rm -f default_lib.lo default_lib_driver.mod opr_ee_i1.mod ee_i1.lo
rm -f ee_i1.f90
| Process library 'default_lib': writing driver
| Process library 'default_lib': creating source code
rm -f ee_i1.f90
rm -f opr_ee_i1.mod
rm -f ee_i1.lo
/usr/local/bin/omega_SM.opt -o ee_i1.f90 -target:whizard
-target:parameter_module parameters_SM -target:module opr_ee_i1
-target:md5sum '70DB728462039A6DC1564328E2F3C3A5' -fusion:progress
-scatter 'e- e+ -> mu- mu+'
[1/1] e- e+ -> mu- mu+ ... allowed. [time: 0.00 secs, total: 0.00 secs, remaining: 0.00 secs]
all processes done. [total time: 0.00 secs]
SUMMARY: 6 fusions, 2 propagators, 2 diagrams
| Process library 'default_lib': compiling sources
[.....]
\end{verbatim}
\begin{verbatim}
| Process library 'default_lib': loading
| Process library 'default_lib': ... success.
| Integrate: compilation done
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 9616
| Initializing integration for process ee:
| ------------------------------------------------------------------------
| Process [scattering]: 'ee'
| Library name = 'default_lib'
| Process index = 1
| Process components:
| 1: 'ee_i1': e-, e+ => mu-, mu+ [omega]
| ------------------------------------------------------------------------
| Beam structure: [any particles]
| Beam data (collision):
| e- (mass = 5.1099700E-04 GeV)
| e+ (mass = 5.1099700E-04 GeV)
| sqrts = 3.600000000000E+02 GeV
| Phase space: generating configuration ...
| Phase space: ... success.
| Phase space: writing configuration file 'ee_i1.phs'
| Phase space: 2 channels, 2 dimensions
| Phase space: found 2 channels, collected in 2 groves.
| Phase space: Using 2 equivalences between channels.
| Phase space: wood
Warning: No cuts have been defined.
\end{verbatim}
\begin{verbatim}
| Starting integration for process 'ee'
| Integrate: iterations not specified, using default
| Integrate: iterations = 3:1000:"gw", 3:10000:""
| Integrator: 2 chains, 2 channels, 2 dimensions
| Integrator: Using VAMP channel equivalences
| Integrator: 1000 initial calls, 20 bins, stratified = T
| Integrator: VAMP
|=============================================================================|
| It Calls Integral[fb] Error[fb] Err[%] Acc Eff[%] Chi2 N[It] |
|=============================================================================|
1 784 8.3282892E+02 1.68E+00 0.20 0.06* 39.99
2 784 8.3118961E+02 1.23E+00 0.15 0.04* 76.34
3 784 8.3278951E+02 1.36E+00 0.16 0.05 54.45
|-----------------------------------------------------------------------------|
3 2352 8.3211789E+02 8.01E-01 0.10 0.05 54.45 0.50 3
|-----------------------------------------------------------------------------|
4 9936 8.3331732E+02 1.22E-01 0.01 0.01* 54.51
5 9936 8.3341072E+02 1.24E-01 0.01 0.01 54.52
6 9936 8.3331151E+02 1.23E-01 0.01 0.01* 54.51
|-----------------------------------------------------------------------------|
6 29808 8.3334611E+02 7.10E-02 0.01 0.01 54.51 0.20 3
|=============================================================================|
\end{verbatim}
\begin{verbatim}
[.....]
| Simulate: integration done
| Simulate: using integration grids from file 'ee_m1.vg'
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 9617
| Simulation: requested number of events = 10
| corr. to luminosity [fb-1] = 1.2000E-02
| Events: writing to LHEF file 'ee.lhe'
| Events: writing to raw file 'ee.evx'
| Events: generating 10 unweighted, unpolarized events ...
| Events: event normalization mode '1'
| ... event sample complete.
| Events: closing LHEF file 'ee.lhe'
| Events: closing raw file 'ee.evx'
| There were no errors and 1 warning(s).
| WHIZARD run finished.
|=============================================================================|
\end{verbatim}
\end{footnotesize}
%$
The final result is the desired event file, \ttt{ee.lhe}.
Let us discuss the output quickly to walk you through the procedures
of a \whizard\ run: after the logfile message and the banner, the
reading of the physics model and the initialization of a process
library, the recorded process with tag \ttt{'ee'} is recorded. Next,
user-defined parameters like the center-of-mass energy and the number
of demanded (unweighted) events are displayed. As a next step,
\whizard\ is starting the simulation of the process with tag
\ttt{'ee'}. It recognizes that there has not yet been an integration
over phase space (done by an optional \ttt{integrate} command,
cf. Sec.~\ref{sec:integrate}), and consequently starts the
integration. It then acknowledges, that the process code for the
process \ttt{'ee'} needs to be compiled first (done by an optional
\ttt{compile} command, cf. Sec.~\ref{sec:compilation}). So, \whizard\
compiles the process library, writes the makefile for its steering,
and as a safeguard against garbage removes possibly existing
files. Then, the source code for the library and its processes are
generated: for the process code, the default method -- the matrix
element generator \oMega\ is called (cf. Sec.~\ref{sec:omega_me}); and
the sources are being compiled.
The next steps are the loading of the process library, and \whizard\
reports the completion of the integration. For the Monte-Carlo
integration, a random number generator is initialized. Here, it is the
default generator, TAO (for more details, cf. Sec.~\ref{sec:tao},
while the random seed is set to a value initialized by the system
clock, as no seed has been provided in the \sindarin\ input file.
Now, the integration for the process \ttt{'ee'} is initialized, and
information about the process (its name, the name of its process
library, its index inside the library, and the process components out
of which it consists, cf. Sec.~\ref{sec:processcomp}) are
displayed. Then, the beam structure is shown, which in that case are
symmetric partonic electron and positron beams with the center-of-mass
energy provided by the user (360 GeV). The next step is the generation
of the phase space, for which the default phase space method
\ttt{wood} (for more details cf. Sec.~\ref{sec:wood}) is selected. The
integration is performed, and the result with absolute and relative
error, unweighting efficiency, accuracy, $\chi^2$ quality is shown.
The final step is the event generation
(cf. Chap.~\ref{chap:events}). The integration grids are now being
used, again the random number generator is initialized. Finally, event
generation of ten unweighted events starts (\whizard\ let us know to
which integrated luminosity that would correspond), and events are
written both in an internal (binary) event format as well as in the
demanded LHE format. This concludes the \whizard\ run.
After a more comprehensive introduction into the \sindarin\ steering
language in the next chapter, Chap.~\ref{chap:sindarinintro}, we will
discuss all the details of the different steps of this introductory
example.
\clearpage
\section{WHIZARD in a Computing Environment}
\subsection{Working on a Single Computer}
\label{sec:workspace}
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
\begin{itemize}
\item
manually add \ttt{your-install-directory/bin} to your execution PATH\\
and \ttt{your-install-directory/lib} to your library search path
(LD\_LIBRARY\_PATH), or
\item
whenever you start a project, execute
\begin{interaction}
your-workspace> . your-install-directory/bin/whizard-setup.sh
\end{interaction}
which will enable the paths in your current environment, or
\item
source \ttt{whizard-setup.sh} script in your shell startup file.
\end{itemize}
In either case, try to call \ttt{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 \ttt{.sin} (by convention). Running
\whizard\ is as simple as
\begin{interaction}
your-workspace> whizard your-input.sin
\end{interaction}
No other configuration files are needed. The total number of
auxiliary and output files generated in a single run may get quite
large, however, and they may clutter your workspace. This is the
reason behind keeping subdirectories on a per-run basis.
Basic usage of \whizard\ is explained in Chapter~\ref{chap:start}, for
more details, consult the following chapters. In
Sec.~\ref{sec:cmdline-options} we give an account of the command-line
options that \whizard\ accepts.
\subsection{Working Parallel on Several Computers}
\label{sec:mpi}
For integration (only VAMP2), \whizard\ supports parallel execution via MPI by communicating between parallel tasks on a single machine or distributed over several machines.
During integration the calculation of channels is distributed along several workers where a master worker collects the results and adapts weights and grids.
In wortwhile cases (e.g. high number of calls in one channel), the calculation of a single grid is additionally distributed.
For that, we provide two different parallelization methods, which can be steered by
\verb|$vamp_parallel_method|, implementing the dualistic parallelization approach between channels and single grids. The \ttt{simple} method provides a locally-fixed assignment approach without the need of intermediate communication between the MPI workers.
Whereas the \ttt{load} method provides a global queue with a master worker acting as a (communication) governor, therefore, excluding itself as potential "computing" worker.
The governor receives and distributes work requests from all other workers, and, finally, receives their results.
The methods differ from each other only in the way how they distribute excessive workers, in the case, where there are more workers than channels.
Here, the \ttt{load} method implements a balancing condition based on the channel weights in contrast to the simplistic ansatz.
Both methods use a full non-blocking communication approach in order to collect the integration results of each channel after each iteration.
After finishing the computation of a channel, the associated slave worker spawns a callback mechansim leading to the initialization of a sending process to the master.
The master worker organizes, depending on the parallelization method, the correct closing of the sending process for a given channel by a matching receiving process.
The callback approach allows us to concurrently communicate and produce integration results providing an increased parallelization portion, i.e.\ better HPC performance and utilization.
The \ttt{load} method comes with a drawback that it does not work with less than three workers.
Hence, we recommend (e.g.\ for debugging purpose of the parallel setup) to use the \ttt{simple} method, and to use the \ttt{load} method only for direct production runs.
In order to use these advancements, \whizard\ requires an installed MPI-3.1 capable
library (e.g. OpenMPI) and configuration and compilation with the appropriate flags,
cf.~Sec.~\ref{sec:installation}.
MPI support is only active when the integration method is set to VAMP2.
Additionally, to preserve the numerical properties of a single task run, it is
recommended to use the RNGstream as random number generator.
\begin{code}
$integration_method = 'vamp2'
$rng_method = 'rng_stream'
$vamp_parallel_method = 'simple' !! or 'load'
\end{code}
\whizard\ has then to be called by mpirun
\begin{footnotesize}
\begin{Verbatim}[frame=single]
your-workspace> mpirun -f hostfile -np 4 --output-filename mpi.log whizard your-input.sin
\end{Verbatim}
\end{footnotesize}
where the number of parallel tasks can be set by \ttt{-np} and a hostfile can be
given by \ttt{--hostfile}. It is recommended to use \ttt{--output-filename} which
lets mpirun redirect the standard (error) output to a file, for each worker separately.
\subsubsection{Notes on Parallelization with MPI}
The parallelization of \whizard\ requires that all instances of the
parallel run be able to write and read all files produced by
\whizard\ in a network file system as the current implementation does
not handle parallel I/O. Usually, high-performance clusters have
support for at least one network filesystem.
Furthermore, not all functions of \whizard\ are currently supported or
are only supported in a limited way in parallel mode. Currently the
\verb|?rebuild_<flags>| for the phase space and the matrix element
library are not yet available, as well as the calculation of matrix
elements with resonance histories.
Some features that have been missing in the very first implementation
of the parallelized integration have now been made available, like
the support of run IDs and the parallelization of the event generation.
A final remark on the stability of the numerical results in terms of
the number of workers involved. Under certain circumstances, results
between different numbers of workers but using otherwise an identical
\sindarin\ file can lead to slightly numerically different (but
statistically compatible) results for integration or event generation
This is related to the execution of the computational operations in
MPI, which we use to reduce results from all workers. If the order of
the numbers in the arithmetical operations changes, for example, by
different setups of the workers, then the numerical results change
slightly, which in turn is amplified under the influence of the
adaptation. Nevertheless, the results are all statistically
consistent.
\subsection{Stopping and Resuming WHIZARD Jobs}
On a Unix-like system, it is possible to prematurely stop running jobs
by a \ttt{kill(1)} command, or by entering \ttt{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 \ttt{kill -9}. A convenient method,
on a terminal, would be to suspend it first by \ttt{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.\footnote{This holds for simple workflow. In
case of scans and repeated integrations of the same process, there
may be name clashes on the written files which prevent resuming. A
future \whizard\ version will address this problem.} 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.
\subsection{Files and Directories: default and customization}
\whizard\ jobs take a small set of files as input. In many cases, this is
just a single \sindarin\ script provided by the user.
When running, \whizard\ can produce a set of auxiliary and output files:
\begin{enumerate}
\item
\textbf{Job.}
Files pertaining to the \whizard\ job as a whole. This is the default log
file \ttt{whizard.log}.
\item
\textbf{Process compilation.} Files that originate from generating and
compiling process code. If the default \oMega\ generator is used, these
files include \fortran\ source code as well as compiled libraries that are
dynamically linked to the running executable. The file names are derived
from either the process-library name or the individual process names, as
defined in the \sindarin\ input. The default library name is
\ttt{default\_lib}.
\item
\textbf{Integration.}
Files that are created by integration, i.e., when calculating the total cross
section for a scattering process using the Monte-Carlo algorithm. The file
names are derived from the process name.
\item
\textbf{Simulation.}
Files that are created during simulation, i.e., generating event samples for
a process or a set of processes. By default, the file names are derived
from the name of the first process. Event-file formats are distinguished
by appropriate file name extensions.
\item
\textbf{Result Analysis.}
Files that are created by the internal analysis tools and written by the
command \ttt{write\_analysis} (or \ttt{compile\_analysis}). The default
base name is \ttt{whizard\_analysis}.
\end{enumerate}
A complex workflow with several processes, parameter sets, or runs, can easily
lead to in file-name clashes or a messy working directory. Furthermore,
running a batch job on a dedicated computing environment often requires
transferring data from a user directory to the server and back.
Custom directory and file names can be used to organize things and facilitate
dealing with the environment, along with the available batch-system tools for
coordinating file transfer.
\begin{enumerate}
\item
\textbf{Job.}
\begin{itemize}
\item
The \ttt{-L} option on the command line defines a custom base name for
the log file.
\item
The \ttt{-J} option on the command line defines a job ID. For instance,
this may be set to the job ID assigned by the batch system. Within the
\sindarin\ script, the job ID is available as the string variable
\ttt{\$job\_id} and can be used for constructing custom job-specific file
and directory names, as described below.
\end{itemize}
\item
\textbf{Process compilation.}
\begin{itemize}
\item
The user can require the program to put all files created during the
compilation step including the library to be linked, in a subdirectory of
the working directory. To enable this, set the string variable
\ttt{\$compile\_workspace} within the \sindarin\ script.
\end{itemize}
\item
\textbf{Integration.}
\begin{itemize}
\item
The value of the string variable \ttt{\$run\_id}, if set, is appended to
the base name of all files created by integration, separated by dots. If
the \sindarin\ script scans over parameters, varying the run ID avoids
repeatedly overwriting files with identical name during the scan.
\item
The user can require the program to put the important files created during
the integration step -- the phase-space configuration file and the
\vamp\ grid files -- in a subdirectory of the working directory. To
enable this, set the string variable \ttt{\$integrate\_workspace} within
the \sindarin\ script. (\ttt{\$compile\_workspace} and
\ttt{\$integrate\_workspace} may be set to the same value.)
\end{itemize}
Log files produced during the integration step are put in the working
directory.
\item
\textbf{Simulation.}
\begin{itemize}
\item
The value of the string variable \ttt{\$run\_id}, if set, identifies
the specific integration run that is used for the event sample. It is
also inserted into default event-sample file names.
\item
The variable \ttt{\$sample}, if set, defines an arbitrary base name for the
files related to the event sample.
\end{itemize}
Files resulting from simulation are put in the working directory.
\item
\textbf{Result Analysis.}
\begin{itemize}
\item
The variable \ttt{\$out\_file}, if set,
defines an arbitrary base name for the analysis data and
auxiliary files.
\end{itemize}
Files resulting from result analysis are put in the working directory.
\end{enumerate}
\subsection{Batch jobs on a different machine}
It is possible to separate the tasks of process-code compilation, integration,
and simulation, and execute them on different machines. To make use of
this feature, the local and remote machines including all
installed libraries that are relevant for \whizard, must be
binary-compatible.
\begin{enumerate}
\item
Process-code compilation may be done once on a local machine, while the
time-consuming tasks of integration and event generation for specific
parameter sets are delegated to a remote machine, e.g., a batch cluster. To
enable this, prepare a \sindarin\ script that just produces process code
(i.e., terminates with a \ttt{compile} command) for the local machine. You
may define \ttt{\$compile\_workspace} such that all generated code
conveniently ends up in a single subdirectory.
To start the batch job, transfer the workspace subdirectory to the remote
machine
and start \whizard\ there. The \sindarin\ script on the remote machine must
include the local script unchanged in all parts that are relevant for
process definition. The program will recognize the contents of the
workspace, skip compilation and instead link the process library immediately.
To proceed further, the script should define the run-specific parameters and
contain the appropriate commands for integration and simulation.
\item
Analogously, you may execute both process-code compilation and integration
locally, but generate event samples on a remote machine. To this end,
prepare a \sindarin\ script that produces process code and computes integrals
(i.e., terminates with an \ttt{integrate} command) for the local machine.
You may define \ttt{\$compile\_workspace} and \ttt{\$integrate\_workspace}
(which may coincide) such that all generated code, phase-space and
integration grid data conveniently end up in subdirectories.
To start the batch job, transfer the workspace(s) to the remote machine and
start \whizard\ there. The \sindarin\ script on the remote machine must
include the local script unchanged in all parts that are relevant for
process definition and integration. The program will recognize the contents
of the workspace, skip compilation and integration and instead load the
process library and integration results immediately. To proceed further,
the script should define the sample-specific parameters and contain the
appropriate commands for simulation.
\end{enumerate}
To simplify transferring whole directories, \whizard\ supports the
\ttt{--pack} and \ttt{--unpack} options. You may specify any number of these
options for a \whizard\ run. (The feature relies on the GNU version of the
\ttt{tar} utility.)
For instance,
\begin{code}
whizard script1.sin --pack my_ws
\end{code}
runs \whizard\ with the \sindarin\ script \ttt{script1.sin} as input, where
within the script you have defined
\begin{code}
$compile_workspace = "my_ws"
\end{code}
as the target directory for process-compilation files. After completion, the
program will tar and gzip the target directory as \ttt{my\_ws.tgz}. You
should copy this file to the remote machine as one of the job's input files.
On the remote machine, you can then run the program with
\begin{code}
whizard script2.sin --unpack my_ws.tgz
\end{code}
where \ttt{script2.sin} should include \ttt{script1.sin}, and add integration
or simulation commands. The contents of \ttt{ws.tgz} will thus be unpacked
and reused on the remote machine, instead of generating new process code.
\subsection{Static Linkage}
In its default running mode, \whizard\ compiles process-specific matrix
element code on the fly and dynamically links the resulting library. On the
computing server, this requires availability of the appropriate \fortran\
compiler, as well as the \ocaml\ compiler suite, and the dynamical linking
feature.
Since this may be unavailable or undesired, there is a possibility to
distribute \whizard\ as a statically linked executable that contains a
pre-compiled library of processes. This removes the need for the \fortran\
compiler, the \ocaml\ system, and extra dynamic linking. Any external
libraries that are accessed (the \fortran\ runtime environment, and possibly
some dynamically linked external libraries and/or the \cpp\ runtime library,
must still be available on the target system, binary-compatible. Otherwise,
there is no need for transferring the complete \whizard\ installation or
process-code compilation data.
Generating, compiling and linking matrix element code is done in advance on a
machine that can access the required tools and produces compatible libraries.
This procedure is accomplished by \sindarin\ commands, explained below in
Sec.~\ref{sec:static}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\section{Troubleshooting}
\label{sec:troubleshooting}
In this section, we list known issues or problems and give advice on
what can be done in case something does not work as intended.
\subsection{Possible (uncommon) build problems}
\label{sec:buildproblems}
\subsubsection{\ocaml\ versions and \oMega\ builds}
For the matrix element generator \oMega\ 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 \oMega/\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.
\subsubsection{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:
\begin{footnotesize}
\begin{Verbatim}[frame=single]
...
libtool: compile: gfortran -I../misc -I../vamp -g -O2 -c processes.f90 -fPIC -o
.libs/processes.o
libtool: compile: gfortran -I../misc -I../vamp -g -O2 -c processes.f90 -o
processes.o >/dev/null 2>&1
make[2]: *** No rule to make target `limits.lo', needed by `decays.lo'. Stop.
...
make: *** [all-recursive] Error 1
\end{Verbatim}
\end{footnotesize}
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:
\begin{footnotesize}
\begin{Verbatim}[frame=single]
$ zcat whizard-3.0.1.tar.gz | tar xf -
$ cd whizard-3.0.1
$ mkdir _build
$ cd _build
$ ../configure FC=gfortran
$ make
\end{Verbatim}
\end{footnotesize}
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.
%%%%%
\subsection{What happens if \whizard\ throws an error?}
\label{ref:errors}
\subsubsection{Particle name special characters in process
declarations}
Trying to use a process declaration like
\begin{code}
process foo = e-, e+ => mu-, mu+
\end{code}
will lead to a \sindarin\ syntax error:
\begin{Code}
process foo = e-, e+ => mu-, mu+
^^
| Expected syntax: SEQUENCE <cmd_process> = process <process_id> '=' <process_p
| Found token: KEYWORD: '-'
******************************************************************************
******************************************************************************
*** FATAL ERROR: Syntax error (at or before the location indicated above)
******************************************************************************
******************************************************************************
\end{Code}
\whizard\ tries to interpret the minus and plus signs as operators
(\ttt{KEYWORD: '-'}), so you have to quote the particle names:
\ttt{process foo = "e-", "e+" => "mu-", "mu+"}.
\subsubsection{Missing collider energy}
This happens if you forgot to set the collider energy in the
integration of a scattering process:
\begin{Code}
******************************************************************************
******************************************************************************
*** FATAL ERROR: Colliding beams: sqrts is zero (please set sqrts)
******************************************************************************
******************************************************************************
\end{Code}
This will solve your problem:
\begin{code}
sqrts = <your_energy>
\end{code}
\subsubsection{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:
\begin{Code}
******************************************************************************
******************************************************************************
*** FATAL ERROR: Process library doesn't contain process 'f00'
******************************************************************************
******************************************************************************
\end{Code}
Note that this could sometimes be a simple typo, e.g. in that case an
\ttt{integrate (f00)} instead of \ttt{integrate (foo)}
\subsubsection{Ambiguous initial state without beam declaration}
When the user declares a process with a flavor sum in the initial
state, e.g.
\begin{code}
process qqaa = u:d, U:D => A, A
sqrts = <your_energy>
integrate (qqaa)
\end{code}
then a fatal error will be issued:
\begin{Code}
******************************************************************************
******************************************************************************
*** FATAL ERROR: Setting up process 'qqaa':
*** --------------------------------------------
*** Inconsistent initial state. This happens if either
*** several processes with non-matching initial states
*** have been added, or for a single process with an
*** initial state flavor sum. In that case, please set beams
*** explicitly [singling out a flavor / structure function.]
******************************************************************************
******************************************************************************
\end{Code}
What now? Either a structure function providing a tensor structure in
flavors has to be provided like
\begin{code}
beams = p, pbar => pdf_builtin
\end{code}
or, if the partonic process was intended, a specific flavor has to be
singled out,
\begin{code}
beams = u, U
\end{code}
which would take only the up-quarks. Note that a sum over process
components with varying initial states is not possible.
\subsubsection{Invalid or unsupported beam structure}
An error message like
\begin{Code}
******************************************************************************
******************************************************************************
*** FATAL ERROR: Beam structure: [.......] not supported
******************************************************************************
******************************************************************************
\end{Code}
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):
\begin{code}
beams = p, p => isr => pdf_builtin
\end{code}
\subsubsection{Mismatch in beams}
Sometimes you get a rather long error output statement followed by a
fatal error:
\begin{Code}
Evaluator product
First interaction
Interaction: 6
Virtual:
Particle 1
[momentum undefined]
[.......]
State matrix: norm = 1.000000000000E+00
[f(2212)]
[f(11)]
[f(92) c(1 )]
[f(-6) c(-1 )] => ME(1) = ( 0.000000000000E+00, 0.000000000000E+00)
[.......]
******************************************************************************
******************************************************************************
*** FATAL ERROR: Product of density matrices is empty
*** --------------------------------------------
*** This happens when two density matrices are convoluted
*** but the processes they belong to (e.g., production
*** and decay) do not match. This could happen if the
*** beam specification does not match the hard
*** process. Or it may indicate a WHIZARD bug.
******************************************************************************
******************************************************************************
\end{Code}
As \whizard\ indicates, this could have happened because the hard
process setup did not match the specification of the beams as in:
\begin{code}
process neutral_current_DIS = e1, u => e1, u
beams_momentum = 27.5 GeV, 920 GeV
beams = p, e => pdf_builtin, none
integrate (neutral_current_DIS)
\end{code}
In that case, the order of the beam particles simply was wrong,
exchange proton and electron (together with the structure functions)
into \ttt{beams = e, p => none, pdf\_builtin}, and \whizard\ will be
happy.
\subsubsection{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:
\begin{Code}
******************************************************************************
******************************************************************************
*** FATAL ERROR: Phase space: Initial beam particle can decay
******************************************************************************
******************************************************************************
\end{Code}
This happens basically only for processes in testing/validation (like
$t \bar t \to b \bar b$). In principle, it could also happen in a real
physics setup, e.g. when simulating electron pairs at a muon collider:
\begin{code}
process mmee = "mu-", "mu+" => "e-", "e+"
\end{code}
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:
\begin{code}
?fatal_beam_decay = false
\end{code}
\subsubsection{Impossible beam polarization}
If you specify a beam polarization that cannot correspond to any
physically allowed spin density matrix, e.g.,
\begin{code}
beams = e1, E1
beams_pol_density = @(-1), @(1:1:.5, -1, 1:-1)
\end{code}
\whizard\ will throw a fatal
error like this:
\begin{Code}
Trace of matrix square = 1.4444444444444444
Polarization: spin density matrix
spin type = 2
multiplicity = 2
massive = F
chirality = 0
pol.degree = 1.0000000
pure state = F
@(+1: +1: ( 3.333333333333E-01, 0.000000000000E+00))
@(-1: -1: ( 6.666666666667E-01, 0.000000000000E+00))
@(-1: +1: ( 6.666666666667E-01, 0.000000000000E+00))
******************************************************************************
******************************************************************************
*** FATAL ERROR: Spin density matrix: not permissible as density matrix
******************************************************************************
******************************************************************************
\end{Code}
\subsubsection{Beams with crossing angle}
Specifying a crossing angle (e.g. at a linear lepton collider) without
explicitly setting the beam momenta,
\begin{code}
sqrts = 1 TeV
beams = e1, E1
beams\_theta = 0, 10 degree
\end{code}
triggers a fatal:
\begin{Code}
******************************************************************************
******************************************************************************
*** FATAL ERROR: Beam structure: angle theta/phi specified but momentum/a p undefined
******************************************************************************
******************************************************************************
\end{Code}
In that case the single beam momenta have to be explicitly set:
\begin{code}
beams = e1, E1
beams\_momentum = 500 GeV, 500 GeV
beams\_theta = 0, 10 degree
\end{code}
\subsubsection{Phase-space generation failed}
Sometimes an error might be issued that \whizard\ could not generate a
valid phase-space parameterization:
\begin{Code}
| Phase space: ... failed. Increasing phs_off_shell ...
| Phase space: ... failed. Increasing phs_off_shell ...
| Phase space: ... failed. Increasing phs_off_shell ...
| Phase space: ... failed. Increasing phs_off_shell ...
******************************************************************************
******************************************************************************
*** FATAL ERROR: Phase-space: generation failed
******************************************************************************
******************************************************************************
\end{Code}
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, \ttt{phs\_t\_channel},
however, is not increased automatically. Its default value is $6$, so
e.g. for the process $e^+ e^- \to 8\gamma$ you will run into the
problem above. Setting
\begin{code}
phs_off_shell = <n>-1
\end{code}
where \ttt{<n>} is the number of final-state particles will solve the problem.
\subsubsection{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 (\whizard\ttt{2}
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 \to
jj$ a distance cut between the two jets prevents singular collinear
splitting in their generation, but if no $p_T$ cut have been set,
there is still singular collinear splitting from the beams.
\subsubsection{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 \ttt{simulate}
command for your process. In case there was a \ttt{simulate} command
but the process under consideration is not possible (e.g. a typo,
\ttt{e1, E1 => e2, E3} instead of \ttt{e1, E1 => e3, E3}), then you
get an error like that:
\begin{Code}
******************************************************************************
*** ERROR: Simulate: no process has a valid matrix element.
******************************************************************************
\end{Code}
\subsubsection{Why is the event file empty?}
In order to get events, you need to set either a desired number of
events:
\begin{code}
n_events = <integer>
\end{code}
or you have to specify a certain integrated luminosity (the default
unit being inverse femtobarn:
\begin{code}
luminosity = <real> / 1 fbarn
\end{code}
In case you set both, \whizard\ will take the one that leads to the
higher number of events.
\subsubsection{Parton showering fails}
For BSM models containing massive stable or long-lived particles
parton showering with \pythiasix\ fails:
\begin{Code}
Advisory warning type 3 given after 0 PYEXEC calls:
(PYRESD:) Failed to decay particle 1000022 with mass 15.000
******************************************************************************
******************************************************************************
*** FATAL ERROR: Simulation: failed to generate valid event after 10000 tries
******************************************************************************
******************************************************************************
\end{Code}
The solution to that problem is discussed in Sec.~\ref{sec:pythia6}.
\vspace{1cm}
%%%%%
\subsection{Debugging, testing, and validation}
\subsubsection{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 \ttt{FCFLAGS = {\em <flags>}} settings during
configuration. For the \ttt{NAG} \fortran\ compiler we use the flags
\ttt{-C=all -nan -gline} for debugging purposes. For the \ttt{gfortran}
compilers, the flags \ttt{-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 \ttt{IEEE} exception handling
support (\ttt{Fortran 2008} status), but we do not use these
implementations in the \whizard\ code (yet).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Steering WHIZARD: \sindarin\ Overview}
\label{chap:sindarinintro}
\section{The command language for WHIZARD}
A conventional physics application program gets its data from a set of input
files. Alternatively, it is called as a library, so the user has to write his
own code to interface it, or it combines these two approaches. \whizard~1 was
built in this way: there were some input files which were written by the user,
and it could be called both stand-alone or as an external library.
\whizard~2 is also a stand-alone program. It comes with its own full-fledged
script language, called \sindarin. All interaction between the user and the
program is done in \sindarin\ expressions, commands, and scripts. Two main
reasons led us to this choice:
\begin{itemize}
\item
In any nontrivial physics study, cuts and (parton- or hadron-level) analysis
are of central importance. The task of specifying appropriate kinematics
and particle selection for a given process is well defined, but it is
impossible to cover all possiblities in a simple format like the cut files
of \whizard~1.
The usual way of dealing with this problem is to write analysis driver code
(often in \cpp, using external libraries for Lorentz algebra etc. However,
the overhead of writing correct \cpp\ or \ttt{Fortran} greatly blows up problems
that could be formulated in a few lines of text.
\item
While many problems lead to a repetitive workflow (process definition,
integration, simulation), there are more involved tasks that involve
parameter scans, comparisons of different processes, conditional execution,
or writing output in widely different formats. This is easily done by a
steering script, which should be formulated in a complete language.
\end{itemize}
The \sindarin\ language is built specifically around event analysis, suitably
extended to support steering, including data types, loops, conditionals, and
I/O.
It would have been possible to use an established general-purpose language for
these tasks. For instance, \ocaml\ which is a functional language would be a
suitable candidate, and the matrix-element generator \oMega\ is written in that
language. Another candidate would be a popular scripting language such as
PYTHON.
We started to support interfaces for commonly used languages: prime
examples for \ttt{C}, \cpp, and PYTHON are found in the
\ttt{share/interfaces} subdirectory. However, introducing a
special-purpose language has the three distinct
advantages: First, it is compiled and executed by the very \ttt{Fortran} code that
handles data and thus accesses it without interfaces. Second, it can be
designed with a syntax especially suited to the task of event handling and
Monte-Carlo steering, and third, the user is not forced to learn all those
features of a generic language that are of no relevance to the application he/she
is interested in.
\section{\sindarin\ scripts}
A \sindarin\ script tells the \whizard\ program what it has to do. Typically,
the script is contained in a file which you (the user) create. The file name
is arbitrary; by convention, it has the extension `\verb|.sin|'.
\whizard\ takes the file name as its argument on the command line and
executes the contained script:
\begin{verbatim}
/home/user$ whizard script.sin
\end{verbatim}
Alternatively, you can call \whizard\ interactively and execute
statements line by line; we describe this below in Sec.\ref{sec:whish}.
A \sindarin\ script is a sequence of \emph{statements}, similar to the
statements in any imperative language such as \ttt{Fortran} or
\ttt{C}. Examples of statements are commands like \ttt{integrate},
variable declarations like \ttt{logical ?flag} or assigments like
\ttt{mH = 130 GeV}.
The script is free-form, i.e., indentation, extra whitespace and
newlines are syntactically insignificant. In contrast to most
languages, there is no statement separator. Statements simply follow each
other, just separated by whitespace.
\begin{code}
statement1 statement2
statement3
statement4
\end{code}
Nevertheless, for clarity we recommend to
write one statement per line where possible, and to use proper
indentation for longer statements, nested and bracketed expressions.
A command may consist of a \emph{keyword}, a list of \emph{arguments} in
parantheses \ttt{(}\ldots\ttt{)}, and an \emph{option} script which
itself is a sequence of statements.
\begin{code}
command
command_with_args (arg1, arg2)
command_with_option { option }
command_with_options (arg) {
option_statement1
option_statement2
}
\end{code}
As a rule, parentheses \ttt{()} enclose arguments and expressions, as
you would expect. Arguments enclosed in square brackets \ttt{[]} also
exist. They have a special meaning, they denote subevents
(collections of momenta) in event analysis. Braces \ttt{\{\}} enclose
blocks of \sindarin\ code. In particular, the option script
associated with a command is a block of code that may contain local
parameter settings, for instance. Braces always indicate a scoping
unit, so parameters will be restored their previous values when the
execution of that command is completed.
The script can contain comments. Comments are initiated by either a \verb|#|
or a \verb|!| character and extend to the end of the current line.
\begin{code}
statement
# This is a comment
statement ! This is also a comment
\end{code}
%%%%%%%%%%%%%%%
\section{Errors}
\label{sec:errors}
Before turning to proper \sindarin\ syntax, let us consider error messages.
\sindarin\ distinguishes syntax errors and runtime errors.
Syntax errors are recognized when the script is read and compiled,
before any part is executed. Look at this example:
\begin{code}
process foo = u, ubar => d, dbar
md = 10
integrade (foo)
\end{code}
\whizard\ will fail with the error message
\begin{interaction}
sqrts = 1 TeV
integrade (foo)
^^
| Expected syntax: SEQUENCE <cmd_num> = <var_name> '=' <expr>
| Found token: KEYWORD: '('
******************************************************************************
******************************************************************************
*** FATAL ERROR: Syntax error (at or before the location indicated above)
******************************************************************************
******************************************************************************
WHIZARD run aborted.
\end{interaction}
which tells you that you have misspelled the command
\verb|integrate|, so the compiler tried to interpret it as a variable.
Runtime errors are categorized by their severity. A warning is simply
printed:
\begin{interaction}
Warning: No cuts have been defined.
\end{interaction}
This indicates a condition that is suspicious, but may actually be
intended by the user.
When an error is encountered, it is printed with more emphasis
\begin{interaction}
******************************************************************************
*** ERROR: Variable 'md' set without declaration
******************************************************************************
\end{interaction}
and the program tries to continue. However, this usually indicates
that there is something wrong. (The $d$ quark is defined
massless, so \verb|md| is not a model parameter.) \whizard\ counts
errors and warnings and tells you at the end
\begin{interaction}
| There were 1 error(s) and no warnings.
\end{interaction}
just in case you missed the message.
Other errors are considered fatal, and execution stops at this point.
\begin{interaction}
******************************************************************************
******************************************************************************
*** FATAL ERROR: Colliding beams: sqrts is zero (please set sqrts)
******************************************************************************
******************************************************************************
\end{interaction}
Here, \whizard\ was unable to do anything sensible. But at least (in
this case) it told the user what to do to resolve the problem.
%%%%%%%%%%%%%%%
\section{Statements}
\label{sec:statements}
\sindarin\ statements are executed one by one. For an overview, we
list the most common statements in the order in which they typically
appear in a \sindarin\ script, and quote the basic syntax and simple
examples. This should give an impression on the \whizard's
capabilities and on the user interface. The list is not complete.
Note that there are no
mandatory commands (although an empty \sindarin\ script is not really
useful). The details and options are explained in later sections.
\subsection{Process Configuration}
\subsubsection{model}
\begin{syntax}
model = \var{model-name}
\end{syntax}
This assignment sets or resets the current physics model. The
Standard Model is already preloaded, so the \ttt{model} assignment
applies to non-default models. Obviously, the model must be known to
\whizard. Example:
\begin{code}
model = MSSM
\end{code}
See Sec.~\ref{sec:models}.
\subsubsection{alias}
\begin{syntax}
alias \var{alias-name} = \var{alias-definition}
\end{syntax}
Particles are specified by their names. For most particles, there
are various equivalent names. Names containing special characters
such as a \verb|+| sign have to be quoted. The \ttt{alias} assignment
defines an alias for a list of particles. This is useful for setting
up processes with sums over flavors, cut expressions, and more. The
alias name is then used like a simple particle name. Example:
\begin{syntax}
alias jet = u:d:s:U:D:S:g
\end{syntax}
See Sec.~\ref{sec:alias}.
\subsubsection{process}
\begin{syntax}
process \var{tag} = \var{incoming} \verb|=>| \var{outgoing}
\end{syntax}
Define a process. You give the process a name \var{tag} by which it is
identified later, and specify the incoming and outgoing particles,
and possibly options. You can define an arbitrary number of processes
as long as they are distinguished by their names. Example:
\begin{code}
process w_plus_jets = g, g => "W+", jet, jet
\end{code}
See Sec.~\ref{sec:processes}.
\subsubsection{sqrts}
\begin{syntax}
sqrts = \var{energy-value}
\end{syntax}
Define the center-of-mass energy for collision processes. The default
setup will assume head-on central collisions of two beams. Example:
\begin{code}
sqrts = 500 GeV
\end{code}
See Sec.~\ref{sec:beam-setup}.
\subsubsection{beams}
\begin{syntax}
beams = \var{beam-particles} \\
beams = \var{beam-particles} => \var{structure-function-setup}
\end{syntax}
Declare beam particles and properties. The current value of \ttt{sqrts} is
used, unless specified otherwise. Example:
\begin{code}
beams = u:d:s, U:D:S => lhapdf
\end{code}
With options, the assignment allows for
defining beam structure in some detail. This includes beamstrahlung and ISR
for lepton colliders, precise structure function definition for hadron
colliders, asymmetric beams, beam polarization, and more. See
Sec.~\ref{sec:beams}.
\subsection{Parameters}
\subsubsection{Parameter settings}
\begin{syntax}
\var{parameter} = \var{value} \\
\var{type} \var{user-parameter} \\
\var{type} \var{user-parameter} = \var{value}
\end{syntax}
Specify a value for a parameter. There are predefined parameters that affect
the behavior of a command, model-specific parameters (masses, couplings), and
user-defined parameters. The latter have to be declared with a type, which
may be \ttt{int} (integer), \ttt{real}, \ttt{complex}, \ttt{logical},
\ttt{string}, or \ttt{alias}. Logical parameter
names begin with a question mark, string parameter names with a dollar sign.
Examples:
\begin{code}
mb = 4.2 GeV
?rebuild_grids = true
real mass_sum = mZ + mW
string $message = "This is a string"
\end{code}
% $
The value need not be a literal, it can be an arbitrary expression of the
correct type. See Sec.~\ref{sec:variables}.
\subsubsection{read\_slha}
\begin{syntax}
read\_slha (\var{filename})
\end{syntax}
This is useful only for supersymmetric models: read a parameter file
in the SUSY Les Houches Accord format. The file defines parameter
values and, optionally, decay widths, so this command removes the need
for writing assignments for each of them.
\begin{code}
read_slha ("sps1a.slha")
\end{code}
See Sec.~\ref{sec:slha}.
\subsubsection{show}
\begin{syntax}
show (\var{data-objects})
\end{syntax}
Print the current value of some data object. This includes not just
variables, but also models, libraries, cuts, etc. This is rather a
debugging aid, so don't expect the output to be concise in the latter
cases. Example:
\begin{code}
show (mH, wH)
\end{code}
See Sec.~\ref{sec:I/O}.
\subsubsection{printf}
\begin{syntax}
printf \var{format-string} (\var{data-objects})
\end{syntax}
Pretty-print the data objects according to the given format string.
If there are no data objects, just print the format string.
This command is borrowed from the \ttt{C} programming language; it is
actually an interface to the system's \ttt{printf(3)} function. The
conversion specifiers are restricted to \ttt{d,i,e,f,g,s},
corresponding to the output of integer, real, and string variables.
Example:
\begin{code}
printf "The Higgs mass is %f GeV" (mH)
\end{code}
See Sec.~\ref{sec:I/O}.
\subsection{Integration}
\subsubsection{cuts}
\begin{syntax}
cuts = \var{logical-cut-expression}
\end{syntax}
The cut expression is a logical macro expression that is evaluated for each
phase space point during integration and event generation. You may construct
expressions out of various observables that are computed for the (partonic)
particle content of the current event. If the expression evaluates to
\verb|true|, the matrix element is calculated and the event is used. If it
evaluates to \verb|false|, the matrix element is set zero and the event is
discarded. Note that for collisions the expression is evaluated in the
lab frame, while for decays it is evaluated in the rest frame of the
decaying particle. In case you want to impose cuts on a factorized
process, i.e. a combination of a production process and one or more
decay processes, you have to use the \ttt{selection} keyword
instead.
Example for the keyword \ttt{cuts}:
\begin{code}
cuts = all Pt > 20 GeV [jet]
and all mZ - 10 GeV < M < mZ + 10 GeV [lepton, lepton]
and no abs (Eta) < 2 [jet]
\end{code}
See Sec.~\ref{sec:cuts}.
\subsubsection{integrate}
\begin{syntax}
integrate (\var{process-tags})
\end{syntax}
Compute the total cross section for a process. The command takes into account
the definition of the process, the beam setup, cuts, and parameters as defined
in the script. Parameters may also be specified as options to the command.
Integration is necessary for each process for which you want to know total or
differential cross sections, or event samples. Apart from computing a value,
it sets up and adapts phase space and integration grids that are used in event
generation. If you just need an event sample, you can omit an explicit
\ttt{integrate} command; the \ttt{simulate} command will call it
automatically. Example:
\begin{code}
integrate (w_plus_jets, z_plus_jets)
\end{code}
See Sec.~\ref{sec:integrate}.
\subsubsection{?phs\_only/n\_calls\_test}
\begin{syntax}
integrate (\var{process-tag}) \{ ?phs\_only = true n\_calls\_test = 1000 \}
\end{syntax}
These are just optional settings for the \ttt{integrate} command
discussed just a second ago. The \ttt{?phs\_only = true} (note that
variables starting with a question mark are logicals) option tells
\whizard\ to prepare a process for integration, but instead of
performing the integration, just to generate a phase space
parameterization. \ttt{n\_calls\_test = <num>} evaluates the sampling
function for random integration channels and random momenta. \vamp\
integration grids are neither generated nor used, so the channel
selection corresponds to the first integration pass, before any grids
or channel weights are adapted. The number of sampling points is
given by \verb|<num>|. The output contains information about the
timing, number of sampling points that passed the kinematics
selection, and the number of matrix-element values that were actually
evaluated. This command is useful mainly for debugging and
diagnostics. Example:
\begin{code}
integrate (some_large_process) { ?phs_only = true n_calls_test = 1000 }
\end{code}
(Note that there used to be a separate command
\ttt{matrix\_element\_test} until version 2.1.1 of \whizard\ which has
been discarded in order to simplify the \sindarin\ syntax.)
\subsection{Events}
\subsubsection{histogram}
\begin{syntax}
histogram \var{tag} (\var{lower-bound}, \var{upper-bound}) \\
histogram \var{tag} (\var{lower-bound}, \var{upper-bound}, \var{step}) \\
\end{syntax}
Declare a histogram for event analysis. The histogram is filled by an
analysis expression, which is evaluated once for each event during a
subsequent simulation step. Example:
\begin{code}
histogram pt_distribution (0, 150 GeV, 10 GeV)
\end{code}
See Sec.~\ref{sec:histogram}.
\subsubsection{plot}
\begin{syntax}
plot \var{tag}
\end{syntax}
Declare a plot for displaying data points. The plot may be filled by an
analysis expression that is evaluated for each event; this would result in a
scatter plot. More likely, you will use this feature for displaying data such
as the energy dependence of a cross section. Example:
\begin{code}
plot total_cross_section
\end{code}
See Sec.~\ref{sec:plot}.
\subsubsection{selection}
\begin{syntax}
selection = \var{selection-expression}
\end{syntax}
The selection expression is a logical macro expression that is evaluated once
for each event. It is applied to the event record,
after all decays have been executed (if any). It is therefore intended
e.g. for modelling detector acceptance cuts etc. For unfactorized
processes the usage of \ttt{cuts} or \ttt{selection} leads to
the same results. Events for which the selection expression evaluates
to false are dropped; they are neither analyzed nor written to any
user-defined output file. However, the dropped events are written to
\whizard's native event file. For unfactorized processes it is
therefore preferable to implement all cuts using the \ttt{cuts}
keyword for the integration, see \ttt{cuts} above.
Example:
\begin{code}
selection = all Pt > 50 GeV [lepton]
\end{code}
The syntax is generically the same as for the \ttt{cuts
expression}, see Sec.~\ref{sec:cuts}. For more information see also
Sec.~\ref{sec:analysis}.
\subsubsection{analysis}
\begin{syntax}
analysis = \var{analysis-expression}
\end{syntax}
The analysis expression is a logical macro expression that is evaluated once
for each event that passes the integration and selection cuts in a
subsequent simulation step. The
expression has type logical in analogy with the cut expression; however, its
main use will be in side effects caused by embedded \ttt{record} expressions.
The \ttt{record} expression books a value, calculated from observables
evaluated for the current event, in one of the predefined histograms or plots.
Example:
\begin{code}
analysis = record pt_distribution (eval Pt [photon])
and record mval (eval M [lepton, lepton])
\end{code}
See Sec.~\ref{sec:analysis}.
\subsubsection{unstable}
\begin{syntax}
unstable \var{particle} (\var{decay-channels})
\end{syntax}
Specify that a particle can decay, if it occurs in the final state of a
subsequent simulation step. (In the integration step, all final-state
particles are considered stable.) The decay channels are processes which
should have been declared before by a \ttt{process} command
(alternatively, there are options that \whizard\ takes care of this
automatically; cf. Sec.~\ref{sec:decays}). They may be
integrated explicitly, otherwise the \ttt{unstable} command will take care of
the integration before particle decays are generated. Example:
\begin{code}
unstable Z (z_ee, z_jj)
\end{code}
Note that the decay is an on-shell approximation. Alternatively, \whizard\ is
capable of generating the final state(s) directly, automatically including the
particle as an internal resonance together with irreducible background.
Depending on the physical problem and on the complexity of the matrix-element
calculation, either option may be more appropriate.
See Sec.~\ref{sec:decays}.
\subsubsection{n\_events}
\begin{syntax}
n\_events = \var{integer}
\end{syntax}
Specify the number of events that a subsequent simulation step should produce.
By default, simulated events are unweighted. (Unweighting is done by a
rejection operation on weighted events, so the usual caveats on event
unweighting by a numerical Monte-Carlo generator do apply.) Example:
\begin{code}
n_events = 20000
\end{code}
See Sec.~\ref{sec:simulation}.
\subsubsection{simulate}
\begin{syntax}
simulate (\var{process-tags})
\end{syntax}
Generate an event sample. The command allows for analyzing the generated
events by the \ttt{analysis} expression. Furthermore, events can be written
to file in various formats. Optionally, the partonic events can be showered
and hadronized, partly using included external (\pythia) or truly
external programs called by \whizard. Example:
\begin{code}
simulate (w_plus_jets) { sample_format = lhef }
\end{code}
See Sec.~\ref{sec:simulation} and Chapter~\ref{chap:events}.
\subsubsection{graph}
\begin{syntax}
graph (\var{tag}) = \var{histograms-and-plots}
\end{syntax}
Combine existing histograms and plots into a common graph. Also
useful for pretty-printing single histograms or plots. Example:
\begin{code}
graph comparison {
$title = "$p_T$ distribution for two different values of $m_h$"
} = hist1 & hist2
\end{code}
% $
See Sec.~\ref{sec:graphs}.
\subsubsection{write\_analysis}
\begin{syntax}
write\_analysis (\var{analysis-objects})
\end{syntax}
Writes out data tables for the specified analysis objects (plots,
graphs, histograms). If the argument is empty or absent, write all
analysis objects currently available. The tables are
available for feeding external programs. Example:
\begin{code}
write_analysis
\end{code}
See Sec.~\ref{sec:analysis}.
\subsubsection{compile\_analysis}
\begin{syntax}
compile\_analysis (\var{analysis-objects})
\end{syntax}
Analogous to \ttt{write\_analysis}, but the generated data tables are
processed by \LaTeX\ and \gamelan, which produces Postscript and PDF
versions of the displayed data. Example:
\begin{code}
compile_analysis
\end{code}
See Sec.~\ref{sec:analysis}.
\section{Control Structures}
Like any complete programming language, \sindarin\ provides means for
branching and looping the program flow.
\subsection{Conditionals}
\subsubsection{if}
\begin{syntax}
if \var{logical\_expression} then \var{statements} \\
elsif \var{logical\_expression} then \var{statements} \\
else \var{statements} \\
endif
\end{syntax}
Execute statements conditionally, depending on the value of a logical
expression. There may be none or multiple \ttt{elsif} branches, and
the \ttt{else} branch is also optional. Example:
\begin{code}
if (sqrts > 2 * mtop) then
integrate (top_pair_production)
else
printf "Top pair production is not possible"
endif
\end{code}
The current \sindarin\ implementation puts some restriction on the
statements that can appear in a conditional. For instance, process
definitions must be done unconditionally.
\subsection{Loops}
\subsubsection{scan}
\begin{syntax}
scan \var{variable} = (\var{value-list}) \{ \var{statements} \}
\end{syntax}
Execute the statements repeatedly, once for each value of the scan
variable. The statements are executed in a local context, analogous
to the option statement list for commands. The value list is a
comma-separated list of expressions, where each item evaluates to the
value that is assigned to \ttt{\var{variable}} for this iteration.
The type of the variable is not restricted to numeric, scans can be
done for various object types. For instance, here is a scan over strings:
\begin{code}
scan string $str = ("%.3g", "%.4g", "%.5g") { printf $str (mW) }
\end{code}
% $
The output:
\begin{interaction}
[user variable] $str = "%.3g"
80.4
[user variable] $str = "%.4g"
80.42
[user variable] $str = "%.5g"
80.419
\end{interaction}
% $
For a numeric scan variable in particular, there are iterators that
implement the usual functionality of \ttt{for} loops. If the scan
variable is of type integer, an iterator may take one of the forms
\begin{syntax}
\var{start-value} \verb|=>| \var{end-value} \\
\var{start-value} \verb|=>| \var{end-value} \verb|/+| \var{add-step} \\
\var{start-value} \verb|=>| \var{end-value} \verb|/-| \var{subtract-step} \\
\var{start-value} \verb|=>| \var{end-value} \verb|/*| \var{multiplicator} \\
\var{start-value} \verb|=>| \var{end-value} \verb|//| \var{divisor} \\
\end{syntax}
The iterator can be put in place of an expression in the
\ttt{\var{value-list}}. Here is an example:
\begin{code}
scan int i = (1, (3 => 5), (10 => 20 /+ 4))
\end{code}
which results in the output
\begin{interaction}
[user variable] i = 1
[user variable] i = 3
[user variable] i = 4
[user variable] i = 5
[user variable] i = 10
[user variable] i = 14
[user variable] i = 18
\end{interaction}
[Note that the \ttt{\var{statements}} part of the scan construct may
be empty or absent.]
For real scan variables, there are even more possibilities for iterators:
\begin{syntax}
\var{start-value} \verb|=>| \var{end-value} \\
\var{start-value} \verb|=>| \var{end-value} \verb|/+| \var{add-step} \\
\var{start-value} \verb|=>| \var{end-value} \verb|/-| \var{subtract-step} \\
\var{start-value} \verb|=>| \var{end-value} \verb|/*| \var{multiplicator} \\
\var{start-value} \verb|=>| \var{end-value} \verb|//| \var{divisor} \\
\var{start-value} \verb|=>| \var{end-value} \verb|/+/| \var{n-points-linear} \\
\var{start-value} \verb|=>| \var{end-value} \verb|/*/| \var{n-points-logarithmic} \\
\end{syntax}
The first variant is equivalent to \ttt{/+ 1}. The \ttt{/+} and
\ttt{/-} operators are intended to add or subtract the given step once
for each iteration. Since in floating-point arithmetic this would be
plagued by rounding ambiguities, the actual implementation first
determines the (integer) number of iterations from the provided step
value, then recomputes the step so that the iterations are evenly
spaced with the first and last value included.
The \ttt{/*} and \ttt{//} operators are analogous. Here, the initial
value is intended to be multiplied by the step value once for each
iteration. After determining the integer number of iterations, the
actual scan values will be evenly spaced on a logarithmic scale.
Finally, the \ttt{/+/} and \ttt{/*/} operators allow to specify the
number of iterations (not counting the initial value) directly. The
\ttt{\var{start-value}} and \ttt{\var{end-value}} are always included,
and the intermediate values will be evenly spaced on a linear
(\ttt{/+/}) or logarithmic (\ttt{/*/}) scale.
Example:
\begin{code}
scan real mh = (130 GeV,
(140 GeV => 160 GeV /+ 5 GeV),
180 GeV,
(200 GeV => 1 TeV /*/ 10))
{ integrate (higgs_decay) }
\end{code}
\subsection{Including Files}
\subsubsection{include}
\begin{syntax}
include (\var{file-name})
\end{syntax}
Include a \sindarin\ script from the specified file. The contents
must be complete commands; they are compiled and executed as if they
were part of the current script. Example:
\begin{code}
include ("default_cuts.sin")
\end{code}
\section{Expressions}
\sindarin\ expressions are classified by their types. The
type of an expression is verified when the script is compiled, before
it is executed. This provides some safety against simple coding
errors.
Within expressions, grouping is done using ordinary brackets \ttt{()}.
For subevent expressions, use square brackets \ttt{[]}.
\subsection{Numeric}
The language supports the classical numeric types
\begin{itemize}
\item
\ttt{int} for integer: machine-default, usually 32 bit;
\item
\ttt{real}, usually \emph{double precision} or 64 bit;
\item
\ttt{complex}, consisting of real and imaginary part equivalent to a
\ttt{real} each.
\end{itemize}
\sindarin\ supports arithmetic expressions similar to conventional
languages. In arithmetic expressions, the three numeric types can be
mixed as appropriate. The computation essentially follows the rules
for mixed arithmetic in \fortran. The arithmetic operators are
\verb|+|, \verb|-|, \verb|*|, \verb|/|, \verb|^|. Standard functions
such as \ttt{sin}, \ttt{sqrt}, etc. are available. See
Sec.~\ref{sec:real} to Sec.~\ref{sec:complex}.
Numeric values can be associated with units. Units evaluate to
numerical factors, and their use is optional, but they can be useful
in the physics context for which \whizard\ is designed. Note that the
default energy/mass unit is \verb|GeV|, and the default unit for cross
sections is \verb|fbarn|.
\subsection{Logical and String}
The language also has the following standard types:
\begin{itemize}
\item
\ttt{logical} (a.k.a.\ boolean). Logical variable names have a
\ttt{?} (question mark) as prefix.
\item
\ttt{string} (arbitrary length). String variable names have a \ttt{\$}
(dollar) sign as prefix.
\end{itemize}
There are comparisons, logical operations, string concatenation, and a
mechanism for formatting objects as strings for output.
\subsection{Special}
Furthermore, \sindarin\ deals with a bunch of data types tailored
specifically for Monte Carlo applications:
\begin{itemize}
\item
\ttt{alias} objects denote a set of particle species.
\item
\ttt{subevt} objects denote a collection of particle momenta within an
event. They have their uses in cut and analysis expressions.
\item
\ttt{process} object are generated by a \ttt{process} statement.
There are no expressions involving processes, but they are referred
to by \ttt{integrate} and \ttt{simulate} commands.
\item
\ttt{model}: There is always a current object of type and name
\ttt{model}. Several models can be used concurrently by
appropriately defining processes, but this happens behind the scenes.
\item
\ttt{beams}: Similarly, the current implementation allows only for a single
object of this type at a given time, which is assigned by a \ttt{beams =}
statement and used by \ttt{integrate}.
\end{itemize}
In the current implementation, \sindarin\ has no container data types
derived from basic types, such as lists, arrays, or hashes, and there
are no user-defined data types. (The \ttt{subevt} type is a container
for particles in the context of events, but there is no type for an
individual particle: this is represented as a one-particle
\ttt{subevt}). There are also containers for inclusive processes which
are however simply handled as an expansion into several components of
a master process tag.
\section{Variables}
\label{sec:variables}
\sindarin\ supports global variables, variables local to a scoping unit (the
option body of a command, the body of a \ttt{scan} loop), and variables local
to an expression.
Some variables are predefined by the system (\emph{intrinsic
variables}). They are further separated into \emph{independent}
variables that can be reset by the user, and \emph{derived} or locked
variables that are automatically computed by the program, but not
directly user-modifiable. On top of that, the user is free to
introduce his own variables (\emph{user variables}).
The names of numerical variables consist of alphanumeric characters and
underscores. The first character must not be a digit. Logical
variable names are furthermore prefixed by a
\ttt{?} (question mark) sign, while string variable names begin
with a \ttt{\$} (dollar) sign.
Character case does matter. In this manual we follow the
convention that variable names consist of lower-case letters,
digits, and underscores only, but you may also use upper-case
letters if you wish.
Physics models contain their own, specific set of numeric variables
(masses, couplings). They are attached to the model where they are
defined, so they appear and disappear with the model that is currently
loaded. In particular, if two different models contain a variable
with the same name, these two variables are nevertheless distinct:
setting one doesn't affect the other. This feature might be called,
in computer-science jargon, a \emph{mixin}.
User variables -- global or local -- are declared by their type when they are
introduced, and acquire an initial value upon declaration. Examples:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
int i = 3
real my_cut_value = 10 GeV
complex c = 3 - 4 * I
logical ?top_decay_allowed = mH > 2 * mtop
string $hello = "Hello world!"
alias q = d:u:s:c
\end{verbatim}
\end{footnotesize}
\end{quote}
An existing user variable can be assigned a new value without a declaration:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
i = i + 1
\end{verbatim}
\end{footnotesize}
\end{quote}
and it may also be redeclared if the new declaration specifies the same type,
this is equivalent to assigning a new value.
Variables local to an expression are introduced by the \ttt{let ... in}
contruct. Example:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
real a = let int n = 2 in
x^n + y^n
\end{verbatim}
\end{footnotesize}
\end{quote}
The explicit \ttt{int} declaration is necessary only if the variable \ttt{n}
has not been declared before. An intrinsic variable must not be declared:
\ttt{let mtop = 175.3 GeV in \ldots}
\ttt{let} constructs can be concatenated if several local variables need to
be assigned: \ttt{let a = 3 in let b = 4 in \textit{expression}}.
Variables of type \ttt{subevt} can only be defined in \ttt{let} constructs.
Exclusively in the context of particle selections (event analysis), there are
\emph{observables} as special numeric objects. They are used like numeric
variables, but they are never declared or assigned. They get their value
assigned dynamically, computed from the particle momentum configuration.
Hence, they may be understood as (intrinsic and predefined) macros.
By convention, observable names begin with a capital letter.
Further macros are
\begin{itemize}
\item
\ttt{cuts} and \ttt{analysis}. They are of type logical, and can be
assigned an expression by the user. They are evaluated once for
each event.
\item
\ttt{scale}, \ttt{factorization\_scale} and
\ttt{renormalization\_scale} are real numeric macros which define the
energy scale(s) of an event. The latter two override the former.
If no scale is defined, the partonic energy is used as the process scale.
\item
\ttt{weight} is a real numeric macro. If it is assigned an
expression, the expression is evaluated for each valid phase-space
point, and the result multiplies the matrix element.
\end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{\sindarin\ in Details}
\label{chap:sindarin}
\section{Data and expressions}
\subsection{Real-valued objects}
\label{sec:real}
Real literals have their usual form, mantissa and, optionally, exponent:
\begin{center}
\ttt{0.}\quad \ttt{3.14}\quad \ttt{-.5}\quad
\ttt{2.345e-3}\quad \ttt{.890E-023}
\end{center}
Internally, real values are treated as double precision. The values are read
by the \fortran\ library, so details depend on its implementation.
A special feature of \sindarin\ is that numerics (real and integer) can be
immediately followed by a physical unit. The supported units are presently
hard-coded, they are
\begin{center}
\ttt{meV}\quad \ttt{eV}\quad \ttt{keV}\quad
\ttt{MeV}\quad \ttt{GeV}\quad \ttt{TeV}
\\
\ttt{nbarn}\quad \ttt{pbarn}\quad \ttt{fbarn}\quad \ttt{abarn}
\\
\ttt{rad}\quad \ttt{mrad}\quad \ttt{degree}
\\
\ttt{\%}
\end{center}
If a number is followed by a unit, it is automatically normalized to the
corresponding default unit: \ttt{14.TeV} is transformed into the real number
\ttt{14000.} Default units are \ttt{GeV}, \ttt{fbarn}, and \ttt{rad}. The
\ttt{\%} sign after a number has the effect that the number is multiplied by
$0.01$. Note that no checks for consistency of units are done, so you can add
\ttt{1 meV + 3 abarn} if you absolutely wish to. Omitting units is always
allowed, in that case, the default unit is assumed.
Units are not treated as variables. In particular, you can't write \ttt{theta
/ degree}, the correct form is \ttt{theta / 1 degree}.
There is a single predefined real constant, namely $\pi$ which is referred to
by the keyword \ttt{pi}. In addition, there is a single predefined
complex constant, which is the complex unit $i$, being referred to by
the keyword \ttt{I}.
The arithmetic operators are
\begin{center}
\verb|+| \verb|-| \verb|*| \verb|/| \verb|^|
\end{center}
with their obvious meaning and the usual precedence rules.
\sindarin\ supports a bunch of standard numerical functions, mostly equivalent
to their \fortran\ counterparts:
\begin{center}
\ttt{abs}\quad \ttt{conjg}\quad \ttt{sgn}\quad \ttt{mod}\quad \ttt{modulo}
\\
\ttt{sqrt}\quad \ttt{exp}\quad \ttt{log}\quad \ttt{log10}
\\
\ttt{sin}\quad \ttt{cos}\quad \ttt{tan}\quad
\ttt{asin}\quad \ttt{acos}\quad \ttt{atan}
\\
\ttt{sinh}\quad \ttt{cosh}\quad \ttt{tanh}
\end{center}
(Unlike \fortran, the \ttt{sgn} function takes only one argument and returns
$1.$, or $-1.$) The function argument is enclosed in brackets: \ttt{sqrt
(2.)}, \ttt{tan (11.5 degree)}.
There are two functions with two real arguments:
\begin{center}
\ttt{max}\quad \ttt{min}
\end{center}
Example: \verb|real lighter_mass = min (mZ, mH)|
The following functions of a real convert to integer:
\begin{center}
\ttt{int}\quad \ttt{nint}\quad \ttt{floor}\quad \ttt{ceiling} %% \; .
\end{center}
and this converts to complex type:
\begin{center}
\ttt{complex}
\end{center}
Real values can be compared by the following operators, the result is a
logical value:
\begin{center}
\verb|==|\quad \verb|<>|
\\
\verb|>|\quad \verb|<|\quad \verb|>=|\quad \verb|<=|
\end{center}
In \sindarin, it is possible to have more than two operands in a logical
expressions. The comparisons are done from left to right. Hence,
\begin{center}
\verb|115 GeV < mH < 180 GeV|
\end{center}
is valid \sindarin\ code and evaluates to \ttt{true} if the Higgs mass is in the
given range.
Tests for equality and inequality with machine-precision real numbers are
notoriously unreliable and should be avoided altogether. To deal with this
problem, \sindarin\ has the possibility to make the comparison operators
``fuzzy'' which should be read as ``equal (unequal) up to an absolute
tolerance'', where the tolerance is given by the real-valued intrinsic
variable \ttt{tolerance}. This variable is initially zero, but can be
set to any value (for instance, \ttt{tolerance = 1.e-13} by the user.
Note that for non-zero tolerance, operators like
\verb|==| and \verb|<>| or \verb|<| and \verb|>| are not mutually
exclusive\footnote{In older versions of \whizard, until v2.1.1, there
used to be separate comparators for the comparisons up to a tolerance,
namely \ttt{==\~{}} and \ttt{<>\~{}}. These have been discarded from
v2.2.0 on in order to simplify the syntax.}.
%%%%%%%%%%%%%%%
\subsection{Integer-valued objects}
\label{sec:integer}
Integer literals are obvious:
\begin{center}
\ttt{1}\quad \ttt{-98765}\quad \ttt{0123}
\end{center}
Integers are always signed. Their range is the default-integer range as
determined by the \fortran\ compiler.
Like real values, integer values can be followed by a physical unit: \ttt{1
TeV}, \ttt{30 degree}. This actually transforms the integer into a real.
Standard arithmetics is supported:
\begin{center}
\verb|+| \verb|-| \verb|*| \verb|/| \verb|^|
\end{center}
It is important to note that there is no fraction datatype, and pure integer
arithmetics does not convert to real. Hence \ttt{3/4} evaluates to \ttt{0},
but \ttt{3 GeV / 4 GeV} evaluates to \ttt{0.75}.
Since all arithmetics is handled by the underlying \fortran\ library, integer
overflow is not detected. If in doubt, do real arithmetics.
Integer functions are more restricted than real functions. We support the
following:
\begin{center}
\ttt{abs}\quad \ttt{sgn}\quad \ttt{mod}\quad \ttt{modulo}
\\
\ttt{max}\quad \ttt{min}
\end{center}
and the conversion functions
\begin{center}
\ttt{real}\quad \ttt{complex}
\end{center}
Comparisons of integers among themselves and with reals are possible using the
same set of comparison operators as for real values. This includes
the operators with a finite tolerance.
%%%%%%%%%%%%%%%%
\subsection{Complex-valued objects}
\label{sec:complex}
Complex variables and values are currently not yet used by the physics
models implemented in \whizard. There complex input coupling constants
are always split into their real and imaginary parts (or modulus and
phase). They are exclusively available for arithmetic calculations.
There is no form for complex literals. Complex values must be created via an
arithmetic expression,
\begin{center}
\ttt{complex c = 1 + 2 * I}
\end{center}
where the imaginary unit \ttt{I} is predefined as a constant.
The standard arithmetic operations are supported (also mixed with real and
integer). Support for functions is currently still incomplete, among the
supported functions there are \ttt{sqrt}, \ttt{log}, \ttt{exp}.
\subsection{Logical-valued objects}
There are two predefined logical constants, \ttt{true} and \ttt{false}.
Logicals are \emph{not} equivalent to integers (like in C) or to strings (like
in PERL), but they make up a type of their own. Only in \verb|printf| output,
they are treated as strings, that is, they require the \verb|%s| conversion
specifier.
The names of logical variables begin with a question mark \ttt{?}. Here is
the declaration of a logical user variable:
\begin{quote}
\begin{footnotesize}
\begin{footnotesize}
\begin{verbatim}
logical ?higgs_decays_into_tt = mH > 2 * mtop
\end{verbatim}
\end{footnotesize}
\end{footnotesize}
\end{quote}
Logical expressions use the standard boolean operations
\begin{center}
\ttt{or}\quad \ttt{and}\quad \ttt{not}
\end{center}
The results of comparisons (see above) are logicals.
There is also a special logical operator with lower priority, concatenation by
a semicolon:
\begin{center}
\ttt{\textit{lexpr1} ; \textit{lexpr2}}
\end{center}
This evaluates \textit{lexpr1} and throws its result away, then evaluates
\textit{lexpr2} and returns that result. This feature is to used with logical
expressions that have a side effect, namely the \ttt{record} function within
analysis expressions.
The primary use for intrinsic logicals are flags that change the behavior of
commands. For instance, \ttt{?unweighted = true} and \ttt{?unweighted =
false} switch the unweighting of simulated event samples on and off.
\subsection{String-valued objects and string operations}
\label{sec:sprintf}
String literals are enclosed in double quotes: \ttt{"This is a string."}
The empty string is \ttt{""}. String variables begin with the dollar
sign: \verb|$|. There is only one string operation, concatenation
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
string $foo = "abc" & "def"
\end{verbatim}
\end{footnotesize}
\end{quote}
However, it is possible to transform variables and values to a string using
the \ttt{sprintf} function. This function is an interface to the system's \ttt{C}
function \ttt{sprintf} with some restrictions and modifications. The allowed
conversion specifiers are
\begin{center}
\verb|%d|\quad \verb|%i| (integer)
\\
\verb|%e|\quad \verb|%f|\quad \verb|%g|\quad
\verb|%E|\quad \verb|%F|\quad \verb|%G| (real)
\\
\verb|%s| (string and logical)
\end{center}
The conversions can use flag parameter, field width, and precision, but length
modifiers are not supported since they have no meaning for the application.
(See also Sec.~\ref{sec:I/O}.)
The \ttt{sprintf} function has the syntax
\begin{center}
\ttt{sprintf} \textit{format-string}
\ttt{(}\textit{arg-list}\ttt{)}
\end{center}
This is an expression that evaluates to a string. The format string contains
the mentioned conversion specifiers. The argument list is optional. The
arguments are separated by commas. Allowed arguments are integer, real,
logical, and string variables, and numeric expressions. Logical and string
expressions can also be printed, but they have to be dressed as
\emph{anonymous variables}. A logical anonymous variable has the form
\ttt{?(}\textit{logical\_expr}\ttt{)} (example: \ttt{?(mH > 115 GeV)}). A
string anonymous variable has the form \ttt{\$(}\textit{string-expr}\ttt{)}.
Example:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
string $unit = "GeV"
string $str = sprintf "mW = %f %s" (mW, $unit)
\end{verbatim}
\end{footnotesize}
\end{quote}
The related \ttt{printf} command with the same syntax prints the formatted
string to standard output\footnote{In older versions of \whizard,
until v2.1.1, there also used to be a \ttt{sprintd} function and a
\ttt{printd} command for default formats without a format
string. They have been discarded in order to simplify the syntax
from version v2.2.0 on.}.
\section{Particles and (sub)events}
\subsection{Particle aliases}
\label{sec:alias}
A particle species is denoted by its name as a string: \verb|"W+"|.
Alternatively, it can be addressed by an \ttt{alias}. For instance, the $W^+$
boson has the alias \ttt{Wp}. Aliases are used like variables in a context
where a particle species is expected, and the user can specify his/her own
aliases.
An alias may either denote a single particle species or a class of particles
species. A colon \ttt{:} concatenates particle names and aliases to yield
multi-species aliases:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
alias quark = u:d:s
alias wboson = "W+":"W-"
\end{verbatim}
\end{footnotesize}
\end{quote}
Such aliases are used for defining processes with summation over flavors, and
for defining classes of particles for analysis.
Each model files define both names and (single-particle) aliases for all
particles it contains. Furthermore, it defines the class aliases
\verb|colored| and \verb|charged| which are particularly useful for event
analysis.
\subsection{Subevents}
Subevents are sets of particles, extracted from an event. The sets are
unordered by default, but may be ordered by appropriate functions. Obviously,
subevents are meaningful only in a context where an event is available. The
possible context may be the specification of a cut, weight, scale, or analysis
expression.
To construct a simple subevent, we put a particle alias or an expression of
type particle alias into square brackets:
\begin{quote}
\begin{footnotesize}
\verb|["W+"]|\quad
\verb|[u:d:s]|\quad
\verb|[colored]|
\end{footnotesize}
\end{quote}
These subevents evaluate to the set of all $W^+$ bosons (to be precise, their
four-momenta), all $u$, $d$, or $s$ quarks, and all colored particles,
respectively.
A subevent can contain pseudoparticles, i.e., particle combinations.
That is, the four-momenta of
distinct particles are combined (added conmponent-wise), and the results
become subevent elements just like ordinary particles.
The (pseudo)particles in a subevent are non-overlapping. That is, for
any of the particles in the original event, there is at most one
(pseudo)particle in the subevent in which it is contained.
Sometimes, variables (actually, named constants) of type subevent are useful.
Subevent variables are declared by the \ttt{subevt} keyword, and their
names carry the prefix \verb|@|. Subevent variables exist only within the
scope of a \verb|cuts| (or \verb|scale|, \verb|analysis|, etc.) macro, which
is evaluated in the presence of an actual event. In the macro body, they are
assigned via the \ttt{let} construct:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
cuts =
let subevt @jets = select if Pt > 10 GeV [colored]
in
all Theta > 10 degree [@jets, @jets]
\end{verbatim}
\end{footnotesize}
\end{quote}
In this expression, we first define \verb|@jets| to stand for the set of all
colored partons with $p_T>10\;\mathrm{GeV}$. This abbreviation is then used
in a logical expression, which evaluates to true if all relative angles
between distinct jets are greater than $10$ degree.
We note that the example also introduces pairs of subevents: the square
bracket with two entries evaluates to the list of all possible pairs which do
not overlap. The objects within square brackets can be either subevents or
alias expressions. The latter are transformed into subevents before they are
used.
As a special case, the original event is always available as the predefined
subevent \verb|@evt|.
\subsection{Subevent functions}
There are several functions that take a subevent (or an alias) as an argument
and return a new subevent. Here we describe them:
\subsubsection{collect}
\begin{quote}
\begin{footnotesize}
\ttt{collect [\textit{particles}]} \\
\ttt{collect if \textit{condition} [\textit{particles}]} \\
\ttt{collect if \textit{condition} [\textit{particles}, \textit{ref\_particles}]}
\end{footnotesize}
\end{quote}
First version: collect all particle momenta in the argument and combine them
to a single four-momentum. The \textit{particles} argument may either be a
\ttt{subevt} expression or an \ttt{alias} expression. The result is a
one-entry \ttt{subevt}. In the second form, only those particles are collected
which satisfy the \textit{condition}, a logical expression. Example:
\ttt{collect if Pt > 10 GeV [colored]}
The third version is useful if you want to put binary observables (i.e.,
observables constructed from two different particles) in the condition. The
\textit{ref\_particles} provide the second argument for binary observables in
the \textit{condition}. A particle is taken into account if the condition is
true with respect to all reference particles that do not overlap with this
particle. Example: \ttt{collect if Theta > 5 degree [photon, charged]}:
combine all photons that are separated by 5 degrees from all charged
particles.
\subsubsection{cluster}
\begin{quote}
\begin{footnotesize}
\ttt{cluster [\textit{particles}]} \\
\ttt{cluster if \textit{condition} [\textit{particles}]} \\
\end{footnotesize}
\end{quote}
First version: collect all particle momenta in the argument and cluster them
to a set of jets. The \textit{particles} argument may either be a
\ttt{subevt} expression or an \ttt{alias} expression. The result is a
one-entry \ttt{subevt}. In the second form, only those particles are clustered
which satisfy the \textit{condition}, a logical expression. Example:
\ttt{cluster if Pt > 10 GeV [colored]}
% The third version is usefule if you want to put binary observables (i.e.,
% observables constructed from two different particles) in the condition. The
% \textit{ref\_particles} provide the second argument for binary observables in
% the \textit{condition}. A particle is taken into account if the condition is
% true with respect to all reference particles that do not overlap with this
% particle. Example: \ttt{cluster if Theta > 5 degree [photon, charged]}:
% combine all photons that are separated by 5 degrees from all charged
% particles.
This command is available from \whizard\ version 2.2.1 on, and only if
the \fastjet\ package has been installed and linked with \whizard\
(cf. Sec.\ref{sec:fastjet}); in a future version of \whizard\ it is
foreseen to have also an intrinsic clustering package inside \whizard\
which will be able to support some of the clustering algorithms
below. To use it in an analysis, you have to set the variable
\ttt{jet\_algorithm} to one of the predefined jet-algorithm values
(integer constants):
\begin{quote}
\begin{footnotesize}
\ttt{kt\_algorithm}\\
\ttt{cambridge\_algorithm}\\
\ttt{antikt\_algorithm}\\
\ttt{genkt\_algorithm}\\
\ttt{cambridge\_for\_passive\_algorithm}\\
\ttt{genkt\_for\_passive\_algorithm}\\
\ttt{ee\_kt\_algorithm}\\
\ttt{ee\_genkt\_algorithm}\\
\ttt{plugin\_algorithm}
\end{footnotesize}
\end{quote}
and the variable \ttt{jet\_r} to the desired $R$ parameter value, as
appropriate for the analysis and the jet algorithm. Example:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
jet_algorithm = antikt_algorithm
jet_r = 0.7
cuts = all Pt > 15 GeV [cluster if Pt > 5 GeV [colored]]
\end{verbatim}
\end{footnotesize}
\end{quote}
\subsubsection{select\_b\_jet, select\_non\_b\_jet, select\_c\_jet,
select\_light\_jet}
This command is available from \whizard\ version 2.8.1 on, and it only
generates anything non-trivial if the \fastjet\ package has been
installed and linked with \whizard\ (cf. Sec.\ref{sec:fastjet}). It
only returns sensible results when it is applied to subevents after
the \ttt{cluster} command (cf. the paragraph before). It is similar to
the \ttt{select} command, and accepts a logical expression as a
possible condition. The four commands \ttt{select\_b\_jet},
\ttt{select\_non\_b\_jet}, \ttt{select\_c\_jet}, and
\ttt{select\_light\_jet} select $b$ jets, non-$b$ jets
(anything lighter than $b$s), $c$ jets (neither $b$ nor light) and
light jets (anything besides $b$ and $c$), respectively. An example
looks like this:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
alias lightjet = u:U:d:D:s:S:c:C:gl
alias jet = b:B:lightjet
process eebbjj = e1, E1 => b, B, lightjet, lightjet
jet_algorithm = antikt_algorithm
jet_r = 0.5
cuts = let subevt @clustered_jets = cluster [jet] in
let subevt @bjets = select_b_jet [@clustered_jets] in
.....
\end{verbatim}
\end{footnotesize}
\end{quote}
\subsubsection{photon\_isolation}
This command is available from \whizard\ version 2.8.1 on. It provides
isolation of photons from hadronic (and possibly electromagnetic)
activity in the event to define a (especially) NLO cross section that
is completely perturbative. The isolation criterion according to
Frixione, cf.~\cite{Frixione:1998jh}, removes the non-perturbative
contribution from the photon fragmentation function. This command can
in principle be applied to elementary hard process partons (and
leptons), but generates something sensible only if the
\fastjet\ package has been installed and linked with
\whizard\ (cf. Sec.\ref{sec:fastjet}). There are three parameters
which allow to tune the isolation, \ttt{photon\_iso\_r0}, which is the
radius $R^0_\gamma$ of the isolation cone, \ttt{photon\_iso\_eps},
which is the fraction $\epsilon_\gamma$ of the photon (transverse)
energy that enters the isolation criterion, and the exponent of the
isolation cone, \ttt{photon\_iso\_n}, $n^\gamma$. For more information
cf.~\cite{Frixione:1998jh}. The command allows also a conditional cut
on the photon which is applied before the isolation takes place. The
first argument are the photons in the event, the second the particles
from which they should be isolated. If also the electromagnetic
activity is to be isolated, photons need to be isolated from
themselves and must be included in the second argument. This is
mandatory if leptons appear in the second argument. Two examples look
like this:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
alias jet = u:U:d:D:s:S:c:C:gl
process eeaajj = e1, E1 => A, A, jet, jet
jet_algorithm = antikt_algorithm
jet_r = 0.5
cuts = photon_isolation if Pt > 10 GeV [A, jet]
....
cuts = let subevt @jets = cluster [jet] in
photon_isolation if Pt > 10 GeV [A, @jets]
.....
process eeajmm = e1, E1 => A, jet, e2, E2
cuts = let subevt @jets = cluster [jet] in
let subevt @iso = join [@jets, A:e2:E2]
photon_isolation [A, @iso]
\end{verbatim}
\end{footnotesize}
\end{quote}
\subsubsection{photon\_recombination}
\begin{quote}
\begin{footnotesize}
\ttt{photon\_recombination [\textit{photons}, \textit{particles}]} \\
\ttt{photon\_recombination if \textit{condition}} [\textit{photons}, \textit{particles}]
\end{footnotesize}
\end{quote}
This function, which maps subevents into other subevents, is used for
electroweak (and mixed coupling) higher order calculations. It takes
the selection of \texttt{photons} (for the moment, \whizard\ restricts
this to one explicit photon in final state) and recombines it with the
closest particle from \texttt{particles} in $R$-distance, if the
$R$-distance is smaller than the parameter set by
\texttt{photon\_rec\_r0}. Otherwise the \texttt{particles} subevent
is left unchanged. The logical variable
\texttt{?keep\_flavors\_when\_recombining} determines whether
\whizard\ keeps the flavor of the particle with which the photon is
recombined into the pseudoparticle, the default being \texttt{true}.
An example for photon recombination is shown here:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
alias lep = e1:e2:e3:E1:E2:E3
process eevv = e1, E1 => A, lep, lep, lep, lep
photon_rec_r0 = 0.15
cuts = let subevt @reco =
- photon_recombination if abs (Eta) < 2.5 [A, lep] in
+ photon_recombination if abs (Eta) < 2.5 [A:lep] in
....
\end{verbatim}
\end{footnotesize}
\end{quote}
\subsubsection{combine}
\begin{quote}
\begin{footnotesize}
\ttt{combine [\textit{particles\_1}, \textit{particles\_2}]} \\
\ttt{combine if \textit{condition}} [\textit{particles\_1}, \textit{particles\_2}]
\end{footnotesize}
\end{quote}
Make a new subevent of composite particles. The composites are generated by
combining all particles from subevent \textit{particles\_1} with all particles
from subevent \textit{particles\_2} in all possible combinations. Overlapping
combinations are excluded, however: if a (composite) particle in the first
argument has a constituent in common with a composite particle in the second
argument, the combination is dropped. In particular, this applies if the
particles are identical.
If a \textit{condition} is provided, the combination is done only when the
logical expression, applied to the particle pair in question, returns true.
For instance, here we reconstruct intermediate $W^-$ bosons:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
let @W_candidates = combine if 70 GeV < M < 80 GeV ["mu-", "numubar"]
in ...
\end{verbatim}
\end{footnotesize}
\end{quote}
Note that the combination may fail, so the resulting subevent could be empty.
\subsubsection{operator +}
If there is no condition, the $+$ operator provides a convenient
shorthand for the \verb|combine| command. In particular, it can be
used if there are several particles to combine. Example:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
cuts = any 170 GeV < M < 180 GeV [b + lepton + invisible]
\end{verbatim}
\end{footnotesize}
\end{quote}
\subsubsection{select}
\begin{quote}
\begin{footnotesize}
\ttt{select if \textit{condition} [\textit{particles}]} \\
\ttt{select if \textit{condition} [\textit{particles}, \textit{ref\_particles}]}
\end{footnotesize}
\end{quote}
One argument: select all particles in the argument that satisfy the
\textit{condition} and drop the rest. Two arguments: the
\textit{ref\_particles} provide a second argument for binary observables.
Select particles if the condition is satisfied for all reference particles.
\subsubsection{extract}
\begin{quote}
\begin{footnotesize}
\ttt{extract [\textit{particles}]} \\
\ttt{extract index \textit{index-value} [\textit{particles}]}
\end{footnotesize}
\end{quote}
Return a single-particle subevent. In the first version, it contains the
first particle in the subevent \textit{particles}. In the second version, the
particle with index \textit{index-value} is returned, where
\textit{index-value} is an integer expression. If its value is negative, the
index is counted from the end of the subevent.
The order of particles in an event or subevent is not always well-defined, so
you may wish to sort the subevent before applying the \textit{extract}
function to it.
\subsubsection{sort}
\begin{quote}
\begin{footnotesize}
\ttt{sort [\textit{particles}]} \\
\ttt{sort by \textit{observable} [\textit{particles}]} \\
\ttt{sort by \textit{observable} [\textit{particles}, \textit{ref\_particle}]}
\end{footnotesize}
\end{quote}
Sort the subevent according to some criterion. If no criterion is supplied
(first version), the subevent is sorted by increasing PDG code (first
particles, then antiparticles). In the second version, the
\textit{observable} is a real expression which is evaluated for each particle
of the subevent in turn. The subevent is sorted by increasing value of this
expression, for instance:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
let @sorted_evt = sort by Pt [@evt]
in ...
\end{verbatim}
\end{footnotesize}
\end{quote}
In the third version, a reference particle is provided as second argument, so
the sorting can be done for binary observables. It doesn't make much sense to
have several reference particles at once, so the \ttt{sort} function uses
only the first entry in the subevent \textit{ref-particle}, if it has more
than one.
\subsubsection{join}
\begin{quote}
\begin{footnotesize}
\ttt{join [\textit{particles}, \textit{new\_particles}]} \\
\ttt{join if \textit{condition} [\textit{particles}, \textit{new\_particles}]}
\end{footnotesize}
\end{quote}
This commands appends the particles in subevent \textit{new\_particles} to the
subevent \textit{particles}, i.e., it joins the two particle sets. To be
precise, a (pseudo)particle from \textit{new\_particles} is only appended if it
does not overlap with any of the (pseudo)particles
present in \textit{particles}, so the function will not produce overlapping
entries.
In the second version, each particle from \textit{new\_particles} is also
checked with all particles in the first set whether \textit{condition} is
fulfilled. If yes, and there is no overlap, it is appended, otherwise
it is dropped.
\subsubsection{operator \&}
Subevents can also be concatenated by the operator \verb|&|. This effectively
applies \ttt{join} to all operands in turn. Example:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
let @visible =
select if Pt > 10 GeV and E > 5 GeV [photon]
& select if Pt > 20 GeV and E > 10 GeV [colored]
& select if Pt > 10 GeV [lepton]
in ...
\end{verbatim}
\end{footnotesize}
\end{quote}
\subsection{Calculating observables}
Observables (invariant mass \ttt{M}, energy \ttt{E}, \ldots) are used in
expressions just like ordinary numeric variables. By convention, their names
-start with a capital letter. They are computed using a particle momentum (or
-two particle momenta) which are taken from a subsequent subevent argument.
+start with a capital letter. They are computed using a particle
+momentum (unary observables), or two particle momenta (binary
+observables) or all momenta of the particles (n-ary/subeventary
+observables) which are taken from a subsequent subevent argument.
We can extract the value of an observable for an event and make it available
for computing the \ttt{scale} value, or for histogramming etc.:
\subsubsection{eval}
\begin{quote}
\begin{footnotesize}
\ttt{eval \textit{expr} [\textit{particles}]} \\
\ttt{eval \textit{expr} [\textit{particles\_1}, \textit{particles\_2}]}
\end{footnotesize}
\end{quote}
The function \ttt{eval} takes an expression involving observables and
evaluates it for the first momentum (or momentum pair) of the subevent (or
subevent pair) in square brackets that follows the expression. For example,
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
eval Pt [colored]
\end{verbatim}
\end{footnotesize}
\end{quote}
evaluates to the transverse momentum of the first colored particle,
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
eval M [@jets, @jets]
\end{verbatim}
\end{footnotesize}
\end{quote}
evaluates to the invariant mass of the first distinct pair of jets (assuming
that \verb|@jets| has been defined in a \ttt{let} construct), and
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
eval E - M [combine [e1, N1]]
\end{verbatim}
\end{footnotesize}
\end{quote}
evaluates to the difference of energy and mass of the combination of the first
electron-neutrino pair in the event.
The last example illustrates why observables are treated like variables, even
though they are functions of particles: the \ttt{eval} construct with the
particle reference in square brackets after the expression allows to compute
derived observables -- observables which are functions of new observables --
without the need for hard-coding them as new functions.
+For subeventary observables, e.g. \ttt{Ht}, the momenta of all
+particles in the subevent are taken to evaluate the observables, e.g.
+\begin{quote}
+\begin{verbatim}
+ eval Ht/2 [t:T:Z:jet]
+\end{verbatim}
+\end{quote}
+takes the (half of) the transverse mass of all tops, $Z$s and jets in
+the final state.
+
+
+\subsubsection{sum}
+
+This \sindarin\ statement works similar to the \ttt{eval} statement
+above, with the syntax
+\begin{quote}
+\begin{verbatim}
+ sum <expr> [<subevt>]
+\end{verbatim}
+\end{quote}
+It sums the \ttt{<expr>} over all elements of the subevents
+\ttt{<subevt>}, e.g.
+\begin{quote}
+\begin{verbatim}
+ sum sqrt(Pt^2 + M^2)/2 [t:T:H:Z]
+\end{verbatim}
+\end{quote}
+would calculate the transverse mass (square root of the sum of squared
+transverse momentum and squared mass) of all tops, Higgs and $Z$
+bosons in the final state.
+
+\subsubsection{prod}
+
+Identical to \ttt{sum}, but takes the product, not the sum of the
+expression \ttt{<expr>} evaluated over the full subevent. Syntax:
+\begin{quote}
+\begin{verbatim}
+ prod <expr> [<subevt>]
+\end{verbatim}
+\end{quote}
\subsection{Cuts and event selection}
\label{sec:cuts}
Instead of a numeric value, we can use observables to compute a logical value.
\subsubsection{all}
\begin{quote}
\begin{footnotesize}
\ttt{all \textit{logical\_expr} [\textit{particles}]} \\
\ttt{all \textit{logical\_expr} [\textit{particles\_1}, \textit{particles\_2}]}
\end{footnotesize}
\end{quote}
The \ttt{all} construct expects a logical expression and one or two subevent
arguments in square brackets.
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
all Pt > 10 GeV [charged]
all 80 GeV < M < 100 GeV [lepton, antilepton]
\end{verbatim}
\end{footnotesize}
\end{quote}
In the second example, \ttt{lepton} and \ttt{antilepton} should be aliases
defined in a \ttt{let} construct. (Recall that aliases are promoted to
subevents if they occur within square brackets.)
This construction defines a cut. The result value is \ttt{true} if the
logical expression evaluates to \ttt{true} for all particles in the subevent
in square brackets. In the two-argument case it must be \ttt{true} for all
non-overlapping combinations of particles in the two subevents. If one of the
arguments is the empty subevent, the result is also \ttt{true}.
\subsubsection{any}
\begin{quote}
\begin{footnotesize}
\ttt{any \textit{logical\_expr} [\textit{particles}]} \\
\ttt{any \textit{logical\_expr} [\textit{particles\_1}, \textit{particles\_2}]}
\end{footnotesize}
\end{quote}
The \ttt{any} construct is true if the logical expression is true for at least
one particle or non-overlapping particle combination:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
any E > 100 GeV [photon]
\end{verbatim}
\end{footnotesize}
\end{quote}
This defines a trigger or selection condition. If a subevent argument is
empty, it evaluates to \ttt{false}
\subsubsection{no}
\begin{quote}
\begin{footnotesize}
\ttt{no \textit{logical\_expr} [\textit{particles}]} \\
\ttt{no \textit{logical\_expr} [\textit{particles\_1}, \textit{particles\_2}]}
\end{footnotesize}
\end{quote}
The \ttt{no} construct is true if the logical expression is true for no single
one particle or non-overlapping particle combination:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
no 5 degree < Theta < 175 degree ["e-":"e+"]
\end{verbatim}
\end{footnotesize}
\end{quote}
This defines a veto condition. If a subevent argument is empty, it
evaluates to \ttt{true}. It is equivalent to \ttt{not any\ldots}, but
included for notational convenience.
\subsection{More particle functions}
\subsubsection{count}
\begin{quote}
\begin{footnotesize}
\ttt{count [\textit{particles}]} \\
\ttt{count [\textit{particles\_1}, \textit{particles\_2}]} \\
\ttt{count if \textit{logical-expr} [\textit{particles}]} \\
\ttt{count if \textit{logical-expr} [\textit{particles}, \textit{ref\_particles}]}
\end{footnotesize}
\end{quote}
This counts the number of events in a subevent, the result is of type
\ttt{int}. If there is a conditional expression, it counts the number of
\ttt{particle} in the subevent that pass the test. If there are two
arguments, it counts the number of non-overlapping particle pairs (that pass
the test, if any).
\subsubsection{Predefined observables}
The following real-valued observables are available in \sindarin\ for use in
\ttt{eval}, \ttt{all}, \ttt{any}, \ttt{no}, and \ttt{count} constructs. The
argument is always the subevent or alias enclosed in square brackets.
\begin{itemize}
\item \ttt{M2}
\begin{itemize}
\item One argument: Invariant mass squared of the (composite) particle in the
argument.
\item Two arguments: Invariant mass squared of the sum of the two momenta.
\end{itemize}
\item \ttt{M}
\begin{itemize}
\item Signed square root of \ttt{M2}: positive if $\ttt{M2}>0$, negative if
$\ttt{M2}<0$.
\end{itemize}
\item \ttt{E}
\begin{itemize}
\item One argument: Energy of the (composite) particle in the argument.
\item Two arguments: Sum of the energies of the two momenta.
\end{itemize}
\item \ttt{Px}, \ttt{Py}, \ttt{Pz}
\begin{itemize}
\item Like \ttt{E}, but returning the spatial momentum components.
\end{itemize}
\item \ttt{P}
\begin{itemize}
\item Like \ttt{E}, returning the absolute value of the spatial momentum.
\end{itemize}
\item \ttt{Pt}, \ttt{Pl}
\begin{itemize}
\item Like \ttt{E}, returning the transversal and longitudinal momentum,
respectively.
\end{itemize}
\item \ttt{Theta}
\begin{itemize}
\item One argument: Absolute polar angle in the lab frame
\item Two arguments: Angular distance of two particles in the lab frame.
\end{itemize}
\item \ttt{Theta\_star}
Only with two arguments, gives the relative polar angle of the two momenta
in the rest system of the momentum sum (i.e. mother particle).
\item \ttt{Phi}
\begin{itemize}
\item One argument: Absolute azimuthal angle in the lab frame
\item Two arguments: Azimuthal distance of two particles in the lab frame
\end{itemize}
\item \ttt{Rap}, \ttt{Eta}
\begin{itemize}
\item One argument: rapidity / pseudorapidity
\item Two arguments: rapidity / pseudorapidity difference
\end{itemize}
\item \ttt{Dist}
\begin{itemize}
\item Two arguments: Distance on the $\eta$-$\phi$ cylinder, i.e.,
$\sqrt{\Delta\eta^2 + \Delta\phi^2}$
\end{itemize}
\item \ttt{kT}
\begin{itemize}
\item Two arguments: $k_T$ jet clustering variable:
$2 \min (E_{j1}^2, E_{j2}^2) / Q^2 \times (1 -
\cos\theta_{j1,j2})$. At the moment, $Q^2 = 1$ GeV$^2$.
\end{itemize}
\end{itemize}
There are also integer-valued observables:
\begin{itemize}
\item \ttt{PDG}
\begin{itemize}
\item One argument: PDG code of the particle. For a composite particle, the
code is undefined (value 0). For flavor sums in the \ttt{cuts} statement,
this observable always returns the same flavor, i.e. the first one from the
flavor list. It is thus only sensible to use it in an \ttt{analysis} or
\ttt{selection} statement when simulating events.
\end{itemize}
\item \ttt{Ncol}
\begin{itemize}
\item One argument: Number of open color lines. Only count color
lines, not anticolor lines. This is defined only if the global flag
\ttt{?colorize\_subevt} is true.
\end{itemize}
\item \ttt{Nacl}
\begin{itemize}
\item One argument: Number of open anticolor lines. Only count anticolor
lines, not color lines. This is defined only if the global flag
\ttt{?colorize\_subevt} is true.
\end{itemize}
\end{itemize}
%%%%%%%%%%%%%%%
\section{Physics Models}
\label{sec:models}
A physics model is a combination of particles, numerical parameters (masses,
couplings, widths), and Feynman rules. Many physics analyses are done in the
context of the Standard Model (SM). The SM is also the default model for
\whizard. Alternatively, you can choose a subset of the SM (QED or QCD),
variants of the SM (e.g., with or without nontrivial CKM matrix), or various
extensions of the SM. The complete list is displayed in
Table~\ref{tab:models}.
The model definitions are contained in text files with filename extension
\ttt{.mdl}, e.g., \ttt{SM.mdl}, which are located in the \ttt{share/models}
subdirectory of the \whizard\ installation. These files are easily readable,
so if you need details of a model implementation, inspect their contents. The
model file contains the complete particle and parameter definitions as well as
their default values. It also contains a list of vertices. This is used only
for phase-space setup; the vertices used for generating amplitudes and the
corresponding Feynman rules are stored in different files within the
\oMega\ source tree.
In a \sindarin\ script, a model is a special object of type \ttt{model}. There
is always a \emph{current} model. Initially, this is the SM, so on startup
\whizard\ reads the \ttt{SM.mdl} model file and assigns its content to the
current model object. (You can change the default model by the \ttt{--model}
option on the command line. Also the preloading of a model can be
switched off with the \ttt{--no-model} option) Once the model has
been loaded, you can define processes for the model, and you have all
independent model parameters at your disposal. As noted before, these
are intrinsic parameters which need not be declared when you assign
them a value, for instance:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
mW = 80.33 GeV
wH = 243.1 MeV
\end{verbatim}
\end{footnotesize}
\end{quote}
Other parameters are \emph{derived}. They can be used in expressions like any
other parameter, they are also intrinsic, but they cannot be modified directly
at all. For instance, the electromagnetic coupling \ttt{ee} is a derived
parameter. If you change either \ttt{GF} (the Fermi constant), \ttt{mW} (the
$W$ mass), or \ttt{mZ} (the $Z$ mass), this parameter will reflect the change,
but setting it directly is an error. In other words, the SM is defined within
\whizard\ in the $G_F$-$m_W$-$m_Z$ scheme. (While this scheme is unusual for
loop calculations, it is natural for a tree-level event generator where the
$Z$ and $W$ poles have to be at their experimentally determined
location\footnote{In future versions of \whizard\ it is foreseen to
implement other electroweak schemes.}.)
The model also defines the particle names and aliases that you can use for
defining processes, cuts, or analyses.
If you would like to generate a SUSY process instead, for instance, you can
assign a different model (cf.\ Table~\ref{tab:models}) to the current model
object:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
model = MSSM
\end{verbatim}
\end{footnotesize}
\end{quote}
This assignment has the consequence that the list of SM parameters and
particles is replaced by the corresponding MSSM list (which is much longer).
The MSSM contains essentially all SM parameters by the same name, but in fact
they are different parameters. This is revealed when you say
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
model = SM
mb = 5.0 GeV
model = MSSM
show (mb)
\end{verbatim}
\end{footnotesize}
\end{quote}
After the model is reassigned, you will see the MSSM value of $m_b$ which
still has its default value, not the one you have given. However, if you
revert to the SM later,
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
model = SM
show (mb)
\end{verbatim}
\end{footnotesize}
\end{quote}
you will see that your modification of the SM's $m_b$ value has been
remembered. If you want both mass values to agree, you have to set them
separately in the context of their respective model. Although this might seem
cumbersome at first, it is nevertheless a sensible procedure since the
parameters defined by the user might anyhow not be defined or available for
all chosen models.
When using two different models which need an SLHA input file,
these {\em have} to be provided for both models.
Within a given scope, there is only one current model. The current model can
be reset permanently as above. It can also be temporarily be reset in a local
scope, i.e., the option body of a command or the body of a \ttt{scan} loop.
It is thus possible to use several models within the same script. For
instance, you may define a SUSY signal process and a pure-SM background
process. Each process depends only on the respective model's parameter set,
and a change to a parameter in one of the models affects only the
corresponding process.
\section{Processes}
\label{sec:processes}
The purpose of \whizard\ is the integration and simulation of high-energy
physics processes: scatterings and decays. Hence, \ttt{process} objects play
the central role in \sindarin\ scripts.
A \sindarin\ script may contain an arbitrary number of process definitions. The
initial states need not agree, and the processes may belong to different
physics models.
\subsection{Process definition}
\label{sec:procdef}
A process object is defined in a straightforward notation. The definition
syntax is straightforward:
\begin{quote}
\begin{footnotesize}
\ttt{process \textit{process-id} = \textit{incoming-particles}} \verb|=>|
\ttt{\textit{outgoing-particles}}
\end{footnotesize}
\end{quote}
Here are typical examples:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
process w_pair_production = e1, E1 => "W+", "W-"
process zdecay = Z => u, ubar
\end{verbatim}
\end{footnotesize}
\end{quote}
Throughout the program, the process will be identified by its
\textit{process-id}, so this is the name of the process object. This
identifier is arbitrary, chosen by the user. It follows the rules for
variable names, so it consists of alphanumeric characters and underscores,
where the first character is not numeric. As a special rule, it must not
contain upper-case characters. The reason is that this name is used for
identifying the process not just within the script, but also within the
\fortran\ code that the matrix-element generator produces for this process.
After the equals sign, there follow the lists of incoming and outgoing
particles. The number of incoming particles is either one or two: scattering
processes and decay processes. The number of outgoing particles should be two
or larger (as $2\to 1$ processes are proportional to a $\delta$
function they can only be sensibly integrated when using a structure
function like a hadron collider PDF or a beamstrahlung spectrum.).
There is no hard upper limit; the complexity of processes that
\whizard\ can handle depends only on the practical computing
limitations (CPU time and memory). Roughly speaking, one can assume
that processes up to $2\to 6$ particles are safe, $2\to 8$ processes
are feasible given sufficient time for reaching a stable integration,
while more complicated processes are largely unexplored.
We emphasize that in the default setup, the matrix element of a physics
process is computed exactly in leading-order perturbation theory, i.e., at
tree level. There is no restriction of intermediate states, the result always
contains the complete set of Feynman graphs that connect the initial with the
final state. If the result would actually be expanded in Feynman graphs
(which is not done by the \oMega\ matrix element generator that
\whizard\ uses), the number of graphs can easily reach several thousands,
depending on the complexity of the process and on the physics model.
More details about the different methods for quantum field-theoretical
matrix elements can be found in Chap.~\ref{chap:hardint}. In the
following, we will discuss particle names, options for processes like
restrictions on intermediate states, parallelization, flavor sums and
process components for inclusive event samples (process containers).
\subsection{Particle names}
The particle names are taken from the particle definition in the current model
file. Looking at the SM, for instance, the electron entry in
\ttt{share/models/SM.mdl} reads
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
particle E_LEPTON 11
spin 1/2 charge -1 isospin -1/2
name "e-" e1 electron e
anti "e+" E1 positron
tex_name "e^-"
tex_anti "e^+"
mass me
\end{verbatim}
\end{footnotesize}
\end{quote}
This tells that you can identify an electron either as \verb|"e-"|, \verb|e1|,
\verb|electron|, or simply \verb|e|. The first version is used for output,
but needs to be quoted, because otherwise \sindarin\ would interpret the minus
sign as an operator. (Technically, unquoted particle identifiers are aliases,
while the quoted versions -- you can say either \verb|e1| or \verb|"e1"| --
are names. On input, this makes no difference.) The alternative version
\verb|e1| follows a convention, inherited from
\comphep~\cite{Boos:2004kh}, that particles are indicated by lower
case, antiparticles by upper case, and for leptons, the generation
index is appended: \verb|e2| is the muon, \verb|e3| the tau. These
alternative names need not be quoted because they contain no special
characters.
In Table~\ref{tab:SM-particles}, we list the recommended names as well as
mass and width parameters for all SM particles. For other models, you may
look up the names in the corresponding model file.
\begin{table}[p]
\begin{center}
\begin{tabular}{|l|l|l|l|cc|}
\hline
& Particle & Output name & Alternative names & Mass & Width\\
\hline\hline
Leptons
&$e^-$ & \verb|e-| & \ttt{e1}\quad\ttt{electron} & \ttt{me} & \\
&$e^+$ & \verb|e+| & \ttt{E1}\quad\ttt{positron} & \ttt{me} & \\
\hline
&$\mu^-$ & \verb|mu-| & \ttt{e2}\quad\ttt{muon} & \ttt{mmu} & \\
&$\mu^+$ & \verb|mu+| & \ttt{E2} & \ttt{mmu} & \\
\hline
&$\tau^-$ & \verb|tau-| & \ttt{e3}\quad\ttt{tauon} & \ttt{mtau} & \\
&$\tau^+$ & \verb|tau+| & \ttt{E3} & \ttt{mtau} & \\
\hline\hline
Neutrinos
&$\nu_e$ & \verb|nue| & \ttt{n1} & & \\
&$\bar\nu_e$ & \verb|nuebar| & \ttt{N1} & & \\
\hline
&$\nu_\mu$ & \verb|numu| & \ttt{n2} & & \\
&$\bar\nu_\mu$ & \verb|numubar| & \ttt{N2} & & \\
\hline
&$\nu_\tau$ & \verb|nutau| & \ttt{n3} & & \\
&$\bar\nu_\tau$ & \verb|nutaubar| & \ttt{N3} & & \\
\hline\hline
Quarks
&$d$ & \verb|d| & \ttt{down} & & \\
&$\bar d$ & \verb|dbar| & \ttt{D} & & \\
\hline
&$u$ & \verb|u| & \ttt{up} & & \\
&$\bar u$ & \verb|ubar| & \ttt{U} & & \\
\hline
&$s$ & \verb|s| & \ttt{strange} & \ttt{ms} & \\
&$\bar s$ & \verb|sbar| & \ttt{S} & \ttt{ms} & \\
\hline
&$c$ & \verb|c| & \ttt{charm} & \ttt{mc} & \\
&$\bar c$ & \verb|cbar| & \ttt{C} & \ttt{mc} & \\
\hline
&$b$ & \verb|b| & \ttt{bottom} & \ttt{mb} & \\
&$\bar b$ & \verb|bbar| & \ttt{B} & \ttt{mb} & \\
\hline
&$t$ & \verb|t| & \ttt{top} & \ttt{mtop} & \ttt{wtop} \\
&$\bar t$ & \verb|tbar| & \ttt{T} & \ttt{mtop} & \ttt{wtop} \\
\hline\hline
Vector bosons
&$g$ & \verb|gl| & \ttt{g}\quad\ttt{G}\quad\ttt{gluon} & & \\
\hline
&$\gamma$ & \verb|A| & \ttt{gamma}\quad\ttt{photon} & & \\
\hline
&$Z$ & \verb|Z| & & \ttt{mZ} & \ttt{wZ} \\
\hline
&$W^+$ & \verb|W+| & \ttt{Wp} & \ttt{mW} & \ttt{wW} \\
&$W^-$ & \verb|W-| & \ttt{Wm} & \ttt{mW} & \ttt{wW} \\
\hline\hline
Scalar bosons
&$H$ & \verb|H| & \ttt{h}\quad \ttt{Higgs} & \ttt{mH} & \ttt{wH} \\
\hline
\end{tabular}
\end{center}
\caption{\label{tab:SM-particles} Names that can be used for SM particles.
Also shown are the intrinsic variables that can be used to set mass and
width, if applicable.}
\end{table}
Where no mass or width parameters are listed in the table, the particle is
assumed to be massless or stable, respectively. This is obvious for particles
such as the photon. For neutrinos, the mass is meaningless to particle
physics collider experiments, so it is zero. For quarks, the $u$ or
$d$ quark mass is unobservable directly, so we also set it zero. For
the heavier quarks, the mass may play a role, so it is kept. (The $s$
quark is borderline; one may argue that its mass is also unobservable
directly.) On the other hand, the electron mass is relevant, e.g., in
photon radiation without cuts, so it is not zero by default.
It pays off to set particle masses to zero, if the approximation is justified,
since fewer helicity states will contribute to the matrix element. Switching
off one of the helicity states of an external fermion speeds up the
calculation by a factor of two. Therefore, script files will usually contain
the assignments
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
me = 0 mmu = 0 ms = 0 mc = 0
\end{verbatim}
\end{footnotesize}
\end{quote}
unless they deal with processes where this simplification is
phenomenologically unacceptable. Often $m_\tau$ and $m_b$ can also be
neglected, but this excludes processes where the Higgs couplings of $\tau$ or
$b$ are relevant.
Setting fermion masses to zero enables, furthermore, the possibility to define
multi-flavor aliases
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
alias q = d:u:s:c
alias Q = D:U:S:C
\end{verbatim}
\end{footnotesize}
\end{quote}
and handle processes such as
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
process two_jets_at_ilc = e1, E1 => q, Q
process w_pairs_at_lhc = q, Q => Wp, Wm
\end{verbatim}
\end{footnotesize}
\end{quote}
where a sum over all allowed flavor combination is automatically included.
For technical reasons, such flavor sums are possible only for massless
particles (or more general for mass-degenerate particles). If you want
to generate inclusive processes with sums over particles of different
masses (e.g. summing over $W/Z$ in the final state etc.), confer below
the section about process components, Sec.~\ref{sec:processcomp}.
Assignments of masses, widths and other parameters are actually in effect when
a process is integrated, not when it is defined. So, these assignments may
come before or after the process definition, with no significant difference.
However, since flavor summation requires masses to be zero, the assignments
may be put before the alias definition which is used in the process.
The muon, tau, and the heavier quarks are actually unstable. However, the
width is set to zero because their decay is a macroscopic effect and, except for
the muon, affected by hadron physics, so it is not described by \whizard. (In
the current \whizard\ setup, all decays occur at the production vertex. A
future version may describe hadronic physics and/or macroscopic particle
propagation, and this restriction may be eventually removed.)
\subsection{Options for processes}
\label{sec:process options}
The \ttt{process} definition may contain an optional argument:
\begin{quote}
\begin{footnotesize}
\ttt{process \textit{process-id} = \textit{incoming-particles}} \verb|=>|
\ttt{\textit{outgoing-particles}} \ttt{\{\textit{options\ldots}\}}
\end{footnotesize}
\end{quote}
The \textit{options} are a \sindarin\ script that is executed in a context local
to the \ttt{process} command. The assignments it contains apply only to the
process that is defined. In the following, we describe the set of potentially
useful options (which all can be also set globally):
\subsubsection{Model reassignment}
It is possible to locally reassign the model via a \ttt{model =} statment,
permitting the definition of process using a model other than the globally
selected model. The process will retain this association during
integration and event generation.
\subsubsection{Restrictions on matrix elements}
\label{subsec:restrictions}
Another useful option is the setting
\begin{quote}
\begin{footnotesize}
\verb|$restrictions =| \ttt{\textit{string}}
\end{footnotesize}
\end{quote}
This option allows to select particular classes of Feynman graphs for the
process when using the \oMega\ matrix element generator. The
\verb|$restrictions| string specifies e.g. propagators that the graph
must contain. Here is an example:
\begin{code}
process zh_invis = e1, E1 => n1:n2:n3, N1:N2:N3, H { $restrictions = "1+2 ~ Z" }
\end{code}
The complete process $e^-e^+ \to \nu\bar\nu H$, summed over all neutrino
generations, contains both $ZH$ pair production (Higgs-strahlung) and
$W^+W^-\to H$ fusion. The restrictions string selects the Higgs-strahlung
graph where the initial electrons combine to a $Z$ boson. Here, the particles
in the process are consecutively numbered, starting with the initial
particles. An alternative for the same selection would be
\verb|$restrictions = "3+4 ~ Z"|. Restrictions can be combined using
\verb|&&|, for instance
\begin{code}
$restrictions = "1+2 ~ Z && 3 + 4 ~ Z"
\end{code}
which is redundant here, however.
The restriction keeps the full energy dependence in the intermediate
propagator, so the Breit-Wigner shape can be observed in distributions. This
breaks gauge invariance, in particular if the intermediate state is off shell,
so you should use the feature only if you know the implications. For
more details, cf. the Chap.~\ref{chap:hardint} and the \oMega\ manual.
Other restrictions that can be combined with the restrictions above on
intermediate propagators allow to exclude certain particles from
intermediate propagators, or to exclude certain vertices from the
matrix elements. For example,
\begin{code}
process eemm = e1, E1 => e2, E2 { $restrictions = "!A" }
\end{code}
would exclude all photon propagators from the matrix element and
leaves only the $Z$ exchange here. In the same way,
\verb|$restrictions = "!gl"| would exclude all gluon exchange. This
exclusion of internal propagators works also for lists of particles,
like
\begin{code}
$restrictions = "!Z:H"
\end{code}
excludes all $Z$ and $H$ propagators from the matrix elements.
Besides excluding certain particles as internal lines, it is also
possible to exclude certain vertices using the restriction command
\begin{code}
process eeww = e1, E1 => Wp, Wm { $restrictions = "^[W+,W-,Z]" }
\end{code}
This would generate the matrix element for the production of two $W$
bosons at LEP without the non-Abelian vertex $W^+W^-Z$. Again, these
restrictions are able to work on lists, so
\begin{code}
$restrictions = "^[W+,W-,A:Z]"
\end{code}
would exclude all triple gauge boson vertices from the above process
and leave only the $t$-channel neutrino exchange.
It is also possible to exlude vertices by their coupling constants,
e.g. the photon exchange in the process $e^+ e^- \to \mu^+ \mu^-$ can
also be removed by the following restriction:
\begin{code}
$restrictions = "^qlep"
\end{code}
Here, \ttt{qlep} is the \fortran\ variable for the coupling constant
of the electron-positron-photon vertex.
\begin{table}
\begin{center}
\begin{tabular}{|l|l|}
\hline
\verb|3+4~Z| & external particles 3 and 4 must come from
intermediate $Z$ \\\hline
\verb| && | & logical ``and'', e.g. in
\verb| 3+5~t && 4+6~tbar| \\\hline
\verb| !A | & exclude all $\gamma$ propagators \\\hline
\verb| !e+:nue | & exclude a list of propagators, here $\gamma$,
$\nu_e$ \\\hline
\verb|^qlep:gnclep| & exclude all vertices with
\ttt{qlep},\ttt{gnclep} coupling constants \\\hline
\verb|^[A:Z,W+,W-]| & exclude all vertices $W^+W^-Z$,
$W^+W^-\gamma$ \\\hline
\verb|^c1:c2:c3[H,H,H]| & exclude all triple Higgs couplings
with $c_i$ constants
\\\hline
\end{tabular}
\end{center}
\caption{List of possible restrictions that can be applied to
\oMega\ matrix elements.}
\label{tab:restrictions}
\end{table}
The Tab.~\ref{tab:restrictions} gives a list of options that can be
applied to the \oMega\ matrix elements.
\subsubsection{Other options}
There are some further options that the \oMega\ matrix-element generator can
take. If desired, any string of options that is contained in this variable
\begin{quote}
\begin{footnotesize}
\verb|$omega_flags =| \ttt{\textit{string}}
\end{footnotesize}
\end{quote}
will be copied verbatim to the \oMega\ call, after all other options.
One important application is the scheme of treating the width of unstable
particles in the $t$-channel. This is modified by the \verb|model:| class of
\oMega\ options.
It is well known that for some processes, e.g., single $W$ production from
photon-$W$ fusion, gauge invariance puts constraints on the treatment of the
unstable-particle width. By default, \oMega\ puts a nonzero width in the $s$
channel only. This correctly represents the resummed Dyson series for the
propagator, but it violates QED gauge invariance, although the effect is only
visible if the cuts permit the photon to be almost on-shell.
An alternative is
\begin{quote}
\begin{footnotesize}
\verb|$omega_flags = "-model:fudged_width"|
\end{footnotesize},
\end{quote}
which puts zero width in the matrix element, so that gauge cancellations
hold, and reinstates the $s$-channel width in the appropriate places by an
overall factor that multiplies the whole matrix element.
Note that the fudged width option only applies to charged unstable particles, such as the $W$ boson or top quark.
Another possibility is
\begin{quote}
\begin{footnotesize}
\verb|$omega_flags = "-model:constant_width"|
\end{footnotesize},
\end{quote}
which puts the width both in the $s$- and in the $t$-channel like diagrams.
A third option is provided by the running width scheme
\begin{quote}
\begin{footnotesize}
\verb|$omega_flags = "-model:running_width"|
\end{footnotesize},
\end{quote}
which applies the width only for $s$-channel like diagrams and multiplies it by a factor of $p^2 / M^2$.
The additional $p^2$-dependent factor mimicks the momentum dependence of the imaginary part of a vacuum polarization for a particle decaying into massles decay products.
It is noted that none of the above options preserves gauge invariance.
For a gauge preserving approach (at least at tree level), \oMega\ provides the complex-mass scheme
\begin{quote}
\begin{footnotesize}
\verb|$omega_flags = "-model:cms_width|
\end{footnotesize}.
\end{quote}
However, in this case, one also has to modify the model in usage.
For example, the parameter setting for the Standard Model can be changed by,
\begin{quote}
\begin{footnotesize}
\verb|model = SM (Complex_Mass_Scheme)|
\end{footnotesize}.
\end{quote}
\subsubsection{Multithreaded calculation of helicity sums via OpenMP}
\label{sec:openmp}
On multicore and / or multiprocessor systems, it is possible to speed
up the calculation by using multiple threads to perform the helicity
sum in the matrix element calculation. As the processing time used by
\whizard\ is not used up solely in the matrix element, the speedup thus
achieved varies greatly depending on the process under consideration;
while simple processes without flavor sums do not profit significantly
from this parallelization, the computation time for processes
involving flavor sums with four or more particles in the final state
is typically reduced by a factor between two and three when utilizing
four parallel threads.
The parallization is implemented using \ttt{OpenMP} and requires
\whizard\ to be compiled with an \ttt{OpenMP} aware compiler and the
appropiate compiler flags This is done in the configuration step, cf.\
Sec.~\ref{sec:installation}.
As with all \ttt{OpenMP} programs, the default number of threads used at
runtime is up to the compiler runtime support and typically set to the
number of independent hardware threads (cores / processors /
hyperthreads) available in the system. This default can be adjusted
by setting the \ttt{OMP\_NUM\_THREADS} environment variable prior to
calling WHIZARD. Alternatively, the available number of threads can
be reset anytime by the \sindarin\ parameter
\ttt{openmp\_num\_threads}. Note however that the total number of
threads that can be sensibly used is limited by the number of
nonvanishing helicity combinations.
%%%%%%%%%%%%%%%
\subsection{Process components}
\label{sec:processcomp}
It was mentioned above that processes with flavor sums (in the initial
or final state or both) have to be mass-degenerate (in most cases
massless) in all particles that are summed over at a certain
position. This condition is necessary in order to use the same
phase-space parameterization and integration for the flavor-summed
process. However, in many applications the user wants to handle
inclusive process definitions, e.g. by defining inclusive decays,
inclusive SUSY samples at hadron colliders (gluino pairs, squark
pairs, gluino-squark associated production), or maybe lepton-inclusive
samples where the tau and muon mass should be kept at different
values. In \whizard\, from version v2.2.0 on, there is the possibility
to define such inclusive process containers. The infrastructure for
this feature is realized via so-called process components: processes
are allowed to contain several process components. Those components
need not be provided by the same matrix element generator,
e.g. internal matrix elements, \oMega\ matrix elements, external
matrix element (e.g. from a one-loop program, OLP) can be mixed. The
very same infrastructure can also be used for next-to-leading order
(NLO) calculations, containing the born with real emission, possible
subtraction terms to make the several components infrared- and
collinear finite, as well as the virtual corrections.
Here, we want to discuss the use for inclusive particle samples. There
are several options, the simplest of which to add up different final
states by just using the \ttt{+} operator in \sindarin, e.g.:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
process multi_comp = e1, E1 => (e2, E2) + (e3, E3) + (A, A)
\end{verbatim}
\end{footnotesize}
\end{quote}
The brackets are not only used for a better grouping of the expressions,
they are not mandatory for \whizard\ to interpret the sum
correctly. When integrating, \whizard\ tells you that this a process
with three different components:
\begin{footnotesize}
\begin{Verbatim}
| Initializing integration for process multi_comp_1_p1:
| ------------------------------------------------------------------------
| Process [scattering]: 'multi_comp'
| Library name = 'default_lib'
| Process index = 1
| Process components:
| 1: 'multi_comp_i1': e-, e+ => m-, m+ [omega]
| 2: 'multi_comp_i2': e-, e+ => t-, t+ [omega]
| 3: 'multi_comp_i3': e-, e+ => A, A [omega]
| ------------------------------------------------------------------------
\end{Verbatim}
\end{footnotesize}
A different phase-space setup is used for each different
component. The integration for each different component is performed
separately, and displayed on screen. At the end, a sum of all
components is shown. All files that depend on the components are being
attached an \ttt{\_i{\em <n>}} where \ttt{{\em <n>}} is the number of
the process component that appears in the list above: the \fortran\
code for the matrix element, the \ttt{.phs} file for the phase space
parameterization, and the grid files for the \vamp\ Monte-Carlo
integration (or any other integration method). However, there will be
only one event file for the inclusive process, into which a mixture of
events according to the size of the individual process component cross
section enter.
More options are to specify additive lists of particles. \whizard\
then expands the final states according to tensor product algebra:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
process multi_tensor = e1, E1 => e2 + e3 + A, E2 + E3 + A
\end{verbatim}
\end{footnotesize}
\end{quote}
This gives the same three process components as above, but \whizard\
recognized that e.g. $e^- e^+ \to \mu^- \gamma$ is a vanishing
process, hence the numbering is different:
\begin{footnotesize}
\begin{Verbatim}
| Process component 'multi_tensor_i2': matrix element vanishes
| Process component 'multi_tensor_i3': matrix element vanishes
| Process component 'multi_tensor_i4': matrix element vanishes
| Process component 'multi_tensor_i6': matrix element vanishes
| Process component 'multi_tensor_i7': matrix element vanishes
| Process component 'multi_tensor_i8': matrix element vanishes
| ------------------------------------------------------------------------
| Process [scattering]: 'multi_tensor'
| Library name = 'default_lib'
| Process index = 1
| Process components:
| 1: 'multi_tensor_i1': e-, e+ => m-, m+ [omega]
| 5: 'multi_tensor_i5': e-, e+ => t-, t+ [omega]
| 9: 'multi_tensor_i9': e-, e+ => A, A [omega]
| ------------------------------------------------------------------------
\end{Verbatim}
\end{footnotesize}
Identical copies of the same process that would be created by
expanding the tensor product of final states are eliminated and appear
only once in the final sum of process components.
Naturally, inclusive process definitions are also available for
decays:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
process multi_dec = Wp => E2 + E3, n2 + n3
\end{Verbatim}
\end{footnotesize}
\end{quote}
This yields:
\begin{footnotesize}
\begin{Verbatim}
| Process component 'multi_dec_i2': matrix element vanishes
| Process component 'multi_dec_i3': matrix element vanishes
| ------------------------------------------------------------------------
| Process [decay]: 'multi_dec'
| Library name = 'default_lib'
| Process index = 2
| Process components:
| 1: 'multi_dec_i1': W+ => mu+, numu [omega]
| 4: 'multi_dec_i4': W+ => tau+, nutau [omega]
| ------------------------------------------------------------------------
\end{Verbatim}
\end{footnotesize}
%%%%%%%%%%%%%%%
\subsection{Compilation}
\label{sec:compilation}
Once processes have been set up, to make them available for integration they
have to be compiled. More precisely, the matrix-element generator
\oMega\ (and it works similarly if a different matrix element method
is chosen) is called to generate matrix element code, the compiler is
called to transform this \fortran\ code into object files, and the
linker is called to collect this in a dynamically loadable library.
Finally, this library is linked to the program. From version v2.2.0 of
\whizard\ this is no longer done by system calls of the OS but steered
via process library Makefiles. Hence, the user can execute and
manipulate those Makefiles in order to manually intervene in the
particular steps, if he/she wants to do so.
All this is done automatically when an \ttt{integrate}, \ttt{unstable}, or
\ttt{simulate} command is encountered for the first time. You may also force
compilation explicitly by the command
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
compile
\end{verbatim}
\end{footnotesize}
\end{quote}
which performs all steps as listed above, including loading the generated
library.
The \fortran\ part of the compilation will be done using the \fortran\ compiler
specified by the string variable
\verb|$fc| and the compiler flags specified as \verb|$fcflags|. The default
settings are those that have been used for compiling \whizard\ itself during
installation. For library compatibility, you should stick to the compiler.
The flags may be set differently. They are applied in the compilation and
loading steps, and they are processed by \ttt{libtool}, so
\ttt{libtool}-specific flags can also be given.
\whizard\ has some precautions against unnecessary repetitions. Hence, when a
\ttt{compile} command is executed (explicitly, or implicitly by the first
integration), the program checks first whether the library is already loaded,
and whether source code already exists for the requested processes. If yes,
this code is used and no calls to \oMega\ (or another matrix element
method) or to the compiler are issued.
Otherwise, it will detect any modification to the process configuration and
regenerate the matrix element or recompile accordingly. Thus, a \sindarin\
script can be executed repeatedly without rebuilding everything from scratch,
and you can safely add more processes to a script in a subsequent run without
having to worry about the processes that have already been treated.
This default behavior can be changed. By setting
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
?rebuild_library = true
\end{verbatim}
\end{footnotesize}
\end{quote}
code will be re-generated and re-compiled even if \whizard\ would think that
this is unncessary. The same effect is achieved by calling \whizard\ with a
command-line switch,
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
/home/user$ whizard --rebuild_library
\end{verbatim}
\end{footnotesize}
\end{quote}
There are further \ttt{rebuild} switches which are described below. If
everything is to be rebuilt, you can set a master switch \ttt{?rebuild} or the
command line option \verb|--rebuild|. The latter can be abbreviated as a short
command-line option:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
/home/user$ whizard -r
\end{verbatim}
\end{footnotesize}
\end{quote}
Setting this switch is always a good idea when starting a new project, just in
case some old files clutter the working directory. When re-running the same
script, possibly modified, the \verb|-r| switch should be omitted, so the
existing files can be reused.
\subsection{Process libraries}
Processes are collected in \emph{libraries}. A script may use more than one
library, although for most applications a single library will probably be
sufficient.
The default library is \ttt{default\_lib}. If you do not specify anything else,
the processes you compile will be collected by a driver file
\ttt{default\_lib.f90} which is compiled together with the process code and
combined as a libtool archive \ttt{default\_lib.la}, which is dynamically linked
to the running \whizard\ process.
Once in a while, you work on several projects at once, and you didn't care
about opening a new working directory for each. If the \verb|-r| option is
given, a new run will erase the existing library, which may contain processes
needed for the other project. You could omit \verb|-r|, so all processes will
be collected in the same library (this does not hurt), but you may wish to
cleanly separate the projects. In that case, you should open a separate
library for each project.
Again, there are two possibilities. You may start the script with the
specification
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
library = "my_lhc_proc"
\end{verbatim}
\end{footnotesize}
\end{quote}
to open a library \verb|my_lhc_proc| in place of the default library.
Repeating the command with different arguments, you may introduce several
libraries in the script. The active library is always the one specified
last. It is possible to issue this command locally, so a particular process
goes into its own library.
Alternatively, you may call \whizard\ with the option
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
/home/user$ whizard --library=my_lhc_proc
\end{verbatim}
\end{footnotesize}
\end{quote}
If several libraries are open simultaneously, the \ttt{compile} command will
compile all libraries that the script has referenced so far. If this is not
intended, you may give the command an argument,
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
compile ("my_lhc_proc", "my_other_proc")
\end{verbatim}
\end{footnotesize}
\end{quote}
to compile only a specific subset.
The command
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
show (library)
\end{verbatim}
\end{footnotesize}
\end{quote}
will display the contents of the actually loaded library together with
a status code which indicates the status of the library and the processes within.
%%%%%%%%%%%%%%%
\subsection{Stand-alone \whizard\ with precompiled processes}
\label{sec:static}
Once you have set up a process library, it is straightforward to make a
special stand-alone \whizard\ executable which will have this library
preloaded on startup. This is a matter of convenience, and it is also useful
if you need a statically linked executable for reasons of profiling,
batch processing, etc.
For this task, there is a variant of the \ttt{compile} command:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
compile as "my_whizard" ()
\end{verbatim}
\end{footnotesize}
\end{quote}
which produces an executable \verb|my_whizard|. You can omit the library
argument if you simply want to include everything. (Note that this command
will \emph{not} load a library into the current process, it is intended for
creating a separate program that will be started independently.)
As an example, the script
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
process proc1 = e1, E1 => e1, E1
process proc2 = e1, E1 => e2, E2
process proc3 = e1, E1 => e3, E3
compile as "whizard-leptons" ()
\end{verbatim}
\end{footnotesize}
\end{quote}
will make a new executable program \verb|whizard-leptons|. This
program behaves completely identical to vanilla \whizard, except for the fact
that the processes \ttt{proc1}, \ttt{proc2}, and \ttt{proc3} are available
without configuring them or loading any library.
% This feature is particularly useful when compiling with the \ttt{-static}
% flag. As long as the architecture is compatible, the resulting binary may be
% run on a different computer where no \whizard\ libraries are present. (The
% program will still need to find its model files, however.)
\section{Beams}
\label{sec:beams}
Before processes can be integrated and simulated, the program has to know
about the collider properties. They can be specified by the \ttt{beams}
statement.
In the command script, it is irrelevant whether a \ttt{beams} statement comes
before or after process specification. The \ttt{integrate} or \ttt{simulate}
commands will use the \ttt{beams} statement that was issued last.
\subsection{Beam setup}
\label{sec:beam-setup}
If the beams have no special properties, and the colliding particles are the
incoming particles in the process themselves, there is no need for a
\ttt{beams} statement at all. You only \emph{must} specify the
center-of-momentum energy of the collider by setting the value of $\sqrt{s}$,
for instance
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
sqrts = 14 TeV
\end{verbatim}
\end{footnotesize}
\end{quote}
The \ttt{beams} statement comes into play if
\begin{itemize}
\item
the beams have nontrivial structure, e.g., parton structure in hadron
collision or photon radiation in lepton collision, or
\item
the beams have non-standard properties: polarization, asymmetry, crossing
angle.
\end{itemize}
Note that some of the abovementioned beam properties had not yet been
reimplemented in the \whizard\ttt{2} release series. From version
v2.2.0 on all options of the legacy series \whizard\ttt{1} are
available again. From version v2.1 to version v2.2 of \whizard\ there
has also been a change in possible options to the \ttt{beams}
statement: in the early versions of \whizard\ttt{2} (v2.0/v2.1), local
options could be specified within the beam settings, e.g. \ttt{beams =
p, p { sqrts = 14 TeV } => pdf\_builtin}. These possibility has been
abandoned from version v2.2 on, and the \ttt{beams} command does not
allow for {\em any} optional arguments any more.
Hence, beam parameters can -- with the exception of the specification
of structure functions -- be specified only globally:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
sqrts = 14 TeV
beams = p, p => lhapdf
\end{verbatim}
\end{footnotesize}
\end{quote}
It does not make any difference whether the value of \ttt{sqrts} is
set before or after the \ttt{beams} statement, the last value found
before an \ttt{integrate} or \ttt{simulate} is the relevant one. This
in particularly allows to specify the beam structure, and then after
that perform a loop or scan over beam energies, beam parameters, or
structure function settings.
The \ttt{beams} statement also applies to particle decay processes, where there
is only a single beam. Here, it is usually redundant because no structure
functions are possible, and the energy is fixed to the decaying particle's
mass. However, it is needed for computing polarized decay, e.g.
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = Z
beams_pol_density = @(0)
\end{verbatim}
\end{footnotesize}
\end{quote}
where for a boson at rest, the polarization axis is defined to be the $z$
axis.
Beam polarization is described in detail below in Sec.~\ref{sec:polarization}.
Note also that future versions of \whizard\ might give support for
single-beam events, where structure functions for single particles
indeed do make sense.
In the following sections we list the available options for structure
functions or spectra inside \whizard\ and explain their usage. More
about the physics of the implemented structure functions can be found
in Chap.~\ref{chap:hardint}.
%%%%%%%%%%%%%%%
\subsection{Asymmetric beams and Crossing angles}
\label{sec:asymmetricbeams}
\whizard\ not only allows symmetric beam collisions, but basically
arbitrary collider setups. In the case there are two different beam
energies, the command
\begin{quote}
\begin{footnotesize}
\ttt{beams\_momentum = {\em <beam\_mom1>}, {\em <beam\_mom2>}}
\end{footnotesize}
\end{quote}
allows to specify the momentum (or as well energies for massless
particles) for the beams. Note that for scattering processes both
values for the beams must be present. So the following to setups for
14 TeV LHC proton-proton collisions are equivalent:
\begin{quote}
\begin{footnotesize}
\ttt{beams = p, p => pdf\_builtin} \newline
\ttt{sqrts = 14 TeV}
\end{footnotesize}
\end{quote}
and
\begin{quote}
\begin{footnotesize}
\ttt{beams = p, p => pdf\_builtin} \newline
\ttt{beams\_momentum = 7 TeV, 7 TeV}
\end{footnotesize}
\end{quote}
Asymmetric setups can be set by using different values for the two
beam momenta, e.g. in a HERA setup:
\begin{quote}
\begin{footnotesize}
\ttt{beams = e, p => none, pdf\_builtin}
\ttt{beams\_momentum = 27.5 GeV, 920 GeV}
\end{footnotesize}
\end{quote}
or for the BELLE experiment at the KEKB accelerator:
\begin{quote}
\begin{footnotesize}
\ttt{beams = e1, E1}
\ttt{beams\_momentum = 8 GeV, 3.5 GeV}
\end{footnotesize}
\end{quote}
\whizard\ lets you know about the beam structure and calculates for
you that the center of mass energy corresponds to 10.58 GeV:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
| Beam structure: e-, e+
| momentum = 8.000000000000E+00, 3.500000000000E+00
| Beam data (collision):
| e- (mass = 5.1099700E-04 GeV)
| e+ (mass = 5.1099700E-04 GeV)
| sqrts = 1.058300530253E+01 GeV
| Beam structure: lab and c.m. frame differ
\end{Verbatim}
\end{footnotesize}
\end{quote}
It is also possible to specify beams for decaying particles, where
\ttt{beams\_momentum} then only has a single argument, e.g.:
\begin{quote}
\begin{footnotesize}
\ttt{process zee = Z => "e-", "e+"} \\
\ttt{beams = Z} \\
\ttt{beams\_momentum = 500 GeV} \\
\ttt{simulate (zee) \{ n\_events = 100 \} }
\end{footnotesize}
\end{quote}
This would correspond to a beam of $Z$ bosons with a momentum of 500
GeV. Note, however, that \whizard\ will always do the integration of
the particle width in the particle's rest frame, while the moving beam
is then only taken into account for the frame of reference for the
simulation.
Further options then simply having different beam energies describe a
non-vanishing between the two incoming beams. Such concepts are quite
common e.g. for linear colliders to improve the beam properties in the
collimation region at the beam interaction points. Such crossing
angles can be specified in the beam setup, too, using the
\ttt{beams\_theta} command:
\begin{quote}
\begin{footnotesize}
\ttt{beams = e1, E1} \\
\ttt{beams\_momentum = 500 GeV, 500 GeV} \\
\ttt{beams\_theta = 0, 10 degree}
\end{footnotesize}
\end{quote}
It is important that when a crossing angle is being specified, and the
collision system consequently never is the center-of-momentum system,
the beam momenta have to explicitly set. Besides a planar crossing
angle, one is even able to rotate an azimuthal distance:
\begin{quote}
\begin{footnotesize}
\ttt{beams = e1, E1} \\
\ttt{beams\_momentum = 500 GeV, 500 GeV} \\
\ttt{beams\_theta = 0, 10 degree} \\
\ttt{beams\_phi = 0, 45 degree}
\end{footnotesize}
\end{quote}
%%%%%%%%%%%%%%%
\subsection{LHAPDF}
\label{sec:lhapdf}
For incoming hadron beams, the \ttt{beams} statement specifies which structure
functions are used. The simplest example is the study of parton-parton
scattering processes at a hadron-hadron collider such as LHC or Tevatron. The
\lhapdf\ structure function set is selected by a syntax similar to the
process setup, namely the example already shown above:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = p, p => lhapdf
\end{verbatim}
\end{footnotesize}
\end{quote}
Note that there are slight differences in using the \lhapdf\ release
series 6 and the older \fortran\ \lhapdf\ release series 5, at least
concerning the naming conventions for the PDF sets~\footnote{Until
\whizard\ version 2.2.1 including, only the \lhapdf\ series 5 was
supported, while from version 2.2.2 on also the \lhapdf\ release
series 6 has been supported.}. The above \ttt{beams}
statement selects a default \lhapdf\ structure-function set for both
proton beams (which is the \ttt{CT10} central set for \lhapdf\ 6, and
\ttt{cteq6ll.LHpdf} central set for \lhapdf 5). The structure
function will apply for all quarks, antiquarks, and the gluon as far
as supported by the particular \lhapdf\ set. Choosing a different set
is done by adding the filename as a local option to the \ttt{lhapdf}
keyword:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = p, p => lhapdf
$lhapdf_file = "MSTW2008lo68cl"
\end{verbatim}
\end{footnotesize}
\end{quote}
for the actual \lhapdf\ 6 series, and
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = p, p => lhapdf
$lhapdf_file = "MSTW2008lo68cl.LHgrid"
\end{verbatim}
\end{footnotesize}
\end{quote}
for \lhapdf 5.Similarly, a member within the set is selected by the
numeric variable \verb|lhapdf_member| (for both release series of \lhapdf).
In some cases, different structure functions have to be chosen for the two
beams. For instance, we may look at $ep$ collisions:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = "e-", p => none, lhapdf
\end{verbatim}
\end{footnotesize}
\end{quote}
Here, there is a list of two independent structure functions (each with its
own option set, if applicable) which applies to the two beams.
Another mixed case is $p\gamma$ collisions, where the photon is to be
resolved as a hadron. The simple assignment
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = p, gamma => lhapdf, lhapdf_photon
\end{verbatim}
\end{footnotesize}
\end{quote}
will be understood as follows: \whizard\ selects the appropriate default
structure functions (here we are using \lhapdf\ 5 as an example as the
support of photon and pion PDFs in \lhapdf\ 6 has been dropped),
\ttt{cteq6ll.LHpdf} for the proton and
\ttt{GSG960.LHgrid} for the photon. The photon case has an additional
integer-valued parameter \verb|lhapdf_photon_scheme|. (There are also pion
structure functions available.) For modifying the default, you have to
specify separate structure functions
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = p, gamma => lhapdf, lhapdf_photon
$lhapdf_file = ...
$lhapdf_photon_file = ...
\end{verbatim}
\end{footnotesize}
\end{quote}
Finally, the scattering of elementary photons on partons is described by
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = p, gamma => lhapdf, none
\end{verbatim}
\end{footnotesize}
\end{quote}
Note that for \lhapdf\ version 5.7.1 or higher and for PDF sets which
support it, photons can be used as partons.
There is one more option for the \lhapdf\ PDFs, namely to specify the
path where the \lhapdf\ PDF sets reside: this is done with the string
variable \ttt{\$lhapdf\_dir = "{\em <path-to-lhapdf>}"}. Usually, it
is not necessary to set this because \whizard\ detects this path via
the \ttt{lhapdf-config} script during configuration, but in the case
paths have been moved, or special files/special locations are to be
used, the user can specify this location explicitly.
%%%%%%%%%%%%%%%
\subsection{Built-in PDFs}
\label{sec:built-in-pdf}
In addition to the possibility of linking against \lhapdf, \whizard\
comes with a couple of built-in PDFs which are selected via the
\verb?pdf_builtin? keyword
%
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = p, p => pdf_builtin
\end{verbatim}
\end{footnotesize}
\end{quote}
%
The default PDF set is CTEQ6L, but other choices are also available by
setting the string variable \verb?$pdf_builtin_set? to an
appropiate value. E.g, modifying the above
setup to
%
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = p, p => pdf_builtin
$pdf_builtin_set = "mrst2004qedp"
\end{verbatim}
\end{footnotesize}
\end{quote}
%
would select the proton PDF from the MRST2004QED set. A list of all currently
available PDFs can be found in Table~\ref{tab:pdfs}.
%
\begin{table}
\centerline{\begin{tabular}{|l||l|p{0.2\textwidth}|l|}
\hline
Tag & Name & Notes & References \\\hline\hline
%
\ttt{cteq6l} & CTEQ6L & \mbox{}\hfill---\hfill\mbox{} &
\cite{Pumplin:2002vw} \\\hline
\ttt{cteq6l1} & CTEQ6L1 & \mbox{}\hfill---\hfill\mbox{} &
\cite{Pumplin:2002vw} \\\hline
\ttt{cteq6d} & CTEQ6D & \mbox{}\hfill---\hfill\mbox{} &
\cite{Pumplin:2002vw} \\\hline
\ttt{cteq6m} & CTEQ6M & \mbox{}\hfill---\hfill\mbox{} &
\cite{Pumplin:2002vw} \\\hline
\hline
\ttt{mrst2004qedp} & MRST2004QED (proton) & includes photon &
\cite{Martin:2004dh} \\\hline
\hline
\ttt{mrst2004qedn} & MRST2004QED (neutron) & includes photon &
\cite{Martin:2004dh} \\\hline
\hline
\ttt{mstw2008lo} & MSTW2008LO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Martin:2009iq} \\\hline
\ttt{mstw2008nlo} & MSTW2008NLO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Martin:2009iq} \\\hline
\ttt{mstw2008nnlo} & MSTW2008NNLO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Martin:2009iq} \\\hline
\hline
\ttt{ct10} & CT10 & \mbox{}\hfill---\hfill\mbox{} &
\cite{Lai:2010vv} \\\hline
\hline
\ttt{CJ12\_max} & CJ12\_max & \mbox{}\hfill---\hfill\mbox{} &
\cite{Owens:2012bv} \\\hline
\ttt{CJ12\_mid} & CJ12\_mid & \mbox{}\hfill---\hfill\mbox{} &
\cite{Owens:2012bv} \\\hline
\ttt{CJ12\_min} & CJ12\_min & \mbox{}\hfill---\hfill\mbox{} &
\cite{Owens:2012bv} \\\hline
\hline
\ttt{CJ15LO} & CJ15LO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Accardi:2016qay} \\\hline
\ttt{CJ15NLO} & CJ15NLO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Accardi:2016qay} \\\hline
\hline
\ttt{mmht2014lo} & MMHT2014LO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Harland-Lang:2014zoa} \\\hline
\ttt{mmht2014nlo} & MMHT2014NLO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Harland-Lang:2014zoa} \\\hline
\ttt{mmht2014nnlo} & MMHT2014NNLO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Harland-Lang:2014zoa} \\\hline
\hline
\ttt{CT14LL} & CT14LLO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Dulat:2015mca} \\\hline
\ttt{CT14L} & CT14LO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Dulat:2015mca} \\\hline
\ttt{CT14N} & CT1414NLO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Dulat:2015mca} \\\hline
\ttt{CT14NN} & CT14NNLO & \mbox{}\hfill---\hfill\mbox{} &
\cite{Dulat:2015mca} \\\hline
\hline
%
\end{tabular}}
\caption{All PDF sets available as builtin sets. The two MRST2004QED
sets also contain a photon.}
\label{tab:pdfs}
\end{table}
The two MRST2004QED sets also contain the photon as a parton, which
can be used in the same way as for \lhapdf\ from v5.7.1 on. Note,
however, that there is no builtin PDF that contains a photon structure
function. There is a \ttt{beams} structure function specifier
\ttt{pdf\_builtin\_photon}, but at the moment this throws an error. It
just has been implemented for the case that in future versions of
\whizard\ a photon structure function might be included.
Note that in general only the data sets for the central values of the
different PDFs ship with \whizard. Using the error sets is possible,
i.e. it is supported in the syntax of the code, but you have to
download the corresponding data sets from the web pages of the PDF
fitting collaborations.
%%%%%%%%%%%%%%%
\subsection{HOPPET $b$ parton matching}
When the \hoppet\ tool~\cite{Salam:2008qg} for hadron-collider PDF
structure functions and their manipulations are
correctly linked to \whizard, it can be used for advanced
calculations and simulations of hadron collider physics. Its main
usage inside \whizard\ is for matching schemes between 4-flavor and
5-flavor schemes in $b$-parton initiated processes at hadron
colliders. Note that in versions 2.2.0 and 2.2.1 it only worked
together with \lhapdf\ version 5, while with the \lhapdf\ version 6
interface from version 2.2.2 on it can be used also with the modern
version of PDFs from \lhapdf. Furthermore, from version 2.2.2, the
\hoppet\ $b$ parton matching also works for the builtin PDFs.
It depends on the corresponding process and the energy scales involved
whether it is a better description to use the
$g\to b\bar b$ splitting from the DGLAP evolution inside the PDF and
just take the $b$ parton content of a PDF, e.g. in BSM Higgs
production for large $\tan\beta$: $pp \to H$ with a partonic
subprocess $b\bar b \to H$, or directly take the gluon PDFs and use
$pp \to b\bar b H$ with a partonic subprocess $gg \to b \bar b
H$. Elaborate schemes for a proper matching between the two
prescriptions have been developed and have been incorporated into the
\hoppet\ interface.
Another prime example for using these matching schemes is single top
production at hadron colliders. Let us consider the following setup:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
process proc1 = b, u => t, d
process proc2 = u, b => t, d
process proc3 = g, u => t, d, B { $restrictions = "2+4 ~ W+" }
process proc4 = u, g => t, d, B { $restrictions = "1+4 ~ W+" }
beams = p,p => pdf_builtin
sqrts = 14 TeV
?hoppet_b_matching = true
$sample = "single_top_matched"
luminosity = 1 / 1 fbarn
simulate (proc1, proc2, proc3, proc4)
\end{Verbatim}
\end{footnotesize}%$
\end{quote}
The first two processes are single top production from $b$ PDFs, the
last two processes contain an explicit $g\to b\bar b$ splitting (the
restriction, cf. Sec.~\ref{sec:process options} has been placed in
order to single out the single top production signal process). PDFs
are then chosen from the default builtin PDF (which is \ttt{CTEQ6L}),
and the \hoppet\ matching routines are switched on by the flag
\ttt{?hoppet\_b\_matching}.
%%%%%%%%%%%%%%%
\subsection{Lepton Collider ISR structure functions}
\label{sec:lepton_isr}
Initial state QED radiation off leptons is an important feature at all
kinds of lepton colliders: the radiative return to the $Z$ resonance
by ISR radiation was in fact the largest higher-order effect for the
SLC and LEP I colliders. The soft-collinear and soft photon radiation
can indeed be resummed/exponentiated to all orders in perturbation
theory~\cite{Gribov:1972rt}, while higher orders in hard-collinear
photons have to be explicitly calculated order by
order~\cite{Kuraev:1985hb,Skrzypek:1990qs}. \whizard\ has an intrinsic
implementation of the lepton ISR structure function that includes all
orders of soft and soft-collinear photons as well as up to the third
order in hard-collinear photons. It can be switched on by the
following statement:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
beams = e1, E1 => isr
\end{Verbatim}
\end{footnotesize}
\end{quote}
As the ISR structure function is a single-beam structure function,
this expression is synonymous for
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
beams = e1, E1 => isr, isr
\end{Verbatim}
\end{footnotesize}
\end{quote}
The ISR structure function can again be applied to only one of the two
beams, e.g. in a HERA-like setup:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
beams = e1, p => isr, pdf_builtin
\end{Verbatim}
\end{footnotesize}
\end{quote}
Their are several options for the lepton-collider ISR structure
function that are summarized in the following:
\vspace{2mm}
\centerline{\begin{tabular}{|l|l|l|}\hline
Parameter & Default & Meaning \\\hline\hline
\ttt{isr\_alpha} & \ttt{0}/intrinsic & value of $\alpha_{QED}$ for ISR
\\\hline
\ttt{isr\_order} & \ttt{3} & max. order of hard-collinear photon
emission \\\hline
\ttt{isr\_mass} & \ttt{0}/intrinsic & mass of the radiating lepton \\\hline
\ttt{isr\_q\_max} & \ttt{0}/$\sqrt{s}$ & upper cutoff for ISR \\\hline
\hline
\ttt{?isr\_recoil} & \ttt{false} & flag to switch on recoil/$p_T$
(\emph{deprecated})\\\hline
\ttt{?isr\_keep\_energy} & \ttt{false} & recoil flag: conserve
energy in splitting (\emph{deprecated})
\\\hline
\end{tabular}}\mbox{}
The maximal order of the hard-collinear photon emission taken into
account by \whizard\ is set by the integer variable \ttt{isr\_order};
the default is the maximally available order of three. With the
variable \ttt{isr\_alpha}, the value of the QED coupling constant
$\alpha_{QED}$ used in the ISR structure function can be set. The
default is taken from the active physics model. The mass of the
radiating lepton (in most cases the electron) is set by
\ttt{isr\_mass}; again the default is taken from the active physics
model. Furthermore, the upper integration border for the ISR structure
function which acts roughly as an upper hardness cutoff for the emitted
photons, can be set through \ttt{isr\_q\_max}; if not set, the
collider energy (possibly after beamstrahlung,
cf. Sec.~\ref{sec:beamstrahlung}) $\sqrt{s}$ (or $\sqrt{\widehat{s}}$)
is taken. Note that \whizard\ accounts for the
exclusive effects of ISR radiation at the moment by a single (hard,
resolved) photon in the event; a more realistic treatment of exclusive
ISR photons in simulation is foreseen for a future version.
While the ISR structure function is evaluated in the collinear limit,
it is possible to generate transverse momentum for both the radiated
photons and the recoiling partonic system. We recommend to stick to
the collinear approximation for the integration step. Integration
cuts should be set up such that they do not significantly depend on
photon transverse momentum. In a subsequent simulation step, it is
possible to transform the events with collinear ISR radiation into
more realistic events with non-collinear radiation. To this end,
\whizard\ provides a separate ISR photon handler which can be
activated in the simulation step. The algorithm operates on the
partonic event: it takes the radiated photons and the partons entering
the hard process, and applies a $p_T$ distribution to those particles
and their interaction products, i.e., all outgoing particles. Cuts
that depend on photon $p_T$ may be applied to the modified events.
For details on the ISR photon handler,
cf.\ Sec.~\ref{sec:isr-photon-handler}.
{\footnotesize The flag \ttt{?isr\_recoil} switches on $p_T$ recoil of
the emitting lepton against photon radiation during integration; per
default it is off. The flag \ttt{?isr\_keep\_energy} controls the
mode of on-shell projection for the splitting process with $p_T$.
Note that this feature is kept for backwards compatibility, but
should not be used for new simulations. The reason is as follows:
For a fraction of events, $p_T$ will become significant, and (i)
energy/momentum non-conservation, applied to both beams separately,
can lead to unexpected and unphysical effects, and (ii) the modified
momenta enter the hard process, so the collinear approximation used
in the ISR structure function computation does not hold. }
%%%%%%%%%%%%%%%
\subsection{Lepton Collider Beamstrahlung}
\label{sec:beamstrahlung}
At linear lepton colliders, the macroscopic electromagnetic
interaction of the bunches leads to a distortion of the spectrum of
the bunches that is important for an exact simulation of the beam
spectrum. There are several methods to account for these effects. The
most important tool to simulate classical beam-beam interactions in
lepton-collider physics is
\ttt{GuineaPig++}~\cite{Schulte:1998au,Schulte:1999tx,Schulte:2007zz}. A
direct interface between this tool \ttt{GuineaPig++} and \whizard\ had
existed as an inofficial add-on to the legacy branch \whizard\ttt{1},
but is no longer applicable in \whizard\ttt{2}. A \whizard-internal
interface is foreseen for the very near future, most probably within
this v2.2 release. Other options are to use parameterizations of the
beam spectrum that have been included in the package \circeone~\cite{CIRCE}
which has been interfaced to \whizard\ since version v1.20 and been
included in the \whizard\ttt{2} release series. Another option is to
generate a beam spectrum externally and then read it in as an ASCII
data file, cf. Sec.~\ref{sec:beamevents}. More about this can be found
in a dedicated section on lepton collider spectra,
Sec.~\ref{sec:beamspectra}.
In this section, we discuss the usage of beamstrahlung spectra by
means of the \circeone\ package. The beamstrahlung spectra are
true spectra, so they have to be applied to pairs of beams, and an
application to only one beam is meaningless. They are switched on by
this \ttt{beams} statement including structure functions:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
beams = e1, E1 => circe1
\end{Verbatim}
\end{footnotesize}
\end{quote}
It is important to note that the parameterization of the beamstrahlung
spectra within \circeone\ contain also processes where $e\to\gamma$
conversions have been taking place, i.e. also hard processes with one
(or two) initial photons can be simulated with beamstrahlung switched
on. In that case, the explicit photon flags, \ttt{?circe1\_photon1}
and \ttt{?circe1\_photon2}, for the two beams have to be properly set,
e.g. (ordering in the final state does not play a role):
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
process proc1 = A, e1 => A, e1
sqrts = 500 GeV
beams = e1, E1 => circe1
?circe1_photon1 = true
integrate (proc1)
process proc2 = e1, A => A, e1
sqrts = 1000 GeV
beams = e1, A => circe1
?circe1_photon2 = true
\end{Verbatim}
\end{footnotesize}
\end{quote}
or
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
process proc1 = A, A => Wp, Wm
sqrts = 200 GeV
beams = e1, E1 => circe1
?circe1_photon1 = true
?circe1_photon2 = true
?circe1_generate = false
\end{Verbatim}
\end{footnotesize}
\end{quote}
In all cases (one or both beams with photon conversion) the beam
spectrum applies to both beams simultaneously.
In the last example ($\gamma\gamma\to W^+W^-$) the default
\circeone\ generator mode was turned off by unsetting
\verb|?circe1_generate|. In the other examples this flag is
set, by default. For standard use cases,
\circeone\ implements a beam-event generator inside the
\whizard\ generator, which provides beam-event samples with correctly
distributed probability. For electrons, the beamstrahlung spectrum
sharply peaks near maximum energy. This distribution is most
efficiently handled by the generator mode. By contrast, in the $\gamma\gamma$
mode, the beam-event c.m.\ energy is concentrated at low values. For
final states with low invariant mass, which are typically produced by
beamstrahlung photons, the generator mode is appropriate.
However, the $W^+W^-$ system requires substantial energy, and such
events will be very rare in the beam-event sample. Switching off the
\circeone\ generator mode solves this
problem.
This is an overview over all options and flags for the \circeone\
setup for lepton collider beamstrahlung:
\vspace{2mm}
\centerline{\begin{tabular}{|l|l|l|}\hline
Parameter & Default & Meaning \\\hline\hline
\ttt{?circe1\_photon1} & \ttt{false} & $e\to\gamma$ conversion for beam 1
\\\hline
\ttt{?circe1\_photon2} & \ttt{false} & $e\to\gamma$ conversion for beam 2
\\\hline
\ttt{circe1\_sqrts} & $\sqrt{s}$ & collider energy for the beam spectrum \\\hline
\ttt{?circe1\_generate} & \ttt{true} & flag for the \circeone\ generator mode \\\hline
\ttt{?circe1\_map} & \ttt{true} & flag to apply special phase-space mapping
\\\hline
\ttt{circe1\_mapping\_slope} & \ttt{2.} & value of PS mapping exponent
\\\hline
\ttt{circe1\_eps} & \ttt{1E-5} & parameter for mapping of spectrum peak
position \\\hline
\ttt{circe1\_ver} & \ttt{0} & internal version of \circeone\ package
\\\hline
\ttt{circe1\_rev} & \ttt{0}/most recent & internal revision of
\circeone\ \\\hline
\ttt{\$circe1\_acc} & \ttt{SBAND} & accelerator type \\\hline
\ttt{circe1\_chat} & \ttt{0} & chattiness/verbosity of \circeone \\\hline
\end{tabular}}\mbox{}
The collider energy relevant for the beamstrahlung spectrum is set by
\ttt{circe1\_sqrts}. As a default, this is always the value of
\ttt{sqrts} set in the \sindarin\ script. However, sometimes these
values do not match, e.g. the user wants to simulate $t\bar t h$ at
\ttt{sqrts = 550 GeV}, but the only available beam spectrum is for 500
GeV. In that case, \ttt{circe1\_sqrts = 500 GeV} has to be set to use
the closest possible available beam spectrum.
As mentioned in the discussion of the examples above, in
\circeone\ there are two options to use the beam spectra for
beamstrahlung: intrinsic semi-analytic approximation formulae for the
spectra, or a Monte-Carlo sampling of the sampling. The second
possibility always give a better description of the spectra, and is
the default for \whizard. It can, however, be switched off by setting
the flag \ttt{?circe1\_generate} to \ttt{false}.
As the beamstrahlung spectra are sharply peaked at the collider
energy, but still having long tails, a mapping of the spectra for an
efficient phase-space sampling is almost mandatory. This is the
default in \whizard, which can be changed by the flag
\ttt{?circe1\_map}. Also, the default exponent for the mapping can be
changed from its default value \ttt{2.} with the variable
\ttt{circe1\_mapping\_slope}. It is important to efficiently sample
the peak position of the spectrum; the effective ratio of the peak to
the whole sampling interval can be set by the parameter
\ttt{circe1\_eps}. The integer parameter \ttt{circe1\_chat} sets the
chattiness or verbosity of the \circeone\ package, i.e. how many
messages and warnings from the beamstrahlung generation/sampling will
be issued.
The actual internal version and revision of the \circeone\ package are
set by the two integer parameters \ttt{circe1\_ver} and
\ttt{circe1\_rev}. The default is in any case always the newest
version and revision, while older versions are still kept for
backwards compatibility and regression testing.
Finally, the geometry and design of the accelerator type is set with
the string variable \ttt{\$circe1\_acc}: it contains the possible
options for the old \ttt{"SBAND"} and \ttt{"XBAND"} setups, as well as
the \ttt{"TESLA"} and JLC/NLC SLAC design \ttt{"JLCNLC"}. The setups
for the most important energies of the ILC as they are summarized in
the ILC
TDR~\cite{Behnke:2013xla,Baer:2013cma,Adolphsen:2013jya,Adolphsen:2013kya}
are available as \ttt{ILC}. Beam spectra for the
CLIC~\cite{Aicheler:2012bya,Lebrun:2012hj,Linssen:2012hp} linear
collider are much more demanding to correctly simulate (due to the
drive beam concept; only the low-energy modes where the drive beam is
off can be simulated with the same setup as the abovementioned
machines). Their setup will be supported soon in one of the upcoming
\whizard\ versions within the \circetwo\ package.
An example of how to generate beamstrahlung spectra with the help of
the package \circetwo\ (that is also a part of \whizard) is this:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
process eemm = e1, E1 => e2, E2
sqrts = 500 GeV
beams = e1, E1 => circe2
$circe2_file = "ilc500.circe"
$circe2_design = "ILC"
?circe_polarized = false
\end{Verbatim}
\end{footnotesize}%$
\end{quote}
Here, the ILC design is used for a beamstrahlung spectrum at 500 GeV
nominal energy, with polarization averaged (hence, the setting of
polarization to \ttt{false}). A list of all available options can be
found in Sec.~\ref{sec:photoncoll}.
More technical details about the simulation of beamstrahlung spectra
see the documented source code of the \circeone\ package, as well as
Chap.~\ref{chap:hardint}. In the next section, we discuss how to read
in beam spectra from external files.
%%%%%%%%%%%%%%%
\subsection{Beam events}
\label{sec:beamevents}
As mentioned in the previous section, beamstrahlung is one of the
crucial ingredients for a realistic simulation of linear lepton
colliders. One option is to take a pre-generated beam spectrum for
such a machine, and make it available for simulation within \whizard\
as an external ASCII data file. Such files basically contain only
pairs of energy fractions of the nominal collider energy $\sqrt{s}$
($x$ values). In \whizard\ they can be used in simulation with the
following \ttt{beams} statement:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
beams = e1, E1 => beam_events
$beam_events_file = "<beam_spectrum_file>"
\end{Verbatim}
\end{footnotesize}%$
\end{quote}
Note that beam spectra must always be pair spectra, i.e. they are
automatically applied to both beam simultaneously.
Beam spectra via external files are expected to reside in the current
working directory. Alternatively, \whizard\ searches for them in the
install directory of \whizard\ in \ttt{share/beam-sim}. There you can
find an example file, \ttt{uniform\_spread\_2.5\%.dat} for such a beam
spectrum. The only possible parameter that can be set is the flag
\ttt{?beam\_events\_warn\_eof} whose default is \ttt{true}. This
triggers the issuing of a warning when the end of file of an external
beam spectrum file is reached. In such a case, \whizard\ starts to
reuse the same file again from the beginning. If the available data
points in the beam events file are not big enough, this could result
in an insufficient sampling of the beam spectrum.
%%%%%%%%%%%%%%%
\subsection{Gaussian beam-energy spread}
\label{sec:gaussian}
Real beams have a small energy spread. If beamstrahlung is small, the spread
may be approximately described as Gaussian. As a replacement for the full
simulation that underlies \ttt{CIRCE2} spectra, it is possible to
impose a Gaussian distributed beam energy, separately for each beam.
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
beams = e1, E1 => gaussian
gaussian_spread1 = 0.1\%
gaussian_spread2 = 0.2\%
\end{Verbatim}
\end{footnotesize}%$
\end{quote}
(Note that the \% sign means multiplication by 0.01, as it should.) The
spread values are defined as the $\sigma$ value of the Gaussian distribution,
i.e., $2/3$ of the events are within $\pm 1\sigma$ for each beam,
respectively.
%%%%%%%%%%%%%%%%
\subsection{Equivalent photon approximation}
\label{sec:epa}
The equivalent photon approximation (EPA) uses an on-shell approximation for
the $e \to e\gamma$ collinear splitting to allow the simulation of
photon-induced backgrounds in lepton collider physics. The original
concept is that of the Weizs\"acker-Williams
approximation~\cite{vonWeizsacker:1934sx,Williams:1934ad,Budnev:1974de}. This
is a single-beam structure function that can be applied to both beams,
or also to one beam only. Usually, there are some simplifications
being made in the derivation. The formula which is implemented here
and seems to be the best for the QCD background for low-$p_T$ hadrons,
corresponds to Eq.~(6.17) of Ref.~\cite{Budnev:1974de}. As this
reference already found, this leads to an "overshooting" of accuracy,
and especially in the high-$x$ (high-energy) region to wrong
results. This formula corresponds to
\begin{equation}
\label{eq:budnev_617}
f(x) = \frac{\alpha}{\pi} \frac{1}{x} \biggl[ \left( \bar{x} +
\frac{x^2}{2} \right) \log
\frac{Q^2_{\text{max}}}{Q^2_{\text{min}}}
- \left( 1 - \frac{x}{2} \right)^2
\log \frac{x^2 + \tfrac{Q^2_{\text{max}}}{E^2}}{x^2 +
\tfrac{Q^2_{\text{min}}}{E^2}}
- \frac{m_e^2 x^2}{Q^2_{\text{min}}} \left( 1 -
\frac{Q^2_{\text{min}}}{Q^2_{\text{max}}} \right) \biggr] \qquad .
\end{equation}
Here, $x$ is the ratio of the photon energy (called frequency $\omega$
in~\cite{Budnev:1974de} over the original electron (or positron) beam
energy $E$. The energy of the electron (or positron) after the
splitting is given by $\bar{x} = 1-x$.
The simplified version is the one that corresponds to many
publications about the EPA during SLC and LEP times, and corresponds
to the $q^2$ integration of Eq.~(6.16e) in~\cite{Budnev:1974de}, where
$q^2$ is the virtuality or momentum transfer of the photon in the EPA:
\begin{equation}
\label{eq:budnev_616e}
f(x) = \frac{\alpha}{\pi} \frac{1}{x} \biggl[ \left( \bar{x} +
\frac{x^2}{2} \right) \log
\frac{Q^2_{\text{max}}}{Q^2_{\text{min}}}
- \frac{m_e^2 x^2}{Q^2_{\text{min}}} \left( 1 -
\frac{Q^2_{\text{min}}}{Q^2_{\text{max}}} \right) \biggr] \qquad .
\end{equation}
While Eq.~(\ref{eq:budnev_617}) is supposed to be the better choice
for simulating hadronic background like low-$p_T$ hadrons and should
be applied for the low-$x$ region of the EPA,
Eq.~(\ref{eq:budnev_616e}) seems better suited for high-$x$
simulations like the photoproduction of BSM resonances etc.
Note that the first term in Eqs.~(\ref{eq:budnev_617}) and
(\ref{eq:budnev_616e}) is the standard Altarelli-Parisi QED splitting
function of electron, $P_{e\to e\gamma}(x) \propto 1 + (1-x)^2$, while
the last term in both equations is the default power correction.
The two parameters $Q^2_{\text{max}}$ and $Q^2_{\text{min}}$ are the
integration boundaries of the photon virtuality integration. Usually,
they are given by the kinematic limits:
\begin{equation}
Q^2_{\text{min}} = \frac{m_e^2 x^2}{\bar{x}} \qquad\qquad
Q^2_{\text{max}} = 4 E^2 \bar{x} = s \bar{x} \qquad .
\end{equation}
For low-$p_T$ hadron simulations, it is not a good idea to take the
kinematic limit as an upper limit, but one should cut the simulation
off at a hadronic scale like e.g. a multiple of the $\rho$ mass.
The user can switch between the two different options using the setting
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
$epa_mode = "default"
\end{Verbatim}
\end{footnotesize}
\end{quote}
or
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
$epa_mode = "Budnev_617"
\end{Verbatim}
\end{footnotesize}
\end{quote}
for Eq.~(\ref{eq:budnev_617}), while Eq.~(\ref{eq:budnev_616e}) can be
chosen with
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
$epa_mode = "Budnev_616e"
\end{Verbatim}
\end{footnotesize}
\end{quote}
Note that a thorough study for high-energy $e^+e^-$ colliders
regarding the suitability of different EPA options is still lacking.
For testing purposes also three more variants or simplifications of
Eq.~(\ref{eq:budnev_616e}) are implemented: the first, steered by
\ttt{\$epa\_mode = log\_power} uses simply $Q^2_{\text{max}} =
s$. This is also the case for the two other method. But the switch
\ttt{\$epa\_mode = log\_simple} uses just \ttt{epa\_mass} (cf. below)
as $Q^2_{\text{min}}$. The final simplification is to drop the power
correction, which can be chosen with \ttt{\$epa\_mode = log}. This
corresponds to the simple formula:
\begin{equation}
f(x) = \frac{\alpha}{2\pi} \frac{1}{x} \, \log\frac{s}{m^2}
\qquad .
\end{equation}
Examples for the application of the EPA in \whizard\ are:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
beams = e1, E1 => epa
\end{Verbatim}
\end{footnotesize}
\end{quote}
or for a single beam:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
beams = e1, p => epa, pdf_builtin
\end{Verbatim}
\end{footnotesize}
\end{quote}
The last process allows the reaction of (quasi-) on-shell photons with
protons.
In the following, we collect the parameters and flags that can be
adjusted when using the EPA inside \whizard:
\vspace{2mm}
\centerline{\begin{tabular}{|l|l|l|}\hline
Parameter & Default & Meaning \\\hline\hline
\ttt{epa\_alpha} & \ttt{0}/intrinsic & value of $\alpha_{QED}$ for EPA
\\\hline
\ttt{epa\_x\_min} & \ttt{0.} & soft photon cutoff in $x$ (mandatory)
\\\hline
\ttt{epa\_q\_min} & \ttt{0.} & minimal $\gamma$ momentum transfer \\\hline
\ttt{epa\_mass} & \ttt{0}/intrinsic & mass of the radiating fermion (mandatory) \\\hline
\ttt{epa\_q\_max} & \ttt{0}/$\sqrt{s}$ & upper cutoff for EPA \\\hline
\ttt{?epa\_recoil} & \ttt{false} & flag to switch on recoil/$p_T$
\\\hline
\ttt{?epa\_keep\_energy} & \ttt{false} & recoil flag to conserve
energy in splitting
\\\hline
\end{tabular}}\mbox{}
The adjustable parameters are partially similar to the parameters in
the QED initial-state radiation (ISR), cf. Sec.~\ref{sec:lepton_isr}:
the parameter \ttt{epa\_alpha} sets the value of the electromagnetic
coupling constant, $\alpha_{QED}$ used in the EPA structure
function. If not set, this is taken from the value inside the active
physics model. The same is true for the mass of the particle that
radiates the photon of the hard interaction, which can be reset by the
user with the variable \ttt{epa\_mass}. There are two dimensionful
scale parameters, the minimal momentum transfer to the photon,
\ttt{epa\_q\_min}, which must not be zero, and the upper momentum-transfer
cutoff
for the EPA structure function, \ttt{epa\_q\_max}. The default for the
latter value is the collider energy, $\sqrt{s}$, or the energy reduced
by another structure function like e.g. beamstrahlung,
$\sqrt{\hat{s}}$. Furthermore, there is a soft-photon regulator for
the splitting function in $x$ space, \ttt{epa\_x\_min}, which also has
to be explicitly set different from zero. Hence, a minimal viable
scenario that will be accepted by \whizard\ looks like this:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
beams = e1, E1 => epa
epa_q_min = 5 GeV
epa_x_min = 0.01
\end{Verbatim}
\end{footnotesize}
\end{quote}
Finally, like the ISR case in Sec.~\ref{sec:lepton_isr}, there is a
flag to consider the recoil of the photon against the radiating
electron by setting \ttt{?epa\_recoil} to \ttt{true} (default:
\ttt{false}).
Though in principle processes like $e^+ e^- \to e^+ e^- \gamma \gamma$
where the two photons have been created almost collinearly and then
initiate a hard process could be described by exact matrix elements
and exact kinematics. However, the numerical stability in the very far
collinear kinematics is rather challenging, such that the use of the
EPA is very often an acceptable trade-off between quality of the
description on the one hand and numerical stability and speed on the
other hand.
In the case, the EPA is set after a second structure function like a
hadron collider PDF, there is a flavor summation over the quark
constituents inside the proton, which are then the radiating fermions
for the EPA. Here, the masses of all fermions have to be identical.
More about the physics of the equivalent photon approximation can be
found in Chap.~\ref{chap:hardint}.
%%%%%%%%%%%%%%%
\subsection{Effective $W$ approximation}
\label{sec:ewa}
An approach similar to the equivalent photon approximation (EPA)
discussed in the previous section Sec.~\ref{sec:epa}, is the usage
of a collinear splitting function for the radiation of massive
electroweak vector bosons $W$/$Z$, the effective $W$ approximation
(EWA). It has been developed for the
description of high-energy weak vector-boson fusion and scattering
processes at hadron colliders, particularly the Superconducting
Super-Collider (SSC). This was at a time when the simulation of $2\to
4$ processes war still very challenging and $2\to 6$ processes almost
impossible, such that this approximation was the only viable solution
for the simulation of processes like $pp \to jjVV$ and subsequent
decays of the bosons $V \equiv W, Z$.
Unlike the EPA, the EWA is much more involved as the structure
functions do depend on the isospin of the radiating fermions, and are
also different for transversal and longitudinal polarizations. Also, a
truely collinear kinematics is never possible due to the finite $W$
and $Z$ boson masses, which start becoming more and more negligible
for energies larger than the nominal LHC energy of 14 TeV.
Though in principle all processes for which the EWA might be
applicable are technically feasible in \whizard\ to be generated also
via full matrix elements, the EWA has been implemented in \whizard\
for testing purposes, backwards compatibility and comparison with
older simulations. Like the EPA, it is a single-beam structure
function that can be applied to one or both beams. We only give an
example for both beams here, this is for a 3 TeV CLIC collider:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
sqrts = 3 TeV
beams = e1, E1 => ewa
\end{Verbatim}
\end{footnotesize}
\end{quote}
And this is for LHC or a higher-energy follow-up collider (which also
shows the concatenation of the single-beam structure functions,
applied to both beams consecutively,
cf. Sec.~\ref{sec:concatenation}:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
sqrts = 14 TeV
beams = p, p => pdf_builtin => ewa
\end{Verbatim}
\end{footnotesize}
\end{quote}
Again, we list all the options, parameters and flags that can be
adapted for the EWA:
\vspace{2mm}
\centerline{\begin{tabular}{|l|l|l|}\hline
Parameter & Default & Meaning \\\hline\hline
\ttt{ewa\_x\_min} & \ttt{0.} & soft $W$/$Z$ cutoff in $x$ (mandatory)
\\\hline
\ttt{ewa\_mass} & \ttt{0}/intrinsic & mass of the radiating fermion \\\hline
\ttt{ewa\_pt\_max} & \ttt{0}/$\sqrt{\hat{s}}$ & upper cutoff for EWA \\\hline
\ttt{?ewa\_recoil} & \ttt{false} & recoil switch
\\\hline
\ttt{?ewa\_keep\_energy} & \ttt{false} & energy conservation for
recoil in splitting
\\\hline
\end{tabular}}\mbox{}
First of all, all coupling constants are taken from the active physics
model as they have to be consistent with electroweak gauge
invariance. Like for EPA, there is a soft $x$ cutoff for the $f \to f
V$ splitting, \ttt{ewa\_x\_min}, that has to be set different from
zero by the user. Again, the mass of the radiating fermion can be set
explicitly by the user; and, also again, the masses for the flavor sum
of quarks after a PDF as radiators of the electroweak bosons have to
be identical. Also for the EWA, there is an upper cutoff for the $p_T$
of the electroweak boson, that can be set via
\ttt{eta\_pt\_max}. Indeed, the transversal $W$/$Z$ structure function
is logarithmically divergent in that variable. If it is not set by the
user, it is estimated from $\sqrt{s}$ and the splitting kinematics.
For the EWA, there is a flag to switch on a recoil for the
electroweak boson against the radiating fermion,
\ttt{?ewa\_recoil}. Note that this is an experimental feature that is
not completely tested. In any case, the non-collinear kinematics
violates 4-four momentum conservation, so there are two choices:
either to conserve the energy (\ttt{?ewa\_keep\_energy = true}) or to
conserve 3-momentum (\ttt{?ewa\_keep\_energy = false}). Momentum
conservation for the kinematics is the default. This is due to the
fact that for energy conservation, there will be a net total momentum
in the event including the beam remnants (ISR/EPA/EWA radiated
particles) that leeds to unexpected or unphysical features in the
energy distributions of the beam remnants recoiling against the rest
of the event.
More details about the physics can be found in
Chap.~\ref{chap:hardint}.
%%%%%%%%%%%%%%%
\subsection{Energy scans using structure functions}
In \whizard, there is an implementation of a pair spectrum,
\ttt{energy\_scan}, that allows to scan the energy dependence of a
cross section without actually scanning over the collider
energies. Instead, only a single integration at the upper end of the
scan interval over the process with an additional pair spectrum
structure function performed. The structure function is chosen
in such a way, that the distribution of $x$ values of the energy scan
pair spectrum translates in a plot over the energy of the final state
in an energy scan from \ttt{0} to \ttt{sqrts} for the process under
consideration.
The simplest example is the $1/s$ fall-off with the $Z$ resonance in
$e^+e^- \to \mu^+ \mu^-$, where the syntax is very easy:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
process eemm = e1, E1 => e2, E2
sqrts = 500 GeV
cuts = sqrts_hat > 50
beams = e1, E1 => energy_scan
integrate (eemm)
\end{Verbatim}
\end{footnotesize}
\end{quote}
The value of \ttt{sqrts = 500 GeV} gives the upper limit for the scan,
while the cut effectively let the scan start at 50 GeV. There are no
adjustable parameters for this structure function. How to plot the
invariant mass distribution of the final-state muon pair to show the
energy scan over the cross section, will be explained in
Sec.~\ref{sec:analysis}.
More details can be found in Chap.~\ref{chap:hardint}.
%%%%%%%%%%%%%%%
\subsection{Photon collider spectra}
\label{sec:photoncoll}
One option that has been discussed as an alternative possibility for a
high-energy linear lepton collider is to convert the electron and
positron beam via Compton backscattering off intense laser beams into
photon
beams~\cite{Ginzburg:1981vm,Telnov:1989sd,Telnov:1995hc}. Naturally,
due to the production
of the photon beams and the inherent electron spectrum, the photon
beams have a characteristic spectrum. The simulation of such spectra
is possible within \whizard\ by means of the subpackage \circetwo,
which have been mentioned already in Sec.~\ref{sec:beamstrahlung}. It
allows to give a much more elaborate description of a linear lepton
collider environment than
\circeone\ (which, however, is not in all cases necessary, as the ILC
beamspectra for electron/positrons can be perfectly well described
with \circeone).
Here is a typical photon collider setup where we take a
photon-initiated process:
\begin{quote}
\begin{footnotesize}
\begin{Verbatim}
process aaww = A, A => Wp, Wm
beams = A, A => circe2
$circe2_file = "teslagg_500_polavg.circe"
$circe2_design = "TESLA/GG"
?circe2_polarized = false
\end{Verbatim}
\end{footnotesize}%$
\end{quote}
Here, the photons are the initial states initiating the hard
scattering. The structure function is \ttt{circe2} which always is a
pair spectrum. The list of available options are:
\vspace{2mm}
\centerline{\begin{tabular}{|l|l|l|}\hline
Parameter & Default & Meaning \\\hline\hline
\ttt{?circe2\_polarized} & \ttt{true} & spectrum respects polarization info
\\\hline
\ttt{\$circe2\_file} & -- & name of beam spectrum data file
\\\hline
\ttt{\$circe2\_design} & \ttt{"*"} & collider design
\\\hline
\end{tabular}}\mbox{}
The only logical flag \ttt{?circe2\_polarized} let \whizard\ know
whether it should keep polarization information in the beam spectra or
average over polarizations. Naturally, because of the Compton
backscattering generation of the photons, photon spectra are always
polarized. The collider design can be specified by the string variable
\ttt{\$circe2\_design}, where the default setting \ttt{"*"}
corresponds to the default of \circetwo\ (which is the TESLA 500 GeV
machine as discussed in the TESLA Technical Design
Report~\cite{AguilarSaavedra:2001rg,Richard:2001qm}). Note that up to
now there have not been any setups for a photon collider option for
the modern linear collider concepts like ILC and CLIC. The string
variable \ttt{\$circe2\_file} then allows to give the name of the file
containing the actual beam spectrum; all files that ship with
\whizard\ are stored in the directory \ttt{circe2/share/data}.
More details about the subpackage \circetwo\ and the physics it
covers, can be found in its own manual and the chapter
Chap.~\ref{chap:hardint}.
%%%%%%%%%%%%%%%
\subsection{Concatenation of several structure functions}
\label{sec:concatenation}
As has been shown already in Sec.~\ref{sec:epa} and
Sec.~\ref{sec:ewa}, it is possible within \whizard\ to concatenate
more than one structure function, irrespective of the fact, whether
the structure functions are single-beam structure functions or pair
spectra. One important thing is whether there is a phase-space mapping
for these structure functions. Also, there are some combinations which
do not make sense from the physics point of view, for example using
lepton-collider ISR for protons, and then afterwards switching on
PDFs. Such combinations will be vetoed by \whizard, and you will find
an error message like (cf. also Sec.~\ref{sec:errors}):
\begin{interaction}
******************************************************************************
******************************************************************************
*** FATAL ERROR: Beam structure: [....] not supported
******************************************************************************
******************************************************************************
\end{interaction}
Common examples for the concatenation of structure functions are
linear collider applications, where beamstrahlung (macroscopic
electromagnetic beam-beam interactions) and electron QED initial-state
radiation are both switched on:
\begin{code}
beams = e1, E1 => circe1 => isr
\end{code}
Another possibility is the simulation of photon-induced backgrounds at
ILC or CLIC, using beamstrahlung and equivalent photon approximation
(EPA):
\begin{code}
beams = e1, E1 => circe1 => epa
\end{code}
or with beam events from a data file:
\begin{code}
beams = e1, E1 => beam_events => isr
\end{code}
In hadron collider physics, parton distribution functions (PDFs) are
basically always switched on, while afterwards the user could specify
to use the effective $W$ approximation (EWA) to simulate high-energy
vector boson scattering:
\begin{code}
sqrts = 100 TeV
beams = p, p => pdf_builtin => ewa
\end{code}
Note that this last case involves a flavor sum over the five active
quark (and anti-quark) species $u$, $d$, $c$, $s$, $b$ in the proton,
all of which act as radiators for the electroweak vector bosons in the
EWA.
This would be an example with three structure functions:
\begin{code}
beams = e1, E1 => circe1 => isr => epa
\end{code}
%%%%%%%%%%%%%%%
\section{Polarization}
\label{sec:polarization}
%%%%%
\subsection{Initial state polarization}
\label{sec:initialpolarization}
\whizard\ supports polarizing the inital state fully or partially by
assigning a nontrivial density matrix in helicity space.
Initial state polarization requires a beam setup and is initialized by
means of the \ttt{beams\_pol\_density} statement\footnote{Note that
the syntax for the specification of beam polarization has changed
from version v2.1 to v2.2 and is incompatible between the two
release series. The old syntax \ttt{beam\_polarization} with its
different polarization constructors has been discarded in favor of a
unified syntax.}:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams_pol_density = @([<spin entries>]), @([<spin entries>])
\end{verbatim}
\end{footnotesize}
\end{quote}
The command \ttt{beams\_pol\_fraction} gives the degree of
polarization of the two beams:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams_pol_fraction = <degree beam 1>, <degree beam 2>
\end{verbatim}
\end{footnotesize}
\end{quote}
Both commands in the form written above apply to scattering processes,
where the polarization of both beams must be specified. The
\ttt{beams\_pol\_density} and \ttt{beams\_pol\_fraction} are possible
with a single beam declaration if a decay process is considered, but
only then.
While the syntax for the command \ttt{beams\_pol\_fraction} is pretty
obvious, the syntax for the actual specification of the beam
polarization is more intricate. We start with the polarization
fraction: for each beam there is a real number between zero
(unpolarized) and one (complete polarization) that can be specified
either as a floating point number like \ttt{0.4} or with a percentage:
\ttt{40 \%}. Note that the actual arithmetics is sometimes
counterintuitive: 80 \% left-handed electron polarization means that
80 \% of the electron beam are polarized, 20 \% are unpolarized,
i.e. 20 \% have half left- and half right-handed polarization
each. Hence, 90 \% of the electron beam is left-handed, 10 \% is
right-handed.
How does the specification of the polarization work? If there are no
entries at all in the polarization constructor, \ttt{@()}, the beam is
unpolarized, and the spin density matrix is proportional to the
unit/identity matrix. Placing entries into the \ttt{@()} constructor
follows the concept of sparse matrices, i.e. the entries that have
been specified will be present, while the rest remains zero. Single
numbers do specify entries for that particular helicity on the main
diagonal of the spin density matrix, e.g. for an electron \ttt{@(-1)}
means (100\%) left-handed polarization. Different entries are
separated by commas: \ttt{@(1,-1)} sets the two diagonal entries at
positions $(1,1)$ and $(-1,-1)$ in the density matrix both equal to
one. Two remarks are in order
already here. First, note that you do not have to worry about the
correct normalization of the spin density matrix, \whizard\ is taking
care of this automatically. Second, in the screen output for the beam
data, only those entries of the spin density matrix that have been
specified by the user, will be displayed. If a
\ttt{beams\_pol\_fraction} statement appears, other components will be
non-zero, but might not be shown. E.g. ILC-like, 80 \% polarization of
the electrons, 30 \% positron polarization will be specified like this
for left-handed electrons and right-handed positrons:
\begin{code}
beams = e1, E1
beams_pol_density = @(-1), @(+1)
beams_pol_fraction = 80%, 30%
\end{code}
The screen output will be like this:
\begin{code}
| ------------------------------------------------------------------------
| Beam structure: e-, e+
| polarization (beam 1):
| @(-1: -1: ( 1.000000000000E+00, 0.000000000000E+00))
| polarization (beam 2):
| @(+1: +1: ( 1.000000000000E+00, 0.000000000000E+00))
| polarization degree = 0.8000000, 0.3000000
| Beam data (collision):
| e- (mass = 0.0000000E+00 GeV) polarized
| e+ (mass = 0.0000000E+00 GeV) polarized
\end{code}
But because of the fraction of unpolarized electrons and positrons,
the spin density matrices for electrons and positrons are:
\[
\rho(e^-) = \diag \left ( 0.10, 0.90 \right) \qquad
\rho(e^+) = \diag \left ( 0.65, 0.35 \right) \quad ,
\]
respectively. So, in general, only the entries due to the polarized
fraction will be displayed on screen. We will come back to more
examples below.
Again, the setting of a single entry, e.g. \ttt{@($\pm m$)}, which
always sets the diagonal component $(\pm m, \pm m)$ of the spin
density matrix equal to one. Here $m$ can have the following values
for the different spins (in parentheses are entries that exist only
for massive particles):
\vspace{1mm}
\begin{center}
\begin{tabular}{|l|l|l|}\hline
Spin $j$ & Particle type & possible $m$ values \\\hline
0 & Scalar boson & 0 \\
1/2 & Spinor & +1, -1 \\
1 & (Massive) Vector boson & +1, (0), -1 \\
3/2 & (Massive) Vectorspinor & +2, (+1), (-1), -2 \\
2 & (Massive) Tensor & +2, (+1), (0), (-1), -2
\\\hline
\end{tabular}
\end{center}
\vspace{1mm}
Off-diagonal entries that are equal to one (up to the normalization)
of the spin-density matrix can be specified simply by the position,
namely: \ttt{@($m$:$m'$, $m''$)}. This would result in a spin density
matrix with diagonal entry $1$ for the position $(m'', m'')$, and an entry
of $1$ for the off-diagonal position $(m,m')$.
Furthermore, entries in the density matrix different from $1$ with a
numerical value \ttt{{\em <val>}} can be
specified, separated by another colon: \ttt{@($m$:$m'$:{\em
<val>})}. Here, it does not matter whether $m$ and $m'$ are different
or not. For $m = m'$ also diagonal spin density matrix entries
different from one can be specified. Note that because spin density
matrices have to be Hermitian, only the entry $(m,m')$ has to be set,
while the complex conjugate entry at the transposed position $(m',m)$
is set automatically by \whizard.
We will give some general density
matrices now, and after that a few more definite examples. In the
general setups below, we always give the expression for the spin
density matrix only for one single beam.
%
{
\newcommand{\cssparse}[4]{%
\begin{pmatrix}
#1 & 0 & \cdots & \cdots & #3 \\
0 & 0 & \ddots & & 0 \\
\vdots & \ddots & \ddots & \ddots & \vdots \\
0 & & \ddots & 0 & 0 \\
#4 & \cdots & \cdots & 0 & #2
\end{pmatrix}%
}
%
\begin{itemize}
\item {\bf Unpolarized:}
\begin{center}
\begin{footnotesize}
\ttt{beams\_pol\_density = @()}
\end{footnotesize}
\end{center}
% \newline
This has the same effect as not specifying any
polarization at all and is the only constructor available for scalars and
fermions declared as left- or right-handed (like the neutrino). Density matrix:
\[ \rho = \frac{1}{|m|}\mathbb{I} \]
($|m|$: particle multiplicity which is 2 for massless, $2j + 1$ for massive particles).
%
\item {\bf Circular polarization:}
\begin{center}
\begin{footnotesize}
\ttt{beams\_pol\_density = @($\pm j$) \qquad beams\_pol\_fraction
= $f$}
\end{footnotesize}
\end{center}
A fraction $f$ (parameter range $f \in \left[0\;;\;1\right]$) of
the particles are in the maximum / minimum helicity eigenstate $\pm
j$, the remainder is unpolarized. For spin $\frac{1}{2}$ and massless
particles of spin $>0$, only the maximal / minimal entries of the
density matrix are populated, and the density matrix looks like this:
\[ \rho = \diag\left(\frac{1\pm f}{2}\;,\;0\;,\;\dots\;,\;0\;,
\frac{1\mp f}{2}\right) \]
%
\item {\bf Longitudinal polarization (massive):}
\begin{center}
\begin{footnotesize}
\ttt{beams\_pol\_density = @(0) \qquad beams\_pol\_fraction = $f$}
\end{footnotesize}
\end{center}
We consider massive particles with maximal spin component $j$, a
fraction $f$ of which having longitudinal polarization, the remainder
is unpolarized. Longitudinal polarization is (obviously) only
available for massive bosons of spin $>0$. Again, the parameter range
for the fraction is: $f \in \left[0\;;\;1\right]$. The density matrix
has the form:
\[ \rho = \diag\left(\frac{1-f}{|m|}\;,\;\dots\;,\;\frac{1-f}{|m|}\;,\;
\frac{1+f \left(|m| - 1\right)}{|m|}\;,\;\frac{1-f}{|m|}\;,
\;\dots\;,\;\frac{1-f}{|m|}\right)
\]
($|m| = 2j+1 $: particle multiplicity)
%
\item {\bf Transverse polarization (along an axis):}
\begin{center}
\begin{footnotesize}
\ttt{beams\_pol\_density = @(j, -j, j:-j:exp(-I*phi)) \qquad
beams\_pol\_fraction = $f$}
\end{footnotesize}
\end{center}
This so called transverse polarization is a polarization along an
arbitrary direction in the $x-y$ plane, with $\phi=0$ being the positive
$x$ direction and $\phi=90^\circ$ the positive $y$ direction. Note that
the value of \ttt{phi} has either to be set inside the beam
polarization expression explicitly or by a statement \ttt{real phi =
{\em val} degree} before. A fraction $f$ of the particles are
polarized, the remainder is unpolarized. Note that, although
this yields a valid density matrix for all particles with multiplicity
$>1$ (in which the only the highest and lowest helicity states are
populated), it is meaningful only for spin $\frac{1}{2}$ particles and
massless bosons of spin $>0$. The range of the parameters are:
$f \in \left[0\;;\;1\right]$ and $\phi \in \mathbb{R}$. This yields a
density matrix:
\[ \rho =
\cssparse{1}{1}
{\frac{f}{2}\,e^{-i\phi}} {\frac{f}{2}\,e^{i\phi}} \]
(for antiparticles, the matrix is conjugated).
%
\item {\bf Polarization along arbitrary axis $\left(\theta, \phi\right)$:}
\begin{center}
\begin{footnotesize}
\ttt{beams\_pol\_density = @(j:j:1-cos(theta),
j:-j:sin(theta)*exp(-I*phi), -j:-j:1+cos(theta))} \qquad\quad\qquad
\ttt{beams\_pol\_fraction = $f$}
\end{footnotesize}
\end{center}
This example describes polarization along an arbitrary axis in polar
coordinates (polar axis in positive $z$ direction, polar angle
$\theta$, azimuthal angle $\phi$). A fraction $f$ of the particles are
polarized, the remainder is unpolarized. Note that, although axis
polarization defines a valid density matrix for all particles with
multiplicity $>1$, it is meaningful only for particles with spin
$\frac{1}{2}$. Valid ranges for the parameters are $f \in
\left[0\;;\;1\right]$, $\theta \in \mathbb{R}$, $\phi \in
\mathbb{R}$. The density matrix then has the form:
\[ \rho = \frac{1}{2}\cdot
\cssparse{1 - f\cos\theta}{1 + f\cos\theta}
{f\sin\theta\, e^{-i\phi}}{f\sin\theta\, e^{i\phi}}
\]
%
\item {\bf Diagonal density matrix:}
\begin{center}
\begin{footnotesize}
\ttt{beams\_pol\_density = @(j:j:$h_j$, j-1:j-1:$h_{j-1}$,
$\ldots$, -j:-j:$h_{-j}$)}
\end{footnotesize}
\end{center}
This defines an arbitrary diagonal density matrix with entries
$\rho_{j,j}\,,\,\dots\,,\,\rho_{-j,-j}$.
%
\item {\bf Arbitrary density matrix:}
\begin{center}
\begin{footnotesize}
\ttt{beams\_pol\_density = @($\{m:m':x_{m,m'}\}$)}:
\end{footnotesize}
\end{center}
Here, \ttt{$\{m:m':x_{m,m'}\}$} denotes a selection of entries at
various positions somewhere in the spin density matrix. \whizard\
will check whether this is a valid spin density matrix, but it does
e.g. not have to correspond to a pure state.
%
\end{itemize}
}
%
The beam polarization statements can be used both globally directly
with the \ttt{beams} specification, or locally inside the
\ttt{integrate} or \ttt{simulate} command. Some more specific examples
are in order to show how initial state polarization works:
%
\begin{itemize}
\item
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = A, A
beams_pol_density = @(+1), @(1, -1, 1:-1:-I)
\end{verbatim}
\end{footnotesize}
\end{quote}
This declares the initial state to be composed of two incoming
photons, where the first photon is right-handed, and the second photon
has transverse polarization in $y$ direction.
%
\item
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = A, A
beams_pol_density = @(+1), @(1, -1, 1:-1:-1)
\end{verbatim}
\end{footnotesize}
\end{quote}
Same as before, but this time the second photon has transverse
polarization in $x$ direction.
%
\item
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = "W+"
beams_pol\_density = @(0)
\end{verbatim}
\end{footnotesize}
\end{quote}
This example sets up the decay of a longitudinal vector boson.
%
\item
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
beams = E1, e1
scan int hel_ep = (-1, 1) {
scan int hel_em = (-1, 1) {
beams_pol_density = @(hel_ep), @(hel_em)
integrate (eeww)
}
}
integrate (eeww)
\end{verbatim}
\end{footnotesize}
\end{quote}
This example loops over the different positron and electron helicity
combinations and calculates the respective integrals. The
\ttt{beams\_pol\_density} statement is local to the scan loop(s) and,
therefore, the last \ttt{integrate} calculates the unpolarized
integral.
\end{itemize}
%
Although beam polarization should be straightforward to use, some pitfalls exist
for the unwary:
\begin{itemize}
\item Once \ttt{beams\_pol\_density} is set globally, it persists and
is applied every time \ttt{beams} is executed (unless it is reset). In
particular, this means that code like
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
process wwaa = Wp, Wm => A, A
process zee = Z => e1, E1
sqrts = 200 GeV
beams_pol_density = @(1, -1, 1:-1:-1), @()
beams = Wp, Wm
integrate (wwaa)
beams = Z
integrate (zee)
beams_pol_density = @(0)
\end{verbatim}
\end{footnotesize}
\end{quote}
will throw an error, because \whizard\ complains that the spin density
matrix has the wrong dimensionality for the second (the decay) process.
This kind of trap can be avoided be using \ttt{beams\_pol\_density}
only locally in \ttt{integrate} or \ttt{simulate} statements.
%
\item On-the-fly integrations executed by \ttt{simulate}
use the beam
setup found at the point of execution. This implies that any polarization
settings you have previously done affect the result of the integration.
%
\item The \ttt{unstable} command also requires integrals of the selected decay
processes, and will compute them on-the-fly if they are unavailable. Here,
a polarized integral is not meaningful at all. Therefore, this command
ignores the current \ttt{beam} setting and issues a warning if a previous
polarized integral is available; this will be discarded.
\end{itemize}
\subsection{Final state polarization}
Final state polarization is available in \whizard\ in the sense that the
polarization of real final state particles can be retained when generating
simulated
events. In order for the polarization of a particle to be retained, it must be
declared as polarized via the \ttt{polarized} statement
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
polarized particle [, particle, ...]
\end{verbatim}
\end{footnotesize}
\end{quote}
The effect of \ttt{polarized} can be reversed with the \ttt{unpolarized}
statement which has the same syntax. For example,
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
polarized "W+", "W-", Z
\end{verbatim}
\end{footnotesize}
\end{quote}
will cause the polarization of all final state $W$ and $Z$ bosons to be
retained, while
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
unpolarized "W+", "W-", Z
\end{verbatim}
\end{footnotesize}
\end{quote}
will reverse the effect and cause the polarization to be summed over again. Note
that \ttt{polarized} and \ttt{unpolarized} are global statements which cannot be
used locally as command arguments and if you use them e.g. in a loop, the
effects will persist beyond the loop body. Also, a particle cannot be
\ttt{polarized} and \ttt{unstable} at the same time (this restriction
might be loosened in future versions of \whizard).
After toggling the polarization flag, the generation of polarized events can be
requested by using the \ttt{?polarized\_events} option of the \ttt{simulate}
command, e.g.
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
simulate (eeww) { ?polarized_events = true }
\end{verbatim}
\end{footnotesize}
\end{quote}
When \ttt{simulate} is run in this mode, helicity information for final state
particles that have been toggled as \ttt{polarized} is written to the event
file(s) (provided that polarization is supported by the selected event file
format(s) ) and can also be accessed in the analysis by means of the \ttt{Hel}
observable. For example, an analysis definition like
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
analysis =
if (all Hel == -1 ["W+"] and all Hel == -1 ["W-"] ) then
record cta_nn (eval cos (Theta) ["W+"]) endif;
if (all Hel == -1 ["W+"] and all Hel == 0 ["W-"] )
then record cta_nl (eval cos (Theta) ["W+"]) endif
\end{verbatim}
\end{footnotesize}
\end{quote}
can be used to histogram the angular distribution for the production of
polarized $W$ pairs (obviously, the example would have to be extended
to cover all possible helicity combinations). Note, however, that
helicity information is not available in the integration step;
therefore, it is not possible to use \ttt{Hel} as a cut observable.
While final state polarization is straightforward to use, there is a caveat when
used in combination with flavor products. If a particle in a flavor product is
defined as \ttt{polarized}, then all particles ``originating'' from the product will
act as if they had been declared as \ttt{polarized} --- their polarization will
be recorded in the generated events. E.g., the example
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
process test = u:d, ubar:dbar => d:u, dbar:ubar, u, ubar
! insert compilation, cuts and integration here
polarized d, dbar
simulate (test) {?polarized_events = true}
\end{verbatim}
\end{footnotesize}
\end{quote}
will generate events including helicity information for all final state $d$ and
$\overline{d}$ quarks, but only for part of the final state $u$ and $\overline{u}$
quarks. In this case, if you had wanted to keep the helicity information also
for all $u$ and $\overline{u}$, you would have had to explicitely include them
into the \ttt{polarized} statement.
\section{Cross sections}
Integrating matrix elements over phase space is the core of \whizard's
activities. For any process where we want the cross section, distributions,
or event samples, the cross section has to be determined first. This is done
by a doubly adaptive multi-channel Monte-Carlo integration. The integration,
in turn, requires a \emph{phase-space setup}, i.e., a collection of
phase-space \emph{channels}, which are mappings of the unit hypercube onto the
complete space of multi-particle kinematics. This phase-space information is
encoded in the file \emph{xxx}\ttt{.phs}, where \emph{xxx} is the process tag.
\whizard\ generates the phase-space file on the fly and can reuse it in later
integrations.
For each phase-space channel, the unit hypercube is binned in each dimension.
The bin boundaries are allowed to move during a sequence of iterations, each
with a fixed number of sampled phase-space points, so they adapt to the actual
phase-space density as far as possible. In addition to this \emph{intrinsic}
adaptation, the relative channel weights are also allowed to vary.
All these steps are done automatically when the \ttt{integrate} command is
executed. At the end of the iterative adaptation procedure, the program has
obtained an estimate for the integral of the matrix element over phase space,
together with an error estimate, and a set of integration \emph{grids} which
contains all information on channel weights and bin boundaries. This
information is stored in a file \emph{xxx}\ttt{.vg}, where \emph{xxx} is the
process tag, and is used for event generation by the \ttt{simulate}
command.
\subsection{Integration}
\label{sec:integrate}
Since everything can be handled automatically using default parameters, it
often suffices to write the command
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
integrate (proc1)
\end{verbatim}
\end{footnotesize}
\end{quote}
for integrating the process with name tag \ttt{proc1}, and similarly
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
integrate (proc1, proc2, proc3)
\end{verbatim}
\end{footnotesize}
\end{quote}
for integrating several processes consecutively. Options to the integrate
command are specified, if not globally, by a local option string
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
integrate (proc1, proc2, proc3) { mH = 200 GeV }
\end{verbatim}
\end{footnotesize}
\end{quote}
(It is possible to place a \ttt{beams} statement inside the option string, if
desired.)
If the process is configured but not compiled, compilation will be done
automatically. If it is not available at all, integration will fail.
The integration method can be specified by the string variable
\begin{quote}
\begin{footnotesize}
\ttt{\$integration\_method = "{\em <method>}"}
\end{footnotesize}
\end{quote} %$
The default method is called \ttt{"vamp"} and uses the \vamp\
algorithm and code. (At the moment, there is only a single simplistic
alternative, using the midpoint rule or rectangle method for
integration, \ttt{"midpoint"}. This is mainly for testing purposes. In
future versions of \whizard, more methods like e.g. Gauss integration
will be made available). \vamp, however, is clearly the main
integration method. It is done in several \emph{passes} (usually two),
and each pass consists of several \emph{iterations}. An iteration
consists of a definite number of \emph{calls} to the matrix-element
function.
For each iteration, \whizard\ computes an estimate of the integral and an
estimate of the error, based on the binned sums of matrix element values and
squares. It also computes an estimate of the rejection efficiency for
generating unweighted events, i.e., the ratio of the average sampling function
value over the maximum value of this function.
After each iteration, both the integration grids (the binnings) and the
relative weights of the integration channels can be adapted to
minimize the variance estimate of the integral. After each pass of several
iterations, \whizard\ computes an average of the iterations within the pass,
the corresponding error estimate, and a $\chi^2$ value. The integral, error,
efficiency and $\chi^2$ value computed for the most recent integration pass,
together with the most recent integration grid, are used for any subsequent
calculation that involves this process, in particular for event generation.
In the default setup, during the first pass(es) both grid binnings and channel
weights are adapted. In the final (usually second) pass, only binnings are
further adapted. Roughly speaking, the final pass is the actual calculation,
while the previous pass(es) are used for ``warming up'' the integration grids,
without using the numerical results. Below, in the section about the
specification of the iterations, Sec.~\ref{sec:iterations}, we will
explain how it is possible to change the behavior of adapting grids
and weights.
Here is an example of the integration output, which illustrates these
properties. The \sindarin\ script describes the process $e^+e^-\to q\bar q
q\bar q$ with $q$ being any light quark, i.e., $W^+W^-$ and $ZZ$ production
and hadronic decay together will any irreducible background. We cut on $p_T$
and energy of jets, and on the invariant mass of jet pairs. Here is the
script:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
alias q = d:u:s:c
alias Q = D:U:S:C
process proc_4f = e1, E1 => q, Q, q, Q
ms = 0 mc = 0
sqrts = 500 GeV
cuts = all (Pt > 10 GeV and E > 10 GeV) [q:Q]
and all M > 10 GeV [q:Q, q:Q]
integrate (proc_4f)
\end{verbatim}
\end{footnotesize}
\end{quote}
After the run is finished, the integration output looks like
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
| Process library 'default_lib': loading
| Process library 'default_lib': ... success.
| Integrate: compilation done
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 12511
| Initializing integration for process proc_4f:
| ------------------------------------------------------------------------
| Process [scattering]: 'proc_4f'
| Library name = 'default_lib'
| Process index = 1
| Process components:
| 1: 'proc_4f_i1': e-, e+ => d:u:s:c, dbar:ubar:sbar:cbar,
| d:u:s:c, dbar:ubar:sbar:cbar [omega]
| ------------------------------------------------------------------------
| Beam structure: [any particles]
| Beam data (collision):
| e- (mass = 5.1099700E-04 GeV)
| e+ (mass = 5.1099700E-04 GeV)
| sqrts = 5.000000000000E+02 GeV
| Phase space: generating configuration ...
| Phase space: ... success.
| Phase space: writing configuration file 'proc_4f_i1.phs'
| Phase space: 123 channels, 8 dimensions
| Phase space: found 123 channels, collected in 15 groves.
| Phase space: Using 195 equivalences between channels.
| Phase space: wood
| Applying user-defined cuts.
| OpenMP: Using 8 threads
| Starting integration for process 'proc_4f'
| Integrate: iterations not specified, using default
| Integrate: iterations = 10:10000:"gw", 5:20000:""
| Integrator: 15 chains, 123 channels, 8 dimensions
| Integrator: Using VAMP channel equivalences
| Integrator: 10000 initial calls, 20 bins, stratified = T
| Integrator: VAMP
|=============================================================================|
| It Calls Integral[fb] Error[fb] Err[%] Acc Eff[%] Chi2 N[It] |
|=============================================================================|
1 9963 2.3797857E+03 3.37E+02 14.15 14.13* 4.02
2 9887 2.8307603E+03 9.58E+01 3.39 3.37* 4.31
3 9815 3.0132091E+03 5.10E+01 1.69 1.68* 8.37
4 9754 2.9314937E+03 3.64E+01 1.24 1.23* 10.65
5 9704 2.9088284E+03 3.40E+01 1.17 1.15* 12.99
6 9639 2.9725788E+03 3.53E+01 1.19 1.17 15.34
7 9583 2.9812484E+03 3.10E+01 1.04 1.02* 17.97
8 9521 2.9295139E+03 2.88E+01 0.98 0.96* 22.27
9 9435 2.9749262E+03 2.94E+01 0.99 0.96 20.25
10 9376 2.9563369E+03 3.01E+01 1.02 0.99 21.10
|-----------------------------------------------------------------------------|
10 96677 2.9525019E+03 1.16E+01 0.39 1.22 21.10 1.15 10
|-----------------------------------------------------------------------------|
11 19945 2.9599072E+03 2.13E+01 0.72 1.02 15.03
12 19945 2.9367733E+03 1.99E+01 0.68 0.96* 12.68
13 19945 2.9487747E+03 2.03E+01 0.69 0.97 11.63
14 19945 2.9777794E+03 2.03E+01 0.68 0.96* 11.19
15 19945 2.9246612E+03 1.95E+01 0.67 0.94* 10.34
|-----------------------------------------------------------------------------|
15 99725 2.9488622E+03 9.04E+00 0.31 0.97 10.34 1.05 5
|=============================================================================|
| Time estimate for generating 10000 events: 0d:00h:00m:51s
| Creating integration history display proc_4f-history.ps and proc_4f-history.pdf
\end{verbatim}
\end{footnotesize}
\end{quote}
Each row shows the index of a single iteration, the number of matrix element
calls for that iteration, and the integral and error estimate. Note
that the number of calls displayed are the real calls to the matrix
elements after all cuts and possible rejections. The error
should be viewed as the $1\sigma$ uncertainty, computed on a statistical
\begin{figure}
\centering
\includegraphics[width=.56\textwidth]{proc_4f-history}
\caption{\label{fig:inthistory} Graphical output of the convergence
of the adaptation during the integration of a \whizard\ process.}
\end{figure}
basis. The next two columns display the error in percent, and the
\emph{accuracy} which is the same error normalized by $\sqrt{n_{\rm calls}}$.
The accuracy value has the property that it is independent of $n_{\rm calls}$,
it describes the quality of adaptation of the current grids. Good-quality
grids have a number of order one, the smaller the better. The next column is
the estimate for the rejection efficiency in percent. Here, the value should
be as high as possible, with $100\,\%$ being the possible maximum.
In the example, the grids are adapted over ten iterations, after which the
accuracy and efficiency have saturated at about $1.0$ and $10\,\%$,
respectively. The asterisk in the accuracy column marks those iterations
where an improvement over the previous iteration is seen. The average over
these iterations exhibits an accuracy of $1.22$, corresponding to $0.39\,\%$
error, and a $\chi^2$ value of $1.15$, which is just right:
apparently, the phase-space for this process and set of cuts is
well-behaved. The subsequent five iterations are used for obtaining
the final integral, which has an accuracy below one (error $0.3\,\%$),
while the efficiency settles at about
$10\,\%$. In this example, the final $\chi^2$ value happens to be quite
small, i.e., the individual results are closer together than the error
estimates would suggest. One should nevertheless not scale down the error,
but rather scale it up if the $\chi^2$ result happens to be much larger than
unity: this often indicates sub-optimally adapted grids, which insufficiently
map some corner of phase space.
One should note that all values are subject to statistical fluctuations, since
the number of calls within each iterations is finite. Typically, fluctuations
in the efficiency estimate are considerably larger than fluctuations in the
error/accuracy estimate. Two subsequent runs of the same script should yield
statistically independent results which may differ in all quantities, within
the error estimates, since the seed of the random-number generator will differ
by default.
It is possible to get exactly reproducible results by setting the
random-number seed explicitly, e.g.,
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
seed = 12345
\end{verbatim}
\end{footnotesize}
\end{quote}
at any point in the \sindarin\ script. \ttt{seed} is a predefined intrinsic
variable. The value can be any 32bit integer. Two runs with different seeds
can be safely taken as statistically independent. In the example
above, no seed has been set, and the seed has therefore been
determined internally by \whizard\ from the system clock.
The concluding line with the time estimate applies to a subsequent simulation
step with unweighted events, which is not actually requested in the current
example. It is based on the timing and efficiency estimate of the most recent
iteration.
As a default, a graphical output of the integration history will be
produced (if both \LaTeX\ and \metapost\ have been available during
configuration). Fig.~\ref{fig:inthistory} shows how this looks like,
and demonstrates how a proper convergence of the integral during the
adaptation looks like. The generation of these graphical history files
can be switched off using the command \ttt{?vis\_history = false}.
%%%%%
\subsection{Integration run IDs}
A single \sindarin\ script may contain multiple calls to the
\ttt{integrate} command with different parameters. By default,
files generated for the same process in a subsequent integration will
overwrite the previous ones. This is undesirable when the script is
re-run: all results that have been overwritten have to be recreated.
To avoid this, the user may identify a specific run by a string-valued
ID, e.g.
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
integrate (foo) { $run_id = "first" }
\end{verbatim}
\end{footnotesize}
\end{quote}
This ID will become part of the file name for all files that are
created specifically for this run. Often it is useful to create a run
ID from a numerical value using \ttt{sprintf}, e.g., in this scan:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
scan real mh = (100 => 200 /+ 10) {
$run_id = sprintf "%e" (mh)
integrate (h_production)
}
\end{verbatim}
\end{footnotesize}
\end{quote}
With unique run IDs, a subsequent run of the same \sindarin\ script
will be able to reuse all previous results, even if there is more than
a single integration per process.
\subsection{Controlling iterations}
\label{sec:iterations}
\whizard\ has some predefined numbers of iterations and calls for the first
and second integration pass, respectively, which depend on the number of
initial and final-state particles. They are guesses for values that yield
good-quality grids and error values in standard situations, where no
exceptionally strong peaks or loose cuts are present in the integrand.
Actually, the large number of warmup iterations in the previous example
indicates some safety margin in that respect.
It is possible, and often advisable, to adjust the iteration and call numbers
to the particular situation. One may reduce the default numbers to short-cut
the integration, if either less accuracy is needed, or CPU time is to be
saved. Otherwise, if convergence is bad, the number of iterations or calls
might be increased.
To set iterations manually, there is the \ttt{iterations} command:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
iterations = 5:50000, 3:100000
\end{verbatim}
\end{footnotesize}
\end{quote}
This is a comma-separated list. Each pair of values corresponds to an
integration pass. The value before the colon is the number of iterations for
this pass, the other number is the number of calls per iteration.
While the default number of passes is two (one for warmup, one for the final
result), you may specify a single pass
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
iterations = 5:100000
\end{verbatim}
\end{footnotesize}
\end{quote}
where the relative channel weights will \emph{not} be adjusted (because this
is the final pass). This is appropriate for well-behaved integrands where
weight adaptation is not necessary.
You can also define more than two passes. That might be useful when reusing a
previous grid file with insufficient quality: specify the previous passes
as-is, so the previous results will be read in, and then a new pass for
further adaptation.
In the final pass, the default behavior is to not adapt grids and
weights anymore. Otherwise, different iterations would be correlated,
and a final reliable error estimate would not be possible. For all but
the final passes, the user can decide whether to adapt grids and
weights by attaching a string specifier to the number of iterations:
\ttt{"g"} does adapt grids, but not weights, \ttt{"w"} the other way
round. \ttt{"gw"} or \ttt{"wg"} does adapt both. By the setting
\ttt{""}, all adaptations are switched off. An example looks like
this:
\begin{code}
iterations = 2:10000:"gw", 3:5000
\end{code}
Since it is often not known beforehand how many iterations the grid
adaptation will need, it is generally a good idea to give the first
pass a large number of iterations. However, in many cases these turn
out to be not necessary. To shortcut iterations, you can set any of
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
accuracy_goal
error_goal
relative_error_goal
\end{verbatim}
\end{footnotesize}
\end{quote}
to a positive value. If this is done, \whizard\ will skip warmup
iterations once all of the specified goals are reached by the current
iteration. The final iterations (without weight adaptation) are
always performed.
\subsection{Phase space}
Before \ttt{integrate} can start its work, it must have a phase-space
configuration for the process at hand. The method for the phase-space
parameterization is determined by the string variable
\ttt{\$phs\_method}. At the moment there are only two options,
\ttt{"single"}, for testing purposes, that is mainly used internally,
and \whizard's traditional method, \ttt{"wood"}. This parameterization
is particularly adapted and fine-tuned for electroweak processes and
might not be the ideal for for pure jet cross sections. In future
versions of \whizard, more options for phase-space parameterizations
will be made available, e.g. the \ttt{RAMBO} algorithm and its massive
cousin, and phase-space parameterizations that take care of the
dipole-like emission structure in collinear QCD (or QED) splittings.
For the standard method, the phase-space parameterization is laid out
in an ASCII file \ttt{\textit{<process-name>\_}i\textit{<comp>}.phs}.
Here, \ttt{{\em <process-name>}} is the process name chosen by the
user while \ttt{{\em <comp>}} is the number of the process component
of the corresponding process. This immediately shows that different
components of processes are getting different phase space setups. This
is necessary for inclusive processes, e.g. the sum of $pp \to Z + nj$
and $pp \to W + nj$, or in future versions of \whizard\ for NLO
processes, where one component is the interference between the virtual
and the Born matrix element, and another one is the subtraction terms.
Normally, you do not have to deal with this file, since \whizard\ will
generate one automatically if it does not find one. (\whizard\ is
careful to check for consistency of process definition and parameters
before using an existing file.)
Experts might find it useful to generate a phase-space file and inspect and/or
modify it before proceeding further. To this end, there is the parameter
\verb|?phs_only|. If you set this \ttt{true}, \whizard\ skips the actual
integration after the phase-space file has been generated. There is also a
parameter \verb|?vis_channels| which can be set independently; if this is
\ttt{true}, \whizard\ will generate a graphical visualization of the
phase-space parameterizations encoded in the phase-space file. This
file has to be taken with a grain of salt because phase space channels
are represented by sample Feynman diagrams for the corresponding
channel. This does however {\em not} mean that in the matrix element
other Feynman diagrams are missing (the default matrix element method,
\oMega, is not using Feynman-diagrammatic amplitudes at all).
Things might go wrong with the default phase-space generation, or manual
intervention might be necessary to improve later performance. There are a few
parameters that control the algorithm of phase-space generation. To
understand their meaning, you should realize that phase-space
parameterizations are modeled after (dominant) Feynman graphs for the current
process.
\subsubsection{The main phase space setup {\em wood}}
For the main phase-space parameterization of \whizard, which is called
\ttt{"wood"}, there are many different parameters and flags that allow
to tune and customize the phase-space setup for every certain process:
The parameter \verb|phs_off_shell| controls the number of off-shell lines in
those graphs, not counting $s$-channel resonances and logarithmically enhanced
$s$- and $t$-channel lines. The default value is $2$. Setting it to zero
will drop everything that is not resonant or logarithmically enhanced.
Increasing it will include more subdominant graphs. (\whizard\ increases the
value automatically if the default value does not work.)
There is a similar parameter \verb|phs_t_channel| which controls
multiperipheral graphs in the parameterizations. The default value is $6$, so
graphs with up to $6$ $t/u$-channel lines are considered. In particular
cases, such as $e^+e^-\to n\gamma$, all graphs are multiperipheral, and for
$n>7$ \whizard\ would find no parameterizations in the default setup.
Increasing the value of \verb|phs_t_channel| solves this problem. (This is
presently not done automatically.)
There are two numerical parameters that describe whether particles are treated
like massless particles in particular situations. The value of
\verb|phs_threshold_s| has the default value $50\;\GeV$. Hence, $W$ and $Z$
are considered massive, while $b$ quarks are considered massless. This
categorization is used for deciding whether radiation of $b$ quarks can lead
to (nearly) singular behavior, i.e., logarithmic enhancement, in the infrared
and collinear regions. If yes, logarithmic mappings are applied to phase
space. Analogously, \verb|phs_threshold_t| decides about potential
$t$-channel singularities. Here, the default value is $100\;\GeV$, so
amplitudes with $W$ and $Z$ in the $t$-channel are considered as
logarithmically enhanced. For a high-energy hadron collider of 40 or
100 TeV energy, also $W$ and $Z$ in $s$-channel like situations might
be necessary to be considered massless.
Such logarithmic mappings need a dimensionful scale as parameter. There are
three such scales, all with default value $10\;\GeV$: \verb|phs_e_scale|
(energy), \verb|phs_m_scale| (invariant mass), and \verb|phs_q_scale|
(momentum transfer). If cuts and/or masses are such that energies, invariant
masses of particle pairs, and momentum transfer values below $10\;\GeV$ are
excluded or suppressed, the values can be kept. In special cases they should
be changed: for instance, if you want to describe $\gamma^*\to\mu^+\mu^-$
splitting well down to the muon mass, no cuts, you may set
\verb|phs_m_scale = mmu|. The convergence of the Monte-Carlo integration
result will be considerably faster.
There are more flags. These and more details about the phase space
parameterization will be described in Sec.~\ref{sec:wood}.
\subsection{Cuts}
\whizard~2 does not apply default cuts to the integrand. Therefore, processes
with massless particles in the initial, intermediate, or final states may not
have a finite cross section. This fact will manifest itself in an integration
that does not converge, or is unstable, or does not yield a reasonable error
or reweighting efficiency even for very large numbers of iterations or calls
per iterations. When doing any calculation, you should verify first that the
result that you are going to compute is finite on physical grounds. If not,
you have to apply cuts that make it finite.
A set of cuts is defined by the \ttt{cuts} statement. Here is an example
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
cuts = all Pt > 20 GeV [colored]
\end{verbatim}
\end{footnotesize}
\end{quote}
This implies that events are kept only (for integration and simulation) if the
transverse momenta of all colored particles are above $20\;\GeV$.
Technically, \ttt{cuts} is a special object, which is unique within a given
scope, and is defined by the logical expression on the right-hand side of the
assignment. It may be defined in global scope, so it is applied to all
subsequent processes. It may be redefined by another \ttt{cuts} statement.
This overrides the first cuts setting: the \ttt{cuts} statement is not
cumulative. Multiple cuts should be specified by the logical operators of
\sindarin, for instance
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
cuts = all Pt > 20 GeV [colored]
and all E > 5 GeV [photon]
\end{verbatim}
\end{footnotesize}
\end{quote}
Cuts may also be defined local to an \ttt{integrate} command, i.e., in the
options in braces. They will apply only to the processes being integrated,
overriding any global cuts.
The right-hand side expression in the \ttt{cuts} statement is evaluated at the
point where it is used by an \ttt{integrate} command (which could be an
implicit one called by \ttt{simulate}). Hence, if the logical expression
contains parameters, such as
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
mH = 120 GeV
cuts = all M > mH [b, bbar]
mH = 150 GeV
integrate (myproc)
\end{verbatim}
\end{footnotesize}
\end{quote}
the Higgs mass value that is inserted is the value in place when
\ttt{integrate} is evaluated, $150\;\GeV$ in this example. This same value
will also be used when the process is called by a subsequent \ttt{simulate};
it is \ttt{integrate} which compiles the cut expression and stores it among
the process data. This behavior allows for scanning over parameters without
redefining the cuts every time.
The cut expression can make use of all variables and constructs that are
defined at the point where it is evaluated. In particular, it can make use of
the particle content and kinematics of the hard process, as in the example
above. In addition to the predefined variables and those defined by the user,
there are the following variables which depend on the hard process:
\begin{quote}
\begin{tabular}{ll}
integer: & \ttt{n\_in}, \ttt{n\_out}, \ttt{n\_tot} \\
real: & \ttt{sqrts}, \ttt{sqrts\_hat}
\end{tabular}
\end{quote}
Example:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
cuts = sqrts_hat > 150 GeV
\end{verbatim}
\end{footnotesize}
\end{quote}
The constants \ttt{n\_in} etc.\ are sometimes useful if a generic set of cuts
is defined, which applies to various processes simultaneously.
The user is encouraged to define his/her own set of cuts, if possible in a
process-independent manner, even if it is not required. The \ttt{include}
command allows for storing a set of cuts in a separate \sindarin\ script which
may be read in anywhere. As an example, the system directories contain a file
\verb|default_cuts.sin| which may be invoked by
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
include ("default_cuts.sin")
\end{verbatim}
\end{footnotesize}
\end{quote}
\subsection{QCD scale and coupling}
\whizard\ treats all physical parameters of a model, the coefficients in the
Lagrangian, as constants. As a leading-order program, \whizard\ does not make
use of running parameters as they are described by renormalization theory.
For electroweak interactions where the perturbative expansion is sufficiently
well behaved, this is a consistent approach.
As far as QCD is concerned, this approach does not yield numerically
reliable results, even on the validity scale of the tree approximation.
In \whizard\ttt{2}, it is therefore possible to replace the fixed value of
$\alpha_s$ (which is accessible as the intrinsic model variable
\verb|alphas|), by a function of an energy scale $\mu$.
This is controlled by the parameter \verb|?alphas_is_fixed|, which is
\ttt{true} by default. Setting it to \ttt{false} enables running~$\alpha_s$.
The user has then to decide how $\alpha_s$ is calculated.
One option is to set \verb|?alphas_from_lhapdf| (default \ttt{false}). This
is recommended if the \lhapdf\ library is used for including structure
functions, but it may also be set if \lhapdf\ is not invoked. \whizard\ will
then use the $\alpha_s$ formula and value that matches the active
\lhapdf\ structure function set and member.
In the very same way, the $\alpha_s$ running from the PDFs implemented
intrinsically in \whizard\ can be taken by setting
\verb|?alphas_from_pdf_builtin| to \ttt{true}. This is the same
running then the one from \lhapdf, if the intrinsic PDF coincides with
a PDF chosen from \lhapdf.
If this is not appropriate, there are again two possibilities. If
\verb|?alphas_from_mz| is \ttt{true}, the user input value \verb|alphas| is
interpreted as the running value $\alpha_s(m_Z)$, and for the particular
event, the coupling is evolved to the appropriate scale $\mu$. The formula is
controlled by the further parameters \verb|alphas_order| (default $0$,
meaning leading-log; maximum $2$) and \verb|alphas_nf| (default $5$).
Otherwise there is the option to set \verb|?alphas_from_lambda_qcd = true|
in order to evaluate $\alpha_s$ from the scale $\Lambda_{\rm QCD}$,
represented by the intrinsic variable \verb|lambda_qcd|. The reference
value for the QCD scale is $\Lambda\_{\rm QCD} = 200$
MeV. \verb|alphas_order| and \verb|alphas_nf| apply analogously.
Note that for using one of the running options for $\alpha_s$, always
\ttt{?alphas\_is\_fixed = false} has to be invoked.
In any case, if $\alpha_s$ is not fixed, each event has to be assigned an
energy scale. By default, this is $\sqrt{\hat s}$, the partonic invariant
mass of the event. This can be replaced by a user-defined scale, the special
object \ttt{scale}. This is assigned and used just like the \ttt{cuts}
object. The right-hand side is a real-valued expression. Here is an example:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
scale = eval Pt [sort by -Pt [colored]]
\end{verbatim}
\end{footnotesize}
\end{quote}
This selects the $p_T$ value of the first entry in the list of colored
particles sorted by decreasing $p_T$, i.e., the $p_T$ of the hardest jet.
The \ttt{scale} definition is used not just for running $\alpha_s$ (if
enabled), but it is also the factorization scale for the \lhapdf\ structure
functions.
These two values can be set differently by specifying
\ttt{factorization\_scale} for the scale at which the PDFs are
evaluated. Analogously, there is a variable
\ttt{renormalization\_scale} that sets the scale value for the running
$\alpha_s$. Whenever any of these two values is set, it supersedes the
\ttt{scale} value.
Just like the \ttt{cuts} expression, the expressions for \ttt{scale},
\ttt{factorization\_scale} and also \ttt{renormalization\_scale}
are evaluated at the point where it is read by an explicit or implicit
\ttt{integrate} command.
\subsection{Reweighting factor}
It is possible to reweight the integrand by a user-defined function of the
event kinematics. This is done by specifying a \ttt{weight} expression.
Syntax and usage is exactly analogous to the \ttt{scale} expression. Example:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
weight = eval (1 + cos (Theta) ^ 2) [lepton]
\end{verbatim}
\end{footnotesize}
\end{quote}
We should note that the phase-space setup is not aware of this reweighting, so
in complicated cases you should not expect adaptation to achieve as accurate
results as for plain cross sections.
Needless to say, the default \ttt{weight} is unity.
\section{Events}
After the cross section integral of a scattering process is known (or the
partial-width integral of a decay process), \whizard\ can generate event
samples. There are two limiting cases or modes of event generation:
\begin{enumerate}
\item
For a physics simulation, one needs \emph{unweighted} events, so the
probability of a process and a kinematical configuration in the event sample
is given by its squared matrix element.
\item
Monte-Carlo integration yields \emph{weighted} events, where the probability
(without any grid adaptation) is uniformly distributed over phase space,
while the weight of the event is given by its squared matrix element.
\end{enumerate}
The choice of parameterizations and the iterative adaptation of the
integration grids gradually shift the generation mode from option 2 to option
1, which obviously is preferred since it simulates the actual outcome of an
experiment. Unfortunately, this adaptation is perfect only in trivial cases,
such that the Monte-Carlo integration yields non-uniform probability still
with weighted events. Unweighted events are obtained by rejection, i.e.,
accepting an event with a probability equal to its own weight divided by the
maximal possible weight. Furthermore, the maximal weight is never precisely
known, so this probability can only be estimated.
The default generation mode of \whizard\ is unweighted. This is controlled by
the parameter \verb|?unweighted| with default value \ttt{true}. Unweighted
events are easy to interpret and can be directly compared with experiment, if
properly interfaced with detector simulation and analysis.
However, when applying rejection to generate unweighted events, the generator
discards information, and for a single event it needs, on the average,
$1/\epsilon$ calls, where the efficiency $\epsilon$ is the ratio of the
average weight over the maximal weight. If \verb|?unweighted| is \ttt{false},
all events are kept and assigned their respective weights in histograms or
event files.
\subsection{Simulation}
\label{sec:simulation}
The \ttt{simulate} command generates an event sample. The number of events
can be set either by specifying the integer variable \verb|n_events|, or by
the real variable \verb|luminosity|. (This holds for unweighted events. If
weighted events are requested, the luminosity value is ignored.) The
luminosity is measured in
femtobarns, but other units can be used, too. Since the cross sections for the
processes are known at that point, the number of events is determined as the
luminosity multiplied by the cross section.
As usual, both parameters can be set either as global or as local parameters:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
n_events = 10000
simulate (proc1)
simulate (proc2, proc3) { luminosity = 100 / 1 pbarn }
\end{verbatim}
\end{footnotesize}
\end{quote}
In the second example, both \verb|n_events| and \verb|luminosity| are set.
In that case, \whizard\ chooses whatever produces the larger number of events.
If more than one process is specified in the argument of \ttt{simulate},
events are distributed among the processes with fractions proportional to
their cross section values. The processes are mixed randomly, as it would be
the case for real data.
The raw event sample is written to a file which is named after the first process
in the argument of \ttt{simulate}. If the process name is \ttt{proc1}, the
file will be named \ttt{proc1.evx}. You can choose another basename by the
string variable \verb|$sample|. For instance,
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
simulate (proc1) { n_events = 4000 $sample = "my_events" }
\end{verbatim}
\end{footnotesize}
\end{quote}
will produce an event file \verb|my_events.evx| which contains $4000$ events.
This event file is in a machine-dependent binary format, so it is not of
immediate use. Its principal purpose is to serve as a cache: if you re-run
the same script, before starting simulation, it will look for an existing
event file that matches the input. If nothing has changed, it will find the
file previously generated and read in the events, instead of generating them.
Thus you can modify the analysis or any further steps without repeating the
time-consuming task of generating a large event sample. If you change the
number of events to generate, the program will make use of the existing event
sample and generate further events only when it is used up. If necessary, you
can suppress the writing/reading of the raw event file by the parameters
\verb|?write_raw| and \verb|?read_raw|.
If you try to reuse an event file that has been written by a previous version
of \whizard, you may run into an incompatibility, which will be detected as an
error. If this happens, you may enforce a compatibility mode (also for
writing) by setting \ttt{\$event\_file\_version} to the appropriate version
string, e.g., \verb|"2.0"|. Be aware that this may break some more recent
features in the event analysis.
Generating an event sample can serve several purposes. First of all,
it can be analyzed directly, by \whizard's built-in capabilities, to
produce tables, histograms, or calculate inclusive observables. The
basic analysis features of \whizard\ are described below in
Sec.~\ref{sec:analysis}. It can be written to an external file in a
standard format that a human or an external program can understand.
In Chap.~\ref{chap:events}, you will find a more thorough discussion
of event generation with \whizard, which also covers in detail the
available event-file formats. Finally, \whizard\ can rescan an
existing event sample. The event sample may either be the result of a
previous \ttt{simulate} run or, under certain conditions, an external
event sample produced by another generator or reconstructed from
data.
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
rescan "my_events" (proc1) { $pdf_builtin_set = "MSTW2008LO" }
\end{verbatim}
\end{footnotesize}
\end{quote}
The rescanning may apply different parameters and recalculate the
matrix element, it may apply a different event selection, it may
reweight the events by a different PDF set (as above). The modified
event sample can again be analyzed or written to file. For more
details, cf.\ Sec.~\ref{sec:rescan}.
%%%%%%%%%%%%%%%
\subsection{Decays}
\label{sec:decays}
Normally, the events generated by the \ttt{simulate} command will be identical
in structure to the events that the \ttt{integrate} command generates. This
implies that for a process such as $pp\to W^+W^-$, the final-state particles
are on-shell and stable, so they appear explicitly in the generated event
files. If events are desired where the decay products of the $W$ bosons
appear, one has to generate another process, e.g., $pp\to u\bar d\bar ud$. In
this case, the intermediate vector bosons, if reconstructed, are off-shell as
dictated by physics, and the process contains all intermediate states that are
possible. In this example, the matrix element contains also $ZZ$, photon, and
non-resonant intermediate states. (This can be restricted via the
\verb|$restrictions| option, cf.\ \ref{sec:process options}.
Another approach is to factorize the process in production (of $W$ bosons) and
decays ($W\to q\bar q$). This is actually the traditional approach, since it
is much less computing-intensive. The factorization neglects all off-shell
effects and irreducible background diagrams that do not have the decaying
particles as an intermediate resonance. While \whizard\ is able to deal with
multi-particle processes without factorization, the needed computing resources
rapidly increase with the number of external particles. Particularly,
it is the phase space integration that becomes the true bottleneck for
a high multiplicity of final state particles.
In order to use the factorized approach, one has to specify particles
as \ttt{unstable}. (Also, the \ttt{?allow\_decays} switch must be \ttt{true};
this is however its default value.) We give an example for a $pp \to Wj$ final
state:
\begin{code}
process wj = u, gl => d, Wp
process wen = Wp => E1, n1
integrate (wen)
sqrts = 7 TeV
beams = p, p => pdf_builtin
unstable Wp (wen)
simulate (wj) { n_events = 1 }
\end{code}
This defines a $2 \to 2$ hard scattering process of $W + j$ production
at the 7 TeV LHC 2011 run. The $W^+$ is marked as unstable, with its
decay process being $W^+ \to e^+ \nu_e$. In the \ttt{simulate} command
both processes, the production process \ttt{wj} and the decay process
\ttt{wen} will be integrated, while the $W$ decays become effective
only in the final event sample. This event sample will contain final
states with multiplicity $3$, namely $e^+ \nu_e d$. Note that here
only one decay process is given, hence the branching ratio for the
decay will be taken to be $100 \%$ by \whizard.
A natural restriction of the factorized approach is the implied narrow-width
approximation. Theoretically, this restriction is necessary since whenever
the width plays an important role, the usage of the factorized approach will
not be fully justified. In particular, all involved matrix elements must be
evaluated on-shell, or otherwise gauge-invariance issues could spoil the
calculation. (There are plans for a future \whizard\ version
to also include Breit-Wigner or Gaussian distributions when using the
factorized approach.)
Decays can be concatenated, e.g. for top pair production and
decay, $e^+ e^- \to t \bar t$ with decay $t \to W^+ b$, and subsequent
leptonic decay of the $W$ as in $W^+ \to \mu^+ \nu_\mu$:
\begin{code}
process eett = e1, E1 => t, tbar
process t_dec = t => Wp, b
process W_dec = Wp => E2, n2
unstable t (t_dec)
unstable Wp (W_dec)
sqrts = 500
simulate (eett) { n_events = 1 }
\end{code}
Note that in this case the final state in the event file will consist
of $\bar t b \mu^+ \nu_\mu$ because the anti-top is not decayed.
If more than one decay process is being specified like in
\begin{code}
process eeww = e1, E1 => Wp, Wm
process w_dec1 = Wp => E2, n2
process w_dec2 = Wp => E3, n3
unstable Wp (w_dec1, w_dec2)
sqrts = 500
simulate (eeww) { n_events = 100 }
\end{code}
then \whizard\ takes the integrals of the specified decay processes
and distributes the decays statistically according to the calculated
branching ratio. Note that this might not be the true branching ratios
if decay processes are missing, or loop corrections to partial widths
give large(r) deviations. In the calculation of the code above,
\whizard\ will issue an output like
\begin{code}
| Unstable particle W+: computed branching ratios:
| w_dec1: 5.0018253E-01 mu+, numu
| w_dec2: 4.9981747E-01 tau+, nutau
| Total width = 4.5496085E-01 GeV (computed)
| = 2.0490000E+00 GeV (preset)
| Decay options: helicity treated exactly
\end{code}
So in this case, \whizard\ uses 50 \% muonic and 50 \% tauonic decays
of the positively charged $W$, while the $W^-$ appears directly in the
event file. \whizard\ shows the difference between the preset $W$
width from the physics model file and the value computed from the two
decay channels.
Note that a particle in a \sindarin\ input script can be also explictly
marked as being stable, using the
\begin{code}
stable <particle-tag>
\end{code}
constructor for the particle \ttt{<particle-tag>}.
\subsubsection{Resetting branching fractions}
\label{sec:br-reset}
As described above, decay processes that appear in a simulation must
first be integrated by the program, either explicitly via the
\verb|integrate| command, or implicitly by \verb|unstable|. In either
case, \whizard\ will use the computed partial widths in order to
determine branching fractions. In the spirit of a purely leading-order
calculation, this is consistent.
However, it may be desired to rather use different branching-fraction
values for the decays of a particle, for instance, NLO-corrected
values. In fact, after \whizard\ has integrated any process, the
integration result becomes available as an ordinary
\sindarin\ variable. For instance, if a decay process has the ID
\verb|h_bb|, the integral of this process -- the partial width, in
this case -- becomes the variable \verb|integral(h_bb)|. This
variable may be reset just like any other variable:
\begin{code}
integral(h_bb) = 2.40e-3 GeV
\end{code}
The new value will be used for all subsequent Higgs branching-ratio
calculations and decays, if an unstable Higgs appears in a process for
simulation.
\subsubsection{Spin correlations in decays}
\label{sec:spin-correlations}
By default, \whizard\ applies full spin and color correlations to the
factorized processes, so it keeps both color and spin coherence between
productions and decays. Correlations between decay products of distinct
unstable particles in the same event are also fully retained. The program
sums over all intermediate quantum numbers.
Although this approach obviously yields the optimal description with the
limits of production-decay factorization, there is support for a simplified
handling of particle decays. Essentially, there are four options, taking a
decay \ttt{W\_ud}: $W^-\to \bar u d$ as an example:
\begin{enumerate}
\item
Full spin correlations: \verb|unstable Wp (W_ud)|
\item
Isotropic decay: \verb|unstable Wp (W_ud) { ?isotropic_decay = true }|
\item
Diagonal decay matrix:
\verb|unstable Wp (W_ud) { ?diagonal_decay = true }|
\item
Project onto specific helicity:
\verb|unstable Wp (W_ud) { decay_helicity = -1 }|
\end{enumerate}
Here, the isotropic option completely eliminates spin correlations. The
diagonal-decays option eliminates just the off-diagonal entries of the $W$
spin-density matrix. This is equivalent to a measurement of spin before the
decay. As a result, spin correlations are still present in the classical
sense, while quantum coherence is lost. The definite-helicity option is
similar and additional selects only the specified helicity component for the
decaying particle, so its decay distribution assumes the shape for an
accordingly polarized particle. All options apply in the rest frame of the
decaying particle, with the particle's momentum as the quantization axis.
\subsubsection{Automatic decays}
A convenient option is if the user did not have to specify the decay
mode by hand, but if they were generated automatically. \whizard\ does
have this option: the flag \ttt{?auto\_decays} can be set to
\ttt{true}, and is taking care of that. In that case the list for the
decay processes of the particle marked as unstable is left empty (we
take a $W^-$ again as example):
\begin{code}
unstable Wm () { ?auto_decays = true }
\end{code}
\whizard\ then inspects at the local position within the \sindarin\
input file where that \ttt{unstable} statement appears the masses of
all the particles of the active physics model in order to determine
which decays are possible. It then calculates their partial widths.
There are a few options to customize the decays. The integer variable
\ttt{auto\_decays\_multiplicity} allows to set the maximal
multiplicity of the final states considered in the auto decay
option. The defaul value of that variable is \ttt{2}; please be quite
careful when setting this to values larger than that. If you do so,
the flag \ttt{?auto\_decays\_radiative} allows to specify whether
final states simply containing additional resolved gluons or photons
are taken into account or not. For the example above, you almost hit
the PDG value for the $W$ total width:
\begin{code}
| Unstable particle W-: computed branching ratios:
| decay_a24_1: 3.3337068E-01 d, ubar
| decay_a24_2: 3.3325864E-01 s, cbar
| decay_a24_3: 1.1112356E-01 e-, nuebar
| decay_a24_4: 1.1112356E-01 mu-, numubar
| decay_a24_5: 1.1112356E-01 tau-, nutaubar
| Total width = 2.0478471E+00 GeV (computed)
| = 2.0490000E+00 GeV (preset)
| Decay options: helicity treated exactly
\end{code}
\subsubsection{Future shorter notation for decays}
{\color{red} In an upcoming \whizard\ version there will be a shorter and more
concise notation already in the process definition for such decays,
which, however, is current not yet implemented. The two first examples
above will then be shorter and have this form:}
\begin{code}
process wj = u, gl => (Wp => E1, n1), d
\end{code}
{\color{red} as well as }
\begin{code}
process eett = e1, E1 => (t => (Wp => E2, n2), b), tbar
\end{code}
%%%%%
\subsection{Event formats}
As mentioned above, the internal \whizard\ event format is a
machine-dependent event format. There are a series of human-readable
ASCII event formats that are supported: very verbose formats intended
for debugging, formats that have been agreed upon during the Les
Houches workshops like LHA and LHEF, or formats that are steered
through external packages like HepMC. More details about event formats
can be found in Sec.~\ref{sec:eventformats}.
%%%%%%%%%%%%%%%
\section{Analysis and Visualization}
\label{sec:analysis}
\sindarin\ natively supports basic methods of data analysis and visualization
which are frequently used in high-energy physics studies. Data generated
during script execution, in particular simulated event samples, can be
analyzed to evaluate further observables, fill histograms, and draw
two-dimensional plots.
So the user does not have to rely on his/her own external graphical
analysis method (like e.g. \ttt{gnuplot} or \ttt{ROOT} etc.), but can
use methods that automatically ship with \whizard. In many cases, the
user, however, clearly will use his/her own analysis machinery,
especially experimental collaborations.
In the following sections, we first summarize the available data structures,
before we consider their graphical display.
\subsection{Observables}
Analyses in high-energy physics often involve averages of quantities other
than a total cross section. \sindarin\ supports this by its \ttt{observable}
objects. An \ttt{observable} is a container that collects a single
real-valued variable with a statistical distribution. It is declared by a
command of the form
\begin{quote}
\begin{footnotesize}
\ttt{observable \emph{analysis-tag}}
\end{footnotesize}
\end{quote}
where \ttt{\emph{analysis-tag}} is an identifier that follows the same rules
as a variable name.
Once the observable has been declared, it can be filled with values. This is
done via the \ttt{record} command:
\begin{quote}
\begin{footnotesize}
\ttt{record \emph{analysis-tag} (\emph{value})}
\end{footnotesize}
\end{quote}
To make use of this, after values have been filled, we want to perform the
actual analysis and display the results. For an observable, these are the
mean value and the standard deviation. There is the command
\ttt{write\_analysis}:
\begin{quote}
\begin{footnotesize}
\ttt{write\_analysis (\emph{analysis-tag})}
\end{footnotesize}
\end{quote}
Here is an example:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
observable obs
record obs (1.2) record obs (1.3) record obs (2.1) record obs (1.4)
write_analysis (obs)
\end{verbatim}
\end{footnotesize}
\end{quote}
The result is displayed on screen:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
###############################################################################
# Observable: obs
average = 1.500000000000E+00
error[abs] = 2.041241452319E-01
error[rel] = 1.360827634880E-01
n_entries = 4
\end{verbatim}
\end{footnotesize}
\end{quote}
\subsection{The analysis expression}
\label{subsec:analysis}
The most common application is the computation of event observables -- for
instance, a forward-backward asymmetry -- during simulation. To this end,
there is an \ttt{analysis} expression, which behaves very similar to the
\ttt{cuts} expression. It is defined either globally
\begin{quote}
\begin{footnotesize}
\ttt{analysis = \emph{logical-expr}}
\end{footnotesize}
\end{quote}
or as a local option to the \ttt{simulate} or \ttt{rescan} commands which
generate and handle event samples. If this expression is defined, it is not
evaluated immediately, but it is evaluated once for each event in the sample.
In contrast to the \ttt{cuts} expression, the logical value of the
\ttt{analysis} expression is discarded; the expression form has been chosen
just by analogy. To make this useful, there is a variant of the \ttt{record}
command, namely a \ttt{record} function with exactly the same syntax. As an
example, here is a calculation of the forward-backward symmetry in a process
\ttt{ee\_mumu} with final state $\mu^+\mu^-$:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
observable a_fb
analysis = record a_fb (eval sgn (Pz) ["mu-"])
simulate (ee_mumu) { luminosity = 1 / 1 fbarn }
\end{verbatim}
\end{footnotesize}
\end{quote}
The logical return value of \ttt{record} -- which is discarded here -- is
\ttt{true} if the recording was successful. In case of histograms (see below)
it is true if the value falls within bounds, false otherwise.
Note that the function version of \ttt{record} can be used anywhere in
expressions, not just in the \ttt{analysis} expression.
When \ttt{record} is called for an observable or histogram in simulation mode,
the recorded value is weighted appropriately. If \ttt{?unweighted} is true,
the weight is unity, otherwise it is the event weight.
The \ttt{analysis} expression can involve any other construct
that can be expressed as an expression in \sindarin. For instance, this
records the energy of the 4th hardest jet in a histogram \ttt{pt\_dist}, if it
is in the central region:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
analysis =
record pt_dist (eval E [extract index 4
[sort by - Pt
[select if -2.5 < Eta < 2.5 [colored]]]])
\end{verbatim}
\end{footnotesize}
\end{quote}
Here, if there is no 4th jet in the event which satisfies the criterion, the
result will be an undefined value which is not recorded. In that case,
\ttt{record} evaluates to \ttt{false}.
Selection cuts can be part of the analysis expression:
\begin{code}
analysis =
if any Pt > 50 GeV [lepton] then
record jet_energy (eval E [collect [jet]])
endif
\end{code}
Alternatively, we can specify a separate selection expression:
\begin{code}
selection = any Pt > 50 GeV [lepton]
analysis = record jet_energy (eval E [collect [jet]])
\end{code}
The former version writes all events to file (if requested), but
applies the analysis expression only to the selected events. This
allows for the simultaneous application of different selections to a
single event sample. The latter version applies the selection to all
events before they are analyzed or written to file.
The analysis expression can make use of all variables and constructs that are
defined at the point where it is evaluated. In particular, it can make use of
the particle content and kinematics of the hard process, as in the example
above. In addition to the predefined variables and those defined by the user,
there are the following variables which depend on the hard process. Some of
them are constants, some vary event by event:
\begin{quote}
\begin{tabular}{ll}
integer: &\ttt{event\_index} \\
integer: &\ttt{process\_num\_id} \\
string: &\ttt{\$process\_id} \\
integer: &\ttt{n\_in}, \ttt{n\_out}, \ttt{n\_tot} \\
real: &\ttt{sqrts}, \ttt{sqrts\_hat} \\
real: &\ttt{sqme}, \ttt{sqme\_ref} \\
real: &\ttt{event\_weight}, \ttt{event\_excess}
\end{tabular}
\end{quote}
The \ttt{process\_num\_id} is the numeric ID as used by external
programs, while the process index refers to the current library. By
default, the two are identical. The process index itself is not
available as a predefined observable. The \ttt{sqme} and
\ttt{sqme\_ref} values indicate the squared matrix element and the
reference squared matrix element, respectively. The latter applies
when comparing with a reference sample (the \ttt{rescan} command).
\ttt{record} evaluates to a logical, so several \ttt{record} functions may
be concatenated by the logical operators \ttt{and} or \ttt{or}. However,
since usually the further evaluation should not depend on the return value of
\ttt{record}, it is more advisable to concatenate them by the semicolon
(\ttt{;}) operator. This is an operator (\emph{not} a statement separator or
terminator) that connects two logical expressions and evaluates both of them
in order. The lhs result is discarded, the result is the value of the rhs:
\begin{quote}
\begin{footnotesize}
\begin{verbatim}
analysis =
record hist_pt (eval Pt [lepton]) ; record hist_ct (eval cos (Theta) [lepton])
\end{verbatim}
\end{footnotesize}
\end{quote}
\subsection{Histograms}
\label{sec:histogram}
In \sindarin, a histogram is declared by the command
\begin{quote}
\begin{footnotesize}
\ttt{histogram \emph{analysis-tag} (\emph{lower-bound}, \emph{upper-bound})}
\end{footnotesize}
\end{quote}
This creates a histogram data structure for an (unspecified) observable. The
entries are organized in bins between the real values \ttt{\emph{lower-bound}}
and \ttt{\emph{upper-bound}}. The number of bins is given by the value of the
intrinsic integer variable \ttt{n\_bins}, the default value is 20.
The \ttt{histogram} declaration supports an optional argument, so the number
of bins can be set locally, for instance
\begin{quote}
\begin{footnotesize}
\ttt{histogram pt\_distribution (0 GeV, 500 GeV) \{ n\_bins = 50 \}}
\end{footnotesize}
\end{quote}
Sometimes it is more convenient to set the bin width directly. This can be
done in a third argument to the \ttt{histogram} command.
\begin{quote}
\begin{footnotesize}
\ttt{histogram pt\_distribution (0 GeV, 500 GeV, 10 GeV)}
\end{footnotesize}
\end{quote}
If the bin width is specified this way, it overrides the setting of
\ttt{n\_bins}.
The \ttt{record} command or function fills histograms. A single call
\begin{quote}
\begin{footnotesize}
\ttt{record (\emph{real-expr})}
\end{footnotesize}
\end{quote}
puts the value of \ttt{\emph{real-expr}} into the appropriate bin. If
the call is issued during a simulation where \ttt{unweighted} is false, the
entry is weighted appropriately.
If the value is outside the range specified in the histogram declaration, it
is put into one of the special underflow and overflow bins.
The \ttt{write\_analysis} command prints the histogram contents as a table in
blank-separated fixed columns. The columns are: $x$ (bin midpoint), $y$ (bin
contents), $\Delta y$ (error), excess weight, and $n$ (number of entries).
The output also contains comments initiated by a \verb|#| sign, and following
the histogram proper, information about underflow and overflow as well as
overall contents is added.
\subsection{Plots}
\label{sec:plot}
While a histogram stores only summary information about a data set, a
\ttt{plot} stores all data as $(x,y)$ pairs, optionally with errors. A plot
declaration is as simple as
\begin{quote}
\begin{footnotesize}
\ttt{plot \emph{analysis-tag}}
\end{footnotesize}
\end{quote}
Like observables and histograms, plots are filled by the \ttt{record} command
or expression. To this end, it can take two arguments,
\begin{quote}
\begin{footnotesize}
\ttt{record (\emph{x-expr}, \emph{y-expr})}
\end{footnotesize}
\end{quote}
or up to four:
\begin{quote}
\begin{footnotesize}
\ttt{record (\emph{x-expr}, \emph{y-expr}, \emph{y-error})}
\\
\ttt{record (\emph{x-expr}, \emph{y-expr},
\emph{y-error-expr}, \emph{x-error-expr})}
\end{footnotesize}
\end{quote}
Note that the $y$ error comes first. This is because applications will
demand errors for the $y$ value much more often than $x$ errors.
The plot output, again written by \ttt{write\_analysis} contains the four
values for each point, again in the ordering $x,y,\Delta y, \Delta x$.
\subsection{Analysis Output}
There is a default format for piping information into observables,
histograms, and plots. In older versions of \whizard\ there was a
first version of a custom format, which was however rather limited.
A more versatile custom output format will be coming soon.
\begin{enumerate}
\item
By default, the \ttt{write\_analysis} command prints all data to the
standard output. The data are also written to a default file with the
name \ttt{whizard\_analysis.dat}.
Output is redirected to a file with a different name if the
variable \ttt{\$out\_file} has a nonempty value. If the file is
already open, the output will be appended to
the file, and it will be kept open. If the file is not open,
\ttt{write\_analysis} will open the output file by itself, overwriting any
previous file with the same name, and close it again after data have been
written.
The command is able to print more than one dataset, following the syntax
\begin{quote}
\begin{footnotesize}
\ttt{write\_analysis (\emph{analysis-tag1}, \emph{analysis-tag2}, \ldots)
\{ \emph{options} \}}
\end{footnotesize}
\end{quote}
The argument in brackets may also be empty or absent; in this case, all
currently existing datasets are printed.
The default data format is suitable for compiling analysis data by \whizard's
built-in \gamelan\ graphics driver (see below and particularly
Chap.~\ref{chap:visualization}). Data are written in
blank-separated fixed columns, headlines and comments are initiated by the
\verb|#| sign, and each data set is terminated by a blank line. However,
external programs often require special formatting.
The internal graphics driver \gamelan\ of \whizard\ is initiated by
the \ttt{compile\_analysis} command. Its syntax is the same, and it
contains the \ttt{write\_analysis} if that has not been separately
called (which is unnecessary). For more details about the \gamelan\
graphics driver and data visualization within \whizard, confer
Chap.~\ref{chap:visualization}.
\item
Custom format. Not yet (re-)implemented in a general form.
\end{enumerate}
\section{Custom Input/Output}
\label{sec:I/O}
\whizard\ is rather chatty. When you run examples or your own scripts, you
will observe that the program echoes most operations (assignments, commands,
etc.) on the standard output channel, i.e., on screen. Furthermore, all
screen output is copied to a log file which by default is named
\ttt{whizard.log}.
For each integration run, \whizard\ writes additional process-specific
information to a file \ttt{\var{tag}.log}, where \ttt{\var{tag}} is the
process name. Furthermore, the \ttt{write\_analysis} command dumps analysis
data -- tables for histograms and plots -- to its own set of files, cf.\
Sec.~\ref{sec:analysis}.
However, there is the occasional need to write data to extra files in a custom
format. \sindarin\ deals with that in terms of the following commands:
\subsection{Output Files}
\subsubsection{open\_out}
\begin{syntax}
open\_out (\var{filename}) \\
open\_out (\var{filename}) \{ \var{options} \}
\end{syntax}
Open an external file for writing. If the file exists, it is overwritten
without warning, otherwise it is created. Example:
\begin{code}
open_out ("my_output.dat")
\end{code}
\subsubsection{close\_out}
\begin{syntax}
close\_out (\var{filename}) \\
close\_out (\var{filename}) \{ \var{options} \}
\end{syntax}
Close an external file that is open for writing. Example:
\begin{code}
close_out ("my_output.dat")
\end{code}
\subsection{Printing Data}
\subsubsection{printf}
\begin{syntax}
printf \var{format-string-expr} \\
printf \var{format-string-expr} (\var{data-objects})
\end{syntax}
Format \ttt{\var{data-objects}} according to \ttt{\var{format-string-expr}}
and print the resulting string to standard output if the string variable
\ttt{\$out\_file} is undefined. If \ttt{\$out\_file} is defined and the file
with this name is open for writing, print to this file instead.
Print a newline at the end if \ttt{?out\_advance} is true, otherwise don't
finish the line.
The \ttt{\var{format-string-expr}} must evaluate to a string. Formatting
follows a subset of the rules for the \ttt{printf(3)} command in the \ttt{C}
language. The supported rules are:
\begin{itemize}
\item All characters are printed as-is, with the exception of embedded
conversion specifications.
\item Conversion specifications are initiated by a percent (\verb|%|) sign and
followed by an optional prefix flag, an optional integer value, an optional
dot followed by another integer, and a mandatory letter as the conversion
specifier.
\item A percent sign immediately followed by another percent sign is
interpreted as a single percent sign, not as a conversion specification.
\item The number of conversion specifiers must be equal to the number of data
objects. The data types must also match.
\item The first integer indicates the minimum field width, the second one the
precision. The field is expanded as needed.
\item The conversion specifiers \ttt{d} and \ttt{i} are equivalent, they
indicate an integer value.
\item The conversion specifier \ttt{e} indicates a real value that should be
printed in exponential notation.
\item The conversion specifier \ttt{f} indicates a real value that should be
printed in decimal notation without exponent.
\item The conversion specifier \ttt{g} indicates a real value that should be
printed either in exponential or in decimal notation, depending on its
value.
\item The conversion specifier \ttt{s} indicates a logical or string value
that should be printed as a string.
\item Possible prefixes are \verb|#| (alternate form, mandatory decimal point
for reals), \verb|0| (zero padding), \verb|-| (left adjusted), \verb|+|
(always print sign), `\verb| |' (print space before a positive number).
\end{itemize}
For more details, consult the \verb|printf(3)| manpage. Note that other
conversions are not supported and will be rejected by \whizard.
The data arguments are numeric, logical or string variables or expressions.
Numeric expressions must be enclosed in parantheses. Logical expressions must
be enclosed in parantheses prefixed by a question mark \verb|?|. String
expressions must be enclosed in parantheses prefixed by a dollar sign
\verb|$|. These forms behave as anonymous variables.
Note that for simply printing a text string, you may call \ttt{printf} with
just a format string and no data arguments.
Examples:
\begin{code}
printf "The W mass is %8f GeV" (mW)
int i = 2
int j = 3
printf "%i + %i = %i" (i, j, (i+j))
string $directory = "/usr/local/share"
string $file = "foo.dat"
printf "File path: %s/%s" ($directory, $file)
\end{code}
There is a related \ttt{sprintf} function, cf.~Sec.~\ref{sec:sprintf}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{WHIZARD at next-to-leading order}
\subsection{Prerequisites}
A full NLO computation requires virtual matrix elements obtained from
loop diagrams. Since \oMega\ cannot calculate such diagrams, external
programs are used. \whizard\ has a generic interface to matrix-element
generators that are BLHA-compatible.
Explicit implementations exist for \gosam, \openloops\ and \recola.
%%%%%
\subsubsection{Setting up \gosam}
The installation of \gosam\ is detailed on the HepForge page
\url{https://gosam/hepforge.org}. We mention here some of the steps
necessary to get it to be linked with \whizard.
{\bf Bug in \gosam\ installation scripts:} In many versions of
\gosam\ there is a bug in the installation scripts that is only
relevant if \gosam\ is installed with superuser privileges. Then all
files in \ttt{\$installdir/share/golem} do not have read privileges
for normal users. These privileges must be given manually to all files
in that directory.
Prerequisites for \gosam\ to produce code for one-loop matrix elements
are the scientific algebra program \ttt{form} and the generator of
loop topologies and diagrams, \ttt{qgraf}.
These can be accessed via their respective webpages
\url{http://www.nikhef.nl/~form/} and
\url{http://cfif.ist.utl.pt/~paulo/qgraf.html}. Note also that both
\ttt{Java} and the Java runtime environment have to be installed in
order for \gosam\ to properly work. Furthermore, \ttt{libtool}
needs to be installed. A more convenient way to install \gosam, is the
automatic installation script
\url{https://gosam.hepforge.org/gosam_installer.py}.
%%%%%
\subsubsection{Setting up \openloops}
\label{sec:openloops-setup}
The installation of \openloops\ is explained in detail on the HepForge
page \url{https://openloops.hepforge.org}. In the following, the main
steps for usage with \whizard\ are summarized.
Please note that at the moment, \openloops\ cannot be installed such
that in almost all cases the explicit \openloops\ package directory
has to be set via \ttt{--with-openloops=<openloops\_dir>}.
\openloops\ can be checked out with
\begin{code}
git clone https://gitlab.com/openloops/OpenLoops.git
\end{code}
Note that \whizard\ only supports \openloops\ version that are at
least 2.1.1 or newer. Alternatively, one can use the public beta
version of \openloops, which can be checked out by the command
\begin{code}
git clone -b public_beta https://gitlab.com/openloops/OpenLoops.git
\end{code}
The program can be build by running \ttt{scons} or \ttt{./scons}, a
local version that is included in the \openloops\ directory. This
produces the script \ttt{./openloops}, which is the main hook for the
further usage of the program.
\openloops\ works by downloading prebuild process libraries, which have
to be installed for each individual process. This requires the file
\ttt{openloops.cfg}, which should contain
the following content:
\begin{code}
[OpenLoops]
process_repositories=public, whizard
compile_extra=1
\end{code}
The first line instructs \openloops\ to also look for process libraries
in an additional lepton collider repository. The second line triggers
the inclusion of $N+1$-particle tree-level matrix elements in the
process directory, so that a complete NLO calculation including real
amplitudes can be performed only with \openloops.
The libraries can then be installed via
\begin{code}
./openloops libinstall proc_name
\end{code}
A list of supported library names can be found on the \openloops\ web
page. Note that a process library also includes all possible permutated
processes. The process library \ttt{ppllj}, for example, can also be
used to compute the matrix elements for $e^+ e^- \rightarrow q \bar{q}$
(massless quarks only). The massive case of the top quark is handled in
\ttt{eett}. Additionally, there are process libraries for top and gauge
boson decays, \ttt{tbw}, \ttt{vjj}, \ttt{tbln} and \ttt{tbqq}.
Finally, \openloops\ can be linked to \whizard\ during configuration by
including
\begin{code}
--enable-openloops --with-openloops=$OPENLOOPS_PATH,
\end{code}
where \ttt{\$OPENLOOPS\_PATH} is the directory the \openloops\
executable is located in. \openloops\ one-loop diagrams can then be
used with the \sindarin\ option
\begin{code}
$loop_me_method = "openloops".
\end{code}
The functional tests which check the \openloops\ functionality require
the libraries \ttt{ppllj}, \ttt{eett} and \ttt{tbw} to be installed (note
that \ttt{eett} is not contained in \ttt{ppll}). During the
configuration of \whizard, it is automatically checked that these two
libraries, as well as the option \ttt{compile\_extra=1}, are present.
\subsubsection{\openloops\ \sindarin\ flags}
Several \sindarin\ options exist to control the behavior of \openloops.
\begin{itemize}
\item \ttt{openloops\_verbosity}:\\
Decide how much \openloops\ output is printed. Can have values 0, 1
and 2.
\item \ttt{?openloops\_use\_cms}:\\
Activates the complex mass scheme. For computations with decaying
resonances like the top quark or W or Z bosons, this is the
preferred option to avoid gauge-dependencies.
\item \ttt{openloops\_phs\_tolerance}:\\
Controls the exponent of \ttt{extra psp\_tolerance} in the BLHA
interface, which is the numerical tolerance for the on-shell
condition of external particles
\item \ttt{openloops\_switch\_off\_muon\_yukawa}:\\
Sets the Yukawa coupling of muons to zero in order to assure
agreement with \oMega, which is possibly used for other
components and per default does not take $H\mu\mu$ couplings
into account.
\item \ttt{openloops\_stability\_log}:\\
Creates the directory \ttt{stability\_log}, which contains information
about the performance of the matrix elements. Possible values are
\begin{itemize}
\item 0: No output (default),
\item 1: On finish() call,
\item 2: Adaptive,
\item 3: Always
\end{itemize}
\item \ttt{?openloops\_use\_collier}: Use Collier as the reduction
method (default true).
\end{itemize}
%%%%%
\subsubsection{Setting up \recola}
\label{sec:recola-setup}
The installation of \recola\ is explained in detail on the HepForge page
\url{https://recola.hepforge.org}. In the following the main steps for
usage with \whizard\ are summarized. The minimal required version number
of \recola\ is 1.3.0.
\recola\ can be linked to \whizard\ during configuration by including
\begin{code}
--enable-recola
\end{code}
In case the \recola\ library is not in a standard path or a path
accessible in the \ttt{LD\_LIBRARY\_PATH} (or
\ttt{DYLD\_LIBRARY\_PATH}) of the operating system, then the option
\begin{code}
--with-recola=$RECOLA_PATH
\end{code}
can be set, where \ttt{\$RECOLA\_PATH} is the directory the
\recola\ library is located in. \recola\ can then be used with the
\sindarin\ option
\begin{code}
$method = "recola"
\end{code}
or any other of the matrix element methods.
Note that there might be a clash of the \collier\ libraries when you
have \collier\ installed both via \recola\ and via \openloops, but
have compiled them with different \fortran\ compilers.
%%%%%
\subsection{NLO cross sections}
An NLO computation can be switched on in \sindarin\ with
\begin{code}
process proc_nlo = in1, in2 => out1, ..., outN { nlo_calculation = <components> },
\end{code}
where the \ttt{nlo\_calculation} can be followed by a list of strings
specifying the desired NLO-components to be integrated, i.e.
\ttt{born}, \ttt{real}, \ttt{virtual}, \ttt{dglap}, (for hadron
collisions) or \ttt{mismatch} (for the soft mismatch in
resonance-aware computations) and \ttt{full}. The \ttt{full} option
switches on all components and is required if the total NLO result is
desired. For example, specifying
\begin{code}
nlo_calculation = born, virtual
\end{code}
will result in the computation of the Born and virtual component.
The integration can be carried out in two different modes: Combined
and separate integration. In the separate integration mode, each
component is integrated individually, allowing for a good overview of
their contributions to the total cross section and a fine tuned
control over the iterations in each component. In the combined
integration mode, all components are added up during integration so that
the sum of them is evaluated. Here, only one integration will be
displayed. The default method is the separate integration.
The convergence of the integration can crucially be influenced by the
presence of resonances. A better convergence is in this case achieved
activating the resonance-aware FKS subtraction,
\begin{code}
$fks_mapping_type = "resonances".
\end{code}
This mode comes with an additional integration component, the
so-called soft mismatch.
Note that you can modify the number of iterations in each component with
the multipliers:
\begin{itemize}
\item \ttt{mult\_call\_real} multiplies the number of calls to be used
in the integration of the real component. A reasonable choice is
\ttt{10.0} as the real phase-space is more complicated than the Born
but the matrix elements evaluate faster than the virtuals.
\item \ttt{mult\_call\_virt} multiplies the number of calls to be used
in the integration of the virtual component. A reasonable choice is
\ttt{0.5} to make sure that the fast Born component only contributes
a negligible MC error compared to the real and virtual components.
\item \ttt{mult\_call\_dglap} multiplies the number of calls to be used
in the integration of the DGLAP component.
\end{itemize}
\subsection{Fixed-order NLO events}
\label{ss:fixedorderNLOevents}
Fixed-order NLO events can also be produced in three different modes:
Combined weighted, combined unweighted and separated weighted.
\begin{itemize}
\item \textbf{Combined weighted}\\
In the combined mode, one single integration grid is produced, from
which events are generated with the total NLO weight. The
corresponding event file contains $N$ events with born-like
kinematics and weight equal to $\mathcal{B} + \mathcal{V} +
\sum_{\alpha_r} \mathcal{C}_{\alpha_r}$, where $\mathcal{B}$ is the
Born matrix element, $\mathcal{V}$ is the virtual matrix element and
$\mathcal{C}_{\alpha_r}$ are the subtraction terms in each singular
region. For resonance-aware processes, also the mismatch value is
added. Each born-like event is followed by $N_{\text{phs}}$
associated events with real kinematics, i.e. events where one
additional QCD particle is present. The corresponding real
matrix elements $\mathcal{R}_\alpha$ form the weight of these events.
$N_{\text{phs}}$ is the number of distinct phase spaces. Two phase spaces
are distinct if they have different resonance histories and/or have
different emitters. So, two $\alpha_r$ can share the same phase
space index.
The combined event mode is activated by
\begin{code}
?combined_nlo_integration = true
?unweighted = false
?fixed_order_nlo_events = true
\end{code}
Moreover, the process must be specified at next-to-leading-order in its
definition using \ttt{nlo\_calculation = full}. \whizard\ then
proceeds as in the usual simulation mode. I.e. it first checks
whether integration grids are already present and uses them if they
fit. Otherwise, it starts an integration.
\item \textbf{Combined unweighted}\\
The unweighted combined events can be generated by using the
\powheg\ mode, cf. also the next subsection, but disabling the
additional radiation and Sudakov factors with the
\ttt{?powheg\_disable\_sudakov} switch:
\begin{code}
?combined_nlo_integration = true
?powheg_matching = true
?powheg_disable_sudakov = true
\end{code}
This will produce events with Born kinematics and unit weights (as
\ttt{?unweighted} is \ttt{true} by default). The events are
unweighted by using $\mathcal{B} + \mathcal{V} + \sum_{\alpha_r}
(\mathcal{C}_{\alpha_r} + \mathcal{R}_{\alpha_r})$. Of course, this
only works when these weights are positive over the full
phase-space, which is not guaranteed for all scales and regions at
NLO. However, for many processes perturbation theory works nicely
and this is not an issue.
\item \textbf{Separate weighted}\\
In the separate mode, grids and events are generated for each
individual component of the NLO process. This method is preferable
for complicated processes, since it allows to individually tune each
grid generation. Moreover, the grid generation is then trivially
parallelized. The event files either contain only Born
kinematics with weight $\mathcal{B}$ or $\mathcal{V}$ (and mismatch
in case of a resonance-aware process) or mixed Born and real
kinematics for the real component like in the combined mode.
However, the Born events have only the weight $\sum_{\alpha_r}
\mathcal{C}_{\alpha_r}$ in this case.
The separate event mode is activated by
\begin{code}
?unweighted = false
?negative_weights = true
?fixed_order_nlo_events = true
\end{code}
Note that negative weights have to be switched on because, in contrast
to the combined mode, the total cross sections of the individual
components can be negative.
Also, the desired component has to appear in the process NLO
specification, e.g. using \ttt{nlo\_calculation = real}.
\end{itemize}
Weighted fixed-order NLO events are supported by any output format that
supports weights like the \ttt{HepMC} format and unweighted NLO events
work with any format. The output can either be written to disk or put
into a FIFO to interface it to an analysis program without writing
events to file.
The weights in the real event output, both in the combined and separate
weighted mode, are divided by a factor $N_{\text{phs}} + 1$. This
is to account for the fact that we artificially increase the number of
events in the output file. Thus, the sum of all event weights correctly
reproduces the total cross section.
\subsection{\powheg\ matching}
To match the NLO events with a parton shower, \whizard\ supports
the \powheg\ matching. It generates a distribution according to
\begin{align}
\label{eq:powheg}
\text{d}\sigma &= \text{d}\Phi_n \,{\bar{B}_{\text{s}}}\,\biggl(
{\Delta_{\text{s}}}(p_T^{\text{min}}\bigr) +
\text{d}\Phi_{\text{rad}}\,{\Delta_{\text{s}}}(k_{\text{T}}(\Phi_{\text{rad}})\bigr)
{\frac{R_{\text{s}}}B}\biggr) \quad \text{where} \\
{\bar{B}_{\text{s}}} &= {B} + {\mathcal{V}} + \text{d}\Phi_{\text{rad}}\,
{\mathcal{R}_{\text{s}}} \quad \text{and} \\
{\Delta_{\text{s}}}(p_T) &= \exp\left[- \int{\text{d}\Phi_{\text{rad}}}
{\frac{R_{\text{s}}}{B}}\; \theta\left(k_T^2(\Phi_{\text{rad}}) -
p_T^2\right)\right]\;.
\end{align}
The subscript s refers to the singular part of the real component, cf.
to the next subsection. Eq.~\eqref{eq:powheg} produces either no or one
additional emission. These events can then either be analyzed directly
or passed on to the parton shower\footnote{E.g. \pythiaeight\ has
explicit examples for \powheg\ input, see also
\url{http://home.thep.lu.se/Pythia/pythia82html/POWHEGMerging.html}.}
for the full simulation. You activate this with
\begin{code}
?fixed_order_nlo_events = false
?combined_nlo_integration = true
?powheg_matching = true
\end{code}
The $p_T^{\text{min}}$ of Eq.~\eqref{eq:powheg} can be set with
\ttt{powheg\_pt\_min}. It sets the minimal scale for the \powheg\
evolution and should be of order 1 GeV and set accordingly in the
interfaced shower. The maximal scale is currently given by \ttt{sqrts}
but should in the future be changeable with \ttt{powheg\_pt\_max}.
Note that the \powheg\ event generation needs an additional grid for
efficient event generation that is generated during integration if
\ttt{?powheg\_matching = true} is set. Thus, this needs to be set before
the \ttt{integrate} statement.
Further options that steer the efficiency of this grid are
\ttt{powheg\_grid\_size\_xi}, \ttt{powheg\_grid\_size\_y} and \ttt{powheg\_grid\_sampling\_points}.
\subsection{Separation of finite and singular contributions}
For both the pure NLO computations as well as the \powheg\ event
generation, \whizard\ supports the partitioning of the real into finite
and singular contributions with the flag
\begin{code}
?nlo_use_real_partition = true
\end{code}
The finite contributions, which by definition should not contain soft or
collinear emissions, will then integrate like an ordinary LO integration
with one additional particle. Similarly, the event generation will
produce only real events without subtraction terms with Born kinematics
for this additional finite component. The \powheg\ event generation
will also only use the singular parts.
The current implementation uses the following parametrization
\begin{align}
R &= R_{\text{fin}} + R_{\text{sing}} \;,\\
R_{\text{sing}} &= R F(\Phi_{n+1}) \;,\\
R_{\text{fin}} &= R (1-F(\Phi_{n+1})) \;,\\
F(\Phi_{n+1}) &=
\begin{cases}
1 & \text{if} \quad\exists\,(i,j)\in\mathcal{P}_{\text{FKS}}\quad \text{with} \quad
\sqrt{(p_i+p_j)^2} < h + m_i + m_j \\
0 & \text{else}
\end{cases} \;.
\end{align}
Thus, a point is {singular ($F=1$)}, if {any} of the {FKS tuples}
forms an {invariant mass} that is {smaller than the hardness scale
$h$}. This parameter is controlled in \sindarin\ with
\ttt{real\_partition\_scale}.
This simplifies in {massless case} to
\begin{align}
F(\Phi_{n+1}) =
\begin{cases}
1 & \text{if} \;\exists\,(i,j)\in\mathcal{P}_{\text{FKS}}\quad \text{with} \quad
2 E_i E_j (1-\cos\theta_{ij}) < h^2 \\
0 & \text{else}
\end{cases} \;.
\end{align}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Random number generators}
\label{chap:rng}
\section{General remarks}
\label{sec:rng}
The random number generators (RNG) are one of the crucialer points of Monte
Carlo calculations, hence, giving those their ``randomness''. A decent
multipurpose random generator covers
\begin{itemize}
\item reproducibility
\item large period
\item fast generation
\item independence
\end{itemize}
of the random numbers. Therefore, special care is taken for the choice of the
RNGs in \whizard{}. It is stated that \whizard{} utilizes \textit{pseudo}-RNGs,
which are based on one (or more) recursive algorithm(s) and start-seed(s) to have
reproducible sequences of numbers. In contrast, a genuine random generator relies
on physical processes.
\whizard\ ships with two completely different random number generators which can be
selected by setting the \sindarin\ option
\begin{code}
$rng_method = "rng_tao"
\end{code}
Although, \whizard{} sets a default seed, it is adviced to use a different one
\begin{code}
seed = 175368842
\end{code}
note that some RNGs do not allow certain seed values (e.g. zero seed).
\section{The TAO Random Number Generator}
\label{sec:tao}
The TAO (``The Art Of'') random number generator is a lagged Fibonacci
generator based upon (signed) 32-bit integer arithmetic and was proposed by
Donald E. Knuth and is implemented in the \vamp\ package.
The TAO random number generator is the default RNG of \whizard{}, but can additionally
be set as \sindarin\ option
\begin{code}
$rng_method = rng_tao
\end{code}
The TAO random number generators is a subtractive lagged Fibonacci generator
\begin{equation*}
x_{j} = \left( x_{j-k} - x_{j-L} \right) \mod 2^{30}
\end{equation*}
with lags $k = 100$ and $l = 37$ and period length $\rho = 2^{30} - 2$.
\section{The RNGStream Generator}
\label{sec:rngstream}
The RNGStream \cite{L_Ecuyer:2002} was originally implemented in \cpp\ with
floating point arithmetic and has been ported to \fortranOThree{}. The RNGstream
can be selected by the \sindarin\ option
\begin{code}
$rng_method = "rng_stream"
\end{code}
The RNGstream supports multiple independent streams and substreams of random
numbers which can be directly accessed.
The main advantage of the RNGStream lies in the domain of parallelization where
different worker have to access different parts of the random number stream to
ensure numerical reproducibility. The RNGstream provides exactly this property with its
(sub)stream-driven model.
Unfortunately, the RNGStream can only be used in combination with \vamptwo{}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Integration Methods}
\section{The Monte-Carlo integration routine: \ttt{VAMP}}
\label{sec:vamp}
\vamp\ \cite{Ohl:1998jn}
is a multichannel extension of the \vegas\ \cite{Lepage:1980dq}
algorithm. For all possible singularities in the integrand, suitable
maps and integration channels are chosen which are then weighted and
superimposed to build the phase space parameterization. Both grids and
weights are modified in the adaption phase of the integration.
The multichannel integration algorithm is implemented as a
\fortranNinetyFive\ library with the task of mapping out the integrand
and finding suitable parameterizations being completely delegated to
the calling program (\whizard\ core in this case). This makes the
actual \vamp\ library completely agnostic of the model under
consideration.
\section{The next generation integrator: \ttt{VAMP2}}
\label{sec:vamp2}
\vamptwo\ is a modern implementation of the integrator package \vamp\ written
in \fortranOThree\, providing the same features. The backbone integrator is
still \vegas\ \cite{Lepage:1980dq}, although implemented differently as in
\vamp{}.
The main advantage over \vamp\ is the overall faster integration due to the usage
of \fortranOThree{}, the possible usage of different random number generators
and the complete parallelization of \vegas\ and the multichannel integration.
\vamptwo{} can be set by the \sindarin{} option
\begin{code}
$integration_method = "vamp2"
\end{code}
It is said that the generated grids between \vamp{} and \vamptwo{} are
incompatible.
\subsection{Multichannel integration}
\label{sec:multi-channel}
The usual matrix elements do not factorise with respect to their integration
variables, thus making an direct integration ansatz with VEGAS
unfavorable.\footnote{One prerequisite for the VEGAS algorithm is that the
integral factorises, and such produces only the best results for those.} Instead, we
apply the multichannel ansatz and let VEGAS integrate each channel in a
factorising mapping.
The different structures of the matrix element are separated by a partition of
unity and the respective mappings, such that each structure factorise at least
once. We define the mappings $\phi_i : U \mapsto \Omega$, where $U$ is the unit
hypercube and $\Omega$ the physical phase space. We refer to each mapping as a
\textit{channel}. Each channel then gives rise to a probability density $g_i : U
\mapsto [0, \infty)$, normalised to unity
\begin{equation*}
\int_0^1 g_i(\phi_i^{-1}(p)) \left| \frac{\partial \phi_i^{-1}}{\partial p} \right| \mathrm{d}\mu(p) = 1, \quad g_i(\phi_i^{-1}(p)) \geq 0,
\end{equation*}
written for a phase space point $p$ using the mapping $\phi_i$.
The \textit{a-priori} channel weights $\alpha_i$ are defined as partition of
unity by $\sum_{i\in I} \alpha_i = 1$ and $0 \leq \alpha_i \leq 1$. The overall
probability density $g$ of a random sample is then obtained by
\begin{equation*}
g(p) = \sum_{i \in I} \alpha_i g_i(\phi_i^{-1}(p)) \left| \frac{\partial \phi_i^{-1}}{\partial p} \right|,
\end{equation*}
which is also a non-negative and normalized probability density.
We reformulate the integral
\begin{equation*}
I(f) = \sum_{i \in I} \alpha_i \int_\Omega g_i(\phi_i^{-1}(p)) \left| \frac{\partial \phi_i^{-1}}{\partial p} \right| \frac{f(p)}{g(p)} \mathrm{d}\mu(p).
\end{equation*}
The actual integration of each channel is then done by VEGAS, which shapes the $g_i$.
\subsection{VEGAS}
\label{sec:vegas}
VEGAS is an adaptive and iterative Monte Carlo algorithm for integration using
importance sampling. After each iteration, VEGAS adapts the probability density
$g_i$ using information collected while sampling. For independent
integration variables, the probability density factorises $g_i = \prod_{j =
1}^{d} g_{i,j}$ for each integration axis and each (independent) $g_{i,j}$ is
defined by a normalised step function
\begin{equation*}
g_{i,j} (x_j) = \frac{1}{N\Delta x_{j,k}}, \quad x_{j,k} - \Delta x_{j,k} \leq x_{j} < x_{j,k},
\end{equation*}
where the steps are $0 = x_{j, 0} < \cdots < x_{j,k} < \cdots < x_{j,N} = 1$ for
each dimension $j$.
The algorithm randomly selects for each dimension a bin and a position inside
the bin and calculates the respective $g_{i,j}$.
\subsection{Channel equivalences}
\label{sec:equivalences}
The automated mulitchannel phasespace configuration can lead to a surplus of
degrees of freedom, e.g. for a highly complex process with a large number of
channels (VBS). In order to marginalize the redundant degrees of freedom of
phasespace configuration, the adaptation distribution of the grids are aligned in accordance to their
phasespace relation, hence the binning of the grids is equialized. These equivalences are activated by
default for \vamp{} and \vamptwo{}, but can be steered by:
\begin{code}
?use_vamp_equivalences = true
\end{code}
Be aware, that the usage of equivalences are currently only possible for LO
processes.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Phase space parameterizations}
\section{General remarks}
\whizard\ as a default performs an adaptive multi-channel Monte-Carlo
integration. Besides its default phase space algorithm, \ttt{wood}, to
be detailed in Sec.~\ref{sec:wood}, \whizard\ contains a phase space
method \ttt{phs\_none} which is a dummy method that is intended for
setups of processes where no phase space integration is needed, but
the program flow needs a (dummy) integrator for internal
consistency. Then, for testing purposes, there is a single-channel
phase space integrator, \ttt{phs\_single}. From version 2.6.0 of
\whizard\ on, there is also a second implementation of the \ttt{wood}
phase space algorithm, called \ttt{fast\_wood},
cf. Sec.~\ref{sec:fast_wood}, whose implementation differs technically
and which therefore solves certain technical flaws of the \ttt{wood}
implementation.
Additionally, \whizard\ supports single-channel, flat phase-space using RAMBO
(on diet).
%%%
\section{The flat method: \ttt{rambo}}
\label{sec:rambo}
The \ttt{RAMBO} algorithm produces a flat phase-space with constant volume for
massless particles. \ttt{RAMBO} was originally published in
\cite{Kleiss:1985gy}. We use the slim version, called \ttt{RAMBO} on diet,
published in \cite{Platzer:2013esa}.
The overall weighting efficiency of the algorithm is unity for massless
final-state particles. For the massive case, the weighting efficiency of unity will
decrease rendering the algorithm less efficient. But in most cases, the
invariants are in regions of phase space where they are much larger than the
masses of the final-state particles.
We provide the \ttt{RAMBO} mainly for cross checking our
implementation and do not recommend it for real world application,
even though it can be used as one. The \ttt{RAMBO} method becomes
useful as a fall-back option if the standard algorithm fails for
physical reasons, see, e.g., Sec.~\ref{sec:ps_anomalous}.
%%%
\section{The default method: \ttt{wood}}
\label{sec:wood}
The \ttt{wood} algorithm classifies different phase space channels
according to their importance for a full scattering or decay process
following heuristic rules. For that purpose, \whizard\ investigates
the kinematics of the different channels depending on the total
center-of-mass energy (or the mass of the decaying particle) and the
masses of the final-state particles.
The \ttt{wood} phase space inherits its name from the naming schemes
of structures of increasing complexities, namely trees, forests and
groves. Simply stated, a phase-space forest is a collection of
phase-space trees. A phase-space tree is a parameterization for a
valid channel in the multi-channel adaptive integration, and each
variable in the a tree corresponds to an integration dimension,
defined by an appropriate mapping of the $(0,1)$ interval of the unit
hypercube to the allowed range of the corresponding integration
variable. The whole set of these phase-space trees, collected in a
phase-space forest object hence contains all parameterizations of the
phase space that \whizard\ will use for a single hard process. Note
that processes might contain flavor sums of particles in the final
state. As \whizard\ will use the same phase space parameterization for
all channels for this set of subprocesses, all particles in those
flavor sums have to have the same mass. E.g. in the definition of a
"light" jet consisting of the first five quarks and antiquarks,
\begin{code}
alias jet = u:d:s:c:b:U:D:S:C:B
\end{code}
all quarks including strange, charm and bottom have to be massless for
the phase-space integration. \whizard\ can treat processes with
subprocesses having final-state particles with different masses in an
"additive" way, where each subprocess will become a distinct component
of the whole process. Each process component will get its own
phase-space parameterization, such that they can allow for different
masses. E.g. in a 4-flavor scheme for massless $u,d,s,c$ quarks one
can write
\begin{code}
alias jet = u:d:s:c:U:D:S:C
process eeqq = e1, E1 => (jet, jet) + (b, B)
\end{code}
In that case, the parameterizations will be for massless final state
quarks for the first subprocess, and for massive $b$ quarks for the
second subprocess. In general, for high-energy lepton colliders, the
difference would not matter much, but performing the integration
e.g. for $\sqrt{s} = 11$ GeV, the difference will be
tremendous. \whizard\ avoids inconsistent phase-space
parameterizations in that way.
As a multi-particle process will contain hundred or thousands of
different channels, the different integration channels (trees) are
grouped into so called {\em groves}. All channels/trees in the same
grove share a common weight for the phase-space integration, following
the assumption that they are related by some approximate symmetry. The
\vamp\ adaptive multi-channel integrator (cf. Sec.~\ref{sec:vamp})
allows for equivalences between different integration channels. This
means that trees/channels that are related by an exact symmetry are
connected by an array of these equivalences.
The phase-space setup, i.e. the detailed structure of trees and
forests, are written by \whizard\ into a phase-space file that has the
same name as the corresponding process (or process component) with the
suffix \ttt{.phs}. For the \ttt{wood} phase-space method this file is
written by a \fortran\ module which constructs a similar tree-like
structure as the directed acyclical graphs (DAGs) in the
\oMega\ matrix element generator but in a less efficient way.
In some very rare cases with externally generated models
(cf. Chapter~\ref{chap:extmodels}) the phase-space generation has been
reported to fail as \whizard\ could not find a valid phase-space
channel. Such pathological cases cannot occur for the hard-coded model
implementations inside \whizard. They can only happen if there are in
principle two different Feynman diagrams contributing to the same
phase-space channel and \whizard\ considers the second one as
extremely subleading (and would hence drop it). If for some reason
however the first Feynman diagram is then absent, no phase-space
channel could be found. This problem cannot occur with the
\ttt{fast\_wood} implementation discussed in the next section,
cf.~\ref{sec:fast_wood}.
The \ttt{wood} algorithms orders the different groves of phase-space
channels according to a heuristic importance depending on the
kinematic properties of the different phase-space channels in the
groves. A phase-space (\ttt{.phs}) file looks typically like this:
\begin{code}
process sm_i1
! List of subprocesses with particle bincodes:
! 8 4 1 2
! e+ e- => mu+ mu-
! 8 4 1 2
md5sum_process = "1B3B7A30C24664A73D3D027382CFB4EF"
md5sum_model_par = "7656C90A0B2C4325AD911301DACF50EB"
md5sum_phs_config = "6F72D447E8960F50FDE4AE590AD7044B"
sqrts = 1.000000000000E+02
m_threshold_s = 5.000000000000E+01
m_threshold_t = 1.000000000000E+02
off_shell = 2
t_channel = 6
keep_nonresonant = T
! Multiplicity = 2, no resonances, 0 logs, 0 off-shell, s-channel graph
grove #1
! Channel #1
tree 3
! Multiplicity = 1, 1 resonance, 0 logs, 0 off-shell, s-channel graph
grove #2
! Channel #2
tree 3
map 3 s_channel 23 ! Z
\end{code}
The first line contains the process name, followed by a list of
subprocesses with the external particles and their binary codes. Then
there are three lines of MD5 check sums, used for consistency
checks. \whizard\ (unless told otherwise) will check for the existence
of a phase-space file, and if the check sum matches, it will reuse the
existing file and not generate it again. Next, there are several
kinematic parameters, namely the center-of-mass energy of the process,
\ttt{sqrts}, and two mass thresholds, \ttt{m\_threshold\_s} and
\ttt{m\_threshold\_t}. The latter two are kinematical thresholds,
below which \whizard\ will consider $s$-channel and $t$-channel-like
kinematic configurations as effectively massless, respectively. The
default values shown in the example have turned out to be optimal
values for Standard Model particles. The two integers \ttt{off\_shell}
and \ttt{t\_channel} give the number of off-shell lines and of
$t$-channel lines that \whizard\ will allow for finding valid
phase-space channels, respectively. This neglects extremley multi-peripheral
background-like diagram constellations which are very subdominamnt
compared to resonant signal processes. The final flag specifies
whether \whizard\ will keep non-resonant phase-space channels
(default), or whether it will focus only on resonant situations.
After this header, there is a list of all groves, i.e. collections of
phase-space channels which are connected by quasi-symmetries, together
with the corresponding multiplicity of subchannels in that
grove. In the phase-space file behind the multiplicity,
\whizard\ denotes the number of (massive) resonances, logarithmcally
enhanced kinematics (e.g. collinear regions), and number of off-shell
lines, respectively. The final entry in the grove header notifies
whether the diagrams in that grove have $s$-channel topologies, or
count the number of corresponding $t$-channel lines.
Another example is shown here,
\begin{code}
! Multiplicity = 3, no resonances, 2 logs, 0 off-shell, 1 t-channel line
grove #1
! Channel #1
tree 3 12
map 3 infrared 22 ! A
map 12 t_channel 2 ! u
! Channel #2
tree 3 11
map 3 infrared 22 ! A
map 11 t_channel 2 ! u
! Channel #3
tree 3 20
map 3 infrared 22 ! A
map 20 t_channel 2 ! u
! Channel #4
tree 3 19
map 3 infrared 22 ! A
map 19 t_channel 2 ! u
\end{code}
where \whizard\ notifies in different situations a photon exchange as
\ttt{infrared}. So it detects a possible infrared singularity where a
particle can become arbitrarily soft. Such a situation can tell the
user that there might be a cut necessary in order to get a meaningful
integration result.
The phase-space setup that is generated and used by the \ttt{wood}
phase-space method can be visualized using the \sindarin\ option
\begin{code}
?vis_channels = true
\end{code}
The \ttt{wood} phase-space method can be invoked with the
\sindarin\ command
\begin{code}
$phs_method = "wood"
\end{code}
Note that this line is unnecessary, as \ttt{wood} is the default
phase-space method of \whizard.
%%%%%
\section{A new method: \ttt{fast\_wood}}
\label{sec:fast_wood}
This method (which is available from version 2.6.0 on) is an
alternative implementation of the \ttt{wood} phase-space algorithm. It
uses the recursive structures inside the \oMega\ matrix element
generator to generate all the structures needed for the different
phase-space channels. In that way, it can avoid some of the
bottlenecks of the \ttt{wood} \fortran\ implementation of the
algorithm. On the other hand, it is only available if the
\oMega\ matrix element generator has been enabled (which is the
default for \whizard). The \ttt{fast\_wood} method is then invoked via
\begin{code}
?omega_write_phs_output = true
$phs_method = "fast_wood"
\end{code}
The first option is necessary in order to tell \oMega\ to write out
the output needed for the \ttt{fast\_wood} parser in order to generate
the phase-space file. This is not enabled by default in order not to
generate unnecessary files in case the default method \ttt{wood} is
used.
So the \ttt{fast\_wood} implementation of the \ttt{wood} phase-space
algorithm parses the tree-like represenation of the recursive set of
one-particle off-shell wave functions that make up the whole amplitude
inside \oMega\ in the form of a directed acyclical graph (DAG) in
order to generate the phase-space (\ttt{.phs}) file
(cf. Sec.~\ref{sec:wood}). In that way, the algorithm makes sure that
only phase-space channels are generated for which there are indeed
(sub)amplitudes in the matrix elements, and this also allows to
exclude vetoed channels due to restrictions imposed on the matrix
elements from the phase-space setup (cf. next
Sec.~\ref{sec:ps_restrictions}).
%%%%%
\section{Phase space respecting restrictions on subdiagrams}
\label{sec:ps_restrictions}
The \fortran\ implementation of the \ttt{wood} phase-space does not
know anything about possible restrictions that maybe imposed on the
\oMega\ matrix elements, cf. Sec.~\ref{sec:process options}.
Consequently, the \ttt{wood} phase space also generates phase-space
channels that might be absent when restrictions are imposed. This is
not a principal problem, as in the adaptation of the phase-space
channels \whizard's integrator \vamp\ will recognize that there is
zero weight in that channel and will drop the channel (stop sampling
in that channel) after some iterations. However, this is a waste of
ressources as it is in principle known that this channel is
absent. Using the \ttt{fast\_wood} phase-space algorithm
(cf. Sec.~\ref{sec:fast_wood} will take restrictions into account, as
\oMega\ will not generate trees for channels that are removed with the
restrictions command. So it advisable for the user in the case of very
complicated processes with restrictions to use the \ttt{fast\_wood}
phase-space method to make \whizard\ generation and integration of the
phase space less cumbersome.
%%%%%
\section{Phase space for processes forbidden at tree level}
\label{sec:ps_anomalous}
The phase-space generators \ttt{wood} and \ttt{fast\_wood} are
intended for tree-level processes with their typical patterns of
singularities, which can be read off from Feynman graphs. They can
and should be used for loop-induced or for externally provided matrix
elements as long as \whizard\ does not provide a dedicated phase-space
module.
Some scattering processes do not occur at tree level but become
allowed if loop effects are included in the calculation. A simple
example is the elastic QED process
\begin{displaymath}
A\quad A \longrightarrow A\quad A
\end{displaymath}
which is mediated by a fermion loop. Similarly, certain applications
provide externally provided or hand-taylored matrix-element code that
replaces the standard \oMega\ code.
Currently, \whizard's phase-space parameterization is nevertheless
tied to the \oMega\ generator, so for tree-level forbidden processes
the phase-space construction process will fail.
There are two possible solutions for this problem:
\begin{enumerate}
\item
It is possible to provide the phase-space parameterization
information externally, by supplying an appropriately formatted
\ttt{.phs} file, bypassing the automatic algorithm. Assuming that
this phase-space file has been named \ttt{my\_phase\_space.phs}, the
\sindarin\ code should contain the following:
\begin{code}
?rebuild_phase_space = false
$phs_file = "my_phase_space.phs"
\end{code}
Regarding the contents of this file, we recommend to generate an
appropriate \ttt{.phs} for a similar setup, using the standard
algorithm. The generated file can serve as a template, which can be
adapted to the particular case.
In detail, the \ttt{.phs} file consists of entries that specify the
process, then a standard header which contains MD5 sums and such --
these variables must be present but their values are irrelevant for
the present case --, and finally at least one \ttt{grove} with
\ttt{tree} entries that specify the parameterization. Individual
parameterizations are built from the final-state and initial-state
momenta (in this order) which we label in binary form as
$1,2,4,8,\dots$. The actual tree consists of iterative fusions of
those external lines. Each fusion is indicated by the number that
results from adding the binary codes of the external momenta that
contribute to it.
For instance, a valid phase-space tree for the process $AA\to AA$ is
given by the simple entry
\begin{code}
tree 3
\end{code}
which indicates that the final-state momenta $1$ and $2$ are
combined to a fusion $1+2=3$. The setup is identical to a process
such as $e^+e^-\to\mu^+\mu^-$ below the $Z$ threshold. Hence, we
can take the \ttt{.phs} file for the latter process, replace the
process tag, and use it as an external phase-space file.
\item
For realistic applications of \whizard\ together with one-loop
matrix-element providers, the actual number of final-state particles may be
rather small, say $2,3,4$. Furthermore, one-loop processes which are
forbidden at tree level do not contain soft or collinear
singularities. In this situation, the \ttt{RAMBO}
phase-space integration method, cf.\ Sec.~\ref{sec:rambo} is a
viable alternative which does not suffer from the problem.
\end{enumerate}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Methods for Hard Interactions}
\label{chap:hardint}
The hard interaction process is the core of any physics simulation
within an MC event generator. One tries to describe the dominant
particle interaction in the physics process of interest at a given
order in perturbation theory, thereby making use of field-theoretic
factorization theorems, especially for QCD, in order to separate
non-perturbative physics like parton distribution functions (PDFs) or
fragmentation functions from the perturbative part. Still, it is in
many cases not possible to describe the perturbative part completely
by means of fixed-order hard matrix elements: in soft and/or collinear
regions of phase space, multiple emission of gluons and quarks (in
general QCD jets) and photons necessitates a resummation, as large
logarithms accompany the perturbative coupling constants and render
fixed-order perturbation theory unreliable. The resummation of these
large logarithms can be done analytically or (semi-)numerically,
however, usually only for very inclusive quantities. At the level of
exclusive events, these phase space regions are the realm of (QCD and
also QED) parton showers that approximate multi-leg matrix elements
from the hard perturbative into to the soft-/collinear regime.
The hard matrix elements are then the core building blocks of the
physics description inside the MC event generator. \whizard\ generates
these hard matrix elements at tree-level (or sometimes for
loop-induced processes using effective operators as insertions) as
leading-order processes. This is done by the \oMega\ subpackage that
is automatically called by \whizard. Besides these physical matrix
elements, there exist a couple of methods to generate dummy matrix
elements for testing purposes, or for generating beam profiles and
using them with externally linked special matrix elements.
Especially for one-loop processes (next-to-leading order for
tree-allowed processes or leading-order for loop-induced processes),
\whizard\ allows to use matrix elements from external providers, so
called OLP programs (one-loop providers). Of course, all of these
external packages can also generate tree-level matrix elements, which
can then be used as well in \whizard.
We start the discussion with the two different options for test matrix
elements, internal test matrix elements with no generated compiled code
in Sec.~\ref{sec:test_me} and so called template matrix elements with
actual \fortran\ code that is compiled and linked, and can also be
modified by the user in Sec.~\ref{sec:template_me}. Then, we move to
the main matrix element method by the matrix element generator
\oMega\ in Sec.~\ref{sec:omega_me}. Matrix elements from the external
matrix element generators are discussed in the order of which
interfaces for the external tools have been implemented: \gosam\ in
Sec.~\ref{sec:gosam_me}, \openloops\ in Sec.~\ref{sec:openloops_me},
and \recola\ in Sec.~\ref{sec:recola_me}.
%%%%%
\section{Internal test matrix elements}
\label{sec:test_me}
This method is merely for internal consistency checks inside \whizard,
and is not really intended to be utilized by the user. The method is
invoked by
\begin{code}
$method = "unit_test"
\end{code}
This particular method is only applicable for the internal test model
\ttt{Test.mdl}, which just contains a Higgs boson and a top
quark. Technically, it will also works within model specifications
for the Standard Model, or the Minimal Supersymmetric Standard Model
(MSSM), or all models which contain particles named as \ttt{H} and
\ttt{t} with PDG codes 25 and 6, respectively. So, the models
\ttt{QED} and {QCD} will not work. Irrespective of what is given in
the \sindarin\ file as a scattering input process, \whizard\ will
always take the process
\begin{code}
model = SM
process <proc_name>= H, H => H, H
\end{code}
or for the test model:
\begin{code}
model = Test
process <proc_name>= s, s => s, s
\end{code}
as corresponding process. (This is the same process, just with
differing nomenclature in the different models). No matrix element
code is generated and compiled, the matrix element is completely
internal, included in the \whizard\ executable (or library), with a
unit value for the squared amplitude. The integration will always be
performed for this particularly process, even if the user provides a
different process for that method. Hence, the result will always be
the volume of the relativistic two-particle phase space. The only two
parameters that influence the result are the collider energy,
\ttt{sqrts}, and the mass of the Higgs particle with PDG code 25 (this
mass parameter can be changed in the model \ttt{Test} as \ttt{ms},
while it would be \ttt{mH} in the Standard Model \ttt{SM}.
It is also possible to use a test matrix element, again internal, for
decay processes, where again \whizard\ will take a predefined process:
\begin{code}
model = SM
process <proc_name> = H => t, tbar
\end{code}
in the \ttt{SM} model or
\begin{code}
model = Test
process <proc_name> = s => f, fbar
\end{code}
Again, this is the same process with PDG codes $25 \to 6 \; -6$ in the
corresponding models. Note that in the model \ttt{SM} the mass of the
quark is set via the variable \ttt{mtop}, while it is \ttt{mf} in the
model \ttt{Test}.
Besides the fact that the user always gets a fixed process and cannot
modify any matrix element code by hand, one can do all things as for a
normal process like generating events, different weights, testing
rebuild flags, using different setups and reweight events
accordingly. Also factorized processes with production and decay can
be tested that way.
In order to avoid confusion, it is highly recommended to use this
method \ttt{unit\_test} only with the test model setup, model
\ttt{Test}.
On the technical side, the method \ttt{unit\_test} does not produce a
process library (at least not an externally linked one), and also not
a makefile in order to modify any process files (which anyways do not
exist for that method). Except for the logfiles and the phase space
file, all files are internal.
%%%%%
\section{Template matrix elements}
\label{sec:template_me}
Much more versatile for the user than the previous matrix element
method in~\ref{sec:test_me}, are two different methods with constant
template matrix elements. These are written out as \fortran\ code by
the \whizard\ main executable (or library), providing an interface
that is (almost) identical to the matrix element code produced by the
\oMega\ generator (cf. the next section,
Sec.~\ref{sec:omega_me}. There are actually two different methods for
that purpose, providing matrix elements with different normalizations:
\begin{code}
$method = "template"
\end{code}
generates matrix elements which give after integration over phase
space exactly one. Of course, for multi-particle final states the
integration can fluctuate numerically and could then give numbers that
are only close to one but not exactly one. Furthermore, the
normalization is not exact if any of the external particles have
non-zero masses, or there are any cuts involved. But otherwise, the
integral from \whizard\ should give unity irrespective of the number
of final state particles.
In contrast to this, the second method,
\begin{code}
$method = "template_unity"
\end{code}
gives a unit matrix elements, or rather a matrix element that contains
helicity and color averaging factors for the initial state and the
square root of the factorials of identical final state particles in
the denominator. Hence, integration over the final state momentum
configuration gives a cross section that corresponds to the volume of
the $n$-particle final state phase space, divided by the corresponding
flux factor, resulting in
\begin{equation}
\sigma(s, 2 \to 2,0) = \frac{3.8937966\cdot 10^{11}}{16\pi} \cdot
\frac{1}{s \text{[GeV]}^2} \; \text{fb}
\end{equation}
for the massless case and
\begin{equation}
\sigma(s, 2 \to 2,m_i) = \frac{3.8937966\cdot 10^{11}}{16\pi} \cdot
\sqrt{\frac{\lambda (s,m_3^2,m_4^2)}{\lambda (s,m_1^2,m_2^2)}}
\cdot \frac{1}{s \text{[GeV]}^2} \; \text{fb}
\end{equation}
for the massive case. Here, $m_1$ and $m_2$ are the masses of the
incoming, $m_3$ and $m_4$ the masses of the outgoing particles, and
$\lambda(x,y,z) = x^2 + y^2 + z^2 - 2xy - 2xz - 2yz$.
For the general massless case with no cuts, the integral should be
exactly
\begin{equation}
\sigma(s, 2\to n, 0) = \frac{(2\pi)^4}{2 s}\Phi_n(s)
= \frac{1}{16\pi s}\,\frac{\Phi_n(s)}{\Phi_2(s)},
\end{equation}
where the volume of the massless $n$-particle phase space is
given by
\begin{equation}\label{phi-n}
\Phi_n(s) = \frac{1}{4(2\pi)^5} \left(\frac{s}{16\pi^2}\right)^{n-2}
\frac{1}{(n-1)!(n-2)!}.
\end{equation}
For $n\neq2$ the phase space volume is dimensionful, so the
units of the integral are $\fb\times\GeV^{2(n-2)}$. (Note that for
physical matrix elements this is compensated by momentum factors from
wave functions, propagators, vertices and possibly dimensionful
coupling constants, but here the matrix element is just equal to
unity.)
Note that the phase-space integration for the \ttt{template} and
\ttt{template\_unity} matrix element methods is organized in the same
way as it would be for the real $2\to n$ process. Since such a phase
space parameterization is not optimized for the constant matrix
element that is supplied instead, good convergence is not guaranteed.
(Setting \ttt{?stratified = true} may be helpful here.)
The possibility to call a dummy matrix element with this method allows
to histogram spectra or structure functions: Choose a trivial process
such as $uu\to dd$, select the \ttt{template\_unity} method, switch
on structure functions for one (or both) beams, and generate events.
The distribution of the final-state mass squared reflects the $x$
dependence of the selected structure function.
Furthermore, the constant in the source code of the unit matrix
elements can be easily modified by the user with their \fortran\ code
in order to study customized matrix elements. Just rerun
\whizard\ with the \ttt{--recompile} option after the modification of
the matrix element code.
Both methods, \ttt{template} and \ttt{template\_unity} will also work
even if no \ocaml\ compiler is found or used and consequently the
\oMega\ matrix elemente generator (cf. Sec.~\ref{sec:omega_me} is
disable. The methods produce a process library for their corresponding
processes, and a makefile, by which \whizard\ steers compilation and
linking of the process source code.
%%%%%
\section{The O'Mega matrix elements}
\label{sec:omega_me}
\oMega\ is a subpackage of \whizard, written in \ocaml, which can
produce matrix elements for a wide class of implemented physics models
(cf. Sec.~\ref{sec:smandfriends} and \ref{sec:bsmmodels} for a list of
all implemented physics models), and even almost arbitrary models when
using external Lagrange level tools, cf. Chap.~\ref{chap:extmodels}.
There are two different variants for matrix elements from \oMega:
the first one is invoked as
\begin{code}
$method = "omega"
\end{code}
and is the default method for \whizard. It produces matrix element as
\fortran\ code which is then compiled and linked. An alternative
method, which for the moment is only available for the Standard Model
and its variants as well models which are quite similar to the SM,
e.g. the Two-Higgs doublet model or the Higgs-singlet extension. This
method is taken when setting
\begin{code}
$method = "ovm"
\end{code}
The acronym \ttt{ovm} stands for \oMega\ Virtual Machine (OVM). The
first (default) method (\ttt{omega}) of \oMega\ matrix elements
produces \fortran\ code for the matrix elements,that is compiled by
the same compiler with which \whizard\ has been compiled. The OVM
method (\ttt{ovm}) generates an \ttt{ASCII} file with so called op
code for operations. These are just numbers which tell what numerical
operations are to be performed on momenta, wave functions and vertex
expression in order to yield a complex number for the amplitude. The
op codes are interpreted by the OVM in the same as a Java Virtual
Machine. In both cases, a compiled \fortran\ is generated which for
the \ttt{omega} method contains the full expression for the matrix
element as \fortran\ code, while for the \ttt{ovm} method this is the
driver file of the OVM. Hence, for the \ttt{ovm} method this file
always has roughly the same size irrespective of the complexity of the
process. For the \ttt{ovm} method, there will also be the \ttt{ASCII}
file that contains the op codes, which has a name with an \ttt{.hbc}
suffix: \ttt{<process\_name>.hbc}.
For both \oMega\ methods, there will be a process library created as
for the template matrix elements (cf. Sec.~\ref{sec:template_me})
named \ttt{default\_lib.f90} which can be given a user-defined name
using the \ttt{library = "<library>"} command. Again, for both methods
\ttt{omega} and \ttt{ovm}, a makefile named
\ttt{<library>\_lib.makefile} is generated by which \whizard\ steers
compilation, linking and clean-up of the process sources. This
makefile can handily be adapted by the user in case she or he wants to
modify the source code for the process (in the case of the source code
method).
Note that \whizard's default ME method via \oMega\ allows the user to
specify many different options either globally for all processes in
the \sindarin, or locally for each process separately in curly
brackets behind the corresponding process definition. Examples are
\begin{itemize}
\item
Restrictions for the matrix elements like the exclusion of
intermediate resonances, the appearance of specific vertices or
coupling constants in the matrix elments. For more details on this
cf. Sec.~\ref{subsec:restrictions}.
\item
Choice of a specific scheme for the width of massive intermediate
resonances, whether to use constant width, widths only in
$s$-channel like kinematics (this is the default), a fudged-width
scheme or the complex-mass scheme. The latter is actually steered as
a specific scheme of the underlying model and not with a specific
\oMega\ command.
\item
Choice of the electroweak gauge for the amplitude. The default is
the unitary gauge.
\end{itemize}
With the exception of the restrictions steered by the
\ttt{\$restrictions = "<restriction>"} string expression, these options
have to be set in their specific \oMega\ syntax verbatim via the
string command \ttt{\$omega\_flags = "<expr>"}.
%%%%%
\section{Interface to GoSam}
\label{sec:gosam_me}
One of the supported methods for automated matrix elements from
external providers is for the \gosam\ package. This program package
which is a combination of \python\ scripts and \fortran\ libraries,
allows both for tree and one-loop matrix elements (which is leading or
next-to-leading order, depending on whether the corresponding process
is allowed at the tree level or not). In principle, the advanced
version of \gosam\ also allows for the evaluation of two-loop virtual
matrix elements, however, this is currently not supported in
\whizard. This method is invoked via the command
\begin{code}
$method = "gosam"
\end{code}
Of course, this will only work correctly of \gosam\ with all its
subcomponents has been correctly found during configuration of
\whizard\ and then subsequently correctly linked.
In order to generate the tables for spin, flavor and color states for
the corresponding process, first \oMega\ is called to provide
\fortran\ code for the interfaces to all the metadata for the
process(es) to be evaluated. Next, the \gosam\ \python\ script is
automatically invoked that first checks for the necessary ingredients
to produce, compile and link the \gosam\ matrix elements. These are
the the \ttt{Qgraf} topology generator for the diagrams, \ttt{Form} to
perform algebra, the \ttt{Samurai}, \ttt{AVHLoop}, \ttt{QCDLoop} and
\ttt{Ninja} libraries for Passarino-Veltman reduction, one-loop tensor
integrals etc. As a next step, \gosam\ automatically writes and
executes a \ttt{configure} script, and then it exchanges the Binoth
Les Houches accord (BLHA) contract files between \whizard\ and
itself~\cite{Binoth:2010xt,Alioli:2013nda} to check whether it
actually generate code for the demanded process at the given
order. Note that the contract and answer files do not have to be
written by the user by hand, but are generated automatically within
the program work flow initiated by the original
\sindarin\ script. \gosam\ then generates \fortran\ code for the
different components of the processes, compiles it and links it into a
library, which is then automatically accessible (as an external
process library) from inside \whizard. The phase space setup and the
integration as well as the LO (and NLO) event generation work then in
exactly the same way as for \oMega\ matrix elements.
As an NLO calculation consists of different components for the Born,
the real correction, the virtual correction, the subtraction part and
possible further components depending on the details of the
calculation, there is the possible to separately choose the matrix
element method for those components via the keywords
\ttt{\$loop\_me\_method}, \ttt{\$real\_tree\_me\_method},
\ttt{\$correlation\_me\_method} etc. These
keywords overwrite the master switch of the \ttt{\$method} keyword.
For more information on the switches and details of the functionality
of \gosam, cf. \url{http://gosam.hepforge.org}.
%%%%%
\section{Interface to Openloops}
\label{sec:openloops_me}
Very similar to the case of \gosam, cf. Sec.~\ref{sec:gosam_me}, is
the case for \openloops\ matrix elements. Also here, first \oMega\ is
called in order to provide an interface for the spin, flavor and color
degrees of freedom for the corresponding process. Information exchange
between \whizard\ and \openloops\ then works in the same automatic way
as for \gosam\ via the BLHA interface. This matrix element method is
invoked via
\begin{code}
$method = "openloops"
\end{code}
This again is the master switch that will tell \whizard\ to use
\openloops\ for all components, while there are special keywords to
tailor-make the setup for the different components of an NLO
calculation (cf. Sec.~\ref{sec:gosam_me}.
The main difference between \openloops\ and \gosam\ is that for
\openloops\ there is no process code to be generated, compiled and
linked for a process, but a precompiled library is called and linked,
e.g. \ttt{ppllj} for the Drell-Yan process. Of course, this library has
to be installed on the system, but if that is not the case, the user
can execute the \openloops\ script in the source directory of
\openloops\ to download, compile and link the corresponding dynamic
library. This limits (for the moment) the usage of \openloops\ to
processes where pre-existint libraries for that specific processes
have been generated by the \openloops\ authors. A new improved
generator for general process libraries for \openloops\ will get rid
of that restriction.
For more information on the installation, switches and details of the
functionality of \openloops, cf. \url{http://openloops.hepforge.org}.
%%%%%
\section{Interface to Recola}
\label{sec:recola_me}
The third one-loop provider (OLP) for external matrix elements that
is supported by \whizard, is \recola. In contrast to \gosam,
cf. Sec.~\ref{sec:gosam_me}, and \openloops,
cf. Sec.~\ref{sec:openloops_me}, \recola\ does not use a BLHA
interface to exchange information with \whizard, but its own
tailor-made C interoperable library interface to communicate to the
Monte Carlo side. \recola\ matrix elements are called for via
\begin{code}
$method = "recola"
\end{code}
\recola\ uses a highly efficient algorithm to generate process code
for LO and NLO SM amplitudes in a fully recursive manner. At the
moment, the setup of the interface within \whizard\ does not allow to
invoke more than one different process in \recola: this would lead to
a repeated initialization of the main setup of \recola\ and would
consequently crash it. It is foreseen in the future to have a
safeguard mechanism inside \whizard\ in order to guarantee
initialization of \recola\ only once, but this is not yet
implemented.
Further information on the installation, details and parameters of
\recola\ can be found at \url{http://recola.hepforge.org}.
%%%%%
\section{Special applications}
\label{sec:special_me}
There are also special applications with combinations of matrix
elements from different sources for dedicated purposes like e.g. for
the matched top--anti-top threshold in $e^+e^-$. For this special
application which depending on the order of the matching takes only
\oMega\ matrix elements or at NLO combines amplitudes from \oMega\ and
\openloops, is invoked by the method:
\begin{code}
$method = "threshold"
\end{code}
\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Implemented physics}
\label{chap:physics}
%%%%%
\section{The hard interaction models}
In this section, we give a brief overview over the different
incarnations of models for the description of the realm of subatomic
particles and their interactions inside \whizard. In
Sec.~\ref{sec:smandfriends}, the Standard Model (SM) itself and
straightforward extensions and modifications thereof in the gauge,
fermionic and Higgs sector are described. Then,
Sec.~\ref{sec:bsmmodels} gives a list and short description of all
genuine beyond the SM models (BSM) that are currently implemented in
\whizard\ and its matrix element generator \oMega. Additional models
beyond that can be integrated and handled via the interfaces to
external tools like \sarah\ and \FeynRules, or the universal model
format \UFO, cf. Chap.~\ref{chap:extmodels}.
%%%%%%%%%%%%%%%
\subsection{The Standard Model and friends}
\label{sec:smandfriends}
%%%%
\subsection{Beyond the Standard Model}
\label{sec:bsmmodels}
\begin{table}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
MODEL TYPE & with CKM matrix & trivial CKM \\
\hline\hline
Yukawa test model & \tt{---} & \tt{Test} \\
\hline
QED with $e,\mu,\tau,\gamma$ & \tt{---} & \tt{QED} \\
QCD with $d,u,s,c,b,t,g$ & \tt{---} & \tt{QCD} \\
Standard Model & \tt{SM\_CKM} & \tt{SM} \\
SM with anomalous gauge couplings & \tt{SM\_ac\_CKM} &
\tt{SM\_ac} \\
SM with $Hgg$, $H\gamma\gamma$, $H\mu\mu$, $He^+e^-$ &
\tt{SM\_Higgs\_CKM} & \tt{SM\_Higgs} \\
SM with bosonic dim-6 operators & \tt{---} &
\tt{SM\_dim6} \\
SM with charge 4/3 top & \tt{---} &
\tt{SM\_top} \\
SM with anomalous top couplings & \tt{---} &
\tt{SM\_top\_anom} \\
SM with anomalous Higgs couplings & \tt{---} &
\tt{SM\_rx}/\tt{NoH\_rx}/\tt{SM\_ul} \\\hline
SM extensions for $VV$ scattering & \tt{---} &
\tt{SSC}/\tt{AltH}/\tt{SSC\_2}/\tt{SSC\_AltT} \\\hline
SM with $Z'$ & \tt{---} & \tt{Zprime} \\
\hline
Two-Higgs Doublet Model & \tt{THDM\_CKM} & \tt{THDM} \\ \hline\hline
MSSM & \tt{MSSM\_CKM} & \tt{MSSM} \\
\hline
MSSM with gravitinos & \tt{---} & \tt{MSSM\_Grav} \\
\hline
NMSSM & \tt{NMSSM\_CKM} & \tt{NMSSM} \\
\hline
extended SUSY models & \tt{---} & \tt{PSSSM} \\
\hline\hline
Littlest Higgs & \tt{---} & \tt{Littlest} \\
\hline
Littlest Higgs with ungauged $U(1)$ & \tt{---} &
\tt{Littlest\_Eta} \\
\hline
Littlest Higgs with $T$ parity & \tt{---} &
\tt{Littlest\_Tpar} \\
\hline
Simplest Little Higgs (anomaly-free) & \tt{---} &
\tt{Simplest} \\
\hline
Simplest Little Higgs (universal) & \tt{---} &
\tt{Simplest\_univ} \\
\hline\hline
SM with graviton & \tt{---} & \tt{Xdim} \\
\hline
UED & \tt{---} & \tt{UED} \\
\hline
``SQED'' with gravitino & \tt{---} & \tt{GravTest} \\
\hline
Augmentable SM template & \tt{---} & \tt{Template} \\
\hline
\end{tabular}
\end{center}
\caption{\label{tab:models} List of models available in
\whizard. There are pure test models or models implemented
for theoretical investigations, a long list of SM variants
as well as a large number of BSM models.}
\end{table}
\subsubsection{Strongly Interacting Models and Composite Models}
Higgsless models have been studied extensively before the Higgs boson
discovery at the LHC Run I in 2012 in order to detect possible
loopholes in the electroweak Higgs sector discovery potential of this
collider. The Threesite Higgsless Model is one of the simplest
incarnations of these models, and was one of the first BSM models
beyond SUSY and Little Higgs models that have been implemented in
\whizard~\cite{Speckner:2010zi}. It is also called the Minimal
Higgsless Model (MHM)~\cite{Chivukula:2006cg} is a minimal
deconstructed Higgsless model which contains only the first resonance
in the tower of Kaluza-Klein modes of a Higgsless extra-dimensional
model. It is a non-renormalizable, effective theory whose
gauge group is an extension of the SM with an extra $SU(2)$ gauge
group. The breaking of the extended electroweak gauge symmetry is
accomplished by a set of nonlinear sigma fields which represent the
effects of physics at a higher scale and make the theory
nonrenormalizable. The physical vector boson spectrum contains the
usual photon, $W^\pm$ and $Z$ bosons as well as a $W'^\pm$ and $Z'$
boson. Additionally, a new set of heavy fermions are introduced to
accompany the new gauge group ``site'' which mix to form the physical
eigenstates. This mixing is controlled by the small mixing parameter
$\epsilon_L$ which is adjusted to satisfy constraints from precision
observables, such as the S parameter~\cite{Chivukula:2005xm}.
Here, additional weak gauge boson production at the LHC was
one of the focus of the studies with \whizard~\cite{Ohl:2008ri}.
\subsubsection{Supersymmetric Models}
\whizard/\oMega\ was the first multi-leg matrix-element/event
generator to include the full Minimal Supersymmetric Standard Model
(MSSM), and also the NMSSM. The SUSY implementations in \whizard\ have
been extensively tested~\cite{Ohl:2002jp,Reuter:2009ex}, and have been
used for many theoretical and experimental studies (some prime
examples
being~\cite{Kalinowski:2008fk,Robens:2008sa,Hagiwara:2005wg}.
\subsubsection{Little Higgs Models}
\subsubsection{Inofficial models}
There have been several models that have been included within the
\whizard/\oMega\ framework but never found their way into the official
release series. One famous example is the non-commutative extension of
the SM, the NCSM. There have been several studies, e.g. simulations on
the $s$-channel production of a $Z$ boson at the photon collider
option of the ILC~\cite{Ohl:2004tn}. Also, the production of
electroweak gauge bosons at the LHC in the framework of the NCSM have
been studied~\cite{Ohl:2010zf}.
%%%%%%%%%%%%%%%
\section{The SUSY Les Houches Accord (SLHA) interface}
\label{sec:slha}
To be filled in
...~\cite{Skands:2003cj,AguilarSaavedra:2005pw,Allanach:2008qq}.
The neutralino sector deserves special attention. After
diagonalization of the mass matrix expresssed in terms
of the gaugino and higgsino eigenstates, the resulting mass
eigenvalues may be either negative or positive. In this case, two
procedures can be followed. Either the masses are rendered
positive and the associated mixing matrix gets purely imaginary
entries or the masses are kept signed, the mixing matrix in this case
being real. According to the SLHA agreement, the second option is
adopted. For a specific eigenvalue, the phase is absorbed into the
definition of the relevant eigenvector, rendering the mass
negative. However, \whizard\ has not yet officially tested for
negative masses. For external SUSY models
(cf.~Chap.~\ref{chap:extmodels}) this means, that one must be careful
using a SLHA file with explicit factors of
the complex unity in the mixing matrix, and on the other hand,
real and positive masses for the neutralinos. For the hard-coded SUSY
models, this is completely handled internally. Especially
Ref.~\cite{Hagiwara:2005wg} discusses the details of the neutralino
(and chargino) mixing matrix.
%%%%%%%%%%%%%%%%
\section{Lepton Collider Beam Spectra}
\label{sec:beamspectra}
For the simulation of lepton collider beam spectra there are two
dedicated tools, \circeone\ and \circetwo\ that have been written as
in principle independent tools. Both attempt to describe the
details of electron (and positron) beams in a realistic lepton
collider environment. Due to the quest for achieving high peak
luminosities at $e^+e^-$ machines, the goal is to make the spatial
extension of the beam as small as possible but keeping the area of the
beam roughly constant. This is achieved by forcing the beams in the
final focus into the shape of a quasi-2D bunch. Due to the high charge
density in that bunch, the bunch electron distribution is modified by
classical electromagnetic radiation, so called {\em beamstrahlung}.
The two \circe\ packages are intended to perform a simulation of this
beamstrahlung and its consequences on the electron beam spectrum as
realistic as possible. More details about the two packages can be
found in their stand-alone documentations. We will discuss the basic
features of lepton-collider beam simulations in the next two sections,
including the technicalities of passing simulations of the machine
beam setup to \whizard. This will be followed by a section on the
simulation of photon collider spectra, included for historical
reasons.
%%%%%
\subsection{\circeone}
While the bunches in a linear collider cross only once, due to their
small size they experience a strong beam-beam effect. There is a
code to simulate the impact of this effect on luminosity and
background, called
\ttt{GuineaPig++}~\cite{Schulte:1998au,Schulte:1999tx,Schulte:2007zz}.
This takes into account the details of the accelerator, the final
focus etc. on the structure of the beam and the main features of the
resulting energy spectrum of the electrons and positrons. It offers
the state-of-the-art simulation of lepton-collider beam spectra as
close as possible to reality. However, for many high-luminosity
simulations, event files produced with \ttt{GuineaPig++} are usually
too small, in the sense that not enough independent events are
available for physics simulations. Lepton collider beam spectra do
peak at the nominal beam energy ($\sqrt{s}/2$) of the collider, and
feature very steeply falling tails. Such steeply falling distributions
are very poorly mapped by histogrammed distributions with fixed bin
widths.
The main working assumption to handle such spectra are being followed
within \circeone:
\begin{enumerate}
\label{circe1_assumptions}
\item The beam spectra for the two beams $P_1$ and $P_2$ factorize
(here $x_1$ and $x_2$ are the energy fractions of the two beams,
respectively):
\begin{equation*}
D_{P_1P_2} (x_1, x_2) = D_{P_1} (x_1) \cdot D_{P_2} (x_2)
\end{equation*}
\item
The peak is described with a delta distribution, and the tail with a
power law:
\begin{equation*}
D(x) = d \cdot \delta(1-x) \; + \; c \cdot x^\alpha \, (1-x)^\beta
\end{equation*}
\end{enumerate}
The two powers $\alpha$ and $\beta$ are the main coefficients that can
be tuned in order to describe the spectrum with \circeone\ as close as
possible as the original \ttt{GuineaPig++} spectrum. More details
about how \circeone\ works and what it does can be found in its own
write-up in \ttt{circe1/share/doc}.
\subsection{\circetwo}
The two conditions listed in \ref{circe1_assumptions} are too
restrictive and hence insufficient to describe more complicated
lepton-collider beam spectra, as they e.g. occur in the CLIC
drive-beam design. Here, the two beams are highly correlated and also
a power-law description does not give good enough precision for the
tails. To deal with these problems, \circetwo\ starts with a
two-dimensional histogram featuring factorized, but variable bin
widths in order to simulate the steep parts of the
distributions. The limited statistics from too small
\ttt{GuineaPig++} event output files leads to correlated
fluctuations that would leave strange artifacts in the
distributions. To abandon them, Gaussian filters are applied to smooth
out the correlated fluctuations. Here care has to be taken when going
from the continuum in $x$ momentum fraction space to the corresponding
\begin{figure}
\centering
\includegraphics{circe2-smoothing}
\caption{\label{fig:circe2-smoothing}
Smoothing the bin at the $x_{e^+} = 1$ boundary with Gaussian
filters of 3 and 10 bins width compared to no smoothing.}
\end{figure}
boundaries: separate smoothing procedures are being applied to the
bins in the continuum region and those in the boundary in order to
avoid artificial unphysical beam energy
spreads. Fig.~\ref{fig:circe2-smoothing} shows the smoothing of the
distribution for the bin at the $x_{e^+} = 1$ boundary. The blue dots
show the direct \ttt{GuineaPig++} output comprising the
fluctuations due to the low statistics. Gaussian filters with widths
of 3 and 10 bins, respectively, have been applied (orange and green
dots, resp.). While there is still considerable fluctuation for 3 bin
width Gaussian filtering, the distribution is perfectly smooth for 10
bin width. Hence, five bin widths seem a reasonable compromise for
histograms with a total of 100 bins. Note that the bins are not
equidistant, but shrink with a power law towards the $x_{e^-} = 1$
boundary on the right hand side of Fig.~\ref{fig:circe2-smoothing}.
\whizard\ ships (inside its subpackage \circetwo) with prepared beam
spectra ready to be used within \circetwo\ for the ILC beam spectra
used in the ILC
TDR~\cite{Behnke:2013xla,Baer:2013cma,Adolphsen:2013jya,Adolphsen:2013kya,Behnke:2013lya}. These
comprise the designed staging energies of 200 GeV, 230 GeV, 250 GeV,
350 GeV, and 500 GeV. Note that all of these spectra up to now do not
take polarization of the original beams on the beamstrahlung into
account, but are polarization-averaged. For backwards compatibility,
also the 500 GeV spectra for the TESLA
design~\cite{AguilarSaavedra:2001rg,Richard:2001qm}, here both for
polarized and polarization-averaged cases, are included. Correlated
spectra for CLIC staging energies like 350 GeV, 1400 GeV and 3000 GeV
are not yet (as of version 2.2.4) included in the \whizard\
distribution.
In the following we describe how to obtain such files with the tools
included in \whizard (resp. \circetwo). The procedure is equivalent to
the so-called \ttt{lumi-linker} construction used by Timothy
Barklow (SLAC) together with the legacy version \whizard\ttt{ 1.95}.
The workflow to produce such files is to run \ttt{GuineaPig++} with
the following input parameters:
\begin{Code}
do_lumi = 7;
num_lumi = 100000000;
num_lumi_eg = 100000000;
num_lumi_gg = 100000000;
\end{Code}
This demands from \ttt{GuineaPig++} the generation of distributions
for the $e^-e^+$, $e^\mp \gamma$, and $\gamma\gamma$ components of the
beamstrahlung's spectrum, respectively. These are the files
\ttt{lumi.ee.out}, \ttt{lumi.eg.out}, \ttt{lumi.ge.out}, and
\ttt{lumi.gg.out}, respectively. These contain pairs $(E_1, E_2)$
of beam energies, {\em not} fractions of the original beam
energy. Huge event numbers are out in here, as \ttt{GuineaPig++}
will produce only a small fraction due to a very low generation
efficiency.
The next step is to transfer these output files from
\ttt{GuineaPig++} into input files used with \circetwo. This is
done by means of the tool \ttt{circe\_tool.opt} that is installed
together with the \whizard\ main binary and libraries. The user should
run this executable with the following input file:
\begin{Code}
{ file="ilc500/ilc500.circe" # to be loaded by WHIZARD
{ design="ILC" roots=500 bins=100 scale=250 # E in [0,1]
{ pid/1=electron pid/2=positron pol=0 # unpolarized e-/e+
events="ilc500/lumi.ee.out" columns=2 # <= Guinea-Pig
lumi = 1564.763360 # <= Guinea-Pig
iterations = 10 # adapting bins
smooth = 5 [0,1) [0,1) # Gaussian filter 5 bins
smooth = 5 [1] [0,1) smooth = 5 [0,1) [1] } } }
\end{Code}
The first line defines the output file, that later can be read in into
the beamstrahlung's description of \whizard\ (cf. below). Then, in the
second line the design of the collider (here: ILC for 500 GeV
center-of-mass energy, with the number of bins) is specified. The next
line tells the tool to take the unpolarized case, then the
\ttt{GuineaPig++} parameters (event file and luminosity) are
set. In the last three lines, details concerning the adaptation of the
simulation as well as the smoothing procedure are being specified: the
number of iterations in the adaptation procedure, and for the
smoothing with the Gaussian filter first in the continuum and then at
the two edges of the spectrum. For more details confer the
documentation in the \circetwo\ subpackage.
This produces the corresponding input files that can be used within
\whizard\ to describe beamstrahlung for lepton colliders, using a
\sindarin\ input file like:
\begin{Code}
beams = e1, E1 => circe2
$circe2_file = "ilc500.circe"
$circe2_design = "ILC"
?circe2_polarized = false
\end{Code}
%%%%%
\subsection{Photon Collider Spectra}
For details confer the complete write-up of the \circetwo\
subpackage.
%%%%%
\section{Transverse momentum for ISR photons}
\label{sec:isr-photon-handler}
The structure functions that describe the splitting of a beam particle
into a particle pair, of which one enters the hard interaction and the
other one is radiated, are defined and evaluated in the strict
collinear approximation. In particular, this holds for the ISR
structure function which describes the radiation of photons off a
charged particle in the initial state.
The ISR structure function that is used by \whizard\ is understood to
be inclusive, i.e., it implicitly contains an integration over
transverse momentum. This approach is to be used for computing a
total cross section via \ttt{integrate}. In \whizard, it is possible
to unfold this integration, as a transformation that is applied by
\ttt{simulate} step, event by event. The resulting modified events
will show a proper logarithmic momentum-transfer ($Q^2$) distribution
for the radiated photons. The recoil is applied to the
hard-interaction system, such that four-momentum and $\sqrt{\hat s}$
are conserved. The distribution is cut off by $Q_{\text{max}}^2$
(cf. \ttt{isr\_q\_max}) for large momentum transfer, and smoothly by
the parton mass (cf.\ \ttt{isr\_mass}) for small momentum transfer.
To activate this modification, set
\begin{Code}
?isr_handler = true
$isr_handler_mode = "recoil"
\end{Code}
before, or as an option to, the \ttt{simulate} command.
Limitations: the current implementation of the $p_T$ modification
works only for the symmetric double-ISR case, i.e., both beams have to
be charged particles with identical mass (e.g., $e^+e^-$). The mode
\ttt{recoil} generates exactly one photon per beam, i.e., it modifies
the momentum of the single collinear photon that the ISR structure
function implementation produces, for each beam. (It is foreseen that
further modes or options will allow to generate multiple photons.
Alternatively, the \pythia\ shower can be used to simulate multiple
photons radiated from the initial state.)
%%%%%
\section{Transverse momentum for the EPA approximation}
\label{sec:epa-beam-handler}
For the equivalent-photon approximation (EPA), which is also defined
in the collinear limit, recoil momentum can be inserted into generated
events in an entirely analogous way. The appropriate settings are
\begin{Code}
?epa_handler = true
$epa_handler_mode = "recoil"
\end{Code}
Limitations: as for ISR, the current implementation of the $p_T$
modification works only for the symmetric double-EPA case. Both
incoming particles of the hard process must be photons, while both
beams must be charged particles with identical mass (e.g., $e^+e^-$).
Furthermore, the current implementation does not respect the
kinematical limit parameter \verb|epa_q_min|, it has to be set to
zero. In effect, the lower $Q^2$ cutoff is determined by the
beam-particle mass \verb|epa_mass|, and the upper cutoff is either
given by $Q_{\text{max}}$ (the parameter
\verb|epa_q_max|), or by the limit $\sqrt{s}$ if this is not set.
It is possible to combine the ISR and EPA handlers, for processes
where ISR is active for one of the beams, EPA for the other beam. For
this scenario to work, both handler switches must be on, and both mode
strings must coincide. The parameters are set separately for ISR and
EPA, as described above.
%%%%%
\section{Resonances and continuum}
\subsection{Complete matrix elements}
Many elementary physical processes are composed of contributions that can be
qualified as (multiply) \emph{resonant} or \emph{continuum}. For instance,
the amplitude for the process $e^+e^-\to q\bar q q\bar q$, evaluated at tree
level in perturbation theory, contains Feynman diagrams with zero, one, or two
$W$ and $Z$ bosons as virtual lines. If the kinematical constraints allow
this, two vector bosons can become simultaneously on-shell in part of phase
space. To a first approximation, this situation is understood as $W^+W^-$ or
$ZZ$ production with subsequent decay. The kinematical distributions show
distinct resonances in the quark-pair spectra. Other graphs contain only one
s-channel $W/Z$ boson, or none at all, such as graphs with $q\bar q$
production and subsequent gluon radiation, splitting into another $q\bar q$
pair.
A \whizard\ declaration of the form
\begin{Code}
process q4 = e1, E1 => u, U, d, D
\end{Code}
produces the full set of graphs for the selected final state, which after
squaring and integrating yields the exact tree-level result for the process.
The result contains all doubly and singly resonant parts, with correct
resonance shapes, as well as the continuum contribution and all interference.
This is, to given order in perturbation theory, the best possible
approximation to the true result.
\subsection{Processes restricted to resonances}
For an intuitive separation of a two-boson ``signal'' contribution, it is
possible to restrict the set of graphs to a certain intermediate state. For
instance, the declaration
\begin{Code}
process q4_zz = e1, E1 => u, U, d, D { $restrictions = "3+4~Z && 5+6~Z" }
\end{Code}
generates an amplitude that contains only those Feynman graphs where the
specified quarks are connected to a $Z$ virtual line. The result may be
understood as $ZZ$ production with subsequent decay, where the $Z$ resonances
exhibit a Breit-Wigner shape. Combining this with the
analogous $W^+W^-$ restricted process, the user can generate ``signal''
processes.
Adding both ``signal'' cross sections $WW$ and $ZZ$ will result in a
reasonable approximation to the exact tree-level cross section. The amplitude
misses the single-resonant and continuum contributions, and the squared
amplitude misses the interference terms, however. More importantly, the
restricted processes as such are not gauge-invariant (with respect to the
electroweak gauge group), and they are no longer dominant away from resonant
kinematics. We therefore strongly recommend that such restricted processes
are always accompanied by a cut setup that restricts the kinematics to an
approximately on-shell pattern for both resonances. For instance:
\begin{Code}
cuts = all 85 GeV < M < 95 GeV [u:U]
and all 85 GeV < M < 95 GeV [d:D]
\end{Code}
In this region, the gauge-dependent and continuum contributions are strictly
subdominant. Away from the resonance(s), the results for a restricted process
are meaningless, and the full process has to be computed instead.
\subsection{Factorized processes}
Another method for obtaining the signal contribution is a proper factorization
into resonance production and decay. We would have to generate a production
process and two decay processes:
\begin{Code}
process z_uu = Z => u, U
process z_dd = Z => d, D
process zz = e1, E1 => Z, Z
\end{Code}
All three processes must be integrated. The integration results are partial
decay widths and the $ZZ$ production cross section, respectively. (Note that
cut expressions in \sindarin\ apply to all integrations, so make sure that
no production-process cuts are active when integrating the decay
processes.)
During a later event-generation step, the $Z$ decays can then be activated by declaring the $Z$ as
unstable,
\begin{Code}
unstable Z (z_uu, z_dd)
\end{Code}
and then simulating the production process
\begin{Code}
simulate (zz)
\end{Code}
The generated events will consist of four-fermion final states, including all
combinations of both decay modes. It is important to note that in this setup,
the invariant $u\bar u$ and $d\bar d$ masses will be always \emph{exactly}
equal to the $Z$ mass. There is no Breit-Wigner shape involved. However, in
this approximation the results are gauge-invariant, as there is no off-shell
contribution involved.
For further details on factorized processes and spin correlations,
cf.\ Sec.~\ref{sec:spin-correlations}.
\subsection{Resonance insertion in the event record}
From the above discussion, we may conclude that it is always preferable to
compute the complete process for a given final state, as long as this is
computationally feasible. However, in the simulation step this approach also
has a drawback. Namely, if a parton-shower module (see below) is switched on,
the parton-shower algorithm relies on event details in order to determine the
radiation pattern of gluons and further splitting. In the generated event
records, the full-process events carry the signature of non-resonant continuum
production with no intermediate resonances. The parton shower will thus start
the evolution at the process energy scale, the total available energy. By
contrast, for an electroweak production and decay process, the evolution
should start only at the vector boson mass, $m_Z$. In effect, even though the
resonant contribution of $WW$ and $ZZ$ constitutes the bulk of the cross
section, the radiation pattern follows the dynamics of four-quark continuum
production. In general, the number of radiated hadrons will be too high.
\begin{figure}
\begin{center}
\includegraphics[width=.41\textwidth]{resonance_e_gam}
\includegraphics[width=.41\textwidth]{resonance_n_charged} \\
\includegraphics[width=.41\textwidth]{resonance_n_hadron}
\includegraphics[width=.41\textwidth]{resonance_n_particles} \\
\includegraphics[width=.41\textwidth]{resonance_n_photons}
\includegraphics[width=.41\textwidth]{resonance_n_visible}
\end{center}
\caption{The process $e^+e^- \to jjjj$ at 250 GeV center-of-mass
energy is compared transferring the partonic events naively to the
parton shower, i.e. without respecting any intermediate resonances
(red lines). The blue lines show the process factorized into $WW$
production and decay, where the shower knows the origin of the two
jet pairs. The orange and dark green lines show the resonance
treatment as mentioned in the text, with
\ttt{resonance\_on\_shell\_limit = 1} and \ttt{= 4},
respectively. \pythiasix\ parton shower and hadronization with the
OPAL tune have been used. The observables are: photon energy
distribution and number of charged tracks (upper line left/right,
number of hadrons and total number of particles (middle
left/right), and number of photons and neutral particles (lower
line left/right).}
\end{figure}
To overcome this problem, there is a refinement of the process description
available in \whizard. By modifying the process declaration to
\begin{Code}
?resonance_history = true
resonance_on_shell_limit = 4
process q4 = e1, E1 => u, U, d, D
\end{Code}
we advise the program to produce not just the complete matrix element, but
also all possible restricted matrix elements containing resonant intermediate
states. This has no effect at all on the integration step, and thus on the
total cross section.
However, when subsequently events are generated with this setting, the program
checks, for each event, the kinematics and determines the set of potentially
resonant contributions. The criterion is whether the off-shellness of a
particular would-be resonance is less than the resonance width multiplied by
the value of \verb|resonance_on_shell_limit| (default value $=4$). For the
set of resonance histories which pass this criterion (which can be empty),
their respective squared matrix element is related to the full-process matrix
element. The ratio is interpreted as a probability. The random-number
generator then selects one or none of the resonance histories, and modifies
the event record accordingly. In effect, for an appropriate fraction of the
events, depending on the kinematics, the parton-shower module is provided with
resonance information, so it can adjust the radiation pattern accordingly.
It has to be mentioned that generating the matrix-element code for all
possible resonance histories takes additional computing resources. In the
current default setup, this feature is switched off. It has to be explicitly
activated via the \verb|?resonance_history| flag.
Also, the feature can be activated or deactivated individually for
each process, such as in
\begin{Code}
?resonance_history = true
process q4_with_res = e1, E1 => u, U, d, D { ?resonance_history = true }
process q4_wo_res = e1, E1 => u, U, d, D { ?resonance_history = false }
\end{Code}
If the flag is \verb|false| for a process, no resonance code will be
generated. Similarly, the flag has to be globally or locally active
when \verb|simulate| is called, such that the feature takes effect for
event generation.
There are two additional parameters that can fine-tune the conditions for
resonance insertion in the event record. Firstly, the parameter
\verb|resonance_on_shell_turnoff|, if nonzero, enables a Gaussian suppression
of the probability for resonance insertion. For instance, setting
\begin{Code}
?resonance_history = true
resonance_on_shell_turnoff = 4
resonance_on_shell_limit = 8
\end{Code}
will reduce the probability for the event to be qualified as resonant by
$e^{-1}= 37\,\%$ if the kinematics is off-shell by four units of the width,
and by $e^{-4}=2\,\%$ at eight units of the width. Beyond this point, the
setting of the \verb|resonance_on_shell_limit| parameter eliminates resonance
insertion altogether. In effect, the resonance-background transition is
realized in a smooth way. Secondly, within the resonant-kinematics range the
probability for qualifying the event as background can be reduced by the
parameter \verb|resonance_background_factor| (default value $=1$) to a number
between zero and one. Setting this to zero means that the event will be
necessarily qualified as resonant, if it falls within the resonant-kinematics
range.
Note that if an event, by the above mechanism, is identified as following a
certain resonance history, the assigned color flow will be chosen to match the
resonance history, not the complete matrix element. This may result in a
reassignment of color flow with respect to the original partonic event.
Finally, we mention the order of execution: any additional
matrix element code is compiled and linked when \verb|compile| is
executed for the processes in question. If this command is omitted,
the \verb|simulate| command will trigger compilation.
\section{Parton showers and Hadronization}
In order to produce sensible events, final state QCD (and also QED)
radiation has to be considered as well as the binding of strongly
interacting partons into mesons and baryons. Furthermore, final state
hadronic resonances undergo subsequent decays into those particles
showing up in (or traversing) the detector. The latter are mostly
pions, kaons, photons, electrons and muons.
The physics associated with these topics can be divided into the
perturbative part which is the regime of the parton shower, and the
non-perturbative part which is the regime for the
hadronization. \whizard\ comes with its own two different parton
shower implementations, an analytic and a so-called $k_T$-ordered
parton shower that will be detailed in the next section.
Note that in general it is not advisable to use different shower and
hadronization methods, or in other words, when using shower and
hadronization methods from different programs these would have to be
tuned together again with the corresponding data.
Parton showers are approximations to full matrix elements taking only
the leading color flow into account, and neglecting all interferences
between different amplitudes leading to the same exclusive final
state. They rely on the QCD (and QED) splitting functions to describe
the emissions of partons off other partons. This is encoded in the
so-called Sudakov form factor~\cite{Sudakov:1954sw}:
\begin{equation*}
\Delta( t_1, t_2) = \exp \left[ \int\limits_{t_1}^{t_2} \mbox{d} t
\int\limits_{z_-}^{z_+} \mbox{d} z \frac{\alpha_s}{2 \pi t} P(z)
\right]
\end{equation*}
This gives the probability for a parton to evolve from scale $t_2$ to
$t_1$ without any further emissions of partons. $t$ is the evolution
parameter of the shower, which can be a parton energy, an emission
angle, a virtuality, a transverse momentum etc. The variable $z$
relates the two partons after the branching, with the most common
choice being the ratio of energies of the parton after and before the
branching. For final-state radiation brachings occur after the hard
interaction, the evolution of the shower starts at the scale of the
hard interaction, $t \sim \hat{s}$, down to a cut-off scale $t =
t_{\text{cut}}$ that marks the transition to the non-perturbative
regime of hadronization. In the space-like evolution for the
initial-state shower, the evolution is from a cut-off representing the
factorization scale for the parton distribution functions (PDFs) to the
inverse of the hard process scale, $-\hat{s}$. Technically, this
evolution is then backwards in (shower) time~\cite{Sjostrand:1985xi},
leading to the necessity to include the PDFs in the Sudakov factors.
The main switches for the shower and hadronization which are realized
as transformations on the partonic events within \whizard\ are
\ttt{?allow\_shower} and \ttt{?allow\_hadronization}, which are
true by default and only there for technical reasons. Next, different
shower and hadronization methods can be chosen within \whizard:
\begin{code}
$shower_method = "WHIZARD"
$hadronization_method = "PYTHIA6"
\end{code}
The snippet above shows the default choices in \whizard\, namely
\whizard's intrinsic parton shower, but \pythiasix\ as hadronization
tool. (Note that \whizard\ does not have its own hadronization module
yet.) The usage of \pythiasix\ for showering and hadronization will
be explained in Sec.~\ref{sec:pythia6}, while the two different
implementations of the \whizard\ homebrew parton showers are discussed
in Sec.~\ref{sec:ktordered} and~\ref{sec:analytic}, respectively.
%%%%%
\subsection{The $k_T$-ordered parton shower}
\label{sec:ktordered}
%%%%%
\subsection{The analytic parton shower}
\label{sec:analytic}
%%%%%
\subsection{Parton shower and hadronization from \pythiasix}
\label{sec:pythia6}
Development of the \pythiasix\ generator for parton shower and
hadronization (the \fortran\ version) has been discontinued by the
authors several years ago. Hence, the final release of that program is
frozen. This allowed to ship this final version, v6.427, with the
\whizard\ distribution without the need of updating it all the
time. One of the main reasons for that inclusion -- besides having the
standard tool for showering and hadronization for decays at hand -- is
to allow for backwards validation within \whizard\ particularly for
the event samples generated for the development of linear collider
physics: first for TESLA, JLC and NLC, and later on for the Conceptual
and Technical Design Report for ILC, for the Conceptual Design Report
for CLIC as well as for the Letters of Intent for the LC detectors,
ILD and SiD.
Usually, an external parton shower and hadronization program (PS) is
steered via the transfer of event files that are given to the PS via
LHE events, while the PS program then produces hadron level events,
usually in HepMC format. These can then be directed towards a full or
fast detector simulation program. As \pythiasix\ has been completely
integrated inside the \whizard\ framework, the showered or more
general hadron level events can be returned to and kept inside
\whizard's internal event record, and hence be used in \whizard's
internal event analysis. In that way, the events can be also written
out in event formats that are not supported by \pythiasix,
e.g. \ttt{LCIO} via the output capabilities of \whizard.
There are several switches to directly steer \pythiasix\ (the values
in brackets correspond to the \pythiasix\ variables):
\begin{code}
ps_mass_cutoff = 1 GeV [PARJ(82)]
ps_fsr_lambda = 0.29 GeV [PARP(72)]
ps_isr_lambda = 0.29 GeV [PARP(61)]
ps_max_n_flavors = 5 [MSTJ(45)]
?ps_isr_alphas_running = true [MSTP(64)]
?ps_fsr_alphas_running = true [MSTJ(44)]
ps_fixed_alphas = 0.2 [PARU(111)]
?ps_isr_angular_ordered = true [MSTP(62)]
ps_isr_primordial_kt_width = 1.5 GeV [PARP(91)]
ps_isr_primordial_kt_cutoff = 5.0 GeV [PARP(93)]
ps_isr_z_cutoff = 0.999 [1-PARP(66)]
ps_isr_minenergy = 2 GeV [PARP(65)]
?ps_isr_only_onshell_emitted_partons =
true [MSTP(63)]
\end{code}
The values given above are the default values. The first value
corresponds to the \pythiasix\ parameter \ttt{PARJ(82)}, its
squared being the minimal virtuality that is allowed for the parton
shower, i.e. the cross-over to the hadronization. The same parameter
is used also for the \whizard\ showers. \ttt{ps\_fsr\_lambda} is
the equivalent of \ttt{PARP(72)} and is the $\Lambda_{\text{QCD}}$
for the final state shower. The corresponding variable for the initial
state shower is called \ttt{PARP(61)} in \pythiasix. By the next
variable (\ttt{MSTJ(45)}), the maximal number of flavors produced
in splittings in the shower is given, together with the number of
active flavors in the running of
$\alpha_s$. \ttt{?ps\_isr\_alphas\_running} which corresponds to
\ttt{MSTP(64)} in \pythiasix\ determines whether or net a running
$\alpha_s$ is taken in the space-like initial state showers. The same
variable for the final state shower is \ttt{MSTJ(44)}. For fixed
$\alpha_s$, the default value is given by \ttt{ps\_fixed\_alpha},
corresponding to \ttt{PARU(111)}. \ttt{MSTP(62)} determines
whether the ISR shower is angular order, i.e. whether angles are
increasing towards the hard interaction. This is per default true, and
set in the variable \ttt{?ps\_isr\_angular\_ordered}. The width of
the distribution for the primordial (intrinsic) $k_T$ distribution
(which is a non-perturbative quantity) is the \pythiasix\ variable
\ttt{PARP(91)}, while in \whizard\ it is given by
\ttt{pythia\_isr\_primordial\_kt\_width}. The next variable
(\ttt{PARP(93}) gives the upper cutoff for that distribution, which
is 5 GeV per default. For splitting in space-like showers, there is a
cutoff on the $z$ variable named \ttt{ps\_isr\_z\_cutoff} in
\whizard. This corresponds to one minus the value of the
\pythiasix\ parameter \ttt{PARP(66)}. \ttt{PARP(65)}, on the
other hand, gives the minimal (effective) energy for a time-like or
on-shell emitted parton on a space-like QCD shower, given by the
\sindarin\ parameter \ttt{ps\_isr\_minenergy}. Whether or not
partons emitted from space-like showers are allowed to be only
on-shell is given by
\ttt{?ps\_isr\_only\_onshell\_emitted\_partons}, \ttt{MSTP(63)}
in \pythiasix\ language.
For more details confer the
\pythiasix\ manual~\cite{Sjostrand:2006za}.
Any other non-standard \pythiasix\ parameter can be fed into the
parton shower via the string variable
\begin{code}
$ps_PYTHIA_PYGIVE = "...."
\end{code}
Variables set here get preference over the ones set explicitly by
dedicated \sindarin\ commands. For example, the OPAL tune for hadronic
final states can be set via:
\begin{code}
$ps_PYTHIA_PYGIVE = "MSTJ(28)=0; PMAS(25,1)=120.; PMAS(25,2)=0.3605E-02; MSTJ(41)=2;
MSTU(22)=2000; PARJ(21)=0.40000; PARJ(41)=0.11000; PARJ(42)=0.52000; PARJ(81)=0.25000;
PARJ(82)=1.90000; MSTJ(11)=3; PARJ(54)=-0.03100; PARJ(55)=-0.00200; PARJ(1)=0.08500;
PARJ(3)=0.45000; PARJ(4)=0.02500; PARJ(2)=0.31000; PARJ(11)=0.60000; PARJ(12)=0.40000;
PARJ(13)=0.72000; PARJ(14)=0.43000; PARJ(15)=0.08000; PARJ(16)=0.08000;
PARJ(17)=0.17000; MSTP(3)=1;MSTP(71)=1"
\end{code}
\vspace{0.5cm}
A very common error that appears quite often when using
\pythiasix\ for SUSY or any other model having a stable particle that
serves as a possible Dark Matter candidate, is the following
warning/error message:
\begin{Code}
Advisory warning type 3 given after 0 PYEXEC calls:
(PYRESD:) Failed to decay particle 1000022 with mass 15.000
******************************************************************************
******************************************************************************
*** FATAL ERROR: Simulation: failed to generate valid event after 10000 tries
******************************************************************************
******************************************************************************
\end{Code}
In that case, \pythiasix\ gets a stable particle (here the lightest
neutralino with the PDG code 1000022) handed over and does not know
what to do with it. Particularly, it wants to treat it as a heavy
resonance which should be decayed, but does not know how do
that. After a certain number of tries (in the example abobe 10k),
\whizard\ ends with a fatal error telling the user that the event
transformation for the parton shower in the simulation has failed
without producing a valid event. The solution to work around that
problem is to let \pythiasix\ know that the neutralino (or any other
DM candidate) is stable by means of
\begin{code}
$ps_PYTHIA_PYGIVE = "MDCY(C1000022,1)=0"
\end{code}
Here, 1000022 has to be replaced by the stable dark matter candidate
or long-lived particle in the user's favorite model. Also note that
with other options being passed to \pythiasix\, the \ttt{MDCY}
option above has to be added to an existing
\ttt{\$ps\_PYTHIA\_PYGIVE} command separated by a semicolon.
%%%%%
\subsection{Parton shower and hadronization from \pythiaeight}
\subsection{Other tools for parton shower and hadronization}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{More on Event Generation}
\label{chap:events}
In order to perform a physics analysis with \whizard\ one has to
generate events. This seems to be a trivial statement, but as there
have been any questions like "My \whizard\ does not produce plots --
what has gone wrong?" we believe that repeating that rule is
worthwile. Of course, it is not mandatory to use \whizard's own analysis
set-up, the user can always choose to just generate events and use
his/her own analysis package like \ttt{ROOT}, or \ttt{TopDrawer}, or
you name it for the analysis.
Accordingly, we first start to describe how to generate events and
what options there are -- different event formats, renaming output
files, using weighted or unweighted events with different
normalizations. How to re-use and manipulate already generated event
samples, how to limit the number of events per file, etc. etc.
\section{Event generation}
To explain how event generation works, we again take our favourite
example, $e^+e^- \to \mu^+ \mu^-$,
\begin{verbatim}
process eemm = e1, E1 => e2, E2
\end{verbatim}
The command to trigger generation of events is \ttt{simulate
(<proc\_name>) \{ <options> \}}, so in our case -- neglecting any
options for now -- simply:
\begin{verbatim}
simulate (eemm)
\end{verbatim}
When you run this \sindarin\ file you will experience a fatal error:
\ttt{FATAL ERROR: Colliding beams: sqrts is zero (please set
sqrts)}. This is because \whizard\ needs to compile and integrate the
process \ttt{eemm} first before event simulation, because it needs the
information of the corresponding cross section, phase space
parameterization and grids. It does both automatically, but you have
to provide \whizard\ with the beam setup, or at least with the
center-of-momentum energy. A corresponding \ttt{integrate} command
like
\begin{verbatim}
sqrts = 500 GeV
integrate (eemm) { iterations = 3:10000 }
\end{verbatim}
obviously has to appear {\em before} the corresponding \ttt{simulate}
command (otherwise you would be punished by the same error message as
before). Putting things in the correct order results in an output
like:
\begin{footnotesize}
\begin{verbatim}
| Reading model file '/usr/local/share/whizard/models/SM.mdl'
| Preloaded model: SM
| Process library 'default_lib': initialized
| Preloaded library: default_lib
| Reading commands from file 'bla.sin'
| Process library 'default_lib': recorded process 'eemm'
sqrts = 5.000000000000E+02
| Integrate: current process library needs compilation
| Process library 'default_lib': compiling ...
| Process library 'default_lib': keeping makefile
| Process library 'default_lib': keeping driver
| Process library 'default_lib': active
| Process library 'default_lib': ... success.
| Integrate: compilation done
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 29912
| Initializing integration for process eemm:
| ------------------------------------------------------------------------
| Process [scattering]: 'eemm'
| Library name = 'default_lib'
| Process index = 1
| Process components:
| 1: 'eemm_i1': e-, e+ => mu-, mu+ [omega]
| ------------------------------------------------------------------------
| Beam structure: [any particles]
| Beam data (collision):
| e- (mass = 5.1099700E-04 GeV)
| e+ (mass = 5.1099700E-04 GeV)
| sqrts = 5.000000000000E+02 GeV
| Phase space: generating configuration ...
| Phase space: ... success.
| Phase space: writing configuration file 'eemm_i1.phs'
| Phase space: 2 channels, 2 dimensions
| Phase space: found 2 channels, collected in 2 groves.
| Phase space: Using 2 equivalences between channels.
| Phase space: wood
Warning: No cuts have been defined.
| OpenMP: Using 8 threads
| Starting integration for process 'eemm'
| Integrate: iterations = 3:10000
| Integrator: 2 chains, 2 channels, 2 dimensions
| Integrator: Using VAMP channel equivalences
| Integrator: 10000 initial calls, 20 bins, stratified = T
| Integrator: VAMP
|=============================================================================|
| It Calls Integral[fb] Error[fb] Err[%] Acc Eff[%] Chi2 N[It] |
|=============================================================================|
1 9216 4.2833237E+02 7.14E-02 0.02 0.02* 40.29
2 9216 4.2829071E+02 7.08E-02 0.02 0.02* 40.29
3 9216 4.2838304E+02 7.04E-02 0.02 0.02* 40.29
|-----------------------------------------------------------------------------|
3 27648 4.2833558E+02 4.09E-02 0.01 0.02 40.29 0.43 3
|=============================================================================|
| Time estimate for generating 10000 events: 0d:00h:00m:04s
| Creating integration history display eemm-history.ps and eemm-history.pdf
| Starting simulation for process 'eemm'
| Simulate: using integration grids from file 'eemm_m1.vg'
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 29913
| OpenMP: Using 8 threads
| Simulation: requested number of events = 0
| corr. to luminosity [fb-1] = 0.0000E+00
| Events: writing to raw file 'eemm.evx'
| Events: generating 0 unweighted, unpolarized events ...
| Events: event normalization mode '1'
| ... event sample complete.
| Events: closing raw file 'eemm.evx'
| There were no errors and 1 warning(s).
| WHIZARD run finished.
|=============================================================================|
\end{verbatim}
\end{footnotesize}
So, \whizard\ tells you that it has entered simulation mode, but besides
this, it has not done anything. The next step is that you have to
demand event generation -- there are two ways to do this: you could
either specify a certain number, say 42, of events you want to have
generated by \whizard, or you could provide a number for an integrated
luminosity of some experiment. (Note, that if you choose to take both
options, \whizard\ will take the one which gives the larger event
sample. This, of course, depends on the given process(es) -- as well
as cuts -- and its corresponding cross section(s).) The first of these
options is set with the command: \ttt{n\_events = <number>}, the
second with \ttt{luminosity = <number> <opt. unit>}.
Another important point already stated several times in the manual is
that \whizard\ follows the commands in the steering \sindarin\ file in a
chronological order. Hence, a given number of events or luminosity
{\em after} a \ttt{simulate} command will be ignored -- or are
relevant only for any \ttt{simulate} command potentially following
further down in the \sindarin\ file. So, in our case, try:
\begin{verbatim}
n_events = 500
luminosity = 10
simulate (eemm)
\end{verbatim}
Per default, numbers for integrated luminosity are understood as
inverse femtobarn. So, for the cross section above this would
correspond to 4283 events, clearly superseding the demand for 500
events. After reducing the luminosity number from ten to one inverse
femtobarn, 500 is the larger number of events taken by \whizard\ for
event generation. Now \whizard\ tells you:
\begin{verbatim}
| Simulation: requested number of events = 500
| corr. to luminosity [fb-1] = 1.1673E+00
| Events: reading from raw file 'eemm.evx'
| Events: reading 500 unweighted, unpolarized events ...
| Events: event normalization mode '1'
| ... event file terminates after 0 events.
| Events: appending to raw file 'eemm.evx'
| Generating remaining 500 events ...
| ... event sample complete.
| Events: closing raw file 'eemm.evx'
\end{verbatim}
I.e., it evaluates the luminosity to which the sample of 500 events
would correspond to, which is now, of course, bigger than the $1
\fb^{-1}$ explicitly given for the luminosity. Furthermore, you can
read off that a file \ttt{whizard.evx} has been generated, containing
the demanded 500 events. (It was there before containing zero events,
because to \ttt{n\_events} or \ttt{luminosity} value had been
set. \whizard\ then tried to get the events first from file before
generating new ones). Files with the suffix \ttt{.evx} are binary
format event files, using a machine-dependent \whizard-specific
event file format. Before we list the event formats supported by
\whizard, the next two sections will tell you more about unweighted and
weighted events as well as different possibilities to normalize events
in \whizard.
As already explained for the libraries, as well as the phase space and
grid files in Chap.~\ref{chap:sindarin}, \whizard\ is trying to re-use
as much information as possible. This is of course also true for the
event files. There are special MD5 check sums testing the integrity
and compatibility of the event files. If you demand for a process for
which an event file already exists (as in the example above, though it
was empty) equally many or less events than generated before,
\whizard\ will not generate again but re-use the existing events (as
already explained, the events are stored in a \whizard-own
binary event format, i.e. in a so-called \ttt{.evx} file. If you
suppress generation of that file, as will be described in subsection
\ref{sec:eventformats} then \whizard\ has to generate events all the
time). From version v2.2.0 of \whizard\ on, the program is also able
to read in event from different event formats. However, most event
formats do not contain as many information as \whizard's internal
format, and a complete reconstruction of the events might not be
possible. Re-using event files is very practical for doing several
different analyses with the same data, especially if there are many
and big data samples. Consider
the case, there is an event file with 200 events, and you now ask
\whizard\ to generate 300 events, then it will re-use the 200 events
(if MD5 check sums are OK!), generate the remaining 100 events and
append them to the existing file. If the user for some reason,
however, wants to regenerate events (i.e. ignoring possibly existing
events), there is the command option \ttt{whizard --rebuild-events}.
%%%%%%%%%
\section{Unweighted and weighted events}
\whizard\ is able to generate unweighted events, i.e. events that are
distributed uniformly and each contribute with the same event weight
to the whole sample. This is done by mapping out the phase space of
the process under consideration according to its different phase space
channels (which each get their own weights), and then unweighting the
sample of weighted events. Only a sample of unweighted events could in
principle be compared to a real data sample from some experiment. The
seventh column in the \whizard\ iteration/adaptation procedure tells you
about the efficiency of the grids, i.e. how well the phase space is
mapped to a flat function. The better this is achieved, the higher the
efficiency becomes, and the closer the weights of the different phase
space channels are to uniformity. This means, for higher efficiency
less weighted events ("calls") are needed to generate a single
unweighted event. An efficiency of 10 \% means that ten weighted
events are needed to generate one single unweighted event. After the
integration is done, \whizard\ uses the duration of calls during the
adaptation to estimate a time interval needed to generate 10,000
unweighted events. The ability of the adaptive multi-channel Monte
Carlo decreases with the number of integrations, i.e. with the number
of final state particles. Adding more and more final state particles
in general also increases the complexity of phase space, especially
its singularity structure. For a $2 \to 2$ process the efficiency is
roughly of the order of several tens of per cent. As a rule of thumb,
one can say that with every additional pair of final state particle
the average efficiency one can achieve decreases by a factor of five
to ten.
The default of \whizard\ is to generate {\em unweighted} events. One can
use the logical variable \ttt{?unweighted = false} to disable
unweighting and generate weighted events. (The command
\ttt{?unweighted = true} is a tautology, because \ttt{true} is the
default for this variable.) Note that again this command has to appear
{\em before} the corresponding \ttt{simulate} command, otherwise it will
be ignored or effective only for any \ttt{simulate} command appearing
later in the \sindarin\ file.
In the unweighted procedure, \whizard\ is keeping track of the highest
weight that has been appeared during the adaptation, and the
efficiency for the unweighting has been estimated from the average
value of the sampling function compared to the maximum value. In
principle, during event generation no events should be generated whose
sampling function value exceeds the maximum function value encountered
during the grid adaptation. Sometimes, however, there are numerical
fluctuations and such events are happening. They are called {\em
excess events}. \whizard\ does keep track of these excess events
during event generation and will report about them, e.g.:
\begin{code}
Warning: Encountered events with excess weight: 9 events ( 0.090 %)
| Maximum excess weight = 6.083E-01
| Average excess weight = 2.112E-04
\end{code}
Whenever in an event generation excess events appear, this shows that
the adaptation of the sampling function has not been perfect. When the
number of excess weights is a finite number of percent, you should
inspect the phase-space setup and try to improve its settings to get a
better adaptation.
Generating \emph{weighted} events is, of course, much faster if the
same number of events is requested. Each event carries a weight
factor which is taken into account for any internal analysis
(histograms), and written to file if an external file format has been
selected. The file format must support event weights.
In a weighted event sample, there is typically a fraction of events
which effectively have weight zero, namely those that have been
created by the phase-space sampler but do not pass the requested
cuts. In the default setup, those events are silently dropped, such
that the events written to file or available for analysis all have
nonzero weight. However, dropping such events affects the overall
normalization. If this has happened, the program will issue a warning
of the form
\begin{code}
| Dropped events (weight zero) = 1142 (total 2142)
Warning: All event weights must be rescaled by f = 4.66853408E-01
\end{code}
This factor has to be applied by hand to any external event files (and
to internally generated histograms). The program cannot include the
factor in the event records, because it is known only after all events
have been generated. To avoid this problem, there is the logical flag
\ttt{?keep\_failed\_events} which tells \whizard\ not to drop events with
weight zero. The normalization will be correct, but the event sample
will include invalid events which have to be vetoed by their zero
weight, before any operations on the event record are performed.
%%%%%%%%%
\section{Choice on event normalizations}
There are basically four different choices to normalize event weights
($\braket{\ldots}$ denotes the average):
\begin{enumerate}
\item $\braket{w_i} = 1$, \qquad\qquad $\Braket{\sum_i w_i} = N$
\item $\braket{w_i} = \sigma$, \qquad\qquad $\Braket{\sum_i w_i} = N
\times \sigma$
\item $\braket{w_i} = 1/N$, \quad\qquad $\Braket{\sum_i w_i} = 1$
\item $\braket{w_i} = \sigma/N$, \quad\qquad $\Braket{\sum_i w_i} = \sigma$
\end{enumerate}
So the four options are to have the average weight equal to unity, to
the cross section of the corresponding process, to one over the number
of events, or the cross section over the event calls. In these four
cases, the event weights sum up to the event number, the event number
times the cross section, to unity, and to the cross section,
respectively. Note that neither of these really guarantees that all
event weights individually lie in the interval $0 \leq w_i \leq 1$.
The user can steer the normalization of events by using in \sindarin\
input files the string variable \ttt{\$sample\_normalization}. The default is
\ttt{\$sample\_normalization = "auto"}, which uses option 1 for
unweighted and 2 for weighted events, respectively. Note that this is
also what the Les Houches Event Format (LHEF) demands for both types
of events. This is \whizard's preferred mode, also for the reason, that
event normalizations are independent from the number of events. Hence,
event samples can be cut or expanded without further need to adjust
the normalization. The unit normalization (option 1) can be switched
on also for weighted events by setting the event normalization
variable equal to \ttt{"1"}. Option 2 can be demanded
by setting \ttt{\$sample\_normalization = "sigma"}. Options 3 and 4 can
be set by \ttt{"1/n"} and \ttt{"sigma/n"}, respectively. \whizard\
accepts small and capital letters for these expressions.
In the following section we show some examples when discussing the
different event formats available in \whizard.
%%%%%%%%%
\section{Event selection}
The \ttt{selection} expression (cf.\ Sec.~\ref{subsec:analysis})
reduces the event sample during generation or rescanning, selecting
only events for which the expression evaluates to \ttt{true}. Apart
from internal analysis, the selection also applies to writing external
files. For instance, the following code generates a $e^+e^-\to
W^+W^-$ sample with longitudinally polarized $W$ bosons only:
\begin{footnotesize}
\begin{verbatim}
process ww = "e+", "e-" => "W-", "W+"
polarized "W+"
polarized "W-"
?polarized_events = true
sqrts = 500
selection = all Hel == 0 ["W+":"W-"]
simulate (ww) { n_events = 1000 }
\end{verbatim}
\end{footnotesize}
The number of events that end up in the sample on file is equal to the
number of events with longitudinally polarized $W$s in the generated
sample, so the file will contain less than 1000 events.
%%%%%%%%%
\section{Supported event formats}
\label{sec:eventformats}
Event formats can either be distinguished whether they are plain
text (i.e. ASCII) formats or binary formats. Besides this, one can
classify event formats according to whether they are natively
supported by \whizard\ or need some external program or library to be
linked. Table~\ref{tab:eventformats} gives a complete list of all
event formats available in \whizard. The second column shows whether
these are ASCII or binary formats, the third column contains brief
remarks about the corresponding format, while the last column tells
whether external programs or libraries are needed (which is the case
only for the HepMC formats).
\begin{table}
\begin{center}
\begin{tabular}{|l||l|l|r|}\hline
Format & Type & remark & ext. \\\hline
ascii & ASCII & \whizard\ verbose format & no
\\
Athena & ASCII & variant of HEPEVT & no
\\
debug & ASCII & most verbose \whizard\ format & no
\\
evx & binary & \whizard's home-brew & no
\\
HepMC & ASCII & HepMC format & yes
\\
HEPEVT & ASCII & \whizard~1 style & no
\\
LCIO & ASCII & LCIO format & yes
\\
LHA & ASCII & \whizard~1/old Les Houches style &no
\\
LHEF & ASCII & Les Houches accord compliant & no
\\
long & ASCII & variant of HEPEVT & no
\\
mokka & ASCII & variant of HEPEVT & no
\\
short & ASCII & variant of HEPEVT & no
\\
StdHEP (HEPEVT) & binary & based on HEPEVT common block & no
\\
StdHEP (HEPRUP/EUP) & binary & based on HEPRUP/EUP common block
& no \\
Weight stream & ASCII & just weights & no \\
\hline
\end{tabular}
\end{center}
\caption{\label{tab:eventformats}
Event formats supported by \whizard, classified according to
ASCII/binary formats and whether an external program or library is
needed to generate a file of this format. For both the HEPEVT and
the LHA format there is a more verbose variant.
}
\end{table}
The "\ttt{.evx}'' is \whizard's native binary event format. If you
demand event generation and do not specify anything further, \whizard\
will write out its events exclusively in this binary format. So in the
examples discussed in the previous chapters (where we omitted all
details about event formats), in all cases this and only this internal
binary format has been generated. The generation of this raw format
can be suppressed (e.g. if you want to have only one specific event
file type) by setting the variable \verb|?write_raw = false|. However,
if the raw event file is not present, \whizard\ is not able to re-use
existing events (e.g. from an ASCII file) and will regenerate events
for a given process. Note that from version v2.2.0 of \whizard\ on,
the program is able to (partially) reconstruct complete events also
from other formats than its internal format (e.g. LHEF), but this is
still under construction and not yet complete.
Other event formats can be written out by setting the variable
\ttt{sample\_format = <format>}, where \ttt{<format>} can be any of
the following supported variables:
\begin{itemize}
\item \ttt{ascii}: a quite verbose ASCII format which contains lots of
information (an example is shown in the appendix). \newline
Standard suffix: \ttt{.evt}
\item \ttt{debug}: an even more verbose ASCII format intended for
debugging which prints out also information about the internal data
structures \newline
Standard suffix: \ttt{.debug}
\item \ttt{hepevt}: ASCII format that writes out a specific
incarnation of the HEPEVT common block (\whizard~1
back-compatibility) \newline
Standard suffix: \ttt{.hepevt}
\item \ttt{hepevt\_verb}: more verbose version of \ttt{hepevt} (\whizard~1
back-compatibility) \newline
Standard suffix: \ttt{.hepevt.verb}
\item \ttt{short}: abbreviated variant of the previous HEPEVT (\whizard\
1 back-compatibility) \newline
Standard suffix: \ttt{.short.evt}
\item \ttt{long}: HEPEVT variant that contains a little bit more
information than the short format but less than HEPEVT (\whizard\
1 back-compatibility) \newline
Standard suffix: \ttt{.long.evt}
\item \ttt{athena}: HEPEVT variant suitable for read-out in the ATLAS
ATHENA software environment (\whizard\
1 back-compatibility) \newline
Standard suffix: \ttt{.athena.evt}
\item \ttt{mokka}: HEPEVT variant suitable for read-out in the MOKKA
ILC software environment \newline
Standard suffix: \ttt{.mokka.evt}
\item \ttt{lcio}: LCIO ASCII format (only available if LCIO is
installed and correctly linked) \newline
Standard suffix: \ttt{.lcio}
\item \ttt{lha}: Implementation of the Les Houches Accord as it was in
the old MadEvent and \whizard~1 \newline
Standard suffix: \ttt{.lha}
\item \ttt{lha\_verb}: more verbose version of \ttt{lha} \newline
Standard suffix: \ttt{.lha.verb}
\item \ttt{lhef}: Formatted Les Houches Accord implementation that
contains the XML headers \newline
Standard suffix: \ttt{.lhe}
\item \ttt{hepmc}: HepMC ASCII format (only available if HepMC is
installed and correctly linked) \newline
Standard suffix: \ttt{.hepmc}
\item \ttt{stdhep}: StdHEP binary format based on the HEPEVT common
block
\newline
Standard suffix: \ttt{.hep}
\item \ttt{stdhep\_up}: StdHEP binary format based on the HEPRUP/HEPEUP
common blocks
\newline
Standard suffix: \ttt{.up.hep}
\item \ttt{stdhep\_ev4}: StdHEP binary format based on the HEPEVT/HEPEV4
common blocks
\newline
Standard suffix: \ttt{.ev4.hep}
\item \ttt{weight\_stream}: Format that prints out only the event
weight (and maybe alternative ones) \newline
Standard suffix: \ttt{.weight.dat}
\end{itemize}
Of course, the variable \ttt{sample\_format} can contain more than one
of the above identifiers, in which case more than one different event
file format is generated. The list above also shows the standard
suffixes for these event formats (remember, that the native binary
format of \whizard\ does have the suffix \ttt{.evx}). (The suffix of
the different event formats can even be changed by the user by setting
the corresponding variable \ttt{\$extension\_lhef = "foo"} or
\ttt{\$extension\_ascii\_short = "bread"}. The dot is automatically
included.)
The name of the corresponding event sample is taken to be the string
of the name of the first process in the \ttt{simulate}
statement. Remember, that conventionally the events for all processes
in one \ttt{simulate} statement will be written into one single event
file. So \ttt{simulate (proc1, proc2)} will write events for the two
processes \ttt{proc1} and \ttt{proc2} into one single event file with
name \ttt{proc1.evx}. The name can be changed by the user with the
command \ttt{\$sample = "<name>"}.
The commands \ttt{\$sample} and \ttt{sample\_format} are both accepted
as optional arguments of a \ttt{simulate} command, so e.g.
\ttt{simulate (proc) \{ \$sample = "foo" sample\_format = hepmc \}}
generates an event sample in the HepMC format for the process
\ttt{proc} in the file \ttt{foo.hepmc}.
Examples for event formats, for specifications of the event formats correspond
the different accords and publications~\footnote{Some event formats, based on
the \ttt{HEPEVT} or \ttt{HEPEUP} common blocks, use fixed-form ASCII output
with a two-digit exponent for real numbers. There are rare cases (mainly,
ISR photons) where the event record can contain numbers with absolute value
less than $10^{-99}$. Since those numbers are not representable in that
format, \whizard\ will set all non-zero numbers below that value to $\pm
10^{-99}$, when filling either common block. Obviously, such values are
physically irrelevant, but in the output they are representable and
distinguishable from zero.}:
\paragraph{HEPEVT:}
The HEPEVT is an ASCII event format that does not contain an event
file header. There is a one-line header for each single event,
containing four entries. The number of particles in the event
(\ttt{ISTHEP}), which is four for a fictitious example process $hh\to
hh$, but could be larger if e.g. beam remnants are demanded to be included in the
event. The second entry and third entry are the number of outgoing
particles and beam remnants, respectively. The event weight is the
last entry. For each particle in the event there are three lines:
the first one is the status according to the HEPEVT format,
\ttt{ISTHEP}, the second one the PDG code, \ttt{IDHEP}, then there are
the one or two possible mother particle, \ttt{JMOHEP}, the first and
last possible daughter particle, \ttt{JDAHEP}, and the polarization.
The second line contains the three momentum components, $p_x$, $p_y$,
$p_z$, the particle energy $E$, and its mass, $m$.
The last line contains the position of the vertex in the event
reconstruction.
\begin{scriptsize}
\begin{verbatim}
4 2 0 3.0574068604E+08
2 25 0 0 3 4 0
0.0000000000E+00 0.0000000000E+00 4.8412291828E+02 5.0000000000E+02 1.2500000000E+02
0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00
2 25 0 0 3 4 0
0.0000000000E+00 0.0000000000E+00 -4.8412291828E+02 5.0000000000E+02 1.2500000000E+02
0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00
1 25 1 2 0 0 0
-1.4960220911E+02 -4.6042825611E+02 0.0000000000E+00 5.0000000000E+02 1.2500000000E+02
0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00
1 25 1 2 0 0 0
1.4960220911E+02 4.6042825611E+02 0.0000000000E+00 5.0000000000E+02 1.2500000000E+02
0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00
\end{verbatim}
\end{scriptsize}
\paragraph{ASCII SHORT:}
This is basically the same as the HEPEVT standard, but very much
abbreviated. The header line for each event is identical, but the first
line per particle does only contain the PDG and the polarization,
while the vertex information line is omitted.
\begin{scriptsize}
\begin{verbatim}
4 2 0 3.0574068604E+08
25 0
0.0000000000E+00 0.0000000000E+00 4.8412291828E+02 5.0000000000E+02 1.2500000000E+02
25 0
0.0000000000E+00 0.0000000000E+00 -4.8412291828E+02 5.0000000000E+02 1.2500000000E+02
25 0
-1.4960220911E+02 -4.6042825611E+02 0.0000000000E+00 5.0000000000E+02 1.2500000000E+02
25 0
1.4960220911E+02 4.6042825611E+02 0.0000000000E+00 5.0000000000E+02 1.2500000000E+02
\end{verbatim}
\end{scriptsize}
\paragraph{ASCII LONG:}
Identical to the ASCII short format, but after each event there is a
line containg two values: the value of the sample function to be
integrated over phase space, so basically the squared matrix element
including all normalization factors, flux factor, structure functions
etc.
\begin{scriptsize}
\begin{verbatim}
4 2 0 3.0574068604E+08
25 0
0.0000000000E+00 0.0000000000E+00 4.8412291828E+02 5.0000000000E+02 1.2500000000E+02
25 0
0.0000000000E+00 0.0000000000E+00 -4.8412291828E+02 5.0000000000E+02 1.2500000000E+02
25 0
-1.4960220911E+02 -4.6042825611E+02 0.0000000000E+00 5.0000000000E+02 1.2500000000E+02
25 0
1.4960220911E+02 4.6042825611E+02 0.0000000000E+00 5.0000000000E+02 1.2500000000E+02
1.0000000000E+00 1.0000000000E+00
\end{verbatim}
\end{scriptsize}
\paragraph{ATHENA:}
Quite similar to the HEPEVT ASCII format. The header line, however,
does contain only two numbers: an event counter, and the number of
particles in the event. The first line for each particle lacks the
polarization information (irrelevant for the ATHENA environment), but
has as leading entry an ordering number counting the particles in the
event. The vertex information line has only the four relevant position
entries.
\begin{scriptsize}
\begin{verbatim}
0 4
1 2 25 0 0 3 4
0.0000000000E+00 0.0000000000E+00 4.8412291828E+02 5.0000000000E+02 1.2500000000E+02
0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00
2 2 25 0 0 3 4
0.0000000000E+00 0.0000000000E+00 -4.8412291828E+02 5.0000000000E+02 1.2500000000E+02
0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00
3 1 25 1 2 0 0
-1.4960220911E+02 -4.6042825611E+02 0.0000000000E+00 5.0000000000E+02 1.2500000000E+02
0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00
4 1 25 1 2 0 0
1.4960220911E+02 4.6042825611E+02 0.0000000000E+00 5.0000000000E+02 1.2500000000E+02
0.0000000000E+00 0.0000000000E+00 0.0000000000E+00 0.0000000000E+00
\end{verbatim}
\end{scriptsize}
\paragraph{MOKKA:}
Quite similar to the ASCII short format, but the event entries are the
particle status, the PDG code, the first and last daughter, the
three spatial components of the momentum, as well as the mass.
\begin{scriptsize}
\begin{verbatim}
4 2 0 3.0574068604E+08
2 25 3 4 0.0000000000E+00 0.0000000000E+00 4.8412291828E+02 1.2500000000E+02
2 25 3 4 0.0000000000E+00 0.0000000000E+00 -4.8412291828E+02 1.2500000000E+02
1 25 0 0 -1.4960220911E+02 -4.6042825611E+02 0.0000000000E+00 1.2500000000E+02
1 25 0 0 1.4960220911E+02 4.6042825611E+02 0.0000000000E+00 1.2500000000E+02
\end{verbatim}
\end{scriptsize}
\paragraph{LHA:}
This is the implementation of the Les Houches Accord, as it was used
in \whizard\ 1 and the old MadEvent. There is a first line containing
six entries: 1. the number of particles in the event, \ttt{NUP},
2. the subprocess identification index, \ttt{IDPRUP}, 3. the event
weight, \ttt{XWGTUP}, 4. the scale of the process, \ttt{SCALUP},
5. the value or status of $\alpha_{QED}$, \ttt{AQEDUP}, 6. the value
for $\alpha_s$, \ttt{AQCDUP}. The next seven lines contain as many
entries as there are particles in the event: the first one has the PDG
codes, \ttt{IDUP}, the next two the first and second mother of the particles,
\ttt{MOTHUP}, the fourth and fifth line the two color indices,
\ttt{ICOLUP}, the next one the status of the particle, \ttt{ISTUP},
and the last line the polarization information, \ttt{ISPINUP}.
At the end of the event there are as lines for each particles with the
counter in the event and the four-vector of the particle. For more
information on this event format confer~\cite{LesHouches}.
\begin{scriptsize}
\begin{verbatim}
25 25 5.0000000000E+02 5.0000000000E+02 -1 -1 -1 -1 3 1
1.0000000000E-01 1.0000000000E-03 1.0000000000E+00 42
4 1 3.0574068604E+08 1.000000E+03 -1.000000E+00 -1.000000E+00
25 25 25 25
0 0 1 1
0 0 2 2
0 0 0 0
0 0 0 0
-1 -1 1 1
9 9 9 9
1 5.0000000000E+02 0.0000000000E+00 0.0000000000E+00 4.8412291828E+02
2 5.0000000000E+02 0.0000000000E+00 0.0000000000E+00 -4.8412291828E+02
3 5.0000000000E+02 -1.4960220911E+02 -4.6042825611E+02 0.0000000000E+00
4 5.0000000000E+02 1.4960220911E+02 4.6042825611E+02 0.0000000000E+00
\end{verbatim}
\end{scriptsize}
\paragraph{LHEF:}
This is the modern version of the Les Houches accord event format
(LHEF), for the details confer the corresponding publication~\cite{LHEF}.
\begin{scriptsize}
\begin{verbatim}
<LesHouchesEvents version="1.0">
<header>
<generator_name>WHIZARD</generator_name>
<generator_version>3.0.1</generator_version>
</header>
<init>
25 25 5.0000000000E+02 5.0000000000E+02 -1 -1 -1 -1 3 1
1.0000000000E-01 1.0000000000E-03 1.0000000000E+00 42
</init>
<event>
4 42 3.0574068604E+08 1.0000000000E+03 -1.0000000000E+00 -1.0000000000E+00
25 -1 0 0 0 0 0.0000000000E+00 0.0000000000E+00 4.8412291828E+02 5.0000000000E+02 1.2500000000E+02 0.0000000000E+00 9.0000000000E+00
25 -1 0 0 0 0 0.0000000000E+00 0.0000000000E+00 -4.8412291828E+02 5.0000000000E+02 1.2500000000E+02 0.0000000000E+00 9.0000000000E+00
25 1 1 2 0 0 -1.4960220911E+02 -4.6042825611E+02 0.0000000000E+00 5.0000000000E+02 1.2500000000E+02 0.0000000000E+00 9.0000000000E+00
25 1 1 2 0 0 1.4960220911E+02 4.6042825611E+02 0.0000000000E+00 5.0000000000E+02 1.2500000000E+02 0.0000000000E+00 9.0000000000E+00
</event>
</LesHouchesEvents>
\end{verbatim}
\end{scriptsize}
Note that for the LHEF format, there are different versions according
to the different stages of agreement. They can be addressed from
within the \sindarin\ file by setting the string variable
\ttt{\$lhef\_version} to one of (at the moment) three values:
\ttt{"1.0"}, \ttt{"2.0"}, or \ttt{"3.0"}. The examples above
corresponds (as is indicated in the header) to the version \ttt{"1.0"}
of the LHEF format. Additional information in form of alternative
squared matrix elements or event weights in the event are the most
prominent features of the other two more advanced versions. For more
details confer the literature.
\vspace{.5cm}
Sample files for the default ASCII format as well as for the debug
event format are shown in the appendix.
%%%%%%%%%
\section[Interfaces to Parton Showers, Matching and
Hadronization]{Interfaces to Parton Showers, Matching\\and
Hadronization}
This section describes the interfaces to the internal parton shower as
well as the parton shower and hadronization routines from
\pythia. Moreover, our implementation of the MLM matching making use
of the parton showers is described. Sample \sindarin\ files are
located in the \ttt{share/examples} directory.
All input files come in two versions, one using the internal shower,
ending in \ttt{W.sin}, and one using \pythia's shower, ending in
\ttt{P.sin}. Thus we state all file names as ending with \ttt{X.sin},
where \ttt{X} has to be replaced by either \ttt{W} or \ttt{P}.
The input files include \ttt{EENoMatchingX.sin} and
\ttt{DrellYanNoMatchingX.sin} for $e^+ e^- \to hadrons$ and $p\bar{p}
\to Z$ without matching. The corresponding \sindarin\ files with
matching enabled are \ttt{EEMatching2X.sin} to \ttt{EEMatching5X.sin}
for $e^+ e^- \to hadrons$ with a different number of partons included
in the matrix element and \ttt{DrallYanMatchingX.sin} for Drell-Yan
with one matched emission.
\subsection{Parton Showers and Hadronization}
From version 2.1 onwards, \whizard\ contains an implementation of an
analytic parton shower as presented in \cite{Kilian:2011ka}, providing
the opportunity to perform the parton shower from whithin
\whizard. Moreover, an interface to \pythia\ is included, which can be
used to delegate the parton shower to \pythia. The same interface can
be used to hadronize events using the generated events using \pythia's
hadronization routines. Note that by \pythia's default, when
performing initial-state radiation multiple interactions are included
and when performing the hadronization hadronic decays are included. If
required, these additional steps have to be switched off using the
corresponding arguments for \pythia's \ttt{PYGIVE} routine via the
\ttt{\$ps\_PYTHIA\_PYGIVE} string.
Note that from version 2.2.4 on the earlier flag
\ttt{--enable-shower} flag has been abandoned, and there is only a
flag to either compile or not compile the interally attached
\pythia\ttt{6} package (\ttt{--enable-pythia6}) last release of
the \fortran\ \pythia, v6.427) as well as the interface. It can be
invoked by the following \sindarin\ keywords:\\[2ex]
%
\centerline{\begin{tabular}{|l|l|}
\hline\ttt{?ps\_fsr\_active = true} & master switch for final-state
parton showers\\\hline
\ttt{?ps\_isr\_active = true} & master switch for initial-state parton
showers\\\hline
\ttt{?ps\_taudec\_active = true} & master switch for $\tau$ decays (at
the moment only via \ttt{TAUOLA}\\\hline
\ttt{?hadronization\_active = true} & master switch to enable
hadronization\\\hline
\ttt{\$shower\_method = "PYTHIA6"} & switch to use \pythiasix's parton
shower instead of \\ &
\whizard's own shower\\\hline
\end{tabular}}\mbox{}
\vspace{4mm}
If either \ttt{?ps\_fsr\_active} or \ttt{?ps\_isr\_active} is set to \verb|true|, the
event will be transferred to the internal shower routines or the \pythia\ data structures,
and the chosen shower steps (initial- and final-state radiation) will be
performed. If hadronization is enabled via the \ttt{?hadronization\_active} switch, \whizard\ will call \pythia's hadronization routine.
The hadron\-ization can be applied to events showered using the internal shower or showered using \pythia's shower routines, as well as unshowered events.
Any necessary transfer of event data to \pythia\ is automatically taken care of within \whizard's shower interface.
The resulting (showered and/or hadronized) event will be transferred back to \whizard,
the former final particles will be marked as intermediate. The
analysis can be applied to a showered and/or hadronized event just
like in the unshowered/unhadronized case. Any event file can be used
and will contain the showered/hadronized event.
Settings for the internal analytic parton shower are set via the following \sindarin\ variables:\\[2ex]
\begin{description}
\item[\ttt{ps\_mass\_cutoff}] The cut-off in virtuality, below
which, partons are assumed to radiate no more. Used for both ISR and
FSR. Given in $\mbox{GeV}$. (Default = 1.0)
\item[\ttt{ps\_fsr\_lambda}] The value for $\Lambda$ used in
calculating the value of the running coupling constant $\alpha_S$
for Final State Radiation. Given in $\mbox{GeV}$. (Default = 0.29)
\item[\ttt{ps\_isr\_lambda}] The value for $\Lambda$ used in
calculating the value of the running coupling constant $\alpha_S$
for Initial State Radiation. Given in $\mbox{GeV}$. (Default = 0.29)
\item[\ttt{ps\_max\_n\_flavors}] Number of quark flavours taken
into account during shower evolution. Meaningful choices are 3 to
include $u,d,s$-quarks, 4 to include $u,d,s,c$-quarks and 5 to
include $u,d,s,c,b$-quarks. (Default = 5)
\item[\ttt{?ps\_isr\_alphas\_running}] Switch to decide between a
constant $\alpha_S$, given by \ttt{ps\_fixed\_alphas}, and a
running $\alpha_S$, calculated using \ttt{ps\_isr\_lambda} for
ISR. (Default = true)
\item[\ttt{?ps\_fsr\_alphas\_running}] Switch to decide between a
constant $\alpha_S$, given by \ttt{ps\_fixed\_alphas}, and a
running $\alpha_S$, calculated using \ttt{ps\_fsr\_lambda} for
FSR. (Default = true)
\item[\ttt{ps\_fixed\_alphas}] Fixed value of $\alpha_S$ for the
parton shower. Used if either one of the variables
\ttt{?ps\_fsr\_alphas\_running}
or \ttt{?ps\_isr\_alphas\_running} are set to
\verb|false|. (Default = 0.0)
\item[\ttt{?ps\_isr\_angular\_ordered}] Switch for angular ordered
ISR. (Default = true )\footnote{The FSR is always simulated with
angular ordering enabled.}
\item[\ttt{ps\_isr\_primordial\_kt\_width}] The width in
$\mbox{GeV}$ of the Gaussian assumed to describe the transverse
momentum of partons inside the proton. Other shapes are not yet
implemented. (Default = 0.0)
\item[\ttt{ps\_isr\_primordial\_kt\_cutoff}] The maximal transverse
momentum in $\mbox{GeV}$ of a parton inside the proton. Used as a
cut-off for the Gaussian. (Default = 5.0)
\item[\ttt{ps\_isr\_z\_cutoff}] Maximal $z$-value in initial state
branchings. (Default = 0.999)
\item[\ttt{ps\_isr\_minenergy}] Minimal energy in $\mbox{GeV}$ of
an emitted timelike or final parton. Note that the energy is not
calculated in the labframe but in the center-of-mas frame of the two
most initial partons resolved so far, so deviations may
occur. (Default = 1.0)
\item[\ttt{ps\_isr\_tscalefactor}] Factor for the starting scale in
the initial state shower evolution. ( Default = 1.0 )
\item[\ttt{?ps\_isr\_only\_onshell\_emitted\_partons}] Switch to
allow only for on-shell emitted partons, thereby rejecting all
possible final state parton showers starting from partons emitted
during the ISR. (Default = false)
\end{description}
Settings for the \pythia\ are transferred using the following
\sindarin\ variables:\\[2ex]
\centerline{\begin{tabular}{|l|l|}
\hline\ttt{?ps\_PYTHIA\_verbose} & if set to false, output from
\pythia\ will be suppressed\\\hline
\ttt{\$ps\_PYTHIA\_PYGIVE} & a string containing settings transferred
to \pythia's \ttt{PYGIVE} subroutine.\\ & The format is explained in
the \pythia\ manual. The limitation to 100 \\ & characters mentioned
there does not apply here, the string is split \\ & appropriately
before being transferred to \pythia.\\\hline
\end{tabular}}\mbox{}
\vspace{4mm}
Note that the included version of \pythia\ uses \lhapdf\ for initial state
radiation whenever this is available, but the PDF set has to be set
manually in that case using the keyword \ttt{ps\_PYTHIA\_PYGIVE}.
\subsection{Parton shower -- Matrix Element Matching}
Along with the inclusion of the parton showers, \whizard\ includes an
implementation of the MLM matching procedure. For a detailed
description of the implemented steps see \cite{Kilian:2011ka}. The
inclusion of MLM matching still demands some manual settings in the
\sindarin\ file. For a given base process and a matching of $N$
additional jets, all processes that can be obtained by attaching up to
$N$ QCD splittings, either a quark emitting a gluon or a gluon
splitting into two quarks ar two gluons, have to be manually specified
as additional processes. These additional processes need to be
included in the \ttt{simulate} statement along with the original
process. The \sindarin\ variable \ttt{mlm\_nmaxMEjets} has to be
set to the maximum number of additional jets $N$. Moreover additional
cuts have to be specified for the additional processes.
\begin{verbatim}
alias quark = u:d:s:c
alias antiq = U:D:S:C
alias j = quark:antiq:g
?mlm_matching = true
mlm_ptmin = 5 GeV
mlm_etamax = 2.5
mlm_Rmin = 1
cuts = all Dist > mlm_Rmin [j, j]
and all Pt > mlm_ptmin [j]
and all abs(Eta) < mlm_etamax [j]
\end{verbatim}
Note that the variables \ttt{mlm\_ptmin}, \ttt{mlm\_etamax} and
\ttt{mlm\_Rmin} are used by the matching routine. Thus, replacing the
variables in the \ttt{cut} expression and omitting the assignment
would destroy the matching procedure.
The complete list of variables introduced to steer the matching procedure is as follows:
\begin{description}
\item[\ttt{?mlm\_matching\_active}] Master switch to enable MLM
matching. (Default = false)
\item[\ttt{mlm\_ptmin}] Minimal transverse momentum, also used in
the definition of a jet
\item[\ttt{mlm\_etamax}] Maximal absolute value of pseudorapidity
$\eta$, also used in defining a jet
\item[\ttt{mlm\_Rmin}] Minimal $\eta-\phi$ distance $R_{min}$
\item[\ttt{mlm\_nmaxMEjets}] Maximum number of jets $N$
\item[\ttt{mlm\_ETclusfactor}] Factor to vary the jet
definition. Should be $\geq 1$ for complete coverage of phase
space. (Default = 1)
\item[\ttt{mlm\_ETclusminE}] Minimal energy in the variation of the
jet definition
\item[\ttt{mlm\_etaclusfactor}] Factor in the variation of the jet
definition. Should be $\leq 1$ for complete coverage of phase
space. (Default = 1)
\item[\ttt{mlm\_Rclusfactor}] Factor in the variation of the jet
definition. Should be $\ge 1$ for complete coverage of phase
space. (Default = 1)
\end{description}
The variation of the jet definition is a tool to asses systematic
uncertainties introduced by the matching procedure (See section 3.1 in
\cite{Kilian:2011ka}).
%%%%%%%%%
\section{Rescanning and recalculating events}
\label{sec:rescan}
In the simplest mode of execution, \whizard\ handles its events at the
point where they are generated. It can apply event transforms such as
decays or shower (see above), it can analyze the events, calculate and
plot observables, and it can output them to file. However, it is also
possible to apply two different operations to those events in
parallel, or to reconsider and rescan an event sample that has been
previously generated.
We first discuss the possibilities that \ttt{simulate} offers. For
each event, \whizard\ calculates the matrix element for the hard
interaction, supplements this by Jacobian and phase-space factors in
order to obtain the event weight, optionally applies a rejection step
in order to gather uniformly weighted events, and applies the
cuts and analysis setup. We may ask about the event matrix element or
weight, or the analysis result, that we would have obtained for a
different setting. To this end, there is an \ttt{alt\_setup} option.
This option allows us to recalculate, event by event, the matrix
element, weight, or analysis contribution with a different parameter
set but identical kinematics. For instance, we may evaluate a
distribution for both zero and non-zero anomalous coupling \ttt{fw}
and enter some observable in separate histograms:
\begin{footnotesize}
\begin{verbatim}
simulate (some_proc) {
fw = 0
analysis = record hist1 (eval Pt [H])
alt_setup = {
fw = 0.01
analysis = record hist2 (eval Pt [H])
}
}
\end{verbatim}
\end{footnotesize}
In fact, the \ttt{alt\_setup} object is not restricted to a single
code block (enclosed in curly braces) but can take a list of those,
\begin{footnotesize}
\begin{verbatim}
alt_setup = { fw = 0.01 }, { fw = 0.02 }, ...
\end{verbatim}
\end{footnotesize}
Each block provides the environment for a separate evaluation of the
event data. The generation of these events, i.e., their kinematics,
is still steered by the primary environment.
The \ttt{alt\_setup} blocks may modify various settings that affect the
evaluation of an event, including physical parameters, PDF choice,
cuts and analysis, output format, etc. This must not (i.e., cannot)
affect the kinematics of an event, so don't modify particle masses.
When applying cuts, they can only reduce the generated event sample,
so they apply on top of the primary cuts for the simulation.
Alternatively, it is possible to \ttt{rescan} a sample that has been
generated by a previous \ttt{simulate} command:
\begin{footnotesize}
\begin{verbatim}
simulate (some_proc) { $sample = "my_events"
analysis = record hist1 (eval Pt [H])
}
?update_sqme = true
?update_weight = true
rescan "my_events" (some_proc) {
fw = 0.01
analysis = record hist2 (eval Pt [H])
}
rescan "my_events" (some_proc) {
fw = 0.05
analysis = record hist3 (eval Pt [H])
}
\end{verbatim}
\end{footnotesize}
In more complicated situation, rescanning is more transparent and
offers greater flexibility than doing all operations at the very point
of event generation.
Combining these features with the \ttt{scan} looping construct, we
already cover a considerable range of applications. (There are
limitations due to the fact that \sindarin\ doesn't provide array
objects, yet.) Note that the \ttt{rescan} construct also allows
for an \ttt{alt\_setup} option.
You may generate a new sample by rescanning, for which you may choose
any output format:
\begin{footnotesize}
\begin{verbatim}
rescan "my_events" (some_proc) {
selection = all Pt > 100 GeV [H]
$sample = "new_events"
sample_format = lhef
}
\end{verbatim}
\end{footnotesize}
The event sample that you rescan need not be an internal raw \whizard\
file, as above. You may rescan a LHEF file,
\begin{footnotesize}
\begin{verbatim}
rescan "lhef_events" (proc) {
$rescan_input_format = "lhef"
}
\end{verbatim}
\end{footnotesize}
This file may have any origin, not necessarily from \whizard. To
understand such an external file, \whizard\ must be able to
reconstruct the hard process and match it to a process with a known
name (e.g., \ttt{proc}), that has been defined in the \sindarin\ script
previously.
Within its limits, \whizard\ can thus be used for translating an event
sample from one format to another format.
There are three important switches that control the rescanning
behavior. They can be set or unset independently.
\begin{itemize}
\item \ttt{?update\_sqme} (default: false).
If true, \whizard\ will recalculate the hard matrix element for each
event. When applying an analysis, the recalculated squared matrix
element (averaged and summed over quantum numbers as usual) is
available as the variable \ttt{sqme\_prc}. This may be related to
\ttt{sqme\_ref}, the corresponding
value in the event file, if available. (For the \ttt{alt\_env}
option, this switch is implied.)
\item \ttt{?update\_weight} (default: false).
If true, \whizard\ will recalculate the event weight according to
the current environment and apply this to the event. In particular,
the user may apply a \ttt{reweight} expression. In an
analysis, the new weight value is available as \ttt{weight\_prc}, to
be related
to \ttt{weight\_ref} from the sample. The updated weight will be
applied for histograms and averages. An unweighted event sample
will thus be transformed into a weighted event sample. (This switch
is also implied for the \ttt{alt\_env} option.)
\item \ttt{?update\_event} (default: false).
If true, \whizard\ will generate a new decay chain etc., if
applicable. That is, it reuses just the particles in the hard
process. Otherwise, the complete event is kept as it is written to
file.
\end{itemize}
For these options to make sense, \whizard\ must have access to a full
process object, so the \sindarin\ script must contain not just a
definition but also a \ttt{compile} command for the matrix elements in
question.
If an event file (other than raw format) contains several processes as
a mixture, they must be identifiable by a numeric ID. \whizard\ will
recognize the processes if their respective \sindarin\ definitions
contain appropriate \ttt{process\_num\_id} options, such as
\begin{footnotesize}
\begin{verbatim}
process foo = u, ubar => d, dbar { process_num_id = 42 }
\end{verbatim}
\end{footnotesize}
Certain event-file formats, such as LHEF, support alternative
matrix-element values or weights. \whizard\ can thus write both
original and
recalculated matrix-element and weight values.
Other formats support only a single
event weight, so the \ttt{?update\_weight} option is necessary for a
visible effect.
External event files in formats such as LHEF, HepMC, or LCIO, also may
carry information about the value of the strong coupling $\alpha_s$
and the energy scale of each event. This information will also be
provided by \whizard\ when writing external event files. When such an
event file is rescanned, the user has the choice to either user the
$\alpha_s$ value that \whizard\ defines in the current context (or the
method for obtaining an event-specific running $\alpha_s$ value), or
override this for each event by using the value in the event file.
The corresponding parameter is \ttt{?use\_alphas\_from\_file}, which
is false by default. Analogously, the parameter
\ttt{?use\_scale\_from\_file} may be set to override the scale
definition in the current context. Obviously, these settings
influence matrix-element recalculation and therefore require
\ttt{?update\_sqme} to be set in order to become operational.
%%%%%%%%%
\section{Negative weight events}
For usage at NLO refer to Subsection~\ref{ss:fixedorderNLOevents}.
In case, you have some other mechanism to produce events with negative
weights (e.g. with the \ttt{weight = {\em <expr>}} command), keep in
mind that you should activate \ttt{?negative\_weights = true} and
\ttt{unweighted = false}. The generation of unweighted events with
varying sign (also known as events and counter events) is currently not
supported.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Internal Data Visualization}
\label{chap:visualization}
\section{GAMELAN}
The data values and tables that we have introduced in the previous section can
be visualized using built-in features of \whizard. To be precise,
\whizard\ can write \LaTeX\ code which incorporates code in the graphics
language GAMELAN to produce a pretty-printed account of observables,
histograms, and plots.
GAMELAN is a macro package for MetaPost, which is part of the
\TeX/\LaTeX\ family. MetaPost, a derivative of Knuth's MetaFont language for
font design, is usually bundled with the \TeX\ distribution, but might need a
separate switch for installation. The GAMELAN macros are contained in a
subdirectory of the \whizard\ package. Upon installation, they will be
installed in the appropriate directory, including the \ttt{gamelan.sty} driver
for \LaTeX. \whizard\ uses a subset of GAMELAN's graphics macros
directly, but it allows for access to the full package if desired.
An (incomplete) manual for GAMELAN can be found in the \ttt{share/doc}
subdirectory of the \whizard\ system. \whizard\ itself uses a subset of the
GAMELAN capabilities, interfaced by \sindarin\ commands and parameters. They
are described in this chapter.
To process analysis output beyond writing tables to file, the
\ttt{write\_analysis} command described in the previous section should be
replaced by \ttt{compile\_analysis}, with the same syntax:
\begin{quote}
\begin{footnotesize}
\ttt{compile\_analysis (\emph{analysis-tags}) \{ \ttt{\emph{options}} \}}
\end{footnotesize}
\end{quote}
where \ttt{\emph{analysis-tags}}, a comma-separated list of analysis objects,
is optional. If there are no tags, all analysis objects are processed. The
\ttt{\emph{options}} script of local commands is also optional, of course.
This command will perform the following actions:
\begin{enumerate}
\item
It writes a data file in default format, as \ttt{write\_analysis} would do.
The file name is given by \ttt{\$out\_file}, if nonempty. The file must not
be already open, since the command needs a self-contained file, but the name
is otherwise arbitrary. If the value of \ttt{\$out\_file} is empty, the
default file name is \ttt{whizard\_analysis.dat}.
\item
It writes a driver file for the chosen datasets, whose name is derived from
the data file by replacing the file extension of the data file with the
extension \ttt{.tex}. The driver file is a \LaTeX\ source file which
contains embedded GAMELAN code that handles the selected graphics data. In
the \LaTeX\ document, there is a separate section for each contained
dataset. Furthermore, a process-/analysis-specific makefile with the
name \ttt{<process\_name>\_ana.makefile} is created that can be used
to generate postscript or PDF output from the \LaTeX\ source. If the
steering flag \ttt{?analysis\_file\_only} is set to \ttt{true}, then
the \LaTeX\ file and the makefile are only written, but no execution
of the makefile resulting in compilation of the \LaTeX\ code (see
the next item) is invoked.
\item
As mentioned above, if the flag \ttt{?analysis\_file\_only} is set
to \ttt{false} (which is the default), the driver file is processed
by \LaTeX (invoked by calling the makefile with the name
\ttt{<process\_name>\_ana.makefile}), which generates an appropriate
GAMELAN source file with extension \ttt{.mp}. This code is executed
(calling GAMELAN/MetaPost, and again \LaTeX\ for typesetting embedded
labels). There is a second \LaTeX\ pass (automatically done by the
makefile) which collects the results, and finally conversion to
PostScript and PDF formats.
\end{enumerate}
The resulting PostScript or PDF file -- the file name is the name of the data
file with the extension replaced by \ttt{.ps} or \ttt{.pdf}, respectively
-- can be printed or viewed with an appropriate viewer such as \ttt{gv}. The
viewing command is not executed automatically by \whizard.
Note that \LaTeX\ will write further files with extensions \ttt{.log},
\ttt{.aux}, and \ttt{.dvi}, and GAMELAN will produce auxiliary files with
extensions \ttt{.ltp} and \ttt{.mpx}. The log file in particular, could
overwrite \whizard's log file if the basename is identical. Be careful to use
a value for \ttt{\$out\_file} which is not likely to cause name clashes.
\subsection{User-specific changes}
In the case, that the \sindarin\ \ttt{compile\_analysis} command is
invoked and the flag named \ttt{?analysis\_file\_only} is not changed
from its default value \ttt{false}, \whizard\ calls the
process-/analysis-specific makefile triggering the compilation of the
\LaTeX\ code and the GAMELAN plots and histograms. If the user wants
to edit the analysis output, for example changing captions, headlines,
labels, properties of the plots, graphs and histograms using GAMELAN
specials etc., this is possible and the output can be regenerated
using the makefile. The user can also directly invoke the GAMELAN
script, \ttt{whizard-gml}, that is installed in the binary directly
along with the \whizard\ binary and other scripts. Note however, that
the \LaTeX\ environment for the specific style files have to be set by
hand (the command line invocation in the makefile does this
automatically). Those style files are generally written into
\ttt{share/texmf/whizard/} directory. The user can execute the
commands in the same way as denoted in the process-/analysis-specific
makefile by hand.
%%%%%
\section{Histogram Display}
%%%%%
\section{Plot Display}
\section{Graphs}
\label{sec:graphs}
Graphs are an additional type of analysis object. In contrast to histograms
and plots, they do not collect data directly, but they rather act as
containers for graph elements, which are copies of existing histograms and
plots. Their single purpose is to be displayed by the GAMELAN driver.
Graphs are declared by simple assignments such as
\begin{quote}
\begin{footnotesize}
\ttt{graph g1 = hist1}
\\
\ttt{graph g2 = hist2 \& hist3 \& plot1}
\end{footnotesize}
\end{quote}
The first declaration copies a single histogram into the graph, the second one
copies two histograms and a plot. The syntax for collecting analysis objects
uses the \ttt{\&} concatenation operator, analogous to string concatenation.
In the assignment, the rhs must contain only histograms and plots. Further
concatenating previously declared graphs is not supported.
After the graph has been declared, its contents can be written to file
(\ttt{write\_analysis}) or, usually, compiledd by the \LaTeX/GAMELAN driver
via the \ttt{compile\_analysis} command.
The graph elements on the right-hand side of the graph assignment are copied
with their current data content. This implies a well-defined order of
statements: first, histograms and plots are declared, then they are filled via
\ttt{record} commands or functions, and finally they can be collected for
display by graph declarations.
A simple graph declaration without options as above is possible, but usually
there are option which affect the graph display. There are two kinds of
options: graph options and drawing options. Graph options apply to the graph
as a whole (title, labels, etc.) and are placed in braces on the lhs of the
assigment. Drawing options apply to the individual graph elements
representing the contained histograms and plots, and are placed together with
the graph element on the rhs of the assignment. Thus, the complete syntax for
assigning multiple graph elements is
\begin{quote}
\begin{footnotesize}
\ttt{graph \emph{graph-tag} \{ \emph{graph-options} \}}
\\
\ttt{= \emph{graph-element-tag1} \{ \emph{drawing-options1} \}}
\\
\ttt{\& \emph{graph-element-tag2} \{ \emph{drawing-options2} \}}
\\
\ldots
\end{footnotesize}
\end{quote}
This form is recommended, but graph and drawing options can also be set as
global parameters, as usual.
We list the supported graph and drawing options in
Tables~\ref{tab:graph-options} and \ref{tab:drawing-options}, respectively.
\begin{table}
\caption{Graph options. The content of strings of type \LaTeX\ must be
valid \LaTeX\ code (containing typesetting commands such as math mode).
The content of strings of type GAMELAN must be valid GAMELAN code.
If a graph bound is kept \emph{undefined}, the actual graph bound is
determined such as not to crop the graph contents in the selected
direction.}
\label{tab:graph-options}
\begin{center}
\begin{tabular}{|l|l|l|l|}
\hline
Variable & Default & Type & Meaning
\\
\hline\hline
\ttt{\$title} & \ttt{""} & \LaTeX &
Title of the graph = subsection headline
\\
\hline
\ttt{\$description} & \ttt{""} & \LaTeX &
Description text for the graph
\\
\hline
\ttt{\$x\_label} & \ttt{""} & \LaTeX &
$x$-axis label
\\
\hline
\ttt{\$y\_label} & \ttt{""} & \LaTeX &
$y$-axis label
\\
\hline
\ttt{graph\_width\_mm} & 130 & Integer &
graph width (on paper) in mm
\\
\hline
\ttt{graph\_height\_mm} & 90 & Integer &
graph height (on paper) in mm
\\
\hline
\ttt{?x\_log} & false & Logical &
Whether the $x$-axis scale is linear or logarithmic
\\
\hline
\ttt{?y\_log} & false & Logical &
Whether the $y$-axis scale is linear or logarithmic
\\
\hline
\ttt{x\_min} & \emph{undefined} & Real &
Lower bound for the $x$ axis
\\
\hline
\ttt{x\_max} & \emph{undefined} & Real &
Upper bound for the $x$ axis
\\
\hline
\ttt{y\_min} & \emph{undefined} & Real &
Lower bound for the $y$ axis
\\
\hline
\ttt{y\_max} & \emph{undefined} & Real &
Upper bound for the $y$ axis
\\
\hline
\ttt{gmlcode\_bg} & \ttt{""} & GAMELAN &
Code to be executed before drawing
\\
\hline
\ttt{gmlcode\_fg} & \ttt{""} & GAMELAN &
Code to be executed after drawing
\\
\hline
\end{tabular}
\end{center}
\end{table}
\begin{table}
\caption{Drawing options. The content of strings of type GAMELAN must be
valid GAMELAN code. The behavior w.r.t. the flags with \emph{undefined}
default value depends on the type of graph element. Histograms: draw
baseline, piecewise, fill area, draw curve, no errors, no symbols; Plots:
no baseline, no fill, draw curve, no errors, no symbols.}
\label{tab:drawing-options}
\begin{center}
\begin{tabular}{|l|l|l|l|}
\hline
Variable & Default & Type & Meaning
\\
\hline\hline
\ttt{?draw\_base} & \emph{undefined} & Logical &
Whether to draw a baseline for the curve
\\
\hline
\ttt{?draw\_piecewise} & \emph{undefined} & Logical &
Whether to draw bins separately (histogram)
\\
\hline
\ttt{?fill\_curve} & \emph{undefined} & Logical &
Whether to fill area between baseline and curve
\\
\hline
\ttt{\$fill\_options} & \ttt{""} & GAMELAN &
Options for filling the area
\\
\hline
\ttt{?draw\_curve} & \emph{undefined} & Logical &
Whether to draw the curve as a line
\\
\hline
\ttt{\$draw\_options} & \ttt{""} & GAMELAN &
Options for drawing the line
\\
\hline
\ttt{?draw\_errors} & \emph{undefined} & Logical &
Whether to draw error bars for data points
\\
\hline
\ttt{\$err\_options} & \ttt{""} & GAMELAN &
Options for drawing the error bars
\\
\hline
\ttt{?draw\_symbols} & \emph{undefined} & Logical &
Whether to draw symbols at data points
\\
\hline
\ttt{\$symbol} & Black dot & GAMELAN &
Symbol to be drawn
\\
\hline
\ttt{gmlcode\_bg} & \ttt{""} & GAMELAN &
Code to be executed before drawing
\\
\hline
\ttt{gmlcode\_fg} & \ttt{""} & GAMELAN &
Code to be executed after drawing
\\
\hline
\end{tabular}
\end{center}
\end{table}
\section{Drawing options}
The options for coloring lines, filling curves, or choosing line styles make
use of macros in the GAMELAN language. At this place, we do not intend to
give a full account of the possiblities, but we rather list a few basic
features that are likely to be useful for drawing graphs.
\subsubsection{Colors}
GAMELAN knows about basic colors identified by name:
\begin{center}
\ttt{black}, \ttt{white}, \ttt{red}, \ttt{green}, \ttt{blue}, \ttt{cyan},
\ttt{magenta}, \ttt{yellow}
\end{center}
More generically, colors in GAMELAN are RGB triplets of numbers (actually,
numeric expressions) with values between 0 and 1, enclosed in brackets:
\begin{center}
\ttt{(\emph{r}, \emph{g}, \emph{b})}
\end{center}
To draw an object in color, one should apply the construct \ttt{withcolor
\emph{color}} to its drawing code. The default color is always black.
Thus, this will make a plot drawn in blue:
\begin{quote}
\begin{footnotesize}
\ttt{\$draw\_options = "withcolor blue"}
\end{footnotesize}
\end{quote}
and this will fill the drawing area of some histogram with an RGB color:
\begin{quote}
\begin{footnotesize}
\ttt{\$fill\_options = "withcolor (0.8, 0.7, 1)"}
\end{footnotesize}
\end{quote}
\subsubsection{Dashes}
By default, lines are drawn continuously. Optionally, they can be drawn using
a \emph{dash pattern}. Predefined dash patterns are
\begin{center}
\ttt{evenly}, \ttt{withdots}, \ttt{withdashdots}
\end{center}
Going beyond the predefined patterns, a generic dash pattern has the syntax
\begin{center}
\ttt{dashpattern (on \emph{l1} off \emph{l2} on} \ldots \ttt{)}
\end{center}
with an arbitrary repetition of \ttt{on} and \ttt{off} clauses. The numbers
\ttt{\emph{l1}}, \ttt{\emph{l2}}, \ldots\ are lengths measured in pt.
To apply a dash pattern, the option syntax \ttt{dashed \emph{dash-pattern}}
should be used. Options strings can be concatenated. Here is how to draw in
color with dashes:
\begin{quote}
\begin{footnotesize}
\ttt{\$draw\_options = "withcolor red dashed evenly"}
\end{footnotesize}
\end{quote}
and this draws error bars consisting of intermittent dashes and
dots:
\begin{quote}
\begin{footnotesize}
\ttt{\$err\_options = "dashed (withdashdots scaled 0.5)"}
\end{footnotesize}
\end{quote}
The extra brackets ensure that the scale factor $1/2$ is applied only the dash
pattern.
\subsubsection{Hatching}
Areas (e.g., below a histogram) can be filled with plain colors by the
\ttt{withcolor} option. They can also be hatched by stripes, optionally
rotated by some angle. The syntax is completely analogous to dashes. There
are two predefined \emph{hatch patterns}:
\begin{center}
\ttt{withstripes}, \ttt{withlines}
\end{center}
and a generic hatch pattern is written
\begin{center}
\ttt{hatchpattern (on \emph{w1} off \emph{w2} on} \ldots \ttt{)}
\end{center}
where the numbers \ttt{\emph{l1}}, \ttt{\emph{l2}}, \ldots\ determine the
widths of the stripes, measured in pt.
When applying a hatch pattern, the pattern may be rotated by some angle (in
degrees) and scaled. This looks like
\begin{quote}
\begin{footnotesize}
\ttt{\$fill\_options = "hatched (withstripes scaled 0.8 rotated 60)"}
\end{footnotesize}
\end{quote}
\subsubsection{Smooth curves}
Plot points are normally connected by straight lines. If data are acquired by
statistical methods, such as Monte Carlo integration, this is usually
recommended. However, if a plot is generated using an analytic mathematical
formula, or with sufficient statistics to remove fluctuations, it might be
appealing to connect lines by some smooth interpolation. GAMELAN can switch
on spline interpolation by the specific drawing option \ttt{linked smoothly}.
Note that the results can be surprising if the data points do have sizable
fluctuations or sharp kinks.
\subsubsection{Error bars}
Plots and histograms can be drawn with error bars. For histograms, only
vertical error bars are supported, while plot points can have error bars in
$x$ and $y$ direction. Error bars are switched on by the \ttt{?draw\_errors}
flag.
There is an option to draw error bars with ticks: \ttt{withticks} and an
alternative option to draw arrow heads: \ttt{witharrows}. These can be used
in the \ttt{\$err\_options} string.
\subsubsection{Symbols}
To draw symbols at plot points (or histogram midpoints), the flag
\ttt{?draw\_symbols} has to be switched on.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Fast Detector Simulation and External Analysis}
\label{chap:ext_anal}
Events from a Monte Carlo event generator are further used in an
analysis, most often combined with a detector simulation. Event files
from the generator are then classified whether they are (i) parton
level (coming from the hard matrix element) for which mostly LHE or
\hepmc\ event formats are used, particle level (after parton shower
and hadronization) - usually in \hepmc\ or \lcio\ format -, or
detector level objects. The latter is the realm of packages like
\ROOT\ or specific software from the experimental software
frameworks. While detailed experimental studies take into account the
best-possible detector description in a so-called full simulation via
\geant\ which takes several seconds per event, fast studies are made
with parameterized fast detector simulations like in \delphes\ or
\texttt{SGV}. In the following, we discuss the options to interface
external packages for these purposes or to pipe events from
\whizard\ to such external packages.
%%%%%
\section{Interfacing ROOT}
\label{sec:root}
One of the most distributed analysis framework is
\ROOT~\cite{Brun:1997pa}. In \whizard\ for the moment there is no
direct interface to the \ROOT\ framework. The easiest way to write
out particle-level events in the \ROOT\ or \ttt{RootTree} format is to
use \whizard's interface to \hepmcthree: this modern incarnation of
the \hepmc\ format has different writer classes, where the writer
class for \ROOT\ and \ttt{RootTree} files is supported by \whizard's
\hepmcthree\ interface. For this to work, one only has to make sure
that \hepmcthree\ has been built with \ROOT\ support, and that the
\whizard\ \ttt{configure} has to detect the \ROOT\ setup on the
computing environment. For more details cf. the installation
section~\ref{sec:hepmc}. If this has been successfully linked, then
\whizard\ can use its own \hepmcthree\ interface to write out
\ROOT\ or \ttt{RootTree} formats.
This can be done by setting the following options in the
\sindarin\ files:
\begin{code}
$hepmc3_mode = "Root"
\end{code}
or
\begin{code}
$hepmc3_mode = "RootTree"
\end{code}
For more details cf.~the \ROOT\ manual and documentation therein.
%%%%%
\section{Interfacing RIVET}
\label{sec:rivet}
\rivet~\cite{Buckley:2010ar} is a very mighty analysis framework which
has been developed to make experimental analyses from the LHC
experiments available for non-collaboration members. It can be easily
used to analyze events and produce high-quality plots for differential
distributions and experimental observables. Since version
3~\cite{Bierlich:2019rhm} there is now also a lot of functionality
that comes very handy for plotting differential distributions at fixed
order in NLO calculations, e.g. negative weights in bins or how to
treat imperfectly balanced events and counterevents close to bin
boundaries etc. For the moment, \whizard\ does not have a dedicated
interface to \rivet, so the preferred method is to write out events,
best in the \hepmc\ or \hepmcthree\ format and then read them into
\rivet. A more sophisticated interface is foreseen for a future
version of \whizard, while there are already development versions
where \whizard\ detects all the \rivet\ infrastructure and
libraries. But they are not yet used.
For more details and practical examples cf.~the \rivet\ manual. This
describes in detail especially the \rivet\ installation. A typical
error that occurs on systems where no \ROOT\ is installed
(cf.~Sec.~\ref{sec:root}) is the one these \ttt{Missing TPython.h}
missing headers. Then \rivet\ can nevertheless be easily built without
\ROOT\ support by setting
\begin{code}
--disable-root
\end{code}
in the \ttt{rivet-bootstrap} script. For an installation of \rivet\ it
is favorable to include the location of the \rivet\ \python\ scripts
in the \ttt{PYTHONPATH} environment variable. They can be accessed
from the \rivet\ configuration script as
\begin{code}
<path_to_rivet-config>/rivet-config --pythonpath
\end{code}
If the \python\ path is not known within the environment variables,
then one commonly encounters error like \ttt{No module named rivet} or
\ttt{Import error: no module named yoda} when running \rivet\ scripts
like e.g. \ttt{yodamerge}.
If you use a \rivet\ version older than \ttt{v3.1.1} there is no
support for \hepmcthree\ yet, so when using \hepmcthree\ with
\whizard\ please use the backwards compatibility mode of \hepmcthree
in the \sindarin\ file:
\begin{code}
$hepmc3_mode = "HepMC2"
\end{code}
When using MPI parallelized runs of \whizard\ there will a large
number of different \ttt{.hepmc} files (also if some grid architecture
has produced these event files in junks). Then one has to first merge
these event files.
Here, we quickly explain how to steer \rivet\ for your own
analysis. For more details, please confer the \rivet\ manual.
\begin{enumerate}
\item The command
\begin{code}
rivet-mkanalysis <name>
\end{code}
creates a template \rivet\ plugin for the analysis \ttt{<name>.cc},
a template info file \ttt{<name>.info} amd a template file for the
plot generation \ttt{<name>.plot}. Note that this overwrites
potentially existing files in this folder with the same name.
\item
Now, analysis statements like e.g. cuts etc. can be implemented in
\ttt{<name>.cc}. For analysis of parton-level events without parton
showering, the cuts can be equivalent to those in \whizard, i.e. the
generator-level cuts can be as strict as the analysis cuts to avoid
generating unnecessary events. If parton showering is applied it is
better to have looser generator than analysis cuts to avoid
undesired plot artifacts.
\item
Next, one executes the command (the shared library name might be
different e.g. on Darwin or BSD OS)
\begin{code}
rivet-buildplugin Rivet<name>.so <name>.cc
\end{code}
This creates an executable \rivet\ analysis library
\ttt{Rivet<name>.so}. The custom analysis should now appear in the
output of
\begin{code}
rivet --list <name>
\end{code}
If this is not the case, the analysis path has to be exported first
as \ttt{RIVET\_ANALYSIS\_PATH=\$PWD}.
\item
We are now ready to use the custom analysis to analyze the
\ttt{.hepmc} events by executing the command
\begin{code}
rivet --pwd --analysis=<name> -o <outfile>.yoda <path/to/hepmcfiles>
\end{code}
and save the produced histograms of the analysis in the \ttt{.yoda}
format. In general the option \ttt{--ignore-beams} for
\rivet\ should be used to prevent \rivet\ to stumble over beam
remnants. This is also relevant for lepton collider processes with
electron PDFs. For a large number of events, event files can become
very big. To avoid writing them all on disk, a FIFO for the
\ttt{<path/to/hepmcfiles>} can be used.
\item
Different \ttt{yoda} files can now be merged into a single file
using the command
\begin{code}
<yodamerge --add -o <name>_full.yoda <name>_01.yoda ...
\end{code}
This should be applied e.g. for the case of fixed-order NLO
differential distributions where Born, real and virtual components
have been generated separately.
\item
Finally, plots can be produced: after listing all the histograms to
be plotted in the plot file \ttt{<name>.plot}, the command
\begin{code}
rivet-mkhtml <name>_full.yoda
\end{code}
translates the \ttt{.yoda} file into a histogram file in the
\ttt{.dat} format. These plots can either be visually enhanced by
modifying the \ttt{<name>.plot} file as is described on the webpage
\url{https://rivet.hepforge.org/make-plots.html}, or by using any
other external plotting tool like e.g. \ttt{Gnuplot} for the
\ttt{.dat} files.
\end{enumerate}
Clearly, this gives only a rough sketch on how to use \rivet\ for an
analysis. For more details, please consult the \rivet\ webpage and the
\rivet\ manual.
%%%%%
\vspace{1cm}
\section{Fast Detector Simulation with DELPHES}
\label{sec:delphes}
Fast detector simulation allows relatively quick checks whether
experimental analyses actually work in a semi-realistic detector
study. There are some older tools for fast simulation like
e.g.~\ttt{PGS} (which is no longer actively maintained) and \ttt{SGV}
which is default fast simulation for ILC studies. For LHC and general
future hadron collider studies, \delphes~\cite{deFavereau:2013fsa} is
the most commonly used tool for fast detector simulation.
The details on how to obtain and build \delphes\ can be obtained from
their webpage, \url{https://cp3.irmp.ucl.ac.be/projects/delphes}. It
depends both on~\ttt{Tcl/Tk} as well as
\ROOT~(cf. Sec.~\ref{sec:root}. Interfacing any Monte Carlo event
generator with a fast detector simulation like \delphes\ is rather
trivial: \delphes\ ships with up to five executables
\begin{code}
DelphesHepMC
DelphesLHEF
DelphesPythia8
DelphesROOT
DelphesSTDHEP
\end{code}
\ttt{DelphesPythia8} is a direct interface between \pythiaeight\ and
\delphes, so detector-level events are directly produced via an API
interface between \pythiaeight\ and \delphes. This is the most
convenient method which is foreseen for \whizard, however not yet
implemented. The other four binaries take input files in the \hepmc,
LHE, \stdhep\ and \ROOT\ format, apply a fast detector simulation
according to the chosen input file and give a \ROOT\ detector-level
event file as output.
Executing one of the binaries above without options, the following
message will be displayed:
\begin{code}
./DelphesHepMC
Usage: DelphesHepMC config_file output_file [input_file(s)]
config_file - configuration file in Tcl format,
output_file - output file in ROOT format,
input_file(s) - input file(s) in HepMC format,
with no input_file, or when input_file is -, read standard input.
\end{code}
Using \delphes\ with \hepmc\ event files then works as
\begin{code}
./DelphesHepMC cards/delphes_card_ATLAS.tcl output.root input.hepmc
\end{code}
For \stdhep\ files which are directly by \whizard\ without external
packages (only assuming that the XDR C libraries are present on the
system), execute
\begin{code}
./DelphesSTDHEP cards/delphes_card_ILD.tcl delphes_output.root input.hep
\end{code}
For LHE files as input, use
\begin{code}
./DelphesLHEF cards/delphes_card_CLICdet_Stage1.tcl delphes_output.root input.lhef
\end{code}
and for \ROOT\ (particle-level) files use
\begin{code}
./DelphesROOT cards/delphes_card_CMS.tcl delphes_output.root input.root
\end{code}
In the \delphes\ cards directory, there is a long list of supported
input files for existing and future detectors, a few of which we have
displayed here.
\delphes\ detector-level output files can then be analyzed with
\ROOT\ as described in the \delphes\ manual.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{User Interfaces for WHIZARD}
\label{chap:userint}
\section{Command Line and \sindarin\ Input Files}
\label{sec:cmdline-options}
The standard way of using \whizard\ involves a command script written
in \sindarin. This script is executed by \whizard\ by mentioning it
on the command line:
\begin{interaction}
whizard script-name.sin
\end{interaction}
You may specify several script files on the command line; they will be
executed consecutively.
If there is no script file, \whizard\ will read commands from standard
input. Hence, this is equivalent:
\begin{interaction}
cat script-name.sin | whizard
\end{interaction}
When executed from the command line, \whizard\ accepts several options.
They are given in long form, i.e., they begin with two dashes. Values
that belong to options follow the option string, separated either by
whitespace or by an equals sign. Hence, \ttt{--prefix /usr} and
\ttt{--prefix=/usr} are equivalent. Some options are also available
in short form, a single dash with a single letter. Short-form options
can be concatenated, i.e., a dash followed by several option letters.
The first set of options is intended for normal operation.
\begin{description}
\item[\ttt{--debug AREA}]: Switch on debug output for \ttt{AREA}.
\ttt{AREA} can be one of \whizard's source directories or \ttt{all}.
\item[\ttt{--debug2 AREA}]: Switch on more verbose debug output for \ttt{AREA}.
\item[\ttt{--single-event}]: Only compute one phase-space point (for debugging).
\item[\ttt{--execute COMMANDS}]: Execute \ttt{COMMANDS} as a script
before the script file (see below). Short version: \ttt{-e}
\item[\ttt{--file CMDFILE}]: Execute commands in \ttt{CMDFILE} before the
main script file (see below). Short version: \ttt{-f}
\item[\ttt{--help}]: List the available options and exit. Short version:
\ttt{-h}
\item[\ttt{--interactive}]: Run \whizard\ interactively. See
Sec.~\ref{sec:whish}. Short version: \ttt{-i}.
\item[\ttt{--library LIB}]: Preload process library \ttt{LIB}
(instead of the default \ttt{processes}). Short version: \ttt{-l}.
\item[\ttt{--localprefix DIR}]: Search in \ttt{DIR} for local
models. Default is \ttt{\$HOME/.whizard}.
\item[\ttt{--logfile \ttt{FILE}}]: Write log to \ttt{FILE}. Default is
\ttt{whizard.log}. Short version: \ttt{-L}.
\item[\ttt{--logging}]: Start logging on startup (default).
\item[\ttt{--model MODEL}]: Preload model \ttt{MODEL}. Default is the
Standard Model \ttt{SM}. Short version: \ttt{-m}.
\item[\ttt{--no-banner}]: Do not display banner at startup.
\item[\ttt{--no-library}]: Do not preload a library.
\item[\ttt{--no-logfile}]: Do not write a logfile.
\item[\ttt{--no-logging}]: Do not issue information into the logfile.
\item[\ttt{--no-model}]: Do not preload a specific physics model.
\item[\ttt{--no-rebuild}]: Do not force a rebuild.
\item[\ttt{--query VARIABLE}]: Display documentation of \ttt{VARIABLE}.
Short version: \ttt{-q}.
\item[\ttt{--rebuild}]: Do not preload a process library and do all
calculations from scratch, even if results exist. This combines all
rebuild options. Short version: \ttt{-r}.
\item[\ttt{--rebuild-library}]: Rebuild the process library, even if code
exists.
\item[\ttt{--rebuild-phase-space}]: Rebuild the phase space setup, even if
it exists.
\item[\ttt{--rebuild-grids}]: Redo the integration, even if previous grids
and results exist.
\item[\ttt{--rebuild-events}]: Redo event generation, discarding previous
event files.
\item[\ttt{--show-config}]: Show build-time configuration.
\item[\ttt{--version}]: Print version information and exit. Short version:
\ttt{-V}.
\item[-]: Any further options are interpreted as file names.
\end{description}
The second set of options refers to the configuration. They are
relevant when dealing with a relocated \whizard\ installation, e.g.,
on a batch systems.
\begin{description}
\item[\ttt{--prefix DIR}]: Specify the actual location of the \whizard\
installation, including all subdirectories.
\item[\ttt{--exec-prefix DIR}]: Specify the actual location of the
machine-specific parts of the \whizard\ installation (rarely needed).
\item[\ttt{--bindir DIR}]: Specify the actual location of the
executables contained in the \whizard\ installation (rarely needed).
\item[\ttt{--libdir DIR}]: Specify the actual location of the
libraries contained in the \whizard\ installation (rarely needed).
\item[\ttt{--includedir DIR}]: Specify the actual location of the
include files contained in the \whizard\ installation (rarely needed).
\item[\ttt{--datarootdir DIR}]: Specify the actual location of the
data files contained in the \whizard\ installation (rarely needed).
\item[\ttt{--libtool LOCAL\_LIBTOOL}]: Specify the actual location and
name of the \ttt{libtool} script that should be used by \whizard.
\item[\ttt{--lhapdfdir DIR}]: Specify the actual location and
of the \lhapdf\ installation that should be used by \whizard.
\end{description}
The \ttt{--execute} and \ttt{--file} options allow for fine-tuning the command
flow. The \whizard\ main program will concatenate all commands given in
\ttt{--execute} commands together with all commands contained in \ttt{--file}
options, in the order they are encountered, as a contiguous command stream
that is executed \emph{before} the main script (in the example above,
\ttt{script-name.sin}).
Regarding the \ttt{--execute} option, commands that contain blanks must be
enclosed in matching single- or double-quote characters since the individual
tokens would otherwise be intepreted as separate option strings.
Unfortunately, a Unix/Linux shell interpreter will strip quotes before handing
the command string over to the program. In that situation, the
quote-characters must be quoted themselves, or the string must be enclosed in
quotes twice. Either version should work as a command line interpreted by
the shell:
\begin{interaction}
whizard --execute \'int my_flag = 1\' script-name.sin
whizard --execute "'int my_flag = 1'" script-name.sin
\end{interaction}
\section{WHISH -- The \whizard\ Shell/Interactive mode}
\label{sec:whish}
\whizard\ can be also run in the interactive mode using its own shell
environment. This is called the \whizard\ Shell (WHISH). For this
purpose, one starts with the command
\begin{interaction}
/home/user$ whizard --interactive
\end{interaction}
or
\begin{interaction}
/home/user$ whizard -i
\end{interaction}
\whizard\ will preload the Standard Model and display a command
prompt:
\begin{interaction}
whish?
\end{interaction}
You now can enter one or more \sindarin\ commands, just as if they
were contained in a script file. The commands are compiled and
executed after you hit the ENTER key. When done, you get a new
prompt. The WHISH can be closed by the \ttt{quit} command:
\begin{verbatim}
whish? quit
\end{verbatim}
Obviously, each input must be self-contained: commands must be
complete, and conditionals or scans must be closed on the same line.
If \whizard\ is run without options and without a script file, it
also reads commands interactively, from standard input. The
difference is that in this case, interactive input is multi-line,
terminated by \ttt{Ctrl-D}, the script is then compiled and
executed as a whole, and \whizard\ terminates.
In WHISH mode, each input line is compiled and executed individually.
Furthermore, fatal errors are masked, so in case of error the program
does not terminate but returns to the WHISH command line. (The
attempt to recover may fail in some circumstances, however.)
\section{Graphical user interface}
\emph{This is still experimental.}
\whizard\ ships with a graphical interface that can be steered in a
browser of your choice. It is located in \ttt{share/gui}. To use it,
you have to run \ttt{npm install} (which will install javascript
libraries locally in that folder) and \ttt{npm start} (which will start
a local web server on your machine) in that folder. More technical
details and how to get \ttt{npm} is discussed in
\ttt{share/gui/README.md}. When it is running, you can access the GUI
by entering \ttt{localhost:3000} as address in your browser. The GUI is
separated into different tabs for basic settings, integration,
simulation, cuts, scans, NLO and beams. You can select and enter what
you are interested in and the GUI will produce a \sindarin\ file. You
can use the GUI to run WHIZARD with that \sindarin\ or just produce it
with the GUI and then tweak it further with an editor. In case you run
it in the GUI, the log file will be updated in the browser as it is
produced. Any \sindarin\ features that are not supported by the GUI can
be added directly as "Additional Code".
\section{\whizard\ as a library}
The compiled \whizard\ program consists of two libraries (\ttt{libwhizard} and
\ttt{libomega}). In the standard setup, these are linked to a short main
program which deals with command line options and top-level administration.
This is the stand-alone \ttt{whizard} executable program.
Alternatively, it is possible to link the libraries to a different main
program of the user's choice. The user program can take complete control of
the \whizard\ features. The \ttt{libwhizard} library provides an API, a
well-defined set of procedures which can be called from a foreign main
program. The supported languages are \fortran, \ttt{C}, and \cpp.
Using the C API, any other language which supports linking against C
libraries can also be interfaced.
\subsection{Fortran main program}
To link a \fortran\ main program with the \whizard\ library, the following steps
must be performed:
\begin{enumerate}
\item
Configure, build and install \whizard\ as normal.
\item
Include code for accessing \whizard\ functionality in the user program.
The code should initialize
\whizard, execute the intended commands, and finalize. For an example, see
below.
\item
Compile the user program. The user program must be
compiled with the same \fortran\ compiler that has been used for the \whizard\
build.
If necessary, specify an option that finds the
installed \whizard\ module files.
For instance, if \whizard\ has been installed in \ttt{whizard-path}, this
should read
\begin{code}
-Iwhizard-path/lib/mod/whizard
\end{code}
\item
Link the program (or compile-link in a single step). If necessary, specify
options that find the installed \whizard\ and \oMega\ libraries. For
instance, if \whizard\ has been installed in \ttt{whizard-path}, this should
read
\begin{code}
-Lwhizard-path/lib -lwhizard -lwhizard_prebuilt -lomega
\end{code}
On some systems, you may have to replace \ttt{lib} by \ttt{lib64}.
Such an example compile-link could look like
\begin{code}
gfortran manual_example_api.f90 -Lwhizard-path/lib -lwhizard -lwhizard_prebuilt -lomega
\end{code}
If \whizard\ has been compiled with a non-default \fortran\ compiler, you may
have to explicitly link the appropriate \fortran\ run-time libraries.
The \ttt{tirpc} library is used by the \ttt{StdHEP} subsystem for \ttt{xdr}
functionality. This library should be present on the host
system. This library needs only be linked of the SunRPC library is
not installed on the system.
If additional libraries such as
\hepmc\ are enabled in the \whizard\ configuration, it may be necessary to
provide extra options for linking those.
An example here looks like
\begin{code}
gfortran manual_example_api.f90 -Lwhizard-path/lib -lwhizard
-lwhizard_prebuilt -lomega -lHepMC3 -lHepMC3rootIO -llcio
\end{code}
\item
Run the program. If necessary, provide the path to the installed shared
libraries. For instance, if \whizard\ has been installed in
\ttt{whizard-path}, this should read
\begin{code}
export LD_LIBRARY_PATH="whizard-path/lib:$LD_LIBRARY_PATH"
\end{code}
On some systems, you may have to replace \ttt{lib} by \ttt{lib64}, as above.
The \whizard\ subsystem will work with input and output
files in the current working directory, unless asked to do otherwise.
\end{enumerate}
Below is an example program, adapted from \whizard's internal unit-test suite.
The user program controls the \whizard\ workflow in the same way as a
\sindarin\ script would do. The commands are a mixture of \sindarin\ command
calls and functionality for passing information between the \whizard\
subsystem and the host program.
In particular, the program can process generated events one-by-one.
\begin{code}
program main
! WHIZARD API as a module
use api
! Standard numeric types
use iso_fortran_env, only: real64, int32
implicit none
! WHIZARD and event-sample objects
type(whizard_api_t) :: whizard
type(simulation_api_t) :: sample
! Local variables
real(real64) :: integral, error
real(real64) :: sqme, weight
integer(int32) :: idx
integer(int32) :: i, it_begin, it_end
! Initialize WHIZARD, setting some global option
call whizard%option ("model", "QED")
call whizard%init ()
! Define a process, set some variables
call whizard%command ("process mupair = e1, E1 => e2, E2")
call whizard%set_var ("sqrts", 100._real64)
call whizard%set_var ("seed", 0)
! Generate matrix-element code, integrate and retrieve result
call whizard%command ("integrate (mupair)")
call whizard%get_integration_result ("mupair", integral, error)
! Print result
print 1, "cross section =", integral / 1000, "pb"
print 1, "error =", error / 1000, "pb"
1 format (2x,A,1x,F5.1,1x,A)
2 format (2x,A,1x,L1)
! Settings for event generation
call whizard%set_var ("$sample", "mupair_events")
call whizard%set_var ("n_events", 2)
! Create an event-sample object and generate events
call whizard%new_sample ("mupair", sample)
call sample%open (it_begin, it_end)
do i = it_begin, it_end
call sample%next_event ()
call sample%get_event_index (idx)
call sample%get_weight (weight)
call sample%get_sqme (sqme)
print "(A,I0)", "Event #", idx
print 3, "sqme =", sqme
print 3, "weight =", weight
3 format (2x,A,1x,ES10.3)
end do
! Finalize the event-sample object
call sample%close ()
! Finalize the WHIZARD object
call whizard%final ()
end program main
\end{code}
The API provides the following commands as \fortran\ subroutines. Most of them
are used in the example above.
\subsubsection{Module}
There is only one module from the \whizard\ package which must be
\texttt{use}d by the user program:
\begin{quote}
\tt use api
\end{quote}
You may \texttt{use} any other \whizard\ module in our program, all module
files are part of the installation. Be aware,
however, that all other modules are considered internal. Unless explictly
mentioned in this manual, interfaces are
not documented here and may change between versions.
Changes to the \ttt{api} module, if any, will be documented here.
\subsubsection{Master object}
All functionality is accessed via a master API object which should be declared
as follows:
\begin{quote}
\tt type(whizard\_api\_t) :: whizard
\end{quote}
There should be only one master object.
\subsubsection{Pre-Initialization options}
Before initializing the API object, it is possible to provide options. The
available options mirror the command-line options of the stand-alone program,
cf.\ Sec.~\ref{sec:cmdline-options}.
\begin{quote}
\tt call whizard\%option (\textit{key}, \textit{value})
\end{quote}
All keys and values are \fortran\ character strings. The following options are
available. For all options, default values exist as listed in
Sec.~\ref{sec:cmdline-options}.
\begin{description}
\item[\tt model] Model that should be preloaded.
\item[\tt library] Name of the library where matrix-element code should end up.
\item[\tt logfile] Name of the logfile that \whizard\ will write.
\item[\tt job\_id] Name of the current job; can be used for writing unique output
files.
\item[\tt unpack] Comma-separated list of files to be uncompressed and unpacked
(via \ttt{tar} and \ttt{gzip}) when \ttt{init} is called on the API object.
\item[\tt pack] Comma-separated list of files or directories to be packed and
compressed when \ttt{final} is called.
\item[\tt rebuild] All of the following:
\item[\tt rebuild\_library] Force rebuilding a matrix-element code library,
overwriting results from a previous run.
\item[\tt recompile] Force recompiling the matrix-element code library.
\item[\tt rebuild\_grids] Force reproducing integration passes.
\item[\tt rebuild\_events] Force regenerating event samples.
\end{description}
\subsubsection{Initialization and finalization}
After options have been set, the system is initialized via
\begin{quote}
\tt call whizard\%init
\end{quote}
Once initialized, \whizard\ can execute commands as listed below. When this
is complete, clean up by
\begin{quote}
\tt call whizard\%final
\end{quote}
\subsubsection{Variables and values}
In the API, \whizard\ requires numeric data types according to the IEEE
standard, which is available to \fortran\ in the \ttt{iso\_fortran\_env}
intrinsic module. Strictly speaking, integer data must have type \ttt{int32},
and real data must have type \ttt{real64}.
For most systems and default compiler settings, it
is not really necessary to \ttt{use} the ISO module and its data types.
Integers map to default \fortran\ \ttt{integer},
and real values map to default \fortran\ \ttt{double precision}.
As an
alternative, you may \ttt{use} the \whizard\ internal \ttt{kinds} module which
declares a \ttt{real(default)} type
\begin{quote}
\tt use kinds, only: default
\end{quote}
On most systems, this will be equivalent
to \ttt{real(real64)}.
To set a \sindarin\ variable, use the function that corresponds to the data
type:
\begin{quote}
\tt call whizard\%set\_var (\textit{name}, \textit{value})
\end{quote}
The name is a \fortran\ string which has to be equal to the name of the
corresponding \sindarin\ variable, including any prefix character (\$ or ?).
The value depends on the type of the \sindarin\
variable.
To retrieve the current value of a variable:
\begin{quote}
\tt call whizard\%get\_var (\textit{name}, \textit{var})
\end{quote}
The variable must be declared as \ttt{integer}, \ttt{real(real64)},
\ttt{logical}, or
\ttt{character(:), allocatable}. This depends on the \sindarin\ variable type.
\subsubsection{Commands}
Any \sindarin\ command can be called via
\begin{quote}
\tt call whizard\%command (\textit{command})
\end{quote}
\ttt{\it command} is a \fortran\ character string, as it would appear
in a \sindarin\ script.
This includes, in particular, the important commands \ttt{process},
\ttt{integrate}, and \ttt{simulate}. You may also set variables that way.
\subsubsection{Retrieving cross-section results}
This call returns the results (integration and error) from a preceding
integration run for the process \textit{process-name}:
\begin{quote}
\tt call whizard\%get\_integration\_result ("\textit{process-name}",
integral, error)
\end{quote}
There is also an optional argument \ttt{known} of type \ttt{logical} which is
set if the integration run was successful, so integral and error are
meaningful.
\subsubsection{Event-sample object}
A \ttt{simulate} command will produce an event sample. With the appropriate
settings, the sample will be written to file in any chosen format, to be
post-processed when it is complete.
However, a possible purpose of using the \whizard\ API is to process events one-by-one
when they are generated. To this end, there is an event-sample handle, which
can be declared in this way:
\begin{quote}
\tt type(simulation\_api\_t) :: sample
\end{quote}
An instance \ttt{sample} of this type is created by this factory method:
\begin{quote}
\tt call whizard\%new\_sample ("\textit{process-name(s)}", sample)
\end{quote}
The command accepts a comma-separated list of process names which should be
included in the event sample.
To start event generation for this sample, call
\begin{quote}
\tt call sample\%open (\textit{it\_begin}, \textit{it\_end} )
\end{quote}
where the two output parameters (integers) \ttt{\it it\_begin} and \ttt{\it it\_end}
provide the bounds for an event loop in the calling program. (In serial mode,
the bounds are equal to 1 and \ttt{n\_events}, respectively, but in an MPI
parallel environment, they depend on the computing node.)
This command generates a new event, to be enclosed within an event loop:
\begin{quote}
\tt call sample\%next\_event
\end{quote}
The event will be available by format-specific access methods, see below.
This command closes and deletes an event sample after the event loop has
completed:
\begin{quote}
\tt call sample\%close
\end{quote}
\subsubsection{Retrieving event data}
After a call to \ttt{next\_event}, the sample object can be queried for
specific event data.
\begin{quote}
\tt call sample\%get\_event\_index (\textit{value})
\end{quote}
returns the index (integer counter) of the current event.
\begin{quote}
\tt call sample\%get\_process\_index (\textit{value})
\\
\tt call sample\%get\_process\_id (\textit{value})
\end{quote}
returns the numeric (string) ID of the hard process, respectively, that was
generated in this event. The variables must be declared as \ttt{integer} and
\ttt{character(:), allocatable}, respectively.
The following methods return \ttt{real(real64)} values.
\begin{quote}
\tt call sample\%get\_sqrts (\textit{value})
\end{quote}
returns the $\sqrt{s}$ value of this event.
\begin{quote}
\tt call sample\%get\_fac\_scale (\textit{value})
\end{quote}
returns the factorization scale of this event (\textit{value}).
\begin{quote}
\tt call sample\%get\_alpha\_s (\textit{value})
\end{quote}
returns the value of the strong coupling for this event (\textit{value}).
\begin{quote}
\tt call sample\%get\_sqme (\textit{value})
\end{quote}
returns the value of the squared matrix element (summed over final states and
averaged over initial states).
\begin{quote}
\tt call sample\%get\_weight (\textit{value})
\end{quote}
returns the Monte-Carlo weight of this event.
Access to the event record depends on the event format that has been
selected. The format must allow access to individual events via data
structures in memory. There are three cases where such structures exist and
are accessible:
\begin{enumerate}
\item
If the event format uses a COMMON block, event data is accessible
via this COMMON block, which must be declared in the calling routine.
\item
The \hepmc\ event format communicates via a \cpp\ object. In \fortran, there
is a wrapper which has to be declared as
\begin{quote}
\tt type(hepmc\_event\_t) :: hepmc\_event
\end{quote}
To activate this handle, the \ttt{next\_event} call must reference it as
an argument:
\begin{quote}
\tt call sample\%next\_event (hepmc\_event)
\end{quote}
The \whizard\ module \ttt{hepmc\_interface} contains procedures which can
work with this record. A pointer to the actual \cpp\ object can be retrieved
as a \fortran\
\ttt{c\_ptr} object as follows:
\begin{quote}
\tt
type(c\_ptr) :: hepmc\_ptr
\\
\dots
\\
hepmc\_ptr = hepmc\_event\_get\_c\_ptr (hepmc\_event)
\end{quote}
\item
The \lcio\ event format also communicates via a \cpp\ object. The access
methods are entirely analogous, replacing \ttt{hepmc} by \ttt{lcio} in all
calls and names.
\end{enumerate}
\subsection{C main program}
To link a C main program with the \whizard\ library, the following steps
must be performed:
\begin{enumerate}
\item
Configure, build and install \whizard\ as normal.
\item
Include code for accessing \whizard\ functionality in the user program.
The code should initialize
\whizard, execute the intended commands, and finalize. For an example, see
below.
\item
Compile the user program with the option that finds the WHIZARD \ttt{C/C++}
interface header file.
For instance, if \whizard\ has been installed in \ttt{whizard-path}, this
should read
\begin{code}
-Iwhizard-path/include
\end{code}
\item
Link the program with the necessary libraries (or compile-link in a single
step). If
\whizard\ has been installed in a system path, this should work
automatically. If
\whizard\ has been installed in a non-default \ttt{whizard-path}, these
are the options:
\begin{code}
-Lwhizard-path/lib -lwhizard -lwhizard_prebuilt -lomega -ltirpc
\end{code}
On some systems, you may have to replace \ttt{lib} by \ttt{lib64}.
If \whizard\ has been compiled with a non-default \fortran\ compiler, you may
have to explicitly link the appropriate \fortran\ run-time libraries.
The \ttt{tirpc} library is used by the \ttt{StdHEP} subsystem for \ttt{xdr}
functionality. This library should be present on the host
system. Cf. the corresponding remarks in the section for a
\fortran\ main program.
If additional libraries such as
\hepmc\ are enabled in the \whizard\ configuration, it may be necessary to
provide extra options for linking those.
\item
Run the program. If necessary, provide the path to the installed shared
libraries. For instance, if \whizard\ has been installed in
\ttt{whizard-path}, this should read
\begin{code}
export LD_LIBRARY_PATH="whizard-path/lib:$LD_LIBRARY_PATH"
\end{code}
On some systems, you may have to replace \ttt{lib} by \ttt{lib64}, as above.
The \whizard\ subsystem will work with input and output
files in the current working directory, unless asked to do otherwise.
\end{enumerate}
Below is an example program, adapted from \whizard's internal unit-test suite.
The user program controls the \whizard\ workflow in the same way as a
\sindarin\ script would do. The commands are a mixture of \sindarin\ command
calls and functionality for passing information between the \whizard\
subsystem and the host program.
In particular, the program can process generated events one-by-one.
\begin{code}
#include <stdio.h>
#include "whizard.h"
int main( int argc, char* argv[] )
{
/* WHIZARD and event-sample objects */
void* wh;
void* sample;
/* Local variables */
double integral, error;
double sqme, weight;
int idx;
int it, it_begin, it_end;
/* Initialize WHIZARD, setting some global option */
whizard_create( &wh );
whizard_option( &wh, "model", "QED" );
whizard_init( &wh );
/* Define a process, set some variables */
whizard_command( &wh, "process mupair = e1, E1 => e2, E2" );
whizard_set_double( &wh, "sqrts", 10. );
whizard_set_int( &wh, "seed", 0 );
/* Generate matrix-element code, integrate and retrieve result */
whizard_command( &wh, "integrate (mupair)" );
/* Print result */
whizard_get_integration_result( &wh, "mupair", &integral, &error);
printf( " cross section = %5.1f pb\n", integral / 1000. );
printf( " error = %5.1f pb\n", error / 1000. );
/* Settings for event generation */
whizard_set_char( &wh, "$sample", "mupair_events" );
whizard_set_int( &wh, "n_events", 2 );
/* Create an event-sample object and generate events */
whizard_new_sample( &wh, "mupair", &sample );
whizard_sample_open( &sample, &it_begin, &it_end );
for (it=it_begin; it<=it_end; it++) {
whizard_sample_next_event( &sample );
whizard_sample_get_event_index( &sample, &idx );
whizard_sample_get_weight( &sample, &weight );
whizard_sample_get_sqme( &sample, &sqme );
printf( "Event #%d\n", idx );
printf( " sqme = %10.3e\n", sqme );
printf( " weight = %10.3e\n", weight );
}
/* Finalize the event-sample object */
whizard_sample_close( &sample );
/* Finalize the WHIZARD object */
whizard_final( &wh );
}
\end{code}
\subsubsection{Header}
The necessary declarations are imported by the directive
\begin{quote}
\tt \#include "whizard.h"
\end{quote}
\subsubsection{Master object}
All functionality is accessed via a master API object which should be declared
as a \ttt{void*} pointer:
\begin{quote}
\tt void* wh;
\end{quote}
The object must be explicitly created:
\begin{quote}
\tt whizard\_create( \&wh );
\end{quote}
There should be only one master object.
\subsubsection{Pre-Initialization options}
Before initializing the API object, it is possible to provide options. The
available options mirror the command-line options of the stand-alone program,
cf.\ Sec.~\ref{sec:cmdline-options}.
\begin{quote}
\tt whizard\_option( \&wh, \textit{key}, \textit{value} );
\end{quote}
All keys and values are null-terminated C character strings. The available
options are
listed above in the \fortran\ interface documentation.
\subsubsection{Initialization and finalization}
After options have been set, the system is initialized via
\begin{quote}
\tt whizard\_init( \&wh );
\end{quote}
Once initialized, \whizard\ can execute commands as listed below. When this
is complete, clean up by
\begin{quote}
\tt whizard\_final( \&wh );
\end{quote}
\subsubsection{Variables and values}
In the API, \whizard\ requires numeric data types according to the IEEE
standard. Integers map to C \ttt{int}, and real values map to C
\ttt{double}. Logical values map to C \ttt{int} interpreted as \ttt{bool},
and string values map to null-terminated C strings.
To set a \sindarin\ variable of appropriate type:
\begin{quote}
\tt whizard\_set\_int ( \&wh, \textit{name}, \textit{value} );
\\
\tt whizard\_set\_double ( \&wh, \textit{name}, \textit{value} );
\\
\tt whizard\_set\_bool ( \&wh, \textit{name}, \textit{value} );
\\
\tt whizard\_set\_char ( \&wh, \textit{name}, \textit{value} );
\end{quote}
\textit{name} is declared \ttt{const char*}. It must match the corresponding
\sindarin\ variable name, including any prefix character (\$ or ?).
\textit{value} is declared \ttt{const double/int/char*}.
To retrieve the current value of a variable:
\begin{quote}
\tt whizard\_get\_int ( \&wh, \textit{name}, \&\textit{var} );
\\
\tt whizard\_get\_double ( \&wh, \textit{name}, \&\textit{var} );
\\
\tt whizard\_get\_bool ( \&wh, \textit{name}, \&\textit{var} );
\\
\tt whizard\_get\_char ( \&wh, \textit{name}, \textit{var}, \textit{len} );
\end{quote}
Here, \ttt{\it var} is a C variable of appropriate type. In the character
case, \ttt{\it var} is a C character array declared as
\ttt{\it var}[\ttt{\it len}]. The functions return zero if the \sindarin\
variable has a known value.
\subsubsection{Commands}
Any \sindarin\ command can be called via
\begin{quote}
\tt whizard\_command( \&wh, \textit{command} );
\end{quote}
\ttt{\it command} is a null-terminated C string that contains commands as they
would appear in a \sindarin\ script.
This includes, in particular, the important commands \ttt{process},
\ttt{integrate}, and \ttt{simulate}. You may also set variables that way.
\subsubsection{Retrieving cross-section results}
This call returns the results (integration and error) from a preceding
integration run for the process \textit{process-name}:
\begin{quote}
\tt whizard\_get\_integration\_result( \&wh, "\textit{process-name}",
\&\textit{integral}, \&\textit{error})
\end{quote}
\ttt{\it integral} and \ttt{\it error} are C variables of type \ttt{double}.
The function returns zero if the integration run was successful, so integral
and error are meaningful.
\subsubsection{Event-sample object}
A \ttt{simulate} command will produce an event sample. With the appropriate
settings, the sample will be written to file in any chosen format, to be
post-processed when it is complete.
However, a possible purpose of using the \whizard\ API is to process events one-by-one
when they are generated. To this end, there is an event-sample handle, which
can be declared in this way:
\begin{quote}
\tt void* \textit{sample};
\end{quote}
An instance \ttt{\it sample} of this type is created by this factory method:
\begin{quote}
\tt whizard\_new\_sample( \&wh, "\textit{process-name(s)}", \&\textit{sample});
\end{quote}
The command accepts a comma-separated list of process names which should be
included in the event sample.
To start event generation for this sample, call
\begin{quote}
\tt whizard\_sample\_open( \&\textit{sample}, \&\textit{it\_begin},
\&\textit{it\_end} );
\end{quote}
where the two output variables (\ttt{int}) \ttt{\it it\_begin} and
\ttt{\it it\_end}
provide the bounds for an event loop in the calling program. (In serial mode,
the bounds are equal to 1 and \ttt{n\_events}, respectively, but in an MPI
parallel environment, they depend on the computing node.)
This command generates a new event, to be enclosed within an event loop:
\begin{quote}
\tt whizard\_sample\_next\_event( \&\textit{sample} );
\end{quote}
The event will be available by format-specific access methods, see below.
This command closes and deletes an event sample after the event loop has
completed:
\begin{quote}
\tt whizard\_sample\_close( \&\textit{sample} );
\end{quote}
\subsubsection{Retrieving event data}
After a call to \ttt{whizard\_sample\_next\_event}, the sample object can be
queried for specific event data.
\begin{quote}
\tt whizard\_sample\_get\_event\_index( \&\textit{sample}, \&\textit{value} );
\\
\tt whizard\_sample\_get\_process\_index( \&\textit{sample}, \&\textit{value} );
\\
\tt whizard\_sample\_get\_process\_id( \&\textit{sample}, \textit{value}, \textit{len} );
\\
\tt whizard\_sample\_get\_sqrts( \&\textit{sample}, \&\textit{value} );
\\
\tt whizard\_sample\_get\_fac\_scale( \&\textit{sample}, \&\textit{value} );
\\
\tt whizard\_sample\_get\_alpha\_s( \&\textit{sample}, \&\textit{value} );
\\
\tt whizard\_sample\_get\_sqme( \&\textit{sample}, \&\textit{value} );
\\
\tt whizard\_sample\_get\_weight( \&\textit{sample}, \&\textit{value} );
\end{quote}
where the \ttt{\it value} is a variable of appropriate type (see above).
Event data are stored in a format-specific way. This may be a COMMON block,
or a \hepmc\ or \lcio\ event record. In the latter cases, cf.\ the \cpp\ API
below for access information.
\subsection{C++ main program}
To link a \cpp\ main program with the \whizard\ library, the following steps
must be performed:
\begin{enumerate}
\item
Configure, build and install \whizard\ as normal.
\item
Include code for accessing \whizard\ functionality in the user program.
The code should initialize
\whizard, execute the intended commands, and finalize. For an example, see
below.
\item
Compile the user program with the option that finds the WHIZARD
\ttt{C/C++} interface header file.
For instance, if \whizard\ has been installed in \ttt{whizard-path}, this
should read
\begin{code}
-Iwhizard-path/include
\end{code}
\item
Link the program with the necessary libraries (or compile-link in a single
step). If
\whizard\ has been installed in a system path, this should work
automatically. If
\whizard\ has been installed in a non-default \ttt{whizard-path}, these
are the options:
\begin{code}
-Lwhizard-path/lib -lwhizard -lwhizard_prebuilt -lomega -ltirpc
\end{code}
On some systems, you may have to replace \ttt{lib} by \ttt{lib64}.
If \whizard\ has been compiled with a non-default \fortran\ compiler, you may
have to explicitly link the appropriate \fortran\ run-time libraries.
The \ttt{tirpc} library is used by the \ttt{StdHEP} subsystem for \ttt{xdr}
functionality. This
library should be present on the host system.
If additional libraries such as
\hepmc\ are enabled in the \whizard\ configuration, it may be necessary to
provide extra options for linking those.
\item
Run the program. If necessary, provide the path to the installed shared
libraries. For instance, if \whizard\ has been installed in
\ttt{whizard-path}, this should read
\begin{code}
export LD_LIBRARY_PATH="whizard-path/lib:$LD_LIBRARY_PATH"
\end{code}
On some systems, you may have to replace \ttt{lib} by \ttt{lib64}, as above.
The \whizard\ subsystem will work with input and output
files in the current working directory, unless asked to do otherwise.
\end{enumerate}
Below is an example program, adapted from \whizard's internal unit-test suite.
The user program controls the \whizard\ workflow in the same way as a
\sindarin\ script would do. The commands are a mixture of \sindarin\ command
calls and functionality for passing information between the \whizard\
subsystem and the host program.
In particular, the program can process generated events one-by-one.
\begin{code}
#include <cstdio>
#include <string>
#include "whizard.h"
int main( int argc, char* argv[] )
{
// WHIZARD and event-sample objects
Whizard* whizard;
WhizardSample* sample;
// Local variables
double integral, error;
double sqme, weight;
int idx;
int it, it_begin, it_end;
// Initialize WHIZARD, setting some global option
whizard = new Whizard();
whizard->option( "model", "QED" );
whizard->init();
// Define a process, set some variables
whizard->command( "process mupair = e1, E1 => e2, E2" );
whizard->set_double( "sqrts", 10. );
whizard->set_int( "seed", 0 );
// Generate matrix-element code, integrate and retrieve result
whizard->command( "integrate (mupair)" );
// Print result
whizard->get_integration_result( "mupair", &integral, &error );
printf( " cross section = %5.1f pb\n", integral / 1000. );
printf( " error = %5.1f pb\n", error / 1000. );
// Settings for event generation
whizard->set_string( "$sample", "mupair_events" );
whizard->set_int( "n_events", 2 );
// Create an event-sample object and generate events
sample = whizard->new_sample( "mupair" );
sample->open( &it_begin, &it_end );
for (it=it_begin; it<=it_end; it++) {
sample->next_event();
idx = sample->get_event_index();
weight = sample->get_weight();
sqme = sample->get_sqme();
printf( "Event #%d\n", idx );
printf( " sqme = %10.3e\n", sqme );
printf( " weight = %10.3e\n", weight );
}
// Finalize the event-sample object
sample->close();
delete sample;
// Finalize the WHIZARD object
delete whizard;
}
\end{code}
\subsubsection{Header}
The necessary declarations are imported by the directive
\begin{quote}
\tt \#include "whizard.h"
\end{quote}
\subsubsection{Master object}
All functionality is accessed via a master API object which should be declared
as follows:
\begin{quote}
\tt Whizard* whizard;
\end{quote}
The constructor takes no arguments:
\begin{quote}
\tt whizard = new Whizard();
\end{quote}
There should be only one master object.
\subsubsection{Pre-Initialization options}
Before initializing the API object, it is possible to provide options. The
available options mirror the command-line options of the stand-alone program,
cf.\ Sec.~\ref{sec:cmdline-options}.
\begin{quote}
\tt whizard->option( \textit{key}, \textit{value} );
\end{quote}
All keys and values are \cpp\ strings. The available options are
listed above in the \fortran\ interface documentation.
\subsubsection{Initialization and finalization}
After options have been set, the system is initialized via
\begin{quote}
\tt whizard->init();
\end{quote}
Once initialized, \whizard\ can execute commands as listed below. When all
is complete, delete the \whizard\ object. This will call the destructor that
correctly finalizes the \whizard\ workflow.
\subsubsection{Variables and values}
In the API, \whizard\ requires numeric data types according to the IEEE
standard. Integers map to C \ttt{int}, and real values map to C
\ttt{double}. Logical values map to C \ttt{int} interpreted as \ttt{bool},
and string values map to \cpp\ \ttt{string}.
To set a \sindarin\ variable of appropriate type:
\begin{quote}
\tt whizard->set\_int ( \textit{name}, \textit{value} );
\\
\tt whizard->set\_double ( \textit{name}, \textit{value} );
\\
\tt whizard->set\_bool ( \textit{name}, \textit{value} );
\\
\tt whizard->set\_string ( \textit{name}, \textit{value} );
\end{quote}
\textit{name} is a \cpp\ string value. It must match the corresponding
\sindarin\ variable name, including any prefix character (\$ or ?).
\textit{value} is a \ttt{double/int/string}, respectively.
To retrieve the current value of a variable:
\begin{quote}
\tt whizard->get\_int ( \textit{name}, \&\textit{var} );
\\
\tt whizard->get\_double ( \textit{name}, \&\textit{var} );
\\
\tt whizard->get\_bool ( \textit{name}, \&\textit{var} );
\\
\tt whizard->get\_string ( \textit{name}, \&\textit{var} );
\end{quote}
Here, \ttt{\it var} is a C variable of appropriate type. The functions return
zero if the \sindarin\ variable has a known value.
\subsubsection{Commands}
Any \sindarin\ command can be called via
\begin{quote}
\tt whizard->command( \textit{command} );
\end{quote}
\ttt{\it command} is a \cpp\ string value that contains commands as they
would appear in a \sindarin\ script.
This includes, in particular, the important commands \ttt{process},
\ttt{integrate}, and \ttt{simulate}. You may also set variables that way.
\subsubsection{Retrieving cross-section results}
This call returns the results (integration and error) from a preceding
integration run for the process \textit{process-name}:
\begin{quote}
\tt whizard->get\_integration\_result( "\textit{process-name}",
\&\textit{integral}, \&\textit{error} );
\end{quote}
\ttt{\it integral} and \ttt{\it error} are variables of type \ttt{double}.
The function returns zero if the integration run was successful, so integral
and error are meaningful.
\subsubsection{Event-sample object}
A \ttt{simulate} command will produce an event sample. With the appropriate
settings, the sample will be written to file in any chosen format, to be
post-processed when it is complete.
However, a possible purpose of using the \whizard\ API is to process events one-by-one
when they are generated. To this end, there is an event-sample handle, which
can be declared in this way:
\begin{quote}
\tt WhizardSample* {sample};
\end{quote}
An instance \ttt{\it sample} of this type is created by this factory method:
\begin{quote}
\tt {sample} = whizard->new\_sample( "\textit{process-name(s)}" );
\end{quote}
The command accepts a comma-separated list of process names which should be
included in the event sample.
To start event generation for this sample, call
\begin{quote}
\tt sample->open( \&\textit{it\_begin},
\&\textit{it\_end});
\end{quote}
where the two output variables (\ttt{int}) \ttt{\it it\_begin} and
\ttt{\it it\_end}
provide the bounds for an event loop in the calling program. (In serial mode,
the bounds are equal to 1 and \ttt{n\_events}, respectively, but in an MPI
parallel environment, they depend on the computing node.)
This command generates a new event, to be enclosed within an event loop:
\begin{quote}
\tt sample->next\_event();
\end{quote}
The event will be available by format-specific access methods, see below.
This command closes and deletes an event sample after the event loop has
completed:
\begin{quote}
\tt sample->close();
\end{quote}
\subsubsection{Retrieving event data}
After a call to \ttt{sample->next\_event}, the sample object can be
queried for specific event data.
\begin{quote}
\tt value = sample->get\_event\_index();
\\
\tt value = sample->get\_process\_index();
\\
\tt value = sample->get\_process\_id();
\\
\tt value = sample->get\_sqrts();
\\
\tt value = sample->get\_fac\_scale();
\\
\tt value = sample->get\_alpha\_s();
\\
\tt value = sample->get\_sqme();
\\
\tt value = sample->get\_weight();
\end{quote}
where the \ttt{\it value} is a variable of appropriate type (see above).
Event data are stored in a format-specific way. This may be a \hepmc\ or
\lcio\ \cpp\ event record.
For interfacing with the \hepmc\ event record, the appropriate declarations
must be in place, e.g.,
\begin{quote}
\tt \#include "HepMC/GenEvent.h"
\\
using namespace HepMC;
\end{quote}
An event-record object must be declared,
\begin{quote}
\tt GenEvent* evt;
\end{quote}
and the \whizard\ event call must take the event as an argument
\begin{quote}
\tt sample->next\_event ( \&evt );
\end{quote}
This will create a new \ttt{evt} object.
Then, the \hepmc\ event record can be accessed via its own methods. After
an event has been processed, the event record should be deleted
\begin{quote}
\tt delete evt;
\end{quote}
Analogously, for interfacing with the \lcio\ event record, the appropriate declarations
must be in place, e.g.,
\begin{quote}
\tt
\#include "lcio.h"
\\
\#include "IMPL/LCEventImpl.h"
\\
using namespace lcio;
\end{quote}
An event-record object must be declared,
\begin{quote}
\tt LCEvent* evt;
\end{quote}
and the \whizard\ event call must take the event as an argument
\begin{quote}
\tt sample->next\_event ( \&evt );
\end{quote}
This will create a new \ttt{evt} object.
Then, the \lcio\ event record can be accessed via its own methods. After
an event has been processed, the event record should be deleted
\begin{quote}
\tt delete evt;
\end{quote}
\subsection{Python main program}
To create a \python\ executable, \whizard\ provides a \ttt{Cython}
interface that uses \cpp\ bindings to link a dynamic library which can
then be loaded as a module via \python. Note that \whizard's
\ttt{Cython}/\python\ interface only works with \python\ttt{v3}. Also
make sure that you do not mix different \python\ versions when linking
external programs which also provide \python\ interfaces like
\hepmc\ or \lcio.
To link a \python\ main program with the \whizard\ library, the following steps
must be performed:
\begin{enumerate}
\item
Configure, build and install \whizard\ as normal.
\item
Include code for accessing \whizard\ functionality in the user program.
The code should initialize
\whizard, execute the intended commands, and finalize. For an example, see
below.
\item
Run \python\ on the user program. Make sure that the operating
system finds the \whizard\ \python\ and library path.
If \whizard\ has been installed in a non-default \ttt{whizard-path}, these
are the options:
\begin{code}
export PYTHONPATH=whizard-path/lib/python/site-packages/:$PYTHONPATH
\end{code}
If necessary, provide the path to the installed shared
libraries. For instance, if \whizard\ has been installed in
\ttt{whizard-path}, this should read
\begin{code}
export LD_LIBRARY_PATH="whizard-path/lib:$LD_LIBRARY_PATH"
\end{code}
On some systems, you may have to replace \ttt{lib} by \ttt{lib64}, as above.
The \whizard\ subsystem will work with input and output
files in the current working directory, unless asked to do otherwise.
\item
The \ttt{tirpc} library is used by the \ttt{StdHEP} subsystem for \ttt{xdr}
functionality. This
library should be present on the host system.
\item
Run the program.
\end{enumerate}
Below is an example program, similar to \whizard's internal unit-test
suite for different external programming languages. The user program
controls the \whizard\ workflow in the same way as a \sindarin\ script
would do. The commands are a mixture of \sindarin\ command
calls and functionality for passing information between the \whizard\
subsystem and the host program.
In particular, the program can process generated events one-by-one.
\begin{code}
import whizard
wz = whizard.Whizard()
wz.option("logfile", "whizard_1_py.log")
wz.option("job_id", "whizard_1_py_ID")
wz.option("library", "whizard_1_py_1_lib")
wz.option("model", "QED")
wz.init()
wz.set_double("sqrts", 100)
wz.set_int("n_events", 3)
wz.set_bool("?unweighted", True)
wz.set_string("$sample", "foobar")
wz.set_int("seed", 0)
wz.command("process whizard_1_py_1_p = e1, E1 => e2, E2")
wz.command("iterations = 1:100")
integral, error = wz.get_integration_result("whizard_1_py_1_p")
print(integral, error)
wz.command("integrate (whizard_1_py_1_p)")
sqrts = wz.get_double("sqrts")
print(f"sqrts = {sqrts:5.1f} GeV")
print(f"sigma = integral:5.1f} pb")
print(f"error {error:5.1f} pb")
sample = wz.new_sample("whizard_1_py_p1, whizard_1_py_p2, whizard_1_py_p3")
it_begin, it_end = sample.open()
for it in range(it_begin, it_end + 1):
sample.next_event()
idx = sample.get_event_index()
i_proc = sample.get_process_index()
proc_id = sample.get_process_id()
f_scale = sample.get_fac_scale()
alpha_s = sample.get_alpha_s()
weight = sample.get_weight()
sqme = sample.get_sqme()
print(f"Event #{idx}")
print(f" process #{i_proc}")
print(f" proc_id = {proc_id}")
print(f" f_scale = {f_scale:10.3e}")
print(f" alpha_s = {f_scale:10.3e}")
print(f" sqme = {f_scale:10.3e}")
print(f" weight = {f_scale:10.3e}")
sample.close()
del(wz)
\end{code}
\subsubsection{Python module import}
There are no necessary headers here as all of this information has
been automatically taken care by the \ttt{Cython} interface layer. The
\whizard\ module needs to be imported by \python\:
\begin{quote}
\tt import whizard
\end{quote}
\subsubsection{Master object}
All functionality is accessed via a master API object which should be declared
as follows:
\begin{quote}
\tt wz = whizard.Whizard()
\end{quote}
The constructor takes no arguments.There should be only one master
object.
\subsubsection{Pre-Initialization options}
Before initializing the API object, it is possible to provide options. The
available options mirror the command-line options of the stand-alone program,
cf.\ Sec.~\ref{sec:cmdline-options}.
\begin{quote}
\tt wz.option( \textit{key}, \textit{value} );
\end{quote}
All keys and values are \python\ strings. The available options are
listed above in the \fortran\ interface documentation.
\subsubsection{Initialization and finalization}
After options have been set, the system is initialized via
\begin{quote}
\tt wz.init()
\end{quote}
Once initialized, \whizard\ can execute commands as listed below. When all
is complete, delete the \whizard\ object. This will call the destructor that
correctly finalizes the \whizard\ workflow.
\subsubsection{Variables and values}
In the API, \whizard\ requires numeric data types according to the IEEE
standard. Integers map to \ttt{Python int}, and real values map to \ttt{Python
double}. Logical values map to \ttt{True} and \ttt{False},
and string values map to \python\ strings.
To set a \sindarin\ variable of appropriate type:
\begin{quote}
\tt wz.set\_int ( \textit{name}, \textit{value} );
\\
\tt wz.set\_double ( \textit{name}, \textit{value} );
\\
\tt wz.set\_bool ( \textit{name}, \textit{value} );
\\
\tt wz.set\_string ( \textit{name}, \textit{value} );
\end{quote}
\textit{name} is a \python\ string value. It must match the corresponding
\sindarin\ variable name, including any prefix character (\$ or ?).
\textit{value} is a \ttt{double/int/string}, respectively.
To retrieve the current value of a variable:
\begin{quote}
\tt wz.get\_int ( \textit{name}, \textit{var} );
\\
\tt wz.get\_double ( \textit{name}, \textit{var} );
\\
\tt wz.get\_bool ( \textit{name}, \textit{var} );
\\
\tt wz.get\_string ( \textit{name}, \textit{var} );
\end{quote}
Here, \ttt{\it var} is a \python\ variable of appropriate type. The
functions return zero if the \sindarin\ variable has a known value.
\subsubsection{Commands}
Any \sindarin\ command can be called via
\begin{quote}
\tt wz.command( \textit{command} );
\end{quote}
\ttt{\it command} is a \python\ string value that contains commands as they
would appear in a \sindarin\ script.
This includes, in particular, the important commands \ttt{process},
\ttt{integrate}, and \ttt{simulate}. You may also set variables that way.
\subsubsection{Retrieving cross-section results}
This call returns the results (integration and error) from a preceding
integration run for the process \textit{process-name}:
\begin{quote}
\tt wz.get\_integration\_result( "\textit{process-name}",
\textit{integral}, \textit{error} );
\end{quote}
\ttt{\it integral} and \ttt{\it error} are variables of type \ttt{double}.
The function returns zero if the integration run was successful, so integral
and error are meaningful.
\subsubsection{Event-sample object}
A \ttt{simulate} command will produce an event sample. With the appropriate
settings, the sample will be written to file in any chosen format, to be
post-processed when it is complete.
However, a possible purpose of using the \whizard\ API is to process events one-by-one
when they are generated. To this end, there is an event-sample handle, which
can be declared in this way:
\begin{quote}
\tt WhizardSample* {sample};
\end{quote}
An instance \ttt{\it sample} of this type is created by this factory method:
\begin{quote}
\tt {sample} = wz.new\_sample( "\textit{process-name(s)}" );
\end{quote}
The command accepts a comma-separated list of process names which should be
included in the event sample.
To start event generation for this sample, call
\begin{quote}
\tt \textit{it\_begin}, \textit{it\_end} = wz.sample\_open()
\end{quote}
where the two output variables (\ttt{int}) \ttt{\it it\_begin} and
\ttt{\it it\_end}
provide the bounds for an event loop in the calling program. (In serial mode,
the bounds are equal to 1 and \ttt{n\_events}, respectively, but in an MPI
parallel environment, they depend on the computing node.)
This command generates a new event, to be enclosed within an event loop:
\begin{quote}
\tt sample.next\_event();
\end{quote}
The event will be available by format-specific access methods, see below.
This command closes and deletes an event sample after the event loop has
completed:
\begin{quote}
\tt sample.close();
\end{quote}
\subsubsection{Retrieving event data}
After a call to \ttt{sample.next\_event}, the sample object can be
queried for specific event data.
\begin{quote}
\tt value = sample.get\_event\_index();
\\
\tt value = sample.get\_process\_index();
\\
\tt value = sample.get\_process\_id();
\\
\tt value = sample.get\_sqrts();
\\
\tt value = sample.get\_fac\_scale();
\\
\tt value = sample.get\_alpha\_s();
\\
\tt value = sample.get\_sqme();
\\
\tt value = sample.get\_weight();
\end{quote}
where the \ttt{\it value} is a variable of appropriate type (see above).
Event data are stored in a format-specific way. This may be a \hepmc\ or
\lcio\ \cpp\ event record, or some formats supported by
\whizard\ intrinsically like LHEF etc.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Examples}
\label{chap:examples}
In this chapter we discuss the running and steering of \whizard\ with
the help of several examples. These examples can be found in the
\ttt{share/examples} directory of your installation. All of these
examples are also shown on the \whizard\ Wiki page:
\url{https://whizard.hepforge.org/trac/wiki}.
\section{$Z$ lineshape at LEP I}
By this example, we demonstrate how a scan over collision energies
works, using as example the measurement of the $Z$ lineshape at LEP I
in 1989. The \sindarin\ script for this example, \ttt{Z-lineshape.sin}
can be found in the \ttt{share/examples} folder of the \whizard\
installation.
We first use the Standard model as physics model:
\begin{code}
model = SM
\end{code}
Aliases for electron, muon and their antiparticles as leptons and
those including the photon as particles in general are introduced:
\begin{code}
alias lep = e1:E1:e2:E2
alias prt = lep:A
\end{code}
Next, the two processes are defined, \eemm, and the same with an
explicit QED photon: $e^+e^- \to \mu^+\mu^-\gamma$,
\begin{code}
process bornproc = e1, E1 => e2, E2
process rc = e1, E1 => e2, E2, A
compile
\end{code}
and the processes are compiled. Now, we define some very loose cuts to
avoid singular regions in phase space, name an infrared cutoff of 100
MeV for all particles, a cut on the angular separation from the beam
axis and a di-particle invariant mass cut which regularizes collinear
singularities:
\begin{code}
cuts = all E >= 100 MeV [prt]
and all abs (cos(Theta)) <= 0.99 [prt]
and all M2 >= (1 GeV)^2 [prt, prt]
\end{code}
For the graphical analysis, we give a description and labels for the
$x$- and $y$-axis in \LaTeX\ syntax:
\begin{code}
$description = "A WHIZARD Example"
$x_label = "$\sqrt{s}$/GeV"
$y_label = "$\sigma(s)$/pb"
\end{code}
We define two plots for the lineshape of the \eemm\ process between 88
and 95 GeV,
\begin{code}
$title = "The Z Lineshape in $e^+e^-\to\mu^+\mu^-$"
plot lineshape_born { x_min = 88 GeV x_max = 95 GeV }
\end{code}
and the same for the radiative process with an additional photon:
\begin{code}
$title = "The Z Lineshape in $e^+e^-\to\mu^+\mu^-\gamma$"
plot lineshape_rc { x_min = 88 GeV x_max = 95 GeV }
\end{code}
%$
The next part of the \sindarin\ file actually performs the scan:
\begin{code}
scan sqrts = ((88.0 GeV => 90.0 GeV /+ 0.5 GeV),
(90.1 GeV => 91.9 GeV /+ 0.1 GeV),
(92.0 GeV => 95.0 GeV /+ 0.5 GeV)) {
beams = e1, E1
integrate (bornproc) { iterations = 2:1000:"gw", 1:2000 }
record lineshape_born (sqrts, integral (bornproc) / 1000)
integrate (rc) { iterations = 5:3000:"gw", 2:5000 }
record lineshape_rc (sqrts, integral (rc) / 1000)
}
\end{code}
So from 88 to 90 GeV, we go in 0.5 GeV steps, then from 90 to 92 GeV
in tenth of GeV, and then up to 95 GeV again in half a GeV steps. The
partonic beam definition is redundant. Then, the born process is
integrated, using a certain specification of calls with adaptation of
grids and weights, as well as a final pass. The lineshape of the Born
process is defined as a \ttt{record} statement, generating tuples of
$\sqrt{s}$ and the Born cross section (converted from femtobarn to
picobarn). The same happens for the radiative $2\to3$ process with a
bit more iterations because of the complexity, and the definition of
the corresponding lineshape record.
If you run the \sindarin\ script, you will find an output like:
\begin{scriptsize}
\begin{Verbatim}[frame=single]
| Process library 'default_lib': loading
| Process library 'default_lib': ... success.
$description = "A WHIZARD Example"
$x_label = "$\sqrt{s}$/GeV"
$y_label = "$\sigma(s)$/pb"
$title = "The Z Lineshape in $e^+e^-\to\mu^+\mu^-$"
x_min = 8.800000000000E+01
x_max = 9.500000000000E+01
$title = "The Z Lineshape in $e^+e^-\to\mu^+\mu^-\gamma$"
x_min = 8.800000000000E+01
x_max = 9.500000000000E+01
sqrts = 8.800000000000E+01
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 10713
| Initializing integration for process bornproc:
| ------------------------------------------------------------------------
| Process [scattering]: 'bornproc'
| Library name = 'default_lib'
| Process index = 1
| Process components:
| 1: 'bornproc_i1': e-, e+ => mu-, mu+ [omega]
| ------------------------------------------------------------------------
| Beam structure: e-, e+
| Beam data (collision):
| e- (mass = 5.1099700E-04 GeV)
| e+ (mass = 5.1099700E-04 GeV)
| sqrts = 8.800000000000E+01 GeV
| Phase space: generating configuration ...
| Phase space: ... success.
| Phase space: writing configuration file 'bornproc_i1.phs'
| Phase space: 1 channels, 2 dimensions
| Phase space: found 1 channel, collected in 1 grove.
| Phase space: Using 1 equivalence between channels.
| Phase space: wood
| Applying user-defined cuts.
| OpenMP: Using 8 threads
| Starting integration for process 'bornproc'
| Integrate: iterations = 2:1000:"gw", 1:2000
| Integrator: 1 chains, 1 channels, 2 dimensions
| Integrator: Using VAMP channel equivalences
| Integrator: 1000 initial calls, 20 bins, stratified = T
| Integrator: VAMP
|=============================================================================|
| It Calls Integral[fb] Error[fb] Err[%] Acc Eff[%] Chi2 N[It] |
|=============================================================================|
1 800 2.5881432E+05 1.85E+03 0.72 0.20* 48.97
2 800 2.6368495E+05 9.25E+02 0.35 0.10* 28.32
|-----------------------------------------------------------------------------|
2 1600 2.6271122E+05 8.28E+02 0.32 0.13 28.32 5.54 2
|-----------------------------------------------------------------------------|
3 1988 2.6313791E+05 5.38E+02 0.20 0.09* 35.09
|-----------------------------------------------------------------------------|
3 1988 2.6313791E+05 5.38E+02 0.20 0.09 35.09
|=============================================================================|
| Time estimate for generating 10000 events: 0d:00h:00m:05s
[.......]
\end{Verbatim}
\end{scriptsize} %$
and then the integrations for the other energy points of the scan will
\begin{figure}
\centering
\includegraphics[width=.47\textwidth]{Z-lineshape_1}
\includegraphics[width=.47\textwidth]{Z-lineshape_2}
\caption{\label{fig:zlineshape} $Z$ lineshape in the dimuon final
state (left), and with an additional photon (right)}
\end{figure}
follow, and finally the same is done for the radiative process as
well. At the end of the \sindarin\ script we compile the graphical
\whizard\ analysis and direct the data for the plots into the file
\ttt{Z-lineshape.dat}:
\begin{code}
compile_analysis { $out_file = "Z-lineshape.dat" }
\end{code}
%$
In this case there is no event generation, but simply the cross
section values for the scan are dumped into a data file:
\begin{scriptsize}
\begin{Verbatim}[frame=single]
$out_file = "Z-lineshape.dat"
| Opening file 'Z-lineshape.dat' for output
| Writing analysis data to file 'Z-lineshape.dat'
| Closing file 'Z-lineshape.dat' for output
| Compiling analysis results display in 'Z-lineshape.tex'
\end{Verbatim}
\end{scriptsize}
%$
Fig.~\ref{fig:zlineshape} shows the graphical \whizard\ output of the
$Z$ lineshape in the dimuon final state from the scan on the left, and
the same for the radiative process with an additional photon on the
right.
%%%%%%%%%%%%%%%
\section{$W$ pairs at LEP II}
This example which can be found as file \ttt{LEP\_cc10.sin} in the
\ttt{share/examples} directory, shows $W$ pair production in the
semileptonic mode at LEP II with its final energy of 209 GeV. Because
there are ten contributing Feynman diagrams, the process has been
dubbed CC10: charged current process with 10 diagrams. We work within
the Standard Model:
\begin{code}
model = SM
\end{code}
Then the process is defined, where no flavor summation is done for the
jets here:
\begin{code}
process cc10 = e1, E1 => e2, N2, u, D
\end{code}
A compilation statement is optional, and then we set the muon mass to
zero:
\begin{code}
mmu = 0
\end{code}
The final LEP center-of-momentum energy of 209 GeV is set:
\begin{code}
sqrts = 209 GeV
\end{code}
Then, we integrate the process:
\begin{code}
integrate (cc10) { iterations = 12:20000 }
\end{code}
Running the \sindarin\ file up to here, results in the output:
\begin{scriptsize}
\begin{Verbatim}[frame=single]
| Process library 'default_lib': loading
| Process library 'default_lib': ... success.
SM.mmu = 0.000000000000E+00
sqrts = 2.090000000000E+02
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 31255
| Initializing integration for process cc10:
| ------------------------------------------------------------------------
| Process [scattering]: 'cc10'
| Library name = 'default_lib'
| Process index = 1
| Process components:
| 1: 'cc10_i1': e-, e+ => mu-, numubar, u, dbar [omega]
| ------------------------------------------------------------------------
| Beam structure: [any particles]
| Beam data (collision):
| e- (mass = 5.1099700E-04 GeV)
| e+ (mass = 5.1099700E-04 GeV)
| sqrts = 2.090000000000E+02 GeV
| Phase space: generating configuration ...
| Phase space: ... success.
| Phase space: writing configuration file 'cc10_i1.phs'
| Phase space: 25 channels, 8 dimensions
| Phase space: found 25 channels, collected in 7 groves.
| Phase space: Using 25 equivalences between channels.
| Phase space: wood
Warning: No cuts have been defined.
| OpenMP: Using 8 threads
| Starting integration for process 'cc10'
| Integrate: iterations = 12:20000
| Integrator: 7 chains, 25 channels, 8 dimensions
| Integrator: Using VAMP channel equivalences
| Integrator: 20000 initial calls, 20 bins, stratified = T
| Integrator: VAMP
|=============================================================================|
| It Calls Integral[fb] Error[fb] Err[%] Acc Eff[%] Chi2 N[It] |
|=============================================================================|
1 19975 6.4714908E+02 2.17E+01 3.36 4.75* 2.33
2 19975 7.3251876E+02 2.45E+01 3.34 4.72* 2.17
3 19975 6.7746497E+02 2.39E+01 3.52 4.98 1.77
4 19975 7.2075198E+02 2.41E+01 3.34 4.72* 1.76
5 19975 6.5976152E+02 2.26E+01 3.43 4.84 1.46
6 19975 6.6633310E+02 2.26E+01 3.39 4.79* 1.43
7 19975 6.7539385E+02 2.29E+01 3.40 4.80 1.43
8 19975 6.6754027E+02 2.11E+01 3.15 4.46* 1.41
9 19975 7.3975817E+02 2.52E+01 3.40 4.81 1.53
10 19975 7.2284275E+02 2.39E+01 3.31 4.68* 1.47
11 19975 6.5476917E+02 2.18E+01 3.33 4.71 1.33
12 19975 7.2963866E+02 2.54E+01 3.48 4.92 1.46
|-----------------------------------------------------------------------------|
12 239700 6.8779583E+02 6.69E+00 0.97 4.76 1.46 2.18 12
|=============================================================================|
| Time estimate for generating 10000 events: 0d:00h:01m:16s
| Creating integration history display cc10-history.ps and cc10-history.pdf
\end{Verbatim}
\end{scriptsize}
\begin{figure}
\centering
\includegraphics[width=.6\textwidth]{cc10_1}
\\\vspace{5mm}
\includegraphics[width=.6\textwidth]{cc10_2}
\caption{Histogram of the dijet invariant mass from the CC10 $W$
pair production at LEP II, peaking around the $W$ mass (upper
plot), and of the muon energy (lower plot).}
\label{fig:cc10}
\end{figure}
The next step is event generation. In order to get smooth
distributions, we set the integrated luminosity to 10
fb${}^{-1}$. (Note that LEP II in its final year 2000 had an
integrated luminosity of roughly 0.2 fb${}^{-1}$.)
\begin{code}
luminosity = 10
\end{code}
With the simulated events corresponding to those 10 inverse femtobarn
we want to perform a \whizard\ analysis: we are going to plot the
dijet invariant mass, as well as the energy of the outgoing muon. For
the plot of the analysis, we define a description and label the $y$
axis:
\begin{code}
$description =
"A WHIZARD Example.
Charged current CC10 process from LEP 2."
$y_label = "$N_{\textrm{events}}$"
\end{code}
We also use \LaTeX-syntax for the title of the first plot and the
$x$-label, and then define the histogram of the dijet invariant mass
in the range around the $W$ mass from 70 to 90 GeV in steps of half a
GeV:
\begin{code}
$title = "Di-jet invariant mass $M_{jj}$ in $e^+e^- \to \mu^- \bar\nu_\mu u \bar d$"
$x_label = "$M_{jj}$/GeV"
histogram m_jets (70 GeV, 90 GeV, 0.5 GeV)
\end{code}
And we do the same for the second histogram of the muon energy:
\begin{code}
$title = "Muon energy $E_\mu$ in $e^+e^- \to \mu^- \bar\nu_\mu u \bar d$"
$x_label = "$E_\mu$/GeV"
histogram e_muon (0 GeV, 209 GeV, 4)
\end{code}
Now, we define the \ttt{analysis} consisting of two \ttt{record}
statements initializing the two observables that are plotted as
histograms:
\begin{code}
analysis = record m_jets (eval M [u,D]);
record e_muon (eval E [e2])
\end{code}
At the very end, we perform the event generation
\begin{code}
simulate (cc10)
\end{code}
and finally the writing and compilation of the analysis in a named
data file:
\begin{code}
compile_analysis { $out_file = "cc10.dat" }
\end{code}
This event generation part screen output looks like this:
\begin{scriptsize}
\begin{Verbatim}[frame=single]
luminosity = 1.000000000000E+01
$description = "A WHIZARD Example.
Charged current CC10 process from LEP 2."
$y_label = "$N_{\textrm{events}}$"
$title = "Di-jet invariant mass $M_{jj}$ in $e^+e^- \to \mu^- \bar\nu_\mu u \bar d$"
$x_label = "$M_{jj}$/GeV"
$title = "Muon energy $E_\mu$ in $e^+e^- \to \mu^- \bar\nu_\mu u \bar d$"
$x_label = "$E_\mu$/GeV"
| Starting simulation for process 'cc10'
| Simulate: using integration grids from file 'cc10_m1.vg'
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 9910
| OpenMP: Using 8 threads
| Simulation: using n_events as computed from luminosity value
| Events: writing to raw file 'cc10.evx'
| Events: generating 6830 unweighted, unpolarized events ...
| Events: event normalization mode '1'
| ... event sample complete.
Warning: Encountered events with excess weight: 39 events ( 0.571 %)
| Maximum excess weight = 1.027E+00
| Average excess weight = 6.764E-04
| Events: closing raw file 'cc10.evx'
$out_file = "cc10.dat"
| Opening file 'cc10.dat' for output
| Writing analysis data to file 'cc10.dat'
| Closing file 'cc10.dat' for output
| Compiling analysis results display in 'cc10.tex'
\end{Verbatim}
\end{scriptsize} %$
Then comes the \LaTeX\ output of the compilation of the graphical
analysis. Fig.~\ref{fig:cc10} shows the two histograms as the are
produced as result of the \whizard\ internal graphical analysis.
%%%%%%%%%%%%%%%
\section{Higgs search at LEP II}
This example can be found under the name \ttt{LEP\_higgs.sin} in the
\ttt{share/doc} folder of \whizard. It displays different search
channels for a very light would-be SM Higgs boson of mass 115 GeV at
the LEP II machine at its highest energy it finally achieved, 209 GeV.
First, we use the Standard Model:
\begin{code}
model = SM
\end{code}
Then, we define aliases for neutrinos, antineutrinos, light quarks and
light anti-quarks:
\begin{code}
alias n = n1:n2:n3
alias N = N1:N2:N3
alias q = u:d:s:c
alias Q = U:D:S:C
\end{code}
Now, we define the signal process, which is Higgsstrahlung,
\begin{code}
process zh = e1, E1 => Z, h
\end{code}
the missing-energy channel,
\begin{code}
process nnbb = e1, E1 => n, N, b, B
\end{code}
and finally the 4-jet as well as dilepton-dijet channels:
\begin{code}
process qqbb = e1, E1 => q, Q, b, B
process bbbb = e1, E1 => b, B, b, B
process eebb = e1, E1 => e1, E1, b, B
process qqtt = e1, E1 => q, Q, e3, E3
process bbtt = e1, E1 => b, B, e3, E3
compile
\end{code}
and we compile the code. We set the center-of-momentum energy to the
highest energy LEP II achieved,
\begin{code}
sqrts = 209 GeV
\end{code}
For the Higgs boson, we take the values of a would-be SM Higgs boson
with mass of 115 GeV, which would have had a width of a bit more than
3 MeV:
\begin{code}
mH = 115 GeV
wH = 3.228 MeV
\end{code}
We take a running $b$ quark mass to take into account NLO corrections
to the $Hb\bar b$ vertex, while all other fermions are massless:
\begin{code}
mb = 2.9 GeV
me = 0
ms = 0
mc = 0
\end{code}
\begin{scriptsize}
\begin{Verbatim}[frame=single]
| Process library 'default_lib': loading
| Process library 'default_lib': ... success.
sqrts = 2.090000000000E+02
SM.mH = 1.150000000000E+02
SM.wH = 3.228000000000E-03
SM.mb = 2.900000000000E+00
SM.me = 0.000000000000E+00
SM.ms = 0.000000000000E+00
SM.mc = 0.000000000000E+00
\end{Verbatim}
\end{scriptsize}
To avoid soft-collinear singular phase-space regions, we apply an
invariant mass cut on light quark pairs:
\begin{code}
cuts = all M >= 10 GeV [q,Q]
\end{code}
Now, we integrate the signal process as well as the combined signal
and background processes:
\begin{code}
integrate (zh) { iterations = 5:5000}
integrate(nnbb,qqbb,bbbb,eebb,qqtt,bbtt) { iterations = 12:20000 }
\end{code}
\begin{scriptsize}
\begin{Verbatim}[frame=single]
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 21791
| Initializing integration for process zh:
| ------------------------------------------------------------------------
| Process [scattering]: 'zh'
| Library name = 'default_lib'
| Process index = 1
| Process components:
| 1: 'zh_i1': e-, e+ => Z, H [omega]
| ------------------------------------------------------------------------
| Beam structure: [any particles]
| Beam data (collision):
| e- (mass = 0.0000000E+00 GeV)
| e+ (mass = 0.0000000E+00 GeV)
| sqrts = 2.090000000000E+02 GeV
| Phase space: generating configuration ...
| Phase space: ... success.
| Phase space: writing configuration file 'zh_i1.phs'
| Phase space: 1 channels, 2 dimensions
| Phase space: found 1 channel, collected in 1 grove.
| Phase space: Using 1 equivalence between channels.
| Phase space: wood
| Applying user-defined cuts.
| OpenMP: Using 8 threads
| Starting integration for process 'zh'
| Integrate: iterations = 5:5000
| Integrator: 1 chains, 1 channels, 2 dimensions
| Integrator: Using VAMP channel equivalences
| Integrator: 5000 initial calls, 20 bins, stratified = T
| Integrator: VAMP
|=============================================================================|
| It Calls Integral[fb] Error[fb] Err[%] Acc Eff[%] Chi2 N[It] |
|=============================================================================|
1 4608 1.6114109E+02 5.52E-04 0.00 0.00* 99.43
2 4608 1.6114220E+02 5.59E-04 0.00 0.00 99.43
3 4608 1.6114103E+02 5.77E-04 0.00 0.00 99.43
4 4608 1.6114111E+02 5.74E-04 0.00 0.00* 99.43
5 4608 1.6114103E+02 5.66E-04 0.00 0.00* 99.43
|-----------------------------------------------------------------------------|
5 23040 1.6114130E+02 2.53E-04 0.00 0.00 99.43 0.82 5
|=============================================================================|
[.....]
\end{Verbatim}
\end{scriptsize}
\begin{figure}
\centering
\includegraphics[width=.48\textwidth]{lep_higgs_1}
\includegraphics[width=.48\textwidth]{lep_higgs_2}
\\\vspace{5mm}
\includegraphics[width=.48\textwidth]{lep_higgs_3}
\caption{Upper line: final state $bb + E_{miss}$, histogram of
the invisible mass distribution (left), and of the di-$b$
distribution (right). Lower plot: light dijet distribution in the
$bbjj$ final state.}
\label{fig:lep_higgs}
\end{figure}
Because the other integrations look rather similar, we refrain from
displaying them here, too. As a next step, we define titles,
descriptions and axis labels for the histograms we want to
generate. There are two of them, one os the invisible mass
distribution, the other is the di-$b$-jet invariant mass. Both
histograms are taking values between 70 and 130 GeV with
bin widths of half a GeV:
\begin{code}
$description =
"A WHIZARD Example. Light Higgs search at LEP. A 115 GeV pseudo-Higgs
has been added. Luminosity enlarged by two orders of magnitude."
$y_label = "$N_{\textrm{events}}$"
$title = "Invisible mass distribution in $e^+e^- \to \nu\bar\nu b \bar b$"
$x_label = "$M_{\nu\nu}$/GeV"
histogram m_invisible (70 GeV, 130 GeV, 0.5 GeV)
$title = "$bb$ invariant mass distribution in $e^+e^- \to \nu\bar\nu b \bar b$"
$x_label = "$M_{b\bar b}$/GeV"
histogram m_bb (70 GeV, 130 GeV, 0.5 GeV)
\end{code}
The analysis is initialized by defining the two records for the
invisible mass and the invariant mass of the two $b$ jets:
\begin{code}
analysis = record m_invisible (eval M [n,N]);
record m_bb (eval M [b,B])
\end{code}
In order to have enough statistics, we enlarge the LEP integrated
luminosity at 209 GeV by more than two orders of magnitude:
\begin{code}
luminosity = 10
\end{code}
We start event generation by simulating the process with two $b$ jets
and two neutrinos in the final state:
\begin{code}
simulate (nnbb)
\end{code}
As a third histogram, we define the dijet invariant mass of two light
jets:
\begin{code}
$title = "Dijet invariant mass distribution in $e^+e^- \to q \bar q b \bar b$"
$x_label = "$M_{q\bar q}$/GeV"
histogram m_jj (70 GeV, 130 GeV, 0.5 GeV)
\end{code}
Then we simulate the 4-jet process defining the light-dijet
distribution as a local record:
\begin{code}
simulate (qqbb) { analysis = record m_jj (eval M / 1 GeV [combine [q,Q]]) }
\end{code}
Finally, we compile the analysis,
\begin{code}
compile_analysis { $out_file = "lep_higgs.dat" }
\end{code}
\begin{scriptsize}
\begin{Verbatim}[frame=single]
| Starting simulation for process 'nnbb'
| Simulate: using integration grids from file 'nnbb_m1.vg'
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 21798
| OpenMP: Using 8 threads
| Simulation: using n_events as computed from luminosity value
| Events: writing to raw file 'nnbb.evx'
| Events: generating 1070 unweighted, unpolarized events ...
| Events: event normalization mode '1'
| ... event sample complete.
Warning: Encountered events with excess weight: 207 events ( 19.346 %)
| Maximum excess weight = 1.534E+00
| Average excess weight = 4.909E-02
| Events: closing raw file 'nnbb.evx'
$title = "Dijet invariant mass distribution in $e^+e^- \to q \bar q b \bar b$"
$x_label = "$M_{q\bar q}$/GeV"
| Starting simulation for process 'qqbb'
| Simulate: using integration grids from file 'qqbb_m1.vg'
| RNG: Initializing TAO random-number generator
| RNG: Setting seed for random-number generator to 21799
| OpenMP: Using 8 threads
| Simulation: using n_events as computed from luminosity value
| Events: writing to raw file 'qqbb.evx'
| Events: generating 4607 unweighted, unpolarized events ...
| Events: event normalization mode '1'
| ... event sample complete.
Warning: Encountered events with excess weight: 112 events ( 2.431 %)
| Maximum excess weight = 8.875E-01
| Average excess weight = 4.030E-03
| Events: closing raw file 'qqbb.evx'
$out_file = "lep_higgs.dat"
| Opening file 'lep_higgs.dat' for output
| Writing analysis data to file 'lep_higgs.dat'
| Closing file 'lep_higgs.dat' for output
| Compiling analysis results display in 'lep_higgs.tex'
\end{Verbatim}
\end{scriptsize}
The graphical analysis of the events generated by \whizard\ are shown
in Fig.~\ref{fig:lep_higgs}. In the upper left, the invisible mass
distribution in the $b\bar b + E_{miss}$ state is shown, peaking
around the $Z$ mass. The upper right shows the $M(b\bar b)$
distribution in the same final state, while the lower plot has the
invariant mass distribution of the two non-$b$-tagged (light) jets in
the $bbjj$ final state. The latter shows only the $Z$
peak, while the former exhibits the narrow would-be 115 GeV Higgs
state.
%%%%%%%%%%%%%%%
\section{Deep Inelastic Scattering at HERA}
%%%%%%%%%%%%%%%
\section{$W$ endpoint at LHC}
%%%%%%%%%%%%%%%
\section{SUSY Cascades at LHC}
%%%%%%%%%%%%%%%
\section{Polarized $WW$ at ILC}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Technical details -- Advanced Spells}
\label{chap:tuning}
\section{Efficiency and tuning}
Since massless fermions and vector bosons (or almost massless states
in a certain approximation) lead to restrictive selection rules for
allowed helicity combinations in the initial and final state. To make
use of this fact for the efficiency of the \whizard\ program, we are
applying some sort of heuristics: \whizard\ dices events into all
combinatorially possible helicity configuration during a warm-up
phase. The user can specify a helicity threshold which sets the number
of zeros \whizard\ should have got back from a specific helicity
combination in order to ignore that combination from now on. By that
mechanism, typically half up to more than three quarters of all
helicity combinations are discarded (and hence the corresponding
number of matrix element calls). This reduces calculation time up to
more than one order of magnitude. \whizard\ shows at the end of the
integration those helicity combinations which finally contributed to
the process matrix element.
Note that this list -- due to the numerical heuristics -- might very
well depend on the number of calls for the matrix elements per
iteration, and also on the corresponding random number seed.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{New External Physics Models}
\label{chap:extmodels}
It is never possible to include all incarnations of physics models that
can be described by the maybe weirdest form of a quantum field theory
in a tailor-made implementation within a program like \whizard. Users
clearly want to be able to use their own special type of model; in
order to do so there are external tools to translate models described
by their field content and Lagrangian densities into Feynman rules and
make them available in an event generator like \whizard. In this
chapter, we describe the interfaces to two such external models,
\sarah\ and \FeynRules.
The \FeynRules\ interface had been started already for the legacy
version \whizard\ttt{1} (where it had to be downloaded from
\url{https://whizard.hepforge.org} as a separate package), but
for the \whizard\ttt{two} release series it has been included in the
\FeynRules\ package (from their version v1.6.0 on). Note that there
was a regression for the usage of external models (from either \sarah\
or \FeynRules) in the first release of series v2.2, v2.2.0. This has
been fixed in all upcoming versions.
Besides using \sarah\ or \FeynRules\ via their interfaces, there is
now a much easier way to let those programs output model files in the
"Universal FeynRules Output" (or \UFO). This option does not have any
principle limitations for models, and also does not rely on the never
truly constant interfaces between two different tools. Their usage is
described in Sec.~\ref{sec:ufo}.
%%%%%%%%%%%%%%%
\section{New physics models via \sarah}
\sarah~\cite{Staub:2008uz,Staub:2009bi,Staub:2010jh,Staub:2012pb,Staub:2013tta}
is a \Mathematica~\cite{mathematica} package which
derives for a given model the
minimum conditions of the vacuum, the mass matrices, and vertices at tree-level
as well as expressions for the one-loop corrections for all masses and the
full two-loop renormalization group equations (RGEs). The vertices can be exported
to be used with \whizard/\oMega. All other information can be used to generate
\fortran\ source code for the RGE solution tool and spectrum generator
\spheno~\cite{Porod:2003um,Porod:2011nf} to get a spectrum generator
for any model. The
advantage is that \spheno\ calculates a consistent set of parameters (couplings,
masses, rotation matrices, decay widths) which can be used as input for \whizard.
\sarah\ and \spheno\ can be also downloaded from the \ttt{HepForge} server:
\begin{center}
\url{https://sarah.hepforge.org} \\
\url{https://spheno.hepforge.org}
\end{center}
\subsection{\whizard/\oMega\ model files from \sarah}
\subsubsection{Generating the model files}
Here we are giving only the information relevant to generate models
for \whizard. For more details about the installation of \sarah\ and
an exhaustion documentation about its usage, confer the \sarah\
manual.
To generate the model files for \whizard/\oMega\ with \sarah, a
new \Mathematica\ session has to be started. \sarah\ is loaded via
\begin{code}
<<SARAH-4.2.1/SARAH.m;
\end{code}
if \sarah\ has been stored in the applications directory of
\Mathematica. Otherwise, the full path has to be given
\begin{code}
<<[Path_to_SARAH]/SARAH.m;
\end{code}
To get an overview which models are delivered with \sarah, the command \verb"ShowModels"
can be used. As an example, we use in the following the triplet
extended MSSM (TMSSM) and initialize it in \sarah\ via
\begin{code}
Start["TMSSM"];
\end{code}
Finally, the output intended for \whizard/\oMega\ is started via
\begin{code}
MakeWHIZARD[Options]
\end{code}
The possible options of the \verb"MakeWHIZARD" command are
\begin{enumerate}
\item \verb"WriteOmega", with values: \verb"True" or \verb"False", default:
\verb"True" \\
Defines if the model files for \oMega\ should be written
\item \verb"WriteWHIZARD", with values: \verb"True" or \verb"False",
default: \verb"True" \\
Defines if the model files for \whizard\ should be written
\item \verb"Exclude", with values: list of generic type, Default:
\verb"{SSSS}" \\
Defines which generic vertices are {\em not} exported to the model
file
\item \verb"WOModelName", with values: string, default: name of the
model in \sarah\ followed by \verb"_sarah" \\
Gives the possibility to change the model name
\item \verb"MaximalCouplingsPerFile", with values: integer, default:
\ttt{150} \\
Defines the maximal number of couplings written per file
\item \verb"Version", with values: formatted number, Default:
\verb"2.2.1"~\footnote{Due to a regression in \whizard\ version
v2.2.0, \sarah\ models cannot be successfully linked within
that version. Hence, the default value here has been set to
version number 2.2.1}, \\
Defines the version of \whizard\ for which the model file is generated
\end{enumerate}
All options and the default values are also shown in the
\Mathematica\ session via \newline\verb"Options[MakeWHIZARD]".
\subsubsection{Using the generated model files with \whizard}
After the interface has completed evaluation, the generated files can
be found in the subdirectory \verb"WHIZARD_Omega" of {\sarah}s output
directory. In order to use it the generated code must be compiled and
installed. For this purpose, open a terminal, enter the output directory
\begin{code}
<PATH_to_SARAH>/Output/TMSSM/EWSB/WHIZARD_Omega/
\end{code}
and run
%
\begin{code}
./configure
make install
\end{code}
%
By default, the last command installs the compiled model into \verb".whizard"
in current user's home directory where it is automatically picked up by
\whizard. Alternative installation paths can be specified using the
\verb"--prefix" option to \whizard.
%
\begin{code}
./configure --prefix=/path/to/installation/prefix
\end{code}
%
If the files are installed into the \whizard\
installation prefix, the program will also pick them up automatically, while
{\whizard}'s \verb"--localprefix" option must be used to communicate any other
choice to \whizard. In case \whizard\ is not available in the binary search
path, the \verb"WO_CONFIG" environment variable can be used to point
\verb"configure" to the binaries
%
\begin{code}
./configure WO_CONFIG=/path/to/whizard/binaries
\end{code}
%
More information on the available options and their syntax can be obtained with
the
\verb"--help" option.
After the model is compiled it can be used in \whizard\ as
\begin{code}
model = tmssm_sarah
\end{code}
\subsection{Linking \spheno\ and \whizard}
As mentioned above, the user can also use \spheno\ to generate spectra
for its models. This is done by means of \fortran\ code for \spheno,
exported from \sarah. To do so, the user has to apply the command
\verb"MakeSPheno[]". For more details
about the options of this command and how to compile and use the \spheno\ output,
we refer to the \sarah\ manual. \\
As soon as the \spheno\ version for the given model is ready it can be used to
generate files with all necessary numerical values for the parameters in a format
which is understood by \whizard. For this purpose, the corresponding flag in the
Les Houches input file of \spheno\ has to be turned on:
\begin{code}
Block SPhenoInput # SPheno specific input
...
75 1 # Write WHIZARD files
\end{code}
Afterwards, \spheno\ returns not only the spectrum file in the
standard SUSY Les Houches accord (SLHA) format (for more details about
the SLHA and the \whizard\ SLHA interface cf. Sec.~\ref{sec:slha}),
but also an additional file called \verb"WHIZARD.par.TMSSM" for our example.
This file can be used
in the \sindarin\ input file via
\begin{code}
include ("WHIZARD.par.TMSSM")
\end{code}
%%%%%
\subsection{BSM Toolbox}
A convenient way to install \sarah\ together with \whizard, \spheno\
and some other codes are the \ttt{BSM Toolbox} scripts
\footnote{Those script have been published
under the name SUSY Toolbox but \sarah\ is with version 4 no longer
restricted to SUSY models}~\cite{Staub:2011dp}. These scripts are
available at
\begin{center}
\url{https://sarah.hepforge.org/Toolbox.html}
\end{center}
The \ttt{Toolbox} provides two scripts. First, the \verb"configure" script is
used via
\begin{code}
toolbox-src-dir> mkdir build
toolbox-src-dir> cd build
toolbox-src-dir> ../configure
\end{code}
%
The \verb"configure" script checks for the requirements of the
different packages and downloads all codes. All downloaded archives will
be placed in the \verb"tarballs" subdirectory of the directory containing the
\verb"configure" script.
Command line options can be used to disable specific packages and to point the
script to custom locations of compilers and of the \Mathematica\ kernel; a full
list of those can be obtained by calling \verb"configure" with the \verb"--help"
option.
After \verb"configure" finishes successfully, \verb"make" can be called to build
all configured packages
%
\begin{code}
toolbox-build-dir> make
\end{code}
\verb"configure" creates also the second script which automates the implementation
of a new model into all packages. The \verb"butler" script takes as argument the
name of the model in \sarah, e.g.
\begin{code}
> ./butler TMSSM
\end{code}
The \verb"butler" script runs \sarah\ to get the output in the same
form as the \whizard/\oMega\
model files and the code for \spheno. Afterwards, it installs the
model in all packages and compiles the new \whizard/\oMega\ model
files as well as the new \spheno\ module.
%%%%%
\newpage
\section{New physics models via \FeynRules}
In this section, we present the interface between the external tool
\FeynRules\ \cite{Christensen:2008py,Christensen:2009jx,Duhr:2011se}
and \whizard. \FeynRules\ is a
\Mathematica~\cite{mathematica} package that allows to derive
Feynman rules from any perturbative quantum field theory-based Lagrangian
in an automated way. It can be downloaded from
\begin{center}
\url{http://feynrules.irmp.ucl.ac.be/}
\end{center}
The input provided by the user is threefold and consists
of the Lagrangian defining the model, together with the definitions of
all the
particles and parameters that appear in the model.
Once this information is provided, \FeynRules\ can perform basic checks
on the sanity of the implementation (e.g. hermiticity, normalization
of the quadratic terms), and finally computes all the interaction
vertices associated with the model and store them in an internal
format for later processing. After the Feynman rules have been
obtained, \FeynRules\ can export the interaction vertices to \whizard\
via a dedicated interface~\cite{Christensen:2010wz}. The interface
checks whether all the vertices are compliant with the structures
supported by \whizard's
matrix element generator \oMega, and discard them in the case
they are not supported. The output of the interface consists of a set
of files organized in a single directory which can be injected into
\whizard/\oMega\ and used as any other built-in models. Together with
the model files, a framework is created which allows to communicate
the new models to \whizard\ in a well defined way, after which
step the model can be used exactly like the built-in ones.
This specifically means that the user is not required to
manually modify the code of \whizard/\oMega, the models created by the
interface can be used directly without any further user intervention.
We first describe the installation and general usage of the interface,
and then list the general properties like the supported particle
types, color quantum numbers and Lorentz structures as well as types
of gauge interactions.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Installation and Usage of the \whizard-\FeynRules\ interface}
\label{sec:interface-usage}
\paragraph{{\bf Installation and basic usage:}}
%
From \FeynRules\ version 1.6.0 onward, the interface to \whizard\ is
part of the \FeynRules\ distribution\footnote{Note that though the
main interface of \FeynRules\ to \whizard\ is for the most recent
\whizard\ release, but also the legacy branch
\whizard\ttt{1} is supported.}. In addition, the latest version
of the interface can be downloaded from the \whizard\ homepage on
\ttt{HepForge}. There you can also find an installer that can be used
to inject the interface into an existing \FeynRules\
installation (which allows to use the interface with the \FeynRules\
release series1.4.x where it is not part of the package).
Once installed, the interface can be called and used in the same way
\FeynRules' other interfaces described
in~\cite{Christensen:2008py}. The details of how to install and use
\FeynRules\ itself can be found
there,~\cite{Christensen:2008py,Christensen:2009jx,Duhr:2011se}. Here,
we only describe how to use the interface to inject new models into
\whizard. For example, once the \FeynRules\ environment has been
initialized and a model has been loaded, the command
\begin{code}
WriteWOOutput[L]
\end{code}
will call the \ttt{FeynmanRules} command to extract the Feynman
rules from the Lagrangian \ttt{L}, translate them together with the
model data and finally write the files necessary for using the model
within \whizard\ to an output directory (the name of which is inferred
from the model name by default). Options can be added for further
control over the translation process (see
Sec.~\ref{app:interface-options}). Instead of using a Lagrangian, it
is also possible to call the interface on a pure vertex list. For
example, the following command
\begin{code}
WriteWOOutput[Input -> list]
\end{code}
will directly translate the vertex list \ttt{list}. Note that this
vertex list must be given in flavor-expanded form in order for the
interface to process it correctly.
The interface also supports the \ttt{WriteWOExtParams} command
described in~\cite{Christensen:2008py}. Issuing
\begin{code}
WriteWOExtParams[filename]
\end{code}
will write a list of all the external parameters to
\ttt{filename}. This is done in the form of a \sindarin\
script. The only option accepted by the command above is the target
version of \whizard, set by the option \ttt{WOWhizardVersion}.
During execution, the interface will print out a series of
messages. It is highly advised to carefully read through this output
as it not only summarizes the settings and the location of the output
files, but also contains information on any skipped vertices or
potential incompatibilities of the model with \whizard.
After the interface has run successfully and written the model files to the
output directory, the model must be imported into \whizard. For doing
so, the model files have to be compiled and can then be installed
independently of \whizard. In the simplest scenario, assuming that the
output directory is the current working directory and that the
\whizard\ binaries can be found in the current \ttt{\$\{PATH\}},
the installation is performed by simply executing
\begin{code}
./configure~\&\&~make clean~\&\&~make install
\end{code}
This will compile the model and install it into the directory
\ttt{\$\{HOME\}/.whizard}, making it fully available to \whizard\
without any further intervention. The build system can be adapted to
more complicated cases through several options to the
\ttt{configure} which are listed in the \ttt{INSTALL} file
created in the output directory. A detailed explanation of all options
can be found in Sec.~\ref{app:interface-options}.
\paragraph{\bf Supported fields and vertices:}
The following fields are currently supported by the interface:
scalars, Dirac and Majorana fermions, vectors and symmetric tensors.
The set of accepted operators, the full list of which can be found in
Tab.~\ref{tab-operators}, is a subset of all the operators supported
by \oMega. While still limited, this list is sufficient for a large
number of BSM models. In addition, a future version of
\whizard/\oMega\ will support the definition of completely general
Lorentz structures in the model, allowing the interface to
translate all interactions handled by \FeynRules. This will be done by
means of a parser within \oMega\ of the \ttt{UFO} file format for
model files from \FeynRules.
\begin{table*}[!t]
\centerline{\begin{tabular}{|c|c|}
\hline Particle spins & Supported Lorentz structures \\\hline\hline
FFS & \parbox{0.7\textwidth}{\raggedright
All operators of dimension four are supported.
\strut}\\\hline
FFV & \parbox[t]{0.7\textwidth}{\raggedright
All operators of dimension four are
supported.
\strut}\\\hline
SSS & \parbox{0.7\textwidth}{\raggedright
All dimension three interactions are supported.
\strut}\\\hline
SVV & \parbox[t]{0.7\textwidth}{\raggedright
Supported operators:\\
\mbox{}\hspace{5ex}$\begin{aligned}
\text{dimension 3:} & \quad\mathcal{O}_3 = V_1^\mu V_{2\mu}\phi \mbox{}\\
\text{dimension 5:} & \quad\mathcal{O}_5 = \phi
\left(\partial^\mu V_1^\nu - \partial^\nu V_1^\mu\right)
\left(\partial_\mu V_{2\nu} - \partial_\nu V_{2\mu}\right)
\end{aligned}$\\
Note that $\mathcal{O}_5$ generates the effective gluon-gluon-Higgs couplings obtained by integrating out heavy quarks.
\strut}\\\hline
SSV & \parbox[t]{0.7\textwidth}{\raggedright
$\left(\phi_1\partial^\mu\phi_2 - \phi_2\partial^\mu\phi_1\right)V_\mu\;$
type interactions are supported.
\strut}\\\hline
SSVV & \parbox{0.7\textwidth}{\raggedright
All dimension four interactions are supported.
\strut}\\\hline
SSSS & \parbox{0.7\textwidth}{\raggedright
All dimension four interactions are supported.
\strut}\\\hline
VVV & \parbox[t]{0.7\textwidth}{\raggedright
All parity-conserving dimension four operators are supported, with
the restriction that non-gauge interactions may be split into
several vertices and can only be handled if all three fields are
mutually different.\strut
\strut}\\\hline
VVVV & \parbox[t]{0.7\textwidth}{\raggedright
All parity conserving dimension four operators are supported.
\strut}\\\hline
TSS, TVV, TFF & \parbox[t]{0.7\textwidth}{\raggedright
The three point couplings in the Appendix of Ref.\
\cite{Han:1998sg} are supported.
\strut}\\\hline
\end{tabular}}
\caption{All Lorentz structures currently supported by the
\whizard-\FeynRules\ interface, sorted with respect to the spins of
the particles. ``S'' stands for scalar, ``F'' for fermion (either
Majorana or Dirac) and ``V'' for vector.}
\label{tab-operators}
\end{table*}
\paragraph{\bf Color:}
%
Color is treated in \oMega\ in the color flow decomposition,
with the flow structure being implicitly determined from
the representations of the particles present at the vertex. Therefore, the
interface has to strip the color structure from the vertices derived by
\FeynRules\ before writing them out to the model files.
While this process is straightforward for all color structures which
correspond only to a single flow assignment, vertices with several
possible flow configurations must be treated with care in order to
avoid mismatches between the flows assigned by \oMega\ and those
actually encoded in the couplings. To this end, the interface derives
the color flow decomposition from the color structure determined by
\FeynRules\ and rejects all vertices which would lead to a wrong flow
assignment by \oMega\ (these rejections are accompanied by warnings
from the interface)\footnote{For the old \whizard\ttt{1} legacy
branch, there was a maximum number of external color flows that had
to explicitly specified. Essentially, this is $n_8 - \frac{1}{2}n_3$
where $n_8$ is the maximum number of external color octets and $n_3$
is the maximum number of external triplets and antitriplets. This
can be set in the \whizard/\FeynRules\ interface by the
\ttt{WOMaxNcf} command, whose default is \ttt{4}.}.
At the moment, the $SU(3)_C$ representations supported by
both \whizard\ and the interface are singlets ($1$), triplets ($3$),
antitriplets ($\bar{3}$) and octets ($8$). Tab.~\ref{tab:su3struct}
shows all combinations of these representations which can
form singlets together with the support status of the respective color
structures in \whizard\ and the interface. Although the supported
color structures do not comprise all possible singlets, the list is
sufficient for a large number of SM extensions. Furthermore, a future
revision of \whizard/\oMega\ will allow for explicit color flow
assignments, thus removing most of the current restrictions.
\begin{table*}
\centerline{\begin{tabular}{|c|c|}
\hline $SU(3)_C$ representations &
Support status
\\\hline\hline
\parbox[t]{0.2\textwidth}{
\centerline{\begin{tabular}[t]{lll}
$111,\quad$ & $\bar{3}31,\quad$ & $\bar{3}38,$ \\
$1111,$ & $\bar{3}311,$ & $\bar{3}381$
\end{tabular}}} &
\parbox[t]{0.7\textwidth}{\raggedright\strut Fully supported by the interface\strut}
\\\hline
$888,\quad 8881$ &
\parbox{0.7\textwidth}{\raggedright\strut Supported only if at least two of the octets
are identical particles.\strut}
\\\hline
$881,\quad 8811$ &
\parbox{0.7\textwidth}{\raggedright\strut Fully supported by the
interface\footnote{%
Not available in version 1.95 and earlier. Note that in order to
use such couplings in 1.96/97, the
\oMega\ option \ttt{2g} must be added to the process definition
in \ttt{whizard.prc}.}.\strut}
\\\hline
$\bar{3}388$ &
\parbox{0.7\textwidth}{\raggedright\strut Supported only if the octets
are identical
particles.\strut}
\\\hline
$8888$ &
\parbox{0.7\textwidth}{\raggedright\strut The only supported flow structure is
\begin{equation*}
\parbox{21mm}{\includegraphics{flow4}}\cdot\;\Gamma(1,2,3,4)
\quad+\quad \text{all acyclic permutations}
\end{equation*}
where $\Gamma(1,2,3,4)$ represents the Lorentz structure associated with the
first flow.\strut}
\\\hline
\parbox[t]{0.2\textwidth}{
\centerline{\begin{tabular}[t]{lll}
$333,\quad$ & $\bar{3}\bar{3}\bar{3},\quad$ & $3331$\\
$\bar{3}\bar{3}\bar{3}1,$ & $\bar{3}\bar{3}33$
\end{tabular}}} &
\parbox[t]{0.7\textwidth}{\raggedright\strut Unsupported (at the
moment)\strut}
\\\hline
\end{tabular}}
\caption{All possible combinations of three or four $SU(3)_C$
representations supported by \FeynRules\ which can be used to build singlets,
together with the support status of the corresponding color structures in
\whizard\ and the interface.}
\label{tab:su3struct}
\end{table*}
\paragraph{\bf Running $\alpha_S$:}
While a running strong coupling is fully supported by the interface, a
choice has to be made which quantities are to be reevaluated when the
strong coupling is evolved. By default \ttt{aS}, \ttt{G} (see
Ref.~\cite{Christensen:2008py} for the nomenclature regarding
the QCD coupling) and any vertex factors depending on them are evolved.
The list of internal parameters that are to be recalculated (together
with the vertex factors depending on them) can be
extended (beyond \ttt{aS} and \ttt{G}) by using
the option \ttt{WORunParameters} when calling the
interface~\footnote{As the legacy branch, \whizard\ttt{1}, does not
support a running strong coupling, this is also vetoed by the
interface when using \whizard \ttt{1.x}.}.
\paragraph{\bf Gauge choices:}
\label{sec:gauge-choices}
The interface supports the unitarity, Feynman and $R_\xi$ gauges. The choice of
gauge must be communicated to the interface via the option \ttt{WOGauge}.
Note that massless gauge bosons are always treated in Feynman gauge.
If the selected gauge is Feynman or $R_\xi$, the interface can
automatically assign the proper masses to the Goldstone bosons. This behavior is
requested by using the \ttt{WOAutoGauge} option. In the $R_\xi$
gauges, the symbol representing the gauge $\xi$ must be communicated to the
interface by using the \ttt{WOGaugeSymbol} option (the symbol is
automatically introduced into the list of external
parameters if \ttt{WOAutoGauge} is
selected at the same time). This feature can be used to automatically extend
models implemented in Feynman gauge to the $R_\xi$ gauges.
Since \whizard\ (at least until the release series 2.3) is a
tree-level tool working with helicity amplitudes, the ghost sector is
irrelevant for \whizard\ and hence dropped by the interface.
\subsection{Options of the \whizard-\FeynRules\ interface}
\label{app:interface-options}
In the following we present a comprehensive list of all the options accepted by
\ttt{WriteWOOutput}. Additionally, we note that all options of the
\FeynRules\ command \ttt{FeynmanRules} are accepted by
\ttt{WriteWOOutput}, which passes them on to \ttt{FeynmanRules}.
\begin{description}
\item[\ttt{Input}]\mbox{}\\
An optional vertex list to use instead of a Lagrangian (which can then be
omitted).
%
\item[\ttt{WOWhizardVersion}]\mbox{}\\
Select the \whizard\ version for which code is to be generated.
The currently available choices are summarized in
Tab.~\ref{tab-wowhizardversion}.
%%
\begin{table}
\centerline{\begin{tabular}{|l|l|}
\hline \ttt{WOWhizardVersion} & \whizard\ versions supported
\\\hline\hline
\ttt{"2.0.3"} (default) & 2.0.3+ \\\hline
\ttt{"2.0"} & 2.0.0 -- 2.0.2 \\\hline\hline
\ttt{"1.96"} & 1.96+ \qquad (deprecated) \\\hline
\ttt{"1.93"} & 1.93 -- 1.95 \qquad (deprecated) \\\hline
\ttt{"1.92"} & 1.92 \qquad (deprecated) \\\hline
\end{tabular}}
\caption{Currently available choices for the \ttt{WOWhizardVersion} option,
together with the respective \whizard\ versions supported by them.}
\label{tab-wowhizardversion}
\end{table}
%%
This list will expand as the program evolves. To get a summary
of all choices available in a particular version of the interface, use
the command
\ttt{?WOWhizardVersion}.
%
\item[\ttt{WOModelName}]\mbox{}\\
The name under which the model will be known to
\whizard\footnote{For versions 1.9x, model names must start
with ``\ttt{fr\_}'' if they are to be picked up by \whizard\
automatically.}. The default is determined from the \FeynRules\
model name.
%
\item[\ttt{Output}]\mbox{}\\
The name of the output directory. The default is determined from the
\FeynRules\ model name.
%
\item[\ttt{WOGauge}]\mbox{}\\
Gauge choice (\emph{cf.} Sec.~\ref{sec:gauge-choices}).
Possible values are: \ttt{WOUnitarity} (default),
\ttt{WOFeynman}, \ttt{WORxi}
%
\item[\ttt{WOGaugeParameter}]\mbox{}\\
The external or internal parameter representing the gauge $\xi$ in
the $R_\xi$ gauges (\emph{cf.} Sec.~\ref{sec:gauge-choices}). Default:
\ttt{Rxi}
%
\item[\ttt{WOAutoGauge}]\mbox{}\\
Automatically assign the Goldstone boson masses in the Feynman and $R_\xi$
gauges and automatically append the symbol for $\xi$ to the parameter list in
the $R_\xi$ gauges. Default: \ttt{False}
%
\item[\ttt{WORunParameters}]\mbox{}\\
The list of all internal parameters which will be recalculated if $\alpha_S$ is
evolved (see above)\footnote{Not available for versions older than
2.0.0}. Default: \mbox{\ttt{\{aS, G\}}}
%
\item[\ttt{WOFast}]\mbox{}\\
If the interface drops vertices which are supported, this option can be
set to \ttt{False} to enable some more time consuming checks which might aid
the identification. Default: \ttt{True}
%
\item[\ttt{WOMaxCouplingsPerFile}]\mbox{}\\
The maximum number of couplings that are written to a single \fortran\
file. If compilation takes too long or fails, this can be
lowered. Default: \ttt{500}
%
\item[\ttt{WOVerbose}]\mbox{}\\
Enable verbose output and in particular more extensive information on any
skipped vertices. Default: \ttt{False}
\end{description}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Validation of the interface}
The output of the interface has been extensively
validated. Specifically, the integrated cross sections for all
possible $2\rightarrow 2$ processes in the \FeynRules\ SM, the MSSM
and the Three-Site Higgsless Model have been compared between
\whizard, \madgraph, and \CalcHep, using the respective \FeynRules\
interfaces as well as the in-house implementations of these models
(the Three-Site Higgsless model not being available in \madgraph).
Also, different gauges have been checked for \whizard\ and \CalcHep.
In all comparisons, excellent agreement within the Monte Carlo errors
was achieved. The detailed comparison including examples of the
comparison tables can be found in~\cite{Christensen:2010wz}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Examples for the \whizard-/\FeynRules\ interface}
Here, we will use the Standard Model, the MSSM and the Three-Site
Higgsless Model as prime examples to explain the usage of the
interface. Those are the models that have been used in the validation
of the interface in~\cite{Christensen:2010wz}. The examples are
constructed to show the application of the different options of the
interface and to serve as a starting point for the generation of the
user's own \whizard\ versions of other \FeynRules\ models.
\subsubsection{\whizard-\FeynRules\ example: Standard
Model}\label{sec:usageSM}
To start off, we will create {\sc Whizard} 2 versions of the Standard
Model as implemented in \FeynRules\ for different gauge choices.
\paragraph{SM: Unitarity Gauge}
In order to invoke \FeynRules, we change to the corresponding
directory and load the program in \Mathematica\ via
\begin{code}
$FeynRulesPath =
SetDirectory["<path-to-FeynRules>"];
<<FeynRules`
\end{code}
%$
The model is loaded by
\begin{code}
LoadModel["Models/SM/SM.fr"];
FeynmanGauge = False;
\end{code}
Note that the second line is required to switch the Standard
Model to Unitarity gauge as opposed to Feynman gauge (which is the default).
Generating a \whizard\ model is now simply done by
\begin{code}
WriteWOOutput[LSM];
\end{code}
After invokation, the interface first gives a short summary of the setup
\begin{code}
Short model name is "fr_standard_model"
Gauge: Unitarity
Generating code for WHIZARD / O'Mega
version 2.0.3
Maximum number of couplings per FORTRAN
module: 500
Extensive lorentz structure checks disabled.
\end{code}
Note that, as we have not changed any options, those settings represent the
defaults. The output proceeds with the calculation of the Feynman rules from the
Standard Model Lagrangian \verb?LSM?. After the rules have been derived, the
interface starts generating output and tries to match the vertices to
their \whizard/\oMega\ counterparts.
\begin{code}
10 of 75 vertices processed...
20 of 75 vertices processed...
30 of 75 vertices processed...
40 of 75 vertices processed...
50 of 75 vertices processed...
60 of 75 vertices processed...
70 of 75 vertices processed...
processed a total of 75 vertices, kept 74
of them and threw away 1, 1 of which
contained ghosts or goldstone bosons.
\end{code}
The last line of the above output is particularily interesting, as it informs us
that everything worked out correctly: the interface was able to match all
vertices, and the only discarded vertex was the QCD ghost interaction.
After the interface has finished running, the model files in the output
directory are ready to use and can be compiled using the procedure described in
the previous section.
%%%%%
\paragraph{SM: Feynman and $R_\xi$ gauges}
As the Standard Model as implemented in \FeynRules\ also supports Feynman
gauge, we can use the program to generate a Feynman gauge version of the model.
Loading \FeynRules\ and the model proceeds as above, with the only
difference being the change
\begin{code}
FeynmanGauge = True;
\end{code}
In order to inform the interface about the modified gauge, we have to
add the option \verb?WOGauge?
\begin{code}
WriteWOOutput[LSM, WOGauge -> WOFeynman];
\end{code}
The modified gauge is reflected in the output of the interface
\begin{code}
Short model name is "fr_standard_model"
Gauge: Feynman
Generating code for WHIZARD / O'Mega
version 2.0.3
Maximum number of couplings per FORTRAN
module: 500
Extensive lorentz structure checks disabled.
\end{code}
The summary of the vertex identification now takes the following form
\begin{code}
processed a total of 163 vertices, kept 139
of them and threw away 24, 24 of which
contained ghosts.
\end{code}
Again, this line tells us that there were no problems --- the only
discarded interactions involved the ghost sector which is irrelevant
for the tree-level part of \whizard.
For a tree-level calculation, the only difference between the
different gauges from the perspective of the interface are the gauge
boson propagators and the Goldstone boson masses. Therefore, the
interface can automatically convert a model in Feynman gauge to a
model in $R_\xi$ gauge. To this end, the call to the interface must be
changed to
\begin{code}
WriteWOOutput[LSM, WOGauge -> WORxi,
WOAutoGauge -> True];
\end{code}
The \verb?WOAutoGauge? argument instructs the interface to
automatically
\begin{enumerate}
\item Introduce a symbol for the gauge parameter $\xi$ into the
list of external parameters
\item Generate the Goldstone boson masses from those of the associated
gauge bosons (ignoring the values provided by \FeynRules)
\end{enumerate}
The modified setup is again reflected in the interface output
\begin{code}
Short model name is "fr_standard_model"
Gauge: Rxi
Gauge symbol: "Rxi"
Generating code for WHIZARD / O'Mega
version 2.0.3
Maximum number of couplings per FORTRAN
module: 500
Extensive lorentz structure checks disabled.
\end{code}
Note the default choice \verb?Rxi? for the name of the $\xi$ parameter
-- this can be modified via the option \verb?WOGaugeParameter?.
While the \verb?WOAutoGauge? feature allows to generate $R_\xi$ gauged models
from models implemented in Feynman gauge, it is of course also possible to use
models genuinely implemented in $R_\xi$ gauge by setting this parameter to
\verb?False?. Also, note that the choice of gauge only affects the propagators
of massive fields. Massless gauge bosons are always treated in Feynman
gauge.
\paragraph{Compilation and usage}
In order to compile and use the freshly generated model files, change to the
output directory which can be determined from the interface output (in this
example, it is \verb?fr_standard_model-WO?). Assuming that \whizard\ is
available in the binary search path, compilation and installation proceeds as
described above by executing
\begin{code}
./configure && make && make install
\end{code}
The model is now ready and can be used similarly to the builtin
\whizard\ models. For example, a minimal \whizard\ input file for
calculating the $e^+e^- \longrightarrow W^+W^-$ scattering cross
section in the freshly generated model would look like
\begin{code}
model = fr_standard_model
process test = "e+", "e-" -> "W+", "W-"
sqrts = 500 GeV
integrate (test)
\end{code}
%%%%%
\subsubsection{\whizard/\FeynRules\ example: MSSM}
In this Section, we illustrate the usage of the interface between {\sc
FeynRules} and {\sc Whizard} in the context of the MSSM. All the
parameters of the model are then ordered in Les Houches blocks and
counters following the SUSY Les Houches Accord (SLHA)
\cite{Skands:2003cj,AguilarSaavedra:2005pw,Allanach:2008qq} (cf. also
Sec.~\ref{sec:slha}).
After having downloaded the model
from the \FeynRules\ website, we store it in a new directory, labelled
\verb"MSSM", of the model library of the local installation of
\FeynRules. The model can then be loaded in \Mathematica\ as in the
case of the SM example above
\begin{code}
$FeynRulesPath =
SetDirectory["<path-to-FeynRules>"];
<<FeynRules`
LoadModel["Models/MSSM/MSSM.fr"];
FeynmanGauge = False;
\end{code}
%$
We are again adopting unitarity gauge.
The number of vertices associated to supersymmetric Lagrangians is in general
very large (several thousands). For such models with many interactions,
it is recommended to first extract all the Feynman rules of the theory before
calling the interface between \whizard\ and \FeynRules.
The reason is related to the efficiency of the interface which takes
a lot of time in the extraction of the interaction vertices. In the
case one wishes to study the phenomenology of several benchmark
scenarios, this procedure, which is illustrated below,
allows to use the interface in the best way. The Feynman rules
are derived from the Lagrangian once and for all and then reused by the
interface for each set of \whizard\ model files to be produced,
considerably speeding up the generation of multiple model files
issued from a single Lagrangian. In addition, the scalar potential of
supersymmetric theories contains a large set of four scalar
interactions, in general irrelevant for collider phenomenology. These
vertices can be neglected with the help of the
\verb"Exclude4Scalars->True" option of both interface commands
\verb"FeynmanRules" and \verb"WriteWOOutput". The Feynman
rules of the MSSM are then computed within the \Mathematica\ notebook
by
\begin{code}
rules = FeynmanRules[lag,
Exclude4Scalars->True, FlavorExpand->True];
\end{code}
where \verb'lag' is the variable containing the Lagrangian.
By default, all the parameters of the model are set to the value of
\ttt{1}. A complete parameter \ttt{{\em <slha\_params>}.dat} file
must therefore be loaded. Such a parameter file can be downloaded from
the \FeynRules\ website or created by hand by the user, and loaded
into \FeynRules\ as
\begin{code}
ReadLHAFile[Input -> "<slha_params>.dat"];
\end{code}
This command does not reduce the size of the model output by removing
vertices with vanishing couplings. However, if desired, this task
could be done with the \ttt{LoadRestriction} command (see Ref.\
\cite{Fuks:2012im} for details).
The vertices are exported to \whizard\ by the command
\begin{code}
WriteWOOutput[Input -> rules];
\end{code}
Note that the numerical values of the parameters of the model can be
modified directly from \whizard, without having to generate a second
time the \whizard\ model files from \FeynRules. A \sindarin\ script is
created by the interface with the help of the instruction
\begin{code}
WriteWOExtParams["parameters.sin"];
\end{code}
and can be further modified according to the needs of the user.
\subsubsection{\whizard-\FeynRules\ example: Three-Site Higgsless Model}
The Three-Site Higgsless model or Minimal Higgsless model (MHM) has
been implemented into \ttt{LanHEP}~\cite{He:2007ge}, \FeynRules\
and independently into \whizard~\cite{Speckner:2010zi},
and the collider phenomenology has been studied by making use of these
implementations \cite{He:2007ge,Ohl:2010zf,Speckner:2010zi}.
Furthermore, the independent implementations in \FeynRules\ and
directly into {\sc Whizard} have been compared and found to
agree~\cite{Christensen:2010wz}. After the discovery of a Higgs boson
at the LHC in 2012, such a model is not in good agreement with
experimental data any more. Here, we simply use it as a guinea pig to
describe the handling of a model with non-renormalizable interactions
with the \FeynRules\ interface, and discuss how to generate \whizard\
model files for it. The model has been implemented in Feynman gauge as
well as unitarity gauge and contains the variable \verb|FeynmanGauge|
which can be set to \verb|True| or \verb|False|. When set to
\verb|True|, the option \verb|WOGauge-> WOFeynman| must be used, as
explained in~\cite{Christensen:2010wz}. $R_\xi$ gauge can also be
accomplished with this model by use of the options
\verb|WOGauge -> WORxi| and \verb?WOAutoGauge -> True?.
Since this model makes use of a nonlinear sigma field of the form
\begin{equation}
\Sigma = 1 + i\pi - \frac{1}{2}\pi^2+\cdots
\end{equation}
many higher dimensional operators are included in the model which are
not currently not supported by \whizard. Even for a future release of
\whizard\ containing general Lorentz structures in interaction
vertices, the user would be forced to expand the series only up to a
certain order. Although \whizard\ can reject these vertices
and print a warning message to the user, it is preferable to remove
the vertices right away in the interface by the option
\verb|MaxCanonicalDimension->4|. This is passed to the command
\verb|FeynmanRules| and restricts the Feynman rules to those of
dimension four and smaller\footnote{\ttt{MaxCanonicalDimension} is an
option of the \ttt{FeynmanRules} function rather than of the
interface, itself. In fact, the interface accepts all the options of
{\tt FeynmanRules} and simply passes them on to the latter.}.
As the use of different gauges was already illustrated in the SM
example, we discuss the model only in Feynman gauge here. We load
\FeynRules:
\begin{code}
$FeynRulesPath =
SetDirectory["<path-to-FeynRules>"];
<<FeynRules`
\end{code}
%$
The MHM model itself is then loaded by
\begin{code}
SetDirectory["<path-to-MHM>"];
LoadModel["3-Site-particles.fr",
"3-Site-parameters.fr",
"3-Site-lagrangian.fr"];
FeynmanGauge = True;
\end{code}
where \verb|<path-to-MHM>| is the path to the directory where the MHM
model files are stored and where the output of the \whizard\
interface will be written. The \whizard\ interface is then initiated:
\begin{code}
WriteWOOutput[LGauge, LGold, LGhost, LFermion,
LGoldLeptons, LGoldQuarks,
MaxCanonicalDimension->4,
WOGauge->WOFeynman, WOModelName->"fr_mhm"];
\end{code}
where we have also made use of the option \verb|WOModelName| to change
the name of the model as seen by \whizard. As in the case of the SM,
the interface begins by writing a short informational message:
\begin{code}
Short model name is "fr_mhm"
Gauge: Feynman
Generating code for WHIZARD / O'Mega
version 2.0.3
Automagically assigning Goldstone
boson masses...
Maximum number of couplings per FORTRAN
module: 500
Extensive lorentz structure checks disabled.
\end{code}
After calculating the Feynman rules and processing the vertices, the
interface gives a summary:
\begin{code}
processed a total of 922 vertices, kept 633
of them and threw away 289, 289 of which
contained ghosts.
\end{code}
showing that no vertices were missed. The files are stored in the
directory \verb|fr_mhm| and are ready to be installed and used with
\whizard.
%%%%%%%%%%%%%%%
\section{New physics models via the \UFO\ file format}
\label{sec:ufo}
In this section, we describe how to use the {\em Universal FeynRules
Output} (\UFO, \cite{Degrande:2011ua}) format for physics models
inside \whizard. Please refer the manuals of e.g.~\FeynRules\ manual
for details on how to generate a \UFO\ file for your favorite physics
model. \UFO\ files are a collection of \python\ scripts that
encode the particles, the couplings, the Lorentz structures, the
decays, as well as parameters, vertices and propagators of the
corresponding model. They reside in a directory of the exact name of
the model they have been created from.
If the user wants to generate events for processes from a physics
model from a \UFO\ file, then this directory of scripts generated by
\FeynRules\ is immediately available if it is a subdirectory of the working
directory of \whizard. The directory name will be taken as the model
name. (The \UFO-model file name must not start with a
non-letter character, i.e. especially not a number. In case such a
file name wants to be used at all costs, the model name in the
\sindarin\ script has to put in quotation marks, but this is not
guaranteed to always work.) Then, a \UFO\ model named, e.g.,
\ttt{test\_model} is accessed by an extra \ttt{ufo} tag in the model
assignment:
\begin{Code}
model = test_model (ufo)
\end{Code}
If desired, \whizard\ can access a directory of \UFO\ files elsewhere
on the file system. For instance, if \FeynRules\ output resides in
the subdirectory \ttt{MyMdl} of
\ttt{/home/users/john/ufo}, \whizard\ can use the model
named \ttt{MyMdl} as follows
\begin{Code}
model = MyMdl (ufo ('/home/users/john/my_ufo_models'))
\end{Code}
that is, the \sindarin\ keyword \ttt{ufo} can take an argument. Note
however, that the latter approach can backfire --- in case just the working
directory is packed and archived for future reference.
%%%%%%%%%%%%%%%
\clearpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\appendix
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{\sindarin\ Reference}
In the \sindarin\ language, there are certain pre-defined constructors or
commands that cannot be used in different context by the user, which
are e.g. \ttt{alias}, \ttt{beams}, \ttt{integrate}, \ttt{simulate} etc.
A complete list will be given below. Also units are fixed, like
\ttt{degree}, \ttt{eV}, \ttt{keV},
\ttt{MeV}, \ttt{GeV}, and \ttt{TeV}. Again, these tags are locked and
not user-redefinable. Their functionality will be listed in detail
below, too. Furthermore, a variable with a preceding
question mark, ?, is a logical, while a preceding dollar, \$, denotes a
character string variable. Also, a lot of unary and binary operators
exist, \ttt{+ - $\backslash$ , = : => < > <= >= \^ \; () [] \{\} }
\url{==}, as well as quotation marks, ". Note that the
different parentheses and brackets fulfill different purposes, which
will be explained below. Comments in a line can either be marked by a
hash, \#, or an exclamation mark, !.
\section{Commands and Operators}
We begin the \sindarin\ reference with all commands, operators, functions
and constructors.
The list of variables (which can be set to change behavior of \whizard) can
be found in the next section.
\begin{itemize}
\item
\ttt{+} \newline
1) Arithmetic operator for addition of integers, reals and complex
numbers. Example: \ttt{real mm = mH + mZ} (cf. also \ttt{-}, \ttt{*},
\ttt{/}, \ttt{\^{}}). 2) It also adds different particles for inclusive
process containers: \ttt{process foo = e1, E1 => (e2, E2) + (e3,
E3)}. 3) It also serves as a shorthand notation for the
concatenation of ($\to$) \ttt{combine} operations on
particles/subevents, e.g. \ttt{cuts = any 170 GeV < M < 180 GeV [b +
lepton + invisible]}.
%%%%%
\item
\ttt{-} \newline
Arithmetic operator for subtraction of integers, reals and complex
numbers. Example: \ttt{real foo = 3.1 - 5.7} (cf. also \ttt{+}, \ttt{*},
\ttt{/}, \ttt{\^{}}).
%%%%%
\item
\ttt{/} \newline
Arithmetic operator for division of integers, reals and complex
numbers. Example: \ttt{scale = mH / 2} (cf. also \ttt{+}, \ttt{*},
\ttt{-}, \ttt{\^{}}).
%%%%%
\item
\ttt{*} \newline
Arithmetic operator for multiplication of integers, reals and complex
numbers. Example: \ttt{complex z = 2 * I} (cf. also \ttt{+}, \ttt{/},
\ttt{-}, \ttt{\^{}}).
%%%%%
\item
\ttt{\^{}} \newline
Arithmetic operator for exponentiation of integers, reals and complex
numbers. Example: \ttt{real z = x\^{}2 + y\^{}2} (cf. also \ttt{+},
\ttt{/}, \ttt{-}, \ttt{\^{}}).
%%%%%
\item
\ttt{<} \newline
Arithmetic comparator between values that checks for ordering
of two values: \ttt{{\em <val1>} < {\em <val2>}} tests whether
\ttt{{\em val1}} is smaller than \ttt{{\em val2}}. Allowed for
integer and real values. Note that this is an exact comparison if
\ttt{tolerance} is set to zero. For a finite value of \ttt{tolerance}
it is a ``fuzzy'' comparison. (cf. also \ttt{tolerance}, \ttt{<>},
\ttt{==}, \ttt{>}, \ttt{>=}, \ttt{<=})
%%%%%
\item
\ttt{>} \newline
Arithmetic comparator between values that checks for ordering
of two values: \ttt{{\em <val1>} > {\em <val2>}} tests whether
\ttt{{\em val1}} is larger than \ttt{{\em val2}}. Allowed for
integer and real values. Note that this is an exact comparison if
\ttt{tolerance} is set to zero. For a finite value of \ttt{tolerance}
it is a ``fuzzy'' comparison. (cf. also \ttt{tolerance}, \ttt{<>},
\ttt{==}, \ttt{>}, \ttt{>=}, \ttt{<=})
%%%%%
\item
\ttt{<=} \newline
Arithmetic comparator between values that checks for ordering
of two values: \ttt{{\em <val1>} <= {\em <val2>}} tests whether
\ttt{{\em val1}} is smaller than or equal \ttt{{\em val2}}. Allowed for
integer and real values. Note that this is an exact comparison if
\ttt{tolerance} is set to zero. For a finite value of \ttt{tolerance}
it is a ``fuzzy'' comparison. (cf. also \ttt{tolerance}, \ttt{<>},
\ttt{==}, \ttt{>}, \ttt{<}, \ttt{>=})
%%%%%
\item
\ttt{>=} \newline
Arithmetic comparator between values that checks for ordering
of two values: \ttt{{\em <val1>} >= {\em <val2>}} tests whether
\ttt{{\em val1}} is larger than or equal \ttt{{\em val2}}. Allowed for
integer and real values. Note that this is an exact comparison if
\ttt{tolerance} is set to zero. For a finite value of \ttt{tolerance}
it is a ``fuzzy'' comparison. (cf. also \ttt{tolerance}, \ttt{<>},
\ttt{==}, \ttt{>}, \ttt{<}, \ttt{>=})
%%%%%
\item
\ttt{==} \newline
Arithmetic comparator between values that checks for identity
of two values: \ttt{{\em <val1>} == {\em <val2>}}. Allowed for
integer and real values. Note that this is an exact comparison if
\ttt{tolerance} is set to zero. For a finite value of \ttt{tolerance}
it is a ``fuzzy'' comparison. (cf. also \ttt{tolerance}, \ttt{<>},
\ttt{>}, \ttt{<}, \ttt{>=}, \ttt{<=})
%%%%%
\item
\ttt{<>} \newline
Arithmetic comparator between values that checks for
two values being unequal: \ttt{{\em <val1>} <> {\em <val2>}}. Allowed for
integer and real values. Note that this is an exact comparison if
\ttt{tolerance} is set to zero. For a finite value of \ttt{tolerance}
it is a ``fuzzy'' comparison. (cf. also \ttt{tolerance}, \ttt{==},
\ttt{>}, \ttt{<}, \ttt{>=}, \ttt{<=})
%%%%%
\item
\ttt{!} \newline
The exclamation mark tells \sindarin\ that everything that follows in
that line should be treated as a comment. It is the same as ($\to$)
\ttt{\#}.
%%%%%
\item
\ttt{\#} \newline
The hash tells \sindarin\ that everything that follows in
that line should be treated as a comment. It is the same as ($\to$)
\ttt{!}.
%%%%%
\item
\ttt{\&} \newline
Concatenates two or more particle lists/subevents and hence acts in
the same way as the subevent function ($\to$) \ttt{join}: \ttt{let
@visible = [photon] \& [colored] \& [lepton] in ...}. (cf. also
\ttt{join}, \ttt{combine}, \ttt{collect}, \ttt{extract}, \ttt{sort}).
%%%%%
\item
\ttt{\$} \newline
Constructor at the beginning of a variable name,
\ttt{\${\em <string\_var>}}, that specifies a string variable.
%%%%%
\item
\ttt{@} \newline
Constructor at the beginning of a variable name, \ttt{@{\em
<subevt\_var>}}, that specifies a subevent variable, e.g. \ttt{let
@W\_candidates = combine ["mu-", "numubar"] in ...}.
%%%%%
\item
\ttt{=} \newline
Binary constructor to appoint values to commands, e.g. \ttt{{\em <command>}
= {\em <expr>}} or \newline \ttt{{\em <command>} {\em <var\_name>} =
{\em <expr>}}.
%%%%%
\item
\ttt{\%} \newline
Constructor that gives the percentage of a number, so in
principle multiplies a real number by \ttt{0.01}. Example: \ttt{1.23
\%} is equal to \ttt{0.0123}.
%%%%%
\item
\ttt{:} \newline
Separator in alias expressions for particles, e.g. \ttt{alias neutrino
= n1:n2:n3:N1:N2:N3}. (cf. also \ttt{alias})
%%%%%
\item
\ttt{;} \newline
Concatenation operator for logical expressions: \ttt{{\em lexpr1} ;
{\em lexpr2}}. Evaluates \ttt{{\em lexpr1}} and throws the result
away, then evaluates \ttt{{\em lexpr2}} and returns that result. Used
in analysis expressions. (cf. also \ttt{analysis}, \ttt{record})
%%%%%
\item
\ttt{/+} \newline
Incrementor for ($\to$) \ttt{scan} ranges, that increments additively,
\ttt{scan {\em <num\_spec> <num>} = ({\em <lower val>} => {\em <upper
val>} /+ {\em <step
size>})}. E.g. \ttt{scan int i = (1 => 5 /+ 2)} scans over the values \ttt{1},
\ttt{3}, \ttt{5}. For real ranges, it divides the interval between
upper and lower bound into as many intervals as the incrementor
provides, e.g. \ttt{scan real r = (1 => 1.5 /+ 0.2)} runs over
\ttt{1.0}, \ttt{1.333}, \ttt{1.667}, \ttt{1.5}.
%%%%%
\item
\ttt{/+/} \newline
Incrementor for ($\to$) \ttt{scan} ranges, that increments additively,
but the number after the incrementor is the number of steps, not the
step size: \ttt{scan {\em <num\_spec> <num>} = ({\em <lower val>} =>
{\em <upper val>}
/+/ {\em <steps>})}. It is only available for real scan ranges, and divides
the interval \ttt{{\em <upper val>} - {\em <lower val>}} into
\ttt{{\em <steps>}} steps,
e.g. \ttt{scan real r = (1 => 1.5 /+/ 3)} runs over \ttt{1.0},
\ttt{1.25}, \ttt{1.5}.
%%%%%
\item
\ttt{/-} \newline
Incrementor for ($\to$) \ttt{scan} ranges, that increments subtractively,
\ttt{scan {\em <num\_spec>} {\em <num>} = ({\em <lower val>} => {\em <upper val>} /- {\em <step
size>})}. E.g. \ttt{scan int i = (9 => 0 /+ 3)} scans over the values \ttt{9},
\ttt{6}, \ttt{3}, \ttt{0}. For real ranges, it divides the interval
between upper and lower bound into as many intervals as the incrementor
provides, e.g. \ttt{scan real r = (1 => 0.5 /- 0.2)} runs over
\ttt{1.0}, \ttt{0.833}, \ttt{0.667}, \ttt{0.5}.
%%%%%
\item
\ttt{/*} \newline
Incrementor for ($\to$) \ttt{scan} ranges, that increments multiplicatively,
\ttt{scan {\em <num\_spec>} {\em <num>} = ({\em <lower val>} => {\em <upper val>} /* {\em <step
size>})}. E.g. \ttt{scan int i = (1 => 4 /* 2)} scans over the values \ttt{1},
\ttt{2}, \ttt{4}. For real ranges, it divides the interval
between upper and lower bound into as many intervals as the incrementor
provides, e.g. \ttt{scan real r = (1 => 5 /* 2)} runs over
\ttt{1.0}, \ttt{2.236} (i.e. $\sqrt{5}$), \ttt{5.0}.
%%%%%
\item
\ttt{/*/} \newline
Incrementor for ($\to$) \ttt{scan} ranges, that increments multiplicatively,
but the number after the incrementor is the number of steps, not the
step size: \ttt{scan {\em <num\_spec>} {\em <num>} = ({\em <lower val>} => {\em <upper val>}
/*/ {\em <steps>})}. It is only available for real scan ranges, and divides
the interval \ttt{{\em <upper val>} - {\em <lower val>}} into \ttt{{\em <steps>}} steps,
e.g. \ttt{scan real r = (1 => 9 /*/ 4)} runs over \ttt{1.000},
\ttt{2.080}, \ttt{4.327}, \ttt{9.000}.
%%%%%
\item
\ttt{//} \newline
Incrementor for ($\to$) \ttt{scan} ranges, that increments by division,
\ttt{scan {\em <num\_spec>} {\em <num>} = ({\em <lower val>} => {\em <upper val>} // {\em <step
size>})}. E.g. \ttt{scan int i = (13 => 0 // 3)} scans over the values \ttt{13},
\ttt{4}, \ttt{1}, \ttt{0}. For real ranges, it divides the interval
between upper and lower bound into as many intervals as the incrementor
provides, e.g. \ttt{scan real r = (5 => 1 // 2)} runs over
\ttt{5.0}, \ttt{2.236} (i.e. $\sqrt{5}$), \ttt{1.0}.
%%%%%
\item
\ttt{=>} \newline
Binary operator that is used in several different contexts: 1) in
process declarations between the particles specifying the
initial and final state, e.g. \ttt{process {\em <proc\_name>} = {\em <in1>}, {\em <in2>}
=> {\em <out1>}, ....}; 2) for the specification of beams when
structure functions are applied to the beam particles, e.g. \ttt{beams
= p, p => pdf\_builtin}; 3) for the specification of the scan range in
the \ttt{scan {\em <var>} {\em <var\_name>} = ({\em <scan\_start>} => {\em <scan\_end>}
{\em <incrementor>})} (cf. also \ttt{process}, \ttt{beams}, \ttt{scan})
%%%%%
\item
\ttt{\%d} \newline
Format specifier in analogy to the \ttt{C} language for the print out
on screen by the ($\to$) \ttt{printf} or into strings by the ($\to$)
\ttt{sprintf} command. It is used for decimal integer numbers,
e.g. \ttt{printf "one = \%d" (i)}. The difference between \ttt{\%i}
and \ttt{\%d} does not play a role here. (cf. also \ttt{printf}, \ttt{sprintf},
\ttt{\%i}, \ttt{\%e}, \ttt{\%f}, \ttt{\%g}, \ttt{\%E}, \ttt{\%F},
\ttt{\%G}, \ttt{\%s})
%%%%%
\item
\ttt{\%e} \newline
Format specifier in analogy to the \ttt{C} language for the print out
on screen by the ($\to$) \ttt{printf} or into strings by the ($\to$)
\ttt{sprintf} command. It is used for floating-point numbers in
standard form \ttt{[-]d.ddd e[+/-]ddd}. Usage e.g. \ttt{printf "pi =
\%e" (PI)}. (cf. also \ttt{printf}, \ttt{sprintf},
\ttt{\%d}, \ttt{\%i}, \ttt{\%f}, \ttt{\%g}, \ttt{\%E}, \ttt{\%F},
\ttt{\%G}, \ttt{\%s})
%%%%%
\item
\ttt{\%E} \newline
Same as ($\to$) \ttt{\%e}, but using upper-case letters. (cf. also
\ttt{printf}, \ttt{sprintf}, \ttt{\%d}, \ttt{\%i}, \ttt{\%e}, \ttt{\%f},
\ttt{\%g}, \ttt{\%F}, \ttt{\%G}, \ttt{\%s})
%%%%%
\item
\ttt{\%f} \newline
Format specifier in analogy to the \ttt{C} language for the print out
on screen by the ($\to$) \ttt{printf} or into strings by the ($\to$)
\ttt{sprintf} command. It is used for floating-point numbers in
fixed-point form. Usage e.g. \ttt{printf "pi =
\%f" (PI)}. (cf. also \ttt{printf}, \ttt{sprintf},
\ttt{\%d}, \ttt{\%i}, \ttt{\%e}, \ttt{\%g}, \ttt{\%E}, \ttt{\%F},
\ttt{\%G}, \ttt{\%s})
%%%%%
\item
\ttt{\%F} \newline
Same as ($\to$) \ttt{\%f}, but using upper-case letters. (cf. also
\ttt{printf}, \ttt{sprintf}, \ttt{\%d}, \ttt{\%i}, \ttt{\%e}, \ttt{\%f},
\ttt{\%g}, \ttt{\%E}, \ttt{\%G}, \ttt{\%s})
%%%%%
\item
\ttt{\%g} \newline
Format specifier in analogy to the \ttt{C} language for the print out
on screen by the ($\to$) \ttt{printf} or into strings by the ($\to$)
\ttt{sprintf} command. It is used for floating-point numbers in
normal or exponential notation, whichever is more approriate. Usage
e.g. \ttt{printf "pi = \%g" (PI)}. (cf. also \ttt{printf}, \ttt{sprintf},
\ttt{\%d}, \ttt{\%i}, \ttt{\%e}, \ttt{\%f}, \ttt{\%E}, \ttt{\%F},
\ttt{\%G}, \ttt{\%s})
%%%%%
\item
\ttt{\%G} \newline
Same as ($\to$) \ttt{\%g}, but using upper-case letters. (cf. also
\ttt{printf}, \ttt{sprintf}, \ttt{\%d}, \ttt{\%i}, \ttt{\%e}, \ttt{\%f},
\ttt{\%g}, \ttt{\%E}, \ttt{\%F}, \ttt{\%s})
%%%%%
\item
\ttt{\%i} \newline
Format specifier in analogy to the \ttt{C} language for the print out
on screen by the ($\to$) \ttt{printf} or into strings by the ($\to$)
\ttt{sprintf} command. It is used for integer numbers,
e.g. \ttt{printf "one = \%i" (i)}. The difference between \ttt{\%i}
and \ttt{\%d} does not play a role here. (cf. \ttt{printf}, \ttt{sprintf},
\ttt{\%d}, \ttt{\%e}, \ttt{\%f}, \ttt{\%g}, \ttt{\%E}, \ttt{\%F},
\ttt{\%G}, \ttt{\%s})
%%%%%
\item
\ttt{\%s} \newline
Format specifier in analogy to the \ttt{C} language for the print out
on screen by the ($\to$) \ttt{printf} or into strings by the ($\to$)
\ttt{sprintf} command. It is used for logical or string variables
e.g. \ttt{printf "foo = \%s" (\$method)}. (cf. \ttt{printf}, \ttt{sprintf},
\ttt{\%d}, \ttt{\%i}, \ttt{\%e}, \ttt{\%f}, \ttt{\%g}, \ttt{\%E}, \ttt{\%F},
\ttt{\%G})
%%%%%
\item
\ttt{abarn} \newline
Physical unit, stating that a number is in attobarns ($10^{-18}$
barn). (cf. also \ttt{nbarn}, \ttt{fbarn}, \ttt{pbarn})
%%%%%
\item
\ttt{abs} \newline
Numerical function that takes the absolute value of its argument:
\ttt{abs ({\em <num\_val>})} yields \ttt{|{\em
<num\_val>}|}. (cf. also \ttt{conjg}, \ttt{sgn}, \ttt{mod}, \ttt{modulo})
%%%%%
\item
\ttt{acos} \newline
Numerical function \ttt{asin ({\em <num\_val>})} that calculates the
arccosine trigonometric function (inverse of \ttt{cos}) of real and
complex numerical numbers or variables. (cf. also \ttt{sin},
\ttt{cos}, \ttt{tan}, \ttt{asin}, \ttt{atan})
%%%%%
\item
\ttt{alias} \newline
This allows to define a collective expression for a class of
particles, e.g. to define a generic expression for leptons, neutrinos
or a jet as \ttt{alias lepton = e1:e2:e3:E1:E2:E3}, \ttt{alias
neutrino = n1:n2:n3:N1:N2:N3}, and \ttt{alias jet =
u:d:s:c:U:D:S:C:g}, respectively.
%%%%%
\item
\ttt{all} \newline
\ttt{all} is a function that works on a logical expression and a list,
\ttt{all {\em <log\_expr>} [{\em <list>}]}, and returns \ttt{true} if and only if
\ttt{log\_expr} is fulfilled for {\em all} entries in \ttt{list}, and
\ttt{false} otherwise. Examples: \ttt{all Pt > 100 GeV [lepton]}
checks whether all leptons are harder than 100 GeV, \ttt{all Dist > 2
[u:U, d:D]} checks whether all pairs of corresponding quarks
are separated in $R$ space by more than 2. Logical expressions with
\ttt{all} can be logically combined with \ttt{and} and
\ttt{or}. (cf. also \ttt{any}, \ttt{and}, \ttt{no}, and \ttt{or})
%%%%%
\item
\ttt{alt\_setup} \newline
This command allows to specify alternative setups for a process/list
of processes, \ttt{alt\_setup = \{ {\em <setup1>} \} [, \{ {\em <setup2>} \} ,
...]}. An alternative setup can be a resetting of a coupling
constant, or different cuts etc. It can be particularly used in a
($\to$) \ttt{rescan} procedure.
%%%%%
\item
\ttt{analysis} \newline
This command, \ttt{analysis = {\em <log\_expr>}}, allows to define an
analysis as a logical expression, with a syntax similar to the ($\to$)
\ttt{cuts} or ($\to$) \ttt{selection} command. Note that a ($\to$)
formally is a logical expression.
%%%%%
\item
\ttt{and} \newline
This is the standard two-place logical connective that has the value
true if both of its operands are true, otherwise a value of false. It
is applied to logical values, e.g. cut expressions. (cf. also
\ttt{all}, \ttt{no}, \ttt{or}).
%%%%%
\item
\ttt{any} \newline
\ttt{any} is a function that works on a logical expression and a list,
\ttt{any {\em <log\_expr>} [{\em <list>}]}, and returns \ttt{true} if
\ttt{log\_expr} is fulfilled for any entry in \ttt{list}, and
\ttt{false} otherwise. Examples: \ttt{any PDG == 13 [lepton]} checks
whether any lepton is a muon, \ttt{any E > 2 * mW [jet]} checks
whether any jet has an energy of twice the $W$ mass. Logical
expressions with \ttt{any} can be logically combined with \ttt{and}
and \ttt{or}. (cf. also \ttt{all}, \ttt{and}, \ttt{no}, and \ttt{or})
%%%%%
\item
\ttt{as} \newline
cf. \ttt{compile}
%%%%%
\item
\ttt{ascii} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of the standard \whizard\ verbose/debug ASCII event
files. (cf. also \ttt{\$sample}, \ttt{\$sample\_normalization},
\ttt{sample\_format})
%%%%%
\item
\ttt{asin} \newline
Numerical function \ttt{asin ({\em <num\_val>})} that calculates the
arcsine trigonometric function (inverse of \ttt{sin}) of real and
complex numerical numbers or variables. (cf. also \ttt{sin},
\ttt{cos}, \ttt{tan}, \ttt{acos}, \ttt{atan})
%%%%%
\item
\ttt{atan} \newline
Numerical function \ttt{atan ({\em <num\_val>})} that calculates the
arctangent trigonometric function (inverse of \ttt{tan}) of real and
complex numerical numbers or variables. (cf. also \ttt{sin},
\ttt{cos}, \ttt{tan}, \ttt{asin}, \ttt{acos})
%%%%%
\item
\ttt{athena} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of the ATHENA variant for HEPEVT ASCII event
files. (cf. also \ttt{\$sample}, \ttt{\$sample\_normalization},
\ttt{sample\_format})
%%%%%
\item
\ttt{beam} \newline
Constructor that specifies a particle (in a subevent) as beam particle. It is
used in cuts, analyses or selections, e.g. \ttt{cuts = all Theta > 20
degree [beam lepton, lepton]}. (cf. also \ttt{incoming}, \ttt{outgoing},
\ttt{cuts}, \ttt{analysis}, \ttt{selection}, \ttt{record})
%%%%%
\item
\ttt{beam\_events} \newline
Beam structure specifier to read in lepton collider beamstrahlung's
spectra from external files as pairs of energy fractions: \ttt{beams:
e1, E1 => beam\_events}. Note that this is a pair spectrum that has to
be applied to both beams simultaneously. (cf. also \ttt{beams},
\ttt{\$beam\_events\_file}, \ttt{?beam\_events\_warn\_eof})
%%%%%
\item
\ttt{beams} \newline
This specifies the contents and structure of the beams: \ttt{beams =
{\em <prt1>}, {\em <prt2>} [ => {\em <str\_fun1>} ....]}. If this
command is absent in the input file, \whizard\ automatically takes the
two incoming partons (or one for decays) of the corresponding process
as beam particles, and no structure functions are applied. Protons and
antiprotons as beam particles are predefined as \ttt{p} and
\ttt{pbar}, respectively. A structure function, like \ttt{pdf\_builtin},
\ttt{ISR}, \ttt{EPA} and so on are switched on as e.g. \ttt{beams = p,
p => lhapdf}. Structure functions can be specified for one of the two
beam particles only, of the structure function is not a
spectrum. (cf. also \ttt{beams\_momentum}, \ttt{beams\_theta},
\ttt{beams\_phi}, \ttt{beams\_pol\_density},
\ttt{beams\_pol\_fraction}, \ttt{beam\_events}, \ttt{circe1},
\ttt{circe2}, \ttt{energy\_scan}, \ttt{epa}, \ttt{ewa}, \ttt{isr},
\ttt{lhapdf}, \ttt{pdf\_builtin}).
%%%%%
\item
\ttt{beams\_momentum} \newline
Command to set the momenta (or energies) for the two beams of a
scattering process: \ttt{beams\_momentum = {\em <mom1>}, {\em <mom2>}} to allow
for asymmetric beam setups (e.g. HERA: \ttt{beams\_momentum = 27.5
GeV, 920 GeV}). Two arguments must be present
for a scattering process, but the command can be used with one
argument to integrate and simulate a decay of a moving
particle. (cf. also \ttt{beams}, \ttt{beams\_theta},
\ttt{beams\_phi}, \ttt{beams\_pol\_density},
\ttt{beams\_pol\_fraction})
%%%%%
\item
\ttt{beams\_phi} \newline
Same as ($\to$) \ttt{beams\_theta}, but to allow for a non-vanishing
beam azimuth angle, too. (cf. also \ttt{beams}, \ttt{beams\_theta},
\ttt{beams\_momentum}, \ttt{beams\_pol\_density},
\ttt{beams\_pol\_fraction})
%%%%%
\item
\ttt{beams\_pol\_density} \newline
This command allows to specify the initial state for polarized beams
by the syntax: \ttt{beams\_pol\_density = @({\em <pol\_spec\_1>}),
@({\em <pol\_spec\_2>})}. Two polarization specifiers are mandatory for
scattering, while one can be used for decays from polarized
probes. The specifier \ttt{{\em <pol\_spec\_i>}} can be empty (no
polarization), has one entry (for a definite helicity/spin
orientation), or ranges of entries of a spin density matrix. The
command can be used globally, or as a local argument of the
\ttt{integrate} command. For detailed information, see
Sec.~\ref{sec:initialpolarization}. It is also possible to use
variables as placeholders in the specifiers. Note that polarization is
assumed to be complete, for partial polarization use ($\to$)
\ttt{beams\_pol\_fraction}. (cf. also \ttt{beams}, \ttt{beams\_theta},
\ttt{beams\_phi}, \ttt{beams\_momentum}, \ttt{beams\_pol\_fraction})
%%%%%
\item
\ttt{beams\_pol\_fraction} \newline
This command allows to specify the amount of polarization when using
polarized beams ($\to$ \ttt{beams\_pol\_density}). The syntax is:
\ttt{beams\_pol\_fraction = {\em <frac\_1>}, {\em <frac\_2>}}. Two fractions must
be present for scatterings, being real numbers between \ttt{0} and
\ttt{1}. A specification with percentage is also possible,
e.g. \ttt{beams\_pol\_fraction = 80\%, 40\%}. (cf. also \ttt{beams},
\ttt{beams\_theta}, \ttt{beams\_phi}, \ttt{beams\_momentum},
\ttt{beams\_pol\_density})
%%%%%
\item
\ttt{beams\_theta} \newline
Command to set a crossing angle (with respect to the $z$ axis) for one
or both of the beams of a
scattering process: \ttt{beams\_theta = {\em <angle1>}, {\em <angle2>}} to allow
for asymmetric beam setups (e.g. \ttt{beams\_angle = 0, 10
degree}). Two arguments must be present for a scattering process, but
the command can be used with one argument to integrate and simulate a
decay of a moving particle. (cf. also \ttt{beams}, \ttt{beams\_phi},
\ttt{beams\_momentum}, \ttt{beams\_pol\_density},
\ttt{beams\_pol\_fraction})
%%%%%
\item
\ttt{by} \newline
Constructor that replaces the default sorting criterion (according to
PDG codes) of the ($\to$) \ttt{sort} function on particle
lists/subevents by one given by a unary or binary particle observable:
\ttt{sort by {\em <observable>} [{\em <particles>} [, {\em
<ref\_particles>}] ]}. (cf. also \ttt{sort}, \ttt{extract}, \ttt{join},
\ttt{collect}, \ttt{combine}, \ttt{+})
%%%%%
\item
\ttt{ceiling} \newline
This is a function \ttt{ceiling ({\em <num\_val>})} that gives the
least integer greater than or equal to \ttt{{\em <num\_val>}},
e.g. \ttt{int i = ceiling (4.56789)} gives \ttt{i = 5}. (cf. also
\ttt{int}, \ttt{nint}, \ttt{floor})
%%%%%
\item
\ttt{circe1} \newline
Beam structure specifier for the \circeone\ structure function for
beamstrahlung at a linear lepton collider: \ttt{beams = e1, E1 =>
circe1}. Note that this is a pair spectrum, so the specifier acts for
both beams simultaneously. (cf. also \ttt{beams}, \ttt{?circe1\_photons},
\ttt{?circe1\_photon2}, \ttt{circe1\_sqrts},
\ttt{?circe1\_generate}, \ttt{?circe1\_map},
\ttt{circe1\_eps}, \newline \ttt{circe1\_mapping\_slope}, \ttt{circe1\_ver},
\ttt{circe1\_rev}, \ttt{\$circe1\_acc}, \ttt{circe1\_chat})
%%%%%
\item
\ttt{circe2} \newline
Beam structure specifier for the lepton-collider structure function
for photon spectra, \circetwo: \ttt{beams = A, A => circe2}. Note that
this is a pair spectrum, an application to only one beam is not
possible. (cf. also \ttt{beams}, \ttt{?circe2\_polarized},
\ttt{\$circe2\_file}, \ttt{\$circe2\_design})
%%%%%
\item
\ttt{clear} \newline
This command allows to clear a variable set before: \ttt{clear
({\em <clearable var.>})} resets the variable \ttt{{\em <clearable var.>}} which
could be the \ttt{beams}, the \ttt{unstable} settings, \ttt{sqrts},
any kind of \ttt{cuts} or \ttt{scale} expressions, any user-set
variable etc. The syntax of the command is completely analogous to
($\to$) \ttt{show}.
%%%%%
\item
\ttt{close\_out} \newline
With the command, \ttt{close\_out ("{\em <out\_file">})} user-defined
information like data or ($\to$) \ttt{printf} statements can be
written out to a user-defined file. The command closes an I/O stream to
an external file \ttt{{\em <out\_file>}}. (cf. also \ttt{open\_out},
\ttt{\$out\_file}, \ttt{printf})
%%%%%
\item
\ttt{cluster} \newline
Command that allows to cluster all particles in a subevent to a set of
jets: \ttt{cluster [{\em<particles>}]}. It also to cluster particles
subject to a certain boolean condition, \ttt{cluster if
{\em<condition>} [{\em<particles>}]}. At the moment only available
if the \fastjet\ package is linked.
(cf. also \ttt{jet\_r}, \ttt{combine}, \ttt{jet\_algorithm},
\ttt{kt\_algorithm}, \newline \ttt{cambridge\_[for\_passive\_]algorithm},
\ttt{antikt\_algorithm}, \ttt{plugin\_algorithm}, \newline
\ttt{genkt\_[for\_passive\_]algorithm},
\ttt{ee\_kt\_algorithm}, \ttt{ee\_genkt\_algorithm},
\ttt{?keep\_flavors\_when\_clustering})
%%%%%
\item
\ttt{collect} \newline
The \ttt{collect [{\em <list>}]} operation collects all particles in
the list \ttt{{\em <list>}} into a one-entry subevent with a
four-momentum of the sum of all four-momenta of non-overlapping
particles in \ttt{{\em <list>}}. (cf. also \ttt{combine},
\ttt{select}, \ttt{extract}, \ttt{sort})
%%%%%
\item
\ttt{complex} \newline
Defines a complex variable. The syntax is e.g. \ttt{complex x = 2 + 3
* I}. (cf.~also \ttt{int}, \ttt{real})
%%%%%
\item
\ttt{combine} \newline
The \ttt{combine [{\em <list1>}, {\em <list2>}]} operation makes a particle list
whose entries are the result of adding (the momenta of) each pair of
particles in the two input lists \ttt{list1}, {list2}. For example,
\ttt{combine [incoming lepton, lepton]} constructs all mutual pairings
of an incoming lepton with an outgoing lepton (an alias for the
leptons has to be defined, of course). (cf. also \ttt{collect},
\ttt{select}, \ttt{extract}, \ttt{sort}, \ttt{+})
%%%%%
\item
\ttt{compile} \newline
The \ttt{compile ()} command has no arguments (the parentheses can
also been left out: /\ttt{compile ()}. The command is optional, it
invokes the compilation of the process(es) (i.e. the matrix element
file(s)) to be compiled as a shared library. This shared object file
has the standard name \ttt{default\_lib.so} and resides in the
\ttt{.libs} subdirectory of the corresponding user workspace. If the
user has defined a different library name \ttt{lib\_name} with the
\ttt{library} command, then WHIZARD compiles this as the shared object
\ttt{.libs/lib\_name.so}. (This allows to split process classes and to
avoid too large libraries.)
Another possibility is to use the command \ttt{compile as
"static\_name"}. This will compile and link the process library in a
static way and create the static executable \ttt{static\_name} in the
user workspace. (cf. also \ttt{library})
%%%%%
\item
\ttt{compile\_analysis} \newline
The \ttt{compile\_analysis} statement does the same as
the \ttt{write\_analysis} command, namely to tell \whizard\ to write
the analysis setup by the user for the \sindarin\ input file under
consideration. If no \ttt{\$out\_file} is provided, the histogram
tables/plot data etc. are written to the default file
\ttt{whizard\_analysis.dat}. In addition to \ttt{write\_analysis},
\ttt{compile\_analysis} also invokes the \whizard\ \LaTeX routines for
producing postscript or PDF output of the data (unless the flag
$\rightarrow$ \ttt{?analysis\_file\_only} is set to \ttt{true}).
(cf. also \ttt{\$out\_file}, \ttt{write\_analysis},
\ttt{?analysis\_file\_only})
%%%%%
\item
\ttt{conjg} \newline
Numerical function that takes the complex conjugate of its argument:
\ttt{conjg ({\em <num\_val>})} yields \ttt{{\em
<num\_val>}$^\ast$}. (cf. also \ttt{abs}, \ttt{sgn}, \ttt{mod}, \ttt{modulo})
%%%%%
\item
\ttt{cos} \newline
Numerical function \ttt{cos ({\em <num\_val>})} that calculates the
cosine trigonometric function of real and complex numerical numbers or
variables. (cf. also \ttt{sin}, \ttt{tan}, \ttt{asin}, \ttt{acos},
\ttt{atan})
%%%%%
\item
\ttt{cosh} \newline
Numerical function \ttt{cosh ({\em <num\_val>})} that calculates the
hyperbolic cosine function of real and complex numerical numbers or
variables. Note that its inverse function is part of the
\ttt{Fortran2008} status and hence not realized. (cf. also \ttt{sinh},
\ttt{tanh})
%%%%%
\item
\ttt{count} \newline
Subevent function that counts the number of particles or particle
pairs in a subevent: \ttt{count [{\em <particles\_1>} [, {\em
<particles\_2>}]]}. This can also be a counting subject to a
condition: \ttt{count if {\em <condition>} [{\em <particles\_1>} [,
{\em <particles\_2>}]]}.
%%%%%
\item
\ttt{cuts} \newline
This command defines the cuts to be applied to certain processes. The
syntax is: \ttt{cuts = {\em <log\_class>} {\em <log\_expr>} [{\em <unary or binary
particle (list) arg>}]}, where the cut expression must be initialized
with a logical classifier \ttt{log\_class} like \ttt{all}, \ttt{any},
\ttt{no}. The logical expression \ttt{log\_expr} contains the cut to
be evaluated. Note that this need not only be a kinematical cut
expression like \ttt{E > 10 GeV} or \ttt{5 degree < Theta < 175 degree},
but can also be some sort of trigger expression or event selection.
Whether the expression is evaluated on particles or pairs
of particles depends on whether the discriminating variable is unary or
binary, \ttt{Dist} being obviously binary, \ttt{Pt} being unary. Note that
some variables are both unary and binary, e.g. the invariant mass $M$. Cut
expressions can be connected by the logical connectives \ttt{and} and
\ttt{or}. The \ttt{cuts} statement acts on all subsequent process
integrations and analyses until a new \ttt{cuts} statement appears.
(cf. also \ttt{all}, \ttt{any},
\ttt{Dist}, \ttt{E}, \ttt{M},
\ttt{no}, \ttt{Pt}).
%%%%%
\item
\ttt{debug} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of the very verbose \whizard\ ASCII event
file format intended for debugging. (cf. also \ttt{\$sample},
\ttt{sample\_format}, \ttt{\$sample\_normalization})
%%%%%
\item
\ttt{degree} \newline
Expression specifying the physical unit of degree for angular
variables, e.g. the cut expression function \ttt{Theta}. (if no unit is
specified for angular variables, radians are used; cf. \ttt{rad}, \ttt{mrad}).
%%%%
\item
\ttt{Dist} \newline
Binary observable specifier, that gives the $\eta$-$\phi$-
(pseudorapidity-azimuth) distance $R = \sqrt{(\Delta \eta)^2 +
(\Delta\phi)^2}$ between the momenta of the two particles: \ttt{eval
Dist [jet, jet]}. (cf. also \ttt{eval}, \ttt{cuts}, \ttt{selection},
\ttt{Theta}, \ttt{Eta}, \ttt{Phi})
%%%%%
\item
\ttt{dump} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of the intrinsic \whizard\ event record format
(output of the \ttt{particle\_t} type container). (cf. also
\ttt{\$sample}, \ttt{sample\_format}, \ttt{\$sample\_normalization}
%%%%%
\item
\ttt{E} \newline
Unary (binary) observable specifier for the energy of a single
(two) particle(s), e.g. \ttt{eval E ["W+"]}, \ttt{all E > 200 GeV [b,
B]}. (cf. \ttt{eval}, \ttt{cuts}, \ttt{selection})
%%%%%
\item
\ttt{else} \label{sindarin_else}\newline
Constructor for providing an alternative in a conditional clause:
\ttt{if {\em <log\_expr>} then {\em <expr 1>} else {\em <expr 2>} endif}. (cf. also
\ttt{if}, \ttt{elsif}, \ttt{endif}, \ttt{then}).
%%%%%
\item
\ttt{elsif} \newline
Constructor for concatenating more than one conditional clause with
each other: \ttt{if {\em <log\_expr 1>} then {\em <expr 1>} elsif {\em <log\_expr 2>}
then {\em <expr 2>} \ldots endif}. (cf. also \ttt{if}, \ttt{else},
\ttt{endif}, \ttt{then}).
%%%%%
\item
\ttt{endif} \newline
Mandatory constructor to conclude a conditional clause: \ttt{if
{\em <log\_expr>} then \ldots endif}. (cf. also \ttt{if},
\ttt{else}, \ttt{elsif}, \ttt{then}).
%%%%%
\item
\ttt{energy\_scan} \newline
Beam structure specifier for the energy scan structure function:
\ttt{beams = e1, E1 => energy\_scan}. This pair spectrum that has to
be applied to both beams simultaneously can be used to scan over a
range of collider energies without using the \ttt{scan} command.
(cf. also \ttt{beams}, \ttt{scan}, \ttt{?energy\_scan\_normalize})
%%%%%
\item
\ttt{epa} \newline
Beam structure specifier for the equivalent-photon approximation
(EPA), i.e the Weizs\"acker-Williams structure function:
e.g. \ttt{beams = e1, E1 => epa} (applied to both beams), or
e.g. \ttt{beams = e1, u => epa, none} (applied to only one
beam). (cf. also \ttt{beams}, \ttt{epa\_alpha}, \ttt{epa\_x\_min},
\ttt{epa\_mass}, \ttt{epa\_q\_max}, \ttt{epa\_q\_min},
\ttt{?epa\_recoil}, \ttt{?epa\_keep\_energy})
%%%%%
\item
\ttt{Eta} \newline
Unary and also binary observable specifier, that as a unary observable
gives the pseudorapidity of a particle momentum. The pseudorapidity is
given by $\eta = - \log \left[ \tan (\theta/2) \right]$, where
$\theta$ is the angle with the beam direction. As a binary
observable, it gives the pseudorapidity difference between the momenta
of two particles, where $\theta$ is the enclosed angle: \ttt{eval Eta
[e1]}, \ttt{all abs (Eta) < 3.5 [jet, jet]}. (cf. also \ttt{eval},
\ttt{cuts}, \ttt{selection}, \ttt{Rap}, \ttt{abs})
%%%%%
\item
\ttt{eV} \newline
Physical unit, stating that the corresponding number is in electron
volt. (cf. also \ttt{keV}, \ttt{meV}, \ttt{MeV}, \ttt{GeV}, \ttt{TeV})
%%%%%
\item
\ttt{eval} \newline
Evaluator that tells \whizard\ to evaluate the following expr:
\ttt{eval {\em <expr>}}. Examples are: \ttt{eval Rap [e1]}, \ttt{eval
M / 1 GeV [combine [q,Q]]} etc. (cf. also \ttt{cuts},
-\ttt{selection}, \ttt{record})
+\ttt{selection}, \ttt{record}, \ttt{sum}, \ttt{prod})
%%%%%
\item
\ttt{ewa} \newline
Beam structure specifier for the equivalent-photon approximation
(EWA): e.g. \ttt{beams = e1, E1 => ewa} (applied to both beams), or
e.g. \ttt{beams = e1, u => ewa, none} (applied to only one
beam). (cf. also \ttt{beams}, \ttt{ewa\_x\_min}, \ttt{ewa\_pt\_max},
\ttt{ewa\_mass}, \ttt{?ewa\_keep\_energy},
\ttt{?ewa\_recoil})
%%%%%
\item
\ttt{exec} \newline
Constructor \ttt{exec ("{\em <cmd\_name>}")} that demands WHIZARD to
execute/run the command \ttt{cmd\_name}. For this to work that
specific command must be present either in the path of the operating
system or as a command in the user workspace.
%%%%%
\item
\ttt{exit} \newline
Command to finish the \whizard\ run (and not execute any further code
beyond the appearance of \ttt{exit} in the \sindarin\ file. The command
(which is the same as $\to$ \ttt{quit}) allows for an argument,
\ttt{exit ({\em <expr>})}, where the expression can be executed, e.g. a
screen message or an exit code.
%%%%%
\item
\ttt{exp} \newline
Numerical function \ttt{exp ({\em <num\_val>})} that calculates the
exponential of real and complex numerical numbers or
variables. (cf. also \ttt{sqrt}, \ttt{log}, \ttt{log10})
%%%%%
\item
\ttt{expect} \newline
The binary function \ttt{expect} compares two numerical expressions
whether they fulfill a certain ordering condition or are equal up
to a specific uncertainty or tolerance which can bet set by the
specifier \ttt{tolerance}, i.e. in principle it checks whether a
logical expression is true. The \ttt{expect} function does actually
not just check a value for correctness, but also records its result.
If failures are present when the program terminates, the exit code is
nonzero. The syntax is \ttt{expect ({\em <num1>} {\em
<log\_comp>} {\em <num2>})}, where \ttt{{\em <num1>}} and
\ttt{{\em <num2>}} are two numerical values (or
corresponding variables) and \ttt{{\em <log\_comp>}} is one of the following
logical comparators: \ttt{<}, \ttt{>}, \ttt{<=}, \ttt{>=}, \ttt{==},
\ttt{<>}.
(cf. also \ttt{<}, \ttt{>}, \ttt{<=}, \ttt{>=}, \ttt{==}, \ttt{<>},
\ttt{tolerance}).
%%%%%
\item
\ttt{extract} \newline
Subevent function that either extracts the first element of a
particle list/subevent: \ttt{extract [ {\em <particles>}]}, or the
element at position \ttt{<index\_value>} of the particle list:
\ttt{extract {\em index <index\_value>} [ {\em
<particles>}]}. Negative index values count from the end of the
list. (cf. also \ttt{sort}, \ttt{combine},
\ttt{collect}, \ttt{+}, \ttt{index})
%%%%%
\item
\ttt{factorization\_scale} \newline
This is a command, \ttt{factorization\_scale = {\em <expr>}}, that sets
the factorization scale of a process or list of processes. It
overwrites a possible scale set by the ($\to$) \ttt{scale} command.
\ttt{{\em <expr>}} can be any kinematic expression that leads to a result of
momentum dimension one, e.g. \ttt{100 GeV}, \ttt{eval
Pt [e1]}. (cf. also \ttt{renormalization\_scale}).
%%%%%
\item
\ttt{false} \newline
Constructor stating that a logical expression or variable is false,
e.g. \ttt{?{\em <log\_var>} = false}. (cf. also \ttt{true}).
%%%%%
\item
\ttt{fbarn} \newline
Physical unit, stating that a number is in femtobarns ($10^{-15}$
barn). (cf. also \ttt{nbarn}, \ttt{abarn}, \ttt{pbarn})
%%%%%
\item
\ttt{floor} \newline
This is a function \ttt{floor ({\em <num\_val>})} that gives the
greatest integer less than or equal to \ttt{{\em <num\_val>}},
e.g. \ttt{int i = floor (4.56789)} gives \ttt{i = 4}. (cf. also
\ttt{int}, \ttt{nint}, \ttt{ceiling})
%%%%%
\item
\ttt{gaussian} \newline
Beam structure specifier that imposes a Gaussian energy distribution,
separately for each beam. The $\sigma$ values are set by
\ttt{gaussian\_spread1} and \ttt{gaussian\_spread2}, respectively.
%%%%%
\item
\ttt{GeV} \newline
Physical unit, energies in $10^9$ electron volt. This is the default
energy unit of WHIZARD. (cf. also \ttt{eV}, \ttt{keV}, \ttt{MeV}, \ttt{meV},
\ttt{TeV})
%%%%%
\item
\ttt{graph} \newline
This command defines the necessary information regarding producing
a graph of a function in \whizard's internal graphical \gamelan\
output. The syntax is: \ttt{graph {\em <record\_name>} \{ {\em <optional
arguments>} \}}. The record with name \ttt{{\em <record\_name>}} has to be
defined, either before or after the graph definition. Possible optional
arguments of the \ttt{graph} command are the minimal and maximal values
of the axes (\ttt{x\_min}, \ttt{x\_max}, \ttt{y\_min}, \ttt{y\_max}).
(cf. \ttt{plot}, \ttt{histogram}, \ttt{record})
%%%%%
\item
\ttt{Hel} \newline
Unary observable specifier that allows to specify the helicity of a
particle, e.g. \ttt{all Hel == -1 [e1]} in a selection. (cf. also
\ttt{eval}, \ttt{cuts}, \ttt{selection})
%%%%%
\item
\ttt{hepevt} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of HEPEVT ASCII event files. (cf. also \ttt{\$sample},
\ttt{sample\_format})
%%%%%
\item
\ttt{hepevt\_verb} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of the extended or verbose version of HEPEVT ASCII event
files. (cf. also \ttt{\$sample}, \ttt{sample\_format})
%%%%%
\item
\ttt{hepmc} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of HepMC ASCII event files. Note that this is only
available if the HepMC package is installed and correctly
linked. (cf. also \ttt{\$sample}, \ttt{sample\_format},
\ttt{?hepmc\_output\_cross\_section})
%%%%%
\item
\ttt{histogram} \newline
This command defines the necessary information regarding plotting data
as a histogram, in the form of: \ttt{histogram {\em <record\_name>} \{
{\em <optional arguments>} \}}. The record with name \ttt{{\em <record\_name>}} has to be
defined, either before or after the histogram definition. Possible optional
arguments of the \ttt{histogram} command are the minimal and maximal values
of the axes (\ttt{x\_min}, \ttt{x\_max}, \ttt{y\_min}, \ttt{y\_max}).
(cf. \ttt{graph}, \ttt{plot}, \ttt{record})
%%%%%
\item
+\ttt{Ht} \newline
+Subeventary observable specifier for the transverse mass
+($\sqrt{p_T^2 + m^2}$ in the c.m. frame) summed over all particles in
+the subevent given as argument, e.g. \ttt{eval Ht [t:T:Z]}. (cf.
+\ttt{eval}, \ttt{sum}, \ttt{prod}, \ttt{Pt}, \ttt{M})
+%%%%%
+\item
\ttt{if} \newline
Conditional clause with the construction \ttt{if {\em <log\_expr>} then
{\em <expr>} [else {\em <expr>} \ldots] endif}. Note that there must be an
\ttt{endif} statement. For more complicated expressions it is better
to use expressions in parentheses: \ttt{if ({\em <log\_expr>}) then
\{{\em <expr>}\} else \{{\em <expr>}\} endif}. Examples are a selection of up quarks
over down quarks depending on a logical variable: \ttt{if ?ok then u
else d}, or the setting of an integer variable depending on the
rapidity of some particle: \ttt{if (eta > 0) then \{ a = +1\} else
\{ a = -1\}}. (cf. also \ttt{elsif}, \ttt{endif}, \ttt{then})
%%%%%
\item
\ttt{in} \newline
Second part of the constructor to let a variable be local to an
expression. It has the syntax \ttt{let {\em <var>} = {\em <value>} in
{\em <expression>}}. E.g. \ttt{let int a = 3 in let int b = 4 in
{\em <expression>}} (cf. also \ttt{let})
%%%%%
\item
\ttt{include} \newline
The \ttt{include} statement, \ttt{include ("file.sin")} allows to
include external \sindarin\ files \ttt{file.sin} into the main WHIZARD
input file. A standard example is the inclusion of the standard cut
file \ttt{default\_cuts.sin}.
%%%%%
\item
\ttt{incoming} \newline
Constructor that specifies particles (or subevents) as incoming. It is
used in cuts, analyses or selections, e.g. \ttt{cuts = all Theta > 20
degree [incoming lepton, lepton]}. (cf. also \ttt{beam}, \ttt{outgoing},
\ttt{cuts}, \ttt{analysis}, \ttt{selection}, \ttt{record})
%%%%%
\item
\ttt{index} \newline
Specifies the position of the element of a particle to be extracted by
the subevent function ($\to$) \ttt{extract}: \ttt{extract {\em index
<index\_value>} [ {\em <particles>}]}. Negative index values count
from the end of the list. (cf. also \ttt{extract}, \ttt{sort}, \ttt{combine},
\ttt{collect}, \ttt{+})
%%%%%
\item
\ttt{int} \newline
1) This is a constructor to specify integer constants in the input
file. Strictly speaking, it is a unary function setting the value
\ttt{int\_val} of the integer variable \ttt{int\_var}:
\ttt{int {\em <int\_var>} = {\em <int\_val>}}. Note that is mandatory for all
user-defined variables. (cf. also \ttt{real} and \ttt{complex})
2) It is a function \ttt{int ({\em <num\_val>})} that converts real and
complex numbers (here their real parts) into integers. (cf. also
\ttt{nint}, \ttt{floor}, \ttt{ceiling})
%%%%%
\item
\ttt{integrate} \newline
The \ttt{integrate ({\em <proc\_name>}) \{ {\em <integrate\_options>} \}} command
invokes the integration (phase-space generation and Monte-Carlo
sampling) of the process \ttt{proc\_name} (which can also be a list of
processes) with the integration options
\ttt{{\em <integrate\_options>}}. Possible options are (1) via
\ttt{\$integration\_method = "{\em <intg. method>}"} the integration
method (the default being VAMP), (2) the number of iterations and
calls per integration during the Monte-Carlo phase-space integration
via the \ttt{iterations} specifier; (3) goal for the
accuracy, error or relative error (\ttt{accuracy\_goal},
\ttt{error\_goal}, \ttt{relative\_error\_goal}). (4) Invoking only
phase space generation (\ttt{?phs\_only = true}), (5) making test
calls of the matrix element. (cf. also \ttt{iterations},
\ttt{accuracy\_goal}, \ttt{error\_goal}, \ttt{relative\_error\_goal},
\ttt{error\_threshold})
%%%%%
\item
\ttt{isr} \newline
Beam structure specifier for the lepton-collider/QED initial-state
radiation (ISR) structure function: e.g. \ttt{beams = e1, E1 => isr}
(applied to both beams), or e.g. \ttt{beams = e1, u => isr, none}
(applied to only one beam). (cf. also \ttt{beams}, \ttt{isr\_alpha},
\ttt{isr\_q\_max}, \ttt{isr\_mass}, \ttt{isr\_order},
\ttt{?isr\_recoil}, \ttt{?isr\_keep\_energy})
%%%%%
\item
\ttt{iterations} \qquad (default: internal heuristics) \newline
Option to set the number of iterations and calls per iteration during
the Monte-Carlo phase-space integration process. The syntax is
\ttt{iterations = {\em <n\_iterations>}:{\em <n\_calls>}}. Note that this can be
also a list, separated by colons, which breaks up the integration
process into passes of the specified number of integrations and calls
each. It works for all integration methods. For VAMP, there is the
additional option to specify whether grids and channel weights should
be adapted during iterations (\ttt{"g"}, \ttt{"w"},
\ttt{"gw"} for both, or \ttt{""} for no adaptation). (cf. also
\ttt{integrate}, \ttt{accuracy\_goal}, \ttt{error\_goal},
\ttt{relative\_error\_goal}, \ttt{error\_threshold}).
%%%%%
\item
\ttt{join} \newline
Subevent function that concatenates two particle lists/subevents if
there is no overlap: \ttt{join [{\em <particles>}, {\em
<new\_particles>}]}. The joining of the two lists can also be made
depending on a condition: \ttt{join if {\em <condition>} [{\em
<particles>}, {\em <new\_particles>}]}. (cf. also \ttt{\&},
\ttt{collect}, \ttt{combine}, \ttt{extract}, \ttt{sort}, \ttt{+})
%%%%%
\item
\ttt{keV} \newline
Physical unit, energies in $10^3$ electron volt. (cf. also \ttt{eV},
\ttt{meV}, \ttt{MeV}, \ttt{GeV}, \ttt{TeV})
%%%%%
\item
\ttt{kT} \newline
Binary particle observable that represents a jet $k_T$ clustering
measure: \ttt{kT [j1, j2]} gives the following kinematic expression:
$2 \min(E_{j1}^2, E_{j2}^2) / Q^2 \times (1 - \cos\theta_{j1,j2})$. At the
moment, $Q^2 = 1$.
%%%%%
\item
\ttt{let} \newline
This allows to let a variable be local to an expression. It has the
syntax \ttt{let {\em <var>} = {\em <value>} in {\em <expression>}}.
E.g. \ttt{let int a = 3 in let int b = 4 in {\em <expression>}}
(cf. also \ttt{in})
%%%%%
\item
\ttt{lha} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of the \whizard\ version 1 style (deprecated) LHA ASCII event
format files. (cf. also \ttt{\$sample}, \newline
\ttt{sample\_format})
%%%%%
\item
\ttt{lhapdf} \newline
This is a beams specifier to demand calling \lhapdf\ parton densities as
structure functions to integrate processes in hadron collisions. Note
that this only works if the external \lhapdf\ library is present and
correctly linked. (cf. \ttt{beams}, \ttt{\$lhapdf\_dir},
\ttt{\$lhapdf\_file}, \ttt{lhapdf\_photon},
\ttt{\$lhapdf\_photon\_file}, \ttt{lhapdf\_member},
\ttt{lhapdf\_photon\_scheme})
%%%%%
\item
\ttt{lhapdf\_photon} \newline
This is a beams specifier to demand calling \lhapdf\ parton densities as
structure functions to integrate processes in hadron collisions with a
photon as initializer of the hard scattering process. Note
that this only works if the external \lhapdf\ library is present and
correctly linked. (cf. \ttt{beams}, \ttt{lhapdf}, \ttt{\$lhapdf\_dir},
\ttt{\$lhapdf\_file}, \ttt{\$lhapdf\_photon\_file},
\ttt{lhapdf\_member}, \ttt{lhapdf\_photon\_scheme})
%%%%%
\item
\ttt{lhef} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of the Les Houches Accord (LHEF) event format files, with
XML headers. There are several different versions of this format,
which can be selected via the \ttt{\$lhef\_version} specifier
(cf. also \ttt{\$sample}, \ttt{sample\_format}, \ttt{\$lhef\_version},
\ttt{\$lhef\_extension}, \ttt{?lhef\_write\_sqme\_prc},
\newline \ttt{?lhef\_write\_sqme\_ref}, \ttt{?lhef\_write\_sqme\_alt})
%%%%%
\item
\ttt{library} \newline
The command \ttt{library = "{\em <lib\_name>}"} allows to specify a separate
shared object library archive \ttt{lib\_name.so}, not using the
standard library \ttt{default\_lib.so}. Those libraries (when using
shared libraries) are located in the \ttt{.libs} subdirectory of the
user workspace. Specifying a separate library is useful for splitting
up large lists of processes, or to restrict a larger number of
different loaded model files to one specific process library.
(cf. also \ttt{compile}, \ttt{\$library\_name})
%%%%%
\item
\ttt{log} \newline
Numerical function \ttt{log ({\em <num\_val>})} that calculates the
natural logarithm of real and complex numerical numbers or
variables. (cf. also \ttt{sqrt}, \ttt{exp}, \ttt{log10})
%%%%%
\item
\ttt{log10} \newline
Numerical function \ttt{log10 ({\em <num\_val>})} that calculates the
base 10 logarithm of real and complex numerical numbers or
variables. (cf. also \ttt{sqrt}, \ttt{exp}, \ttt{log})
%%%%%
\item
\ttt{long} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of the long variant of HEPEVT ASCII event
files. (cf. also \ttt{\$sample},
\ttt{sample\_format})
%%%%%
\item
\ttt{M} \newline
Unary (binary) observable specifier for the (signed) mass of a single
(two) particle(s), e.g. \ttt{eval M [e1]}, \ttt{any M = 91 GeV [e2,
E2]}. (cf. \ttt{eval}, \ttt{cuts}, \ttt{selection})
%%%%%
\item
\ttt{M2} \newline
Unary (binary) observable specifier for the mass squared of a single
(two) particle(s), e.g. \ttt{eval M2 [e1]}, \ttt{all M2 > 2*mZ [e2,
E2]}. (cf. \ttt{eval}, \ttt{cuts}, \ttt{selection})
%%%%%
\item
\ttt{max} \newline
Numerical function with two arguments \ttt{max ({\em <var1>}, {\em
<var2>})} that gives the maximum of the two arguments: $\max (var1,
var2)$. It can act on all combinations of integer and real
variables. Example: \ttt{real heavier\_mass = max (mZ, mH)}. (cf. also
\ttt{min})
%%%%%
\item
\ttt{meV} \newline
Physical unit, stating that the corresponding number is in $10^{-3}$
electron volt. (cf. also \ttt{eV}, \ttt{keV}, \ttt{MeV}, \ttt{GeV},
\ttt{TeV})
%%%%%
\item
\ttt{MeV} \newline
Physical unit, energies in $10^6$ electron volt. (cf. also \ttt{eV},
\ttt{keV}, \ttt{meV}, \ttt{GeV}, \ttt{TeV})
%%%%%
\item
\ttt{min} \newline
Numerical function with two arguments \ttt{min ({\em <var1>}, {\em
<var2>})} that gives the minimum of the two arguments: $\min (var1,
var2)$. It can act on all combinations of integer and real
variables. Example: \ttt{real lighter\_mass = min (mZ, mH)}. (cf. also
\ttt{max})
%%%%%
\item
\ttt{mod} \newline
Numerical function for integer and real numbers \ttt{mod (x, y)} that
computes the remainder of the division of \ttt{x} by \ttt{y} (which
must not be zero). (cf. also
\ttt{abs}, \ttt{conjg}, \ttt{sgn}, \ttt{modulo})
%%%%%
\item
\ttt{model} \qquad (default: \ttt{SM}) \newline
With this specifier, \ttt{model = {\em <model\_name>}}, one sets the hard
interaction physics model for the processes defined after this model
specification. The list of available models can be found in Table
\ref{tab:models}. Note that the model specification can appear
arbitrarily often in a \sindarin\ input file, e.g. for compiling and
running processes defined in different physics models. (cf. also
\ttt{\$model\_name})
%%%%%
\item
\ttt{modulo} \newline
Numerical function for integer and real numbers \ttt{modulo (x, y)} that
computes the value of $x$ modulo $y$. (cf. also
\ttt{abs}, \ttt{conjg}, \ttt{sgn}, \ttt{mod})
%%%%%
\item
\ttt{mokka} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of the MOKKA variant for HEPEVT ASCII event
files. (cf. also \ttt{\$sample},
\ttt{sample\_format})
%%%%%
\item
\ttt{mrad} \newline
Expression specifying the physical unit of milliradians for angular
variables. This default in \whizard\ is \ttt{rad}. (cf. \ttt{degree}, \ttt{rad}).
%%%%%
\item
\ttt{nbarn} \newline
Physical unit, stating that a number is in nanobarns ($10^{-9}$
barn). (cf. also \ttt{abarn}, \ttt{fbarn}, \ttt{pbarn})
%%%%%
\item
\ttt{n\_in} \newline
Integer variable that accesses the number of incoming particles of a
process. It can be used in cuts or in an analysis. (cf. also
\ttt{sqrts\_hat}, \ttt{cuts}, \ttt{record}, \ttt{n\_out}, \ttt{n\_tot})
%%%%%
\item
\ttt{Nacl} \newline
Unary observable specifier that returns the total number of open anticolor lines
of a particle or subevent (i.e., composite particle). Defined only if
\ttt{?colorize\_subevt} is true.. (cf. also
\ttt{Ncol}, \ttt{?colorize\_subevt})
%%%%%
\item
\ttt{Ncol} \newline
Unary observable specifier that returns the total number of open color lines
of a particle or subevent (i.e., composite particle). Defined only if
\ttt{?colorize\_subevt} is true.. (cf. also
\ttt{Nacl}, \ttt{?colorize\_subevt})
%%%%%
\item
\ttt{nint} \newline
This is a function \ttt{nint ({\em <num\_val>})} that converts real
numbers into the closest integer, e.g. \ttt{int i = nint (4.56789)}
gives \ttt{i = 5}. (cf. also
\ttt{int}, \ttt{floor}, \ttt{ceiling})
%%%%%
\item
\ttt{no} \newline
\ttt{no} is a function that works on a logical expression and a list,
\ttt{no {\em <log\_expr>} [{\em <list>}]}, and returns \ttt{true} if and only if
\ttt{log\_expr} is fulfilled for {\em none} of the entries in
\ttt{list}, and \ttt{false} otherwise. Examples: \ttt{no Pt < 100 GeV
[lepton]} checks whether no lepton is softer than 100 GeV. It is the
logical opposite of the function \ttt{all}. Logical expressions with
\ttt{no} can be logically combined with \ttt{and} and
\ttt{or}. (cf. also \ttt{all}, \ttt{any}, \ttt{and}, and \ttt{or})
%%%%%
\item
\ttt{none} \newline
Beams specifier that can used to explicitly {\em not} apply a
structure function to a beam, e.g. in HERA physics: \ttt{beams = e1, P
=> none, pdf\_builtin}. (cf. also \ttt{beams})
%%%%%
\item
\ttt{not} \newline
This is the standard logical negation that converts true into false
and vice versa. It is applied to logical values, e.g. cut
expressions. (cf. also \ttt{and}, \ttt{or}).
%%%%%
\item
\ttt{n\_out} \newline
Integer variable that accesses the number of outgoing particles of a
process. It can be used in cuts or in an analysis. (cf. also
\ttt{sqrts\_hat}, \ttt{cuts}, \ttt{record}, \ttt{n\_in}, \ttt{n\_tot})
%%%%%
\item
\ttt{n\_tot} \newline
Integer variable that accesses the total number of particles (incoming
plus outgoing) of a process. It can be used in cuts or in an
analysis. (cf. also \ttt{sqrts\_hat}, \ttt{cuts}, \ttt{record},
\ttt{n\_in}, \ttt{n\_out})
%%%%%
\item
\ttt{observable} \newline
With this, \ttt{observable = {\em <obs\_spec>}}, the user is able to define
a variable specifier \ttt{obs\_spec} for observables. These can be
reused in the analysis, e.g. as a \ttt{record}, as functions of the
fundamental kinematical variables of the processes.
(cf. \ttt{analysis}, \ttt{record})
%%%%%
\item
\ttt{open\_out} \newline
With the command, \ttt{open\_out ("{\em <out\_file">})} user-defined
information like data or ($\to$) \ttt{printf} statements can be
written out to a user-defined file. The command opens an I/O stream to
an external file \ttt{{\em <out\_file>}}. (cf. also \ttt{close\_out},
\ttt{\$out\_file}, \ttt{printf})
%%%%%
\item
\ttt{or} \newline
This is the standard two-place logical connective that has the value
true if one of its operands is true, otherwise a value of false. It
is applied to logical values, e.g. cut expressions. (cf. also
\ttt{and}, \ttt{not}).
%%%%%
\item
\ttt{outgoing} \newline
Constructor that specifies particles (or subevents) as outgoing. It is
used in cuts, analyses or selections, e.g. \ttt{cuts = all Theta > 20
degree [incoming lepton, outgoing lepton]}. Note that the \ttt{outgoing}
keyword is redundant and included only for completeness: \ttt{outgoing lepton}
has the same meaning as \ttt{lepton}. (cf. also \ttt{beam},
\ttt{incoming},
\ttt{cuts}, \ttt{analysis}, \ttt{selection}, \ttt{record})
%%%%%
\item
\ttt{P} \newline
Unary (binary) observable specifier for the spatial momentum
$\sqrt{\vec{p}^2}$ of a single (two) particle(s), e.g. \ttt{eval P
["W+"]}, \ttt{all P > 200 GeV [b, B]}. (cf. \ttt{eval}, \ttt{cuts},
\ttt{selection})
%%%%%
\item
\ttt{pbarn} \newline
Physical unit, stating that a number is in picobarns ($10^{-12}$
barn). (cf. also \ttt{abarn}, \ttt{fbarn}, \ttt{nbarn})
%%%%%
\item
\ttt{pdf\_builtin} \newline
This is a beams specifier for \whizard's internal PDF structure
functions to integrate processes in hadron collisions.
(cf. \ttt{beams}, \ttt{pdf\_builtin\_photon},
\ttt{\$pdf\_builtin\_file})
%%%%%
\item
\ttt{pdf\_builtin\_photon} \newline
This is a beams specifier for \whizard's internal PDF structure
functions to integrate processes in hadron collisions with a photon as
initializer of the hard scattering process.
(cf. \ttt{beams}, \ttt{\$pdf\_builtin\_file})
%%%%%
\item
\ttt{PDG} \newline
Unary observable specifier that allows to specify the PDG code of a
particle, e.g. \ttt{eval PDG [e1]}, giving \ttt{11}. (cf. also
\ttt{eval}, \ttt{cuts}, \ttt{selection})
%%%%%
\item
\ttt{Phi} \newline
Unary and also binary observable specifier, that as a unary observable
gives the azimuthal angle of a particle's momentum in the detector
frame (beam into $+z$ direction). As a binary observable, it gives the
azimuthal difference between the momenta of two particles: \ttt{eval
Phi [e1]}, \ttt{all Phi > Pi [jet, jet]}. (cf. also \ttt{eval},
\ttt{cuts}, \ttt{selection}, \ttt{Theta})
%%%%%
\item
\ttt{photon\_isolation} \newline
Logical function \ttt{photon\_isolation if {\em <condition>} [{\em
<list1>} , {\em <list2>}]} that cuts out event where the photons in
\ttt{{\em <list1>}} do not fulfill the condition \ttt{{\em
<condition>}} and are not isolated from hadronic (and electromagnetic)
activity, i.e. the photon fragmentation. (cf. also \ttt{cluster},
\ttt{collect}, \ttt{combine}, \ttt{extract}, \ttt{select},
\ttt{sort}, \ttt{+})
%%%%%
\item
+\ttt{photon\_recombination} \newline
+Similar to the \ttt{cluster} statement takes a subevent as argument
+and combines a (single) photon with the closest non-photon object
+given in the subevent. Depends on the \sindarin\ variable
+\ttt{photon\_rec\_r0} which gives the $R$ radius within which the photon
+is recombined. (cf. also \ttt{cluster}, \ttt{collect}, \ttt{combine})
+%%%%%
+\item
\ttt{Pl} \newline
Unary (binary) observable specifier for the longitudinal momentum
($p_z$ in the c.m. frame) of a single (two) particle(s),
e.g. \ttt{eval Pl ["W+"]}, \ttt{all Pl > 200 GeV [b,
B]}. (cf. \ttt{eval}, \ttt{cuts}, \ttt{selection})
%%%%%
\item
\ttt{plot} \newline
This command defines the necessary information regarding plotting data
as a graph, in the form of: \ttt{plot {\em <record\_name>} \{ {\em <optional
arguments>} \}}. The record with name \ttt{{\em <record\_name>}} has to be
defined, either before or after the plot definition. Possible optional
arguments of the \ttt{plot} command are the minimal and maximal values
of the axes (\ttt{x\_min}, \ttt{x\_max}, \ttt{y\_min}, \ttt{y\_max}).
(cf. \ttt{graph}, \ttt{histogram}, \ttt{record})
%%%%%
\item
\ttt{polarized} \newline
Constructor to instruct \whizard\ to retain polarization of the
corresponding particles in the generated events: \ttt{polarized {\em <prt1>}
[, {\em <prt2>} , ...]}. (cf. also \ttt{unpolarized}, \ttt{simulate},
\ttt{?polarized\_events})
%%%%%
\item
\ttt{printf} \newline
Command that allows to print data as screen messages, into logfiles or
into user-defined output files: \ttt{printf "{\em <string\_expr>}"}. There
exist format specifiers, very similar to the \ttt{C} command
\ttt{printf}, e.g. \ttt{printf "\%i" (123)}. (cf. also
\ttt{open\_out}, \ttt{close\_out}, \ttt{\$out\_file},
\ttt{?out\_advance}, \ttt{sprintf}, \ttt{\%d}, \ttt{\%i}, \ttt{\%e},
\ttt{\%f}, \ttt{\%g}, \ttt{\%E}, \ttt{\%F}, \ttt{\%G}, \ttt{\%s})
%%%%%
\item
\ttt{process} \newline
Allows to set a hard interaction process, either for a decay process
with name \ttt{{\em <decay\_proc>}} as \ttt{process {\em
<decay\_proc>} = {\em <mother>} => {\em <daughter1>}, {\em
<daughter2>}, ...}, or for a scattering process
with name \ttt{{\em <scat\_proc}} as \ttt{process {\em <scat\_proc>} =
{\em <in1>}, {\em <in2>} => {\em <out1>}, {\em <out2>}, ...}. Note
that there can be arbitrarily many processes to be defined in a
\sindarin\ input file. There are two options for particle/process sums: flavor sums:
\ttt{{\em <prt1>}:{\em <prt2>}:...}, where all masses have to be identical, and
inclusive sums, \ttt{{\em <prt1>} + {\em <prt2>} + ...}. The latter can be done on
the level of individual particles, or sums over whole final
states. Here, masses can differ, and terms will be translated into
different process components. The \ttt{process} command also allows for
optional arguments, e.g. to specify a numerical identifier
(cf. \ttt{process\_num\_id}), the method how to generate the code for
the matrix element(s): \ttt{\$method}, possible methods are either
with the \oMega\ matrix element generator, using template matrix
elements with different normalizations, or completely internal matrix
element; for \oMega\ matrix elements there is also the possibility to
specify possible restrictions (cf. \ttt{\$restrictions}).
%%%%%
\item
+\ttt{prod} \newline
+Takes the product of an expression \ttt{<expr>} over the elements of
+the given subevent \ttt{<subevt>}, \ttt{prod <expr> [<subevt>]}, e.g.
+\ttt{prod Hel [e1:E1]} (cf. \ttt{eval}, \ttt{sum}).
+%%%%%
+\item
\ttt{Pt} \newline
Unary (binary) observable specifier for the transverse momentum
($\sqrt{p_x^2 + p_y^2}$ in the c.m. frame) of a single (two)
particle(s), e.g. \ttt{eval Pt ["W+"]}, \ttt{all Pt > 200 GeV [b,
B]}. (cf. \ttt{eval}, \ttt{cuts}, \ttt{selection})
%%%%%
\item
\ttt{Px} \newline
Unary (binary) observable specifier for the $x$-component of the
momentum of a single (two) particle(s), e.g. \ttt{eval Px ["W+"]},
\ttt{all Px > 200 GeV [b, B]}. (cf. \ttt{eval}, \ttt{cuts},
\ttt{selection})
%%%%%
\item
\ttt{Py} \newline
Unary (binary) observable specifier for the $y$-component of the
momentum of a single (two) particle(s), e.g. \ttt{eval Py ["W+"]},
\ttt{all Py > 200 GeV [b, B]}. (cf. \ttt{eval}, \ttt{cuts},
\ttt{selection})
%%%%%
\item
\ttt{Pz} \newline
Unary (binary) observable specifier for the $z$-component of the
momentum of a single (two) particle(s), e.g. \ttt{eval Pz ["W+"]},
\ttt{all Pz > 200 GeV [b, B]}. (cf. \ttt{eval}, \ttt{cuts},
\ttt{selection})
%%%%%
\item
\ttt{quit} \newline
Command to finish the \whizard\ run (and not execute any further code
beyond the appearance of \ttt{quit} in the \sindarin\ file. The command
(which is the same as $\to$ \ttt{exit}) allows for an argument,
\ttt{quit ({\em <expr>})}, where the expression can be executed, e.g. a
screen message or an quit code.
%%%%%
\item
\ttt{rad} \newline
Expression specifying the physical unit of radians for angular
variables. This is the default in \whizard. (cf. \ttt{degree}, \ttt{mrad}).
%%%%%
\item
\ttt{Rap} \newline
Unary and also binary observable specifier, that as a unary observable
gives the rapidity of a particle momentum. The rapidity is given by $y
= \frac12 \log \left[ (E + p_z)/(E-p_z) \right]$. As a binary
observable, it gives the rapidity difference between the momenta of
two particles: \ttt{eval Rap [e1]}, \ttt{all abs (Rap) < 3.5 [jet,
jet]}. (cf. also \ttt{eval}, \ttt{cuts}, \ttt{selection}, \ttt{Eta},
\ttt{abs})
%%%%%
\item
\ttt{read\_slha} \newline
Tells \whizard\ to read in an input file in the SUSY Les Houches accord
(SLHA), as \ttt{read\_slha ("slha\_file.slha")}. Note that the files
for the use in \whizard\ should have the suffix \ttt{.slha}.
(cf. also \ttt{write\_slha}, \ttt{?slha\_read\_decays},
\ttt{?slha\_read\_input}, \ttt{?slha\_read\_spectrum})
%%%%%
\item
\ttt{real} \newline
This is a constructor to specify real constants in the input
file. Strictly speaking, it is a unary function setting the value
\ttt{real\_val} of the real variable \ttt{real\_var}:
\ttt{real {\em <real\_var>} = {\em <real\_val>}}. (cf. also \ttt{int} and
\ttt{complex})
%%%%%
\item
\ttt{real\_epsilon}\\
Predefined real; the relative uncertainty intrinsic to the floating
point type of the \fortran\ compiler with which \whizard\ has been
built.
%%%%%
\item
\ttt{real\_precision}\\
Predefined integer; the decimal precision of the floating point type
of the \fortran\ compiler with which \whizard\ has been built.
%%%%%
\item
\ttt{real\_range}\\
Predefined integer; the decimal range of the floating point type of
the \fortran\ compiler with which \whizard\ has been built.
%%%%%
\item
\ttt{real\_tiny}\\
Predefined real; the smallest number which can be represented by the
floating point type of the \fortran\ compiler with which \whizard\ has
been built.
%%%%%
\item
\ttt{record} \newline
The \ttt{record} constructor provides an internal data structure in
\sindarin\ input files. Its syntax is in general \ttt{record
{\em <record\_name>} ({\em <cmd\_expr>})}. The \ttt{{\em <cmd\_expr>}} could be the
definition of a tuple of points for a histogram or an \ttt{eval}
constructor that tells \whizard\ e.g. by which rule to calculate an
observable to be stored in the record \ttt{record\_name}. Example:
\ttt{record h (12)} is a record for a histogram defined under the name
\ttt{h} with the single data point (bin) at value 12; \ttt{record rap1
(eval Rap [e1])} defines a record with name \ttt{rap1} which has an
evaluator to calculate the rapidity (predefined \whizard\ function) of
an outgoing electron.
(cf. also \ttt{eval}, \ttt{histogram}, \ttt{plot})
%%%%%
\item
\ttt{renormalization\_scale} \newline
This is a command, \ttt{renormalization\_scale = {\em <expr>}}, that sets
the renormalization scale of a process or list of processes. It
overwrites a possible scale set by the ($\to$) \ttt{scale} command.
\ttt{{\em <expr>}} can be any kinematic expression that leads to a result of
momentum dimension one, e.g. \ttt{100 GeV}, \ttt{eval
Pt [e1]}. (cf. also \ttt{factorization\_scale}).
%%%%%
\item
\ttt{rescan} \newline
This command allows to rescan event samples with modified model
parameter, beam structure etc. to recalculate (analysis) observables,
e.g.: \newline
\ttt{rescan "{\em <event\_file>}" ({\em <proc\_name>}) \{ {\em <rescan\_setup>}\}}.
\newline
\ttt{"{\em <event\_file>}"} is the name of the event file and
\ttt{{\em <proc\_name>}} is the process whose (existing) event
file of arbitrary size that is to be rescanned. Several flags allow to
reconstruct the beams ($\to$ \ttt{?recover\_beams}), to reuse only the
hard process but rebuild the full events ($\to$
\ttt{?update\_event}), to recalculate the matrix element ($\to$
\ttt{?update\_sqme}) or to recalculate the individual event weight ($\to$
\ttt{?update\_weight}). Further rescan options are redefining model
parameter input, or defining a completely new alternative setup ($\to$
\ttt{alt\_setup}) (cf. also \ttt{\$rescan\_input\_format})
%%%%%
\item
\ttt{results} \newline
Only used in the combination \ttt{show (results)}. Forces \whizard\ to
print out a results summary for the integrated processes.
(cf. also \ttt{show})
%%%%%
\item
\ttt{reweight} \newline
The \ttt{reweight = {\em <expr>}} command allows to give for a process or
list of processes an alternative weight, given by any kind of scalar
expression \ttt{{\em <expr>}}, e.g. \ttt{reweight = 0.2} or \ttt{reweight =
(eval M2 [e1, E1]) / (eval M2 [e2, E2])}. (cf. also \ttt{alt\_setup},
\ttt{weight}, \ttt{rescan})
%%%%%
\item
\ttt{sample\_format} \newline
Variable that allows the user to specify additional event formats
beyond the \whizard\ native binary event format. Its syntax is
\ttt{sample\_format = {\em <format>}}, where \ttt{{\em <format>}} can be any of
the following specifiers: \ttt{hepevt}, \ttt{hepevt\_verb}, \ttt{ascii},
\ttt{athena}, \ttt{debug}, \ttt{long}, \ttt{short}, \ttt{hepmc},
\ttt{lhef}, \ttt{lha}, \ttt{lha\_verb}, \ttt{stdhep}, \ttt{stdhep\_up},
\texttt{lcio}, \texttt{mokka}.
(cf. also \ttt{\$sample}, \ttt{simulate}, \ttt{hepevt}, \ttt{ascii},
\ttt{athena}, \ttt{debug}, \ttt{long}, \ttt{short}, \ttt{hepmc},
\ttt{lhef}, \ttt{lha}, \ttt{stdhep}, \ttt{stdhep\_up}, \texttt{lcio},
\texttt{mokka}, \ttt{\$sample\_normalization}, \ttt{?sample\_pacify}, \newline
\ttt{sample\_max\_tries}, \ttt{sample\_split\_n\_evt}, \ttt{sample\_split\_n\_kbytes})
%%%%%
\item
\ttt{scale} \newline
This is a command, \ttt{scale = {\em <expr>}}, that sets the kinematic scale
of a process or list of processes. Unless overwritten explicitly by
($\to$) \ttt{factorization\_scale} and/or ($\to$)
\ttt{renormalization\_scale} it sets both scales. \ttt{{\em <expr>}} can be
any kinematic expression that leads to a result of momentum dimension
one, e.g. \ttt{scale = 100 GeV}, \ttt{scale = eval Pt [e1]}.
%%%%%
\item
\ttt{scan} \newline
Constructor to perform loops over variables or scan over processes in
the integration procedure. The syntax is \ttt{scan {\em <var>} {\em <var\_name>}
({\em <value list>} or {\em <value\_init>} => {\em <value\_fin>} /{\em <incrementor>}
{\em <increment>}) \{ {\em <scan\_cmd>} \}}. The variable \ttt{var} can be
specified if it is not a real, e.g. an integer. \ttt{var\_name} is the
name of the variable which is also allowed to be a predefined one like
\ttt{seed}. For the scan, one can either specify an explicit list of
values \ttt{value list}, or use an initial and final value and a
rule to increment. The \ttt{scan\_cmd} can either be just a
\ttt{show} to print out the scanned variable or the integration of a process.
Examples are: \ttt{scan seed (32 => 1 // 2) \{ show (seed\_value) \}
}, which runs the seed down in steps 32, 16, 8, 4, 2, 1 (division by
two). \ttt{scan mW (75 GeV, 80 GeV => 82 GeV /+ 0.5 GeV, 83 GeV => 90
GeV /* 1.2) \{ show (sw) \} } scans over the $W$ mass for the values
75, 80, 80.5, 81, 81.5, 82, 83 GeV, namely one discrete value, steps
by adding 0.5 GeV, and increase by 20 \% (the latter having no effect
as it already exceeds the final value). It prints out the
corresponding value of the effective mixing angle which is defined as
a dependent variable in the model input file(s). \ttt{scan sqrts (500 GeV =>
600 GeV /+ 10 GeV) \{ integrate (proc) \} } integrates the process
\ttt{proc} in eleven increasing 10 GeV steps in center-of-mass energy
from 500 to 600 GeV. (cf. also \ttt{/+}, \ttt{/+/}, \ttt{/-},
\ttt{/*}, \ttt{/*/}, \ttt{//})
%%%%%
\item
\ttt{select} \newline
Subevent function \ttt{select if {\em <condition>} [{\em <list1>} [ ,
{\em <list2>}]]} that selects all particles in \ttt{{\em <list1>}}
that satisfy the condition \ttt{{\em <condition>}}. The second
particle list \ttt{{\em <list2>}} is for conditions that depend on
binary observables. (cf. also \ttt{collect},
\ttt{combine}, \ttt{extract}, \ttt{sort}, \ttt{+})
%%%%%
\item
\ttt{select\_b\_jet} \newline
Subevent function \ttt{select if {\em <condition>} [{\em <list1>} [ ,
{\em <list2>}]]} that selects all particles in \ttt{{\em <list1>}}
that are $b$ jets and satisfy the condition \ttt{{\em
<condition>}}. The second particle list \ttt{{\em <list2>}} is for
conditions that depend on binary observables. (cf. also \ttt{cluster},
\ttt{collect}, \ttt{combine}, \ttt{extract}, \ttt{select},
\ttt{sort}, \ttt{+})
%%%%%
\item
\ttt{select\_c\_jet} \newline
Subevent function \ttt{select if {\em <condition>} [{\em <list1>} [ ,
{\em <list2>}]]} that selects all particles in \ttt{{\em <list1>}}
that are $c$ jets (but {\em not} $b$ jets) and satisfy the condition
\ttt{{\em <condition>}}. The second particle list \ttt{{\em <list2>}}
is for conditions that depend on binary observables. (cf. also
\ttt{cluster}, \ttt{collect}, \ttt{combine}, \ttt{extract},
\ttt{select}, \ttt{sort}, \ttt{+})
%%%%%
\item
\ttt{select\_light\_jet} \newline
Subevent function \ttt{select if {\em <condition>} [{\em <list1>} [ ,
{\em <list2>}]]} that selects all particles in \ttt{{\em <list1>}}
that are light(-flavor) jets and satisfy the condition
\ttt{{\em <condition>}}. The second particle list \ttt{{\em <list2>}}
is for conditions that depend on binary observables. (cf. also
\ttt{cluster}, \ttt{collect}, \ttt{combine}, \ttt{extract},
\ttt{select}, \ttt{sort}, \ttt{+})
%%%%%
\item
\ttt{select\_non\_b\_jet} \newline
Subevent function \ttt{select if {\em <condition>} [{\em <list1>} [ ,
{\em <list2>}]]} that selects all particles in \ttt{{\em <list1>}}
that are {\em not} $b$ jets ($c$ and light jets) and satisfy the
condition \ttt{{\em <condition>}}. The second particle list \ttt{{\em
<list2>}} is for conditions that depend on binary
observables. (cf. also \ttt{cluster}, \ttt{collect}, \ttt{combine},
\ttt{extract}, \ttt{select}, \ttt{sort}, \ttt{+})
%%%%%
\item
\ttt{selection} \newline
Command that allows to select particular final states in an analysis
selection, \ttt{selection = {\em <log\_expr>}}. The term \ttt{log\_expr} can
be any kind of logical expression. The syntax matches exactly
the one of the ($\to$) \ttt{cuts} command. E.g. \ttt{selection = any
PDG == 13} is an electron selection in a lepton sample.
%%%%%
\item
\ttt{sgn} \newline
Numerical function for integer and real numbers that gives the sign of
its argument: \ttt{sgn ({\em <num\_val>})} yields $+1$ if \ttt{{\em
<num\_val>}} is positive or zero, and $-1$ otherwise. (cf. also
\ttt{abs}, \ttt{conjg}, \ttt{mod}, \ttt{modulo})
%%%%%
\item
\ttt{short} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of the short variant of HEPEVT ASCII event
files. (cf. also \ttt{\$sample}, \ttt{sample\_format})
%%%%%
\item
\ttt{show} \newline
This is a unary function that is operating on specific constructors in
order to print them out in the \whizard\ screen output as well as the
log file \ttt{whizard.log}. Examples are \ttt{show({\em <parameter\_name>})}
to issue a specific parameter from a model or a constant defined in a
\sindarin\ input file, \ttt{show(integral({\em <proc\_name>}))},
\ttt{show(library)}, \ttt{show(results)}, or \ttt{show({\em <var>})} for any
arbitrary variable. Further possibilities are \ttt{show(real)},
\ttt{show(string)}, \ttt{show(logical)} etc. to allow to show all
defined real, string, logical etc. variables, respectively.
(cf. also \ttt{library}, \ttt{results})
%%%%%
\item
\ttt{simulate} \newline
This command invokes the generation of events for the process
\ttt{proc} by means of \ttt{simulate ({\em <proc>})}.
Optional arguments: \ttt{\$sample}, \ttt{sample\_format},
\ttt{checkpoint} (cf. also \ttt{integrate}, \ttt{luminosity},
\ttt{n\_events}, \ttt{\$sample}, \ttt{sample\_format},
\ttt{checkpoint}, \ttt{?unweighted}, \ttt{safety\_factor},
\ttt{?negative\_weights}, \ttt{sample\_max\_tries},
\ttt{sample\_split\_n\_evt}, \ttt{sample\_split\_n\_kbytes})
%%%%%
\item
\ttt{sin} \newline
Numerical function \ttt{sin ({\em <num\_val>})} that calculates the
sine trigonometric function of real and complex numerical numbers or
variables. (cf. also \ttt{cos}, \ttt{tan}, \ttt{asin}, \ttt{acos},
\ttt{atan})
%%%%%
\item
\ttt{sinh} \newline
Numerical function \ttt{sinh ({\em <num\_val>})} that calculates the
hyperbolic sine function of real and complex numerical numbers or
variables. Note that its inverse function is part of the
\ttt{Fortran2008} status and hence not realized. (cf. also \ttt{cosh},
\ttt{tanh})
%%%%%
\item
\ttt{sort} \newline
Subevent function that allows to sort a particle list/subevent either
by increasing PDG code: \ttt{sort [{\em <particles>}]} (particles
first, then antiparticles). Alternatively, it can sort according to a
unary or binary particle observable (in that case there is a second
particle list, where the first particle is taken as a reference):
\ttt{sort by {\em <observable>} [{\em <particles>} [, {\em
<ref\_particles>}]]}. (cf. also \ttt{extract}, \ttt{combine},
\ttt{collect}, \ttt{join}, \ttt{by}, \ttt{+})
%%%%%
\item
\ttt{sprintf} \newline
Command that allows to print data into a string variable: \ttt{sprintf
"{\em <string\_expr>}"}. There exist format specifiers, very similar
to the \ttt{C} command \ttt{sprintf}, e.g. \ttt{sprintf "\%i"
(123)}. (cf. \ttt{printf}, \ttt{\%d}, \ttt{\%i}, \ttt{\%e},
\ttt{\%f}, \ttt{\%g}, \ttt{\%E}, \ttt{\%F}, \ttt{\%G}, \ttt{\%s})
%%%%%
\item
\ttt{sqrt} \newline
Numerical function \ttt{sqrt ({\em <num\_val>})} that calculates the
square root of real and complex numerical numbers or
variables. (cf. also \ttt{exp}, \ttt{log}, \ttt{log10})
%%%%%
\item
\ttt{sqrts\_hat} \newline
Real variable that accesses the partonic energy of a hard-scattering
process. It can be used in cuts or in an analysis, e.g. \ttt{cuts =
sqrts\_hat > {\em <num>} [ {\em <phys\_unit>} ]}. The physical unit
can be one of the following \ttt{eV}, \ttt{keV}, \ttt{MeV}, \ttt{GeV},
and \ttt{TeV}. (cf. also \ttt{sqrts}, \ttt{cuts}, \ttt{record})
%%%%%
\item
\ttt{stable} \newline
This constructor allows particles in the final states of processes in
decay cascade set-up to be set as stable, and not letting them
decay. The syntax is \ttt{stable {\em <prt\_name>}} (cf. also \ttt{unstable})
%%%%%
\item
\ttt{stdhep} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of binary StdHEP event files based on the HEPEVT common
block. (cf. also \ttt{\$sample}, \ttt{sample\_format})
%%%%%
\item
\ttt{stdhep\_up} \newline
Specifier for the \ttt{sample\_format} command to demand the
generation of binary StdHEP event files based on the HEPRUP/HEPEUP common
blocks. (cf. also \ttt{\$sample}, \ttt{sample\_format})
%%%%%
\item
+\ttt{sum} \newline
+Takes the sum of an expression \ttt{<expr>} over the elements of
+the given subevent \ttt{<subevt>}, \ttt{sum <expr> [<subevt>]}, e.g.
+\ttt{sum Pt/2 [jets]} (cf. \ttt{eval}, \ttt{prod}).
+%%%%%
+\item
\ttt{tan} \newline
Numerical function \ttt{tan ({\em <num\_val>})} that calculates the
tangent trigonometric function of real and complex numerical numbers or
variables. (cf. also \ttt{sin}, \ttt{cos}, \ttt{asin}, \ttt{acos},
\ttt{atan})
%%%%%
\item
\ttt{tanh} \newline
Numerical function \ttt{tanh ({\em <num\_val>})} that calculates the
hyperbolic tangent function of real and complex numerical numbers or
variables. Note that its inverse function is part of the
\ttt{Fortran2008} status and hence not realized. (cf. also \ttt{cosh},
\ttt{sinh})
%%%%%
\item
\ttt{TeV} \newline
Physical unit, for energies in $10^{12}$ electron volt. (cf. also
\ttt{eV}, \ttt{keV}, \ttt{MeV}, \ttt{meV}, \ttt{GeV})
%%%%
\item
\ttt{then} \newline
Mandatory phrase in a conditional clause: \ttt{if {\em <log\_expr>} then
{\em <expr 1>} \ldots endif}. (cf. also \ttt{if}, \ttt{else}, \ttt{elsif},
\ttt{endif}).
%%%%%
\item
\ttt{Theta} \newline
Unary and also binary observable specifier, that as a unary observable
gives the angle between a particle's momentum and the beam axis ($+z$
direction). As a binary observable, it gives the angle enclosed
between the momenta of the two particles: \ttt{eval Theta [e1]},
\ttt{all Theta > 30 degrees [jet, jet]}. (cf. also \ttt{eval},
\ttt{cuts}, \ttt{selection}, \ttt{Phi}, \ttt{Theta\_star})
%%%%%
\item
\ttt{Theta\_star} \newline
Binary observable specifier, that gives the polar angle enclosed
between the momenta of the two particles in the rest frame of the
mother particle (momentum sum of the two particle): \ttt{eval
Theta\_star [jet, jet]}. (cf. also \ttt{eval},
\ttt{cuts}, \ttt{selection}, \ttt{Theta})
%%%%%
\item
\ttt{true} \newline
Constructor stating that a logical expression or variable is true,
e.g. \ttt{?{\em <log\_var>} = true}. (cf. also \ttt{false}).
%%%%%
\item
\ttt{unpolarized} \newline
Constructor to force \whizard\ to discard polarization of the
corresponding particles in the generated events: \ttt{unpolarized {\em <prt1>}
[, {\em <prt2>} , ...]}. (cf. also \ttt{polarized}, \ttt{simulate},
\ttt{?polarized\_events})
%%%%%
\item
\ttt{unstable} \newline
This constructor allows to let final state particles of the hard
interaction undergo a subsequent (cascade) decay (in the on-shell
approximation). For this the user has to define the list of desired
\begin{figure}
\begin{Verbatim}[frame=single]
process zee = Z => e1, E1
process zuu = Z => u, U
process zz = e1, E1 => Z, Z
compile
integrate (zee) { iterations = 1:100 }
integrate (zuu) { iterations = 1:100 }
sqrts = 500 GeV
integrate (zz) { iterations = 3:5000, 2:5000 }
unstable Z (zee, zuu)
\end{Verbatim}
\caption{\label{fig:ex_unstable} \sindarin\ input file for unstable
particles and inclusive decays.}
\end{figure}
decay channels as \ttt{unstable {\em <mother>} ({\em <decay1>}, {\em <decay2>}, ....)},
where \ttt{mother} is the mother particle, and the argument is a list
of decay channels. Note that -- unless the \ttt{?auto\_decays = true}
flag has been set -- these decay channels have to be provided by the
user as in the example in Fig. \ref{fig:ex_unstable}. First, the $Z$
decays to electrons and up quarks are generated, then $ZZ$ production
at a 500 GeV ILC is called, and then both $Z$s are decayed according
to the probability distribution of the two generated decay matrix
elements. This obviously allows also for inclusive decays.
(cf. also \ttt{stable}, \ttt{?auto\_decays})
%%%%%
\item
\ttt{weight} \newline
This is a command, \ttt{weight = {\em <expr>}}, that allows to specify a
weight for a process or list of processes. \ttt{{\em <expr>}} can be
any expression that leads to a scalar result, e.g. \ttt{weight = 0.2},
\ttt{weight = eval Pt [jet]}. (cf. also \ttt{rescan},
\ttt{alt\_setup}, \ttt{reweight})
%%%%%
\item
\ttt{write\_analysis} \newline
The \ttt{write\_analysis} statement tells \whizard\ to write the
analysis setup by the user for the \sindarin\ input file under
consideration. If no \ttt{\$out\_file} is provided, the histogram
tables/plot data etc. are written to the default file
\ttt{whizard\_analysis.dat}. Note that the related command
\ttt{compile\_analysis} does the same as \ttt{write\_analysis} but in
addition invokes the \whizard\ \LaTeX routines for producing
postscript or PDF output of the data.
(cf. also \ttt{\$out\_file}, \ttt{compile\_analysis})
%%%%%
\item
\ttt{write\_slha} \newline
Demands \whizard\ to write out a file in the SUSY Les Houches accord
(SLHA) format. (cf. also \ttt{read\_slha}, \ttt{?slha\_read\_decays},
\ttt{?slha\_read\_input}, \ttt{?slha\_read\_spectrum})
%%%%%
\end{itemize}
\section{Variables}
\subsection{Rebuild Variables}
\begin{itemize}
\item
\ttt{?rebuild\_events} \qquad (default: \ttt{false}) \newline
This logical variable, if set \ttt{true} triggers \whizard\ to newly
create an event sample, even if nothing seems to have changed,
including the MD5 checksum. This can be used when manually
manipulating some settings. (cf also \ttt{?rebuild\_grids},
\ttt{?rebuild\_library}, \ttt{?rebuild\_phase\_space})
%%%%%
\item
\ttt{?rebuild\_grids} \qquad (default: \ttt{false}) \newline
The logical variable \ttt{?rebuild\_grids} forces \whizard\ to newly
create the VAMP grids when using VAMP as an integration method, even
if they are already present. (cf. also \ttt{?rebuild\_events},
\ttt{?rebuild\_library}, \ttt{?rebuild\_phase\_space})
%%%%%
\item
\ttt{?rebuild\_library} \qquad (default: \ttt{false}) \newline
The logical variable \ttt{?rebuild\_library = true/false} specifies
whether the library(-ies) for the matrix element code for processes is
re-generated (incl. possible Makefiles etc.) by the corresponding ME
method (e.g. if the process has been changed, but not its name). This
can also be set as a command-line option \ttt{whizard --rebuild}. The
default is \ttt{false}, i.e. code is never re-generated if it is
present and the MD5 checksum is valid.
(cf. also \ttt{?recompile\_library}, \ttt{?rebuild\_grids},
\ttt{?rebuild\_phase\_space})
%%%%%
\item
\ttt{?rebuild\_phase\_space} \qquad (default: \ttt{false}) \newline
This logical variable, if set \ttt{true}, triggers recreation of the
phase space file by \whizard\. (cf. also \ttt{?rebuild\_events},
\ttt{?rebuild\_grids}, \ttt{?rebuild\_library})
%%%%%
\item
\ttt{?recompile\_library} \qquad (default: \ttt{false}) \newline
The logical variable \ttt{?recompile\_library = true/false} specifies
whether the library(-ies) for the matrix element code for processes is
re-compiled (e.g. if the process code has been manually modified by
the user). This can also be set as a command-line option \ttt{whizard
--recompile}. The default is \ttt{false}, i.e. code is never
re-compiled if its corresponding object file is present. (cf. also
\ttt{?rebuild\_library})
%%%%%
\end{itemize}
\subsection{Standard Variables}
\begin{itemize}
\input{variables}
\end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage
\section*{Acknowledgements}
We would like to thank E.~Boos, R.~Chierici, K.~Desch, M.~Kobel,
F.~Krauss, P.M.~Manakos, N.~Meyer, K.~M\"onig, H.~Reuter, T.~Robens,
S.~Rosati, J.~Schumacher, M.~Schumacher, and C.~Schwinn who
contributed to \whizard\ by their suggestions, bits of codes and
valuable remarks and/or used several versions of the program for
real-life applications and thus helped a lot in debugging and
improving the code. Special thanks go to A.~Vaught and J.~Weill for
their continuos efforts on improving the g95 and gfortran compilers,
respectively.
%\end{fmffile}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% References
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\baselineskip15pt
\begin{thebibliography}{19}
\bibitem{PYTHIA}
T.~Sj\"ostrand,
Comput.\ Phys.\ Commun.\ \textbf{82} (1994) 74.
\bibitem{comphep}
A.~Pukhov, \emph{et al.},
Preprint INP MSU 98-41/542, \ttt{hep-ph/9908288}.
\bibitem{madgraph}
T.~Stelzer and W.F.~Long,
Comput.\ Phys.\ Commun.\ \textbf{81} (1994) 357.
\bibitem{omega}
T.~Ohl,
\emph{Proceedings of the Seventh International Workshop on
Advanced Computing and Analysis Technics in Physics Research},
ACAT 2000, Fermilab, October 2000,
IKDA-2000-30, \ttt{hep-ph/0011243};
M.~Moretti, Th.~Ohl, and J.~Reuter,
LC-TOOL-2001-040
\bibitem{VAMP}
T.~Ohl,
{\em Vegas revisited: Adaptive Monte Carlo integration beyond
factorization},
Comput.\ Phys.\ Commun.\ {\bf 120}, 13 (1999)
[arXiv:hep-ph/9806432].
%%CITATION = CPHCB,120,13;%%
\bibitem{CIRCE}
T.~Ohl,
{\em CIRCE version 1.0: Beam spectra for simulating linear collider
physics},
Comput.\ Phys.\ Commun.\ {\bf 101}, 269 (1997)
[arXiv:hep-ph/9607454].
%%CITATION = CPHCB,101,269;%%
%\cite{Gribov:1972rt}
\bibitem{Gribov:1972rt}
V.~N.~Gribov and L.~N.~Lipatov,
{\em e+ e- pair annihilation and deep inelastic e p scattering in
perturbation theory},
Sov.\ J.\ Nucl.\ Phys.\ {\bf 15}, 675 (1972)
[Yad.\ Fiz.\ {\bf 15}, 1218 (1972)].
%%CITATION = SJNCA,15,675;%%
%\cite{Kuraev:1985hb}
\bibitem{Kuraev:1985hb}
E.~A.~Kuraev and V.~S.~Fadin,
{\em On Radiative Corrections to e+ e- Single Photon Annihilation at
High-Energy},
Sov.\ J.\ Nucl.\ Phys.\ {\bf 41}, 466 (1985)
[Yad.\ Fiz.\ {\bf 41}, 733 (1985)].
%%CITATION = SJNCA,41,466;%%
%\cite{Skrzypek:1990qs}
\bibitem{Skrzypek:1990qs}
M.~Skrzypek and S.~Jadach,
{\em Exact and approximate solutions for the electron nonsinglet
structure function in QED},
Z.\ Phys.\ C {\bf 49}, 577 (1991).
%%CITATION = ZEPYA,C49,577;%%
%\cite{Schulte:1998au}
\bibitem{Schulte:1998au}
D.~Schulte,
{\em Beam-beam simulations with Guinea-Pig},
eConf C {\bf 980914}, 127 (1998).
%%CITATION = ECONF,C980914,127;%%
%\cite{Schulte:1999tx}
\bibitem{Schulte:1999tx}
D.~Schulte,
{\em Beam-beam simulations with GUINEA-PIG},
CERN-PS-99-014-LP.
%%CITATION = CERN-PS-99-014-LP;%%
%\cite{Schulte:2007zz}
\bibitem{Schulte:2007zz}
D.~Schulte, M.~Alabau, P.~Bambade, O.~Dadoun, G.~Le Meur, C.~Rimbault and F.~Touze,
{\em GUINEA PIG++ : An Upgraded Version of the Linear Collider Beam
Beam Interaction Simulation Code GUINEA PIG},
Conf.\ Proc.\ C {\bf 070625}, 2728 (2007).
%%CITATION = CONFP,C070625,2728;%%
%\cite{Behnke:2013xla}
\bibitem{Behnke:2013xla}
T.~Behnke, J.~E.~Brau, B.~Foster, J.~Fuster, M.~Harrison, J.~M.~Paterson, M.~Peskin and M.~Stanitzki {\it et al.},
{\em The International Linear Collider Technical Design Report -
Volume 1: Executive Summary},
arXiv:1306.6327 [physics.acc-ph].
%%CITATION = ARXIV:1306.6327;%%
%\cite{Baer:2013cma}
\bibitem{Baer:2013cma}
H.~Baer, T.~Barklow, K.~Fujii, Y.~Gao, A.~Hoang, S.~Kanemura, J.~List and H.~E.~Logan {\it et al.},
{\em The International Linear Collider Technical Design Report -
Volume 2: Physics},
arXiv:1306.6352 [hep-ph].
%%CITATION = ARXIV:1306.6352;%%
%\cite{Adolphsen:2013jya}
\bibitem{Adolphsen:2013jya}
C.~Adolphsen, M.~Barone, B.~Barish, K.~Buesser, P.~Burrows, J.~Carwardine, J.~Clark and H\'{e}l\`{e}n.~M.~Durand {\it et al.},
{\em The International Linear Collider Technical Design Report -
Volume 3.I: Accelerator \& in the Technical Design Phase},
arXiv:1306.6353 [physics.acc-ph].
%%CITATION = ARXIV:1306.6353;%%
%\cite{Adolphsen:2013kya}
\bibitem{Adolphsen:2013kya}
C.~Adolphsen, M.~Barone, B.~Barish, K.~Buesser, P.~Burrows, J.~Carwardine, J.~Clark and H\'{e}l\`{e}n.~M.~Durand {\it et al.},
{\em The International Linear Collider Technical Design Report -
Volume 3.II: Accelerator Baseline Design},
arXiv:1306.6328 [physics.acc-ph].
%%CITATION = ARXIV:1306.6328;%%
%\cite{Behnke:2013lya}
\bibitem{Behnke:2013lya}
T.~Behnke, J.~E.~Brau, P.~N.~Burrows, J.~Fuster, M.~Peskin, M.~Stanitzki, Y.~Sugimoto and S.~Yamada {\it et al.},
%``The International Linear Collider Technical Design Report - Volume 4: Detectors,''
arXiv:1306.6329 [physics.ins-det].
%%CITATION = ARXIV:1306.6329;%%
%\cite{Aicheler:2012bya}
\bibitem{Aicheler:2012bya}
M.~Aicheler, P.~Burrows, M.~Draper, T.~Garvey, P.~Lebrun, K.~Peach and N.~Phinney {\it et al.},
{\em A Multi-TeV Linear Collider Based on CLIC Technology : CLIC
Conceptual Design Report},
CERN-2012-007.
%%CITATION = CERN-2012-007;%%
%\cite{Lebrun:2012hj}
\bibitem{Lebrun:2012hj}
P.~Lebrun, L.~Linssen, A.~Lucaci-Timoce, D.~Schulte, F.~Simon, S.~Stapnes, N.~Toge and H.~Weerts {\it et al.},
{\em The CLIC Programme: Towards a Staged e+e- Linear Collider
Exploring the Terascale : CLIC Conceptual Design Report},
arXiv:1209.2543 [physics.ins-det].
%%CITATION = ARXIV:1209.2543;%%
%\cite{Linssen:2012hp}
\bibitem{Linssen:2012hp}
L.~Linssen, A.~Miyamoto, M.~Stanitzki and H.~Weerts,
{\em Physics and Detectors at CLIC: CLIC Conceptual Design Report},
arXiv:1202.5940 [physics.ins-det].
%%CITATION = ARXIV:1202.5940;%%
%\cite{vonWeizsacker:1934sx}
\bibitem{vonWeizsacker:1934sx}
C.~F.~von Weizs\"acker,
{\em Radiation emitted in collisions of very fast electrons},
Z.\ Phys.\ {\bf 88}, 612 (1934).
%%CITATION = ZEPYA,88,612;%%
%\cite{Williams:1934ad}
\bibitem{Williams:1934ad}
E.~J.~Williams,
{\em Nature of the high-energy particles of penetrating radiation
and status of ionization and radiation formulae},
Phys.\ Rev.\ {\bf 45}, 729 (1934).
%%CITATION = PHRVA,45,729;%%
%\cite{Budnev:1974de}
\bibitem{Budnev:1974de}
V.~M.~Budnev, I.~F.~Ginzburg, G.~V.~Meledin and V.~G.~Serbo,
{\em The Two photon particle production mechanism. Physical problems.
Applications. Equivalent photon approximation},
Phys.\ Rept.\ {\bf 15} (1974) 181.
%%CITATION = PRPLC,15,181;%%
%\cite{Ginzburg:1981vm}
\bibitem{Ginzburg:1981vm}
I.~F.~Ginzburg, G.~L.~Kotkin, V.~G.~Serbo and V.~I.~Telnov,
{\em Colliding gamma e and gamma gamma Beams Based on the Single
Pass Accelerators (of Vlepp Type)},
Nucl.\ Instrum.\ Meth.\ {\bf 205}, 47 (1983).
%%CITATION = NUIMA,205,47;%%
%\cite{Telnov:1989sd}
\bibitem{Telnov:1989sd}
V.~I.~Telnov,
{\em Problems of Obtaining $\gamma \gamma$ and $\gamma \epsilon$
Colliding Beams at Linear Colliders},
Nucl.\ Instrum.\ Meth.\ A {\bf 294}, 72 (1990).
%%CITATION = NUIMA,A294,72;%%
%\cite{Telnov:1995hc}
\bibitem{Telnov:1995hc}
V.~I.~Telnov,
{\em Principles of photon colliders},
Nucl.\ Instrum.\ Meth.\ A {\bf 355}, 3 (1995).
%%CITATION = NUIMA,A355,3;%%
%\cite{AguilarSaavedra:2001rg}
\bibitem{AguilarSaavedra:2001rg}
J.~A.~Aguilar-Saavedra {\it et al.} [ECFA/DESY LC Physics Working
Group Collaboration],
{\em TESLA: The Superconducting electron positron linear collider
with an integrated x-ray laser laboratory. Technical design
report. Part 3. Physics at an e+ e- linear collider},
hep-ph/0106315.
%%CITATION = HEP-PH/0106315;%%
%\cite{Richard:2001qm}
\bibitem{Richard:2001qm}
F.~Richard, J.~R.~Schneider, D.~Trines and A.~Wagner,
{\em TESLA, The Superconducting Electron Positron Linear Collider
with an Integrated X-ray Laser Laboratory, Technical Design Report
Part 1 : Executive Summary},
hep-ph/0106314.
%%CITATION = HEP-PH/0106314;%%
%\cite{Sudakov:1954sw}
\bibitem{Sudakov:1954sw}
V.~V.~Sudakov,
%``Vertex parts at very high-energies in quantum electrodynamics,''
Sov.\ Phys.\ JETP {\bf 3}, 65 (1956)
[Zh.\ Eksp.\ Teor.\ Fiz.\ {\bf 30}, 87 (1956)].
%%CITATION = SPHJA,3,65;%%
\cite{Sjostrand:1985xi}
\bibitem{Sjostrand:1985xi}
T.~Sjostrand,
%``A Model for Initial State Parton Showers,''
Phys.\ Lett.\ {\bf 157B}, 321 (1985).
doi:10.1016/0370-2693(85)90674-4
%%CITATION = doi:10.1016/0370-2693(85)90674-4;%%
%\cite{Sjostrand:2006za}
\bibitem{Sjostrand:2006za}
T.~Sjostrand, S.~Mrenna and P.~Z.~Skands,
%``PYTHIA 6.4 Physics and Manual,''
JHEP {\bf 0605}, 026 (2006)
doi:10.1088/1126-6708/2006/05/026
[hep-ph/0603175].
%%CITATION = doi:10.1088/1126-6708/2006/05/026;%%
%\cite{Ohl:1998jn}
\bibitem{Ohl:1998jn}
T.~Ohl,
{\em Vegas revisited: Adaptive Monte Carlo integration beyond
factorization},
Comput.\ Phys.\ Commun.\ {\bf 120}, 13 (1999)
[hep-ph/9806432].
%%CITATION = HEP-PH/9806432;%%
%\cite{Lepage:1980dq}
\bibitem{Lepage:1980dq}
G.~P.~Lepage,
%``Vegas: An Adaptive Multidimensional Integration Program,''
CLNS-80/447.
%%CITATION = CLNS-80/447;%%
\bibitem{HDECAY}
A.~Djouadi, J.~Kalinowski, M.~Spira,
Comput.\ Phys.\ Commun.\ \textbf{108} (1998) 56-74.
%\cite{Beyer:2006hx}
\bibitem{Beyer:2006hx}
M.~Beyer, W.~Kilian, P.~Krstono\v{s}ic, K.~M\"onig, J.~Reuter, E.~Schmidt
and H.~Schr\"oder,
{\em Determination of New Electroweak Parameters at the ILC -
Sensitivity to New Physics},
Eur.\ Phys.\ J.\ C {\bf 48}, 353 (2006)
[hep-ph/0604048].
%%CITATION = HEP-PH/0604048;%%
%\cite{Alboteanu:2008my}
\bibitem{Alboteanu:2008my}
A.~Alboteanu, W.~Kilian and J.~Reuter,
{\em Resonances and Unitarity in Weak Boson Scattering at the LHC},
JHEP {\bf 0811}, 010 (2008)
[arXiv:0806.4145 [hep-ph]].
%%CITATION = ARXIV:0806.4145;%%
%\cite{Binoth:2010xt}
\bibitem{Binoth:2010xt}
T.~Binoth {\it et al.},
%``A Proposal for a standard interface between Monte Carlo tools and one-loop programs,''
Comput.\ Phys.\ Commun.\ {\bf 181}, 1612 (2010)
doi:10.1016/j.cpc.2010.05.016
[arXiv:1001.1307 [hep-ph]].
%%CITATION = doi:10.1016/j.cpc.2010.05.016;%%
%\cite{Alioli:2013nda}
\bibitem{Alioli:2013nda}
S.~Alioli {\it et al.},
%``Update of the Binoth Les Houches Accord for a standard interface
%between Monte Carlo tools and one-loop programs,''
Comput.\ Phys.\ Commun.\ {\bf 185}, 560 (2014)
doi:10.1016/j.cpc.2013.10.020
[arXiv:1308.3462 [hep-ph]].
%%CITATION = doi:10.1016/j.cpc.2013.10.020;%%
%\cite{Speckner:2010zi}
\bibitem{Speckner:2010zi}
C.~Speckner,
{\em LHC Phenomenology of the Three-Site Higgsless Model},
PhD thesis, arXiv:1011.1851 [hep-ph].
%%CITATION = ARXIV:1011.1851;%%
%\cite{Chivukula:2006cg}
\bibitem{Chivukula:2006cg}
R.~S.~Chivukula, B.~Coleppa, S.~Di Chiara, E.~H.~Simmons, H.~-J.~He,
M.~Kurachi and M.~Tanabashi,
{\em A Three Site Higgsless Model},
Phys.\ Rev.\ D {\bf 74}, 075011 (2006)
[hep-ph/0607124].
%%CITATION = HEP-PH/0607124;%%
%\cite{Chivukula:2005xm}
\bibitem{Chivukula:2005xm}
R.~S.~Chivukula, E.~H.~Simmons, H.~-J.~He, M.~Kurachi and M.~Tanabashi,
{\em Ideal fermion delocalization in Higgsless models},
Phys.\ Rev.\ D {\bf 72}, 015008 (2005)
[hep-ph/0504114].
%%CITATION = HEP-PH/0504114;%%
%\cite{Ohl:2008ri}
\bibitem{Ohl:2008ri}
T.~Ohl and C.~Speckner,
{\em Production of Almost Fermiophobic Gauge Bosons in the Minimal
Higgsless Model at the LHC},
Phys.\ Rev.\ D {\bf 78}, 095008 (2008)
[arXiv:0809.0023 [hep-ph]].
%%CITATION = ARXIV:0809.0023;%%
%\cite{Ohl:2002jp}
\bibitem{Ohl:2002jp}
T.~Ohl and J.~Reuter,
{\em Clockwork SUSY: Supersymmetric Ward and Slavnov-Taylor
identities at work in Green's functions and scattering
amplitudes},
Eur.\ Phys.\ J.\ C {\bf 30}, 525 (2003)
[hep-th/0212224].
%%CITATION = HEP-TH/0212224;%%
%\cite{Reuter:2009ex}
\bibitem{Reuter:2009ex}
J.~Reuter and F.~Braam,
{\em The NMSSM implementation in WHIZARD},
AIP Conf.\ Proc.\ {\bf 1200}, 470 (2010)
[arXiv:0909.3059 [hep-ph]].
%%CITATION = ARXIV:0909.3059;%%
%\cite{Kalinowski:2008fk}
\bibitem{Kalinowski:2008fk}
J.~Kalinowski, W.~Kilian, J.~Reuter, T.~Robens and K.~Rolbiecki,
{\em Pinning down the Invisible Sneutrino},
JHEP {\bf 0810}, 090 (2008)
[arXiv:0809.3997 [hep-ph]].
%%CITATION = ARXIV:0809.3997;%%
%\cite{Robens:2008sa}
\bibitem{Robens:2008sa}
T.~Robens, J.~Kalinowski, K.~Rolbiecki, W.~Kilian and J.~Reuter,
{\em (N)LO Simulation of Chargino Production and Decay},
Acta Phys.\ Polon.\ B {\bf 39}, 1705 (2008)
[arXiv:0803.4161 [hep-ph]].
%%CITATION = ARXIV:0803.4161;%%
%\cite{Kilian:2004pp}
\bibitem{Kilian:2004pp}
W.~Kilian, D.~Rainwater and J.~Reuter,
{\em Pseudo-axions in little Higgs models},
Phys.\ Rev.\ D {\bf 71}, 015008 (2005)
[hep-ph/0411213].
%%CITATION = HEP-PH/0411213;%%
%\cite{Kilian:2006eh}
\bibitem{Kilian:2006eh}
W.~Kilian, D.~Rainwater and J.~Reuter,
{\em Distinguishing little-Higgs product and simple group models at
the LHC and ILC},
Phys.\ Rev.\ D {\bf 74}, 095003 (2006)
[Erratum-ibid.\ D {\bf 74}, 099905 (2006)]
[hep-ph/0609119].
%%CITATION = HEP-PH/0609119;%%
%\cite{Ohl:2004tn}
\bibitem{Ohl:2004tn}
T.~Ohl and J.~Reuter,
{\em Testing the noncommutative standard model at a future photon
collider},
Phys.\ Rev.\ D {\bf 70}, 076007 (2004)
[hep-ph/0406098].
%%CITATION = HEP-PH/0406098;%%
%\cite{Ohl:2010zf}
\bibitem{Ohl:2010zf}
T.~Ohl and C.~Speckner,
{\em The Noncommutative Standard Model and Polarization in Charged
Gauge Boson Production at the LHC},
Phys.\ Rev.\ D {\bf 82}, 116011 (2010)
[arXiv:1008.4710 [hep-ph]].
%%CITATION = ARXIV:1008.4710;%%
\bibitem{LesHouches}
E.~Boos {\it et al.},
{\em Generic user process interface for event generators},
arXiv:hep-ph/0109068.
%%CITATION = HEP-PH/0109068;%%
\bibitem{Skands:2003cj}
P.~Z.~Skands {\it et al.},
{\em SUSY Les Houches Accord: Interfacing SUSY Spectrum Calculators, Decay
Packages, and Event Generators},
JHEP {\bf 0407}, 036 (2004)
[arXiv:hep-ph/0311123].
%%CITATION = JHEPA,0407,036;%%
%\cite{AguilarSaavedra:2005pw}
\bibitem{AguilarSaavedra:2005pw}
J.~A.~Aguilar-Saavedra, A.~Ali, B.~C.~Allanach, R.~L.~Arnowitt, H.~A.~Baer, J.~A.~Bagger, C.~Balazs and V.~D.~Barger {\it et al.},
{\em Supersymmetry parameter analysis: SPA convention and project},
Eur.\ Phys.\ J.\ C {\bf 46}, 43 (2006)
[hep-ph/0511344].
%%CITATION = HEP-PH/0511344;%%
%\cite{Allanach:2008qq}
\bibitem{Allanach:2008qq}
B.~C.~Allanach, C.~Balazs, G.~Belanger, M.~Bernhardt, F.~Boudjema, D.~Choudhury, K.~Desch and U.~Ellwanger {\it et al.},
%``SUSY Les Houches Accord 2,''
Comput.\ Phys.\ Commun.\ {\bf 180}, 8 (2009)
[arXiv:0801.0045 [hep-ph]].
%%CITATION = ARXIV:0801.0045;%%
\bibitem{LHEF}
J.~Alwall {\it et al.},
{\em A standard format for Les Houches event files},
Comput.\ Phys.\ Commun.\ {\bf 176}, 300 (2007)
[arXiv:hep-ph/0609017].
%%CITATION = CPHCB,176,300;%%
\bibitem{Hagiwara:2005wg}
K.~Hagiwara {\it et al.},
{\em Supersymmetry simulations with off-shell effects for LHC and
ILC},
Phys.\ Rev.\ D {\bf 73}, 055005 (2006)
[arXiv:hep-ph/0512260].
%%CITATION = PHRVA,D73,055005;%%
\bibitem{Allanach:2002nj}
B.~C.~Allanach {\it et al.},
{\em The Snowmass points and slopes: Benchmarks for SUSY searches},
in {\it Proc. of the APS/DPF/DPB Summer Study on the Future of Particle Physics (Snowmass 2001) } ed. N.~Graf,
Eur.\ Phys.\ J.\ C {\bf 25} (2002) 113
[eConf {\bf C010630} (2001) P125]
[arXiv:hep-ph/0202233].
%%CITATION = HEP-PH 0202233;%%
\bibitem{PeskinSchroeder}
M.E. Peskin, D.V.Schroeder, {\em An Introduction to Quantum Field
Theory}, Addison-Wesley Publishing Co., 1995.
\bibitem{UtaKlein}
U. Klein, O. Fischer, {\em private communications}.
\bibitem{stdhep}
L.~Garren, {\em StdHep, Monte Carlo Standardization at FNAL},
Fermilab CS-doc-903,
\url{http://cd-docdb.fnal.gov/cgi-bin/ShowDocument?docid=903}
%\cite{Frixione:1998jh}
\bibitem{Frixione:1998jh}
S.~Frixione,
%``Isolated photons in perturbative QCD,''
Phys.\ Lett.\ B {\bf 429}, 369 (1998)
doi:10.1016/S0370-2693(98)00454-7
[hep-ph/9801442].
%%CITATION = doi:10.1016/S0370-2693(98)00454-7;%%
\bibitem{LHAPDF}
W.~Giele {\it et al.},
{\em The QCD / SM working group: Summary report},
arXiv:hep-ph/0204316;
%%CITATION = HEP-PH/0204316;%%
M.~R.~Whalley, D.~Bourilkov and R.~C.~Group,
{\em The Les Houches Accord PDFs (LHAPDF) and Lhaglue},
arXiv:hep-ph/0508110;
%%CITATION = HEP-PH/0508110;%%
D.~Bourilkov, R.~C.~Group and M.~R.~Whalley,
{\em LHAPDF: PDF use from the Tevatron to the LHC},
arXiv:hep-ph/0605240.
%%CITATION = HEP-PH/0605240;%%
\bibitem{HepMC}
M.~Dobbs and J.~B.~Hansen,
{\em The HepMC C++ Monte Carlo event record for High Energy
Physics},
Comput.\ Phys.\ Commun.\ {\bf 134}, 41 (2001).
%%CITATION = CPHCB,134,41;%%
%\cite{Boos:2004kh}
\bibitem{Boos:2004kh}
E.~Boos {\it et al.} [CompHEP Collaboration],
%``CompHEP 4.4: Automatic computations from Lagrangians to events,''
Nucl.\ Instrum.\ Meth.\ A {\bf 534}, 250 (2004)
[hep-ph/0403113].
%%CITATION = HEP-PH/0403113;%%
%493 citations counted in INSPIRE as of 12 May 2014
% Parton distributions
%\cite{Pumplin:2002vw}
\bibitem{Pumplin:2002vw}
J.~Pumplin, D.~R.~Stump, J.~Huston {\it et al.},
{\em New generation of parton distributions with uncertainties from
global QCD analysis},
JHEP {\bf 0207}, 012 (2002).
[hep-ph/0201195].
%\cite{Martin:2004dh}
\bibitem{Martin:2004dh}
A.~D.~Martin, R.~G.~Roberts, W.~J.~Stirling {\it et al.},
{\em Parton distributions incorporating QED contributions},
Eur.\ Phys.\ J.\ {\bf C39}, 155-161 (2005).
[hep-ph/0411040].
%\cite{Martin:2009iq}
\bibitem{Martin:2009iq}
A.~D.~Martin, W.~J.~Stirling, R.~S.~Thorne {\it et al.},
{\em Parton distributions for the LHC},
Eur.\ Phys.\ J.\ {\bf C63}, 189-285 (2009).
[arXiv:0901.0002 [hep-ph]].
%\cite{Lai:2010vv}
\bibitem{Lai:2010vv}
H.~L.~Lai, M.~Guzzi, J.~Huston, Z.~Li, P.~M.~Nadolsky, J.~Pumplin and C.~P.~Yuan,
{\em New parton distributions for collider physics},
Phys.\ Rev.\ D {\bf 82}, 074024 (2010)
[arXiv:1007.2241 [hep-ph]].
%%CITATION = PHRVA,D82,074024;%%
%\cite{Owens:2012bv}
\bibitem{Owens:2012bv}
J.~F.~Owens, A.~Accardi and W.~Melnitchouk,
{\em Global parton distributions with nuclear and finite-$Q^2$
corrections},
Phys.\ Rev.\ D {\bf 87}, no. 9, 094012 (2013)
[arXiv:1212.1702 [hep-ph]].
%%CITATION = ARXIV:1212.1702;%%
%\cite{Accardi:2016qay}
\bibitem{Accardi:2016qay}
A.~Accardi, L.~T.~Brady, W.~Melnitchouk, J.~F.~Owens and N.~Sato,
%``Constraints on large-$x$ parton distributions from new weak boson production and deep-inelastic scattering data,''
arXiv:1602.03154 [hep-ph].
%%CITATION = ARXIV:1602.03154;%%
%\cite{Harland-Lang:2014zoa}
\bibitem{Harland-Lang:2014zoa}
L.~A.~Harland-Lang, A.~D.~Martin, P.~Motylinski and R.~S.~Thorne,
%``Parton distributions in the LHC era: MMHT 2014 PDFs,''
arXiv:1412.3989 [hep-ph].
%%CITATION = ARXIV:1412.3989;%%
%\cite{Dulat:2015mca}
\bibitem{Dulat:2015mca}
S.~Dulat {\it et al.},
%``The CT14 Global Analysis of Quantum Chromodynamics,''
arXiv:1506.07443 [hep-ph].
%%CITATION = ARXIV:1506.07443;%%
%\cite{Salam:2008qg}
\bibitem{Salam:2008qg}
G.~P.~Salam and J.~Rojo,
{\em A Higher Order Perturbative Parton Evolution Toolkit (HOPPET)},
Comput.\ Phys.\ Commun.\ {\bf 180}, 120 (2009)
[arXiv:0804.3755 [hep-ph]].
%%CITATION = ARXIV:0804.3755;%%
%\cite{Kilian:2011ka}
\bibitem{Kilian:2011ka}
W.~Kilian, J.~Reuter, S.~Schmidt and D.~Wiesler,
{\em An Analytic Initial-State Parton Shower},
JHEP {\bf 1204} (2012) 013
[arXiv:1112.1039 [hep-ph]].
%%CITATION = ARXIV:1112.1039;%%
%\cite{Staub:2008uz}
\bibitem{Staub:2008uz}
F.~Staub,
{\em Sarah},
arXiv:0806.0538 [hep-ph].
%%CITATION = ARXIV:0806.0538;%%
%\cite{Staub:2009bi}
\bibitem{Staub:2009bi}
F.~Staub,
{\em From Superpotential to Model Files for FeynArts and
CalcHep/CompHep},
Comput.\ Phys.\ Commun.\ {\bf 181}, 1077 (2010)
[arXiv:0909.2863 [hep-ph]].
%%CITATION = ARXIV:0909.2863;%%
%\cite{Staub:2010jh}
\bibitem{Staub:2010jh}
F.~Staub,
{\em Automatic Calculation of supersymmetric Renormalization Group
Equations and Self Energies},
Comput.\ Phys.\ Commun.\ {\bf 182}, 808 (2011)
[arXiv:1002.0840 [hep-ph]].
%%CITATION = ARXIV:1002.0840;%%
%\cite{Staub:2012pb}
\bibitem{Staub:2012pb}
F.~Staub,
{\em SARAH 3.2: Dirac Gauginos, UFO output, and more},
Computer Physics Communications {\bf 184}, pp. 1792 (2013)
[Comput.\ Phys.\ Commun.\ {\bf 184}, 1792 (2013)]
[arXiv:1207.0906 [hep-ph]].
%%CITATION = ARXIV:1207.0906;%%
%\cite{Staub:2013tta}
\bibitem{Staub:2013tta}
F.~Staub,
{\em SARAH 4: A tool for (not only SUSY) model builders},
Comput.\ Phys.\ Commun.\ {\bf 185}, 1773 (2014)
[arXiv:1309.7223 [hep-ph]].
%%CITATION = ARXIV:1309.7223;%%
\bibitem{mathematica}
\Mathematica\ is a registered trademark of Wolfram Research, Inc.,
Champain, IL, USA.
%\cite{Porod:2003um}
\bibitem{Porod:2003um}
W.~Porod,
{\em SPheno, a program for calculating supersymmetric spectra, SUSY
particle decays and SUSY particle production at e+ e- colliders},
Comput.\ Phys.\ Commun.\ {\bf 153}, 275 (2003)
[hep-ph/0301101].
%%CITATION = HEP-PH/0301101;%%
%\cite{Porod:2011nf}
\bibitem{Porod:2011nf}
W.~Porod and F.~Staub,
{\em SPheno 3.1: Extensions including flavour, CP-phases and models
beyond the MSSM},
Comput.\ Phys.\ Commun.\ {\bf 183}, 2458 (2012)
[arXiv:1104.1573 [hep-ph]].
%%CITATION = ARXIV:1104.1573;%%
%\cite{Staub:2011dp}
\bibitem{Staub:2011dp}
F.~Staub, T.~Ohl, W.~Porod and C.~Speckner,
%``A Tool Box for Implementing Supersymmetric Models,''
Comput.\ Phys.\ Commun.\ {\bf 183}, 2165 (2012)
[arXiv:1109.5147 [hep-ph]].
%%CITATION = ARXIV:1109.5147;%%
%%%%% FeynRules %%%%%
%\cite{Christensen:2008py}
\bibitem{Christensen:2008py}
N.~D.~Christensen and C.~Duhr,
{\em FeynRules - Feynman rules made easy},
Comput.\ Phys.\ Commun.\ {\bf 180}, 1614 (2009)
[arXiv:0806.4194 [hep-ph]].
%%CITATION = ARXIV:0806.4194;%%
%\cite{Christensen:2009jx}
\bibitem{Christensen:2009jx}
N.~D.~Christensen, P.~de Aquino, C.~Degrande, C.~Duhr, B.~Fuks,
M.~Herquet, F.~Maltoni and S.~Schumann,
{\em A Comprehensive approach to new physics simulations},
Eur.\ Phys.\ J.\ C {\bf 71}, 1541 (2011)
[arXiv:0906.2474 [hep-ph]].
%%CITATION = ARXIV:0906.2474;%%
%\cite{Duhr:2011se}
\bibitem{Duhr:2011se}
C.~Duhr and B.~Fuks,
%``A superspace module for the FeynRules package,''
Comput.\ Phys.\ Commun.\ {\bf 182}, 2404 (2011)
[arXiv:1102.4191 [hep-ph]].
%%CITATION = ARXIV:1102.4191;%%
%\cite{Christensen:2010wz}
\bibitem{Christensen:2010wz}
N.~D.~Christensen, C.~Duhr, B.~Fuks, J.~Reuter and C.~Speckner,
{\em Introducing an interface between WHIZARD and FeynRules},
Eur.\ Phys.\ J.\ C {\bf 72}, 1990 (2012)
[arXiv:1010.3251 [hep-ph]].
%%CITATION = ARXIV:1010.3251;%%
%\cite{Degrande:2011ua}
\bibitem{Degrande:2011ua}
C.~Degrande, C.~Duhr, B.~Fuks, D.~Grellscheid, O.~Mattelaer and T.~Reiter,
%``UFO - The Universal FeynRules Output,''
Comput.\ Phys.\ Commun.\ {\bf 183}, 1201 (2012)
doi:10.1016/j.cpc.2012.01.022
[arXiv:1108.2040 [hep-ph]].
%%CITATION = doi:10.1016/j.cpc.2012.01.022;%%
%\cite{Han:1998sg}
\bibitem{Han:1998sg}
T.~Han, J.~D.~Lykken and R.~-J.~Zhang,
{\em On Kaluza-Klein states from large extra dimensions},
Phys.\ Rev.\ D {\bf 59}, 105006 (1999)
[hep-ph/9811350].
%%CITATION = HEP-PH/9811350;%%
%\cite{Fuks:2012im}
\bibitem{Fuks:2012im}
B.~Fuks,
{\em Beyond the Minimal Supersymmetric Standard Model: from theory
to phenomenology},
Int.\ J.\ Mod.\ Phys.\ A {\bf 27}, 1230007 (2012)
[arXiv:1202.4769 [hep-ph]].
%%CITATION = ARXIV:1202.4769;%%
%\cite{He:2007ge}
\bibitem{He:2007ge}
H.~-J.~He, Y.~-P.~Kuang, Y.~-H.~Qi, B.~Zhang, A.~Belyaev,
R.~S.~Chivukula, N.~D.~Christensen and A.~Pukhov {\it et al.},
{\em CERN LHC Signatures of New Gauge Bosons in Minimal Higgsless
Model},
Phys.\ Rev.\ D {\bf 78}, 031701 (2008)
[arXiv:0708.2588 [hep-ph]].
%%CITATION = ARXIV:0708.2588;%%
%%%%% WHIZARD NLO %%%%%
%\cite{Kilian:2006cj}
\bibitem{Kilian:2006cj}
W.~Kilian, J.~Reuter and T.~Robens,
{\em NLO Event Generation for Chargino Production at the ILC},
Eur.\ Phys.\ J.\ C {\bf 48}, 389 (2006)
[hep-ph/0607127].
%%CITATION = HEP-PH/0607127;%%
%\cite{Binoth:2010ra}
\bibitem{Binoth:2010ra}
J.~R.~Andersen {\it et al.} [SM and NLO Multileg Working Group
Collaboration],
{\em Les Houches 2009: The SM and NLO Multileg Working Group:
Summary report},
arXiv:1003.1241 [hep-ph].
%%CITATION = ARXIV:1003.1241;%%
%\cite{Butterworth:2010ym}
\bibitem{Butterworth:2010ym}
J.~M.~Butterworth, A.~Arbey, L.~Basso, S.~Belov, A.~Bharucha,
F.~Braam, A.~Buckley and M.~Campanelli {\it et al.},
{\em Les Houches 2009: The Tools and Monte Carlo working group
Summary Report},
arXiv:1003.1643 [hep-ph], arXiv:1003.1643 [hep-ph].
%%CITATION = ARXIV:1003.1643;%%
%\cite{Binoth:2009rv}
\bibitem{Binoth:2009rv}
T.~Binoth, N.~Greiner, A.~Guffanti, J.~Reuter, J.-P.~.Guillet and T.~Reiter,
{\em Next-to-leading order QCD corrections to pp --> b anti-b b
anti-b + X at the LHC: the quark induced case},
Phys.\ Lett.\ B {\bf 685}, 293 (2010)
[arXiv:0910.4379 [hep-ph]].
%%CITATION = ARXIV:0910.4379;%%
%\cite{Greiner:2011mp}
\bibitem{Greiner:2011mp}
N.~Greiner, A.~Guffanti, T.~Reiter and J.~Reuter,
{\em NLO QCD corrections to the production of two bottom-antibottom
pairs at the LHC}
Phys.\ Rev.\ Lett.\ {\bf 107}, 102002 (2011)
[arXiv:1105.3624 [hep-ph]].
%% CITATION = ARXIV:1105.3624;%%
%\cite{L_Ecuyer:2002}
\bibitem{L_Ecuyer:2002}
P.~L\'{e}Ecuyer, R.~Simard, E.~J.~Chen, and W.~D.~Kelton,
{\em An Object-Oriented Random-Number Package with Many Long Streams and
Substreams},
Operations Research, vol. 50, no. 6, pp. 1073-1075, Dec. 2002.
%\cite{Platzer:2013esa}
\bibitem{Platzer:2013esa}
S.~Pl\"atzer,
{\em RAMBO on diet},
[arXiv:1308.2922 [hep-ph]].
%% CITATION = ARXIV:1308.2922;%%
%\cite{Kleiss:1991rn}
\bibitem{Kleiss:1991rn}
R.~Kleiss and W.~J.~Stirling,
{\em Massive multiplicities and Monte Carlo},
Nucl.\ Phys.\ B {\bf 385}, 413 (1992).
doi:10.1016/0550-3213(92)90107-M
%%CITATION = doi:10.1016/0550-3213(92)90107-M;%%
%\cite{Kleiss:1985gy}
\bibitem{Kleiss:1985gy}
R.~Kleiss, W.~J.~Stirling and S.~D.~Ellis,
{\em A New Monte Carlo Treatment of Multiparticle Phase Space at High-energies},
Comput.\ Phys.\ Commun.\ {\bf 40} (1986) 359.
doi:10.1016/0010-4655(86)90119-0
%% CITATION = doi:10.1016/0010-4655(86)90119-0;%%
%\cite{Brun:1997pa}
\bibitem{Brun:1997pa}
R.~Brun and F.~Rademakers,
{\em ROOT: An object oriented data analysis framework},
Nucl. Instrum. Meth. A \textbf{389}, 81-86 (1997)
doi:10.1016/S0168-9002(97)00048-X
%\cite{Buckley:2010ar}
\bibitem{Buckley:2010ar}
A.~Buckley, J.~Butterworth, L.~L\"onnblad, D.~Grellscheid, H.~Hoeth, J.~Monk, H.~Schulz and F.~Siegert,
{\em Rivet user manual},
Comput. Phys. Commun. \textbf{184}, 2803-2819 (2013)
doi:10.1016/j.cpc.2013.05.021
[arXiv:1003.0694 [hep-ph]].
%\cite{Bierlich:2019rhm}
\bibitem{Bierlich:2019rhm}
C.~Bierlich, A.~Buckley, J.~Butterworth, C.~H.~Christensen, L.~Corpe,
D.~Grellscheid, J.~F.~Grosse-Oetringhaus, C.~Gutschow,
P.~Karczmarczyk, J.~Klein, L.~L\"onnblad, C.~S.~Pollard, P.~Richardson,
H.~Schulz and F.~Siegert,
{\em Robust Independent Validation of Experiment and Theory: Rivet
version 3},
SciPost Phys. \textbf{8}, 026 (2020)
doi:10.21468/SciPostPhys.8.2.026
[arXiv:1912.05451 [hep-ph]].
%\cite{deFavereau:2013fsa}
\bibitem{deFavereau:2013fsa}
J.~de Favereau \textit{et al.} [DELPHES 3],
{\em DELPHES 3, A modular framework for fast simulation of a generic
collider experiment},
JHEP \textbf{02}, 057 (2014)
doi:10.1007/JHEP02(2014)057
[arXiv:1307.6346 [hep-ex]]
\end{thebibliography}
\end{document}