add more tests and comments

Author: lonerapier

src/field/gf_101_2.rs

@@ -27,7 +27,7 @@ impl<F: FiniteField> QuadraticExtensionField<F> {
   const D: usize = 2;
 
   /// irreducible polynomial used to reduce field polynomials to second degree:
-  /// F[X]/(X^2-K)
+  /// F[X]/(X^2-2)
   fn irreducible() -> F { F::from_canonical_u32(2) }
 }
 
@@ -56,8 +56,22 @@ impl<F: FiniteField> FiniteField for QuadraticExtensionField<F> {
 
   fn neg_one() -> Self { Self { value: [F::neg_one(), F::zero()] } }
 
-  fn generator() -> Self { Self { value: [F::from_canonical_u32(15), F::from_canonical_u32(20)] } }
+  // field generator: can be verified using sage script
+  // ```sage
+  // F = GF(101)
+  // Ft.<t> = F[]
+  // P = Ft(t ^ 2 - 2)
+  // F_2 = GF(101 ^ 2, name="t", modulus=P)
+  // f_2_primitive_element = F_2.primitive_element()
+  // ```
+  fn generator() -> Self {
+    // TODO: unsure if this is correct or not, research more
+    Self { value: [F::from_canonical_u32(15), F::from_canonical_u32(20)] }
+  }
 
+  /// Computes the multiplicative inverse of `a`, i.e. 1 / (a0 + a1 * t).
+  /// Multiply by `a0 - a1 * t` in numerator and denominator.
+  /// Denominator equals `(a0 + a1 * t) * (a0 - a1 * t) = a0.pow(2) - a1.pow(2) * Q::residue()`
   fn inverse(&self) -> Option<Self> {
     if *self == Self::zero() {
       return None;
@@ -109,6 +123,20 @@ impl<F: FiniteField> AddAssign for QuadraticExtensionField<F> {
   fn add_assign(&mut self, rhs: Self) { *self = self.clone() + rhs; }
 }
 
+impl<F: FiniteField> Add<F> for QuadraticExtensionField<F> {
+  type Output = Self;
+
+  fn add(self, rhs: F) -> Self::Output {
+    let mut res = self;
+    res.value[0] += rhs;
+    res
+  }
+}
+
+impl<F: FiniteField> AddAssign<F> for QuadraticExtensionField<F> {
+  fn add_assign(&mut self, rhs: F) { *self = *self + rhs; }
+}
+
 impl<F: FiniteField> Sub for QuadraticExtensionField<F> {
   type Output = Self;
 
@@ -126,6 +154,20 @@ impl<F: FiniteField> SubAssign for QuadraticExtensionField<F> {
   fn sub_assign(&mut self, rhs: Self) { *self = self.clone() - rhs; }
 }
 
+impl<F: FiniteField> Sub<F> for QuadraticExtensionField<F> {
+  type Output = Self;
+
+  fn sub(self, rhs: F) -> Self::Output {
+    let mut res = self;
+    res.value[0] -= rhs;
+    res
+  }
+}
+
+impl<F: FiniteField> SubAssign<F> for QuadraticExtensionField<F> {
+  fn sub_assign(&mut self, rhs: F) { *self = *self - rhs; }
+}
+
 impl<F: FiniteField> Sum for QuadraticExtensionField<F> {
   fn sum<I: Iterator<Item = Self>>(iter: I) -> Self {
     iter.reduce(|x, y| x + y).unwrap_or(Self::zero())
@@ -141,6 +183,8 @@ impl<F: FiniteField> Product for QuadraticExtensionField<F> {
 impl<F: FiniteField> Mul for QuadraticExtensionField<F> {
   type Output = Self;
 
+  /// Returns the multiplication of `a` and `b` using the following equation:
+  /// (a0 + a1 * t) * (b0 + b1 * t) = a0 * b0 + a1 * b1 * irreducible() + (a0 * b1 + a1 * b0) * t
   fn mul(self, rhs: Self) -> Self::Output {
     let a = self.value;
     let b = rhs.value;
@@ -155,6 +199,21 @@ impl<F: FiniteField> MulAssign for QuadraticExtensionField<F> {
   fn mul_assign(&mut self, rhs: Self) { *self = *self * rhs; }
 }
 
+impl<F: FiniteField> Mul<F> for QuadraticExtensionField<F> {
+  type Output = Self;
+
+  fn mul(self, rhs: F) -> Self::Output {
+    let mut res = self;
+    res.value[0] *= rhs;
+    res.value[1] *= rhs;
+    res
+  }
+}
+
+impl<F: FiniteField> MulAssign<F> for QuadraticExtensionField<F> {
+  fn mul_assign(&mut self, rhs: F) { *self = *self * rhs; }
+}
+
 impl<F: FiniteField> Div for QuadraticExtensionField<F> {
   type Output = Self;
 
@@ -224,6 +283,17 @@ mod tests {
     assert_eq!(x + y + z + x + y + z, [x, x, y, y, z, z].iter().cloned().sum());
   }
 
+  #[test]
+  fn test_pow() {
+    let mut rng = rand::thread_rng();
+    let x = F2::from_base(rng.gen::<F>());
+
+    assert_eq!(x, x.pow(<F2 as FiniteField>::Storage::from(1_u32)));
+
+    let res = x.pow(<F2 as FiniteField>::Storage::from(4_u32));
+    assert_eq!(res, x.square().square());
+  }
+
   #[test]
   fn test_inv_div() {
     let mut rng = rand::thread_rng();
@@ -240,4 +310,26 @@ mod tests {
     assert_eq!(x / (y * z), (x / y) / z);
     assert_eq!((x * y) / z, x * (y / z));
   }
+
+  #[test]
+  fn test_generator() {
+    assert_eq!(F2::generator() * F::from_canonical_u32(F::ORDER), F2::zero());
+  }
+
+  #[test]
+  fn test_add_sub_mul_subfield() {
+    let mut rng = rand::thread_rng();
+    let x = F2::from_base(rng.gen::<F>());
+    let y = rng.gen::<F>();
+
+    let add1 = x + y;
+    let sub1 = x - y;
+    let res = x * F::two();
+    assert_eq!(add1 + sub1, res);
+
+    let mul1 = x * y;
+    let inv_mul = x * y.inverse().unwrap();
+    let res = x.square();
+    assert_eq!(mul1 * inv_mul, res);
+  }
 }

src/field/mod.rs

@@ -70,8 +70,15 @@ pub trait FiniteField:
   }
 }
 
-/// A Finite field extension trait
-pub trait ExtensionField<Base: FiniteField>: FiniteField + From<Base> {
+pub trait ExtensionField<Base: FiniteField>:
+  FiniteField
+  + From<Base>
+  + Add<Base, Output = Self>
+  + AddAssign<Base>
+  + Sub<Base, Output = Self>
+  + SubAssign<Base>
+  + Mul<Base, Output = Self>
+  + MulAssign<Base> {
   const D: usize;
   fn irreducible() -> Base;
   fn from_base(b: Base) -> Self;