add some docs and fix names

NNPDF · Mar 16, 2024 · c9d4c43 · c9d4c43
1 parent a4626f2
commit c9d4c43
Show file tree

Hide file tree

Showing 4 changed files with 33 additions and 24 deletions.
diff --git a/benchmarks/bench_kfactor.py b/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"
-    order_to_update = 3
+    pto_to_update = 3  # here we want to update NNLO
     pdf_name = "NNPDF40_nnlo_as_01180"
     kfactor.compute_k_factor_grid(
         test_files / "data" / "grids" / "400",
         test_files / "data" / "kfactors",
         fake_yaml_path,
-        order_to_update,
+        pto_to_update,
         target_folder=tmp_path,
     )
     pluskfactor_grid_path = tmp_path / "ATLAS_TTB_8TEV_LJ_TRAP.pineappl.lz4"

diff --git a/docs/source/theory/kfactors.rst b/docs/source/theory/kfactors.rst
@@ -4,8 +4,16 @@ K-Factors
 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.
+containing the kfactor files and ``YAMLDB_FILE`` is the path to the yamldb file of the requested dataset.
 The other inputs have already been described in the previous section.
+``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 alpha_s.
+Note that only pure QCD kfactors are taken into account.
+If the flag ``order_exists`` is passed the kfactor is applied to the specified perturbative order.
+
+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``.
diff --git a/src/pineko/cli/kfactor.py b/src/pineko/cli/kfactor.py
@@ -13,14 +13,14 @@
 @click.argument("kfactor_folder", type=click.Path(exists=True))
 @click.argument("yamldb_file", type=click.Path(exists=True))
 @click.argument("target_folder", type=click.Path(exists=True))
-@click.argument("order_to_update", type=int)
+@click.argument("pto_to_update", type=int)
 @click.option("--order_exists", is_flag=True, help="Owerwrite an existing order.")
 def k_factor_inclusion(
     grids_folder,
     kfactor_folder,
     yamldb_file,
     target_folder,
-    order_to_update,
+    pto_to_update,
     order_exists,
 ):
     """Construct new grid with k_factor included."""
@@ -32,7 +32,7 @@ def k_factor_inclusion(
         grids_folder,
         kfactor_folder,
         yamldb_file,
-        order_to_update,
+        pto_to_update,
         target_folder=target_folder,
         order_exists=order_exists,
     )
diff --git a/src/pineko/kfactor.py b/src/pineko/kfactor.py
@@ -93,11 +93,6 @@ def compute_scale_factor(
         index of the bin
     alphas: lhapdf.AlphaS
         alpha_s object
-
-    Returns
-    -------
-    float
-        full contribution factor
     """
     alpha_val = alphas.alphasQ2(mu2)
     max_as = order_to_update[0]
@@ -160,11 +155,9 @@ def construct_new_order(grid, order, order_to_update, central_kfactor, alphas):
     alphas : lhapdf.AlphaS
         alphas
     """
-
     # extract the relevant order to rescale from the grid for each lumi and bin
     grid_orders = [order.as_tuple() for order in grid.orders()]
 
-    # NOTE: eventual QED corrections are not supported
     new_grid = scale_variations.initialize_new_grid(grid, order_to_update)
     orginal_order_index = grid_orders.index(order)
 
@@ -200,7 +193,7 @@ def do_it(
     central_kfactor,
     alphas,
     grid,
-    order_to_update,
+    pto_to_update,
     target_grid_path,
     order_exists,
 ):
@@ -214,8 +207,9 @@ def do_it(
         alphas
     grid : pineappl.grid
         loaded grid
-    order_to_update : int
-        alpha_s order to update
+    pto_to_update : int
+        perturbative order to update: 1 = LO, 2 = NLO ...
+        no matter which power of alpha_s it is.
     target_grid_path: pathlib.Path
         path where store the new grid
     order_exists: bool
@@ -224,12 +218,16 @@ def do_it(
     grid_orders = [order.as_tuple() for order in grid.orders()]
 
     # remove not necessary orders
-    order_mask = pineappl.grid.Order.create_mask(grid.orders(), order_to_update, 0, True)
+    # NOTE: eventual QED corrections are not supported
+    order_mask = pineappl.grid.Order.create_mask(grid.orders(), pto_to_update, 0, True)
     grid_orders_filtered = list(np.array(grid_orders)[order_mask])
     grid_orders_filtered.sort(key=scale_variations.qcd)
     min_as = grid_orders_filtered[0][0]
     min_al = grid_orders_filtered[0][1]
 
+    # the actual alpha_s order to update
+    order_to_update = pto_to_update + min_as - 1
+
     # check if the order is already there
     is_in = is_already_in((order_to_update, min_al, 0, 0), grid_orders_filtered)
 
@@ -248,7 +246,9 @@ def do_it(
     order_to_update = (order_to_update, grid_orders_filtered[0][1], 0, 0)
     new_order_grid = None
     for i, as_order in enumerate(orders_list):
-        order_grid = construct_new_order(grid, as_order, order_to_update, central_kfactor, alphas)
+        order_grid = construct_new_order(
+            grid, as_order, order_to_update, central_kfactor, alphas
+        )
         if i == 0:
             new_order_grid = order_grid
         else:
@@ -309,7 +309,7 @@ def compute_k_factor_grid(
     grids_folder,
     kfactor_folder,
     yamldb_path,
-    order_to_update,
+    pto_to_update,
     target_folder=None,
     order_exists=False,
 ):
@@ -323,8 +323,9 @@ def compute_k_factor_grid(
         kfactors folder
     yamldb_path : pathlib.Path()
         path to the yaml file describing the dataset
-    order_to_update : int
-        alpha_s order to update
+    pto_to_update : int
+        perturbative order to update: 1 = LO, 2 = NLO ...
+        no matter which power of alpha_s it is.
     target_folder: pathlib.Path
         path where store the new grid
     order_exists: bool
@@ -340,7 +341,7 @@ def compute_k_factor_grid(
     for grid_list in yamldict["operands"]:
         # loop on grids
         for grid in grid_list:
-            # TODO: kfactor type should be passed as argument
+            # TODO: generalize for other type of kfactors ?
             cfac_path = kfactor_folder / f"CF_QCD_{grid}.dat"
             if "ATLASDY2D8TEV" in grid:
                 cfac_path = kfactor_folder / f"CF_QCDEWK_{grid}.dat"
@@ -356,7 +357,7 @@ def compute_k_factor_grid(
                 central_kfactor_filtered,
                 alphas,
                 current_grid,
-                order_to_update,
+                pto_to_update,
                 target_folder / grid_name,
                 order_exists,
             )