#############
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
  init:
    - 1.65
    - 4
  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:

1. computing them from scratch with
   `pinefarm <https://github.com/NNPDF/pinefarm/>`_ (and `pinecards <https://github.com/NNPDF/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.)