lhapdf

view CONFIGFLAGS @ 1110:2ba52dbf2312

Add release instructions for new sets
author Andy Buckley <andy@insectnation.org>
date Tue, 17 Oct 2017 17:12:04 +0100
parents e5487edcdf41
children
line source
1 /**
2 @page config Configuration flags
5 LHAPDF v6 CONFIGURATION FLAGS
6 =============================
8 Documentation of the configuration flags for use in LHAPDF at the global
9 settings, PDF set info, and PDF member info levels. If a configuration key
10 is requested from a PDF member info and is not found, the search will fall
11 back to first the PDF set and then to the global config.
14 Note that there is no such thing as a uniquely config-level or set-level
15 quantity: all flags may be set at config, set, or member level -- what
16 determines the functionality is the value as evaluated on a PDF member
17 regardless of whether it is set directly on that member or if it has cascaded
18 down from a higher grouping level.
21 CONFIG LEVEL
22 ============
24 @note The flags listed here are simply most *likely* to be used at config-level,
25 but they can be set differently for each set or for each member in a set if so
26 desired. Flags set at a more specific level always take precedence.
29 Verbosity
30 ---------
31 (uint)
33 Level of verbosity of the LHAPDF system. 0 is silent, 1 is the default and will
34 print out minimal information about a PDF set or member when first initialized,
35 2 will print out more verbose information, and higher values are reserved for
36 future use to print out extremely verbose information during PDF use -- this
37 will be for debugging only, since printouts during PDF evaluation will slow down
38 the operation of LHAPDF by potentially large factors.
41 ShowBanner
42 ----------
43 (bool)
45 Whether or not to print out an LHAPDF5-style banner to stdout. (Triggered in Config destructor)
47 NOT YET IMPLEMENTED! Will be once an LHAPDF6 paper is available to cite...
50 Pythia6LambdaV5Compat
51 ---------------------
52 (bool)
54 An LHAPDF5 compatibility mode flag which sets all LambdaQCD common block values
55 to 0.192 as was historically the case for PYTHIA6's use of LHAPDF. This
56 behaviour is physically incorrect, as well as against the spirit of the PYTHIA6
57 steering flags, but it is the long-term behaviour of PYTHIA6+LHAPDF and many
58 PYTHIA6 MC tunes have been built around this behaviour. This flag is set 'true'
59 by default to minimise user surprise -- most users will expect PYTHIA6 to behave
60 the same with both LHAPDF5 and 6. If you want LHAPDF6 to report correct,
61 i.e. PDF specific, values to PYTHIA6, then explicitly set this flag to be false.
64 SET LEVEL
65 =========
67 @note The flags listed here are simply most *likely* to be used at set-level,
68 but they can be set differently for each member in a set (or at the global
69 config level) if so desired. Flags set at a more specific level always take
70 precedence.
73 SetDesc
74 -------
75 MANDATORY
76 (string)
78 A human-readable description of this PDF set.
81 SetIndex
82 --------
83 OPTIONAL, but should be set for sets with assigned LHAPDF IDs
84 (int)
86 The LHAPDF global ID code for the first member in this PDF set.
89 Authors
90 -------
91 MANDATORY
92 (free string)
94 Authors of this PDF set.
97 Year
98 ----
99 OPTIONAL
100 (uint)
102 Year in which this PDF fit was made.
105 Reference
106 ---------
107 OPTIONAL
108 (free string)
110 A reference to the paper that describes this PDF set. Use semicolons
111 to separate a standard journal string, arXiv ID, DOI code, etc.
114 Particle
115 --------
116 OPTIONAL
117 (int): e.g. 2212
119 The PDG ID code (including nuclear codes) for the parent particle which this PDF
120 set (or member) describes. The most common are proton (2212), neutron (2112),
121 pion (211), photon (22), and nuclei like the deuteron (1000010020).
124 Flavors
125 -------
126 MANDATORY
127 (list<int> or int): [-5,-4,-3,-2,-1,1,2,3,4,5,21]
129 List of supported (user-visible) parton flavors, using the PDG Monte Carlo
130 numbering scheme (quarks from 1 .. 6, antiquarks from -6 .. -1, and gluon = 21,
131 as well as any "optional extras" such as photon = 22).
134 NumMembers
135 ----------
136 MANDATORY
137 (uint): 1
139 How many members there are in the set, including the central member(s) and error
140 set members.
142 @note There is no guarantee that all members are installed or that they are
143 consecutively numbered. This number is the official number of members in the
144 released set.
147 NumErrorMembers
148 ---------------
149 OPTIONAL... may _become_ mandatory?
150 (uint): e.g. 50
152 How many members there are in the error part of this set, i.e. not counting any
153 central member(s).
155 TODO: Default to NumMembers - 1?
157 Assumed structure of PDF sets has first error member at Nmem = 1?
159 @note There is no guarantee that all members are installed or that they are
160 consecutively numbered. This number is the official number of error set members
161 in the released set.
164 Interpolator
165 ------------
166 MANDATORY (for grid PDFs)
167 (enum string): linear, cubic
169 The factory name string of the PDF grid interpolator to use -- only *needs* to
170 be specified if overriding the default, which is cubic. Could also be
171 member-specific, if necessary.
174 Extrapolator
175 ------------
176 MANDATORY (for grid PDFs)
177 (enum string): nearest,error
179 The factory name string of the PDF grid extrapolator to use. It is recommended
180 that this not be set to the "error" value in PDF data files; the choice of
181 whether out-of-range PDFs should throw errors should primarily be made by the
182 code *user*, and it is not the normally expected behaviour.
185 XMin, XMax
186 ----------
187 MANDATORY
188 (float)
190 Minimum and maximum values of x in the PDF set. Could also be member-specific.
193 QMin, QMax
194 ------------
195 MANDATORY
196 (float)
198 Minimum and maximum values of Q in the PDF set, in GeV. Could also be member-specific.
201 OrderQCD
202 --------
203 MANDATORY
204 (uint): e.g. 2
206 Maximum number of loops considered in the QCD evolution of this set (i.e. 0 =
207 LO, 1 = NLO, etc.)
210 FlavorScheme
211 ------------
212 MANDATORY
213 (enum string): fixed/variable
215 The flavour treatment scheme used in the fit's QCD evolution. alpha_s evolution
216 will use this value if AlphaS_FlavorScheme is not explicitly set.
219 NumFlavors
220 ----------
221 MANDATORY
222 (uint): e.g. 3, 4 or 5
224 Maximum/fixed number of flavors used in the fit. alpha_s evolution will use
225 this value if AlphaS_NumFlavors is not explicitly set.
228 AlphaS_MZ
229 ---------
230 MANDATORY
231 (float): e.g. 0.118
233 The value of alpha_s at Q = MZ.
236 AlphaS_OrderQCD
237 ---------------
238 MANDATORY
239 (uint): e.g. 2
241 Maximum number of loops considered in the QCD evolution of alpha_s corresponding
242 to this PDF set (i.e. 0 = LO, 1 = NLO, etc.)
245 AlphaS_FlavorScheme
246 -------------------
247 OPTIONAL
248 (enum string): fixed/variable
250 The flavour treatment scheme used in alpha_s evolution for this PDF fit.
251 If unset, alpha_s evolution will fall back to using the FlavorScheme flag which
252 represents the QCD evolution used for the whole set, not just the alpha_s part.
255 AlphaS_NumFlavors
256 -----------------
257 OPTIONAL
258 (uint): e.g. 3, 4 or 5
260 Maximum/fixed number of flavors used in alpha_s evolution for this PDF fit.
261 If unset, alpha_s evolution will fall back to using the NumFlavors flag which
262 represents the QCD evolution used for the whole set, not just the alpha_s part.
265 AlphaS_Type
266 -----------
267 MANDATORY
268 (enum string): ode, analytic, ipol
270 The method to be used to calculate alpha_s for this set (cf. the AlphaS class
271 hierarchy).
274 AlphaS_Qs, AlphaS_vals
275 ----------------------
276 MANDATORY if AlphaS_Type = ipol
277 (2 x list<float>)
279 A pair of lists for interpolation-based alpha_s(Q) solving (i.e. Alphas_Type =
280 ipol). The values of Q are in GeV, and the two lists must be the same length. If
281 only one of these keys is defined, or if their lengths are different, a metadata
282 exception will be thrown.
285 AlphaS_Lambda3, AlphaS_Lambda4, AlphaS_Lambda5
286 ----------------------------------------------
287 MANDATORY if AlphaS_Type = analytic
288 (float): e.g. 0.192
290 The value of Lambda_QCD in 3, 4 and 5 flavour schemes, used with
291 AlphaS_OrderQCD in determining an alpha_s evolution corresponding
292 to this PDF set if the analytic alpha_s evaluation scheme is used.
294 A contiguous range of Lambda_n's must be provided, e.g. (3,4,5) or (4,5) or just
295 (5) are ok, but (3,5) is not.
298 ErrorType
299 ---------
300 OPTIONAL (but should be present if there is an error set)
301 (enum string): replicas, symmhessian, hessian, custom, none
303 A set-level declaration of the type of error treatment provided by this set.
305 Additional members can be given at the end of a set to allow estimation of
306 uncertainties due to parameter variation (for example, alphaS or heavy-quark masses).
307 The number of parameters, npar, is determined by counting the number of "+" characters
308 in the ErrorType, and the last 2*npar members of the set should correspond to parameter
309 variations, i.e. the central PDF fits obtained when a given parameter is moved up or down
310 from the nominal value. For example, "ErrorType: replicas+as+mc+mb+mt" could be used for
311 a set where the last eight members correspond to variation of AlphaS, MCharm, MBottom and
312 MTop, respectively. The parameter variation uncertainty is calculated by summing in
313 quadrature half the difference between each of the two relevant members. This is added
314 in quadrature to the PDF uncertainty to obtain a combined PDF+parameter uncertainty.
315 See the demonstration programs in "examples/testpdfunc.cc" and "examples/testpdfunc.py".
318 ErrorConfLevel
319 --------------
320 OPTIONAL (but should be present if there is a Hessian error set
321 with confidence level not equal to 1-sigma)
322 (int/float): e.g. 90
324 The confidence level of the Hessian error set eigenvectors, in percent.
325 If not present, assume 1-sigma = erf(1/sqrt(2)) = 68.2689...% by default.
328 CentralMember
329 -------------
330 OPTIONAL
331 (int): e.g. 0
333 The member ID in this PDF set of the main ("central") member. Usually 0. A
334 negative value indicates that this set has no central member.
337 FirstErrorMember
338 ----------------
339 OPTIONAL
340 (uint): e.g. 1
342 The member ID in this PDF set of the first member of an error set. Usually 1.
345 MZ, MDown, MUp, MStrange, MCharm, MBottom, MTop
346 -----------------------------------------------
347 OPTIONAL
348 (float)
350 Masses of quarks and the Z0 boson in this PDF set's evolution. Default values
351 are set in the global LHAPDF config.
354 ThresholdDown, ThresholdUp, ThresholdStrange, ThresholdCharm, ThresholdBottom, ThresholdTop
355 -------------------------------------------------------------------------------------------
356 OPTIONAL
357 (float)
359 Flavour activation thresholds for the quarks in this PDF set's evolution.
360 The masses (MDown, MUp, etc.) are used as default values if these are not set.
363 AlphaS_MDown, AlphaS_MUp, AlphaS_MStrange, AlphaS_MCharm, AlphaS_MBottom, AlphaS_MTop
364 -------------------------------------------------------------------------------------
365 OPTIONAL
366 (float)
368 Masses of quarks used in alpha_s evolution for this PDF. The raw PDF MDown,
369 MUp, etc. are used by default.
372 AlphaS_ThresholdDown, AlphaS_ThresholdUp, AlphaS_ThresholdStrange, AlphaS_ThresholdCharm, AlphaS_ThresholdBottom, AlphaS_ThresholdTop
373 -------------------------------------------------------------------------------------------------------------------------------------
374 OPTIONAL
375 (float)
377 Flavour activation thresholds for the quarks in alpha_s evolution for this PDF.
378 The raw PDF ThresholdDown, ThresholdUp, etc. are used by default, with fallback
379 to AlphaS_Threshold* and AlphaS_M* values.
382 MinLHAPDFVersion
383 ----------------
384 OPTIONAL but should be present if some LHAPDF6 versions are incompatible.
385 (int): e.g. 600001
387 Minimal LHAPDF version code (integerised) needed to use this PDF.
390 DataVersion
391 -----------
392 MANDATORY
393 (int, default = -1)
395 The version of this PDF's data file, used to version fixes to the set.
397 @note Use a zero or negative value to flag this PDF as unsuitable for production
398 use. The LHAPDF system will produce a warning printout in that case.
401 ForcePositive
402 -------------
403 OPTIONAL
404 (uint = 0,1,2, default = 0)
406 If 0, no positivity forcing will be made. If 1, force returned PDF values to be
407 positive (always > 0), to avoid accidental interpolation overshoots into
408 negative values. If 2, force returned PDF values to be positive definite (always
409 > 1e-10), to avoid both negative values and *also* ensure that the PDF is never
410 exactly 0, to avoid issues with reweighting.
413 Note
414 ----
415 OPTIONAL
416 (str)
418 An important short piece of usage information about this PDF set. Only use it
419 exceptionally, e.g. for marking that a PDF set is deprecated and users should
420 avoid it. The note will be printed into the online PDF table, and possibly used
421 by other external programs, but does not affect normal runtime behaviour.
425 MEMBER LEVEL
426 ============
428 @note The flags listed here are simply most *likely* to be used at member-level,
429 but they can also be set at the set or global config level if so desired. This
430 tends not to make sense for most of the flags listed here, however. Flags set at
431 a more specific level always take precedence.
433 Format
434 ------
435 MANDATORY
436 (enum string): lhagrid1, ... the trailing number is for format versioning.
438 Used to determine what parser should be instantiated to read the member file(s).
441 PdfDesc
442 -------
443 OPTIONAL
444 (free string): Description of the role of this PDF member
447 PdfType
448 -------
449 MANDATORY
450 (enum string): 'central' or 'error' or 'replica'
452 The type of this PDF, i.e. is it a central (canonical) PDF or is it meant for
453 use as either a Hessian error or a replica member of a statistical ensemble.
454 Parameter variation members given at the end of a set should have type 'central'.
456 */