~maddevelopers/mg5amcnlo/GGVV_plugin

######################################################################

#                                                                    #

#                          GGVV MG5aMC plugin                        #

#																	 #

#  for the computation of the virtual ME of any process of the class #

#                             g g > V^* V^* 						 #

#  with arbitrary SM vector V decays.								 #

#																	 #

#                        Author: Valentin Hirschi                    #

#                                                   			     #

#  Based on analytical FormFactors provided in                       #

#                                                                    #

#  Andreas von Manteuffel, Lorenzo Tancredi:                         #

#  "The two-loop helicity amplitudes for gg -> V1V2 -> 4 leptons",   #

#  arXiv:1503.08835                                                  #

#                                                                    #

######################################################################

1. Installation and requirements

--------------------------------

1.1 GMP, CLN and GINAC

----------------------

The following three dependencies must be installed, in this order, and

prior to using this plugin:

GMP

CLN

GINAC

1.2 GGVVamp

-----------

Then the library of the in-house version of the GGVVAmp must be compiled

in the directory <MG5aMC_root_path>/PLUGIN/GGVV/ggvvamp-1.0.

First fill in the value of the following three Makefile variables:

GMP_LOCATION   = <SPECIFY_YOUR_GMP_INSTALLATION_PREFIX_HERE>

CLN_LOCATION   = <SPECIFY_YOUR_CLN_INSTALLATION_PREFIX_HERE>

GINAC_LOCATION = <SPECIFY_YOUR_GINAC_INSTALLATION_PREFIX_HERE>

in the file <MG5aMC_root_path>/PLUGIN/GGVV/ggvvamp-1.0/Makefile

Then both the static and dynamic libraries for GGVVamp can be compiled with:

cd <MG5aMC_root_path>/PLUGIN/GGVV/ggvvamp-1.0

make -j8 libggvvamp.a

make -j8 libggvvamp.so

Depending on your system the compilation can take several hours, so make sure

to specify a parallel compilation with as many cores as you have available.

You can quickly the sanity of your installation to this point by compiling

and running the standalone executable './GGVVME_no_thread':

cd <MG5aMC_root_path>/PLUGIN/GGVV/ggvvamp-1.0

make GGVVME_no_thread

./GGVVME_no_thread

The first kinematic configuration evaluated should return the following:

 ---------------------------------

 n  E  px  py  pz  m

 1   0.5000000E+03  0.0000000E+00  0.0000000E+00  0.5000000E+03  0.0000000E+00

 2   0.5000000E+03  0.0000000E+00  0.0000000E+00 -0.5000000E+03  0.0000000E+00

 3   0.5000000E+03  0.1090640E+03  0.4373705E+03 -0.1962062E+03  0.9118800E+02

 4   0.5000000E+03 -0.1090640E+03 -0.4373705E+03  0.1962062E+03  0.9118800E+02

 ---------------------------------

 One-loop ME:    4.1947022165801595

 two-loop ME:    173.44105071267427

 ---------------------------------

Notice that the 'One-loop ME' and 'two-loop ME' are *NOT* matrix evaluation

but just the sum of the real and imaginary part of all form-factors that are

only intended to be used as "hash output" to check the sanity of the installation.

1.3 Envrionment variables and linking

-------------------------------------

We recommend to make the lib directories of GMP, CLN and GINAC as well as the 

directory '<MG5aMC_root_path>/PLUGIN/GGVV/ggvvamp-1.0' available in your

environment variable LD_LIBRARY_PATH (as well as DYLD_LIBRARY_PATHS on MacOS)

so that this plugin can automatically detect their locations.

Alternatively, the corresponding installation prefixes can be speicified

explicitely in the following file of the plugin:

   <MG5aMC_root_path>/PLUGIN/GGVV/GGVV_dependencies_prefixes.dat

Beware however that having all the paths available in the environment variables

above mentionned is mandatory for using dynamic linking (which is quite preferrable

in this case since GGVV amp weighs more than a GB).

For this reason, the plugin uses static linking by default, but this behavior can

be changed prior the output of a process by running the following command in the

MG5_aMC GGVV command-line interface:

GGVV >set_linking_mode dynamic

or toggled back with

GGVV >set_linking_mode static 

2. Running and testing MG5aMC GGVV plugin

-----------------------------------------

Processes of the class 'g g > V^* V^*' with arbitrary SM vector V decays.

In many cases however the syntax to be used for generation is not directly straightforward

as we opted to generate the one-loop amplitude with MadLoop and only the two-loop amplitude

with GGVV, to allow for more possibilities.

It is therefore best to start by running the example process

  g g > e+ e- e+ e- 

including all box contributions (feature both Z-bosons and off-shell photons).

This will also serve as a cross-check of the correct behavior of the plugin.

Indeed, by running the following example cards, you will obtain the one-loop squared ME

for this process using GGVV amplitudes first and then with MadLoop standalone, and you

will be able to make sure the results match.

This can be done as follows for the output using GGVV amplitudes:

./bin/mg5_aMC --mode=GGVV PLUGIN/GGVV/CrossCheck_GGVV_epemepem.mg5

While for MadLoop standalone result the command is:

./bin/mg5_aMC PLUGIN/GGVV/CrossCheck_ML_epemepem.mg5

These cards are commented and the reader is encouraged to read them in order to

gain an understanding of how the generation commands work.

Also, the expected output of the code is included in the comments of the card

and can be used for validation.

Finally, notice that the GGVV UFO model store in 'PLUGIN/GGVV/GGVV_UFO_model' has

special external parameters that are intended to steer the computation of GGVV amplitudes.

These can be accessed and modified in the param_card.dat of the output in:

<PROC_OUTPUT>/Cards/param_card.dat

and are:

  40001 2.0e+00        # n_loops

  40002 1.0e-07        # requiredRelativeAccuracy

  40003 5.0e+00        # NFforAlphaSRunning

  50001 1.0e+00        # include_d_quark 

  50002 1.0e+00        # include_u_quark 

  50003 1.0e+00        # include_s_quark 

  50004 1.0e+00        # include_c_quark 

  50005 1.0e+00        # include_b_quark 

  50006 1.0e+00        # include_t_quark 

Most importantly you can freely toggle between computing the 1-loop squared

and the 2-loop x 1-loop by adjusting the paramter n_loops from 1.0 to 2.0.

The number of flavours specified only the parameter Nf that will appear

in the running of the LO contribution, so that the mu_r dependence of the 

two-loop form factors can be adjusted accordingly, while the actual list of

flavors that are allowed in the two-loop form factors is controled via the

'include_<flavor>_quark parameters.

The parameter 'requiredRelativeAccuracy' allows to adjust the threshold 

controlling when the numerical accuracy rescue system of GGVVamp must be activated.

Finally, notice that the quark masses are always neglected (i.e. equiv to zero) in

the two-loop form factors, however if you specify non-zero quark masses in the

param_card.dat they *will* be used in the computation of the one-loop amplitudes

(computed by MadLoop) that will multiply the two-loop form factors.

This might or might not be the anticipated result, this is why it should be stressed here.