LHAPDF v6 CONFIGURATION FLAGS

Documentation of the configuration flags for use in LHAPDF at the global settings, PDF set info, and PDF member info levels. If a configuration key is requested from a PDF member info and is not found, the search will fall back to first the PDF set and then to the global config.

Note that there is no such thing as a uniquely config-level or set-level quantity: all flags may be set at config, set, or member level – what determines the functionality is the value as evaluated on a PDF member regardless of whether it is set directly on that member or if it has cascaded down from a higher grouping level.

CONFIG LEVEL

Note: The flags listed here are simply most likely to be used at config-level, but they can be set differently for each set or for each member in a set if so desired. Flags set at a more specific level always take precedence.

Verbosity

(uint)

Level of verbosity of the LHAPDF system. 0 is silent, 1 is the default and will print out minimal information about a PDF set or member when first initialized, 2 will print out more verbose information, and higher values are reserved for future use to print out extremely verbose information during PDF use – this will be for debugging only, since printouts during PDF evaluation will slow down the operation of LHAPDF by potentially large factors.

Pythia6LambdaV5Compat

(bool)

An LHAPDF5 compatibility mode flag which sets all LambdaQCD common block values to 0.192 as was historically the case for PYTHIA6's use of LHAPDF. This behaviour is physically incorrect, as well as against the spirit of the PYTHIA6 steering flags, but it is the long-term behaviour of PYTHIA6+LHAPDF and many PYTHIA6 MC tunes have been built around this behaviour. This flag is set 'true' by default to minimise user surprise – most users will expect PYTHIA6 to behave the same with both LHAPDF5 and 6. If you want LHAPDF6 to report correct, i.e. PDF specific, values to PYTHIA6, then explicitly set this flag to be false.

SET LEVEL

To ensure LHAPDF working properly with your set, make sure the following mandatory flags are set in the set info:

SetDesc
Authors
Flavors
NumMembers
XMin
XMax
QMin
QMax
OrderQCD
FlavorScheme
NumFlavors
AlphaS_MZ
AlphaS_OrderQCD
AlphaS_Type
DataVersion
Format

Depending on the alpha_S type, there might be additional mandatory parameters. For 'AlphaS_Type: ipol'

AlphaS_Qs
AlphaS_Vals

and for 'AlphaS_Type: analytic' a continuous range of

AlphaS_Lambda3
AlphaS_Lambda4
AlphaS_Lambda5

has to be provided. For details check the descriptions below.

Note: The flags listed here are simply most likely to be used at set-level, but they can be set differently for each member in a set (or at the global config level) if so desired. Flags set at a more specific level always take precedence.

SetDesc

MANDATORY (string)

A human-readable description of this PDF set.

SetIndex

OPTIONAL, but should be set for sets with assigned LHAPDF IDs (int)

The LHAPDF global ID code for the first member in this PDF set.

Authors

MANDATORY (free string)

Authors of this PDF set.

Year

OPTIONAL (uint)

Year in which this PDF fit was made.

Reference

OPTIONAL (free string)

A reference to the paper that describes this PDF set. Use semicolons to separate a standard journal string, arXiv ID, DOI code, etc.

Particle

OPTIONAL (int): e.g. 2212

The PDG ID code (including nuclear codes) for the parent particle which this PDF set (or member) describes. The most common are proton (2212), neutron (2112), pion (211), photon (22), and nuclei like the deuteron (1000010020).

Flavors

MANDATORY (list[int] or int): [-5,-4,-3,-2,-1,1,2,3,4,5,21]

List of supported (user-visible) parton flavors, using the PDG Monte Carlo numbering scheme (quarks from 1 .. 6, antiquarks from -6 .. -1, and gluon = 21, as well as any "optional extras" such as photon = 22).

NumMembers

MANDATORY (uint): 1

How many members there are in the set, including the central member(s) and error set members.

Note: There is no guarantee that all members are installed or that they are consecutively numbered. This number is the official number of members in the released set.

NumErrorMembers

OPTIONAL... may become mandatory? (uint): e.g. 50

How many members there are in the error part of this set, i.e. not counting any central member(s).

TODO: Default to NumMembers - 1?

Assumed structure of PDF sets has first error member at Nmem = 1?

Note: There is no guarantee that all members are installed or that they are consecutively numbered. This number is the official number of error set members in the released set.

Interpolator

OPTIONAL (enum string): linear, cubic, log, logcubic

The factory name string of the PDF grid interpolator to use – only needs to be specified if overriding the default, which is logcubic. Could also be member-specific, if necessary. Linear and cubic are respectively linear and cubic interpolation in the linear x & Q2 spaces, and log and logcubic are the same but in the (recommended) log(x) and log(Q2) spaces.

Extrapolator

OPTIONAL (enum string): nearest,error

The factory name string of the PDF grid extrapolator to use. It is recommended that this not be set to the "error" value in PDF data files; the choice of whether out-of-range PDFs should throw errors should primarily be made by the code user, and it is not the normally expected behaviour.

XMin, XMax

MANDATORY (float)

Minimum and maximum values of x in the PDF set. Could also be member-specific.

QMin, QMax

MANDATORY (float)

Minimum and maximum values of Q in the PDF set, in GeV. Could also be member-specific.

OrderQCD

MANDATORY (uint): e.g. 2

Maximum number of loops considered in the QCD evolution of this set (i.e. 0 = LO, 1 = NLO, etc.)

FlavorScheme

MANDATORY (enum string): fixed/variable

The flavour treatment scheme used in the fit's QCD evolution. alpha_s evolution will use this value if AlphaS_FlavorScheme is not explicitly set.

NumFlavors

MANDATORY (uint): e.g. 3, 4 or 5

Maximum/fixed number of flavors used in the fit. alpha_s evolution will use this value if AlphaS_NumFlavors is not explicitly set.

AlphaS_MZ

MANDATORY (float): e.g. 0.118

The value of alpha_s at Q = MZ.

AlphaS_OrderQCD

MANDATORY (uint): e.g. 2

Maximum number of loops considered in the QCD evolution of alpha_s corresponding to this PDF set (i.e. 0 = LO, 1 = NLO, etc.)

AlphaS_FlavorScheme

OPTIONAL (enum string): fixed/variable

The flavour treatment scheme used in alpha_s evolution for this PDF fit. If unset, alpha_s evolution will fall back to using the FlavorScheme flag which represents the QCD evolution used for the whole set, not just the alpha_s part.

AlphaS_NumFlavors

OPTIONAL (uint): e.g. 3, 4 or 5

Maximum/fixed number of flavors used in alpha_s evolution for this PDF fit. If unset, alpha_s evolution will fall back to using the NumFlavors flag which represents the QCD evolution used for the whole set, not just the alpha_s part.

AlphaS_Type

MANDATORY (enum string): ode, analytic, ipol

The method to be used to calculate alpha_s for this set (cf. the AlphaS class hierarchy).

AlphaS_Qs, AlphaS_Vals

MANDATORY if AlphaS_Type = ipol (2 x list[float])

A pair of lists for interpolation-based alpha_s(Q) solving (i.e. Alphas_Type = ipol). The values of Q are in GeV, and the two lists must be the same length. If only one of these keys is defined, or if their lengths are different, a metadata exception will be thrown.

AlphaS_Lambda3, AlphaS_Lambda4, AlphaS_Lambda5

MANDATORY if AlphaS_Type = analytic (float): e.g. 0.192

The value of Lambda_QCD in 3, 4 and 5 flavour schemes, used with AlphaS_OrderQCD in determining an alpha_s evolution corresponding to this PDF set if the analytic alpha_s evaluation scheme is used.

A contiguous range of Lambda_n's must be provided, e.g. (3,4,5) or (4,5) or just (5) are ok, but (3,5) is not.

ErrorType

OPTIONAL (but should be present if there is an error set) (enum string): replicas, symmhessian, hessian, custom, none

A set-level declaration of the type of error treatment provided by this set.

Additional members can be given at the end of a set to allow estimation of uncertainties due to parameter variation (for example, alphaS or heavy-quark masses), with string-formatting rules to specify how they are to be combined.

The top-level division of the error-type string is into components to be combined in signed quadrature (i.e. separate quadrature combination for positive and negative variations of the observable from the nominal. These components are separated by + signs in the ErrorType string.

Each quadrature component is treated as a (+,-) pair, in general formed from the envelope of several variation members. The named terms in such an envelope are separated by * symbols, and their core name should follow C-like naming restrictions: alphanumeric and underscore characters, and they cannot start with a digit. You are encouraged to keep these names simple and limit use of underscores to essential situations.

Each term corresponds to either one or two PDF members, depending on the optional presence of a prefix symbol:

if there is no prefix preceding the core name, it is taken to denote a (usually "up/down") parameter-variation pair;
if there is a preceding # character, the term is derived from a single member with a resulting (+,0) or (0,-) error pair;
and if prefixed by a $ character, it represents a single variation-member whose effect is to be symmetrised to a (delta,delta) error pair. A generally asymmetric envelope is returned from the union of these pairs as the total (+,-) pair for that quadrature term.

Examples:

symmhessian: a symmetric Hessian PDF error-set with no parameter variations.
replicas+alphas+mb: a replica set with two pairs of parameter variations to be combined in quadrature.
hessian+alphas+$mc: a Hessian set with a pair variation and a single-member variation to be symmetrised.
replicas+alphas+#fit1*#fit2*$foo+mb: a replica set with a 3-member envelope made from a mix of asymmetric and symmetrised variations, and a final pair of variations: 4 error-groups to be combined in quadrature.

See the demonstration programs in "examples/testpdfunc.cc" and "examples/testpdfunc.py".

ErrorConfLevel

OPTIONAL (but should be present if there is a Hessian error set with confidence level not equal to 1-sigma) (int/float): e.g. 90

The confidence level of the Hessian error set eigenvectors, in percent. If not present, assume 1-sigma = erf(1/sqrt(2)) = 68.2689...% by default.

CentralMember

OPTIONAL (int): e.g. 0

The member ID in this PDF set of the main ("central") member. Usually 0. A negative value indicates that this set has no central member.

FirstErrorMember

OPTIONAL (uint): e.g. 1

The member ID in this PDF set of the first member of an error set. Usually 1.

MZ, MDown, MUp, MStrange, MCharm, MBottom, MTop

OPTIONAL (float)

Masses of quarks and the Z0 boson in this PDF set's evolution. Default values are set in the global LHAPDF config.

ThresholdDown, ThresholdUp, ThresholdStrange, ThresholdCharm, ThresholdBottom, ThresholdTop

OPTIONAL (float)

Flavour activation thresholds for the quarks in this PDF set's evolution. The masses (MDown, MUp, etc.) are used as default values if these are not set.

AlphaS_MDown, AlphaS_MUp, AlphaS_MStrange, AlphaS_MCharm, AlphaS_MBottom, AlphaS_MTop

OPTIONAL (float)

Masses of quarks used in alpha_s evolution for this PDF. The raw PDF MDown, MUp, etc. are used by default.

AlphaS_ThresholdDown, AlphaS_ThresholdUp, AlphaS_ThresholdStrange, AlphaS_ThresholdCharm, AlphaS_ThresholdBottom, AlphaS_ThresholdTop

OPTIONAL (float)

Flavour activation thresholds for the quarks in alpha_s evolution for this PDF. The raw PDF ThresholdDown, ThresholdUp, etc. are used by default, with fallback to AlphaS_Threshold* and AlphaS_M* values.

MinLHAPDFVersion

OPTIONAL but should be present if some LHAPDF6 versions are incompatible. (int): e.g. 600001

Minimal LHAPDF version code (integerised) needed to use this PDF.

DataVersion

MANDATORY (int, default = -1)

The version of this PDF's data file, used to version fixes to the set.

Note: Use a zero or negative value to flag this PDF as unsuitable for production use. The LHAPDF system will produce a warning printout in that case.

ForcePositive

OPTIONAL (uint = 0,1,2, default = 0)

If 0, no positivity forcing will be made.

If 1, force returned PDF values to be positive (always ≥ 0), to avoid accidental interpolation overshoots into negative values.

If 2, force returned PDF values to be positive definite (always ≥ 1e-10), to avoid both negative values and also ensure that the PDF is never exactly 0, to avoid issues with reweighting.

Note

OPTIONAL (str)

An important short piece of usage information about this PDF set. Only use it exceptionally, e.g. for marking that a PDF set is deprecated and users should avoid it. The note will be printed into the online PDF table, and possibly used by other external programs, but does not affect normal runtime behaviour.

MEMBER LEVEL

Note: The flags listed here are simply most likely to be used at member-level, but they can also be set at the set or global config level if so desired. This tends not to make sense for most of the flags listed here, however. Flags set at a more specific level always take precedence.

Format

MANDATORY (enum string): lhagrid1, ... the trailing number is for format versioning.

Used to determine what parser should be instantiated to read the member file(s).

MemDesc

OPTIONAL (free string): Description of the role of this set member.

A PdfDesc flag will be used as a fallback, for backward compatibility.

MemType

MANDATORY (enum string): 'central' or 'error' or 'replica' or 'variation'

The type of this set member, i.e. is it a central (canonical) function or is it meant for use as either a Hessian error or a replica member of a statistical ensemble. Parameter variation members given at the end of a set should have type 'variation', (but 'central' is allowed for backward compatibility).

A PdfType flag will be used as a fallback, for backward compatibility.