Merge pull request #169 from NNPDF/use_nnpdf_theory

Use nnpdf single-truth theory

.github/workflows/bench.yml

@@ -56,4 +56,4 @@ jobs:
           files: ./coverage.xml
           flags: bench
           name: codecov-umbrella
-          fail_ci_if_error: true
+          fail_ci_if_error: false

docs/source/overview/prerequisites.rst

@@ -18,57 +18,62 @@ This is a standard example:
   [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"
 
+  # 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`` will generate all necessary folders.
+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.
+"""""
+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]``).
+i.e., ``pineko`` should be installed with the ``nnpdf`` extra (``pip install pineko[nnpdf]``).
+
+Manual configuration
+""""""""""""""""""""
 
-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.
+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"
 
-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:
+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:
 
 ::
 
-  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
 ---------------------
@@ -121,7 +126,7 @@ generated by *pineko* itself starting from this default template.
 Grids
 -----
 
-*pineko* does **NOT** compute grids, which are instead expected input to *pineko*.
+*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
@@ -132,10 +137,4 @@ There are typically two ways to obtain grids:
     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
------
-
-.. [1] this is to be replaced by a binding to the NNPDF theory objects
+  (e.g. they may differ by scale variations, different DIS settings, etc.)

docs/source/overview/running.rst

@@ -95,3 +95,37 @@ With the command ``pineko compare`` it is possible to compare the predictions as
 
 again eventually specifying the values of *renormalization* and *factorization* scales with the
 appropriate options.
+
+Using pineko with NNPDF
+"""""""""""""""""""""""
+
+It is possible to use ``pineko`` without providing an explicit mapping between data and grids
+(i.e., without a ``yamldb`` database) or theory cards, by using the data declared in the NNPDF
+repository (which includes a data-theory mapping).
+
+In order to do this you need to install ``pineko`` with the ``nnpdf`` extra, which installs
+the latest version from the ``nnpdf`` repository::
+
+  pip install pineko[nnpdf]
+
+In order to enable ``pineko`` to read the data from ``nnpdf`` it is necessary to set up
+the ``general::nnpdf`` key in the configuration file.
+Note that if you do that, both ``theory_cards`` and ``ymldb`` keys become unnecessary,
+like in the example below.
+
+
+.. code-block:: yaml
+
+  [general]
+  nnpdf = true
+
+  [paths]
+  grids = "data/grids"
+  operator_card_template_name = "../_template.yaml"
+  operator_cards = "data/operator_cards"
+  ekos = "data/ekos"
+  fktables = "data/fktables"
+
+  [paths.logs]
+  eko = "logs/eko"
+  fk = "logs/fk"