kfactor maintenance and documentation

benchmarks/bench_cli.py

@@ -113,18 +113,15 @@ def benchmark_scaffold_cli(test_empty_proj):
     assert "Success: All the folders are correctly configured" in res.output
 
 
-def benchmark_gen_sv_cli(test_files, tmp_path, test_pdf, lhapdf_path):
+def benchmark_gen_sv_cli(test_files, tmp_path):
     runner = CliRunner()
-    pdf_name = "NNPDF40_nlo_as_01180"
     max_as = "2"
     nf = "5"
     name_grid = "ATLAS_TTB_8TEV_LJ_TRAP_norensv_fixed.pineappl.lz4"
     grid_path = test_files / "data" / "grids" / "400" / name_grid
     new_grid_path = tmp_path / name_grid
     target_path = tmp_path
     shutil.copy(grid_path, new_grid_path)
-    with lhapdf_path(test_pdf):
-        pdf = lhapdf.mkPDF(pdf_name)
     res = runner.invoke(
         command,
         ["ren_sv_grid", str(new_grid_path), str(target_path), max_as, nf, "False"],
@@ -137,7 +134,7 @@ def benchmark_kfactor_cli(test_files, tmp_path):
     grid_folder = test_files / "data" / "grids" / "400"
     kfolder = test_files / "data" / "kfactors"
     fake_yaml_path = test_files / "data" / "yamldb" / "ATLAS_TTB_FAKE.yaml"
-    max_as = "3"
+    ordr_to_update = "3"
     target_path = tmp_path
     res = runner.invoke(
         command,
@@ -147,8 +144,7 @@ def benchmark_kfactor_cli(test_files, tmp_path):
             str(kfolder),
             str(fake_yaml_path),
             str(target_path),
-            max_as,
-            "False",
+            ordr_to_update,
         ],
     )
-    assert "The number of bins match the lenght of the k-factor" in res.output
+    assert "The number of bins match the length of the kfactor" in res.output

benchmarks/bench_kfactor.py

@@ -7,13 +7,13 @@
 
 def benchmark_kfactor_inclusion(test_files, tmp_path, test_pdf, lhapdf_path):
     fake_yaml_path = test_files / "data" / "yamldb" / "ATLAS_TTB_FAKE.yaml"
-    max_as = 3
+    pto_to_update = 3  # here we want to update NNLO
     pdf_name = "NNPDF40_nnlo_as_01180"
-    kfactor.compute_k_factor_grid(
+    kfactor.apply_to_dataset(
         test_files / "data" / "grids" / "400",
         test_files / "data" / "kfactors",
         fake_yaml_path,
-        max_as,
+        pto_to_update,
         target_folder=tmp_path,
     )
     pluskfactor_grid_path = tmp_path / "ATLAS_TTB_8TEV_LJ_TRAP.pineappl.lz4"
@@ -46,7 +46,7 @@ def benchmark_kfactor_inclusion(test_files, tmp_path, test_pdf, lhapdf_path):
         np.array([], dtype=bool),
         sv_list,
     ).reshape(bin_number, len(sv_list))
-    centrals_kfactor, _ = kfactor.read_kfactor(
+    centrals_kfactor, _ = kfactor.read_from_file(
         test_files / "data" / "kfactors" / "CF_QCD_ATLAS_TTB_8TEV_LJ_TRAP.dat"
     )
     rtol = 1.0e-15

docs/source/overview/running.rst

@@ -63,7 +63,7 @@ handy utility functions:
 
 - applying the :doc:`FONLL prescription</theory/fonll>`
 - applying the :doc:`scale variation prescription</theory/scalevar>`
-- burning the :doc:`K-factor</theory/kfactors>` into grids
+- burning the :doc:`Kfactor</theory/kfactors>` into grids
 
 
 Checking the grids

docs/source/theory/kfactors.rst

@@ -1,11 +1,22 @@
-K-Factors
+Kfactors
 =========
 
 Another useful tool that `pineko` includes is ``pineko kfactor`` which allows the embedding of a kfactor
 as a proper order in a grid. The usage is the following::
 
-  pineko kfactor GRIDS_FOLDER KFACTOR_FOLDER YAMLDB_PATH TARGET_FOLDER MAX_AS ORDER_EXISTS
+  pineko kfactor GRIDS_FOLDER KFACTOR_FOLDER YAMLDB_FILE TARGET_FOLDER PTO_TO_UPDATE [--order_exists]
 
-where ``GRIDS_FOLDER`` is the folder containing the grids to update, ``KFACTOR_FOLDER`` is the folder
-containing the kfactor files and ``YAMLDB_PATH`` is the path to the yamldb file of the requested dataset.
-The other inputs have already been described in the previous section.
+where:
+
+- ``GRIDS_FOLDER`` is the folder containing the grids to update,
+- ``KFACTOR_FOLDER`` is the folder containing the kfactor files,
+- ``YAMLDB_FILE`` is the path to the yamldb file of the requested dataset,
+- ``TARGET_FOLDER`` is the folder where the new updated grids is going to be saved,
+- ``PTO_TO_UPDATE`` is the :math:`\alpha_s` perturbative order to update or create,
+  with the convention that ``LO=1``, ``NLO=2`` and so on, irrespectively to the powers of :math:`\alpha_s`.
+- ``--order_exists`` is a flag used to apply the kfactor to the specified perturbative order, insead of the next.
+
+Note that only pure QCD kfactors are taken into account.
+For example to add the NNLO in a grid containing at most NLO one has to select ``PTO_TO_UPDATE=2``;
+nn the other hand to reweight the NNLO present in a grid with a kfactor,
+one should do ``PTO_TO_UPDATE=2 --order_exists``.