\boldmath The MC@NLO 2.0 Event Generator% \footnote{Work supported in part by the UK Particle Physics and Astronomy Research Council and by the EU Fourth Framework Programme `Training and Mobility of Researchers', Network `Quantum Chromodynamics and the Deep Structure of Elementary Particles', contract FMRX-CT98-0194 (DG 12 - MIHT).}
Stefano Frixione
INFN
Sezione di Genova
Via Dodecaneso 33
16146 Genova
Italy
This is the user's manual of {$\MCatNLO$} 2.0. This package is a practical implementation, based upon the HERWIG event generator, of the $\MCatNLO$ formalism, which allows one to incorporate NLO QCD matrix elements consistently into a parton shower framework. This document is self-contained, but we emphasise the main differences with respect to version 1.0.
hep-ph0307146.tex
\documentclass[paper]{JHEP}
\usepackage{epsfig}
\usepackage{amssymb}
%
\def\beq{\begin{equation}}
\def\eeq{\end{equation}}
\def\eq{\beq\eeq}
\def\beqn{\begin{eqnarray}}
\def\eeqn{\end{eqnarray}}
%
\def \ep{\epsilon}
\def \as{\alpha_{\rm s}}
\def\VEV#1{\left\langle #1\right\rangle}
\def\abs#1{\left|#1\right|}
\def\HW{{\small HERWIG}}
\def\NLO{{\small NLO}}
\def\MC{{\small MC}}
\def\ltap{\stackrel{<}{\sim}}
%
\newcommand\sss{\scriptscriptstyle\rm}
\newcommand\bSigma{\overline{\Sigma}}
\newcommand\xMC{|_{\sss {\rm MC}}}
\newcommand\MCatNLO{{\rm MC}@{\rm NLO}}
\newcommand\code{\tt}
\newcommand\variable{\tt}
%
\preprint{
 Cavendish--HEP--03/09\hfill\\
 CERN--TH/2003--159\hfill\\
 GEF--TH--7/2003}
\title{\boldmath The MC@NLO 2.0 Event Generator%
\footnote{Work supported in part by the UK Particle Physics and
Astronomy Research Council and by the EU Fourth Framework Programme
`Training and Mobility of Researchers', Network `Quantum Chromodynamics
and the Deep Structure of Elementary Particles',
contract FMRX-CT98-0194 (DG 12 - MIHT).}}
\author{Stefano Frixione\\
  INFN, Sezione di Genova,
  Via Dodecaneso 33, 16146 Genova, Italy\\
  E-mail: \email{Stefano.Frixione@cern.ch}}
\author{Bryan R.\ Webber\\
  Theory Division, CERN, 1211 Geneva 23, Switzerland and\\
  Cavendish Laboratory, %University of Cambridge\\
  Madingley Road, Cambridge CB3 0HE, U.K.\\
  E-mail: \email{webber@hep.phy.cam.ac.uk}}
\abstract{
This is the user's manual of {$\MCatNLO$} 2.0. This package is a 
practical implementation, based upon the HERWIG event generator,
of the $\MCatNLO$ formalism, which allows one to incorporate NLO QCD 
matrix elements consistently into a parton shower framework. This document
is self-contained, but we emphasise the main differences with respect
to version 1.0.
}
\keywords{QCD, Monte Carlo, NLO Computations, Resummation, Hadronic Colliders}
\begin{document}

\section{Generalities}
In this documentation file, we briefly describe how to run the 
$\MCatNLO$, implemented according to the formalism introduced in 
ref.~\cite{Frixione:2002ik}. The production processes now available are 
listed in table~\ref{tab:proc}. The process codes {\variable IPROC} will be
explained below.  $H_{1,2}$ represent hadrons (in practice, $p$ or $\bar p$).
The treatment of vector boson pair production within $\MCatNLO$ has been 
described in ref.~\cite{Frixione:2002ik}, that of heavy quark pair 
production in ref.~\cite{Frixione:2003ei}. The NLO matrix elements have 
been taken from 
refs.~\cite{Mele:1990bq,Frixione:1992pj,Frixione:1993yp,Mangano:jk}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{table}[htb]
\begin{center}
\begin{tabular}{|c|l|}\hline
{\variable IPROC} & Process \\\hline
 --1705 & $H_1 H_2\to b\bar{b}+X$\\\hline
 --1706 & $H_1 H_2\to t\bar{t}+X$\\\hline
 --2850 & $H_1 H_2\to W^+W^-+X$\\\hline
 --2860 & $H_1 H_2\to Z^0Z^0+X$\\\hline
 --2870 & $H_1 H_2\to W^+Z^0+X$\\\hline
 --2880 & $H_1 H_2\to W^-Z^0+X$\\\hline
\end{tabular}
\end{center}
\caption{\label{tab:proc}
Processes implemented in $\MCatNLO 2.0$.
}
\end{table}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

This documentation
refers to $\MCatNLO$ version 2.0, which supersedes version 1.0
described in ref.~\cite{Frixione:2002bd}.

\subsection{Mode of operation}
In the case of standard MC, a hard kinematic configuration is
generated on a event-by-event basis, and it is subsequently showered 
and hadronized. In the case of $\MCatNLO$, all of the hard kinematic
configurations are generated in advance, and stored in a file 
(which we call {\em event file} -- see sect.~\ref{sec:evfile}); 
the event file is then read by \HW, which showers and hadronizes each 
hard configuration. In the current version 2.0, the events are 
handled by the ``Les Houches'' generic user process 
interface~\cite{Boos:2001cv} (see ref.~\cite{Frixione:2003ei} for 
more details). Therefore, in the $\MCatNLO$ the reading of a 
hard configuration from the event file is equivalent to the generation 
of such a configuration in the standard MC.

The signal to \HW\ that configurations should be read from an event file using
the Les Houches interface is a negative value of the process code {\variable
IPROC}; this accounts for the negative values in table~\ref{tab:proc}. In the
case of heavy quark production, the codes are simply the negative of those for
the corresponding standard \HW\ MC processes.  Where possible, this convention
will be adopted for additional $\MCatNLO$ processes. In the case of gauge
boson production, the codes are the negative of those adopted in $\MCatNLO$
1.0 (for which the Les Houches interface was not yet available), rather than
those of standard \HW. Consistently with what happens in standard \HW, by
subtracting 10000 from {\variable IPROC} one generates the same processes as
in table~\ref{tab:proc}, but eliminates the underlying event.

Apart from these differences, $\MCatNLO$ and \HW\ {\em behave in exactly the
same way}. Thus, the available user's analysis routines can be used without
any modification in the case of $\MCatNLO$. One should recall, however, that
$\MCatNLO$ always generates some events with negative weights (see
refs.~\cite{Frixione:2002ik,Frixione:2003ei}); therefore, the correct
distributions are obtained by summing weights with their signs (i.e., the
absolute values of the weights must {\em NOT} be used when filling the
histograms).

With such a structure, it is natural to create two separate executables,
which we improperly denote as \NLO\ and \MC. The former has the sole scope
of creating the event file; the latter is just \HW, augmented by
the capability of reading the event file.

\subsection{Package files}
The package consists of the following files:

\begin{itemize}
\item {\bf Shell utilities}\\
    {\code MCatNLO.Script}\\
    {\code MCatNLO.inputs}\\
    {\code Makefile}

\item {\bf Utility codes}\\
    {\code alpha.f}\\ 
    {\code dummies.f}\\ 
    {\code linux.f}\\ 
    {\code mcatnlo\_date.f}\\  
    {\code mcatnlo\_hbook.f}\\  
    {\code mcatnlo\_int.f}\\
    {\code mcatnlo\_libofpdf.f}\\ 
    {\code mcatnlo\_mlmtopdf.f}\\ 
    {\code mcatnlo\_pdftomlm.f}\\ 
    {\code mcatnlo\_str.f}\\ 
    {\code mcatnlo\_uti.f}\\ 
    {\code mcatnlo\_uxdate.c}\\
    {\code sun.f}\\ 
    {\code trapfpe.c}

\item {\bf General \HW\ routines}\\
    {\code mcatnlo\_hwdriver.f}\\ 
    {\code mcatnlo\_hwlhin.f}

\item {\bf Process-specific codes}\\
    {\code mcatnlo\_hwanbtm.f}\\
    {\code mcatnlo\_hwantop.f}\\
    {\code mcatnlo\_hwanvbp.f}\\
    {\code mcatnlo\_qqmain.f}\\
    {\code mcatnlo\_qqxsec.f}\\
    {\code mcatnlo\_vbmain.f}\\
    {\code mcatnlo\_vbxsec.f}\\
    {\code hvqcblks.h}
\end{itemize}
These files can be downloaded from the Web page:\\
$\phantom{aaaaaaaa}$%
{\code http://www.hep.phy.cam.ac.uk/theory/webber/MCatNLO}\\
The files {\code mcatnlo\_hwan{\em xxx}.f}, which appear in the
list of the process-specific codes, are sample \HW\ analysis
routines. They are provided here to give the user a ready-to-run
package, but they should be replaced with appropriate codes according 
to the user's needs.

In addition to the files listed above, the user will need a
version of the \HW\ code
\cite{Marchesini:1992ch,Corcella:2001bw,Corcella:2002jc}.
As stressed in 
ref.~\cite{Frixione:2002ik}, for the $\MCatNLO$ we do not
modify the existing (LL) shower algorithm. However,
since $\MCatNLO$ 2.0 makes use of the Les Houches interface,
first implemented in \HW\ 6.5, the version must be 6.500 or higher.
On most systems, users will need to delete the dummy  subroutines 
{\small UPEVNT}, {\small UPINIT}, {\small PDFSET} and {\small STRUCTM}
from the standard  \HW\ package, to permit linkage of the corresponding
routines from the $\MCatNLO$ package. 

\subsection{Working environment}
We have written a number of shell scripts and a {\code Makefile} (all
listed under {\bf Shell utilities} above) which will simplify the use of
the package considerably. In order to use them, the computing system
must support {\code bash} shell, and {\code gmake}. 
Should they be unavailable on the user's computing system, the compilation and
running of our $\MCatNLO$ requires more detailed instructions; in this case,
we refer the reader to app.~\ref{app:instr}. This appendix will serve also as
a reference for a more advanced use of the package.

\subsection{Source and running directories}
We assume that all the files of the package sit in the same directory,
which we call the {\em source directory}. When creating the executable, 
our shell scripts determine the type of operating system, and create a
subdirectory of the source directory, which we call the {\em running 
directory}, whose name is {\variable Alpha}, {\variable Sun}, or {\variable
Linux}, depending on the operating system.  If the operating system is
not known by our scripts, the name of the working directory is
{\variable Run}. The running directory contains all the object files
and executable files, and in general all the files produced by the
$\MCatNLO$ while running.  It must also contain the relevant grid
files (see sect.~\ref{sec:pdfs}), or links to them, if the library of
parton densities provided with the $\MCatNLO$ package is used. 

\section{Prior to running\label{sec:priors}}
Before running the code, the user needs to edit the following files:\\
$\phantom{aaa}${\code mcatnlo\_hwan{\em xxx}.f}\\
$\phantom{aaa}${\code mcatnlo\_hwdriver.f}\\ 
$\phantom{aaa}${\code mcatnlo\_hwlhin.f}\\
We do not assume that the user will adopt the latest release of \HW\ 
(although, as explained above, it must be version 6.500 or higher). For this 
reason, the files {\code mcatnlo\_hwdriver.f} and {\code mcatnlo\_hwlhin.f} 
must be edited, in order to modify the {\code INCLUDE HERWIGXX.INC} command
to correspond to the version of \HW\ the user is going to adopt.
{\code mcatnlo\_hwdriver.f} contains a set of read statements,
which are necessary for the \MC\ to get the input parameters (see
sect.~\ref{sec:running} for the input procedure); these read
statements must not be modified or eliminated. Also, {\code
mcatnlo\_hwdriver.f} calls the \HW\ routines which
perform showering, hadronization, decays (see sect.~\ref{sec:decay} 
for more details on this issue), and so forth; the user can
freely modify this part, as customary in \MC\ runs. Finally, the sample
codes {\code mcatnlo\_hwan{\em xxx}.f} contain analysis-related routines:
these files must be replaced by files which contain the user's analysis 
routines. We point out that, in version 2.0, the {\code Makefile} need not
be edited any longer, since the corresponding operations are now 
performed by setting script variables (see sect.~\ref{sec:scrvar}).

\subsection{Parton densities\label{sec:pdfs}}
Since the knowledge of the parton densities (PDF) is necessary in
order to get the physical cross section, a PDF library must be
linked. The possibility exists to link the CERNLIB PDF library
(PDFLIB); however, we also provide a self-contained PDF library with
this package, which is faster than PDFLIB. The user may link either
PDF library; all that is necessary is to set the variable {\variable
PDFLIBRARY} (in the file {\code MCatNLO.inputs}) equal to {\variable
THISLIB} if one wants to link to our PDF library, and equal to
{\variable PDFLIB} if one wants to link to PDFLIB.  Our PDF library
collects the original codes, written by the authors of the PDF fits;
as such, for most of the densities it needs to read the files which
contain the grids that initialize the PDFs. These files, which can
be also downloaded from the $\MCatNLO$ web page, must either be copied 
into the running directory, or defined in the running directory as logical
links to the physical files (by using {\code ln -sn}).

As stressed before, consistent inputs must be given to the \NLO\ and
\MC\ codes. However, in ref.~\cite{Frixione:2002ik} we found that the
dependence upon the PDFs used by the MC is rather weak. So one may
want to run the \NLO\ and \MC\ adopting a regular NLL-evolved set in the
former case, and the default \HW\ set in the latter (the advantage is
that this option reduces the amount of running time of the \MC). In
order to do so, the user must set the variable {\variable HERPDF}
equal to {\variable DEFAULT} in the file {\code MCatNLO.inputs};
setting {\variable HERPDF=EXTPDF} will force the \MC\ to use the same
PDF set as the \NLO\ code.

Regardless of the PDFs used in the \MC\ run, users must delete the dummy 
PDFLIB routines {\small PDFSET} and {\small STRUCTM} from \HW, as
explained earlier.

In MC@NLO 2.0, the PDF library LHAPDF is not supported.

\section{Running\label{sec:running}}
It is straightforward to run the $\MCatNLO$. First, edit\\
$\phantom{aaa}${\code MCatNLO.inputs}\\
and write there all the input parameters (for the complete list 
of the input parameters, see sect.~\ref{sec:scrvar}). As the last
line of the file {\code MCatNLO.inputs}, write\\
$\phantom{aaa}${\code runMCatNLO}\\
Finally, execute {\code MCatNLO.inputs} from the (bash) shell.
This procedure will create the \NLO\ and \MC\ executables, and run them
using the inputs given in {\code MCatNLO.inputs}, which guarantees
that the parameters used in the \NLO\ and \MC\ runs are identical.
Should the user only need to create the executables without running
them, or to run the \NLO\ or the \MC\ only, he/she should replace the
call to {\code runMCatNLO} in the last line of {\code MCatNLO.inputs}
by calls to\\
$\phantom{aaa}${\code compileNLO}\\
$\phantom{aaa}${\code compileMC}\\
$\phantom{aaa}${\code runNLO}\\
$\phantom{aaa}${\code runMC}\\
which have obvious meanings. We point out that the command {\code runMC}
may be used with {\variable IPROC}=1705 or 1706 to generate $b\bar{b}$
or $t\bar{t}$ events with standard \HW.

We stress that the input parameters are not solely related to
physics (masses, CM energy, and so on); there are a few of them
which control other things, such as the number of events generated.
These must also be set by the user, according to his/her needs:
see sect.~\ref{sec:scrvar}.

Two such variables are {\variable HERWIGVER} and {\variable HWUTI},
which have been moved in version 2.0 from the {\code Makefile} to
{\code MCatNLO.inputs}. The former variable must be set equal 
to the object file name of the version of \HW\ currently adopted 
(matching the one whose common blocks are included in the files
mentioned in sect.~\ref{sec:priors}). The variable {\variable HWUTI} 
must be set equal to the list of object files that the user needs in 
the analysis routines.

If the shell scripts are not used to run the codes, the inputs are
given to the \NLO\ or \MC\ codes during an interactive talk-to phase;
the complete sets of inputs for our codes are reported in 
app.~\ref{app:input}.

\subsection{Event file\label{sec:evfile}}
The \NLO\ code creates the event file. In order to do so, it goes through
two steps; first it integrates the cross sections (integration step),
and then, using the information gathered in the integration step, 
produces a set of events (event generation step).

The event generation step necessarily follows the integration step;
however, for each integration step one can have an arbitrary number of
event generation steps, i.e., an arbitrary number of event files.
This is useful in the case in which the statistics accumulated 
with a given event file is not sufficient.

Suppose the user wants to create an event file; editing {\code
MCatNLO.inputs}, the user sets {\variable BASES=ON}, to enable the
integration step, sets the parameter {\variable NEVENTS} equal to
the number of events wanted on tape, and runs the code; the
information on the integration step (unreadable to the user, but
needed by the code in the event generation step) is written on files
whose name begin with {\variable FPREFIX}, a string the user sets
in {\code MCatNLO.inputs}; these files (which we denotes as {\em data
files}) have extensions {\code .data}. The name of the event file is 
{\variable EVPREFIX.events}, where {\variable EVPREFIX} is again a 
string set by the user.

Now suppose the user wants to create another event file, to increase
the statistics. The user simply sets {\variable BASES=OFF}, since 
the integration step is not necessary any longer (however, the data
files must not be removed: the information
stored there is still used by the \NLO\ code); changes the string
{\variable EVPREFIX} (failure to do so overwrites the existing event
file), while keeping {\variable FPREFIX} at the same value as before;
and changes the value of {\variable RNDEVSEED} (the random number
seed used in the event generation step; failure to do so results in
an event file identical to the previous one); the number {\variable
NEVENTS} generated may or may not be equal to the one chosen in
generating the former event file(s).

We point out that data and event files may be very large. If the user
wants to store them in a scratch area, this can be done by setting the
script variable {\variable SCRTCH} equal to the physical address
of the scratch area (see sect.~\ref{sec:res}).

\subsection{Decays}\label{sec:decay}
$\MCatNLO$ is intended primarily for the study of NLO corrections
to production cross sections and distributions.  NLO corrections to
the decays of produced particles are not included.  In the current
version, spin correlations in decays are also neglected, although
these will be included in future versions where possible. This means
that at present quantities sensitive to the polarisation of produced
particles are not given correctly even to leading order.
For such quantities, it may be preferable to use the standard
\HW\ MC, which does include spin correlations.

Particular decay modes of gauge bosons may be forced in $\MCatNLO$
in the same way as in standard \HW, using the {\variable MODBOS}
variables -- see sect.~3.4 of ref.~\cite{Corcella:2001bw}. However,
top decays cannot be forced in this way because the decay is
treated as a three-body process: the $W^\pm$ boson entry in
{\code HEPEVT} is for information only.  Instead, the top
branching ratios can be altered using the {\variable HWMODK}
subroutine -- see sect.~7 of ref.~\cite{Corcella:2001bw}.
This is done separately for the $t$ and $\bar t$. For example,
{\code CALL HWMODK(6,1.D0,100,12,-11,5,0,0)} forces
the decay $t\to \nu_e e^+ b$, while leaving $\bar t$ decays
unaffected.  Note that the order of the decay products is
important for the decay matrix element
({\variable NME} = 100) to be applied correctly.
The relevant statements should be inserted in the \HW\ main program
(corresponding to {\code mcatnlo\_hwdriver.f} in this package)
after the statement {\code CALL HWUINC} and before
the loop over events.  A separate run with
{\code CALL HWMODK(-6,1.D0,100,-12,11,-5,0,0)} should
be performed if one wishes to symmetrize the forcing of
$t$ and $\bar t$ decays, since calls to {\variable HWMODK} from
within the event loop do not produce the desired result.

\subsection{Results\label{sec:res}}
As in the case of standard \HW\, the form of the results will be
determined by the user's analysis routines. However, in addition
to any files written by the user's analysis routines, the
$\MCatNLO$ writes the following files:\\
$\blacklozenge$ 
{\variable FPREFIXNLOinput}: the input file for the \NLO\ executable, 
created according to the set of input parameters defined in 
{\code MCatNLO.inputs} (where the user also sets the string
{\variable FPREFIX}). See table~\ref{tab:NLOi}.\\
$\blacklozenge$ 
{\variable FPREFIXNLO.log}: the log file relevant to the \NLO\ run.\\
$\blacklozenge$ 
{\variable FPREFIXxxx.data}: {\variable xxx} can assume several different 
values. These are the data files created by the \NLO\ code. They can be 
removed only if no further event generation step is foreseen with the
current choice of parameters.\\
$\blacklozenge$ 
{\variable FPREFIXMCinput}: analogous to {\variable FPREFIXNLOinput}, 
but for the \MC\ executable. See table~\ref{tab:MCi}.\\
$\blacklozenge$ 
{\variable FPREFIXMC.log}: analogous to {\variable FPREFIXNLO.log}, but 
for the \MC\ run.\\
$\blacklozenge$ 
{\variable EVPREFIX.events}: the event file, where {\variable EVPREFIX} 
is the string set by the user in {\code MCatNLO.inputs}.\\
$\blacklozenge$ 
{\variable EVPREFIXxxx.events}: {\variable xxx} can assume several different 
values. These files are temporary event files, which are used by the
\NLO\ code, and eventually removed by the shell scripts. They MUST NOT be
removed by the user during the run (the program will crash or give
meaningless results).

By default, all the files produced by the $\MCatNLO$ are written in the
running directory.  However, if the variable {\variable SCRTCH} (to be set in
{\code MCatNLO.inputs}) is {\em not} blank, the data and event files will be
written in the directory whose address is stored in {\variable SCRTCH}
(such a directory is not created by the scripts, and must already exist
at runtime).

\section{Script variables\label{sec:scrvar}}
In the following, we list all the variables appearing in 
{\code MCatNLO.inputs}; these can be changed by the user to suit 
his/her needs. This must be done by editing {\code MCatNLO.inputs}.
\begin{itemize}
\item[{\variable ECM}] 
 The CM energy of the colliding particles.
\item[{\variable FREN}] 
 The ratio between the renormalization scale, and a reference mass scale.
\item[{\variable FFACT}] 
 As {\variable FREN}, for the factorization scale.
\item[{\variable FRENMC}] 
 As {\variable FREN}; enters the MC-subtraction terms $\bSigma\xMC$
 (see ref~\cite{Frixione:2002ik}).
\item[{\variable FFACTMC}] 
 As {\variable FFACT}; enters the MC-subtraction terms $\bSigma\xMC$
 (see ref~\cite{Frixione:2002ik}).
\item[{\variable xMASS}] 
 The mass (in GeV) of the particle {\variable x}, with 
 {\variable x=W,Z,U,D,S,C,B,G}.
\item[{\variable HVQMASS}] 
 The mass (in GeV) of the bottom or top quark, when {\variable IPROC}=--1705
 or --1706 respectively. In the former case, {\variable HVQMASS} must coincide 
 with {\variable BMASS}.
\item[{\variable IPROC}]
 Process number that identifies heavy particles in the final 
 states: see table~\ref{tab:proc} for valid entries.
\item[{\variable PARTn}]
 The type of the incoming particle \#{\variable n}, with {\variable n}=1,2. 
 \HW\ naming conventions are used ({\variable P, PBAR, N, NBAR}).
\item[{\variable PDFGROUP}]
 The name of the group fitting the parton densities used;
 the labeling conventions of PDFLIB are adopted.
\item[{\variable PDFSET}] 
 The number of the parton density set; according to PFDLIB,
 the pair ({\variable PDFGROUP}, {\variable PDFSET}) identifies the densities.
\item[{\variable LAMBDAFIVE}]
 The value of $\Lambda_{\sss QCD}$, for five flavours and in the 
 ${\overline {\rm MS}}$ scheme.
\item[{\variable SCHEMEOFPDF}] 
 The subtraction scheme in which the parton densities are defined.
\item[{\variable FPREFIX}] Our integration routine creates files with
 name beginning by the string {\variable FPREFIX}. These files are not 
 directly accessed by the user; for more details, see sect.~\ref{sec:evfile}.
\item[{\variable EVPREFIX}] 
 The name of the event file begins with this string; for 
 more details, see sect.~\ref{sec:evfile}.
\item[{\variable EXEPREFIX}] 
 The name of the \NLO\ and \MC\ executables begin with this string; this is
 useful in the case of simultaneous runs.
\item[{\variable NEVENTS}] 
 The number of events stored in the event file, eventually
 processed by \mbox{\HW\ .}
\item[{\variable WGTTYPE}]
 Valid entries are 0 and 1. When set to 0, the weights are $\pm 1$. When
 set to 1, the weights are $\pm w$, with $w$ a constant such that the sum 
 of the weights gives the total NLO rate.
\item[{\variable RNDEVSEED}] 
 This is the seed for the random number generation is the
 event generation step; must be changed in order to obtain
 statistically-equivalent but different event files.
\item[{\variable BASES}] 
 Controls the integration step; valid entries are {\variable ON} and 
 {\variable OFF}. At least one run with {\variable BASES=ON} must be 
 performed.
\item[{\variable PDFLIBRARY}] 
 Valid entries are {\variable PDFLIB} and {\variable THISLIB}. 
 In the former case,
 the local version of PDFLIB is used to compute the parton
 densities, whereas in the latter case the densities are
 obtained from our self-contained faster package.
\item[{\variable HERPDF}] 
 If set to {\variable DEFAULT}, \HW\ uses its internal PDF set 
 (controlled by {\variable NSTRU}), regardless of the densities
 adopted at the NLO level. If set to {\variable EXTPDF}, \HW\ uses
 the same PDFs as the \NLO\ code.
\item[{\variable HWPATH}] 
 The physical address of the directory where the user's
 preferred version of \HW\ is stored.
\item[{\variable SCRTCH}]
 The physical address of the directory where the user wants to store the
 data and event files. If left blank, these files are stored in the 
 running directory.
\item[{\variable HWUTI}]
This variables must be set equal to a list of object files,
needed by the analysis routines of the user (for example,
{\variable HWUTI=obj1.o obj2.o obj3.o} is a valid assignment).
\item[{\variable HERWIGVER}]
This variable must to be set equal to the name of the
object file corresponding to the version of \HW\ linked
to the package (for example, {\variable HERWIGVER=herwig65.o} is a
valid assignment).
\end{itemize}

\section*{Acknowledgement}
Many thanks to Paolo Nason for contributions to the heavy quark code
and valuable discussions on all aspects of the $\MCatNLO$ project.

\section*{Appendices}
\appendix

\section{From MC@NLO version 1.0 to version 2.0\label{app:newver}}
In this appendix we list the changes that occurred in the package, which
motivate the upgrade in version number.

$\bullet$~The Les Houches generic user process interface has been adopted.

$\bullet$~As a result, the convention for process codes has been changed:
MC@NLO process codes {\variable IPROC} are negative.

$\bullet$~The code {\code mcatnlo\_hwhvvj.f}, which was specific to
vector boson pair production in version 1.0, has been replaced by
{\code mcatnlo\_hwlhin.f}, which reads the event file according
to the Les Houches prescription, and works for all the production 
processes implemented.

$\bullet$~The {\code Makefile} need not be edited, since the variables
{\variable HERWIGVER} and {\variable HWUTI} have been moved to
{\code MCatNLO.inputs} (where they must be set by the user).

$\bullet$~A code {\code mcatnlo\_hbook.f} has been added to the list of
utility codes. It contains a simplified version (written by M.~Mangano)
of {\small HBOOK}, and it is only used by the sample analysis routines
{\code mcatnlo\_hwan{\em xxx}.f}. As such, the user will not need it
when linking to a self-contained analysis code.

We also remind the reader that the \HW\ version must be 
6.5 or higher since the  Les Houches interface is used.

\section{Running the package without the shell scripts\label{app:instr}}
In this appendix, we describe the actions that the user needs to 
take in order to run the package without using the shell scripts,
and the {\variable Makefile}. Examples are given for vector boson
pair production, but only trivial modifications are necessary in
order to treat heavy quark pair production; they are listed below.

\subsection{Creating the executables\label{app:exe}}
An $\MCatNLO$ run requires the creation of two executables, for the \NLO\
and \MC\ codes respectively. The files to link depend on whether one
uses PDFLIB, or the PDF library provided with this package; we list
them below:
\begin{itemize}
\item {\bf NLO without PDFLIB:}
{\code mcatnlo\_vbmain.o mcatnlo\_vbxsec.o mcatnlo\_date.o mcatnlo\_int.o 
mcatnlo\_uxdate.o mcatnlo\_uti.o mcatnlo\_str.o\\
mcatnlo\_pdftomlm.o mcatnlo\_libofpdf.o dummies.o SYSFILE}
\item {\bf NLO with PDFLIB:}
{\code mcatnlo\_vbmain.o mcatnlo\_vbxsec.o mcatnlo\_date.o mcatnlo\_int.o 
mcatnlo\_uxdate.o mcatnlo\_uti.o mcatnlo\_str.o\\
mcatnlo\_mlmtopdf.o dummies.o}
{\variable SYSFILE CERNLIB}
\item {\bf MC without PDFLIB:}
{\code mcatnlo\_hwdriver.o mcatnlo\_hwlhin.o\\ mcatnlo\_hwanvbp.o 
mcatnlo\_hbook.o mcatnlo\_str.o mcatnlo\_pdftomlm.o\\ mcatnlo\_libofpdf.o 
dummies.o} {\variable HWUTI HERWIGVER}
\item {\bf MC with PDFLIB:}
{\code mcatnlo\_hwdriver.o mcatnlo\_hwlhin.o\\ mcatnlo\_hwanvbp.o 
mcatnlo\_hbook.o mcatnlo\_str.o mcatnlo\_mlmtopdf.o\\ dummies.o}
{\variable HWUTI HERWIGVER CERNLIB}
\end{itemize}
In the case of heavy quark pair production, the files 
{\code mcatnlo\_vbmain.o} and\\ {\code mcatnlo\_vbxsec.o} are replaced by
{\code mcatnlo\_qqmain.o} and {\code mcatnlo\_qqxsec.o} respectively in the 
\NLO\ executable, and the \HW\ analysis routines {\code mcatnlo\_hwanvbp.o} 
by either {\code mcatnlo\_hwanbtm.o} or {\code mcatnlo\_hwantop.o} in
the \MC\ executable. The variable {\variable SYSFILE} must be set 
either equal to {\code alpha.o},
or to {\code linux.o}, or to {\code sun.o}, according to the architecture 
of the machine on which the run is performed. For any other architecture,
the user should provide a file corresponding to {\code alpha.f} etc.,
which he/she will easily obtain by modifying {\code alpha.f}. The 
variables {\variable HWUTI} and {\variable HERWIGVER} have been described
in sect.~\ref{sec:scrvar}. Finally, {\variable CERNLIB} must be set
in order to link the local version of CERN PDFLIB. In order to create
the object files eventually linked, static compilation is always
recommended (for example, {\code g77 -Wall -fno-automatic} on Linux).

\subsection{The input files\label{app:input}}
In this appendix, we describe the inputs to be given to the \NLO\ and 
\MC\ executables in the case of vector boson pair production. The case
of heavy quark pair production is completely analogous.
When the shell scripts are used to run the $\MCatNLO$,
two files are created, {\variable FPREFIXNLOinput} and 
{\variable FPREFIXMCinput}, which are read by the \NLO\ and \MC\ executable
respectively. We start by considering the inputs for the \NLO\
executable, presented in table~\ref{tab:NLOi}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{table}[htb]
\begin{center}
\begin{tabular}{ll}
\hline
 '{\variable FPREFIX}'                       & ! prefix for BASES files\\
 '{\variable EVPREFIX}'                      & ! prefix for event files\\
  {\variable ECM FFACT FREN FFACTMC FRENMC}  & ! energy, scalefactors\\
  {\variable IPROC}                        & ! -2850/60/70/80=WW/ZZ/ZW+/ZW-\\
  {\variable WMASS ZMASS}                    & ! M\_W, M\_Z\\
  {\variable UMASS DMASS SMASS CMASS BMASS GMASS} & ! quark and gluon masses\\
 '{\variable PART1}'  '{\variable PART2}'    & ! hadron types\\
 '{\variable PDFGROUP}'   {\variable PDFSET} & ! PDF group and id number\\
  {\variable LAMBDAFIVE}                     & ! Lambda\_5, $<$0 for default\\
 '{\variable SCHEMEOFPDF}'                   & ! scheme\\
  {\variable NEVENTS}                        & ! number of events\\
  {\variable WGTTYPE}                 & ! 0 =$>$ wgt=+1/-1, 1 =$>$ wgt=+w/-w\\
  {\variable RNDEVSEED}                      & ! seed for rnd numbers\\
  {\variable zi}                             & ! zi\\
  {\variable nitn$_1$ nitn$_2$}              & ! itmx1,itmx2\\
\hline\\
\end{tabular}
\end{center}
\caption{\label{tab:NLOi}
Sample input file for the \NLO\ code (for vector boson pair production). 
{\variable FPREFIX} and {\variable EVPREFIX} must be understood with 
{\variable SCRTCH} in front (see sect.~\ref{sec:scrvar}).
}
\end{table}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The variables whose name is in uppercase characters have been described 
in sect.~\ref{sec:scrvar}. The other variables are assigned by the shell
script. Their default values are given in table~\ref{tab:defNLO}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{table}[htb]
\begin{center}
\begin{tabular}{ll}
\hline
Variable & Default value\\
\hline
{\variable zi}          & 0.1\\
{\variable nitn$_i$}    & 10/0 ({\variable BASES=ON/OFF})\\
\hline\\
\end{tabular}
\end{center}
\caption{\label{tab:defNLO}
Default values for script-generated variables in {\code FPREFIXNLOinput}.
In the case of heavy quark pair production, the default is 
{\variable zi}$=0.3$.
}
\end{table}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Users who run the package without the script should use the values
given in table~\ref{tab:defNLO}. The variable {\variable zi} controls,
to a certain extent, the number of negative-weight events generated 
by the $\MCatNLO$ (see ref.~\cite{Frixione:2002ik}). Therefore, the user
may want to tune this parameter in order to reduce as much as possible
the number of negative-weight events. We stress that the \MC\ code will
not change this number; thus, the tuning can (and must) be done only 
by running the \NLO\ code. The variables {\variable nitn$_i$} control
the integration step (see sect.~\ref{sec:evfile}), which can be
skipped by setting {\variable nitn$_i=0$}. If one needs to perform the
integration step, we suggest setting these variables as indicated in
table~\ref{tab:defNLO}. 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{table}[htb]
\begin{center}
\begin{tabular}{ll}
\hline
 '{\variable EVPREFIX.events}'               & ! event file\\
  {\variable NEVENTS}                        & ! number of events\\
%%  {\variable esctype}    & ! 0-$>$EMSCA=sqrt(s)-2*pT, 1-$>$EMSCA=sqrt(s)\\
  {\variable pdftype}                      & ! 0-$>$Herwig PDFs, 1 otherwise\\
 '{\variable PART1}'  '{\variable PART2}'    & ! hadron types\\
  {\variable beammom beammom}                & ! beam momenta\\
  {\variable IPROC}                         & ! --2850/60/70/80=WW/ZZ/ZW+/ZW-\\
 '{\variable PDFGROUP}'                      & ! PDF group (1)\\
  {\variable PDFSET}                         & ! PDF id number (1)\\
 '{\variable PDFGROUP}'                      & ! PDF group (2)\\
  {\variable PDFSET}                         & ! PDF id number (2)\\
  {\variable LAMBDAFIVE}                     & ! Lambda\_5, $<$0 for default\\
  {\variable WMASS WMASS ZMASS}              & ! M\_W+, M\_W-, M\_Z\\
  {\variable UMASS DMASS SMASS CMASS BMASS GMASS} & ! quark and gluon masses\\
\hline\\
\end{tabular}
\end{center}
\caption{\label{tab:MCi}
Sample input file for the \MC\ code (for vector boson pair production), 
resulting from setting {\variable HERPDF=EXTPDF}, which implies 
{\variable pdftype=1}. 
Setting {\variable HERPDF=DEFAULT} results in an analogous file, with
{\variable pdftype=0}, and without the lines concerning
{\variable PDFGROUP} and {\variable PDFSET}. {\variable EVPREFIX} 
must be understood with {\variable SCRTCH} in front 
(see sect.~\ref{sec:scrvar}). The negative sign of {\variable IPROC}
tells \HW\ to use Les Houches interface routines.
}
\end{table}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
We now turn to the inputs for the \MC\ executable, presented
in table~\ref{tab:MCi}. 
The variables whose names are in uppercase characters have been described 
in sect.~\ref{sec:scrvar}. The other variables are assigned by the shell
script. Their default values are given in table~\ref{tab:defMC}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{table}[htb]
\begin{center}
\begin{tabular}{ll}
\hline
Variable & Default value\\
\hline
{\variable esctype}         & 0\\
{\variable pdftype}         & 0/1 ({\variable HERPDF=DEFAULT/EXTPDF})\\
{\variable beammom}         & {\variable EMC}/2\\
\hline\\
\end{tabular}
\end{center}
\caption{\label{tab:defMC}
Default values for script-generated variables in {\code MCinput}.
}
\end{table}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The user can freely change the values of {\variable esctype} and
{\variable pdftype}; on the other hand, the value of {\variable beammom}
must always be equal to half of the hadronic CM energy.

In the case of heavy quark production, the \MC\ executable can be run with
the corresponding positive input process codes {\variable IPROC} = 1705
or 1706,
to generate a standard \HW\ run for comparison purposes. Then the input
event file will not be read: instead, parton configurations will be
generated by \HW\ according to the LO matrix elements.

%\newpage

\begin{thebibliography}{100}

%\cite{Frixione:2002ik}
\bibitem{Frixione:2002ik}
S.~Frixione and B.~R.~Webber,
``Matching NLO QCD computations and parton shower simulations,''
JHEP {\bf 0206} (2002) 029
[hep-ph/0204244].
%%CITATION = HEP-PH 0204244;%%

%\cite{Frixione:2003ei}
\bibitem{Frixione:2003ei}
S.~Frixione, P.~Nason and B.~R.~Webber,
``Matching NLO QCD and parton showers in heavy flavour production,''
arXiv:hep-ph/0305252.
%%CITATION = HEP-PH 0305252;%%

%\cite{Mele:1990bq}
\bibitem{Mele:1990bq}
B.~Mele, P.~Nason and G.~Ridolfi,
``QCD Radiative Corrections To Z Boson Pair Production In Hadronic Collisions,''
Nucl.\ Phys.\ B {\bf 357} (1991) 409.
%%CITATION = NUPHA,B357,409;%%

%\cite{Frixione:1992pj}
\bibitem{Frixione:1992pj}
S.~Frixione, P.~Nason and G.~Ridolfi,
``Strong corrections to W Z production at hadron colliders,''
Nucl.\ Phys.\ B {\bf 383} (1992) 3.
%%CITATION = NUPHA,B383,3;%%

%\cite{Frixione:1993yp}
\bibitem{Frixione:1993yp}
S.~Frixione,
``A Next-to-leading order calculation of the cross-section for the production of W+ W- pairs in hadronic collisions,''
Nucl.\ Phys.\ B {\bf 410} (1993) 280.
%%CITATION = NUPHA,B410,280;%%

%\cite{Mangano:jk}
\bibitem{Mangano:jk}
M.~L.~Mangano, P.~Nason and G.~Ridolfi,
``Heavy Quark Correlations In Hadron Collisions At Next-To-Leading Order,''
Nucl.\ Phys.\ B {\bf 373} (1992) 295.
%%CITATION = NUPHA,B373,295;%%

%\cite{Frixione:2002bd}
\bibitem{Frixione:2002bd}
S.~Frixione and B.~R.~Webber,
``The MC@NLO event generator,''
arXiv:hep-ph/0207182.
%%CITATION = HEP-PH 0207182;%%

%\cite{Boos:2001cv}
\bibitem{Boos:2001cv}
E.~Boos {\it et al.},
``Generic user process interface for event generators,''
arXiv:hep-ph/0109068.
%%CITATION = HEP-PH 0109068;%%

%\cite{Marchesini:1992ch}
\bibitem{Marchesini:1992ch}
G.~Marchesini, B.~R.~Webber, G.~Abbiendi, I.~G.~Knowles, M.~H.~Seymour and L.~Stanco,
``HERWIG: A Monte Carlo event generator for simulating hadron emission reactions with interfering gluons. Version 5.1 - April 1991,''
Comput.\ Phys.\ Commun.\  {\bf 67} (1992) 465.
%%CITATION = CPHCB,67,465;%%
%\href{\wwwspires?j=CPHCB%2c67%2c465}{SPIRES}

%\cite{Corcella:2001bw}
\bibitem{Corcella:2001bw}
G.~Corcella, I.G.~Knowles, G.~Marchesini, S.~Moretti, K.~Odagiri,
P.~Richardson, M.H.~Seymour and B.R.~Webber,
``HERWIG 6: An event generator for hadron emission reactions with  interfering gluons (including supersymmetric processes),''
JHEP {\bf 0101} (2001) 010
[hep-ph/0011363].
%%CITATION = HEP-PH 0011363;%%

%\cite{Corcella:2002jc}
\bibitem{Corcella:2002jc}
G.~Corcella {\it et al.},
``HERWIG 6.5 release note,''
arXiv:hep-ph/0210213.

\end{thebibliography}
\end{document}


hep-ph0307146.extracted_bib
\begin{thebibliography}{100}

%\cite{Frixione:2002ik}
\bibitem{Frixione:2002ik}
S.~Frixione and B.~R.~Webber,
``Matching NLO QCD computations and parton shower simulations,''
JHEP {\bf 0206} (2002) 029
[hep-ph/0204244].
%%CITATION = HEP-PH 0204244;%%

%\cite{Frixione:2003ei}
\bibitem{Frixione:2003ei}
S.~Frixione, P.~Nason and B.~R.~Webber,
``Matching NLO QCD and parton showers in heavy flavour production,''
arXiv:hep-ph/0305252.
%%CITATION = HEP-PH 0305252;%%

%\cite{Mele:1990bq}
\bibitem{Mele:1990bq}
B.~Mele, P.~Nason and G.~Ridolfi,
``QCD Radiative Corrections To Z Boson Pair Production In Hadronic Collisions,''
Nucl.\ Phys.\ B {\bf 357} (1991) 409.
%%CITATION = NUPHA,B357,409;%%

%\cite{Frixione:1992pj}
\bibitem{Frixione:1992pj}
S.~Frixione, P.~Nason and G.~Ridolfi,
``Strong corrections to W Z production at hadron colliders,''
Nucl.\ Phys.\ B {\bf 383} (1992) 3.
%%CITATION = NUPHA,B383,3;%%

%\cite{Frixione:1993yp}
\bibitem{Frixione:1993yp}
S.~Frixione,
``A Next-to-leading order calculation of the cross-section for the production of W+ W- pairs in hadronic collisions,''
Nucl.\ Phys.\ B {\bf 410} (1993) 280.
%%CITATION = NUPHA,B410,280;%%

%\cite{Mangano:jk}
\bibitem{Mangano:jk}
M.~L.~Mangano, P.~Nason and G.~Ridolfi,
``Heavy Quark Correlations In Hadron Collisions At Next-To-Leading Order,''
Nucl.\ Phys.\ B {\bf 373} (1992) 295.
%%CITATION = NUPHA,B373,295;%%

%\cite{Frixione:2002bd}
\bibitem{Frixione:2002bd}
S.~Frixione and B.~R.~Webber,
``The MC@NLO event generator,''
arXiv:hep-ph/0207182.
%%CITATION = HEP-PH 0207182;%%

%\cite{Boos:2001cv}
\bibitem{Boos:2001cv}
E.~Boos {\it et al.},
``Generic user process interface for event generators,''
arXiv:hep-ph/0109068.
%%CITATION = HEP-PH 0109068;%%

%\cite{Marchesini:1992ch}
\bibitem{Marchesini:1992ch}
G.~Marchesini, B.~R.~Webber, G.~Abbiendi, I.~G.~Knowles, M.~H.~Seymour and L.~Stanco,
``HERWIG: A Monte Carlo event generator for simulating hadron emission reactions with interfering gluons. Version 5.1 - April 1991,''
Comput.\ Phys.\ Commun.\  {\bf 67} (1992) 465.
%%CITATION = CPHCB,67,465;%%
%\href{\wwwspires?j=CPHCB%2c67%2c465}{SPIRES}

%\cite{Corcella:2001bw}
\bibitem{Corcella:2001bw}
G.~Corcella, I.G.~Knowles, G.~Marchesini, S.~Moretti, K.~Odagiri,
P.~Richardson, M.H.~Seymour and B.R.~Webber,
``HERWIG 6: An event generator for hadron emission reactions with  interfering gluons (including supersymmetric processes),''
JHEP {\bf 0101} (2001) 010
[hep-ph/0011363].
%%CITATION = HEP-PH 0011363;%%

%\cite{Corcella:2002jc}
\bibitem{Corcella:2002jc}
G.~Corcella {\it et al.},
``HERWIG 6.5 release note,''
arXiv:hep-ph/0210213.

\end{thebibliography}