MadGraph Interface

A small library of matrix elements obtained with MADGRAPH is included with the standard VINCIA release, along with the corresponding HELAS routines. The interface allows VINCIA to match to these matrix elements during the shower evolution. Currently, we are in the process of migrating from an interface based on MG4 to one based on MG5, hence for a time both interfaces will coexist in the code.

flag  Vincia:useMG4   (default = on)
On/Off switch for the MG4 interface.

flag  Vincia:useMG5   (default = on)
On/Off switch for the MG5 interface.

Note: see the section on Useful References for additional references to include when using the matrix elements provided by this interface.

In the interest of forward compatibility, only the interface to MG version 5 is discussed below. (For MG4, see this documentation page in previous versions of VINCIA.)

Conventions and Base Class

Note: this interface is undergoing active development. The conventions below represent a snapshot of the current status, as of June 2017. Significant future developments are expected, with ensuing changes to the conventions and methods given below.

Process Label

VINCIA identifies each MG5 process via a unique process label,

The convention for the process label is that entries 0 and 1 contain the two incoming particles in order of increasing PDG code, taking sign into account. (For decay processes, entry 0 should be the ID of the decaying particle.) Subsequent entries in the vector contain the list of final-state particles, again ordered by increasing PDG code, taking sign into account.

The MG5 interface contains a method to create the process label for a given particle state,

where id is a vector of PDG ID codes, in any order, or alternatively pIn is a list of Pythia8::Particle in any order, with iA and (optionally) iB denoting the positions of the incoming A and (optionally) B particles in the vector.

A single matrix element can be used for several process labels, as for instance in the case of QCD dg>dg, ug>ug, etc. This is achieved by allowing each implemented matrix element to return a vector of process labels (see the description of the base class MG5matrix below), with each entry a specific label to be handled by that matrix element.

Accessing Matrix Elements

The implemented MG5 matrix elements can be accessed in several ways. At the most basic level, a pointer to the MG5matrix instance for a specific process label can be returned (if it exists) by:

If a matrix element for the given process label is not found in VINCIA, a zero pointed is returned.

The value of the matrix element squared for a given particle state can be obtained (if the corresponding process label exists in VINCIA) via the method:

where the set of particles, pIn, should be ordered in VINCIA colour order, i.e., starting on final-state triplets (or initial-state anti-triplets) and progressing along gluons to final-state antitriplets (or initial-state triplets). Note that the starting point for cyclic gluon rings is arbitrary, as is the relative order of multiple contractions and of colour-singlet particles (as long as they are placed outside the colour traces). The MG5 interface will automatically reorder the particles by PDG code (to map the state to a process label, see above), pull the particles with the lowest MG index to the front of cyclic gluon traces, and order multiple separate contractions by lowest MG index of the first parton appearing in each contraction. The resulting permutation of coloured partons is then used to identify the LC topology (MG5 ICOL value) corresponding to the given state, and to identify which helicity amplitude(s) (MG5 IHEL value) to use. Whether the colour information is used or not is controlled by with the values Note that the options 0 and 1 are not normalised by the factorial DBLE(IDEN) factor (permutations of identical particles, and colour/helicity-averaging), while option 2 does include that normalisation. Thus, option 2 returns the usual value that an MG5 matrix element would produce, whereas options 0 and 1 return the values for specific amplitudes (squared) corresponding to specific particle orderings.

Choosing Helicities

Since the MG5 matrix elements contain explicit helicity amplitudes, they can also be used to select a random set of helicities for an initially unpolarised configuration. The corresponding method is:

Note that the input vector of particles, pIn, is a reference, on which the method will operate to replace any unset helicities (particles with pIn[i].pol()=9) by specified ones.

The MG5matrix Base Class

Note: see the existing MG5 matrix elements in interfaces/MG5/ and include/VinciaMG5/ for examples.

As mentioned above, MG5 matrix elements are identified by a (set of) process label(s), which VINCIA uses to determine which matrix-element code to use for a given particle state. Thus, any derived class must provide the following function, which tells VINCIA which states it can handle:

In addition, methods must be provided that provide a human-readable name for the process (or class of processes when several labels are provided), as well as the number of legs (used to set the dimension expected for input vectors):

The main method to translate from the VINCIA colour-ordered indexation to the MG5 PDG-ordered indexation should not normally need to be redefined (general cases already handled by the base class implementation):

Return false if translation impossible / inconsistent input.

Assuming that setPerm() has already been called, the following methods store a set of momenta for later use, assuming the same particle order as in the last call to setPerm() (if permute=true). Note: these methods must be copied explicitly in derived classes so that the private variable pSav will be the variable in the derived class, rather than the one in the base class.

The following methods to determine the IHEL and ICOL values to use must also be provided. The base class implementation relies on maps initialised by initHelMap() and initColMap() (called by the constructor) and can be left as they are unless implementing a new way to set IHEL and/or ICOL.

Further methods used in the current implementation which wraps fortran MG5 matrix elements may also be redefined:

Finally, for a properly initialised ME with well-defined permutation, helicity, and colour structure, the main method to return the corresponding amplitude squared is:

Adding User-Defined Matrix Elements

The procedure for including a new matrix element is not intended for general users at this point, but is documented here for reference.

The MG5 matrix elements included with VINCIA are located in the interfaces/MG5/ subdirectory. The starting point for each matrix element is an ordinary MG5 matrix.f file, as obtained eg from the MG5 output matrix command. To import (any number of) such file(s) into VINCIA, the easiest is to place them in the interfaces/MG5/import/ subdirectory and run the import.sh script (in interfaces/MG5). The script asks for a base class which should normally be MG5matrix. A set of processed .f files suitable for use in VINCIA and named for the matrix elements they contain, along with corresponding C++ .h and .cc wrappers, is produced. The .h files should be moved to the include/VinciaMG5/ directory while the .cc and .f files should be left in interfaces/MG5/. They can be added to VINCIA's list of available matrix elements via the method

Note: this assumes the user has already created an instance of the relevant matrix element, eg in their main program. An example of how to do this can be found in the example program vincia31.cc.

Note 2: if a user-defined matrix element provides any (set of) process label(s) that overlaps with any internal VINCIA one(s), then the user-defined matrix element(s) will supersede and replace the internal VINCIA one(s).

Note 3: to import new matrix elements into VINCIA proper, the script mkProcessList.sh can be called to produce a complete list of matrix elements, which can be used to replace the hardcoded list in src/MG5interface.cc.