Use convolute instead of convolve

README.md

@@ -12,7 +12,7 @@ This repository contains programs, libraries and interfaces to read and write
 coupling].
 
 PineAPPL grids are generated by Monte Carlo generators, and the grids in turn
-can be convoluted with PDFs to produce tables and plots, such as the following
+can be convolved with PDFs to produce tables and plots, such as the following
 one:
 
 ![plot](docs/NNPDF_DY_14TEV_40_PHENO.jpeg)

docs/cli-reference.md

@@ -32,7 +32,7 @@ order (`a2`) and the next-to-leading order QCD (`a2as1`).
 ## `PDFSET`: Specifying PDF members or entire PDF sets
 
 The parameter `PDFSET` that appears for all convolutional-type subcommands
-(`channels`, `convolute`, etc.) must be one of the following strings:
+(`channels`, `convolve`, etc.) must be one of the following strings:
 
 - `setname/member`: In this case `setname` must be a valid [LHAPDF] set name
   and `member` must be the member index. The index `0` denotes the central PDF,

docs/installation.md

@@ -168,16 +168,16 @@ inside it.
 ### Man pages
 
 Most of PineAPPL's help is available as `pineappl --help` and as `pineappl
-convolute --help`, for example. However, the same information can also be
+convolve --help`, for example. However, the same information can also be
 installed as man pages, which can then be used as either
 
     man pineappl
-    man pineappl-convolute
+    man pineappl-convolve
 
 or
 
     pineappl help
-    pineappl help convolute
+    pineappl help convolve
 
 For this to work first install the [CLI](#cli-pineappl-for-your-shell). Next,
 go to your local copy of PineAPPL's repository and create the man page

docs/interpolation-grids.md

@@ -4,9 +4,9 @@ This document explains what interpolation grids are and what PineAPPL is.
 
 ## What are interpolation grids?
 
-Interpolation grids store theoretical predictions that are not convoluted with
+Interpolation grids store theoretical predictions that are not convolved with
 PDFs yet. After the predictions have been generated once, the grids can be
-convoluted with arbitrary PDFs in a fraction of a second. This is very
+convolved with arbitrary PDFs in a fraction of a second. This is very
 advantageous for the following applications:
 
 - *PDF set dependence* of a prediction. Are the predictions with CT18, MSHT20

examples/cpp/Makefile

@@ -8,7 +8,7 @@ PROGRAMS = \
 	fill-custom-grid \
 	advanced-convolution \
 	advanced-filling \
-	convolute-grid \
+	convolve-grid \
 	display-channels \
 	display-orders \
 	merge-grids \
@@ -25,7 +25,7 @@ advanced-convolution: advanced-convolution.cpp
 advanced-filling: advanced-filling.cpp
 	$(CXX) $(CXXFLAGS) $< $(PINEAPPL_DEPS) -o $@
 
-convolute-grid: convolute-grid.cpp
+convolve-grid: convolve-grid.cpp
 	$(CXX) $(CXXFLAGS) $< $(LHAPDF_DEPS) $(PINEAPPL_DEPS) -o $@
 
 display-channels: display-channels.cpp

examples/cpp/advanced-convolution.cpp

@@ -78,10 +78,10 @@ int main(int argc, char* argv[]) {
     // `xfx1` and `alphas` are *proton* PDFs. If the grid contains cross sections of either a
     // proton-proton, proton-antiproton or antiproton-antiproton collision PineAPPL will perform the
     // necessary charge conjugations to yield the correct convolutions
-    pineappl_grid_convolute_with_one(grid, 2212, xfx1, alphas, pdf, order_mask.get(),
+    pineappl_grid_convolve_with_one(grid, 2212, xfx1, alphas, pdf, order_mask.get(),
         channel_mask.get(), xir, xif, dxsec1.data());
 
-    // how does the grid know which PDFs it must be convoluted with? This is determined by the
+    // how does the grid know which PDFs it must be convolved with? This is determined by the
     // metadata keys `initial_state_1` and `initial_state_2`, which are by default set to `2212`,
     // the PDG MC ID for the proton. Let's change the second value to an antiproton:
     pineappl_grid_set_key_value(grid, "initial_state_2", "-2212");
@@ -90,8 +90,8 @@ int main(int argc, char* argv[]) {
 
     // this calculates the corresponding proton-antiproton differential cross sections. Since the
     // grid itself is unchanged, this change effectively means that for the second PDF the charge
-    // convoluted PDFs are used
-    pineappl_grid_convolute_with_one(grid, 2212, xfx1, alphas, pdf, order_mask.get(),
+    // convolved PDFs are used
+    pineappl_grid_convolve_with_one(grid, 2212, xfx1, alphas, pdf, order_mask.get(),
         channel_mask.get(), xir, xif, dxsec2.data());
 
     // what if we have a collision where we actually need two PDFs? Let's simulate the collision of
@@ -102,13 +102,13 @@ int main(int argc, char* argv[]) {
 
     // For proton-deuteron collisions we can't easily relate the PDFs and have to actually pass two
     // different PDFs, each with their ID of the particle they represent:
-    pineappl_grid_convolute_with_two(grid, 2212, xfx1, 1000010020, xfx2, alphas, pdf,
+    pineappl_grid_convolve_with_two(grid, 2212, xfx1, 1000010020, xfx2, alphas, pdf,
         order_mask.get(), channel_mask.get(), xir, xif, dxsec3.data());
 
     std::vector<double> dxsec4(bins);
 
     // test with both masks set to `nullptr`
-    pineappl_grid_convolute_with_two(grid, 2212, xfx1, 1000010020, xfx2, alphas, pdf, nullptr,
+    pineappl_grid_convolve_with_two(grid, 2212, xfx1, 1000010020, xfx2, alphas, pdf, nullptr,
         nullptr, xir, xif, dxsec4.data());
 
     std::vector<double> normalizations(bins);

examples/cpp/convolute-grid.cpp → examples/cpp/convolve-grid.cpp

@@ -68,11 +68,11 @@ int main(int argc, char* argv[]) {
     // parameter. The integer `2212` is the PDG MC id for a proton and signals and `xfx` is the PDF
     // of a proton. In this case we assume that both initial state hadrons' PDFs can derived from
     // that of a proton. If this isn't the case, for instance for a proton-lead collision, both PDFs
-    // must be given separately and the function `pineappl_grid_convolute_with_two` must be used.
+    // must be given separately and the function `pineappl_grid_convolve_with_two` must be used.
     // The parameters `order_mask` and `channel_mask` can be used to select specific orders and
     // channels, respectively. Using `xir` and `xif` the renormalization and factorization scales
     // can be varied around its central values, respectively.
-    pineappl_grid_convolute_with_one(grid, 2212, xfx, alphas, pdf, order_mask,
+    pineappl_grid_convolve_with_one(grid, 2212, xfx, alphas, pdf, order_mask,
         channel_mask, xir, xif, dxsec.data());
 
     std::vector<double> normalizations(bins);

examples/cpp/fill-grid.cpp

@@ -203,7 +203,7 @@ int main() {
     // determine the subgrid which are being filled
     pineappl_keyval_set_string(keyval, "subgrid_type", "LagrangeSubgrid");
 
-    // set the PDG ids of hadrons whose PDFs should be used to convolute the grid with
+    // set the PDG ids of hadrons whose PDFs should be used to convolve the grid with
     pineappl_keyval_set_string(keyval, "initial_state_1", "2212");
     pineappl_keyval_set_string(keyval, "initial_state_2", "2212");
 
@@ -249,7 +249,7 @@ int main() {
 
     std::cout << "Generated " << filename << " containing a a -> l+ l-.\n\n"
         "Try running (PDF sets must contain non-zero photon PDF):\n"
-        "  - pineappl convolute " << filename << " NNPDF31_nnlo_as_0118_luxqed\n"
+        "  - pineappl convolve " << filename << " NNPDF31_nnlo_as_0118_luxqed\n"
         "  - pineappl --silence-lhapdf plot " << filename
         << " NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py\n"
         "  - pineappl --help\n";

examples/cpp/output

@@ -1,13 +1,13 @@
 Generated drell-yan-rap-ll.pineappl.lz4 containing a a -> l+ l-.
 
 Try running (PDF sets must contain non-zero photon PDF):
-  - pineappl convolute drell-yan-rap-ll.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed
+  - pineappl convolve drell-yan-rap-ll.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed
   - pineappl --silence-lhapdf plot drell-yan-rap-ll.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
   - pineappl --help
 Generated drell-yan-rap-ll-custom-grid.pineappl.lz4 containing a a -> l+ l-.
 
 Try running (PDF sets must contain non-zero photon PDF):
-  - pineappl convolute drell-yan-rap-ll-custom-grid.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed
+  - pineappl convolve drell-yan-rap-ll-custom-grid.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed
   - pineappl --silence-lhapdf plot drell-yan-rap-ll-custom-grid.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
   - pineappl --help
 idx  p-p c#0 l#0 p-p~ c#0 l#  p-d c#0 l#0       p-d       dx

examples/fortran/dyaa.f90

@@ -113,7 +113,7 @@ program dyaa
     print *, 'Generated DY-LO-AA.pineappl.lz4 containing a a -> l+ l-.'
     print *, ''
     print *, 'Try running (PDF sets must contain non-zero photon PDF):'
-    print *, '  - pineappl convolute DY-LO-AA.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed'
+    print *, '  - pineappl convolve DY-LO-AA.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed'
     print *, '  - pineappl --silence-lhapdf plot DY-LO-AA.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py'
     print *, '  - pineappl --help'
 

examples/fortran/lhapdf_example.f90

@@ -27,19 +27,19 @@ program lhapdf_example
     call lhapdf_initpdfset_byname(0, "nCTEQ15_1_1")
     call lhapdf_initpdfset_byname(1, "nCTEQ15FullNuc_208_82")
 
-    ! calling pineappl_grid_convolute without any flags
+    ! calling pineappl_grid_convolve without any flags
     xfx => xfx_test1
     alphas => alphas_test1
-    write(*, *) "first pineappl_grid_convolute_with_one: "
-    write(*, *) pineappl_grid_convolute_with_one(grid, 2212, xfx, alphas, &
+    write(*, *) "first pineappl_grid_convolve_with_one: "
+    write(*, *) pineappl_grid_convolve_with_one(grid, 2212, xfx, alphas, &
         [.true., .true.], [.true., .true.], 1.0_dp, 1.0_dp)
 
-    ! calling pineappl_grid_convolute with two integer flags that are used in xfx_test2 and alphas_test2 to determine the set and member indices
+    ! calling pineappl_grid_convolve with two integer flags that are used in xfx_test2 and alphas_test2 to determine the set and member indices
     xfx => xfx_test2
     alphas => alphas_test2
     flags = [1, 0]
-    write(*, *) "second pineappl_grid_convolute_with_one: "
-    write(*, *) pineappl_grid_convolute_with_one(grid, 2212, xfx, alphas, &
+    write(*, *) "second pineappl_grid_convolve_with_one: "
+    write(*, *) pineappl_grid_convolve_with_one(grid, 2212, xfx, alphas, &
         [.true., .true.], [.true., .true.], 1.0_dp, 1.0_dp, c_loc(flags(1)))
 contains
 

examples/fortran/pineappl.f90

@@ -85,8 +85,8 @@ type (c_ptr) function grid_clone(grid) bind(c, name = 'pineappl_grid_clone')
             type (c_ptr), value :: grid
         end function
 
-        subroutine grid_convolute_with_one(grid, pdg_id, xfx, alphas, state, order_mask, lumi_mask, xi_ren, xi_fac, results) &
-            bind(c, name = 'pineappl_grid_convolute_with_one')
+        subroutine grid_convolve_with_one(grid, pdg_id, xfx, alphas, state, order_mask, lumi_mask, xi_ren, xi_fac, results) &
+            bind(c, name = 'pineappl_grid_convolve_with_one')
             use iso_c_binding
             type (c_ptr), value        :: grid, state
             integer (c_int32_t), value :: pdg_id
@@ -96,8 +96,8 @@ subroutine grid_convolute_with_one(grid, pdg_id, xfx, alphas, state, order_mask,
             real (c_double)            :: results(*)
         end subroutine
 
-        subroutine grid_convolute_with_two(grid, pdg_id1, xfx1, pdg_id2, xfx2, alphas, state, order_mask, lumi_mask, &
-            xi_ren, xi_fac, results) bind(c, name = 'pineappl_grid_convolute_with_two')
+        subroutine grid_convolve_with_two(grid, pdg_id1, xfx1, pdg_id2, xfx2, alphas, state, order_mask, lumi_mask, &
+            xi_ren, xi_fac, results) bind(c, name = 'pineappl_grid_convolve_with_two')
             use iso_c_binding
             type (c_ptr), value        :: grid, state
             integer (c_int32_t), value :: pdg_id1, pdg_id2
@@ -437,7 +437,7 @@ type (pineappl_grid) function pineappl_grid_clone(grid)
         pineappl_grid_clone = pineappl_grid(grid_clone(grid%ptr))
     end function
 
-    function pineappl_grid_convolute_with_one(grid, pdg_id, xfx, alphas, order_mask, lumi_mask, xi_ren, xi_fac, state) result(res)
+    function pineappl_grid_convolve_with_one(grid, pdg_id, xfx, alphas, order_mask, lumi_mask, xi_ren, xi_fac, state) result(res)
         use iso_c_binding
 
         implicit none
@@ -469,13 +469,13 @@ function pineappl_grid_convolute_with_one(grid, pdg_id, xfx, alphas, order_mask,
             state_ = c_null_ptr
         end if
 
-        call grid_convolute_with_one(grid%ptr, pdg_id, c_funloc(xfx), c_funloc(alphas), state_, &
+        call grid_convolve_with_one(grid%ptr, pdg_id, c_funloc(xfx), c_funloc(alphas), state_, &
             [(logical(order_mask(i), c_bool), i = 1, size(order_mask))], &
             [(logical(lumi_mask(i), c_bool), i = 1, size(lumi_mask))], &
             xi_ren, xi_fac, res)
     end function
 
-    function pineappl_grid_convolute_with_two(grid, pdg_id1, xfx1, pdg_id2, xfx2, alphas, &
+    function pineappl_grid_convolve_with_two(grid, pdg_id1, xfx1, pdg_id2, xfx2, alphas, &
         order_mask, lumi_mask, xi_ren, xi_fac, state) result(res)
         use iso_c_binding
 
@@ -510,7 +510,7 @@ function pineappl_grid_convolute_with_two(grid, pdg_id1, xfx1, pdg_id2, xfx2, al
             state_ = c_null_ptr
         end if
 
-        call grid_convolute_with_two(grid%ptr, pdg_id1, c_funloc(xfx1), pdg_id2, c_funloc(xfx2), c_funloc(alphas), state_, &
+        call grid_convolve_with_two(grid%ptr, pdg_id1, c_funloc(xfx1), pdg_id2, c_funloc(xfx2), c_funloc(alphas), state_, &
             [(logical(order_mask(i), c_bool), i = 1, size(order_mask))], &
             [(logical(lumi_mask(i), c_bool), i = 1, size(lumi_mask))], &
             xi_ren, xi_fac, res)

examples/fortran/test.f90

@@ -136,18 +136,18 @@ program test_pineappl
     xfx2 => xfx2_test
     alphas => alphas_test
 
-    result = pineappl_grid_convolute_with_one(grid, 2212, xfx1, alphas, &
+    result = pineappl_grid_convolve_with_one(grid, 2212, xfx1, alphas, &
         [.true., .true.], [.true., .true.], 1.0_dp, 1.0_dp)
     if (any(result > 0 .neqv. [.true., .true., .false.])) then
-        write(*, *) "pineappl_grid_convolute_with_one(): ", result
-        error stop "error: pineappl_grid_convolute_with_one"
+        write(*, *) "pineappl_grid_convolve_with_one(): ", result
+        error stop "error: pineappl_grid_convolve_with_one"
     end if
 
-    result = pineappl_grid_convolute_with_two(grid, 2212, xfx1, 2212, xfx2, alphas, &
+    result = pineappl_grid_convolve_with_two(grid, 2212, xfx1, 2212, xfx2, alphas, &
         [.true., .true.], [.true., .true.], 1.0_dp, 1.0_dp)
     if (any(result < 0 .neqv. [.true., .true., .false.])) then
-        write(*, *) "pineappl_grid_convolute_with_two(): ", result
-        error stop "error: pineappl_grid_convolute_with_two"
+        write(*, *) "pineappl_grid_convolve_with_two(): ", result
+        error stop "error: pineappl_grid_convolve_with_two"
     end if
 
     call pineappl_keyval_delete(key_vals)

examples/object-oriented-cpp/dyaa.cpp

@@ -124,7 +124,7 @@ int main() {
 
     // perform a convolution of the grid with PDFs
     std::unique_ptr<LHAPDF::PDF> pdf (LHAPDF::mkPDF("NNPDF31_nlo_as_0118_luxqed", 0));
-    std::vector<double> dxsec = grid.convolute_with_one(2212, *pdf.get());
+    std::vector<double> dxsec = grid.convolve_with_one(2212, *pdf.get());
 
     // print the results
     for (std::size_t j = 0; j != dxsec.size(); ++j) {
@@ -144,7 +144,7 @@ int main() {
 
     std::printf("Generated %s containing a a -> l+ l-.\n\n"
         "Try running (PDF sets must contain non-zero photon PDF):\n"
-        "  - pineappl convolute %s NNPDF31_nnlo_as_0118_luxqed\n"
+        "  - pineappl convolve %s NNPDF31_nnlo_as_0118_luxqed\n"
         "  - pineappl --silence-lhapdf plot %s NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py\n"
         "  - pineappl --help\n", filename.c_str(), filename.c_str(), filename.c_str());
 }

examples/python/dyaa.py

@@ -159,7 +159,7 @@ def main(calls, pdfname, filename):
         pdf = lhapdf.mkPDF(pdfname, 0)
         pdg_id = int(pdf.set().get_entry('Particle'))
         # perform convolution
-        dxsec = grid.convolute_with_one(pdg_id, pdf.xfxQ2, pdf.alphasQ2)
+        dxsec = grid.convolve_with_one(pdg_id, pdf.xfxQ2, pdf.alphasQ2)
         for i in range(len(dxsec)):
             print(f"{bins[i]:.1f} {bins[i + 1]:.1f} {dxsec[i]:.3e}")
 

pineappl/src/empty_subgrid.rs

@@ -11,7 +11,7 @@ use std::iter;
 pub struct EmptySubgridV1;
 
 impl Subgrid for EmptySubgridV1 {
-    fn convolute(
+    fn convolve(
         &self,
         _: &[f64],
         _: &[f64],
@@ -82,7 +82,7 @@ mod tests {
     #[test]
     fn create_empty() {
         let mut subgrid = EmptySubgridV1;
-        assert_eq!(subgrid.convolute(&[], &[], &[], &mut |_, _, _| 0.0), 0.0,);
+        assert_eq!(subgrid.convolve(&[], &[], &[], &mut |_, _, _| 0.0), 0.0,);
         assert!(subgrid.is_empty());
         subgrid.merge(&mut EmptySubgridV1.into(), false);
         subgrid.scale(2.0);

pineappl/src/evolution.rs

@@ -45,12 +45,12 @@ pub struct EvolveInfo {
 ///
 /// The EKO may convert a `Grid` from a basis given by the particle identifiers [`pids1`] to a
 /// possibly different basis given by [`pids0`]. This basis must also be identified using
-/// [`lumi_id_types`], which tells [`FkTable::convolute`] how to perform a convolution. The members
+/// [`lumi_id_types`], which tells [`FkTable::convolve`] how to perform a convolution. The members
 /// [`ren1`] and [`alphas`] must be the strong couplings given at the respective renormalization
 /// scales. Finally, [`xir`] and [`xif`] can be used to vary the renormalization and factorization
 /// scales, respectively, around their central values.
 ///
-/// [`FkTable::convolute`]: super::fk_table::FkTable::convolute
+/// [`FkTable::convolve`]: super::fk_table::FkTable::convolve
 /// [`FkTable`]: super::fk_table::FkTable
 /// [`alphas`]: Self::alphas
 /// [`fac0`]: Self::fac0
@@ -104,7 +104,7 @@ pub struct OperatorInfo {
 /// The EKO slice may convert a `Grid` from a basis given by the particle identifiers `pids1` to a
 /// possibly different basis given by `pids0`. This basis must also be identified using
 /// [`lumi_id_types`](Self::lumi_id_types), which tells
-/// [`FkTable::convolute`](super::fk_table::FkTable::convolute) how to perform a convolution.
+/// [`FkTable::convolve`](super::fk_table::FkTable::convolve) how to perform a convolution.
 #[derive(Clone)]
 pub struct OperatorSliceInfo {
     /// Squared factorization scale of the `FkTable`.

pineappl/src/fk_table.rs

@@ -276,15 +276,16 @@ impl FkTable {
         self.grid.write_lz4(writer)
     }
 
-    /// Propagate convolute to grid
-    pub fn convolute(
+    /// Convolve the FK-table. This method has fewer arguments than [`Grid::convolve`], because
+    /// FK-tables have all orders merged together and do not support scale variations.
+    pub fn convolve(
         &self,
         lumi_cache: &mut LumiCache,
         bin_indices: &[usize],
         lumi_mask: &[bool],
     ) -> Vec<f64> {
         self.grid
-            .convolute(lumi_cache, &[], bin_indices, lumi_mask, &[(1.0, 1.0)])
+            .convolve(lumi_cache, &[], bin_indices, lumi_mask, &[(1.0, 1.0)])
     }
 
     /// Set a metadata key-value pair