How to generate a standalone MadLoop library for the evaluation of one-loop matrix elements

In order to generate a standalone MadLoop library for several processes, you must first generated them with the 'generate' and 'add process' syntax, while making sure to use 'virt=' when specifying the perturbation couplings. Here is an example

MG5_aMC> generate u d~ > e+ ve [virt=QCD]  @42
MG5_aMC> add process c s > c s h QED<=3 QCD=0 [virt=QCD] @23
MG5_aMC> add process g g > z z [virt=QCD] @33
MG5_aMC> ...
MG5_aMC> output MyStandaloneMadLoopOutput

Notice that you cannot output together processes from different models, these will need to be put in separate libraries. Also, the '@<i>' syntax is optional and will be assigned by default if absent, but this can allow you to specify how each process will be identified in the library (i.e. the prefix for the corresponding symbols/subroutines will be ML5_<i>_). At this stage I recommend that you run 'launch -f' this will compile and run each process for a trial kinematic configuration, making sure that they are functional and also performing the initialization of the loop and helicity filters (which only need to be done once after which they are saved on disk for future use in 'MyStandaloneMadLoopOutput/SubProcesses/MadLoop5_resources'):

MG5_aMC> launch -f

You can now exit the MG5_aMC interface and you can go to the various folders 'MyStandaloneMadLoopOutput/SubProcesses/P<i>_*' where <i> is the identifier specified above with the '@' syntax. In each of these folders you can compile the steering fortran driver 'check_sa.f' with

> cd <MG_root>/MyStandaloneMadLoopOutput/SubProcesses/P33_gg_zz
> make check
> ./check

If you want to chose your phase-space point (as opposed to the default behavior which picks a random configuration generated by RAMBO) you can directly modify 'check_sa.f' and change the following parameters

PARAMETER (READPS = .FALSE.) -> PARAMETER (READPS = .TRUE.)
PARAMETER (NPSPOINTS = 4) -> PARAMETER (NPSPOINTS = 1)

and recompile. The kinematic configuration is then read from the file 'PS.input' that you should create and in which you can specify the kinematic configuration in this format (E,px,py,pz) for each external particle, in the order of the process specified, e.g. for our g g > z z case:

> cat PS.input
5.000000000000000E+002        0.000000000000000E+000        0.000000000000000E+000        5.000000000000000E+002
5.000000000000000E+002        0.000000000000000E+000        0.000000000000000E+000       -5.000000000000000E+002
5.000000000000002E+002        3.169376489451249E+002        1.414175899625355E+002       -3.481900926021950E+002
5.000000000000002E+002       -3.169376489451246E+002       -1.414175899625355E+002        3.481900926021950E+002

Notice that the result for the loop matrix element computed for the last kinematic configuration explored by './check' is not only displayed on screen but also written in the file 'results.dat'. The runtime parameter for MadLoop can be edited directly in the card 'MyStandaloneMadLoopOutput/SubProcesses/MadLoopParams.dat' (doesn't necessitate a recompilation). It is worth noting that one can also steer the MadLoop standalone output with f2py, in a similar way as explained in this page.

Finally, the above is convenient when debugging or testing MadLoop for individual PS points, but it is clear that a library is needed to integrate MadLoop loop matrix elements in any third-party tool. In order to do so, you can simply type 'make OLP' or 'make OLP_static' (for a static library) in the Subprocesses folder (OLP stands for One-Loop Provider):

> cd <MG_root>/MyStandaloneMadLoopOutput/SubProcesses
> make OLP_static

And you will see the resulting library 'libMadLoop.a' being created in the folder 'MyStandaloneMadLoopOutput/lib'. You can now link your third-party tool to this library and call main MadLoop subroutines which are 'ML5_<i>_SLOOPMATRIX' where <i> is whatever integer you specified when generating the processes. Notice that the similar subroutines with the name 'ML5_<i>_SLOOPMATRIXHEL' allow you to specify the helicity configuration. You can look for the implementations of these subroutines in the files 'MyStandaloneMadLoopOutput/SubProcesses/P<i>_*/loop_matrix.f' to understand the nature of their inputs (or read the short driver file 'check_sa' that uses them').

*Warning* It is important to stress that at run time MadLoop must have access to the content of the folder '<MG_root>/MyStandaloneMadLoopOutput/SubProcesses/MadLoop5_resources'. You can make sure that this is the case using any of the three following setups:

• Run your executable linked to MadLoop from anywhere within the folder '<MG_root>/MyStandaloneMadLoopOutput/SubProcesses'

OR

• Make a soft link of the folder '<MG_root>/MyStandaloneMadLoopOutput/SubProcesses/MadLoop5_resources' to wherever you are running your executable from

OR

• Before issuing your first call to MadLoop via an 'sloop*' subroutine, first have your program call the MadLoop subroutine 'SETMADLOOPPATH(PATH)' to instruct MadLoop of where you chose to place 'MadLoop5_resources' (PATH is a character array of fixed length 512)

The default reduction tools interfaced to MadLoop (CutTools, IREGI and Ninja) are linked statically so that you don't have to worry about them. However, if you activated optional reduction tools (such as PJFry, Golem or Samurai), they are linked dynamically so that you will have to make sure that these libraries can be found both during the compilation and running of your third party tool linked against MadLoop (all these libraries and includes are soft-linked in the '<MG_root>/MyStandaloneMadLoopOutput/lib' directory.

Finally, as stated before, the best way to understand how to call the various MadLoop subroutines is to read the workflow of the driver file 'check_sa.f'. For completeness, we provide here the details of the inputs and outputs of two of the most common way of calling MadLoop. First the simplest one:

        CALL ML5_<ID>_SLOOPMATRIX(P, RESULT)

where the input is:

• A rank-2 array of double precision floating point variables, i.e. 'real*8 P(0:3,N_external)' which describes the kinematic configuration

and the output is

• A rank-2 array of double precision floating point variables, i.e. 'real*8 RESULT(0:3,0:N_COUPLING_ORDERS_COMBINATIONS)' where 'N_COUPLING_ORDERS_COMBINATIONS' is the number of different combinations of coupling orders which have a contribution for this process.

This number can be retrieved using MadLoop's subroutine 'CALL ML5_23_GET_ANSWER_DIMENSION(N_COUPLING_ORDERS_COMBINATIONS)' and the index 0 corresponds to the sum of all individual contributions.

To summarize, the result returned by MadLoop is

    RESULT(I,J)

with

I=0 -> Born contribution

I=1 -> Finite part of the virtual contribution

I=2 -> Residue of the $\epsilon^{{-1}$ pole of the the virtual contribution}

I=3 -> Residue of the $\epsilon^{{-2}$ pole of the the virtual contribution}

and

J=0 -> Result for the sum of all contributions factorizing different coupling order combinations

J in [1,N_coupling_order_combinations) -> Result for the contribution that factorize the specific coupling order combination labelled with integer 'J'.

and now the most complete access subroutine:

        CALL ML5_<ID>_SLOOPMATRIXHEL_THRES(P, HEL_ID, RESULT, REQ_ACC, PREC_FOUND, RETURNCODE)

whose extra inputs on top of the 'P' explained above are

HEL_ID -> An integer which specifies which helicity configuration you want to evaluate the one-loop matrix element for (ordered as in MadLoop5_resources/ML5_<ID>_HelConfigs.dat). '-1' indicates that you want to sum/average over all helicity configurations.

REQ_ACC -> is a double precision floating point variable that specifies the target relative accuracy for MadLoop's computation (-1.0d0 means that the value of the parameter 'MLStabThres' of MadLoop5_resources/MadLoopParams.dat will be used instead)

And the extra outputs on top of RESULT described above are:

PREC_FOUND(0:NSQUAREDSO) -> An array of NSQUAREDSO floating point variables specifying the numerical accuracy detected for each coupling order combination.
This number can be obtained by calling the MadLoop subroutine CALL ML5_<ID>_GET_NSQSO_LOOP(NSQUAREDSO_LOOP)". The index 0 refers to the sum of all contributions.

RETURNCODE -> An integer providing information on the internal behavior for MadLoop for that particular PS point. It follows the following convention:

     Return code conventions: RET_CODE = H*100 + T*10 + U
   
     Return code == -1 
     No Stability check could be performed  
   
     H == 1
     Stability unknown.
     H == 2
     Stable PS (SPS) point.
     No stability rescue was necessary.
     H == 3
     Unstable PS (UPS) point.
     Stability rescue necessary, and successful.
     H == 4
     Exceptional PS (EPS) point.
     Stability rescue attempted, but unsuccessful.
     
     T == 1
     Default computation (double prec.) was performed.
     T == 2
     Quadruple precision was used for this PS point.
     T == 3
     MadLoop in initialization phase. Only double precision used.
     T == 4
     MadLoop in initialization phase. Quadruple precision used.
     
     U == 0
     Not stable.
     U == 1
     Stable with CutTools in double precision.
     U == 2
     Stable with PJFry++.
     U == 3
     Stable with IREGI.
     U == 4
     Stable with Golem95
     U == 5
     Stable with Samurai
     U == 6
     Stable with Ninja in double precision
     U == 8
     Stable with Ninja in quadruple precision
     U == 9
     Stable with CutTools in quadruple precision. 

Finally, if you want color stripped amplitudes (typically for specific chosen color flows, but not only), this is relatively straightforward too, so contact me directly (Valentin Hirschi) and I'll add instructions on this page.