44Theory data files
55=================
66
7- In the ``nnpdf++ `` project, ``FK `` tables (or grids ) are used to provide the
7+ In the ``nnpdf `` framework, Fast Kernel tables ( ``FK `` tables for short ) are used to provide the
88information required to compute perturbative QCD cross sections in a compact fashion. With
99the ``FK `` method a typical hadronic observable data point :math: `\mathcal {O}`, is
1010computed as,
@@ -29,170 +29,23 @@ Additional information may be introduced via correction factors known internally
2929as :math: `C`-factors. These consist of data point by data point multiplicative
3030corrections to the final result of the ``FK `` convolution :math: `\mathcal {O}`. These
3131are provided by ``CFACTOR `` files, typical applications being the application
32- of NNLO and electroweak corrections. For processes which depend non-linearly
32+ of NNLO and electroweak corrections. For processes which depend non-linearly
3333upon PDFs, such as cross-section ratios or asymmetries, multiple FK tables may
34- be required for one observable. In this case information is provided in the form
35- of a ``COMPOUND `` file which specifies how the results from several ``FK ``
36- tables may be combined to produce the target observable. In this section we
37- shall specify the layout of the ``FK ``, ``COMPOUND `` and ``CFACTOR ``
38- files.
39-
40- FK table compression
41- --------------------
42-
43- It is important to note that the FK table format as described here pertains to
44- the *uncompressed * tables. Typically FK tables as found and read by the
45- NNPDF code are compressed individually with gzip.
34+ be required for one observable.
35+ In this case information is provided in the form of operations defined in the commondata file.
4636
4737``FK `` file format
48- ==================
49-
50- ``FK `` preamble layout
51- ----------------------
52-
53- The FK preamble is constructed by a set of data segments, of which there are two
54- configurations. The first configuration consists of a list of key-value pairs,
55- and the second is a simple data 'blob' with no requirements as to its
56- formatting. Each segment begins with a delineating line which for key-value pairs is
57-
58- _SegmentName_____________________________________________
59-
60- and for data blobs is
61-
62- {SegmentName_____________________________________________
63-
64- The key difference being in the first character, underscore (``_ ``) for
65- key-value pair segments, and open curly brace (``{ ``) for data blobs. The name of
66- the segment is specified from the second character, to a terminating
67- underscore (``_ ``). The line is then typically padded out with underscores up
68- to 60 characters. Following this delineating line, for a key-value segment, the
69- following lines must all be of the format
70-
71- *KEY: VALUE
72-
73- with the first character required to be an asterisk (``* ``), then specifying the
74- key, and value for that segment. For blob-type segments, no constraints are
75- placed upon the format, aside from that each line **must not ** begin with
76- one of the delineating characters ``{ `` or ``_ ``, as these will trigger the
77- construction of a new segment.
78-
79- While the user may specify additional segments, both key-value pair and
80- blob-type for their own use, there are seven segments required by the code.
81- These are, specified by their segment name:
82-
83- * **GridDesc ** [BLOB]
84-
85- This segment provides a 'banner' with a short description for the FK table. The contents of this banner are displayed when the table is read from file.
86-
87- * **VersionInfo ** [K-V]
88-
89- A list specifying the versions of the various pieces of code used in the generation of this FK table (minimally libnnpdf and apfel).
90-
91- * **GridInfo ** [K-V]
92-
93- This list specified various architectural points of the FK table. The required keys are specified in :ref: `fk_config_variables `.
94-
95- * **TheoryInfo ** [K-V]
96-
97- A list of all the theory parameters used in the generation of the table. The required keys are specified in :ref: `th_parameter_definitions `.
98-
99- * **FlavourMap ** [BLOB]
100-
101- The segment describes the flavour structure of the grid by means of a flavour
102- map. This map details which flavour channels are active in the grid, using the
103- basis specified :ref: `here<flavours> `. For DIS processes, an example
104- section would be
105-
106- | {FlavourMap_____________________________________________
107- | 0 1 1 0 0 0 0 0 0 0 1 0 0 0
108-
109- which specifies that only the Singlet, gluon and :math: `T_8 ` channels are populated in
110- the grid. In the case of hadronic FK tables, the full :math: `14 \times 14 ` flavour
111- combination matrix is specified in the same manner. Consider the flavourmap for
112- the CDFR2KT *Dataset *:
113-
114- | {FlavourMap_____________________________________________
115- | 0 0 0 0 0 0 0 0 0 0 0 0 0 0
116- | 0 1 1 0 0 0 0 0 0 0 0 0 0 0
117- | 0 1 1 0 0 0 0 0 0 0 0 0 0 0
118- | 0 0 0 1 0 0 0 0 0 0 0 0 0 0
119- | 0 0 0 0 1 0 0 0 0 0 0 0 0 0
120- | 0 0 0 0 0 1 0 0 0 0 0 0 0 0
121- | 0 0 0 0 0 0 0 0 0 0 0 0 0 0
122- | 0 0 0 0 0 0 0 0 0 0 0 0 0 0
123- | 0 0 0 0 0 0 0 0 0 0 0 0 0 0
124- | 0 0 0 0 0 0 0 0 0 1 0 0 0 0
125- | 0 0 0 0 0 0 0 0 0 0 1 0 0 0
126- | 0 0 0 0 0 0 0 0 0 0 0 0 0 0
127- | 0 0 0 0 0 0 0 0 0 0 0 0 0 0
128- | 0 0 0 0 0 0 0 0 0 0 0 0 0 0
129-
130- This flavourmap contains 9 nonzero entries, demonstrating the importance of only
131- computing those flavour combinations that are relevant to the process.
132- Additionally this map instructs the ``nnpdf++ `` convolution code as to which
133- elements of the FastKernel grid should be read, to minimise holding zero entries
134- in memory.
135-
136- * **xGrid ** [BLOB]
137-
138- This segment defines the :math: `x`-grid upon which the ``FK `` grid is defined,
139- given as an :math: `N_x` long list of the :math: `x`-grid points. This grid should be
140- optimised to minimise ``FK `` grid zeros in :math: `x`-space. The blob is a simple
141- list of the grid points, here is an example of an :math: `x`-grid with :math: `N_x=5 `
142- entries:
143-
144- | {xGrid_____________________________________________
145- | 0.10000000000000001
146- | 0.13750000000000001
147- | 0.17499999999999999
148- | 0.21250000000000002
149- | 1.00000000000000000
150-
151- For examples of complete DIS and hadronic ``FK `` table headers, see
152- :ref: `example_fk_preamble `.
153-
154- ``FK `` grid layout
15538------------------
15639
157- To start the section of the file with the ``FK `` grid itself, we begin with a
158- blob-type segment delineator:
159-
160- {FastKernel_____________________________________________
40+ The ``FK `` tables in NNPDF are pineappl grids convoluted with an EKO
41+ which in turns generates a new pineappl grid collapsed on couplings, scale and orders to speed up
42+ the calculation.
16143
162- The grid itself is now written out. For hadronic data, the format is line by line as follows:
44+ More information about the format of these files can be found in the ` pineappl docs < https://github.com/NNPDF/pineappl/blob/master/docs/README.md >`_.
16345
164- :math: `d \:\: \alpha \:\: \beta \:\: \sigma ^d_{\alpha\beta 1 1 } \:\: \sigma ^d_{\alpha\beta 1 2 }\:\: ....\:\: \sigma ^d_{\alpha\beta n n}`
165-
166- where :math: `d` is the index of the data point for that line, :math: `\alpha ` is the :math: `x`-index
167- of the first PDF, :math: `\beta ` is the :math: `x`-index of the second PDF, the
168- :math: `\sigma ^d_{\alpha\beta i j}` are the values of the FastKernel grid for data
169- point :math: `d` as in the equation :ref: `here<observable> `, and :math: `n=14 ` is the total number of parton
170- flavours in the grid. Therefore the full :math: `14 \times 14 ` flavour space for one
171- combination of the indices :math: `\{ d,\alpha ,\beta \}` is written out on each line.
172- These lines should be written out first in :math: `\beta `, then :math: `\alpha ` and finally
173- :math: `d` so that the ``FK `` grids are written in blocks of data points. All ``FK ``
174- grid values should be written out in double precision. For DIS data the ``FK ``
175- grids must be written out as
176-
177- :math: `d \:\: \alpha \:\: \sigma ^d_{\alpha 1 } \:\: \sigma ^d_{\alpha 2 }\:\: ....\:\: \sigma ^d_{\alpha n}`
178-
179- Therefore here all :math: `n=14 ` values are written out for each combination of :math: `\{ d,\alpha \}`.
180- When writing out the grids, note that only :math: `x`-grid points for which there are
181- nonzero ``FK `` entries are written out. For example, there should be no lines
182- such as:
183-
184- :math: `d \:\: \alpha \:\: \beta \:\: 0 \:\: 0 \:\: 0 \:\: .... \:\: 0 `
185-
186- However, for those :math: `x`-grid points which do have nonzero :math: `\sigma ` contributions,
187- the full set of flavour contributions must be written out regardless of the
188- number of zero entries. This choice was made in order that the nonzero flavour
189- entries may be examined/optimised by hand after the FK table is generated.
190-
191- The ``FK `` file should end on the last entry in the grid, and without empty
192- lines at the end of file.
19346
19447``CFACTOR `` file format
195- =======================
48+ -----------------------
19649
19750Additional multiplicative factors to be applied to the output of the ``FK ``
19851convolution may be introduced by the use of ``CFACTOR `` files. These files
@@ -241,22 +94,23 @@ where the :math:`i^{\text{th}}` line corresponds to the :math:`C`-factor to be a
24194the ``FK `` prediction for the :math: `(i-1 )^{\text {th}}` data point. The first column
24295denotes the value of the :math: `C`-factor and the second column denotes the
24396uncertainty upon it (in absolute terms, not as a percentage or otherwise
244- relative to the :math: `C`-factor). For a complete example of a ``CFACTOR `` file,
97+ relative to the :math: `C`-factor).
98+ Note that at this moment the uncertainty is not used during the fit.
99+ For a complete example of a ``CFACTOR `` file,
245100please see :ref: `example_cfactor_file `.
246101
247- ``COMPOUND `` file format
248- ========================
102+ ``FK `` Operations
103+ -----------------
249104
250105Some *Datasets * cover observables that depend non-linearly upon the input
251106PDFs. For example, the NMCPD *Dataset * is a measurement of the ratio of
252- deuteron to proton structure functions. In the ``nnpdf++ `` code such sets are
107+ deuteron to proton structure functions. In the ``nnpdf `` code such sets are
253108denoted *Compound Datasets *. In these cases, a prescription must be given for how the
254109results from FK convolutions, as in this :ref: `equation<observable> `, should be combined.
255110
256- The ``COMPOUND `` files are a simple method of providing this information. For
257- each *Compound Dataset * a ``COMPOUND `` file is provided that contains the
258- information on how to build the observable from constituent ``FK `` tables. The
259- following operations are currently implemented:
111+ The information on the opoeration which compounds the ``FK `` tables is provided in the
112+ metadata of the observables.
113+ The following operations are currently implemented:
260114
261115================================= ========= =================
262116Operation :math: `(N_{\text {FK}})` Code Output Observable
@@ -277,27 +131,23 @@ observable prediction for the :math:`d^{\text{th}}` point arising from the
277131:math: `i^{\text {th}}` ``FK `` table calculation. Note that here the ordering in :math: `i`
278132is important.
279133
280- The ``COMPOUND `` file layout is as so. The first line is once again a general
281- comment line and is not used by the code, and therefore has no particular
282- requirements other than its presence. Following this line should come a list of
283- the ``FK `` tables required for the calculation. This must be given as the
284- table's filename *without * its path, preceded by the string '**FK: **'. For example,
134+ The information about the composition is, as mentioned above, given in the ``theory ``
135+ entry of the datasets' metadata file.
136+ For instance:
285137
286- | FK: FK_SETNAME_1.dat
287- | FK: FK_SETNAME_2.dat
138+ | theory:
139+ | FK_tables:
140+ | - - FK_TABLE_BIN_1
141+ | - FK_TABLE_BIN_2
142+ | - - FK_TABLE_NORM
143+ | operation: "ratio"
288144
289- The ordering of the list is once again important, and must match the above
145+ In the above example, the entries `FK_TABLE_BIN_1 ` and `FK_TABLE_BIN_2 ` will be concatenated.
146+ The resulting concatenated table will then be divide (see above) by the `FK_TABLE_NORM `.
147+ The ordering of the list is important, and must match the above
290148table. For example, the observables :math: `\mathcal {O}^{(i)}` arise from the
291149computation with the :math: `i^{\text {th}}` element of this list. The final line
292150specified the operation to be performed upon the list of tables, and must take
293151the form
294152
295- OP: **[CODE] **
296-
297- where the **[CODE] ** is given in the above table. Here is an example of a
298- complete ``COMPOUND `` file
299-
300- | # COMPOUND FK
301- | FK: FK\_NUMERATOR.dat
302- | FK: FK\_DENOMINATOR.dat
303- | OP: RATIO
153+ operation: **[CODE] **
0 commit comments