structure.tex 8.7 KB
Newer Older
ulrich_y's avatar
ulrich_y committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
%!TEX root=manual
\section{Structure of \mcmule{}}

\mcmule{} is written in Fortran 95 with helper and analysis tools
written in Mathematica and {\tt python2.7}.  The code is written with
two kinds of applications in mind. First, several processes are
implemented, some at NLO, some at NNLO. For these the user can define
an arbitrary (infrared safe), fully differential observable and
compute cross sections and distributions. Second, the program is set
up such that additional processes can be implemented by supplying the
relevant matrix elements.

To just run \mcmule{} only a Fortran compiler such as {\tt gfortran}
is needed.  The main executable can be compiled by running
$ ./configure
$ make mcmule
When started, {\tt mcmule} reads options from {\tt stdin} as specified
in Table~\ref{tab:mcmuleinput} (cf. Section~\ref{sec:example}).

The structure of the code and the relation between the most important
Fortran modules is depicted in Figure~\ref{fig:structure}. A solid
arrow indicates ``using'' the full module, whereas a dotted arrow is
indicative of partial use. In what follows we give a brief description
of the various modules and mention some variables that play a
prominent role in the interplay between the modules.

  \caption{The structure of \mcmule{}.}

    \item[{\tt global\_def}:]
    This module simply provides some parameters such as fermion masses
    that are needed throughout the code. It also defines {\tt prec} as
    a generic type for the precision used. Currently, this simply
    corresponds to double precision.

    \item[{\tt functions}:]
    This module is a library of basic functions that are needed at
    various points in the code. This includes dot products, eikonal
    factors, the integrated eikonal, and an interface for scalar
    integral functions among others.

    \item[{\tt collier}:]
    This is an external module~\cite{Denner:2016kdg}. It will be
    linked to \mcmule{} during compilation and provides the numerical
    evaluations of the scalar, and in rare cases tensor, integral
    functions in {\tt functions}.

    \item[{\tt phase\_space}:]
    The routines for generating phase-space points and their weights
    are collected in this module. Phase-space routines ending with
    {\tt FKS} are prepared for the \ac{FKS} subtraction procedure
    with a single unresolved photon. In the weight of such routines a
    factor $\xi_1$ is omitted to allow the implementation of the
    distributions in the \ac{FKS} method. This corresponds to a global
    variable {\tt xiout1}. This factor has to be included in the
    integrand of the module {\tt{integrands}}. Also the variable {\tt
    ksoft1} is provided that corresponds to the photon momentum
    without the (vanishing) energy factor $\xi_1$. Routines ending
    with {\tt FKSS} are routines with two unresolved photons.
    Correspondingly a factor $\xi_1\,\xi_2$ is missing in the weight
    and {\tt xiout1} and {\tt xiout2}, as well as {\tt ksoft1} and
    {\tt ksoft2} are provided. To ensure numerical stability it is
    often required to tune the phase-space routine to a particular
    kinematic situation.

    \item[{\tt \{pg\}\_mat\_el}]:
    Matrix elements are grouped into \term{process groups} such as
    muon decay ({\tt mudec}) or $\mu$-$e$ and $\mu$-$p$ scattering
    ({\tt mue}). Each process group contains a {\tt mat\_el} module
    that provides all matrix elements for its group.  Simple matrix
    elements are coded directly in this module. More complicated
    results are imported from sub-module not shown in
    Figure~\ref{fig:structure}. A matrix element starting with {\tt P}
    contains a polarised initial state.  A matrix element ending in
    {\tt av} is averaged over a neutrino pair in the final state.

    \item[{\tt \{pg\}}:]
    In this module the soft limits of all applicable matrix elements
    of a process group are provided to allow for the soft subtractions
    required in the \ac{FKS} scheme. These limits are simply the
    eikonal factor evaluated with {\tt ksoft} from {\tt phase\_space}
    times the reduced matrix element, provided through {\tt mat\_el}.

    This module also functions as the interface of the process group,
    exposing all necessary functions that are imported by

    \item[{\tt mat\_el},] which collects all matrix elements as well
    as their particle labelling or \aterm{particle

    \item[{\tt user}:]
    For a user of the code who wants to run for an already implemented
    process, this is the only relevant module.  At the beginning of
    the module, the user has to specify the number of quantities to be
    computed, {\tt nr\_q}, the number of bins in the histogram, {\tt
    nr\_bins}, as well as their lower and upper boundaries, {\tt
    min\_val} and {\tt max\_val}. The last three quantities are arrays
    of length {\tt nr\_q}. The quantities themselves, i.e. the
    measurement function is to be defined in {\tt quant} by the user
    in terms of the momenta of the particles. Cuts can be applied by
    setting the logical variable {\tt pass\_cut} to
    false\footnote{Technically, {\tt pass\_cut} is a list of length
    {\tt nr\_q}, allowing to decide whether to cut for each histogram
    separately.}. Some auxiliary functions
    like (pseudo)rapidity, transverse momentum etc. are predefined in
    {\tt functions}. Each quantity has to be given a name through the
    array {\tt names}.

    Further, {\tt user} contains a subroutine called {\tt userinit}.
    This allows the user to read additional input at runtime, for
    example which of multiple cuts should be calculated. It also
    allows the user to print some information on the configuration
    implemented. Needless to say that it is good idea to do this for
    documentation purposes.

    \item[{\tt vegas}:]
    As the name suggests this module contains the adaptive Monte Carlo
    routine {\tt vegas}~\cite{Lepage:1980jk}.  The binning routine
    {\tt bin\_it} is also in this module, hence the need for the
    binning metadata, i.e. the number of bins and histograms ({\tt
    nr\_bins} and {\tt nr\_q}, respectively) as well as their bounds
    ({\tt min\_val} and {\tt max\_val}) and names, from {\tt user}.

    \item[{\tt integrands}:]
    In this module the functions that are to be integrated by {\tt
    vegas} are coded. There are three types of integrands:
    non-subtracted, single subtracted, and double subtracted
    integrands, corresponding to, for example, the three parts
    of the ${\rm FKS}^2$ scheme~\cite{Engel:2019nfw,Ulrich:2020phd}.
    The matrix elements to be evaluated and the phase-space routines
    used are set using function pointers through a subroutine {\tt
    init\_piece}.  The factors $\xi_i$ that were omitted in the
    phase-space weight have to be included here for the single and
    double subtracted integrands.

    \item[{\tt mcmule}:]
    This is the main program, but actually does little else than read
    the inputs and call {\tt vegas} with a function provided by {\tt

    \item[{\tt test}:]
    For developing purposes, a separate main program exists that is
    used to validate the code after each change. Reference values for
    matrix elements and results of short integration are stored here
    and compared against.


The library of matrix elements (indicated by {\tt mat\_el\_lib})
deserves a few comments. As matrix elements quickly become very large,
we store them separately from the main code. This makes it also easy
to extend the program by minimising the code that needs to be changed.
We group matrix elements into process group, \term{generic processes},
and \term{generic pieces} as shown in Appendix~\ref{sec:pieces}.  In
some cases a generic piece is split into various partitions (cf.
Section~\ref{sec:ps} for details on why that is important).

When running {\tt mcmule}, the code generates a statefile from which
the full state of the integrator can be reconstructed should the
integration be interrupted (cf. Section~\ref{sec:vegasff} for
details). This makes the statefile ideal to also store results in a
compact format.  To analyse these results, we provide a python tool
{\tt pymule}, additionally to the main code for \mcmule{}. {\tt
pymule} uses {\tt numpy}~\cite{Walt:2011np} for data storage and {\tt
matplotlib} for plotting~\cite{Hunter:2007mp}. {\tt pymule} works with
any python interpreter but {\tt IPython}~\cite{Perez:2007ip} is
recommended. We will encounter {\tt pymule} in
Section~\ref{sec:analyse} when we discuss how to use it to analyse
results. A full list of functions provided can be found in