.. _sec_libmcmule: libmcmule user guide ==================== .. f:currentmodule:: mcmule McMule's Fortran code has hundreds of functions and subroutine and we will not document all of them here. However, we will list those exposed by the :f:mod:`mcmule` module. McMule uses a custom type for real numbers that usually defaults to double precision and is used in the following .. f:type:: real(kind=prec) :attrs: fixed The real number type used in McMule. This cannot be changed at runtime by the user but should be used for all interactions with the code. It usually refers to double precision Momenta in McMule are of the form ``(/ px, py, pz, E /)`` though it is often advisable to instead use the functions defined in Section :ref:`sec_libmcmule_scalar`. Parameters, variables, and functions of ``libmcmule`` ----------------------------------------------------- The main module of McMule, :f:mod:`mcmule`, exposes the following parameters, variables, and functions to the user Some parameters are denoted as *fixed* (cannot be changed without recompiling McMule) or *protected* (can be changed only through the use of functions) Variables to be set by the user file ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. f:variable:: pass_cut :type: logical :shape: nr_q This controls whether the event is acceptable. If at least one entry of this array is ``.true.`` the event will be calculated and added to the cross section. If individual elements are ``.false.``, this event will *not* be added to the corresponding histogram. :f:mod:`mcmule` will ensure that the size of this array is correct. Exposed as :c:var:`mcmule_pass_cut` in C. .. f:variable:: names :type: character(len=namesLen) :shape: nr_q The names of the distributions the user wishes the calculate. :f:mod:`mcmule` will ensure that the size of this array is correct Exposed as :c:var:`mcmule_names` in C. .. note:: Even though it is possible to calculate multiple closely related cuts simultaneously, this can harm the speed of convergence as the VEGAS algorithm optimises for the cross section and not for the distributions. .. f:variable:: musq :type: real(kind=prec) The renormalisation scale :math:`\mu^2`. This variable *needs* to be set by the user, otherwise McMule will fail. Exposed as :c:var:`mcmule_musq` in C. .. f:variable:: pol1(4) :type: real(kind=prec) The polarisation of the first polarised particle. Exposed as :c:var:`mcmule_pol1` in C. .. f:variable:: pol2(4) :type: real(kind=prec) The polarisation of the second polarised particle Exposed as :c:var:`mcmule_pol2` in C. .. f:variable:: filenamesuffix :type: character(len=filenamesuffixLen) The observable-specific suffix to the vegas file Exposed as :c:var:`mcmule_filenamesuffix` in C. .. f:variable:: userweight :type: real(kind=prec) The weight the user wishes to attach to a given event, may be set by :f:subr:`user.userevent`. Exposed as :c:var:`mcmule_userweight` in C. Couplings and masses ^^^^^^^^^^^^^^^^^^^^ Couplings are (usually) hard-coded in McMule and cannot be changed. Masses can be changed using the :f:subr:`initflavour` routine. .. f:variable:: GF :type: real(kind=prec) :attrs: fixed The Fermi constant. For predominantly historic reasons, this is set to ``1._prec``. Exposed as :c:var:`mcmule_Gf` in C. .. f:variable:: alpha :type: real(kind=prec) :attrs: fixed The fine-structure constant in the :term:`OS` scheme. For predominantly historic reasons, this is set to ``1._prec``. Exposed as :c:var:`mcmule_alpha` in C. .. f:variable:: sw2 :type: real(kind=prec) The weak mixing angle :math:`\sin(\theta_W)^2`. This can be changed by the user at runtime to modify the :term:`EW` scheme that is used. Exposed as :c:var:`mcmule_sw2` in C. .. f:variable:: Mel :type: real(kind=prec) :attrs: fixed The numerical value of the electron mass in MeV, irregardless of the :f:var:`flavour` .. f:variable:: Mmu :type: real(kind=prec) :attrs: fixed The numerical value of the muon mass in MeV, irregardless of the :f:var:`flavour` .. f:variable:: Mtau :type: real(kind=prec) :attrs: fixed The numerical value of the tau mass in MeV, irregardless of the :f:var:`flavour` .. f:variable:: Mproton :type: real(kind=prec) :attrs: fixed The numerical value of the proton mass in MeV, irregardless of the :f:var:`flavour` .. f:variable:: MZ :type: real(kind=prec) :attrs: fixed The numerical value of the Z boson mass in MeV .. f:variable:: Mm :type: real(kind=prec) :attrs: protected The actual value of the ``m`` particle, usually the muon mass but if :f:var:`flavour` is eg. ``tau-e`` the tau mass. Exposed as :c:var:`mcmule_Mm` in C. .. f:variable:: Me :type: real(kind=prec) :attrs: protected The actual value of the ``e`` particle, usually the electron mass but if :f:var:`flavour` is eg. ``tau-mu`` the muon mass. Exposed as :c:var:`mcmule_Me` in C. .. f:variable:: Mt :type: real(kind=prec) :attrs: protected The actual value of the ``t`` particle, usually the tau mass Exposed as :c:var:`mcmule_Mtau` in C. .. f:variable:: scms :type: real(kind=prec) :attrs: protected The numerical value of the centre-of-mass energy Exposed as :c:var:`mcmule_scms` in C. .. f:subroutine:: initflavour(flavour, scms) This sets the values of the masses and centre-of-mass energy as per Section :ref:`sec_general_flavour`. :p character(len=*) flavour: the flavour to use, will be written into :f:var:`flavour` :p real(kind=prec) scms[optional]: the Mandelstam :math:`s = (p_1+p_2)^2` to use. .. warning:: Calling this function at run-time is possible (eg. during :f:subr:`userevent`) but requires updating of ``masses`` (cf. `Issue#57 `__) .. f:variable:: Mj :type: real(kind=prec) The mass of a New Physics particle. Exposed as :c:var:`mcmule_Mj` in C. .. warning:: Calling this function at run-time is possible (eg. during :f:subr:`userevent`) but requires updating of ``masses`` (cf. `Issue#57 `__) .. f:variable:: CLj, CRj :type: real(kind=prec) The values of the left- and right-handed :math:`J\bar\psi\psi` coupling Exposed as :c:var:`mcmule_CLj` and :c:var:`mcmule_CRj` in C. .. f:variable:: the_proton_ff :type: procedure :attrs: pointer A function pointer to the proton form factor. This needs to be of the form .. code:: fortran subroutine proton_formfactor(Q2, Gel, Gmag) real(kind=prec), intent(in) :: Q2 real(kind=prec), intent(out) :: Gel, Gmag ... end subroutine proton_formfactor where ``Q2`` is the momentum transfer :math:`-(p_e-p_p)^2` and ``Gel`` and ``Gmag`` are the Sachs form factors. .. f:variable:: lambda :type: real(kind=prec) When using a dipole or monopole proton form factor, this is the width of the dipole in MeV2. .. f:variable:: kappa :type: real(kind=prec) When using a dipole or monopole proton form factor, this the proton's magnetic dipole moment .. _sec_libmcmule_scalar: Scalar quantities ^^^^^^^^^^^^^^^^^ .. f:function:: s(p1, p2) :type: real(kind=prec) The scalar product :math:`2p_1\cdot p_2` :p real(kind=prec) p1(4): the first momentum :math:`p_1` :p real(kind=prec) p2(4): the second momentum :math:`p_2` .. f:function:: sq(p) :type: real(kind=prec) The Lorentz square :math:`p^2` :p real(kind=prec) p(4): the momentum :math:`p` .. f:function:: asymtensor(p1, p2, p3, p4) :type: real(kind=prec) The total asymmetric tensor :math:`\varepsilon_{\mu\nu\rho\sigma} p_1^\mu p_2^\nu p_3^\rho p_4^\sigma` :p real(kind=prec) p1(4): the momentum :math:`p_1` :p real(kind=prec) p2(4): the momentum :math:`p_2` :p real(kind=prec) p3(4): the momentum :math:`p_3` :p real(kind=prec) p4(4): the momentum :math:`p_4` .. f:function:: cos_th(p1, p2) :type: real(kind=prec) The cosine of the angle between the two momenta :math:`p_1` and :math:`p_2` .. math:: \cos\theta_{12} = \frac{\vec p_1\cdot \vec p_2}{|\vec p_1|\ |\vec p_2|} :p real(kind=prec) p1(4): the first momentum :math:`p_1` :p real(kind=prec) p2(4): the second momentum :math:`p_2` .. note:: This will return 0 if the computation fails .. f:function:: eta(p) :type: real(kind=prec) The pseudorapidity w.r.t. the :math:`z` axis .. math:: \eta = \frac12\log\frac{|\vec p| + p_z}{|\vec p| - p_z} :p real(kind=prec) p(4): the momentum :math:`p` .. f:function:: rap(p) :type: real(kind=prec) The rapidity w.r.t. the :math:`z` axis .. math:: y = \frac12\log\frac{E + p_z}{E - p_z} :p real(kind=prec) p(4): the momentum :math:`p` .. f:function:: pt(p) :type: real(kind=prec) The transverse momentum w.r.t. the :math:`z` axis .. math:: p_T = \sqrt{p_x^2+p_z^2} :p real(kind=prec) p(4): the momentum :math:`p` .. f:function:: absvec(p) :type: real(kind=prec) The length of the three-vector part :math:`|\vec p` :p real(kind=prec) p(4): the momentum :math:`p` .. f:function:: phi(p) :type: real(kind=prec) The azimuthal angle of :math:`p`, :math:`-\pi<\phi<\pi` :p real(kind=prec) p(4): the momentum :math:`p` .. note:: This may return :math:`100\pi` if the calculation fails. .. f:function:: rij(p1, p2) :type: real(kind=prec) The jet distance :math:`R_{12}` between the two momenta :math:`p_1` and :math:`p_2`, normalised by :math:`D_{\text{res}} = 0.7` .. math:: R_{12} = \frac{\Delta y_{12}^2 + \Delta\phi_{12}^2}{D_\text{res}^2} :p real(kind=prec) p1(4): the first momentum :math:`p_1` :p real(kind=prec) p2(4): the second momentum :math:`p_2` .. _sec_libmcmule_transf: Transformations ^^^^^^^^^^^^^^^ .. f:function:: boost_back(rec, mo) boosts the momentum ``mo`` from the frame where ``rec`` is at rest to the frame where ``rec`` is specified, i.e. .. code:: fortran boost_back(rec, (/ 0., 0., 0., sqrt(sq(rec)) /)) = rec This function can be viewed as the inversion of :f:func:`boost_rf`. :p real(kind=prec) rec(4): the system to boost into :p real(kind=prec) mo(4): the momentum to boost :r boost_back(4): the boosted momentum :rtype boost_back: real(kind=prec) .. f:function:: boost_rf(rec, mo) boosts ``mo`` to (non-unique) rest frame of ``rec``, i.e. .. code:: fortran boost_rf(rec, rec) = (/ 0., 0., 0., sqrt(sq(rec)) /) This function can be viewed as the inversion of :f:func:`boost_back`. :p real(kind=prec) rec(4): the system to boost into :p real(kind=prec) mo(4): the momentum to boost :r boost_back(4): the boosted momentum :rtype boost_back: real(kind=prec) .. f:function:: euler_mat(a,b,c) gives the Euler rotation matrix formed by rotation by :math:`\alpha` around the current :math:`z` axis, then by :math:`\beta` around the current :math:`y` axis, and the by :math:`\gamma` around the current :math:`z` axis. .. math:: \begin{pmatrix} c_{\alpha}c_{\beta }c_{\gamma}-s_{\alpha}s_{\gamma}&-c_{\alpha}c_{\beta } s_{\gamma}-c_{\gamma}s_{\alpha}&c_{\alpha}s_{\beta }&0\\ c_{\beta }c_{\gamma}s_{\alpha}+c_{\alpha}s_{\gamma}& c_{\alpha}c_{\gamma}-c_{\beta } s_{\alpha}s_{\gamma}&s_{\alpha}s_{\beta }&0\\ -c_{\gamma}s_{\beta } & s_{\beta }s_{\gamma} &c_{\beta } &0\\ 0 & 0 & 0 &1 \end{pmatrix} :p real(kind=prec) a: the angle :math:`\alpha` :p real(kind=prec) b: the angle :math:`\beta` :p real(kind=prec) c: the angle :math:`\gamma` :r euler_mat(4,4): the :math:`4\times4` Euler matrix :rtype euler_mat: real(kind=prec) Main routine ^^^^^^^^^^^^ If the user wishes to call McMule from their own executable rather than using the default ``mcmule``, they may use .. f:subroutine:: runmcmule(ncall_ad, itmx_ad, ncall, itmx, initial_ran_seed, xi1, xi2, piece, flav, tfilename) This function initialises McMule and performs the integration. Exposed as :c:func:`mcmule_runmcmule` in C. :p integer ncall_ad: number of calls per iteration during pre-conditioning :p integer itmxl_ad: number of iterations during pre-conditioning. No pre-conditioning is performed if this value is zero :p integer ncall: number of calls per iteration during the main run :p integer itmxl: number of iterations during the main run (cf. Section :ref:`sec_stat`). :p integer initial_ran_seed: the initial random seed (cf. Section :ref:`sec_rng`). :p real(kind=prec) xi1, xi2: the :math:`\xi` values, either used for subtraction or the integrated eikonal. It is recommended that they are equal. :p character(len=*) piece: the :f:var:`mcmule/which_piece` to calculate :p character(len=*) flav: the :f:var:`mcmule/flavour` to use :p character(len=*) tfilename [optional]: the filename to use for the output, autogenerated if not present .. f:subroutine:: load_quant(filename) Loads the observable defined in filename using ``dl_open`` :p character(len=*) filename: the library to open .. f:subroutine:: set_observable(number_hist, number_bins, lower_bounds, upper_bounds, measurement_function, user_integration, user_initialisation, user_integration_dimension, names_length, filenamesuffix_length) Set the observable to an already loaded function. :p integer number_hist: The number of distributions to calculate, similar to :f:var:`user/nq` :p integer number_bins: The number of bins in the distributions to calculate, similar to :f:var:`user/nbins` :p real(kind=prec) lower_bounds(number_hist) [target]: The lower bounds of the distributions, similar to :f:var:`user/min_val` :p real(kind=prec) upper_bounds(number_hist) [target]: The upper bounds of the distributions, similar to :f:var:`user/max_val` :p quantfunc measurement_function: a pointer to the measurement function like :f:func:`user/quant` :p usereventfunc user_integration [optional]: a pointer to the user event function like :f:func:`user/userevent` :p inituserfunc user_initialisation [optional]: a pointer to the user initialisation :p integer user_integration_dimension [optional]: the number of integrations the user wishes to carry out to account eg. for beam effects, similar to :f:var:`user/userdim` :p integer names_length: the maximally allowed length of the histogram :f:var:`mcmule/names`, similar to :f:var:`user/namesLen` :p integer filenamesuffix_length [optional]: the maximally allowed length of the observable name as specified in :f:var:`mcmule/filenamesuffix`, similar to :f:var:`user/filenamesuffixLen` Technical parameters ^^^^^^^^^^^^^^^^^^^^ .. warning:: The following parameters are exposed for the user to view for finer control over the :term:`measurement function`. Extreme care must be taken when using these. .. f:variable:: nel :type: integer Set to 1 if electron :term:`VP` loops are to be included, set to 0 otherwise. More options may be added later. Exposed as :c:var:`mcmule_Nel` in C. .. f:variable:: nmu :type: integer Set to 1 if muon :term:`VP` loops are to be included, set to 0 otherwise. More options may be added later. Exposed as :c:var:`mcmule_Nmu` in C. .. f:variable:: ntau :type: integer Set to 1 if tau :term:`VP` loops are to be included, set to 0 otherwise. More options may be added later. Exposed as :c:var:`mcmule_Ntau` in C. .. f:variable:: nhad :type: integer Set to 1 if :term:`HVP` loops are to be included, set to 0 otherwise. More options may be added later. Exposed as :c:var:`mcmule_Nhad` in C. .. f:variable:: which_piece :type: character(len=25) :attrs: protected The piece being integrated, cf. Section :ref:`sec_pieces` and :term:`which_piece`. This variable is read-only and is set by McMule. .. f:variable:: flavour :type: character(len=15) :attrs: protected The flavour configuration being used. This can only be changed using :f:subr:`initflavour` The following parameters should not be modified by the user unless especially advised to do so .. f:variable:: softcut :type: real(kind=prec) :attrs: advanced The value of :math:`\xi` below which the integrand is set to zero without subtraction .. f:variable:: collcut :type: real(kind=prec) :attrs: advanced The value of :math:`\cos\theta` below which the integrand is set to zero .. f:variable:: sSwitch :type: real(kind=prec) :attrs: advanced The value of :math:`\xi` below which the matrix element is approximated at :term:`LP`. This is only available for some matrix elements .. f:variable:: ntsSwitch :type: real(kind=prec) :attrs: advanced The value of :math:`\xi` below which the matrix element is approximated at :term:`NLP`. This is only available for some matrix elements .. f:variable:: pcSwitch :type: real(kind=prec) :attrs: advanced The value of :math:`1-y` below which the matrix element is approximated. This is only available for some matrix elements .. f:variable:: xicut1 :type: real(kind=prec) :attrs: protected The :math:`\xi_c` value below which to subtract the first photon .. f:variable:: xicut2 :type: real(kind=prec) :attrs: protected The :math:`\xi_c` value below which to subtract the second photon .. f:variable:: xieik1 :type: real(kind=prec) :attrs: protected The argument to the first integrated eikonal .. f:variable:: xicut2 :type: real(kind=prec) :attrs: protected The argument to the second integrated eikonal .. f:variable:: zero :type: real(kind=prec) :attrs: fixed Real numbers below this value may be truncated .. f:variable:: pi :type: real(kind=prec) :attrs: fixed .. f:variable:: xiout :attrs: protected The current values of :math:`\xi` for single-real corrections. .. f:variable:: xioutA, xioutB :attrs: protected The current values of :math:`\xi_i` for double-real corrections. .. f:variable:: yout :attrs: protected The current values of :math:`y` for single-real corrections. .. f:variable:: youtA, youtB :attrs: protected The current values of :math:`y_i` for double-real corrections. .. f:variable:: qsoft :attrs: protected The momentum of the soft photon *without* :math:`\xi` for single-real corrections. .. f:variable:: qsoftA, qsoftB :attrs: protected The momenta of the soft photons *without* :math:`\xi_i` for double-real corrections. .. f:variable:: nr_q :attrs: protected This variable is obtained by reading :f:var:`user.nq`. Exposed as :c:var:`mcmule_nr_q` in C; .. f:function:: sachs_gel(q2) :type: real(kind=prec) The electric Sachs form factor of the proton. In the dipole approximation this is .. math:: G_e(Q^2) = \frac1{(1+Q^2/\Lambda)^2} :p real(kind=prec) q2: the value of :math:`Q^2` .. f:function:: sachs_gmag(q2) :type: real(kind=prec) The magnetic Sachs form factor of the proton. In the dipole approximation this is .. math:: G_m(Q^2) = \frac{\kappa}{(1+Q^2/\Lambda)^2} :p real(kind=prec) q2: the value of :math:`Q^2` .. _sec_libmcmule_c: Symbols exposed to C/C++ ^^^^^^^^^^^^^^^^^^^^^^^^ McMule is inherently a Fortran code. However, it can be used with a user file written in C/C++ even though many of the quality-of-life functions defined in Sections :ref:`sec_libmcmule_scalar` and :ref:`sec_libmcmule_transf` are not available. .. c:type:: real The real number type used in McMule .. c:member:: bool* mcmule_pass_cut Preprocessor alias for :f:var:`pass_cut`. .. c:member:: char* mcmule_names Preprocessor alias for :f:var:`names`. It is recommened to use the :c:macro:`MCMULE_SET_NAME` macro to interact with this variable. .. c:member:: real mcmule_musq Preprocessor alias for :f:var:`musq`. .. c:member:: real* mcmule_pol1 Preprocessor alias, points to the first element of :f:var:`pol1`. .. c:member:: real* mcmule_pol2 Preprocessor alias, points to the first element of :f:var:`pol2`. .. c:member:: char* mcmule_filenamesuffix Preprocessor alias, points to the first element of :f:var:`filenamesuffix`. .. c:member:: real* mcmule_userweight Preprocessor alias, points to the user weight .. c:member:: real mcmule_Gf Preprocessor alias for :f:var:`GF`. .. c:member:: real mcmule_alpha Preprocessor alias for :f:var:`alpha`. .. c:member:: real mcmule_sw2 Preprocessor alias for :f:var:`sw2`. .. c:member:: real mcmule_Mm Preprocessor alias for :f:var:`Mm`. .. c:member:: real mcmule_Me Preprocessor alias for :f:var:`Me`. .. c:member:: real mcmule_Mtau Preprocessor alias for :f:var:`Mt`. .. c:member:: real mcmule_scms Preprocessor alias for :f:var:`scms`. .. c:member:: real mcmule_Mj Preprocessor alias for :f:var:`Mj`. .. c:member:: real mcmule_CLj Preprocessor alias for :f:var:`CLj`. .. c:member:: real mcmule_CRj Preprocessor alias for :f:var:`CRj`. .. c:member:: proton_ff mcmule_protonff Preprocessor alias for :f:var:`the_proton_ff`. .. c:member:: real mcmule_protonff_lambda Preprocessor alias for :f:var:`lambda`. .. c:member:: real mcmule_protonff_kappa Preprocessor alias for :f:var:`kappa`. .. c:member:: int mcmule_Nel Preprocessor alias for :f:var:`Nel`. .. c:member:: int mcmule_Nmu Preprocessor alias for :f:var:`Nmu`. .. c:member:: int mcmule_Ntau Preprocessor alias for :f:var:`Ntau`. .. c:member:: int mcmule_Nhad Preprocessor alias for :f:var:`Nhad`. .. c:member:: int mcmule_nr_q Preprocessor alias for :f:var:`nr_q`. .. c:macro:: MCMULE_SET_NAME(q, name) Sets the *q*-th observable to the name ``name`` .. c:function:: void mcmule_initflavour(char* flavour, double* scms) Interface fo f:subr:`initflavour`. :param char* flavour: the flavour combnination to use :param double* scms: a pointer to the centre-of-mass energy. Passing a null pointer will is only allowed for decay processes or when using a flavour preset. .. c:function:: void mcmule_runmcmule(int ncall_ad, int itmx_ad, int ncall, int itmx, int initial_ran_seed, real xicut1, real xicut2, char* piece, char* flav, char* tfilename); Interface for :f:subr:`runmcmule`. :param char* tfilename: set to ``NULL`` to use default .. c:function:: void mcmule_set_observable(int number_hist, int number_bins, real* lower_bounds, real* upper_bounds, quantfunc measurement_function, usereventfunc user_integration, inituserfunc user_initialisation, int user_integration_dimension, int names_length, int filenamesuffix_length) Interface for :f:subr:`set_observable`. The user file in Fortran ------------------------ .. f:currentmodule:: user A Fortran user file must be in the form of a module :f:mod:`user` that defines the following symbols. .. warning:: None of the values may be ``parameters`` in Fortran as they are not exposed to libmcmule .. f:variable:: namesLen :type: integer :attrs: default = 6 The maximally allowed length of the histogram :f:var:`mcmule/names`. .. f:variable:: filenamesuffixLen :type: integer :attrs: default = 10 The maximally allowed length of the observable name as specified in :f:var:`mcmule/filenamesuffix`. .. f:variable:: nq :type: integer :attrs: default=1 The number of distributions the user intends to calculate. .. f:variable:: nbins :type: integer :attrs: default=100 The number of bins in the distributions the user intends to calculate .. f:variable:: userdim :type: integer :attrs: default=0 The number of integrations the user wishes to carry out to account eg. for beam effects .. f:variable:: bin_kind :type: integer :attrs: default=0 The binning mechanism being used, ``0`` for :math:`{\rm d}\sigma/{\rm d}Q` and ``1`` for :math:`Q {\rm d}\sigma/{\rm d}Q`. .. warning:: Note that the latter is not properly tested and should only be used with great care .. f:variable:: min_val :type: real(kind=prec) :shape: nr_q The lower bounds of the distributions .. f:variable:: max_val :type: real(kind=prec) :shape: nr_q The upper bounds of the distributions .. f:subroutine:: inituser If defined, this is called without arguments once as soon as McMule starts and has read all other configuration, meaning that it can access :f:var:`mcmule/which_piece` It needs to at least set :f:var:`mcmule/flavour` through :f:subr:`mcmule/initflavour`. It may be used to read any further information (like cut configuration etc). The user does not have to print hashes -- this is already taken care of -- but is very much invited to include information of what it is they are doing. If the user is using the cut channel of the menu, they may need to set the :f:var:`mcmule/filenamesuffix` variable which is appended to the name of the VEGAS file. Example for reading a cut and setting the flavour: .. code:: fortran SUBROUTINE INITUSER integer cut call initflavour("mu-e", 1000.) read*,cut write(filenamesuffix,'(I2)') cut END SUBROUTINE INITUSER with a global variable ``cut`` .. f:subroutine:: userevent(x, ndim) If defined, the user may use this routine in combination with :f:var:`mcmule/userweight` to integrate over further parameters, i.e. to calculate .. math:: \sigma \sim \int_0^1 {\rm d} x_1 \int_0^1 {\rm d} x_2 \cdots \int_0^1 {\rm d} x_m \times \int {\rm d}\Phi\,\, \left\vert\mathcal{M}_n\right\vert^2\,\, f(x_1,x_2,\cdots,x_n;p_1,\cdots,p_n) with a generalised :term:`measurement function` :math:`f`. A minimal example that does not include extra intgration is .. code:: fortran SUBROUTINE USEREVENT(X, NDIM) integer :: ndim real(kind=prec) :: x(ndim) userweight = 1. END SUBROUTINE USEREVENT :p real(kind=prec) x(ndim): the values of the integration :p integer ndim: the dimension of ``x``, should equal :f:var:`userdim`. .. f:function:: quant(q1,q2,q3,q4,q5,q6,q7) The :term:`measurement function` the user wishes to calculate. This needs to at least set :f:var:`mcmule/pass_cut` but also returns the values of the observables that are to be computed. It also fixes fix the renormalisation scale :f:var:`musq` though this could be done elsewhere. If the user wishes to consider polarised scattering, :f:var:`mcmule/pol1` and :f:var:`mcmule/pol2` need to be set. A minimal example that accepts every event and does not calculate a distribution would be .. code:: fortran FUNCTION QUANT(q1,q2,q3,q4,q5,q6,q7) real (kind=prec), intent(in) :: q1(4),q2(4),q3(4),q4(4),q5(4),q6(4),q7(4) real (kind=prec) :: quant(nr_q) !! ==== keep the line below in any case ==== !! musq = me**2 pol1 = 0. pass_cut = .true. END FUNCTION QUANT :p real(kind=prec) qi(4): the momenta :r quant(nr_q): the observables that are to be histogrammed :rtype quant: real(kind=prec) .. f:currentmodule:: The user file in C/C++ ---------------------- A C/C++ user file must define the following symbols. The defaults are identical to Fortran. .. c:member:: int mcmule_namelen The maximally allowed length of the histogram :c:var:`mcmule_names`. .. c:member:: int mcmule_filename_suffix_length The maximally allowed length of the observable name as specified in :c:var:`mcmule_filenamesuffix`. .. c:member:: int mcmule_number_hist The number of distributions the user intends to calculate. .. c:member:: int mcmule_number_bins The number of bins in the distributions the user intends to calculate .. c:member:: int mcmule_user_integration_dimension The number of integrations the user wishes to carry out to account eg. for beam effects .. c:member:: int mcmule_bin_kind The binning mechanism being used, ``0`` for :math:`{\rm d}\sigma/{\rm d}Q` and ``1`` for :math:`Q {\rm d}\sigma/{\rm d}Q`. .. warning:: Note that the latter is not properly tested and should only be used with great care .. c:member:: real mcmule_lower_bounds[nr_q] The lower bounds of the distributions .. c:member:: real mcmule_upper_bounds[nr_q] The upper bounds of the distributions .. c:function:: void mcmule_user_initialisation() If defined, this is called without arguments once as soon as McMule starts and has read all other configuration, meaning that it can access :f:var:`mcmule/which_piece` and :f:var:`mcmule/flavour`. It may be used to read any further information (like cut configuration etc). The user does not have to print hashes -- this is already taken care of -- but is very much invited to include information of what it is they are doing. If the user is using the cut channel of the menu, they may need to set the :c:var:`mcmule_filenamesuffix` variable which is appended to the name of the VEGAS file. .. c:function:: void mcmule_user_integration(real* x, int ndim) If defined, the user may use this routine in combination with :c:var:`mcmule_userweight` to integrate over further parameters. :param real* x: a pointer to the first element of the values of the integration :param int ndim: the dimension of ``x``, should equal :c:var:`mcmule_user_integration_dimension`. .. c:function:: void mcmule_measurement_function(double** res, real* q1,real* q2,real* q3,real* q4,real* q5,real* q6,real* q7) The :term:`measurement function` the user wishes to calculate. This needs to at least set :c:var:`mcmule_pass_cut` but also returns the values of the observables that are to be computed. It also fixes fix the renormalisation scale :c:var:`mcmule_musq` though this could be done elsewhere. If the user wishes to consider polarised scattering, :c:var:`mcmule_pol1` and :c:var:`mcmule_pol2` need to be set. This may use the macro :c:macro:`MCMULE_SET_NAME` :param real** res: a double pointer to the result. :param real* qi: pointers to the first component of the momenta .. code:: c void mcmule_measurement_function(double**res,double*p1,double*p2,double*p3,double*p4,double*p5,double*p6,double*p7) { mcmule_musq = 1.; res[0][0] = p3[2] / p3[3]; // Set the second quant to p3z/E3 res[0][1] = p4[2] / p4[3]; // Set the second quant to p4z/E4 mcmule_pass_cut[0] = 1; // Accept event mcmule_pass_cut[1] = 1; // Accept event MCMULE_SET_NAME(0, "p3z/E3") MCMULE_SET_NAME(1, "p4z/E4") }