Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 18

Installation
The PDF evolution module
- Customization of the PDF evolution
  - Setting functions
The DIS module

APFEL v2.6.1: A PDF Evolution Library with QED

corrections

Valerio Bertone1,2, Stefano Carrazza2and Juan Rojo1

1Rudolf Peierls Centre for Theoretical Physics,

1 Keble Road, University of Oxford, OX1 3NP, Oxford, UK

2PH Department, TH Unit, CERN, CH-1211 Geneva 23, Switzerland

Abstract

In this document we present the user manual for the APFEL library. Written in For-

tran 77, all the functionalities can also be accessed via the C/C++ and Python interfaces.

For simplicity, we will restrict ourselves to the description of the C/C++ interface, but the

usage of the Fortran 77 and Python interfaces is very similar and examples of their use

are provided in the examples folder of the APFEL source code. First of all, we will discuss

how to install APFEL and how to execute the basic example programs. After that, we will

list the various customization options that can be accessed by the user for both the PDF

evolution and the DIS structure functions modules.

Contents

1 Installation 1

2 The PDF evolution module 2

2.1 Customization of the PDF evolution . . . . . . . . . . . . . . . . . . . . . . 4

2.1.1 Settingfunctions............................. 5

3 The DIS module 18

1 Installation

The APFEL library is available from its HepForge website:

http://apfel.hepforge.org/

and from the GitHub webpage:

https://github.com/scarrazza/apfel

It can also be accessed directly from the git repository. The last development version can

be downloaded by giving:

1git c lon e ht tp s : // gi thu b . com / sc arra zz a / ap fel . g it

For the tagged versions one can use the git tag commands:

1git tag -l

2git c hec kout tags / t ag_n ame

to switch to any of the past releases. We strongly recommend to use the latest stables

release.

The installation of the APFEL library can be easily done following the standard autotools

sequence:

1./ co n figure

2make

3make inst all

which automatically installs APFEL in /usr/local/. Note that by default the APFEL

library requires an installation of the LHAPDF PDF library1. However, an LHAPDF-less

installation is also supported by giving:

1./ co nf ig ur e -- dis able - l ha pdf

To use a diﬀerent installation path, one simply needs to use the option:

1./ co nfigu re - - pre fix =/ p ath / to / the / in st allation / f old er

In this case, the APFEL installation path should be included to the environmental variable

LD LIBRARY PATH. This can be done adding to the local .bashrc ﬁle (or .profile ﬁle on

Mac) the string:

1export L D_ LI BR AR Y _P AT H = $ LD _L IB RA R Y_ PA TH :/ pa th / to / t he / i ns ta ll at io n /←-

fo lde r / lib

Once APFEL has been properly compiled and installed, the conﬁguration script apfel-config

should automatically be present. Such script is useful to determine the compiler ﬂags.

Type:

1apfel - co nf ig -- h el p

in a shell to see all the possible options. Particularly useful is the --list-funcs ﬂag

that lists all the functions available in APFEL along with a short explanation. In addition,

also the shell script apfel is provided which starts an interactive console session of APFEL

providing a prompt tool to use the library without coding.

In the following we will list and illustrate all the functionalities of APFEL and explaining

how they can be accessed by the user. The most recent version of APFEL provide also an

additional module to compute DIS (and SIA) structure functions in diﬀerent mass scheme.

Such module is dependent of the original PDF evolution module as it inherits from it many

of the setting functions that we will describe in the next section. We will start describing

1The current release of APFEL assumes that LHAPDF version 6 has been previously installed as version 5

is no longer supported.

the functions of the PDF evolution module and we will devote the following section to a

thourough description of the DIS module.

2 The PDF evolution module

The basic usage of the PDF evolution module of APFEL requires only two steps to have

the complete set of evolved PDFs. The ﬁrst step is the initialization of APFEL through the

call of the following function:

1APFEL :: InitializeAPFEL () ;

This will precompute all the needed evolution operators that enter the discretized DGLAP

equation. Let us recall that once the general settings of the evolution have been deﬁned

(perturbative order, heavy quark masses, reference value of αs, and so on), the initializa-

tion needs to be performed only once, irrespective of the scales that are used in the PDF

evolution. The second step consists in performing the actual PDF evolution between the

initial scale Q0 and the ﬁnal scale Q(in GeV). This can be achieved using the function:

1APFEL :: E v o lveAPFEL (Q0 , Q );

Calling this function APFEL solves the discretized DGLAP equations using the evolution

operators precomputed in the initialization step.

Now the user can access the evolved PDFs at the scale Qvia the use of the functions:

1AP FEL :: xPD F (i , x );

2APFEL :: xgamma (x );

where the real variable xis the desired value of Bjorken-xwhile the integer variable i

in the function xPDF, which runs from −6 to 6, corresponds to the quark ﬂavor index

according to the following convention: Note that in APFEL we have explicitly separated

i:−6−5−4−3−2−1 0 1 2 3 4 5 6

xPDF :¯

t¯

b¯c¯s¯u¯

d g d u s c b t

the access to the quark and gluon PDFs (via xPDF) and from that to the photon PDF (via

xgamma). Note also that the functions xPDF and xgamma return xtimes the PDFs (i.e. the

momentum fractions).

The basic information given above is enough to write a simple and yet complete pro-

gram that performs PDF evolution using APFEL. As an illustration, a C/C++ program that

computes and tabulates PDFs to be compared with the Les Houches PDF benchmark

evolution tables would be the following:

1#include <iostream >

2#include < i oma ni p >

3#include <cmath >

4#include " APF EL / APFEL . h"

5using n a mespac e std ;

7int main ()

9// Define grid in x

10 double xl ha [ 11] = {1 e -7 , 1e -6 , 1 e -5 , 1 e -4 , 1 e -3 , 1e -2 ,

11 1e -1 , 3 e -1 , 5 e -1 , 7e -1 , 9 e -1};

13 // Precomputes evolu t ion op erators on the grid

14 APFEL :: InitializeAPFEL () ;

16 // Pe rfor m evo l ution

17 double Q0 = sq rt (2 ) ;

18 double Q = sqrt (100 00) ;

19 APFEL :: E v o lveAPFEL (Q0 , Q );

21 cout << s cientif ic << setpre ci sion (5) << endl ;

22 cout << "x"

23 << setw(11) << " u - u bar "

24 << setw(11) << " d - d bar "

25 << setw(11) << " 2( ubr + dbr ) "

26 << setw(11) << " c+ cbar "

27 << setw(11) << " gluon "

28 << setw(11) << " photon " << endl;

30 cout << s cie nti fic ;

31 // Tab ulate PDFs for the LHA x values

32 for (int i = 0; i < 11; i ++)

33 cout << xlha[i] << "\t"

34 << AP FE L :: xP DF (2 , x lha [ i ]) - A PF EL : : x PD F ( -2 , x lha [i ] ) < < "\t"

35 << AP FE L :: xP DF (1 , x lha [ i ]) - A PF EL : : x PD F ( -1 , x lha [i ] ) < < "\t"

36 << 2 *( AP FEL :: x PDF ( -1 , xlh a [ i ]) + AP FE L :: xP DF ( -2 , xl ha [ i ]) ) < < "\t"

37 << AP FE L :: xP DF (4 , x lha [ i ]) + A PF EL : : x PD F ( -4 , x lha [i ] ) < < "\t"

38 << APFEL :: xPDF (0 , xlha [i ]) << "\t"

39 << AP FEL :: xg am ma ( x lha [ i ]) < < "\t"

40 << endl;

42 return 0;

43 }

It should be noticed that this example code uses the default settings of APFEL for the

evolution parameters such as: initial scale PDFs, perturbative order, heavy quark masses,

values of the couplings, etc. In the following we will discuss how the user can customize

the settings for the PDF evolution in APFEL.

2.1 Customization of the PDF evolution

The customization of the PDF evolution with APFEL can be achieved using a number

of dedicated functions, to be called before the initialization stage, that is before calling

InitializeAPFEL2. We will subdivide the available functions into three cathegories:

2This is not entirely precise because there is a number of customization functions that are eﬀective only

at the evolution level and thus can be called also after InitializeAPFEL but before EvolveAPFEL. We will

discuss this feature case by case when going through all functions available in APFEL.

•the setting functions which provide the real costumization tools. These functions

allow the user to change the way how the initialization and the output (see next

items) functions behave.

•The initialization functions which are resposible to perform the “main” operations,

like initializing the evolution factor and evolving PDFs.

•The output functions which ﬁnally return the result of a given set of setting and

initialization functions.

In the following we will list and comment all the functions belonging to each of the

cathegories above. Finally, we remind the reader that running the conﬁguration script

apfel-config with the --list-funcs ﬂag will list all the functions available in APFEL

along with a short explanation.

2.1.1 Setting functions

Bofore going through the various setting functions, the user should be aware of the fact

that APFEL has a set of default settings that are used if the user does not intervene to

change any of them. This is why the example described above needs only a very limited

number of steps. However, while each time that APFEL is run a banner with a list of the

main settings is displayed, it is usefull to report here the default settings of APFEL. We will

ﬁrst go through all the setting functions and only at the end we will report the default

settings so that the meaning of all of them should be clear to the reader who went through

this section.

Bofore proceeding with the descitpion of the setting functions of the evolution module,

it is useful to notice that in the following we will use the identiﬁers int,double,bool and

string to specify the type of entry expected by each of the fuctions described below.

1APFEL::SetPerturbativeOrder(int pto ) ;

This function sets the perturbative order of the PDF evolution to pto. The integer pto

can take the values 0, 1 ot 2 according to whether the PDF evolution is performed at

O(αs), O(α2

s), or O(α3

s), that is LO, NLO and NNLO, respectively. This function also

sets the perturbative order of the evolution of the couplings αsand αand possibly of the

heavy quark masses. The default for pto is 2.

1APFEL :: S etTh eory ( strin g the ory ) ;

This function sets the theory to be used in the evolution. The alternatives for theory are:

•"QCD": the PDF evolution is done solving the pure QCD DGLAP equations,

•"QED": the PDF evolution is done solving the pure QED DGLAP equations,

•"QUniD": the PDF evolution is done solving the coupled QCD+QED DGLAP equa-

tions as explained above.

There are more options available that access more “exotic” (and obsolete) solutions of the

coupled QCD+QED DGLAP equations. They are:

•"QCEDP" for QCD+QED in parallel,

•"QCEDS" for QCD+QED in series,

•"QECDP" for QED+QCD in parallel,

•"QECDS" for QED+QCD in series,

•"QavDP" for the averaged solution in parallel,

•"QavDS" for the averaged solution in series,

and they refer to diﬀerent combinations of the separate QCD and QED evolutions. The

reader can refer to the original APFEL publication for a detailed explanation. However, the

use of these solution is discouraged unless the user is well aware of their meaning. The

default is "QCD".

1APFEL :: SetV FNS () ;

This function sets the Variable-Flavour Number Scheme (VFNS) for the PDF, αs, and α3

evolution. In practice this means that, if any heavy quark threshold is encountered during

the evolution, the solutions of the DGLAP equation below and above the threshold itself

will be properly matched. This option is used as a default.

1AP FEL :: Se tFF NS ( int nf l );

This function, as opposed to SetVFNS, sets the Fixed-Flavour Number Scheme (FFNS)

with nfl active ﬂavours for the PDF, αsand α(and MS) evolution. This function forces

the evolution to be done with nfl active ﬂavours in any evolution range. The allowed

values are nfl = 3, 4, 5 and 6.

1APFEL::SetAlphaQCDRef(double alpharef , double Qref ) ;

This function sets the reference values of the strong coupling αsat the scale Qref in GeV

to alpharef. The default is alpharef = 0.35 at Qref =√2 GeV.

1APFEL::SetAlphaQEDRef(double alpharef , double Qref ) ;

This function sets the reference values of the QED coupling αat the scale Qref in GeV

to alpharef. The default is alpharef = 7.496252·10−3at Qref = 1.777 GeV.

1APFEL :: Se tLambdaQCDRef ( double lambdaref , int n ref ) ;

3In case the MS deﬁnition for the heavy quark masses is used (see below) and the running of the masses

has been enabled, this function sets the VFNS also for the running of the heavy quark masses.

This function sets the value of ΛQCD in GeV with nref ﬂavours to lambdaref. This

value is used only if the lambda solution of the β-function equation (see below) is used to

compute the running of αs. The default is lambdaref = 0.220 GeV with nref = 5.

1APFEL :: S etPoleMasses ( double mc , double mb , double mt ) ;

This function sets the values of the heavy quark thresholds in GeV and sets the pole-mass

scheme as a renormalization scheme for the heavy quark masses. This function is used as

a default with mc =√2 GeV, mb = 4.5 GeV, mt = 175 GeV.

1APFEL::SetMSbarMasses(double mc , double mb , double mt ) ;

2sets the v alues of the heavy quark t h r esholds

3in GeV in the MSbar scheme .

This function, as opposed to SetPoleMasses, sets the values of the heavy quark masses in

GeV and sets the MS scheme as a renormalization scheme for the heavy quark masses. The

reference scales at which the masses are deﬁned can be speciﬁed using the SetMassScaleReference

function (see below).

1APFEL::SetMassScaleReference(double Qc , double Qb , double Q t );

This function sets the reference scales in GeV at which heavy quark masses are given.

This function is eﬀective only if the MS deﬁnition for the heavy quark masses is used

and has no eﬀect if the pole masses are used. If this function is not called, APFEL will

assume that the mass reference scales are equal to the masses themselves. In other words,

in the absence of a call to this function when using the MS deﬁnition for the heavy quark

masses, the SetMSbarMasses function will deﬁne mc(mc), mb(mb) and mt(mt). If instead

this function is called and the reference scales are found to be diﬀerent from the masses

themselves, the values of mc(mc), mb(mb) and mt(mt) are also evaluated by applying the

RG evolution as they are needed as thresholds for the VFNS evolution when using the MS

deﬁnition for the heavy quark masses.

1APFEL::EnableMassRunning(bool) ;

This function enables or disables the running of the MS masses. This is eﬀective only if

the SetMSbarMasses is also called and in practice switches on and oﬀ the solution RG

equation of the heavy quark masses. The default is true.

1APFEL :: S etTau Mass ( double mtau ) ;

This function sets the values of the τlepton in GeV to mtau. This function is eﬀective

only if the evolution of the lepton PDFs is enabled (see below). The default is mtau =

1.777 GeV.

1AP FEL :: Se tM ax Fl av ou rA lp ha ( int nf ) ;

This function sets the maximum number of active ﬂavours in the evolution of the couplings

αsand α(and the masses) to nf. In practice, this function forces the code not to match the

solution of the β-function and γ-function equations at a given threshold if that threshold

is above the maximum number allowed nf. The default is nf = 6.

1APFEL::SetMaxFlavourPDFs(int nf ) ;

This function sets the maximum number of active ﬂavours in the evolution of PDFs to

nf. In practice, this function forces the code not to match the solution of the DGLAP

equation at a given threshold if that threshold is above the maximum number allowed nf.

The default is nf = 6.

1APFEL::SetRenFacRatio(double ratio );

This function sets the ratio between factorization scale µF(entering PDFs) and renormal-

ization scale µR(entering the couplings and possibly the heavy quark masses) to ratio.

If ratio is diﬀerent from one, APFEL will assume that µR=µF/ratio and, as explained

above, this gives rise to additional terms in the higher order splitting functions. The

default is ratio = 1.

1APFEL::SetTimeLikeEvolution(bool);

This function enables or disables the time-like evolution. This evolution, as opposed to

the space-like evolution used for PDFs, is used to evolve fragmentation functions (FFs).

The default is false.

1APFEL::SetSmallxResummation(bool , st ri ng la ) ;

This function enables or disables the small-xresummation in the evolution and set the

logarithmic accuracy of the resummation to la. The possible options for la are "LL" and

"NLL". The small-xresummation of the evolution relies on an external code called HELL

that returns the diﬀerence between the ﬁxed-order and the resummed splitting functions

as explained above. By default, the small-xresummation is disabled.

1APFE L :: Se tA lp haEvolution ( strin g evol ) ;

This function sets the solution of the β-function equations for the running couplings to

evol. The variable evol can take the following strings:

•"exact": the β-function equations are solved numerically in an exact way using the

Runge-Kutta method. The boundary condition is given by the reference values of

the coupling at the reference scales.

•"expanded": the β-function equations are solved analytically by expanding the in-

verse of the β-function when computing the solution of the RG equation. See above

for more details. The boundary condition is given by the reference values of the

coupling at the reference scales.

•"lambda": the β-function equations are solved in an analytical way in terms of the

Landau pole ΛQCD. See above for more details.

It should be noticed that a diﬀerent choice of evol only aﬀects the running of αsbeyond

LO while the running of α, being computed always at LO, is left unchanged. The default

is evol ="exact".

1APFE L :: S etPDFEvolution ( s tring evolp ) ;

This function sets the solution of the DGLAP equations for the evolution of PDFs to

evolp. The variable evolp can take the following strings:

•"exactmu": the DGLAP equation diﬀerential in the factorization scale µFis solved

numerically in an exact way using the Runge-Kutta method.

•"exactalpha": the DGLAP equation diﬀerential in the coupling αsis solved numer-

ically in an exact way using the Runge-Kutta method. This solution is completely

equivalent to exactmu.

•"expandalpha": the DGLAP equation diﬀerential in the coupling αsis solved an-

alytically by expanding the ratio between splitting functions and β-function. See

above for more details.

•"truncated": this solution mimics the N-space truncated solution and its imple-

mentation requires the numerical derivatives of the expandalpha solution. A detailed

explanantion of the implementation of thsi particular solution is given above.

In all cases the boundary conditions are given by the input initial scale PDFs. The default

is evolp ="exactmu".

1APFEL::SetEpsilonTruncation(double e ps ) ;

If the truncated evolution for PDFs has been chosen by calling the SetPDFEvolution

function, the SetEpsilonTruncation function sets the truncation parameter used to

compute the numerical dericatives to eps.

1APFE L :: S etPDF Set ( s tring name ) ;

This function sets the PDF set to be evolved to name. The string variable name can be

the name of an LHAPDF set. This is needed to distinguish the LHAPDF sets from the

other possible options available. Other possible options for name are:

•"ToyLH": this option returns the so-called toy LH PDFs that have been conceived

for benchmark purposes. Details can be found in Ref. ???.

•"external": this option is useful to evolve an “external” set of PDFs provided by the

user. If this option is chosen, APFEL will look for a routine called ExternalSetAPFEL

whose structure is the following:

subroutine ExternalSetAPFEL(x,Q0,xf)

where xand Q0 are the input values of the Bjorken variable and the scale in GeV,

while xf(-6:7) is the output array whose entries from −6to 6are the usual quark

and gluon distributions (times x) and the 7-th entry corresponds instead to the

photon PDF.

•"external1": This option is completely analogous to external with the only diﬀer-

ence that the name of the routined expected is now ExternalSetAPFEL1. A second

slot for an external set might be useful in some cases if the user want to evolve a

second PDF set in the same code.

•"repexternal": This option is an extension of the previous two and the only dif-

ference is that the code expects a soubroutine called ExternalSetAPFELRep whose

structure is:

subroutine ExternalSetAPFELRep(x,Q0,irep,xf)

where, in addition to the entries discussed above, there is the integer irep that

identiﬁes the irep-th replica of the input set. This option might be useful is the

input set has more than one replica but it’s not directly an LHAPDF set.

•"leptexternal": This option is a further extension of the original external option

in that it also provides as an output the lepton PDFs. In particular, if this op-

tion is chosen, the code looks for a subroutine called ExternalSetAPFELLept whose

structure is the following:

subroutine ExternalSetAPFELLept(x,Q0,irep,xf,xl)

where there is the additional output array xl(-3:3) whose entries correspond to:

xl(-3) =xτ+(x, Q0),

xl(-2) =xµ+(x, Q0),

xl(-1) =xe+(x, Q0),

xl(0) =xγ(x, Q0),

xl(1) =xe−(x, Q0),

xl(2) =xµ−(x, Q0),

xl(3) =xτ−(x, Q0).

In addition, as compared to the options above, the index of the array xf now runs

from -6 to 6(and no longer to 7) as the photon PDF is now the 0-th entry of the

array xl.

•"pretabulated": This option is mainly conceived for an internal purposes but the

user the expert user might want to exploit it becuase it allows one to evolve PDF

sets whose functional form is not know as it makes possible to evolve PDFs starting

from their value in a ﬁnite number of points. However, it is necessary to know

the full structure of the internal grids used by APFEL. This information is anyway

(partially) accessible using some ad hoc functions of APFEL.In particular, if this

option is chosen, the codes looks for a subroutine called pretabulatedPDFs with the

following structure:

pretabulatedPDFs(igrid,alpha,xf,xl)

where the integer igrid identiﬁes the subgrid and the integer alpha runs over the

nodes of the igrid-th grid. Again, xf(-6:6) and xl(-3:3) are the quark and gluon,

and the lepton and photon PDFs.

•"pretabulated1": This option is a copy of pretabulated and the only diﬀerence

is that in this case the code looks for a subroutine called pretabulatedPDFs1 have

the very same structure of that shown above.

•"apfel": This option is again conceived for internal purposes but it might turn out

to be useful if a higher performance of the evolution is required. If the apfel option

is chosen, the code will use as initial PDFs the PDFs evolved from a previous call

of the function EvolveAPFEL. Of course, this requires that a previous evolution with

a PDF set diﬀerent from apfel exists. This might be convenient when one want to

tabulate PDFs over a grid in Qin a faster way. In fact, using the apfel option allows

one to split a wide range in Qinto small sequential steps without the need to do

every single evolution starting from the same initial scale. This is convenient because

the execution time is proportional to the wideness of the energy range covered by

the evolution.

There are other options that are strictly used for internal purposes and thus there is no

need to list them here. The default is name ="ToyLH".

1AP FEL :: Se tR epli ca ( int nr ) ;

This function selects the member or replica of the PDF set to be evolved to nr. This

function is eﬀective only if an LHAPDF set is used and, of course, the integer nr must

be within zero and the maximum number of members/replicas contained in the LHAPDF

set in use. The default is default nr = 0, that is, according to the LHAPDF convention,

the central member.

1APFEL :: S etQLi mits ( double Qmin , double Qmax ) ;

This function sets the energy range in GeV within which the evolution is allowed. In

practice, for a given pair of Qmin and Qmax, the initial scale Q0 and the ﬁnal scale Qof any

evolution must be such that Qmin < Q0, Q < Qmax. The default is Qmin = 0.5 GeV and

Qmax = 100000 GeV.

1APFEL::SetNumberOfGrids(int n g );

This function sets the number of internal x-space subgrids to be used by APFEL to ng. The

parameters of the single grids must be speciﬁed grid by grid using the SetGridParameters

function discussed below. The default is ng = 3.

1APFEL::SetGridParameters(int i , int n , int deg , double x);

This function must always be associated with one call to the SetNumberOfGrids function

described above. It sets the parameter of the i-th subgrid where imust run from 1 to

ng and thus there must be exactly ng calls to SetGridParameters.ncorresponds to the

number intervals (not nodes) of the i-th subgrid, deg identiﬁes the degree of the lagrange

polynomials and thus it is bound to be bigger than zero, and ﬁnally xis lower bound of

the grid being the upper bound always assumed to be 1. It is necessary that the value

of xis increasingly bigger as the index igrid increases. In practice this mean that the

lower bound of the igrid-th subgrid must be in the range covered by the (igrid - 1)-th

subgrid.

1AP FEL :: Se tE xt er na lG ri d ( int i , int np , int deg , double *x);

2sets the e xterna l grid in the po sitio n i with

3np int er vals , interpola ti on de gre e deg . x

4must be a one - dimentio nal array with upper bound

5in 1 ( there ca nnot be mo re than 1 ext ernal gri d ).

1APFEL::SetFastEvolution(bool) ;

2sets the fast PDF e volutio n ( d efa ult tru e ).

1APFEL :: GetVer s ion () ;

2re turn s the A PFE L v ers ion in use .

1APFEL::EnableWelcomeMessage(bool);

2enable s the prin ting of the we lcome me ssage with

3the APFEL banner and the report of the evol u tion

4pa ramet ers ( default true).

1APFE L :: Enabl eEvo lut ionO pera tor ( bool);

2enable s the computati o n of the exte rnal e volutio n

3pa ramet ers ( def aul t false ) .

1APFEL::EnableLeptonEvolution(bool);

2enable s the evol ution of the lepton PDFs when the

3fast QUniD is used ( defa ult false ) .

1APFE L :: Lo ckGr ids ( bool);

2locks the su bgr ids ( de fau lt false ) .

1APFEL :: Clea nUp () ;

2reset s all the evol u tion p a rameters to the

3default se tting s .

1APFEL::SetLHgridParameters(int nx , int nxm , double xmin , double xm , ←-

double xmax , int nq2 , double q2min , double q 2m ax );

2sets the paramete r s of the grid over which PDFs

3will be t abu late d in the LHAPD F for mat .

1APFEL :: ListFunction s () ;

2list s all the fu nct ions availa ble in APFEL .

1Initialization functions:

2APFEL :: InitializeAPFEL () ;

3in itializ es the APFEL library . If no setti ngs has

4been specified , it uses the default ones.

5APFEL :: E volveAP FEL ( double Q0 , double Q);

6evolve s PDFs on the grid to the scale Q [ GeV ]

7st ar tin g f ro m the sca le Q0 [ G eV ].

8APFEL :: D eriveAP FEL ( double Q);

9co mputes the logarit h m i c deri v a tive with re spect

10 of Q of PDFs at the scale Q [ GeV ].

1Outpu t fu nctions :

2AP FEL :: x PD F ( int i , double x ) and xgamma(double x);

3return "x" ti mes t he i - th and the pho ton PDF

4in "x" at the f inal scale "Q" [ GeV ] d efin ed in

5"EvolveAPFEL".

6APFEL :: xPDFa ll ( double x , double * xf ) ;

7return s at once "x" times all the PDF in the

8array xf [ -6:6] c omput ed in "x" at the final scale

9"Q" [ GeV ] d efin ed in "EvolveAPFEL".

10 AP FEL :: x PDF j ( int i , double x ) and xgammaj(double x);

11 return "x" ti mes t he i - th and the pho ton PDF

12 in "x" at the f inal scale "Q" [ GeV ] d efin ed in

13 "EvolveAPFEL" interpo la ted on the joint grid .

14 AP FEL :: d xPD F ( int i , double x ) and dxgamma(double x);

15 return "x" ti mes t he d er iv at iv e in ln ( Q ^2 ) of

16 the i - th and the photon PDF in "x" at the scale

17 "Q" [ GeV ] d efin ed in "DeriveAPFEL".

18 AP FEL :: N PD F ( int i , int N) and Ngamma(int N);

19 return the N - th m ome nt of th e i - th and the

20 photo n PDF the final scale "Q" [ GeV ] def ined in

21 "EvolveAPFEL".

22 AP FEL :: L UM I ( int i , int j , double S);

23 return s the part onic l u minosity of the i- th and

24 j - th p ar to ns for the CoM energy S [ GeV ^2] for the

25 fi nal i nv ari an t mass Mx = Q [ GeV ] d efi ned in

26 "EvolveAPFEL".

27 APFEL :: A lph aQC D ( double Q);

28 return s the QCD strong cou pling alp ha_s at the

29 scale "Q" [ Ge V ].

30 APFEL :: A lph aQE D ( double Q);

31 return s the QED coup ling alpha at the scale

32 "Q" [ GeV ].

33 APFEL::HeavyQuarkMass(int i , double Q);

34 re tu rn s th e m ass of th e i - th he av y qu ar k

35 (i = 4 ,5 ,6) scale "Q" [ Ge V ] ( the m ass es run only

36 when using the MSbar scheme ) .

37 APFEL :: nInter v als () ;

38 return s the number of inter vals of the joint

39 grid.

40 AP FEL :: x Gri d ( int alpha );

41 return s the value of "x" on the alpha - th node of

42 the joi nt grid .

43 APFEL::GetPerturbativeOrder();

44 return s the perturbative order set for the

45 ev o lution

46 APFEL::ExternalEvolutionOperator(string fname, int i , int j , double x , ←-

int beta ) ;

47 return s the PDF evolut i on op erato r .

48 AP FEL :: LH AP DFgr id ( int Nrep , double Qin , stri ng fnam e );

49 pr oduces a PDF i n t e r p o lation grid in the LHAPDF

50 format.

51 APFEL::LHAPDFgridDerivative(int Nrep , st ring fna me );

52 pr oduces an interpolation grid in the LHAPDF

53 format for the der ive d PDFs .

1-- -- Functi o ns of the DIS module ----

3Initialization functions:

5APFEL :: Initializ e A P F E L _ D IS () ;

6in itialize s the DIS module . If no se tti ngs has

7been specified , it uses the default ones.

8APFEL :: Compu teSt ructu reFu ncti onsAP FEL ( double Q0 , double Q);

9co mputes the DIS structu re fu n ctions on the grid

10 at the scale "Q" [ GeV ] app ly ing also the PDF

11 ev o lution from the ini tial scale " Q0 " [ GeV ].

13 Settin g fu nct ion s :

15 AP FEL :: S et Ma ss Sc he me ( s tr ing ms ) ;

16 sets the mass sch eme to be used to compu te the

17 st r ucture functi o ns ( " ms " =" ZM - V FNS " ," FFN S " ,

18 " FONL L - A " ," FO NLL - B " ," FONLL - C " ,default " ms " =

19 "ZM - VF NS " ).

20 APFEL :: SetPolarizationD IS ( double po l );

21 sets the beam po l a r i z ation ( default " po l " = 0) .

22 AP FEL :: S et Pr oc es sD IS ( s tr ing pr ) ;

23 sets proce ss ( " pr " =" EM " ," NC " ," CC " ,default

24 " pr " =" EM " ).

25 APFE L :: Se tP rojec tileDIS ( s tri ng l ept ) ;

26 sets the pr o jectile (" le pt " =" el ec tr on " ,

27 " po sitron " ," ne utrino " ,"antineutrino",default

28 " lept " =" elec tron " ).

29 AP FEL :: Se tT ar getDIS ( stri ng tar ) ;

30 sets the t arget ( " tar " ="proton","neutron",

31 " is osc a lar " ," ir on " ,default " tar " ="proton")

32 APFEL :: S etZ Mas s ( double massz ) ;

33 sets the value of the mass of the Z boson

34 (default " mass z " = 91. 1876 GeV ) .

35 APFEL :: S etW Mas s ( double massw ) ;

36 sets the value of the mass of the W boson

37 (default " mass w " = 80 .38 5 GeV ) .

38 APFEL :: S etProtonMass ( double massp ) ;

39 sets the value of the mass of the p roton

40 (default " mass p " = 0 .9382 72 04 6 GeV ) .

41 APFEL :: S etSin2ThetaW ( double sw ) ;

42 sets the value of sin ^2( t heta_W )

43 (default " sw " = 0. 23126) .

44 APFEL :: S etGF ermi ( double gf ) ;

45 sets the value of Fermi co nstant

46 (default " gf " = 1. 16 63 787 e -5) .

47 APFEL :: SetC KM ( double vud , double vus , double vub ,

48 double vcd , double vcs , double vcb ,

49 double vtd , double vts , double vt b );

50 sets the absolut e value of the entries of the

51 CKM matrix

52 (default: 0.97427d0, 0.22536d0, 0.00355d0,

53 0.2252 2 d0 , 0.97343 d0 , 0.04140 d0 ,

54 0.0088 6 d0 , 0.04050 d0 , 0.99914 d0 ).

55 APFEL::SetRenQRatio(double ra tio ) ;

56 sets the ratio muR / Q ( default 1)

57 APFEL::SetFacQRatio(double ra tio ) ;

58 sets the ratio muF / Q ( default 1)

59 APFE L :: Ena ble Dy nam ic alS ca leV ar iat io ns ( bool);

60 enables or di sables the p ossibility to pe rform

61 fact / ren scale var i a tions point by point without

62 re qu irin g the ra tio \ mu_ {R , F} / Q to be c on sta nt .

63 Li mi tat io ns : \ mu_F = \ mu _R and slow er code .

64 APFEL::EnableTargetMassCorrections(bool);

65 enables or di sables the target mass cor r e c tions

66 to the DIS st ructure func t ions due to the finite

67 mass of the p roton .

68 APFE L :: EnableDampi ngFONLL ( bool);

69 enables or di sables the d ampi ng f actor when the

70 FONLL s tru ctu re functio ns are c omput ed .

71 APFE L :: S electCh arge ( stri ng selch ) ;

72 select s one particu l a r charge in the NC struc t ure

73 fu n ctions (" selch " =" d own " ," u p " ,"strange",

74 " char m ","bottom"," t op " ," all " ,default

75 " selc h " =" all " )

76 APFEL :: SetProp agatorC orrect ion ( double dr ) ;

77 sets the co r rection to the Z pro p a gator i nvolv e d

78 in the NC DIS struct u re fu nctions

79 (default " dr " = 0) .

80 APFEL::SetEWCouplings(double vd , double vu , double ad , double au ) ;

81 sets the vecto r and axial co u plings of the up -

82 and down - t ype qua rks . If they are not set by the

83 user the stand ard co u p l i n g l ings are used .

85 Outpu t fu nctions :

87 APFEL :: F2lig ht ( double x), F2charm(double x ) , F 2b ot tom ( double x ) ,

88 F2to p ( double x), F2total(double x);

89 APFEL :: FLlig ht ( double x), FLcharm(double x ) , F Lb ot tom ( double x ) ,

90 FLto p ( double x), FLtotal(double x);

91 APFEL :: F3lig ht ( double x), F3charm(double x ) , F 3b ot tom ( double x ) ,

92 F3to p ( double x), F3total(double x);

93 return the F2 , FL and xF3 s t r uncture f unction s in

94 "x" at the final scale "Q" [ GeV ] d efin ed in

95 "ComputeStructureFunctionsAPFEL".

96 APFEL :: GetZ Mass () ;

97 return s the value of the mass of the Z boson

98 APFEL :: GetW Mass () ;

99 return s the value of the mass of the W boson

100 APFEL :: GetProtonMas s () ;

101 return s the value of the mass of the proton

102 APFEL :: GetSin2Theta W () ;

103 return s the value of sin ^2( theta _W )

104 APFEL :: GetGF e rmi () ;

105 return s the value of Fermi co nstant

106 AP FEL :: GetC KM ( int u , int d);

107 re tu rn s the a bs ol ut e v alu e of th e (u , d ) e nt ry

108 of the CKM m atrix

109 AP FEL :: GetS IA To ta lC ro ss Se ct io n ( int pto , double Q);

110 return s the SIA total cross s ecti on in natu ral

111 units at the perturba t i v e orde r " pt o " and at the

112 scale "Q" in GeV ( only for time - like ev olut ion ) .

113 APFEL :: E xternalDISOpe r a t o r ( strin g SF , int ihq , int i , double x , int ←-

beta ) ;

114 return s the DIS operato rs .

115

116 Specia l fu n ctions for the product ion of FK tables :

117

118 AP FEL :: Se tF KO bs er va bl e ( st ring obs ) ;

119 APFEL :: GetFKObservable () ;

120 APFEL :: F KSimula tor ( str ing obs , double x , double q , double y , int i , int←-

beta ) ;

121 APFEL :: F KObservables ( string obs , double x , double q , double y);

122 APFEL :: Comput eHard Cross Secti onsDY ( s tring inputfile , string outpu tfile );

123 APFEL :: Co mputeFKTables ( string inputfile , double Q0 , int flmap [196]) ;

Using the dafualt settings of APFEL this is how the evolution banner would look like:

1Welcome to

2_/_/_/ _/_/_/_/ _/_/_/_/ _/_/_/_/ _/

3_/ _/ _/ _/ _ / _/ _/

4_/_/_/_/ _/_/_/_/ _/_/_/ _/_/_/ _/

5_/ _/ _ / _ / _/ _/

6_/ _/ _/ _/ _/_/_/_/ _/_/_/_/

7_____v 2 .6.1 A PDF Evolut ion Library , arXiv :1310 . 1 394

8Author s : V. Bertone , S . Carrazza , J. Rojo

10 Repor t of the evol u tion p ara met ers :

12 QCD evoluti o n

13 Space - l ike e vol ution ( PDFs )

14 Ev o lution scheme : VFNS at N2LO

15 So lution of the DGLAP equat ion : "exactmu" with max imum 6 active fl avours

16 So lution of the coupl ing equ ati ons : " exa ct " with max imum 6 active ←-

flavours

17 Co upl ing refere nce value :

18 - A lpha QC D ( 1 .41 42 GeV ) = 0 .3 500 00

19 Pole heavy quark thr esh old s :

20 - Mc = 1.414 GeV

21 - Mb = 4.500 GeV

22 - Mt = 175.0 00 GeV

23 muR / muF = 1.0000

25 Allowe d ev o lution range [ 0.50 : 100000. 0 0 ] GeV

26 Fast evolut i on e nabl ed

As clear, the most important settings are reported in the banner and we recommand to

consult the banner every time that APFEL is run to make sure that the desired setting are

actually used.

Here is the complete set of default settings used by APFEL:

1APFEL::EnableWelcomeMessage(true);

2APFEL :: S etQL imits (0.5 ,100 000) ;

3APFEL::SetPerturbativeOrder(2);

4APFEL :: SetVF NS

5APFEL :: SetTheo ry (" QCD " );

6APFEL::SetFastEvolution(true) ;

7APFEL::SetTimeLikeEvolution(false );

8APFEL::SetSmallxResummation(false ," NLL " );

9APFEL :: S e t A l p h a Q C D R e f (0.35 , sqrt (2) ;) ;

10 AP FEL :: Se tA lp ha QE DR ef (7. 49 62 52 e - 3 , 1.7 77) ;

11 APFE L :: S et LambdaQCDRef (0. 22 0 ,5 ) ;

12 APFEL::SetEpsilonTruncation(1e-5);

13 APFEL::SetAlphaEvolution(" ex act " );

14 APFEL :: S e t P D F E v o l u t i o n ( "exactmu") ;

15 AP FEL :: Se tR en Fa cR atio (1) ;

16 APFEL :: S e t P o l e M a s ses ( sqrt (2) ,4.5 ,175) ;

17 APFEL :: Se t M a s s S caleRefere n c e ( sqrt (2) ,4.5 ,175) ;

18 APFEL :: S etTa uMas s (1.77 7) ;

19 APFEL::EnableMassRunning(true) ;

20 AP FEL :: Se tM ax Fl av ou rP DF s (6) ;

21 AP FEL :: Se tM ax Fl av ou rA lp ha ( 6) ;

22 APFEL :: SetPDFs et (" ToyLH " );

23 AP FEL :: Se tR epli ca (0) ;

24 APFE L :: E na bleE volut ionOpe rator ( f al se );

25 APFEL::EnableLeptonEvolution(f alse );

26 APFE L :: LockGr ids ( false ) ;

27 APFEL :: S etL H gridParamet e rs (100 ,50 ,1 e -9 ,1e -1 ,1 ,50 ,1 ,1 e10 );

28 AP FEL :: Se tN um be rO fG ri ds (3 ) ;

29 APFEL :: S etGridPara m eters (1 ,80 ,3 ,1 e -5) ;

30 APFEL :: S etGridPara m eters (2 ,50 ,5 ,1 e -1) ;

31 APFEL :: S etGridPara m eters (3 ,40 ,5 ,8 e -1) ;

As an illustration, if the user wants to perform the QCD evolution at NLO instead of

the default NNLO, she/he needs to add to the code above, before the initialization routine

InitializeAPFEL, a call to the corresponding function, that is:

1APFEL::SetPerturbativeOrder(1);

or if the user wants to use as a boundary condition for the PDF evolution a particular

set available through the LHAPDF interface, say NNPDF23 nlo as 0118 qed.LHgrid, she/he

needs to call before the initialization the following function:

1APFEL :: SetPDFS et (" NNPDF2 3 _ n l o_as_01 1 8 _ q ed . LHgrid ");

By default, APFEL will use the central replica of the selected PDF set. Varying any other

setting is similar, various example programs have been collected in the examples folder in

the APFEL source folder.

When modifying the default settings, particular care must be taken with the number

of interpolation grids, the number of points in each grid and the order of the interpolation.

The default settings in APFEL use three grids whose ranges and number of points have been

tuned to give accurate and fast results over a wide range of x. If the default parameters

are modiﬁed, the user should check that the accuracy is still good enough, by comparing

for instance with another run of APFEL with the default interpolation parameters.

The folder examples in the APFEL source directory contains several examples that

further illustrate the functionalities of the code, and that can be used by the user as a

starting point towards a program that suits her/his particular physics needs. All these

examples are available in the three possible interfaces to APFEL:Fortran 77,C/C++ and

Python.

3 The DIS module

Manual

Navigation menu

Versions of this User Manual:

Views

Navigation