Page MenuHomeHEPForge
Files F8309563

manual.tex
No OneTemporary
Actions

manual.tex
View Options

\documentclass[12pt]{book}
%\usepackage{feynmp}
\usepackage{graphics,graphicx}
\usepackage{color}
\usepackage{amsmath,amssymb}
\usepackage[bookmarks,bookmarksnumbered=true]{hyperref}
\usepackage{url}
%BEGIN LATEX
\usepackage{supertabular,verbatim}
\IfFileExists{hevea.sty}{\usepackage{hevea}}
%END LATEX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Macro section
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\email}[2]{\thanks{\ahref{#1@{}#2}{#1@{}#2}}}
\newcommand{\whizardpage}{\url{http://whizard.event-generator.org}}
\newcommand{\hepforgepage}{\url{http://projects.hepforge.org/whizard}}
%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
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Macros specific for this paper
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\ttt}[1]{\texttt{#1}}
\newcommand{\whizard}{\texttt{WHIZARD}}
\newcommand{\oMega}{\texttt{O'Mega}}
\newcommand{\vamp}{\texttt{VAMP}}
\newcommand{\vegas}{\texttt{VEGAS}}
\newcommand{\madgraph}{\texttt{MadGraph}}
\newcommand{\helas}{\texttt{HELAS}}
\newcommand{\herwig}{\texttt{HERWIG}}
\newcommand{\isajet}{\texttt{ISAJET}}
\newcommand{\pythia}{\texttt{PYTHIA}}
\newcommand{\jetset}{\texttt{JETSET}}
\newcommand{\comphep}{\texttt{CompHEP}}
\newcommand{\circe}{\texttt{CIRCE}}
\newcommand{\gamelan}{\textsf{gamelan}}
\newcommand{\stdhep}{\texttt{STDHEP}}
\newcommand{\pdflib}{\texttt{PDFLIB}}
%%%%%
\newcommand{\fortran}{\texttt{FORTRAN}}
\newcommand{\ocaml}{\texttt{O'Caml}}
\newenvironment{commands}{\begin{quote}\tt}{\end{quote}}
%\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
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
%BEGIN LATEX
%\shortletter % subdivided in paragraphs instead of sections
%\preliminary % mark on title page
%\baselineskip20pt % stretch linespacing in main text
%END LATEX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%BEGIN LATEX
\preprintno{arXiv:0708.4233 (also based on LC-TOOL-2001-039 (revised))}
%END LATEX
\title{%
%HEVEA WHIZARD 2.0 \\
%BEGIN LATEX
\texttt{\huge WHIZARD 2.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}
\\[\baselineskip]
}
\def\authormail{\texttt{kilian@physik.uni-siegen.de},
\texttt{ohl@physik.uni-wuerzburg.de}, \texttt{reuter@physik.uni-freiburg.de}}
\author{%
Wolfgang Kilian,%
\thanks{e-mail: \texttt{kilian@hep.physik.uni-siegen.de}}
Thorsten Ohl,%
\thanks{e-mail: \texttt{ohl@physik.uni-wuerzburg.de}}
J\"urgen Reuter%
\thanks{e-mail: \texttt{reuter@physik.uni-freiburg.de}}}
%BEGIN LATEX
\address{%
Deutsches Elektronen-Synchrotron DESY,
D--22603 Hamburg, Germany \\
%% \authormail
}
%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 events can be written to file in various formats
(including HepMC, LHEF, STDHEP, and ASCII) or analyzed directly on the
parton level using a built-in \LaTeX-compatible graphics package.
\\[\baselineskip]
Tree-level matrix elements are generated automatically for arbitrary
partonic processes by calling the built-in matrix-element generator
\oMega. 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. Using an
adaptive multi-channel method for phase space integration, the program is
able 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, an interface to the LHAPDF library is
provided. Also, the standard PDF library (\pdflib) can be linked.
{\bf Is this still be true?}
\\[\baselineskip]
For Linear Collider physics,
beamstrahlung (\circe), Compton and ISR spectra are included for
electrons and photons. Alternatively, beam-crossing events can be
read directly from file.
\\[\baselineskip]
For showering, fragmenting and hadronizing the final state, a \pythia\
and \herwig interface are provided which follow the Les Houches
Accord. \whizard\ does come with its own shower.
\\[\baselineskip]
The \whizard\ distribution is available at
\begin{center}
\texttt{http://whizard.event-generator.org} or via \newline
\texttt{http://projects.hepforge.org/whizard}
\end{center}
}
%END LATEX
%
\maketitle
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% Text
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\begin{fmffile}
\tableofcontents
\newpage
\chapter{Introduction}
WHIZARD is a modern Monte-Carlo
\newpage
\chapter{Installation}
\section{Prerequisites and Installation}
The concept of the \whizard\ installation has been changed from
version 1 to version 2. Now \whizard\ is centrally installed on a
computer, e.g. in the \texttt{/usr/local}, and then the user has a
working space which is completely separated from the \whizard\
installation directory. The \whizard\ tarball can be downloaded either
from the \whizard\ webpage, \whizardpage, or the corresponding
HepForge webpage, \hepforgepage. On the \whizard\ webpage, one can
either download the tarball of the most recent version (or older
versions), or one can check out the latest version from the subversion
(svn) repository. The latter is only recommended for developers and
users willing to accept that maybe not all newly installed features
are already working. The check-out from the svn repository is done
with the following command:
\begin{equation*}
\texttt{svn checkout http://svn.hepforge.org/whizard/trunk/ SomeLocalDir}
\end{equation*}
Note again, that the subversion contains the latest developer
version. In order to be able, to compile this, one has to first
generate the \ttt{configure} script out of the file \ttt{configure.ac}
by running \ttt{autoreconf} (NOT \ttt{autoconf}) which is part of the
\ttt{autoconf/automake} (\url{http://www.gnu.org/software/autoconf/}
and \url{http://www.gnu.org/software/automake}) package. Furthermore,
the development version also needs the \ttt{noweb} tools to be
installed on the system in order to extract the source codes and
documentation from several so called \ttt{.nw} files. The \ttt{noweb}
package can be downloaded and installed from
\url{http://www.cs.tufts.edu/~nr/noweb/}.
The general prerequisites for the installation (i.e. also from the
tarball, not only from the svn) are standard tools for software
development like \texttt{make} etc., and two different compilers, a
\fortran \texttt{2003} for the \whizard\ core and its corresponding
libraries as well as an \ocaml\ compiler for the \oMega\ matrix
element generator.
Unpack the tarball, go to the \whizard\ directory, create a new
directory and go to it. In that directory, perform a
\url{../configure FC=<your FORTRAN compiler> --prefix=/usr/local}.
Note that this is because the source and compile directories should be
different to avoid any problems during compilation and
installation. \url{../configure --help} shows you the options for the
configure process you have. The \texttt{FC} environment variable
allows you to specify your \fortran\ compiler of choice. Note that
\whizard\ 2 has been written in \fortran \texttt{2003} in a fully
object-oriented way. We highly recommend usage of the standard
\texttt{gfortran} compiler from version 4.5.0 on. You can access the
help menu of configure by \texttt{../configure
--help}. \texttt{./configure -V} shows you the actual version of
your downloaded \whizard\ distribution. The possible environment
variables are:
\begin{verbatim}
CC C compiler command
CFLAGS C compiler flags
LDFLAGS linker flags, e.g. -L<lib dir> if you have libraries in a
nonstandard directory <lib dir>
LIBS libraries to pass to the linker, e.g. -l<library>
CPPFLAGS C/C++/Objective C preprocessor flags, e.g. -I<include dir> if
you have headers in a nonstandard directory <include dir>
CPP C preprocessor
FC Fortran compiler command
FCFLAGS Fortran compiler flags
CXX C++ compiler command
CXXFLAGS C++ compiler flags
CXXCPP C++ preprocessor
\end{verbatim}
For most of these there is no need to be set during installation.
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 \texttt{LHAPDF} and \texttt{HepMC}.
Finally, all the Makefiles are being built.
The compilation is done by invoking \texttt{make} and finally
\texttt{make install}. You could also do a \texttt{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.
It is possible to compile WHIZARD without the \ttt{O'Caml} parts of
\ttt{O'Mega}, namely by using the \ttt{--disable-omega} option of the
configure. This will result in a built of WHIZARD with the O'Mega
Fortran library, but without the binaries for the matrix element
generation. All selftests (cf. \ref{sec:selftests}) requiring O'Mega
matrix elements are thereby switched off. Note that you can install
such a built (e.g. on a batch system without O'Caml installation), but
the try to build a distribution (all \ttt{make distxxx} targets) will fail.
%%%%%
\subsection{WHIZARD self tests/checks}
\label{sec:selftests}
WHIZARD has a number of self-consistency checks and test 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
\texttt{make check} from the \texttt{build} directory. If \texttt{src}
and \texttt{build} directories are the same, all relevant files for
these self-tests reside in the \texttt{test} 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 \texttt{src}
and \texttt{build} directory are different as recommended, then the
input files will have been installed in
\url{prefix/share/whizard/test}, while the corresponding test shell
scripts remain in the \texttt{srcdir/test} directory. As the main shell
script \url{run_whizard_sh} has been built in the \texttt{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.
\texttt{make check} still correctly performs all WHIZARD
self-consistency tests.
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 setting the configure option
\url{--enable-extnum-checks}. On the other hand, the standard
self-consistency checks can be completely disabled with the option
\url{--disable-default-checks}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Setting up a user work space}
When \whizard\ is installed on a system it can be used by any user in
a multi-user environment.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage
\chapter{How to use WHIZARD}
\section{Getting Started}
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.
\subsection{Hello World}
The script is written in SINDARIN. This is a DSL -- a
domain-specific scripting language that is designed for the single
purpose of steering WHIZARD.
Previous versions of the program, similar to most high-energy physics
programs, 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 PERL or PYTHON (or even C++), 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.
Now since SINDARIN \emph{is} a programming language, we honor the old
tradition of starting with the famous Hello World program. In
SINDARIN this reads
\begin{quote}
\begin{verbatim}
echo ("Hello World!")
\end{verbatim}
\end{quote}
Open your favorite editor, type this text, and save it into a file
named \verb|hello.sin|.
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
\begin{verbatim}
> whizard -r hello.sin
\end{verbatim}
and if everything works well, you get the output
\begin{verbatim}
| Writing log to 'whizard.log'
|=============================================================================|
| WHIZARD 2.0.0_rc1
|=============================================================================|
| Initializing process library 'processes'
| Reading model file 'SM.mdl'
| Using model: SM
| Reading commands from file 'hello.sin'
Hello World!
| WHIZARD run finished.
|=============================================================================|
\end{verbatim}
\subsection{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 initializes a
\emph{process library}, and it reads a physics \emph{model}. 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:
\begin{quote}
\begin{verbatim}
process ee = e1, E1 -> e2, E2
compile
sqrts = 360 GeV
integrate (ee)
n_events = 10
?write_lhef = true
$file_lhef = "ee.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}
> whizard -r ee.sin
\end{verbatim}
(We will come to the meaning of the \verb|-r| option later.)
This produces a lot of output. We break it down into pieces.
The startup is as before:
\begin{verbatim}
| Writing log to 'whizard.log'
|=============================================================================|
| WHIZARD 2.0.0_rc1
|=============================================================================|
| Initializing process library 'processes'
| Reading model file 'SM.mdl'
| Using model: SM
| Reading commands from file 'ee.sin'
| Added process to library 'processes':
| [O] ee = e-, e+ -> mu-, mu+
\end{verbatim}
\begin{verbatim}
| Generating code for process library 'processes'
| Calling O'Mega for process 'ee'
| command: /home/kilian/whizard/build/nagfor/src/omega/bin/omega_SM.opt -o ee.f90 -target:whizard -target:parameter_module parameters_SM -target:module ee -target:md5sum 6ABA33BC2927925D0F073B1C1170780A -fusion:progress -scatter 'e- e+ -> mu- mu+'
[1/1] e- e+ -> mu- mu+ ... done. [time: 0.03 secs, total: 0.03 secs, remaining: 0.00 secs]
all processes done. [total time: 0.03 secs]
SUMMARY: 6 fusions, 2 propagators, 2 diagrams
| Writing interface code for process library 'processes'
| Compiling process library 'processes'
\end{verbatim}
\begin{verbatim}
| Loading process library 'processes'
| Process 'ee': updating previous configuration
sqrts = 3.6000000000000000E+02
| Integrating process 'ee'
| Generating phase space, writing file 'ee.phs' (this may take a while)
| Found 2 phase space channels.
Warning: No cuts have been defined.
\end{verbatim}
\begin{verbatim}
| Using partonic energy as event scale.
| iterations = 3:1000, 3:10000
| Creating grids
| 1000 calls, 2 channels, 2 dimensions, 20 bins, stratified = T
|=============================================================================|
| It Calls Integral[fb] Error[fb] Err[%] Acc Eff[%] Chi2 N[It] |
|=============================================================================|
1 1000 8.3366006E+02 1.47E+00 0.18 0.06* 40.12
2 1000 8.3357740E+02 8.16E-01 0.10 0.03* 40.11
3 1000 8.3214263E+02 1.01E+00 0.12 0.04 57.40
|-----------------------------------------------------------------------------|
3 3000 8.3311382E+02 5.83E-01 0.07 0.04 57.40 0.69 3
|-----------------------------------------------------------------------------|
4 10000 8.3325834E+02 1.10E-01 0.01 0.01* 57.02
5 10000 8.3333796E+02 1.11E-01 0.01 0.01 57.03
6 10000 8.3323772E+02 1.11E-01 0.01 0.01 57.03
|=============================================================================|
6 30000 8.3327798E+02 6.41E-02 0.01 0.01 57.03 0.23 3
|=============================================================================|
\end{verbatim}
\begin{verbatim}
n_events = 10
?write_lhef -> true
$file_lhef -> "ee.lhef"
| No analysis setup has been provided.
| Writing events in LHEF format to file 'ee.lhef'
| Generating 10 events ...
| Writing events in internal format to file 'whizard.evx'
| ... done
| There were no errors and 1 warning(s).
| WHIZARD run finished.
|=============================================================================|
\end{verbatim}
\section{SINDARIN -- The WHIZARD command language}
%% The event generator WHIZARD ships with its own command and interpreter
%% language, which can either be used in the input file(s) or in the
%% interactive mode (cf. Sec.\ref{sec:whish}), SINDARIN, Syntax for
%% INtegration, Data Analysis, Results display and external
%% INterfaces. Corresponding input files written in SINDARIN must have
%% the suffix \texttt{.sin}. Examples for SINDARIN input files can be
%% found in the \texttt{share/doc} subdirectory of the sources.
%% In the following, we discuss the details of the input files. The
%% advantage is that all steps of a physics analysis, i.e. the model
%% selection, the process specification, individual parameter settings,
%% the collider and beam set-up, the cuts, the integrations details, as
%% well as the full analysis set-up. Of course, if one likes one can
%% include separate files from the main input file and split information
%% into several files. In the sequel, the individual steps of the input
%% file are specified, but first we give a general introduction into the
%% characteristics and capabilities of SINDARIN. A first example for an
%% input file might help to recognize general features:
%% \begin{footnotesize}
%% \begin{center}
%% \begin{verbatim}
%% process nnh = e1, E1 -> n1, N1, H
%% compile
%% !---------------------------------------------
%% me = 0
%% mH = 115 GeV
%% sqrts = 500 GeV
%% beams = e1, E1
%% seed = 0
%% integrate (nnh) { iterations = 3:5000, 2:5000 }
%% show (results)
%% \end{verbatim}
%% \end{center}
%% \end{footnotesize}
%% This input file generates a SM vector boson fusion process for the ILC
%% with a specified electron and Higgs mass at a center-of-mass energy of
%% 500 GeV. The beam specification is even redundant in the file
%% above. The random-number seed is set to a specific value, then the
%% process is integrated with certain iteration values, and a result
%% summary is demanded. No event generation and no analysis are done.
%%%
\subsection{Syntactic details of SINDARIN}
In the SINDARIN language, there are certain pre-defined constructors or
commands that cannot be used in different context by the user, which
are -- in alphabetical order -- \ttt{\$action}, \ttt{alias}, \ttt{all},
\ttt{\$analysis\_filename}, \ttt{and}, \ttt{as},
\ttt{any}, \ttt{beams}, \ttt{cmplx},
\ttt{combine}, \ttt{compile}, \ttt{cuts},
\ttt{\$description},
\ttt{echo}, \ttt{else}, \ttt{exec}, \ttt{expect},
\ttt{false}, \ttt{?fatal\_beam\_decay},
\ttt{\$file\_debug}, \ttt{\$file\_default}, \ttt{file\_hepmc},
\ttt{\$file\_lhef}, \ttt{if}, \ttt{include},
\ttt{int}, \ttt{integrate}, \ttt{iterations}, \ttt{\$label}, \ttt{lhapdf},
\ttt{library}, \ttt{load}, \ttt{luminosity},
\ttt{model}, \ttt{n\_events}, \ttt{no}, \ttt{observable}, \ttt{or},
\ttt{\$physical\_unit},
\ttt{plot}, \ttt{process}, \ttt{read\_slha},
\ttt{real}, \ttt{?rebuild}, \ttt{?recompile}, \ttt{record},
\ttt{\$restrictions}, \ttt{results}, \ttt{scan}, \ttt{seed},
\ttt{show}, \ttt{simulate}, \ttt{sqrts},
\ttt{then}, \ttt{\$title}, \ttt{tolerance}, \ttt{true}, \ttt{unstable},
\ttt{write\_analysis}, \ttt{?write\_debug}, \ttt{?write\_default},
\ttt{\$write\_hepmc}, \ttt{?write\_lhef}, \ttt{write\_slha},
\ttt{\$xlabel}, and \ttt{\$ylabel}. Also units
are fixed, like \ttt{degree}, \ttt{eV}, \ttt{keV}, q
\ttt{MeV}, \ttt{GeV}, and \ttt{TeV}. Again, these tags are locked and
not user-redefinable. There functionality will be listed in detail
below. Furthermore, a variable with a preceding
question mark, ?, is a logical, while a preceding hash, \#, denotes a
character string variable. Also, a lot of unary and binary operators
exist, \ttt{+ - $\backslash$ , = : -> < > <= >= \^ \; () [] \{\} }
\url{~}\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 be marked by a hash,
\#, or an exclamation mark, !.
\begin{itemize}
\item
\ttt{\$action} \newline
{\color{red} I have no real clue yet. In the example input file it is
used to set an histogram manually by the individual record
entries. But why is it a logical variable??? WK?}
%%%%%
\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 <log\_expr> [<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{\$analysis\_filename} \newline
This character variable allows to create a \LaTeX file for the user
anaylsis, and to specify its name. If this variable is not set, the
analysis will be directed to the screen output. (cf. also
\ttt{write\_analysis})
%%%%
\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{or}).
%%%%%
\item
\ttt{as} \newline
cf. \ttt{compile}
%%%%%
\item
\ttt{any} \newline
\ttt{any} is a function that works on a logical expression and a list,
\ttt{any <log\_expr> [<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{beams} \newline
This specifies the contents and structure of the beams. 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{lhapdf},
\ttt{ISR}, \ttt{EPA} and so on are switched on as e.g. \ttt{beams = p,
p -> lhapdf}. (cf. also \ttt{circe}, \ttt{circe2}, \ttt{lhapdf}).
%%%%%
\item
\ttt{cmplx} \newline
{\color{red} Defines a complex variable. (to be finalized still}
%%%%%
\item
\ttt{combine} \newline
The \ttt{combine [<list1>, <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 defined, of course).
%%%%%
\item
\ttt{compile} \newline
The \ttt{compile} command is mandatory, 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{processes.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}, \ttt{load})
%%%%
\item
\ttt{cuts} \newline
This command defines the cuts to be applied to certain processes. The
syntax is: \ttt{cuts = <log\_class> <log\_expr> [<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, e.g. PDG == 15 would select a tau lepton. 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{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).
\item
\ttt{\$description} \newline
String variable that allows to specify a description text for the
analysis, \ttt{\$description = "analysis description text"}.
This line appears below the title of a corresponding analysis, on top
of the respective plot. (cf. \ttt{analysis}, \ttt{\$title})
\item
\ttt{echo} \newline
Allows to put verbose information on the screen during execution, e.g.
\ttt{echo ("Hello, world!")}.
(cf. also \ttt{show})
%%%%%
\item
\ttt{else} \newline
cf. \ttt{if}
%%%%%
\item
\ttt{eV} \newline
Physical unit, stating that the corresponding number is in electron volt.
%%%%%
\item
\ttt{exec} \newline
Constructor \ttt{exec ("<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{expect} \newline
The binary function \ttt{expect} compares two numerical expressions
whether they are 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 (<num1> <log\_comp> <num2>)},
where \ttt{num1} and \ttt{num2} are two numerical values (or
corresponding variables) and \ttt{log\_comp} is one of the following
logical comparators: \url{<}, \url{>}, \url{<=}, \url{>=}, \url{==},
\url{/=}, \url{~~}, \url{~}.
(cf. also \url{<}, \url{>}, \url{<=}, \url{>=}, \url{==}, \url{/=},
\url{~~}, \url{~}, \ttt{tolerance}).
%%%%%
\item
\ttt{false} \newline
Constructor stating that a logical expression or variable is false,
e.g. \ttt{?<log\_var> = false}. (cf. also \ttt{true}).
%%%%%
\item
\ttt{?fatal\_beam\_decay} \newline
Logical variable that let the user decide whether the possibility of a
beam decay is treated as a fatal error or only as a warning. An
example is a process $b t \to X$, where the bottom quark as an inital
state particle appears as a possible decay product of the second
incoming particle, the top quark. This might trigger inconsistencies
or instabilities in the phase space set-up.
%%%%%
\item
\ttt{\$file\_debug} \newline
String variable that allows via \ttt{\$file\_debug = "file\_name"} to
specify the name for the file \ttt{file\_name} to which events in a
a long verbose format with debugging information are written. If not
set, the default file name is \ttt{whizard.debug}. (cf. also
\ttt{?write\_debug})
%%%%%
\item
\ttt{\$file\_default} \newline
String variable that allows via \ttt{\$file\_default = "file\_name"} to
specify the name for the file \ttt{file\_name} to which events in a
human-readable format are written. If not set, the default file name
is \ttt{whizard.default}. (cf. also \ttt{?write\_default})
%%%%%
\item
\ttt{\$file\_hepmc} \newline
String variable that allows via \ttt{\$file\_hepmc = "file\_name"} to
specify the name for the file \ttt{file\_name} to which events in
the HepMC format are written. If not set, the default file name
is \ttt{whizard.hepmc}. (cf. also \ttt{?write\_hepmc})
%%%%%
\item
\ttt{\$file\_lhef} \newline
String variable that allows via \ttt{\$file\_lhef = "file\_name"} to
specify the name for the file \ttt{file\_name} to which events in
the (new) Les Houches event (LHE) format (including XML headers) are
written. If not set, the default file name is
\ttt{whizard.lhef}. (cf. also \ttt{?write\_lhef})
%%%%%
\item
\ttt{GeV} \newline
Physical unit, energies in $10^9$ electron volt. This is the default
energy unit of WHIZARD.
%%%%%
\item
\ttt{if} \newline
Conditional clause with the construction \ttt{if <log\_expr> then
<expr> else <expr>}. Note that there is no specific \ttt{end if}
statement. For more complicated expressions it is better to use
expressions in parentheses: \ttt{if (<log\_expr>) then
\{<expr>\} else \{<expr>\}}. 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\}}. The \ttt{then} constructor is not mandatory and can be
omitted.
%%%%%
\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{int} \newline
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 <int\_var> = <int\_val>}. (cf. also \ttt{real} and \ttt{cmplx})
%%%%%
\item
\ttt{integrate} \newline
The \ttt{integrate (<proc\_name>) \{ <integrate\_options> \}} command
invokes the integration (phase-space grid generation and Monte-Carlo
sampling of the process \ttt{proc\_name} (which can also be a list of
processes) with the integration options
\ttt{<integrate\_options}. Right now the only option is to specify the
number of iterations and calls per integration during the Monte-Carlo
phase-space integration via \ttt{iterations =
<n\_iterations>:<n\_calls>}. Note that this can be list, separated
by colons, which breaks up the integration process into units of the
specified number of integrations and calls each.
%%%%%
\item
\ttt{iterations} \newline
Option to set the number of iterations and calls per iteration during
the Monte-Carlo phase-space integration process, cf. \ttt{integrate}.
%%%%%
\item
\ttt{keV} \newline
Physical unit, energies in $10^3$ electron volt.
%%%%%
\item
\ttt{\$label} \newline
This is a string variable, \ttt{\$label = "label\_name"} that allows
to specify a label \ttt{label\_name} for analysis plots on the $x$
axis. It is only taken into account if the variable \ttt{\$xlabel} has
not been set, in which case it is overwritten by the string value of
that variable. (cf. also \ttt{xlabel}, \ttt{ylabel}).
{\color{red} WK: Do I see this correctly?}
%%%%%
\item
\ttt{lhapdf} \newline
{\color{red} NOT YET PROPERLY WORKING!!!!}
(cf. \ttt{beams})
%%%%%
\item
\ttt{library} \newline
The command \ttt{library = "<lib\_name>"} allows to specify a separate
shared object library archive \ttt{lib\_name.so}, not using the
standard library \ttt{processes.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{load})
%%%%%
\item
\ttt{load} \newline
The \ttt{load} command allows to load again a library if some details
have been changed (processes added, redefined or maybe changed.
{\color{red} Guess, here is some explanation missing}
(cf. also \ttt{compile}, \ttt{library})
%%%%%
\item
\ttt{luminosity}
This specifier \ttt{luminosity = <num>} sets the integrated luminosity
for the event generation of the processes in the SINDARIN input
files. Note that WHIZARD itself chooses the number from the
\ttt{luminosity} or from the \ttt{n\_events} specifier, whichever
would give the larger number of events. As this depends on the cross
section under consideration, it might be different for different
processes in the process list.
{\color{red} WK: Is this correct? Do we really want this? What about
different units?}
Furthermore, the \ttt{luminosity} or \ttt{n\_events} command has to be
invoked {\em after} the corresponding logical variable which tells
WHIZARD to write an event file in a specific format.
(cf. \ttt{n\_events}, \ttt{?write\_debug}, \ttt{?write\_default},
\ttt{\$write\_hepmc}, \ttt{?write\_lhef})
%%%%%
\item
\ttt{MeV} \newline
Physical unit, energies in $10^6$ electron volt.
%%%%%
\item
\ttt{model} \newline
With this specifier, \ttt{model = <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.
%%%%%
\item
\ttt{no} \newline
\ttt{no} is a function that works on a logical expression and a list,
\ttt{no <log\_expr> [<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{n\_events} \newline
This specifier \ttt{n\_events = <num>} sets the number of events
for the event generation of the processes in the SINDARIN input
files. Note that WHIZARD itself chooses the number from the
\ttt{n\_events} or from the \ttt{luminosity} specifier, whichever
would give the larger number of events. As this depends on the cross
section under consideration, it might be different for different
processes in the process list.
{\color{red} WK: Is this correct? Do we really want this?}
Furthermore, the \ttt{n\_events} or \ttt{luminosity} command has to be
invoked {\em after} the corresponding logical variable which tells
WHIZARD to write an event file in a specific format.
(cf. \ttt{luminosity}, \ttt{?write\_debug}, \ttt{?write\_default},
\ttt{\$write\_hepmc}, \ttt{?write\_lhef})
%%%%%
\item
\ttt{observable} \newline
With this, \ttt{observable = <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{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}).
%%%%%
\item
\ttt{\$physical\_unit} \newline
This is a string variable, \ttt{\$physical\_unit = "<unit\_name>''},
that allows to set a \LaTeX name \ttt{unit\_name} for the physical
unit of a label of an analysis plot. This unit is then also used for
calculations within the analysis set-up.
%%%%%
\item
\ttt{plot} \newline
(cf. \ttt{record})
%%%%%
\item
\ttt{process} \newline
Allows to set a hard interaction process, either for a decay process
\ttt{decay\_proc} as \ttt{process <decay\_proc> = <mother>
-> <daughter1>, <daughter2>, ...}, or for a scattering process
\ttt{scat\_proc} as \ttt{<incoming1>, <incoming2>
-> <outgoing1>, <outgoing2>, ...}. Note that there can be
arbitrarily many processes to be defined in a
SINDARIN input file.
(cf. also \ttt{restrictions})
%%%%%
\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})
%%%%%
\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 integer variable \ttt{real\_var}:
\ttt{real <real\_var> = <real\_val>}. (cf. also \ttt{int} and
\ttt{cmplx})
%%%%%
\item
\ttt{?rebuild} \newline
The logical variable \ttt{?rebuild = true/false} specifies whether
the matrix element code for processes is re-generated by the matrix
element generator O'Mega (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}).
%%%%%
\item
\ttt{?recompile} \newline
The logical variable \ttt{?recompile = true/false} specifies whether
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})
%%%%%
\item
\ttt{record} \newline
The \ttt{record} constructor provides an internal data structure in
SINDARIN input files. Its syntax is in general \ttt{record
<record\_name> (<cmd\_expr>)}. The \ttt{<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}.
(cf. also \ttt{eval})
%%%%%
\item
\ttt{\$restrictions} \newline
This is an optional argument for process definitions. It defines a
string variable, \ttt{process <process\_name> = <particle1>,
<particle2> -> <particle3>, <particle4>, ... \{ \$restrictions =
"<restriction\_def>" \}}. The string argument \ttt{restriction\_def}
is directly transferred during the code generation to the matrix
element generator O'Mega. It has to be of the form \ttt{n1 + n2 + ...
\url{~} <particle (list)>}, where \ttt{n1} and so on are the numbers of the
particles above in the process definition. The tilde specifies a
certain intermediate state to be equal to the particle(s) in
\ttt{particle (list)}. An example is \ttt{process eemm\_z = e1,
E1 -> e2, E2 \{ \$restrictions = "1+2 \url{~} Z" \} } restricts the code
to be generated for the process $e^- e^+ \to \mu^- \mu^+$ to the
$s$-channel $Z$-boson exchange. (cf. also \ttt{process})
%%%%%
\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{scan} \newline
Constructor to perform loops over variables or scan over processes in
the integration procedure. The syntax is \ttt{scan <var> <var\_name>
(<value list> or <value\_init> -> <value\_fin> /<incrementor>
<increment>) \{ <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.
%%%%%
\item
\ttt{seed} \newline
Integer variable \ttt{seed = <num>} that allows to set a specific
random seed \ttt{num}. If not set, WHIZARD takes the time from the
system clock to determine the random seed.
%%%%%
\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(<parameter\_name>)}
to issue a specific parameter from a model or a constant defined in a
SINDARIN input file, \ttt{show(integral(<proc\_name>))},
\ttt{show(library)}, \ttt{show(results)}, or show(<var>) for any
arbitrary variable.
(cf. also \ttt{echo}, \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 (<proc>)}.
(cf. also \ttt{integrate}, \ttt{luminosity}, \ttt{n\_events})
%%%%%
\item
\ttt{sqrts} \newline
Real variable in order to set the center-of-mass energy for the
collisions (collider energy $\sqrt{s}$, not hard interaction energy
$sqrt{\hat{s}}$): \ttt{sqrts = <num> <phys\_unit>}. The physical unit
can be one of the following \ttt{eV}, \ttt{keV}, \ttt{MeV}, \ttt{GeV},
and \ttt{TeV}. If absent, WHIZARD takes \ttt{GeV} as its standard
unit.
%%%%%
\item
\ttt{TeV} \newline
Physical unit, for energies in $10^{12}$ electron volt.
%%%%
\item
\ttt{then} \newline
Alternative option inside a conditional clause, not mandatory, hence
maybe be omitted, cf. \ttt{if}.
%%%%%
\item
\ttt{\$title} \newline
This string variable sets the title of a plot in a WHIZARD analysis
setup, e.g. a histogram or an observable. The syntax is \ttt{\$title =
"<your title>"}. This title appears as a section header in the
analysis file, but not in the screen output of the analysis.
(cf. also \ttt{\$description}, \ttt{\$label}, \ttt{\$xlabel},
\ttt{\$ylabel}).
%%%%%
\item
\ttt{tolerance} \newline
Real variable that defines the tolerance with which the (logical)
function \ttt{expect} accepts equality or inequality:
\ttt{tolerance = <num>}. This can e.g. be used for cross-section tests
and backwards compatibility checks.
(cf. also \ttt{expect})
%%%%%
\item
\ttt{true} \newline
Constructor stating that a logical expression or variable is true,
e.g. \ttt{?<log\_var> = true}. (cf. also \ttt{false}).
%%%%%
\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}
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 <mother> (<decay1>, <decay2>, ....)},
where \ttt{mother} is the mother particle, and the argument is a list
of decay channels. Note that these 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.
%%%%%
\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{\$analysis\_filename} is provided, the
analysis (including the histograms) are printed out on the screen,
otherwise they are written to a file defined by that specific string
variable.
(cf. also \ttt{\$analysis\_filename})
%%%%%
\item
\ttt{?write\_debug} \newline
Logical variable that, if set true, demands WHIZARD to write out an
event file in a long, verbose format for debugging purposes. Note that
\ttt{simulate} has to be invoked for this in order to work as well as
either a non-zero number of events, \ttt{n\_events}, or a
non-vanishing luminosity, \ttt{luminosity}. The \ttt{?write\_debug}
flag has to be set before the event or luminosity numbers!
The standard name of the event file will be \ttt{whizard.debug}, but
can be redefined by the \ttt{\$file\_debug} variable.
(cf. \ttt{\$file\_debug}, \ttt{luminosity}, \ttt{n\_events}, \ttt{simulate})
%%%%%
\item
\ttt{?write\_default} \newline
Logical variable that, if set true, demands WHIZARD to write out an
event file in a standard ASCII format. Note that
\ttt{simulate} has to be invoked for this in order to work as well as
either a non-zero number of events, \ttt{n\_events}, or a
non-vanishing luminosity, \ttt{luminosity}. The \ttt{?write\_default}
flag has to be set before the event or luminosity numbers!
The standard name of the event file will be \ttt{whizard.default}, but
can be redefined by the \ttt{\$file\_default} variable.
(cf. \ttt{\$file\_default}, \ttt{luminosity}, \ttt{n\_events}, \ttt{simulate})
\item
\ttt{\$write\_hepmc} \newline
Logical variable that, if set true, demands WHIZARD to write out an
event file in the HepMC format (if externally linked). Note that
\ttt{simulate} has to be invoked for this in order to work as well as
either a non-zero number of events, \ttt{n\_events}, or a
non-vanishing luminosity, \ttt{luminosity}. The \ttt{?write\_hepmc}
flag has to be set before the event or luminosity numbers!
The standard name of the event file will be \ttt{whizard.hepmc}, but
can be redefined by the \ttt{\$file\_hepmc} variable.
(cf. \ttt{\$file\_hepmc}, \ttt{luminosity}, \ttt{n\_events}, \ttt{simulate})
%%%%%
\item
\ttt{?write\_lhef} \newline
Logical variable that, if set true, demands WHIZARD to write out an
event file (new) Les Houches event format (LHEF, with XML
headers). Note that \ttt{simulate} has to be invoked for this in
order to work as well as either a non-zero number of events,
\ttt{n\_events}, or a non-vanishing luminosity, \ttt{luminosity}. The
\ttt{?write\_lhef} flag has to be set before the event or luminosity
numbers! The standard name of the event file will be
\ttt{whizard.lhef}, but can be redefined by the \ttt{\$file\_lhef}
variable. (cf. \ttt{\$file\_lhef}, \ttt{luminosity}, \ttt{n\_events},
\ttt{simulate})
%%%%%
\item
\ttt{write\_slha} \newline
Demands WHIZARD to write out a file in the SUSY Les Houches accord
(SLHA).
{\color{red} How this file gets its info is still completely unknown
to me! Hard-coded right now? Docu is missing!!!}
(cf. also \ttt{read\_slha})
%%%%%
\item
\ttt{\$xlabel} \newline
String variable, \ttt{\$xlabel = "<LaTeX code>"}, that sets the $x$
axis label in a plot or histogram in a WHIZARD analysis.
(cf. also \ttt{label} and \ttt{\$ylabel})
%%%%%
\item
\ttt{\$ylabel} \newline
String variable, \ttt{\$ylabel = "<LaTeX code>"}, that sets the $y$
axis label in a plot or histogram in a WHIZARD analysis.
(cf. also \ttt{label} and \ttt{\$xlabel})
\end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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{verbatim}
/home/user$ whizard --interactive
\end{verbatim}
or
\begin{verbatim}
/home/user$ whizard -i
\end{verbatim}
The WHISH can be closed by the \texttt{quit} command:
\begin{verbatim}
whish? quit
\end{verbatim}
%%%%%
\section{Using processes from several different models}
When using two different models which need an SLHA input file,
these {\em have} to be provided for both models. Otherwise WHIZARD
will not be performing the phase-space setup for the second process.
Note that when using more than one models, the setting of parameters
{\em after} the last model and process declarations only affects the
active -- i.e. the last -- model. If one wants to set a parameter for
all models in the input file, one has to repeat the model setting for
every defined model. Aöthough 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.
\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Examples}
\newpage
\chapter{Implemented physics}
\section{The Monte-Carlo integration routine: \ttt{VAMP}}
%%%%%
\section{The Phase-Space Setup}
%%%%%
\section{The hard interaction models}
\subsection{The Standard Model and friends}
%%%%
\subsection{Beyond the Standard Model}
\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 anomalous top couplings & \tt{---} &
\tt{SM\_top} \\
SM with K matrix & \tt{---} &
\tt{SM\_KM} \\\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
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
SM with graviton & \tt{---} & \tt{Xdim} \\
\hline
UED & \tt{---} & \tt{UED} \\
\hline
SM with $Z'$ & \tt{---} & \tt{Zprime} \\
\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}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Technical details -- Advanced Spells}
\subsection{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.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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, \texttt{hep-ph/9908288}.
\bibitem{madgraph}
T.~Stelzer and W.F.~Long,
Comput.\ Phys.\ Commun.\ \textbf{81} (1994) 357.
\bibitem{omega}
T.~Ohl,
% to appear in:
\emph{Proceedings of the Seventh International Workshop on
Advanced Computing and Analysis Technics in Physics Research},
ACAT 2000, Fermilab, October 2000,
IKDA-2000-30, \texttt{hep-ph/0011243};
M.~Moretti, Th.~Ohl, and J.~Reuter,
LC-TOOL-2001-040
\bibitem{VAMP}
T.~Ohl,
Comput.\ Phys.\ Commun.\ \textbf{120} (1999) 13.
\bibitem{CIRCE}
T.~Ohl,
Comput.\ Phys.\ Commun.\ \textbf{101} (1997) 269.
\bibitem{ISR}
M.~Skrzypek and S.~Jadach,
Z.\ Phys.\ \textbf{C49} (1991) 577.
\bibitem{HDECAY}
A.~Djouadi, J.~Kalinowski, M.~Spira,
Comput.\ Phys.\ Commun.\ \textbf{108} (1998) 56-74.
\bibitem{LesHouches}
E.~Boos \emph{et al.},
in: Proc.\ Les Houches 2001,
\texttt{hep-ph/0109068}
\bibitem{SLHA}
P.~Skands \emph{et al.},
arXiv:hep-ph/0311123.
\bibitem{Hagiwara:2005wg}
K.~Hagiwara {\it et al.},
%``Supersymmetry simulations with off-shell effects for LHC and ILC,''
arXiv:hep-ph/0512260.
%%CITATION = HEP-PH 0512260;%%
\bibitem{Allanach:2002nj}
B.~C.~Allanach {\it et al.},
%``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{Aguilar-Saavedra:2005pw}
J.~A.~Aguilar-Saavedra {\it et al.},
%``Supersymmetry parameter analysis: SPA convention and project,''
arXiv:hep-ph/0511344.
%%CITATION = HEP-PH 0511344;%%
\end{thebibliography}
\end{document}

File Metadata

Mime Type
text/x-tex
Expires
Sat, Dec 21, 3:46 PM (1 d, 6 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
4023335
Default Alt Text
manual.tex (62 KB)

Event Timeline