Polish codes

pineappl/src/boc.rs

@@ -16,7 +16,7 @@ use std::str::FromStr;
 
 /// TODO
 #[repr(C)]
-#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize, Hash)]
 pub enum Kinematics {
     /// TODO
     Scale(usize),

pineappl/src/convolutions.rs

@@ -31,7 +31,7 @@ pub struct ConvolutionCache<'a> {
 }
 
 impl<'a> ConvolutionCache<'a> {
-    /// TODO
+    /// Constructor.
     pub fn new(
         convolutions: Vec<Conv>,
         xfx: Vec<&'a mut dyn FnMut(i32, f64, f64) -> f64>,
@@ -160,7 +160,8 @@ impl<'a> ConvolutionCache<'a> {
     }
 }
 
-/// TODO
+/// A cache for evaluating the full convolutions. Methods like [`Grid::convolve`] and
+/// [`FkTable::convolve`] calls this `struct`.
 pub struct GridConvCache<'a, 'b> {
     cache: &'b mut ConvolutionCache<'a>,
     perm: Vec<(usize, bool)>,
@@ -171,7 +172,7 @@ pub struct GridConvCache<'a, 'b> {
 }
 
 impl GridConvCache<'_, '_> {
-    /// TODO
+    /// Perform the convolution with the PDF(s) for a given channel entry of a subgrid.
     pub fn as_fx_prod(&mut self, pdg_ids: &[i32], as_order: u8, indices: &[usize]) -> f64 {
         // TODO: here we assume that
         // - indices[0] is the (squared) factorization scale,
@@ -280,7 +281,7 @@ impl GridConvCache<'_, '_> {
     }
 }
 
-/// TODO
+/// Defines the various types of convolutions.
 #[repr(C)]
 #[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
 pub enum ConvType {
@@ -295,7 +296,7 @@ pub enum ConvType {
 }
 
 impl ConvType {
-    /// TODO
+    /// Constructor.
     #[must_use]
     pub const fn new(polarized: bool, time_like: bool) -> Self {
         match (polarized, time_like) {
@@ -306,7 +307,7 @@ impl ConvType {
         }
     }
 
-    /// TODO
+    /// Check whether the current convolution is of type parton distribution function.
     #[must_use]
     pub const fn is_pdf(&self) -> bool {
         matches!(self, Self::UnpolPDF | Self::PolPDF)

pineappl/src/evolution.rs

@@ -215,7 +215,11 @@ fn ndarray_from_subgrid_orders_slice(
     alphas_table: &AlphasTable,
 ) -> Result<X1aX1bOpDTuple> {
     // TODO: remove these assumptions from the following code
-    assert_eq!(grid.kinematics()[0], Kinematics::Scale(0));
+    assert_eq!(
+        grid.kinematics()[0],
+        Kinematics::Scale(0),
+        "For the `Kinematics`, the scale must always go first."
+    );
     let x_start = grid
         .kinematics()
         .iter()

pineappl/src/fk_table.rs

@@ -107,10 +107,6 @@ impl FkTable {
         &self.grid
     }
 
-    // TODO: when trying to convert the following function to `const` as per clippy's suggestion,
-    // the compiler errors out with: 'the destructor for this type cannot be evaluated in constant
-    // functions'
-
     /// Converts the `FkTable` back to a [`Grid`].
     #[must_use]
     pub fn into_grid(self) -> Grid {
@@ -122,7 +118,9 @@ impl FkTable {
     ///
     /// # Panics
     ///
-    /// TODO
+    /// This function may panic in two cases: first when there is a mismatch between the `xgrid`
+    /// and the subgrid nodes, and second when the defined kinematic is not part of the `Kinematic`
+    /// object.
     #[must_use]
     pub fn table(&self) -> ArrayD<f64> {
         let x_grid = self.x_grid();

pineappl/src/grid.rs

@@ -19,16 +19,13 @@ use itertools::Itertools;
 use lz4_flex::frame::{FrameDecoder, FrameEncoder};
 use ndarray::{s, Array2, Array3, ArrayView3, ArrayViewMut3, Axis, CowArray, Dimension, Ix4, Zip};
 use serde::{Deserialize, Serialize};
-use std::collections::BTreeMap;
+use std::collections::{BTreeMap, HashMap};
 use std::io::{BufRead, BufReader, BufWriter, Read, Write};
 use std::ops::{Bound, RangeBounds};
 use std::{iter, mem};
 
 const BIN_AXIS: Axis = Axis(1);
 
-// const ORDER_AXIS: Axis = Axis(0);
-// const CHANNEL_AXIS: Axis = Axis(2);
-
 #[derive(Clone, Deserialize, Serialize)]
 struct Mmv4;
 
@@ -151,13 +148,13 @@ impl Grid {
         }
     }
 
-    /// TODO
+    /// Get the Monte Carlo reference for the given grid.
     #[must_use]
     pub const fn reference(&self) -> &Reference {
         &self.reference
     }
 
-    /// TODO
+    /// Set the Monte Carlo reference for the given grid.
     pub fn set_reference(&mut self, reference: Reference) {
         // TODO: check that the number of bins and channels is consistent between the grid and
         // `reference`
@@ -193,10 +190,6 @@ impl Grid {
     /// and `channel_mask`. A variation of the scales is performed using the factors in `xi`; the
     /// first factor varies the renormalization scale, the second the factorization scale. Note
     /// that for the variation to be trusted all non-zero log-grids must be contained.
-    ///
-    /// # Panics
-    ///
-    /// TODO
     pub fn convolve(
         &self,
         cache: &mut ConvolutionCache,
@@ -280,10 +273,6 @@ impl Grid {
     /// Fills the grid with an ntuple for the given `order`, `observable`, and `channel`. The
     /// parameter `ntuple` must contain the variables specified by the `kinematics` parameter in
     /// the constructor [`Grid::new`] in the same order.
-    ///
-    /// # Panics
-    ///
-    /// TODO
     pub fn fill(
         &mut self,
         order: usize,
@@ -439,12 +428,28 @@ impl Grid {
         Ok(())
     }
 
+    /// Check if two `Kinematics` objects are the same even in the case they are ordered
+    /// differently.
+    fn are_kinematics_equal(kin_a: &[Kinematics], kin_b: &[Kinematics]) -> bool {
+        let mut count_a = HashMap::new();
+        let mut count_b = HashMap::new();
+
+        for item in kin_a {
+            *count_a.entry(item).or_insert(0) += 1;
+        }
+        for item in kin_b {
+            *count_b.entry(item).or_insert(0) += 1;
+        }
+
+        count_a == count_b
+    }
+
     /// Merge non-empty `Subgrid`s contained in `other` into `self`. Subgrids with the same bin
     /// limits are summed and subgrids with non-overlapping bin limits create new bins in `self`.
     ///
     /// # Errors
     ///
-    /// If `self` and `other` in have different convolutions, PID bases, kinematics,
+    /// Raises an error if `self` and `other` have different convolutions, PID bases, kinematics,
     /// interpolations, or scales an error is returned. If the bin limits of `self` and `other`
     /// are different and if the bin limits of `other` cannot be merged with `self` an error is
     /// returned.
@@ -455,17 +460,16 @@ impl Grid {
         if self.pid_basis() != other.pid_basis() {
             return Err(Error::General("PID bases do not match".to_owned()));
         }
-        // TODO: relax check if kinematic variables are permutations of each other
-        if self.kinematics() != other.kinematics() {
-            return Err(Error::General("kinematics do not match".to_owned()));
-        }
         // TODO: relax check if subgrid types don't use interpolation
         if self.interpolations() != other.interpolations() {
             return Err(Error::General("interpolations do not match".to_owned()));
         }
         if self.scales() != other.scales() {
             return Err(Error::General("scales do not match".to_owned()));
         }
+        if !Self::are_kinematics_equal(self.kinematics(), other.kinematics()) {
+            return Err(Error::General("kinematics do not match".to_owned()));
+        }
 
         let mut new_orders: Vec<Order> = Vec::new();
         let mut new_bins = 0;
@@ -654,10 +658,6 @@ impl Grid {
     /// Scales each subgrid by a factor which is the product of the given values `alphas`, `alpha`,
     /// `logxir`, and `logxif`, each raised to the corresponding powers for each subgrid. In
     /// addition, every subgrid is scaled by a factor `global` independently of its order.
-    ///
-    /// # Panics
-    ///
-    /// TODO
     pub fn scale_by_order(
         &mut self,
         alphas: f64,
@@ -720,11 +720,12 @@ impl Grid {
         self.subgrids.view_mut()
     }
 
-    /// TODO
+    /// Set the bin with filled limits for the grid. This is used to redefine the bin specifications
+    /// and normalizations.
     ///
     /// # Errors
     ///
-    /// TODO
+    /// Raises an error if the length of the bins in the grid and in the redefinition are different.
     pub fn set_bwfl(&mut self, bwfl: BinsWithFillLimits) -> Result<()> {
         let bins = bwfl.len();
         let grid_bins = self.bwfl().len();
@@ -740,7 +741,7 @@ impl Grid {
         Ok(())
     }
 
-    /// TODO
+    /// Get the bin specifications for this grid.
     #[must_use]
     pub const fn bwfl(&self) -> &BinsWithFillLimits {
         &self.bwfl
@@ -993,10 +994,6 @@ impl Grid {
     }
 
     /// Return the metadata of this grid.
-    ///
-    /// # Panics
-    ///
-    /// TODO
     #[must_use]
     pub fn metadata_mut(&mut self) -> &mut BTreeMap<String, String> {
         &mut self.metadata