MCFM-10.4/Doc/sections/cppinterface.tex

\newpage

\hypertarget{c-interface}{%
\topheading{C++ matrix element interface}\label{c-interface}}

Since version 10.1, MCFM offers a dedicated C++ interface to access its
analytic one-loop amplitudes. Please cite ref.~\cite{Campbell:2021vlt} in
addition to the main MCFM references when using the C++ interface.

\hypertarget{available-processes}{%
\midheading{Processes with C++ interface}\label{available-processes}}

The following Standard-Model processes are available:

\begin{longtable}[]{@{}lll@{}}
\hline
Process & Order EW & Order QCD \\
\hline
\endhead
\(pp\to \ell^+\ell^-\) & 2 & 1 \\
\(pp\to \ell^+\ell^- j\) & 2 & 2 \\
\(pp\to \ell^+\ell^- j j\) & 2 & 3 \\
& & \\
\(pp\to \ell^\pm\nu_\ell\) & 2 & 1 \\
\(pp\to \ell^\pm\nu_\ell j\) & 2 & 2 \\
\(pp\to \ell^\pm\nu_\ell j j\) & 2 & 3 \\
& & \\
\(pp\to h\) & 1 & 2 \\
\(pp\to h j\) & 1 & 3 \\
\(pp\to h j j\) & 1 & 4 \\
& & \\
\(pp\to h h\) & 2 & 2 \\
& & \\
\(pp\to \ell^+\ell^- h\) & 3 & 1 \\
\(pp\to \ell^+\ell^- h j\) & 3 & 2 \\
& & \\
\(pp\to \ell^\pm\nu_\ell h\) & 3 & 1 \\
\(pp\to \ell^\pm\nu_\ell h j\) & 3 & 2 \\
& & \\
\(pp\to \gamma j\) & 1 & 2 \\
\(pp\to \gamma j j\) & 1 & 3 \\
& & \\
\(pp\to \gamma \gamma\) & 2 & 1 \\
\(gg\to \gamma \gamma\) & 2 & 1 \\
\(pp\to \gamma \gamma j\) & 2 & 2 \\
& & \\
\(pp\to \gamma \gamma \gamma\) & 3 & 1 \\
& & \\
\(pp\to \gamma \gamma \gamma \gamma\) & 4 & 1 \\
& & \\
\(pp\to \ell^+\ell^-\gamma\) & 3 & 1 \\
\(pp\to \ell^\pm\nu_\ell\gamma\) & 3 & 1 \\
\(pp\to \nu_\ell\bar\nu_\ell\gamma\) & 3 & 1 \\
& & \\
\(pp\to \ell^+\ell^{\prime-}\nu_\ell\bar\nu_{\ell'}\) & 4 & 1 \\
& & \\
\(pp\to \ell^+\ell^-\nu_{\ell'}\bar\nu_{\ell'}\) & 4 & 1 \\
\(pp\to \ell^+\ell^-\ell^{\prime+}\ell^{\prime-}\) & 4 & 1 \\
\(pp\to \ell^+\ell^-\ell^+\ell^-\) & 4 & 1 \\
& & \\
\(pp\to \ell^+\ell^-\ell^{\prime\pm}\nu_{\ell'}\) & 4 & 1 \\
\(pp\to \ell^\pm\nu_\ell\nu_{\ell'}\bar\nu_{\ell'}\) & 4 & 1 \\
& & \\
\(pp\to t \bar t\) & 0 & 3 \\
& & \\
\(pp\to j j\) & 0 & 3 \\
\hline
\end{longtable}

In addition, the following HEFT processes are available (requires
model=heft):

\begin{longtable}[]{@{}lll@{}}
\hline
Process & Order EW & Order QCD \\
\hline
\endhead
\(pp\to h\) & 1 & 2 \\
\(pp\to h j\) & 1 & 3 \\
\(pp\to h j j\) & 1 & 4 \\
\hline
\end{longtable}

All processes are crossing invariant.

Further processes may be
implemented in the future. Please contact the authors if interested in a
specific process.

\hypertarget{installation}{%
\midheading{Installation}\label{installation}}

To use the C++ interface, please enable compiling MCFM as a library by
adding the following flag

\begin{verbatim}
cmake .. -DWITH_LIBRARY
\end{verbatim}

This will create a shared library {\verb!libMCFM.so!}
in the {\verb!lib/!} directory.

\hypertarget{usage}{%
\midheading{Usage}\label{usage}}

Examples showing the basic usage of the interface and how to fill the
complete list of parameters with default values are given in
{\verb!src/BLHA/text.cxx!} and
{\verb!src/BLHA/params.cxx!}, respectively.

The MCFM C++ interface is constructed as a C++ class

\begin{verbatim}
CXX_Interface mcfm;
\end{verbatim}

included in the header

\begin{verbatim}
#include "MCFM/CXX_Interface.h"
\end{verbatim}

It must be initialized on a \(\texttt{std::map}\) of
\(\texttt{std::string}\), containing all (standard-model) parameters

\begin{verbatim}
bool CXX_Interface::Initialize(std::map<std::string,std::string>& parameters);
\end{verbatim}

Prior to use, each process has to be initialized in the interface

\begin{verbatim}
int CXX_Interface::InitializeProcess(const Process_Info &pi);
\end{verbatim}

which takes a {\verb!Process_Info!} object as input,
which in turn contains the defining parameters of a given process,
i.e.~the PDG IDs, number of incoming particles, and QCD and EW coupling
orders

\begin{verbatim}
Process_Info(const std::vector<int> &ids, const int nin,const int oqcd, const int oew);
\end{verbatim}

Phase space points are defined using the
{\verb!FourVec!} struct, which represents four-vectors
in the ordering \((E, p_x, p_y, p_z)\)

\begin{verbatim}
FourVec(double e, double px, double py, double pz);
\end{verbatim}

Given a list of four-vectors in this format, one-loop matrix elements
can be calculated either using the process ID returned by the
{\verb!InitializeProcess!} method

\begin{verbatim}
void CXX_Interface::Calc(int procID,const std::vector<FourVec> &p, int oqcd);
\end{verbatim}

or using a {\verb!Process_Info!} struct:

\begin{verbatim}
void CXX_Interface::Calc(const Process_Info &pi,const std::vector<FourVec> &p,int oqcd);
\end{verbatim}

In the same way, the result of this calculation can be accessed either
via the process ID

\begin{verbatim}
const std::vector<double>& CXX_Interface::GetResult(int procID);
\end{verbatim}

or using the {\verb!Process_Info!} struct:

\begin{verbatim}
const std::vector<double> &CXX_Interface::GetResult(const Process_Info &pi)
\end{verbatim}

The result is returned as a list of Laurent series coefficients in the
format
\begin{equation*}
(\mathcal{O}(\varepsilon^0), \mathcal{O}(\varepsilon^{-1}), \mathcal{O}(\varepsilon^{-2}), \mathrm{Born})
\;.
\end{equation*}
However, by default only the \(\mathcal{O}(\varepsilon^0)\) coefficient,
i.e.~the finite part, is returned.

The calculation of the pole terms and the Born can be enabled by setting
the following switch to {\verb!1!}

\begin{verbatim}
void CXX_Interface::SetPoleCheck(int check);
\end{verbatim}

\hypertarget{tests}{%
\midheading{Tests}\label{tests}}

A set of programs to test MCFM's amplitudes against
\href{https://openloops.hepforge.org}{OpenLoops},
\href{https://recola.gitlab.io/recola2/}{Recola}, and
\href{http://madgraph.phys.ucl.ac.be}{MadLoop} can be compiled. For
example to compile the OpenLoops test program an additional OpenLoops
directory {\verb!-DOLDIR=$HOME/OpenLoops!} must be
specified that contains the header files in the
{\verb!include!} subdirectory. For Recola and MadLoops
the variables {\verb!RCLDIR!} and
{\verb!MLDIR!} must be specified, respectively.