Prerequisites

Generating a theory requires several files which are described next.

pineko.toml

You need to provide a pineko.toml, that provides all necessary paths to the input and output folders. This is a standard example:

[general]
nnpdf = true

[paths]
# inputs
grids = "data/grids"
theory_cards = "data/theory_cards"
operator_card_template_name = "_template.yaml"
# outputs
operator_cards = "data/operator_cards"
ekos = "data/ekos"
fktables = "data/fktables"

[paths.logs]
eko = "logs/eko"
fk = "logs/fk"

All the relevant inputs are described below. The command pineko scaffold new will generate all necessary folders.

nnpdf

The key nnpdf tells pineko it should use the data files from NNPDF to map datasets to FK Tables. If this key is given, a valid installation of nnpdf needs to be available as well. i.e, pineko should be installed with the nnpdf extra (pip install pineko[nnpdf]).

Alternatively, it is possible not to set this key (or set it to false) and instead provide a path with yaml files containing such dataset-FK mapping. If a custom database of mappings is to be used, the path to the folder containing this files needs to be explicitly provided:

[paths]
ymldb = "data/yamldb"

These yaml files (which should be named <dataset>.yaml) define a mapping from datasets to FK tables. An actual (rather simple) example is the following:

conversion_factor: 1.0
operands:
- - HERA_NC_318GEV_EP_SIGMARED
operation: 'null'
target_dataset: HERACOMBNCEP920

In operands all the necessary FK tables for the target_dataset are listed. In this case operation is NULL which means that the FK tables will just be concatenated but other kinds of operations can be used (for instance ratio).

Theory Runcards

You need to provide the necessary theory runcards named with their respective theory ID inside the paths.theory_cards folder [1]. For more details about theory runcards you can look at https://eko.readthedocs.io/en/latest/code/IO.html under Theory Runcards.

Default Operator Card

You need to provide a default operator card for EKO for each theory you want to use. An example is the following:

configs:
  evolution_method: truncated
  ev_op_max_order:
    - 10
    - 0
  ev_op_iterations: 1
  interpolation_polynomial_degree: 4
  interpolation_is_log: true
  scvar_method: None
  inversion_method: expanded
  polarized: False
  time_like: False
  n_integration_cores: 1
mu0: 1.65
mugrid:
  - - 50.0
    - 5
xgrid:
  - 1.9999999999999954e-07
  - 3.034304765867952e-07
  - 4.6035014748963906e-07
  - 6.984208530700364e-07
  - 1.0596094959101024e-06
  - 1.607585498470808e-06
  - 2.438943292891682e-06
  ...
  - 0.601472197967335
  - 0.6648139482473823
  - 0.7295868442414312
  - 0.7956242522922756
  - 0.8627839323906108
  - 0.9309440808717544
  - 1
debug:
  skip_non_singlet: false
  skip_singlet: false

For more details about what is needed inside an operator card please refer to https://eko.readthedocs.io/en/latest/code/IO.html under the section Operator Runcard. Note that the actual operator cards for each FK table will be generated by pineko itself starting from this default template.

Grids

pineko does NOT compute grids, which are instead expected input to pineko. There are typically two ways to obtain grids:

  1. computing them from scratch with pinefarm (and pinecards).

  2. You can reuse the grids from a different theory by running:

    pineko theory inherit-grids SOURCE_THEORY_ID TARGET_THEORY_ID DATASET1 DATASET2 ...
    

The relation between the source theory and the target theory is non-trivial (e.g. they may differ by scale variations, different DIS settings, etc)

Notes