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"
operator_card_template_name = "_template.yaml"
# outputs
operator_cards = "data/operator_cards"
ekos = "data/ekos"
fktables = "data/fktables"

# The following two keys are only necessary when nnpdf=false
#theory_cards = "data/theory_cards"
#ymldb = "data/yamldb"

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

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

Theory runcards and dataset definition

You need to provide the necessary theory runcards and the mapping between datasets and FK tables (as one dataset may consist several FK tables). For more details about theory runcards you can look at https://docs.nnpdf.science/theory/theoryparamsdefinitions.html

Both configuration can be either provided by the NNPDF framework or in a manual setup.

nnpdf

The key nnpdf tells pineko it should use the data files from NNPDF to map datasets to FK Tables and to define the theory parameters. 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]).

Manual configuration

Alternatively, it is possible to provide a path paths.theory_cards with yaml files containing the theory cards, and a path paths.ymldb with yaml files containing the 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"
theory_cards = "data/theory_cards"

The mapping from datasets to FK tables is provided by yaml files (which should be named <dataset>.yaml) and a simple example is the following:

operands:
- - HERA_NC_318GEV_EP_SIGMARED

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 as input to pineko. There are typically two ways to obtain grids:

computing them from scratch with pinefarm (and pinecards).

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.)