\documentclass[11pt]{article}
\usepackage{geometry}                % See geometry.pdf to learn the layout options. There are lots.
\geometry{letterpaper}                   % ... or a4paper or a5paper or ... 
%\geometry{landscape}                % Activate for for rotated page geometry
%\usepackage[parfill]{parskip}    % Activate to begin paragraphs with an empty line rather than an indent
\usepackage{graphicx}
\usepackage{epstopdf}
\DeclareGraphicsRule{.tif}{png}{.png}{`convert #1 `dirname #1`/`basename #1 .tif`.png}

\setlength{\parindent}{0cm}

\usepackage{listings}
\usepackage{color}
\usepackage{textcomp}
\definecolor{listinggray}{gray}{0.9}
\definecolor{lbcolor}{rgb}{1,1,1}
\lstset{
	backgroundcolor=\color{lbcolor},
	tabsize=4,
	rulecolor=,
	language=matlab,
        basicstyle=\normalsize,
        upquote=true,
        aboveskip={1.5\baselineskip},
        columns=fixed,
        showstringspaces=false,
        extendedchars=true,
        breaklines=true,
        prebreak = \raisebox{0ex}[0ex][0ex]{\ensuremath{\hookleftarrow}},
        frame=single,
        showtabs=false,
        showspaces=false,
        showstringspaces=false,
        identifierstyle=\ttfamily,
        keywordstyle=\color[rgb]{0,0,1},
        commentstyle=\color[rgb]{0.133,0.545,0.133},
        stringstyle=\color[rgb]{0.627,0.126,0.941},
}

\newcommand{\mcgrid} {{\tt MCgrid }}
\newcommand{\rivet} {{\tt Rivet }}
\newcommand{\appl} {{\tt APPLgrid }}
\newcommand{\sherpa} {{\tt SHERPA }}

\title{\mcgrid Version 1.0.X User Guide}
\author{mcgrid@projects.hepforge.org}
\begin{document}
\date{}
\maketitle
\tableofcontents
\section{Introduction}
\mcgrid is a software package that provides access to the \appl interpolation tool for Monte Carlo event generator codes. This is done by providing additional tools to the \rivet analysis system for the construction of \mcgrid enhanced \rivet analyses. The interface is based around a one-to-one correspondence between a \rivet histogram class and a wrapper for an \appl interpolation grid. The \rivet system provides all of the analysis tools required to project a Monte Carlo weight upon an experimental data bin, and the \mcgrid package provides the correct conversion of the event weight to an \appl fill call, fully accounting for the statistical subtitles in the process and the correct treatment of Catani-Seymour counter terms in the event weights. \mcgrid has been tested and designed for use with the \sherpa event generator, however as with \rivet the package is suitable for use with any code which can produce events in the {\tt HepMC} event record format.
\clearpage

\section{Software setup}
\subsection{Installation and build dependancies}
The \mcgrid package is supplied as an external library which may be used when constructing \rivet analyses. It has a few basic dependancies, namely,
\begin{itemize}
\item \rivet version 2.0.0 or later.
\item \appl version 1.4.28 or later.
\item {\tt boost::Filesystem } version 3 or later.
\item Optionally {\tt pkg-config} for path management.
\end{itemize}
In order to install the test code supplied with \mcgrid you should additionally have the {\tt LHAPDF} package installed. 
\\\\
\mcgrid may be configured and installed in the conventional way with the autotools build system. In the mcgrid directory you should perform:
\begin{lstlisting}[language=bash]
	./configure --prefix=[installation-dir]
	make && make install
\end{lstlisting}
Additionally there are two important configuration options to be noted.
\begin{itemize}
\item \lstinline[language=bash]{--disable-sherpafill }
\end{itemize}
This option disables the default fill behaviour of \mcgrid which takes into account the PDF structure of event weights originating from the \sherpa\cite{Gleisberg:2008ta} event generator and enables the generic fill mode. You should enable this if you wish to use a different event generator with \mcgrid and the PDF dependance of the supplied weights is via a simple multiplicative factor as described in \cite{cpc}.
\begin{itemize}
\item \lstinline[language=bash]{--disable-namedweights }
\end{itemize}
This option disables the use of named weights in the {\tt HepMC}\cite{Dobbs:2001ck} interface. This option should only be used if you encounter difficulties in running \mcgrid with HepMC records generated by older versions of the standard.
\vskip5pt

\subsection{Linking with a \rivet analysis.}
To include \mcgrid functionality in your analysis, you should supply the usual \lstinline[language=bash]{rivet-buildplugin} script with additional flags providing the paths to the package. The installation procedure provides the system with a \lstinline[language=bash]{pkg-config .pc} file to provide path information. A typical command for building a \rivet plugin would therefore be:
\begin{lstlisting}[language=bash]
 rivet-buildplugin [RivetAnalysis.so] [RivetAnalsis.cc]  \     $(pkg-config mcgrid --cflags) $(pkg-config mcgrid --libs)
\end{lstlisting}
An set of example analyses and a typical Makefile are provided in the \lstinline[language=bash]{examples} directory of the \mcgrid package.

\section{Implementing \mcgrid tools in an analysis}
\subsection{Required modifications}
To use the \mcgrid tools, there are three modifications that must be made to your \rivet analyses to enable the package.
Firstly the \mcgrid headers should be included at the top of the analysis code:
\begin{lstlisting}[language=c++]
	#include "mcgrid/mcgrid.hh"
\end{lstlisting}
Secondly, in the analysis phase of the code, the \mcgrid event handler must be called for every event passed to \rivet. This is done by adding the following line to the start of the analysis phase:
\begin{lstlisting}[language=c++]
	MCgrid::PDFHandler::HandleEvent(event);
\end{lstlisting}
Finally in the finalise phase, the event handler must be cleared and exported by adding the following as the final line in the finalise phase:
\begin{lstlisting}[language=c++]
	MCgrid::PDFHandler::ClearHandler();
\end{lstlisting}
With these modifications you have a barebones \mcgrid enabled \rivet analysis. An example of this minimal modification, \lstinline[language=bash]{MCGRID_BASIC} is given in the \lstinline[language=bash]{examples} directory.
\subsection{Booking subprocess PDFs}
After the basic modifications, you need to specify a \appl subprocess PDF combination. This details which QCD subprocesses contribute to the full process in question, and how the individual parton-parton subchannels are categorised into said subprocesses. This information is provided by \appl \lstinline[language=c++]{lumi_pdf} config files. For the details of how these files may be obtained from \sherpa or constructed by hand, refer to Appendix \ref{sec:subproc}.\\\\
To initialise a subprocess config file in \mcgrid you should call the following in the rivet \lstinline[language=c++]{init()} phase for each process in the analysis:
\begin{lstlisting}[language=c++]
 MCgrid::bookPDF(configname, histoDir(), beam1Type, beam2Type);
\end{lstlisting}
Where \lstinline[language=c++]{configname} is a \lstinline[language=c++]{std::string} providing the filename of the subprocess config name. This file should be installed to the \appl share folder. \lstinline[language=c++]{histoDir()} is a standard \rivet function which provides the name of the analysis. \lstinline[language=c++]{beam1Type} and \lstinline[language=c++]{beam2Type} specify whether the beam types used in the config file, either for proton or anti-proton beams where the quark flavours should be switched when performing a fill. For an LHC analysis an example call would be:
\begin{lstlisting}[language=c++]
 const string PDFname("atlas_inclusivejets.config");
 MCgrid::bookPDF(PDFname, histoDir(),
                 MCgrid::BEAM_PROTON, MCgrid::BEAM_PROTON);
\end{lstlisting}
Or for a Tevatron analysis where the second beam is antiprotons in the event generation:
\begin{lstlisting}[language=c++]
 const string PDFname("cdf_zrapidity.config");
 MCgrid::bookPDF(PDFname, histoDir(),
                 MCgrid::BEAM_PROTON, MCgrid::BEAM_ANTIPROTON);
\end{lstlisting}
An important config file that is provided by default in \appl is the \lstinline[language=bash]{basic.config} file. In this subprocess config all 121 partonic channels are active. If you do not have a specific subprocess identification file for your analysis, it is always possible to use this subprocess PDF. However the resulting grid will be significantly larger than a typical grid produced with subprocess identification enabled. \\\\
A few examples of subprocess config files are provided in the \lstinline[language=bash]{examples/subproc} folder.

\subsection{Initialising {\tt APPLgrids} in your analysis}
With the subprocess PDFs initialised it is time to set up the interpolating grids themselves. Firstly the \rivet analysis should be implemented and checked as in a standard analysis using only the histogram classes. Once the user is satisfied with the analysis, they should add to the analysis class
their grid classes. \\\\
For every \rivet histogram for which the user wishes to construct a corresponding \appl, they should add an \lstinline[language=c++]{MCgrid::gridPtr} instance to the analysis class' private attributes. For example:
\clearpage
\begin{lstlisting}[language=c++]
 private:
    /// Rivet Histograms
    Histo1DPtr _h_distribution;
    Histo1DPtr _h_xsection;
    
    // APPLgrids
    MCgrid::gridPtr _a_distribution;
    MCgrid::gridPtr _a_xsection;
\end{lstlisting}
 The naming of the gridPtr objects is left to the user, however it's recommended that they explicitly reference the histogram they are to be based upon.\\\\
 Now, in the \lstinline[language=c++]{init()} phase where your histograms are initialised, the \lstinline[language=c++]{MCgrid::gridPtr} instances should also be initialised with the following function:
 
  \begin{lstlisting}[language=c++]
	MCgrid::gridPtr MCgrid::bookGrid( 
		// Corresponding Rivet histogram
		const Rivet::Histo1DPtr hist,      
		// Result of Rivet histoDir() call
		const std::string histoDir,        
		// APPLgrid subprocess PDF   
		const std::string pdfname,    
		// Leading order power of alpha_s for the process
		const int    LOpower,               
		// Minimum value of parton x in the event sample      
		const double xmin,                   
		// Maximum value of parton x in the event sample
		const double xmax,        
		// Minimum event scale^2           
		const double q2min,          
		// Maximum event scale^2       
		const double q2max,            
		// Grid architecture    
		const gridArch arch   
	);   
\end{lstlisting}

Where the struct \lstinline[language=c++]{gridArch} specified the architecture of the \appl interpolation. It can be initialised with the following constructor:
  \clearpage
  \begin{lstlisting}[language=c++]
	gridArch( 
		const int nX, 	// Number of points in x-grid
		const int nQ2,	// Number of points in Q^2 grid
		const int xOrd,	// Order of interpolation on x-grid
		const int Q2Ord // Order of interpolation on Q^2-grid
	):
 \end{lstlisting}

 As an example, consider the construction of a grid for a Drell-Yan $Z$-rapidity analysis where events are generated with a fixed scale of $M_z^2$:
   \begin{lstlisting}[language=c++]
    // Grid architecture
    MCgrid::gridArch arch(50,1,5,0);
   
    /// Book histograms and grids
    _h_xsection = bookHisto1D(1, 1, 1);
    _a_xsection = MCgrid::bookGrid(	_h_xsection,
    								histoDir(), PDFname,
     								0, 
									1E-5, 1,
									8315.18, 8315.18,
									arch);
\end{lstlisting}

\subsection{Filling and finalising the grids}
In the \lstinline[language=c++]{analyse} phase of your \rivet analysis, both the histograms and \appl classes must be populated after the experimental cuts and analysis tools are applied as usual.\\\\
Once you have performed your event selection and are ready to fill a histogram, you simply have to fill the corresponding \lstinline[language=c++]{gridPtr} also. 
   \begin{lstlisting}[language=c++]
	_h_distribution->fill(coord, weight);	// Histogram fill  
	_a_distribution->fill(coord, event);	// grid fill
\end{lstlisting}
Here \lstinline[language=c++]{coord} specifies the value of the histogrammed quantity for that event, \lstinline[language=c++]{weight} is the usual event weight and \lstinline[language=c++]{event} is the \lstinline[language=c++]{Rivet::Event} object passed to the \lstinline[language=c++]{analyse} method.
\\\\
Finally the normalisation of the grids should be set, and the \appl \lstinline[language=bash]{.root} files exported for use. This is accomplished in the \lstinline[language=c++]{finalise} phase of the analysis. For the normalisation the treatment of the grids is once again analogous to that of the histograms. For each histogram/grid pair to be normalised the following should be called:
   \begin{lstlisting}[language=c++]
	// Histogram normalisation
	scale(_h_distribution, normalisation);	
	// Grid normalisation
	_a_distribution->scale(normalisation);	
\end{lstlisting}

And finally the grids should be written to file.   
\begin{lstlisting}[language=c++]
	_a_distribution->exportgrid();	
\end{lstlisting}
The filename of the grid will be based automatically upon the id of the corresponding histogram.

\section{Executing your \mcgrid / \rivet analysis}
As is typical with the \appl package, to fill it's produced grids two runs of the analysis must be performed. The first, or phasespace fill run, determines the relative statistics of each partonic channel in the process such that their statistical samples may be combined correctly, and also establishes the boundaries of the $x$, $Q^2$ phase space for each of the interpolation grids as explained in \cite{Carli:2010rw}. The second run actually populates the grids with the Monte Carlo weights. It is therefore typically sufficient to perform a run with a smaller but representative event sample for the phase space run, and only run the full event sample for the full fill.
\\\\
The modified \rivet analysis produced with \mcgrid utilities can be uses as a completely conventional \rivet analysis, running over {\tt HepMC} event record files, or indeed streamed via a {\tt FIFO} pipe or straight from an event generator. \\\\
The first run of the analysis will produce an \mcgrid results directory in the current working directory, and export an event count file along with the optimised \appl phase space grid to \lstinline[language=bash]{mcgrid/<analysis name>/phasespace/}. The second, fill run, looks for these files and reads them in preparation for the fill. The final \appl files are exported into the directory \lstinline[language=bash]{mcgrid/<analysis name>/} at the end of the second run.

\subsection{Parallelisation and grid combination} 
In the case of very large statistics Monte Carlo runs, it may be advantageous to parallelise the calculation to provide a substantial speed boost in the generation of the \appl files. It should be noted however that the phase space information provided from the first run must be used by all subsequent parallel runs to ensure the correct combination of the final grids. Therefore the phase space run may not be parallelised. However, as mentioned previously, a representative sample rather than the full event record may be used to determine the phase space information. This data may then be provided to several parallel fill runs. Combination of the produced grids is done by the standard tool provided with the \appl package, \lstinline[language=c++]{applgrid-combine}.
\begin{thebibliography}{99}


%\cite{Gleisberg:2008ta}
\bibitem{Gleisberg:2008ta}
  T.~Gleisberg, S.~.Hoeche, F.~Krauss, M.~Schonherr, S.~Schumann, F.~Siegert and J.~Winter,
  %``Event generation with SHERPA 1.1,''
  JHEP {\bf 0902} (2009) 007
  [arXiv:0811.4622 [hep-ph]].
  %%CITATION = ARXIV:0811.4622;%%
  %652 citations counted in INSPIRE as of 27 Nov 2013

\bibitem{cpc}
  L.~Del.~Debbio, N.~P.~Hartland, S.~Schumann, [arXiv:1312.4460 [hep-ph]].
  
  %\cite{Dobbs:2001ck}
\bibitem{Dobbs:2001ck}
  M.~Dobbs and J.~B.~Hansen,
  %``The HepMC C++ Monte Carlo event record for High Energy Physics,''
  Comput.\ Phys.\ Commun.\  {\bf 134} (2001) 41.\\
  %%CITATION = CPHCB,134,41;%%
  %99 citations counted in INSPIRE as of 25 Nov 2013
  
  %\cite{Carli:2010rw}
\bibitem{Carli:2010rw}
  T.~Carli, D.~Clements, A.~Cooper-Sarkar, C.~Gwenlan, G.~P.~Salam, F.~Siegert, P.~Starovoitov and M.~Sutton,
  %``A posteriori inclusion of parton density functions in NLO QCD final-state calculations at hadron colliders: The APPLGRID Project,''
  Eur.\ Phys.\ J.\ C {\bf 66} (2010) 503
  [arXiv:0911.2985 [hep-ph]].
  %%CITATION = ARXIV:0911.2985;%%
  %43 citations counted in INSPIRE as of 31 Oct 2013
  


  
  %\cite{Gleisberg:2008fv}
\bibitem{Gleisberg:2008fv}
  T.~Gleisberg and S.~Hoeche,
  %``Comix, a new matrix element generator,''
  JHEP {\bf 0812} (2008) 039
  [arXiv:0808.3674 [hep-ph]].
  %%CITATION = ARXIV:0808.3674;%%
  %104 citations counted in INSPIRE as of 25 Nov 2013

   %\cite{Krauss:2001iv}
\bibitem{Krauss:2001iv}
  F.~Krauss, R.~Kuhn and G.~Soff,
  %``AMEGIC++ 1.0: A Matrix element generator in C++,''
  JHEP {\bf 0202} (2002) 044
  [hep-ph/0109036].
  %%CITATION = HEP-PH/0109036;%%
  %201 citations counted in INSPIRE as of 25 Nov 2013
  
\end{thebibliography}

\clearpage
\appendix
\section{Subprocess Identification Scripts}
The subprocess identification config files of \appl list the partonic components of each of the $N_{sub}$ distinct subprocesses present in the calculation. For each subprocess there are a set of $N_{pair}^{(isub)}$ parton-parton pairs that contribute to it. The configuration file denotes these as so:

\begin{lstlisting}[language=bash]
[Flag for removal of CKM matrix elements = 0 or 1]
0 [pair1] [pair2] .. [pairN_0]
1 [pair1] [pair2] .. [pairN_1]
..
[Nsub]  
\end{lstlisting}
Where the pairs are denoted by integer pairs in the $LHA$ basis, neglecting the top quark:\\
\begin{table}[h]
\centering
\begin{tabular}{c c c c c c c c c c c }
  $\bar{b}$ & $\bar{c}$ & $\bar{s}$ & $\bar{u}$ & $\bar{d}$ & $g$ & $d$ & $u$ & $s$ & $c$ & $b$ \\
  -5 & -4 & -3 & -2 & -1 & 0 & 1 & 2 & 3 & 4 & 5 \\
\end{tabular}
\end{table}

The \appl package searches for these configuration files in it's \lstinline[language=bash]{share} path which can be found by using:
\begin{lstlisting}[language=bash]
applgrid-config --share
\end{lstlisting}

In \mcgrid the first parameter in the configuration should always be set to zero, as the \appl functionality of CKM matrix element variations is not available in the package. However the loss of this feature will only impact calculations where the CKM elements enter only in the vertex connecting the two incoming partons.  \\\\
As an example configuration, consider a hypothetical process who's only partonic subprocesses consist of $U\bar{U}$ and $gD$ channels where $U$ denotes an up-type quark and $D$ a down-type. The configuration file for \appl would then be:
\begin{lstlisting}[language=bash]
0 
0 2 -2 4 -4 # UUBar
1 0 1 0 3 0 5 # gD
\end{lstlisting}
An important point is that these configuration files refer to the numbering scheme for \emph{proton} distributions. In the case where the user wishes to use a calculation with an initial state antiproton beam, the signs on the antiproton beam flavours should be flipped. For example, for a $p\bar{p}$ beam our previous configuration file would become:
\begin{lstlisting}[language=bash]
0
0 2 2 4 4 # UUBar (ppbar)
1 0 -1 0 -3 0 -5 # gD (ppbar)
\end{lstlisting}
Such that the correct PDF treatment of the antiproton beam is taken into account. Examples of subprocess configurations for both $pp$ and $p\bar{p}$ beams can be found in the \lstinline[language=bash]{examples} directory.\\\\
Provided in the \mcgrid package are a pair of simple python scripts for the automated generation of \appl \lstinline[language=c++]{lumi_pdf} configuration files from the output of either of the two matrix element generators present in \sherpa, {\tt COMIX}\cite{Gleisberg:2008fv} and {\tt AMEGIC++}\cite{Krauss:2001iv}. The user may choose to either construct the appropriate configuration file by hand or make use of these scripts.\\\\
The tools can be found in the directory \lstinline[language=bash]{mcgrid/scripts}. The two scripts are \\\lstinline[language=bash]{identifyAmegicSubprocs.py} and  \lstinline[language=bash]{identifyComixSubprocs.py}.
\\\\
The operation of the two scripts is identical. Taking the \sherpa run card which you will use for the full event generation run, you should run with only a handful of events, which is sufficient for the generation of the process information required to form the subprocess configurations. You should then run the appropriate script for your chosen matrix element generator in the produced \lstinline[language=bash]{Process} directory.

\begin{lstlisting}[language=bash]
identify[MEgen]Subprocs.py --beamtype=[pp/ppbar/pbarp]
\end{lstlisting}

Where the argument specifies the beam types used in the event generation. This ensures that the quark flavours are mapped correctly to the proton PDF basis. This script will then produce a \lstinline[language=bash]{subprocs.config} file to be used in your \mcgrid analysis and packaged with the produced \appl file for release.  
\label{sec:subproc}



\end{document}  