Add more code comments to various ECC logic

ec/src/models/short_weierstrass_jacobian.rs

@@ -293,13 +293,13 @@ impl<P: Parameters> PartialEq for GroupProjective<P> {
         // The points (X, Y, Z) and (X', Y', Z')
         // are equal when (X * Z^2) = (X' * Z'^2)
         // and (Y * Z^3) = (Y' * Z'^3).
-        let z1 = self.z.square();
-        let z2 = other.z.square();
+        let z1z1 = self.z.square();
+        let z2z2 = other.z.square();
 
-        if self.x * &z2 != other.x * &z1 {
+        if self.x * &z2z2 != other.x * &z1z1 {
             false
         } else {
-            self.y * &(z2 * &other.z) == other.y * &(z1 * &self.z)
+            self.y * &(z2z2 * &other.z) == other.y * &(z1z1 * &self.z)
         }
     }
 }
@@ -399,6 +399,12 @@ impl<P: Parameters> ProjectiveCurve for GroupProjective<P> {
 
     #[inline]
     fn batch_normalization(v: &mut [Self]) {
+        // A projective curve element (x, y, z) is normalized
+        // to its affine representation, by the conversion
+        // (x, y, z) -> (x / z^2, y / z^3, 1)
+        // Batch normalizing N short-weierstrass curve elements costs:
+        //     1 inversion + 6N field multiplications + N field squarings    (Field ops)
+        // (batch inversion requires 3N multiplications + 1 inversion)
         let mut z_s = v.iter().map(|g| g.z).collect::<Vec<_>>();
         ark_ff::batch_inversion(&mut z_s);
 

ec/src/models/twisted_edwards_extended.rs

@@ -444,6 +444,12 @@ impl<P: Parameters> ProjectiveCurve for GroupProjective<P> {
     }
 
     fn batch_normalization(v: &mut [Self]) {
+        // A projective curve element (x, y, t, z) is normalized
+        // to its affine representation, by the conversion
+        // (x, y, t, z) -> (x/z, y/z, t/z, 1)
+        // Batch normalizing N twisted edwards curve elements costs:
+        //     1 inversion + 6N field multiplications
+        // (batch inversion requires 3N multiplications + 1 inversion)
         let mut z_s = v.iter().map(|g| g.z).collect::<Vec<_>>();
         ark_ff::batch_inversion(&mut z_s);
 

ec/src/msm/variable_base.rs

@@ -66,9 +66,19 @@ impl VariableBaseMSM {
                 });
 
                 // Compute sum_{i in 0..num_buckets} (sum_{j in i..num_buckets} bucket[j])
+                // This is computed below for b buckets, using 2b curve additions.
+                //
                 // We could first normalize `buckets` and then use mixed-addition
                 // here, but that's slower for the kinds of groups we care about
                 // (Short Weierstrass curves and Twisted Edwards curves).
+                // In the case of Short Weierstrass curves,
+                // mixed addition saves ~4 field multiplications per addition.
+                // However normalization (with the inversion batched) takes ~6
+                // field multiplications per element,
+                // hence batch normalization is a slowdown.
+
+                // `running_sum` = sum_{j in i..num_buckets} bucket[j],
+                // where we iterate backwords from i = num_buckets to 0
                 let mut running_sum = G::Projective::zero();
                 buckets.into_iter().rev().for_each(|b| {
                     running_sum += &b;