Refactor some internals of ff

ff/src/biginteger/mod.rs

@@ -1,7 +1,6 @@
 use crate::{
-    const_for,
-    fields::{BitIteratorBE, BitIteratorLE},
-    UniformRand,
+    bits::{BitIteratorBE, BitIteratorLE},
+    const_for, UniformRand,
 };
 #[allow(unused)]
 use ark_ff_macros::unroll_for_loops;

ff/src/bits.rs

@@ -0,0 +1,82 @@
+/// Iterates over a slice of `u64` in *big-endian* order.
+#[derive(Debug)]
+pub struct BitIteratorBE<Slice: AsRef<[u64]>> {
+    s: Slice,
+    n: usize,
+}
+
+impl<Slice: AsRef<[u64]>> BitIteratorBE<Slice> {
+    pub fn new(s: Slice) -> Self {
+        let n = s.as_ref().len() * 64;
+        BitIteratorBE { s, n }
+    }
+
+    /// Construct an iterator that automatically skips any leading zeros.
+    /// That is, it skips all zeros before the most-significant one.
+    pub fn without_leading_zeros(s: Slice) -> impl Iterator<Item = bool> {
+        Self::new(s).skip_while(|b| !b)
+    }
+}
+
+impl<Slice: AsRef<[u64]>> Iterator for BitIteratorBE<Slice> {
+    type Item = bool;
+
+    fn next(&mut self) -> Option<bool> {
+        if self.n == 0 {
+            None
+        } else {
+            self.n -= 1;
+            let part = self.n / 64;
+            let bit = self.n - (64 * part);
+
+            Some(self.s.as_ref()[part] & (1 << bit) > 0)
+        }
+    }
+}
+
+/// Iterates over a slice of `u64` in *little-endian* order.
+#[derive(Debug)]
+pub struct BitIteratorLE<Slice: AsRef<[u64]>> {
+    s: Slice,
+    n: usize,
+    max_len: usize,
+}
+
+impl<Slice: AsRef<[u64]>> BitIteratorLE<Slice> {
+    pub fn new(s: Slice) -> Self {
+        let n = 0;
+        let max_len = s.as_ref().len() * 64;
+        BitIteratorLE { s, n, max_len }
+    }
+
+    /// Construct an iterator that automatically skips any trailing zeros.
+    /// That is, it skips all zeros after the most-significant one.
+    pub fn without_trailing_zeros(s: Slice) -> impl Iterator<Item = bool> {
+        let mut first_trailing_zero = 0;
+        for (i, limb) in s.as_ref().iter().enumerate().rev() {
+            first_trailing_zero = i * 64 + (64 - limb.leading_zeros()) as usize;
+            if *limb != 0 {
+                break;
+            }
+        }
+        let mut iter = Self::new(s);
+        iter.max_len = first_trailing_zero;
+        iter
+    }
+}
+
+impl<Slice: AsRef<[u64]>> Iterator for BitIteratorLE<Slice> {
+    type Item = bool;
+
+    fn next(&mut self) -> Option<bool> {
+        if self.n == self.max_len {
+            None
+        } else {
+            let part = self.n / 64;
+            let bit = self.n - (64 * part);
+            self.n += 1;
+
+            Some(self.s.as_ref()[part] & (1 << bit) > 0)
+        }
+    }
+}

ff/src/fields/cyclotomic.rs

@@ -0,0 +1,123 @@
+/// Fields that have a cyclotomic multiplicative subgroup, and which can
+/// leverage efficient inversion and squaring algorithms for elements in this subgroup.
+/// If a field has multiplicative order p^d - 1, the cyclotomic subgroups refer to subgroups of order φ_n(p),
+/// for any n < d, where φ_n is the [n-th cyclotomic polynomial](https://en.wikipedia.org/wiki/Cyclotomic_polynomial).
+///
+/// ## Note
+///
+/// Note that this trait is unrelated to the `Group` trait from the `ark_ec` crate. That trait
+/// denotes an *additive* group, while this trait denotes a *multiplicative* group.
+pub trait CyclotomicMultSubgroup: crate::Field {
+    /// Is the inverse fast to compute? For example, in quadratic extensions, the inverse
+    /// can be computed at the cost of negating one coordinate, which is much faster than
+    /// standard inversion.
+    /// By default this is `false`, but should be set to `true` for quadratic extensions.
+    const INVERSE_IS_FAST: bool = false;
+
+    /// Compute a square in the cyclotomic subgroup. By default this is computed using [`Field::square`], but for
+    /// degree 12 extensions, this can be computed faster than normal squaring.
+    ///
+    /// # Warning
+    ///
+    /// This method should be invoked only when `self` is in the cyclotomic subgroup.
+    fn cyclotomic_square(&self) -> Self {
+        let mut result = *self;
+        *result.cyclotomic_square_in_place()
+    }
+
+    /// Square `self` in place. By default this is computed using
+    /// [`Field::square_in_place`], but for degree 12 extensions,
+    /// this can be computed faster than normal squaring.
+    ///
+    /// # Warning
+    ///
+    /// This method should be invoked only when `self` is in the cyclotomic subgroup.
+    fn cyclotomic_square_in_place(&mut self) -> &mut Self {
+        self.square_in_place()
+    }
+
+    /// Compute the inverse of `self`. See [`Self::INVERSE_IS_FAST`] for details.
+    /// Returns [`None`] if `self.is_zero()`, and [`Some`] otherwise.
+    ///
+    /// # Warning
+    ///
+    /// This method should be invoked only when `self` is in the cyclotomic subgroup.
+    fn cyclotomic_inverse(&self) -> Option<Self> {
+        let mut result = *self;
+        result.cyclotomic_inverse_in_place().copied()
+    }
+
+    /// Compute the inverse of `self`. See [`Self::INVERSE_IS_FAST`] for details.
+    /// Returns [`None`] if `self.is_zero()`, and [`Some`] otherwise.
+    ///
+    /// # Warning
+    ///
+    /// This method should be invoked only when `self` is in the cyclotomic subgroup.
+    fn cyclotomic_inverse_in_place(&mut self) -> Option<&mut Self> {
+        self.inverse_in_place()
+    }
+
+    /// Compute a cyclotomic exponentiation of `self` with respect to `e`.
+    ///
+    /// # Warning
+    ///
+    /// This method should be invoked only when `self` is in the cyclotomic subgroup.
+    fn cyclotomic_exp(&self, e: impl AsRef<[u64]>) -> Self {
+        let mut result = *self;
+        result.cyclotomic_exp_in_place(e);
+        result
+    }
+
+    /// Set `self` to be the result of exponentiating [`self`] by `e`,
+    /// using efficient cyclotomic algorithms.
+    ///
+    /// # Warning
+    ///
+    /// This method should be invoked only when `self` is in the cyclotomic subgroup.
+    fn cyclotomic_exp_in_place(&mut self, e: impl AsRef<[u64]>) {
+        if self.is_zero() {
+            return;
+        }
+
+        if Self::INVERSE_IS_FAST {
+            // We only use NAF-based exponentiation if inverses are fast to compute.
+            let naf = crate::biginteger::arithmetic::find_naf(e.as_ref());
+            exp_loop(self, naf.into_iter().rev())
+        } else {
+            exp_loop(
+                self,
+                crate::bits::BitIteratorBE::without_leading_zeros(e.as_ref()).map(|e| e as i8),
+            )
+        };
+    }
+}
+
+/// Helper function to calculate the double-and-add loop for exponentiation.
+fn exp_loop<F: CyclotomicMultSubgroup, I: Iterator<Item = i8>>(f: &mut F, e: I) {
+    // If the inverse is fast and we're using naf, we compute the inverse of the base.
+    // Otherwise we do nothing with the variable, so we default it to one.
+    let self_inverse = if F::INVERSE_IS_FAST {
+        f.cyclotomic_inverse().unwrap() // The inverse must exist because self is not zero.
+    } else {
+        F::one()
+    };
+    let mut res = F::one();
+    let mut found_nonzero = false;
+    for value in e {
+        if found_nonzero {
+            res.cyclotomic_square_in_place();
+        }
+
+        if value != 0 {
+            found_nonzero = true;
+
+            if value > 0 {
+                res *= &*f;
+            } else if F::INVERSE_IS_FAST {
+                // only use naf if inversion is fast.
+                res *= &self_inverse;
+            }
+        }
+    }
+    *f = res;
+}

ff/src/fields/fft_friendly.rs

@@ -0,0 +1,83 @@
+/// The interface for fields that are able to be used in FFTs.
+pub trait FftField: crate::Field {
+    /// The generator of the multiplicative group of the field
+    const GENERATOR: Self;
+
+    /// Let `N` be the size of the multiplicative group defined by the field.
+    /// Then `TWO_ADICITY` is the two-adicity of `N`, i.e. the integer `s`
+    /// such that `N = 2^s * t` for some odd integer `t`.
+    const TWO_ADICITY: u32;
+
+    /// 2^s root of unity computed by GENERATOR^t
+    const TWO_ADIC_ROOT_OF_UNITY: Self;
+
+    /// An integer `b` such that there exists a multiplicative subgroup
+    /// of size `b^k` for some integer `k`.
+    const SMALL_SUBGROUP_BASE: Option<u32> = None;
+
+    /// The integer `k` such that there exists a multiplicative subgroup
+    /// of size `Self::SMALL_SUBGROUP_BASE^k`.
+    const SMALL_SUBGROUP_BASE_ADICITY: Option<u32> = None;
+
+    /// GENERATOR^((MODULUS-1) / (2^s *
+    /// SMALL_SUBGROUP_BASE^SMALL_SUBGROUP_BASE_ADICITY)) Used for mixed-radix
+    /// FFT.
+    const LARGE_SUBGROUP_ROOT_OF_UNITY: Option<Self> = None;
+
+    /// Returns the root of unity of order n, if one exists.
+    /// If no small multiplicative subgroup is defined, this is the 2-adic root
+    /// of unity of order n (for n a power of 2).
+    /// If a small multiplicative subgroup is defined, this is the root of unity
+    /// of order n for the larger subgroup generated by
+    /// `FftConfig::LARGE_SUBGROUP_ROOT_OF_UNITY`
+    /// (for n = 2^i * FftConfig::SMALL_SUBGROUP_BASE^j for some i, j).
+    fn get_root_of_unity(n: u64) -> Option<Self> {
+        let mut omega: Self;
+        if let Some(large_subgroup_root_of_unity) = Self::LARGE_SUBGROUP_ROOT_OF_UNITY {
+            let q = Self::SMALL_SUBGROUP_BASE.expect(
+                "LARGE_SUBGROUP_ROOT_OF_UNITY should only be set in conjunction with SMALL_SUBGROUP_BASE",
+            ) as u64;
+            let small_subgroup_base_adicity = Self::SMALL_SUBGROUP_BASE_ADICITY.expect(
+                "LARGE_SUBGROUP_ROOT_OF_UNITY should only be set in conjunction with SMALL_SUBGROUP_BASE_ADICITY",
+            );
+
+            let q_adicity = crate::utils::k_adicity(q, n);
+            let q_part = q.checked_pow(q_adicity)?;
+
+            let two_adicity = crate::utils::k_adicity(2, n);
+            let two_part = 2u64.checked_pow(two_adicity)?;
+
+            if n != two_part * q_part
+                || (two_adicity > Self::TWO_ADICITY)
+                || (q_adicity > small_subgroup_base_adicity)
+            {
+                return None;
+            }
+
+            omega = large_subgroup_root_of_unity;
+            for _ in q_adicity..small_subgroup_base_adicity {
+                omega = omega.pow(&[q as u64]);
+            }
+
+            for _ in two_adicity..Self::TWO_ADICITY {
+                omega.square_in_place();
+            }
+        } else {
+            // Compute the next power of 2.
+            let size = n.next_power_of_two() as u64;
+            let log_size_of_group = ark_std::log2(usize::try_from(size).expect("too large"));
+
+            if n != size || log_size_of_group > Self::TWO_ADICITY {
+                return None;
+            }
+
+            // Compute the generator for the multiplicative subgroup.
+            // It should be 2^(log_size_of_group) root of unity.
+            omega = Self::TWO_ADIC_ROOT_OF_UNITY;
+            for _ in log_size_of_group..Self::TWO_ADICITY {
+                omega.square_in_place();
+            }
+        }
+        Some(omega)
+    }
+}