Minor changes (docs mostly)

ext/crates/fp/src/field/limb.rs

@@ -16,14 +16,14 @@ use crate::{
     limb::{Limb, LimbBitIndexPair},
 };
 
-/// Methods that lets us interact with the underlying `Limb` type.
+/// Methods that let us interact with the underlying `Limb` type.
 ///
 /// In practice this is an extension trait of a `Field`, so we treat it as such. We can't make it a
 /// supertrait of `Field` because `Field` is already a supertrait of `LimbMethods`.
 pub trait LimbMethods: Clone + Copy + Sized {
     type Element: FieldElement;
 
-    /// Encode a field element into a `Limb`. The limbs of an `FpVectorP<Self>` will consist of the
+    /// Encode a field element into a `Limb`. The limbs of an `FqVectorP<Self>` will consist of the
     /// coordinates of the vector, packed together using this method. It is assumed that the output
     /// value occupies at most `self.bit_length()` bits with the rest padded with zeros, and that
     /// the limb is reduced.
@@ -43,7 +43,14 @@ pub trait LimbMethods: Clone + Copy + Sized {
     /// reduced.
     fn fma_limb(self, limb_a: Limb, limb_b: Limb, coeff: Self::Element) -> Limb;
 
-    /// Return the `Limb` whose entries are the entries of `limb` reduced modulo `P`.
+    /// Reduce a limb, i.e. make it "canonical". For example, in [`Fp`](super::Fp), this replaces
+    /// every entry by its value modulo p.
+    ///
+    /// Many functions assume that the input limbs are reduced, but it's useful to allow the
+    /// existence of non-reduced limbs for performance reasons. Some functions like `fma_limb` can
+    /// be very quick compared to the reduction step, so finishing a computation by reducing all
+    /// limbs in sequence may allow the compiler to play some tricks with, for example, loop
+    /// unrolling and SIMD.
     fn reduce(self, limb: Limb) -> Limb;
 
     /// If `l` is a limb of `Self::Element`s, then `l & F.bitmask()` is the value of the
@@ -64,18 +71,15 @@ pub trait LimbMethods: Clone + Copy + Sized {
         }
     }
 
-    /// Check whether or not a limb is reduced, i.e. whether every entry is a value in the range `0..P`.
-    /// This is currently **not** faster than calling [`reduce`] directly.
+    /// Check whether or not a limb is reduced. This may potentially not be faster than calling
+    /// [`reduce`] directly.
     fn is_reduced(self, limb: Limb) -> bool {
         limb == self.reduce(limb)
     }
 
-    /// Given an interator of `Self::Element`s, pack all of them into a single limb in order.
-    /// It is assumed that
-    ///  - The values of the iterator are less than P
-    ///  - The values of the iterator fit into a single limb
-    ///
-    /// If these assumptions are violated, the result will be nonsense.
+    /// Given an interator of `Self::Element`s, pack all of them into a single limb in order. It is
+    /// assumed that the values of the iterator fit into a single limb. If this assumption is
+    /// violated, the result will be nonsense.
     fn pack<T: Iterator<Item = Self::Element>>(self, entries: T) -> Limb {
         let bit_length = self.bit_length();
         let mut result: Limb = 0;

ext/crates/fp/src/field/smallfq.rs

@@ -36,9 +36,8 @@ fn zech_logs<P: Prime>(fq: SmallFq<P>) -> Arc<ZechTable> {
             FpVector::from_slice(fq.characteristic(), &v)
         };
         let mul_by_a = |cur: FpVector| {
-            // Shift all entries to the right by one. We're assuming that cur is a polynomial
-            // representing an element of the field, so the leading coefficient is zero, and there
-            // is no overflow.
+            // Shift all entries up by one. We're assuming that cur is a polynomial representing an
+            // element of the field, so the top coefficient is zero, and there is no overflow.
             let mut next = FpVector::from_slice(
                 cur.prime(),
                 &std::iter::once(0)
@@ -64,7 +63,7 @@ fn zech_logs<P: Prime>(fq: SmallFq<P>) -> Arc<ZechTable> {
         }
 
         // Loop over all elements again, but now recording logarithms.
-        let table = HashMap::new();
+        let table = ZechTable::new();
         table.insert(fq.zero(), fq.one());
 
         let mut cur = FpVector::new(fq.characteristic(), conway_poly.len());
@@ -75,12 +74,12 @@ fn zech_logs<P: Prime>(fq: SmallFq<P>) -> Arc<ZechTable> {
                 cur_plus_1.add_basis_element(0, 1);
                 cur_plus_1
             };
-            cur = mul_by_a(cur);
-
             table.insert(
                 SmallFqElement(Some(i)),
                 SmallFqElement(poly_to_power.get(&cur_plus_1).as_deref().cloned()),
             );
+
+            cur = mul_by_a(cur);
         }
         Arc::new(table)
     });

ext/crates/fp/src/vector/impl_fpvectorp.rs

@@ -12,8 +12,7 @@ use crate::{
 };
 
 impl<F: Field> FqVectorP<F> {
-    pub fn new(fq: impl Into<F>, len: usize) -> Self {
-        let fq = fq.into();
+    pub fn new(fq: F, len: usize) -> Self {
         let number_of_limbs = fq.number(len);
         Self {
             fq,
@@ -27,8 +26,7 @@ impl<F: Field> FqVectorP<F> {
         Self { fq, len, limbs }
     }
 
-    pub fn new_with_capacity(fq: impl Into<F>, len: usize, capacity: usize) -> Self {
-        let fq = fq.into();
+    pub fn new_with_capacity(fq: F, len: usize, capacity: usize) -> Self {
         let mut limbs = Vec::with_capacity(fq.number(capacity));
         limbs.resize(fq.number(len), 0);
         Self { fq, len, limbs }

ext/crates/fp/src/vector/mod.rs

@@ -635,8 +635,8 @@ mod test {
     #[test]
     #[ignore]
     fn test_sign_rule() {
-        let mut in1 = FqVectorP::<Fp<P2>>::new(P2, 128);
-        let mut in2 = FqVectorP::<Fp<P2>>::new(P2, 128);
+        let mut in1 = FqVectorP::new(Fp(P2), 128);
+        let mut in2 = FqVectorP::new(Fp(P2), 128);
         let tests = [
             (
                 0x181e20846a820820,

ext/crates/fp/src/vector/vector_2.rs

@@ -19,11 +19,11 @@ use crate::{
 
 static F2: Fp<P2> = Fp(P2);
 
-pub type FpVector = FqVectorP<Fp<P2>>;
-pub type Slice<'a> = SliceP<'a, Fp<P2>>;
-pub type SliceMut<'a> = SliceMutP<'a, Fp<P2>>;
-pub type FpVectorIterator<'a> = FpVectorIteratorP<'a, Fp<P2>>;
-pub type FpVectorNonZeroIterator<'a> = FpVectorNonZeroIteratorP<'a, Fp<P2>>;
+pub type FpVector = FqVectorP<F2>;
+pub type Slice<'a> = SliceP<'a, F2>;
+pub type SliceMut<'a> = SliceMutP<'a, F2>;
+pub type FpVectorIterator<'a> = FpVectorIteratorP<'a, F2>;
+pub type FpVectorNonZeroIterator<'a> = FpVectorNonZeroIteratorP<'a, F2>;
 
 // `FpVector` implementations