[an error occurred while processing this directive]
Package-X is hosted by Hepforge, IPPP Durham

Introduction to CollierLink

CollierLink extends the analytic capabilities of Package-X by supplying a fast and stable numerical implementation of Passarino-Veltman functions provided by the COLLIER library.

This tutorial illustrates how to use CollierLink. To make the most of CollierLink, it is recommended that you are fairly experienced with Mathematica, and have used Package-X before. Although not necessary, it is also helpful to have prior experience with using the COLLIER library.

Numerical evaluation of Passarino-Veltman functions

Normally, the Passarino-Veltman functions PVA, PVB, PVC, PVD and PVX in Package-X do not numerically evaluate. Instead they must be turned into analytic expressions by LoopRefine before they can be evaluated. When CollierLink is initialized, the COLLIER library is loaded into the Mathematica runtime, and definitions are added to the Passarino-Veltman functions so they can be numerically evaluated.

PVA[r,m0]numerically evaluates with the COLLIER library.
PVB[r,n1,s,m0,m1]numerically evaluates .
PVB'[r,n1,s,m0,m1]numerically evaluates .
PVC[r,n1,n2,s1,s12,s2,m0,m1,m2]numerically evaluates .
PVD[r,n1,n2,n3,s1,s2,s3,s4,s12,s23,m0,m1,m2,m3]numerically evaluates .
PVX[r,n1,n2,,s01,s12,s23,,m0,m1,m2,]numerically evaluates the general Passarino-Veltman function .
UVDiv[PVx][r,]numerically evaluates the UV divergent polynomial of the Passarino-Veltman function.

Passarino-Veltman functions that can be numerically evaluated with CollierLink.

After loading CollierLink, the Passarino-Veltman functions can be directly evaluated.
In[1]:=
Click for copyable input
When all arguments of the Passarino-Veltman function are numerical, an appropriate call to the COLLIER library subroutine A_cll, or B_cll, or C_cll, or ... is made.
In[1]:=
Click for copyable input
Out[1]=
In[2]:=
Click for copyable input
Out[2]=
Numerical evaluation of the derivative of B functions calls the subroutine DB_cll:
In[3]:=
Click for copyable input
Out[3]=
In[4]:=
Click for copyable input
Out[4]=
Numerical evaluation of the UV divergent polynomial with Package-X, and with the COLLIER library:
In[5]:=
Click for copyable input
Out[5]=
Out[6]=

When CollierLink loaded, the COLLIER library is initialized with init_cll(6,6,''). This allocates sufficient memory for the evaluation of Passarino-Veltman functions of up to rank 6 and with up to 6 denominator factors.

Setting and Getting Parameters

The COLLIER library provides a number of global parameters which influence the numerical evaluation of Passarino-Veltman functions, which may be modified with SetCollierLinkOptions.

CollierLinkOptions[]get the current values of global parameters.
SetCollierLinkOptions[namevalue]set new values for global parameters.

Getting and setting parameters of the COLLIER library.

parameter name
default value
"MaxRank"6highest rank for which Passarino-Veltman functions can be numerically evaluated
"Mode"1branch of COLLIER library to use for numerical evaluation. 1=COLI, 2=DD, 3=both branches
"InvEpsUV"0.0numerical value of ultraviolet poles
"MuUV"1.0value of 't Hooft mass parameter in logarithms associated with ultraviolet divergences.
"InvEpsIR"{0.0,0.0}numerical values of infrared {, } poles
"MuIR"1.0value of 't Hooft mass parameter in logarithms associated with infrared divergences.

Some of the global parameters settable by SetCollierLinkOptions.

The option "MaxRank" specfies the highest rank for which the Passarino-Veltman functions can be numerically evaluated. To calculate higher rank Passarino-Veltman functions, set "MaxRank" to a higher number.

The default "MaxRank" is 6:
In[7]:=
Click for copyable input
Out[7]=
Out[8]=
Raise "MaxRank" to 7 to evaluate higher rank Passarino-Veltman functions:
In[9]:=
Click for copyable input
Out[10]=
Out[11]=

The COLLIER library offers two independent numerical implementations of the Passarino-Veltman functions: the COLI branch programmed by Ansgar Denner, and the DD branch programmed by Stefan Dittmaier. When CollierLink is initialized, the COLI branch is active by default, but it may be changed by toggling the "Mode" setting at any time during the Mathematica runtime.

Evaluate the Passarino-Veltman functions using the COLI branch and the DD branch:
In[12]:=
Click for copyable input
Out[13]=
Out[15]=

This feature is useful to internally crosscheck the numerical implementations of the Passarino-Veltman functions in the COLLIER library.

Once a setting has been modified with SetCollierLinkOptions, all further numerical evaluations will be carried out with these settings until they are changed again. To check the current settings, use CollierLinkOptions[]:

In[16]:=
Click for copyable input
Out[16]=

Computations with CollierLink

In this section, the partial width is constructed and evaluated with CollierLink to illustrate a typical workflow. The integrals are set up with LoopIntegrate, and all kinematic conditions are applied, as is typical for calculations with Package-X. However, instead of calling LoopRefine, the expression is manipulated at the level of Passarino-Veltman functions, and ultimately numerically evaluated directly.

Load CollierLink:
In[1]:=
Click for copyable input
On shell and kinematic relations:
In[1]:=
Click for copyable input

W boson contributions:

In[2]:=
Click for copyable input
Out[5]=

Top quark contribution:

In[6]:=
Click for copyable input
Out[8]=

Hypothetical charged scalar loop:

In[9]:=
Click for copyable input
Out[12]=
Form the total:
In[13]:=
Click for copyable input

Once the amplitude has been constructed, couplings and masses should be renormalized to render the amplitude finite, and the limit to should be taken. Below are some functions to help carry out this task:

LoopRefine[expr,PartUVDivergent]computes the UV divergent pole part of expr.
SeparateUV[expr]extracts rational polynomials of UV origin, and obtains the behavior of expr.

Tools for renormalizing and taking the limit .

In this example, the amplitude is free of UV divergences, so no parameters need to be renormalized.

This confirms the amplitude is UV finite:
In[14]:=
Click for copyable input
Out[14]=

Despite its finiteness, observe that the W boson contribution to the amplitude contains explicit dependence on , which is multiplying UV-divergent Passarino-Veltman functions in several places, e.g.
    8 mW2 PVC[1,0,0,0,0,mH2,mW,mW,mW], and
    -2 (-1+) mW2 PVB[0,0,mH2,mW,mW]
Since the COLLIER library is unable to algebraically handle , the rational polynomials of UV origin of this kind must be separated out explicitly.

This isolates polynomials of UV origin from Passarino-Veltman functions:
In[15]:=
Click for copyable input
Out[15]=
Make the rational polynomials of UV origin in the amplitude explicit (here, Simplify serves to shorten the expression, and is not essential):
In[16]:=
Click for copyable input
Out[16]=

To obtain the total width, the amplitude must be squared, which in turn requires the conjugate of the amplitude. Since the tensors and are real, only the scalar coefficient functions multiplying them need to be conjugated. For this, you can use the Package-X utility function X`Utilities`CollectByTensorStructures to conjugate the coefficient functions.

X`Utilities`CollectByTensorStructures[expr,Conjugate]organizes expr by tensor structures and applies Conjugate to each coefficient.

Conjugating just the scalar functions.

The applies Conjugate to the Lorentz invariant form factors:
In[17]:=
Click for copyable input
Out[17]=
Take the complex conjugate of the amplitude, and store it as ampTo4Conj (Simplify not essential):
In[18]:=
Click for copyable input
Out[18]=

When squaring this amplitude, the external polarization sum can be straightforwardly taken by contracting the μ and ν indices of the amplitude with the μ and ν indices of its complex conjugate.

The amplitude squared, with the normalization factor restored:
In[19]:=
Click for copyable input

The decay width is constructed by multiplying the calculated squared amplitude with the phase space factor and by dividing by the flux factor of . The result is an expression involving various Passarino-Veltman functions that can be numerically evaluated.

Define the width as a function of the hypothetical charged scalar mass and the Higgs portal coupling:
In[20]:=
Click for copyable input
Evaluate it at a point:
In[21]:=
Click for copyable input
Out[21]=
Make a plot:
In[22]:=
Click for copyable input
Out[22]=

When the numerical evaluation of an expression is attempted, separate COLLIER library function calls are made for each Passarino-Veltman function in the expression as part of Mathematica's standard evaluation sequence. The kernel then combines them and ultimately returns a result. Despite being computationally expensive, results of individual Passarino-Veltman functions are not remembered, and each one in the expression is recalculated anew which is quite inefficient. Therefore, computing with CollierLink in the way described above is suitable for light-weight computations. But for heavy-duty computations involving hundreds (or even thousands) of Passarino-Veltman functions, direct evaluation can take a lot of time.

Compiling Functions with CollierLink

Using CollierCompile, larger expressions can be evaluated much more efficiently by creating and compiling a program which uses the COLLIER library. This keeps Mathematica's kernel at bay until the final result is obtained. Furthermore, since the program is guaranteed to make calls of the Passarino-Veltman coefficient functions in a predetermined and fixed order, the program can take advantage of COLLIER's global cache system to avoid recalculation of previously computed Passarino-Veltman functions.

CollierCompile[{x1,x2,},expr] takes an expression expr and returns a CollierCompiledFunction which evaluates this expression using the COLLIER library when provided numerical values for x1, x2, .

CollierCompile[{x1,x2,},expr]compile expr to be evaluated using the COLLIER library.

Compiling expressions for evaluation with the COLLIER library.

This creates and compiles a program to evaluate using the COLLIER library, and stores it as f:
Out[23]=
Click for copyable input
Out[23]=
Evaluating f yields the same result as evaluating PVB directly:
Out[24]=
Click for copyable input
Out[24]=
Out[25]=

CollierCompile holds its arguments unevaluated, and definitions made earlier in the Mathematica session will not be inserted into its argument. Use Evaluate to override this nonstandard behavior to force evaluation of its argument before compiling the function.

This defines myExpr to be a one-loop integral:
In[26]:=
Click for copyable input
Out[26]=
CollierCompile does not recognize myExpr. Use Evaluate to insert its definition:
In[27]:=
Click for copyable input
Out[27]=
In[28]:=
Click for copyable input
Out[28]=

Using the cache system

Each time a CollierCompiledFunction is created, a new cache is designated to it. In order to properly use COLLIER's cache system, it needs to be "taught" which Passarino-Veltman functions need not be recalculated and can be remembered. Therefore CollierCompile automatically primes its cache by evaluating the function at several random values of its arguments x1, x2, before returning a CollierCompiledFunction ready for you to evaluate.

But, in order to take full advantage of the cache system, it is important to specify parameters of the function which will not change from one evaluation to the next (e.g. fixed coupling constants and masses). Otherwise, in the course of priming the cache system, it will inadvertently be taught that these parameters can change, potentially leading to far fewer remembered Passarino-Veltman functions. You can specify the constants and their values using the Constants option.

This creates a compiled function with one argument, s, and two constants, g and m:
Out[29]=
Click for copyable input
Out[29]=

Keeping the mechanics of the cache system in mind, you can use CollierCompile to create and compile a program to evaluate the partial width. Suppose you are interested in making a parameter scan only over the hypothetical scalar boson mass and Higgs portal coupling mS and λp. Then it is wise to specify them as function arguments, and the declare the remainder e, Nc, Qf, v, mH, mW, mt as constants.

This creates a compiled function to evaluate the partial width as a function of two parameters:
In[30]:=
Click for copyable input
Out[30]=
Make a plot using the CollierCompiledFunction. Observe how much faster it evaluates:
Out[31]=
Click for copyable input
Out[31]=

Since the Standard Model masses and couplings were declared constants, the Passarino-Veltman functions making up the W-boson and top-quark contributions were calculated and remembered when the cache was primed at the time the CollierCompiledFunction was created. The only Passarino-Veltman functions which were recalculated to construct the plot are the select few that make up the scalar boson contribution.