feanor_math/algorithms/fft/
cooley_tuckey.rs

1use std::alloc::{Allocator, Global};
2use std::ops::Range;
3use std::fmt::Debug;
4
5use crate::algorithms::unity_root::*;
6use crate::divisibility::{DivisibilityRingStore, DivisibilityRing};
7use crate::rings::zn::*;
8use crate::seq::SwappableVectorViewMut;
9use crate::ring::*;
10use crate::seq::VectorViewMut;
11use crate::homomorphism::*;
12use crate::algorithms::fft::*;
13use crate::rings::float_complex::*;
14use super::complex_fft::*;
15
16///
17/// An optimized implementation of the Cooley-Tukey FFT algorithm, to compute
18/// the Fourier transform of an array with power-of-two length.
19/// 
20/// # Example
21/// ```rust
22/// # use feanor_math::assert_el_eq;
23/// # use feanor_math::ring::*;
24/// # use feanor_math::algorithms::fft::*;
25/// # use feanor_math::rings::zn::*;
26/// # use feanor_math::algorithms::fft::cooley_tuckey::*;
27/// // this ring has a 256-th primitive root of unity
28/// let ring = zn_64::Zn::new(257);
29/// let fft_table = CooleyTuckeyFFT::for_zn(ring, 8).unwrap();
30/// let mut data = [ring.one()].into_iter().chain((0..255).map(|_| ring.zero())).collect::<Vec<_>>();
31/// fft_table.unordered_fft(&mut data, &ring);
32/// assert_el_eq!(ring, ring.one(), data[0]);
33/// assert_el_eq!(ring, ring.one(), data[1]);
34/// ```
35/// 
36/// # Convention
37/// 
38/// This implementation does not follows the standard convention for the mathematical
39/// DFT, by performing the standard/forward FFT with the inverse root of unity `z^-1`.
40/// In other words, the forward FFT computes
41/// ```text
42///   (a_0, ..., a_(n - 1)) -> (sum_j a_j z^(-ij))_i
43/// ```
44/// as demonstrated by
45/// ```rust
46/// # use feanor_math::assert_el_eq;
47/// # use feanor_math::ring::*;
48/// # use feanor_math::algorithms::fft::*;
49/// # use feanor_math::rings::zn::*;
50/// # use feanor_math::algorithms::fft::cooley_tuckey::*;
51/// # use feanor_math::homomorphism::*;
52/// # use feanor_math::divisibility::*;
53/// // this ring has a 4-th primitive root of unity
54/// let ring = zn_64::Zn::new(5);
55/// let root_of_unity = ring.int_hom().map(2);
56/// let fft_table = CooleyTuckeyFFT::new(ring, root_of_unity, 2);
57/// let mut data = [ring.one(), ring.one(), ring.zero(), ring.zero()];
58/// fft_table.fft(&mut data, ring);
59/// let inv_root_of_unity = ring.invert(&root_of_unity).unwrap();
60/// assert_el_eq!(ring, ring.add(ring.one(), inv_root_of_unity), data[1]);
61/// ```
62/// 
63/// # On optimizations
64/// 
65/// I tried my best to make this as fast as possible in general, with special focus
66/// on the Number-theoretic transform case. I did not implement the following
67/// optimizations, for the following reasons:
68///  - Larger butterflies: This would improve data locality, but decrease twiddle
69///    locality (or increase arithmetic operation count). Since I focused mainly on
70///    the `Z/nZ` case, where the twiddles are larger than the ring elements (since they
71///    have additional data to speed up multiplications), this is not sensible.
72///  - The same reasoning applies to a SplitRadix approach, which only actually decreases
73///    the total number of operations if multiplication-by-`i` is free.
74/// 
75pub struct CooleyTuckeyFFT<R_main, R_twiddle, H, A = Global> 
76    where R_main: ?Sized + RingBase,
77        R_twiddle: ?Sized + RingBase,
78        H: Homomorphism<R_twiddle, R_main>,
79        A: Allocator
80{
81    hom: H,
82    root_of_unity: R_main::Element,
83    log2_n: usize,
84    // stores the powers of `root_of_unity^-1` in special bitreversed order
85    root_of_unity_list: Vec<Vec<R_twiddle::Element>>,
86    // stores the powers of `root_of_unity` in special bitreversed order
87    inv_root_of_unity_list: Vec<Vec<R_twiddle::Element>>,
88    allocator: A,
89    two_inv: R_twiddle::Element,
90    n_inv: R_twiddle::Element
91}
92
93///
94/// Assumes that `index` has only the least significant `bits` bits set.
95/// Then computes the value that results from reversing the least significant `bits`
96/// bits.
97/// 
98pub fn bitreverse(index: usize, bits: usize) -> usize {
99    index.reverse_bits().checked_shr(usize::BITS - bits as u32).unwrap_or(0)
100}
101
102#[inline(never)]
103fn butterfly_loop<T, S, F>(log2_n: usize, data: &mut [T], butterfly_range: Range<usize>, stride_range: Range<usize>, log2_step: usize, twiddles: &[S], butterfly: F)
104    where F: Fn(&mut T, &mut T, &S) + Clone
105{
106    assert_eq!(1 << log2_n, data.len());
107    assert!(log2_step < log2_n);
108
109    // the coefficients of a group of inputs have this distance to each other
110    let stride = 1 << (log2_n - log2_step - 1);
111    assert!(stride_range.start <= stride_range.end);
112    assert!(stride_range.end <= stride);
113
114    // how many butterflies we compute within each group
115    assert!(butterfly_range.start <= butterfly_range.end);
116    assert!(butterfly_range.end <= (1 << log2_step));
117    assert!(butterfly_range.end <= twiddles.len());
118    
119    let current_data = &mut data[(stride_range.start + butterfly_range.start * 2 * stride)..];
120    let stride_range_len = stride_range.end - stride_range.start;
121    
122    if stride == 1 && stride_range_len == 1 {
123        for (twiddle, butterfly_data) in twiddles[butterfly_range].iter().zip(current_data.as_chunks_mut::<2>().0.iter_mut()) {
124            let [a, b] = butterfly_data.each_mut();
125            butterfly(a, b, &twiddle);
126        }
127    } else if stride_range_len >= 1 {
128        for (twiddle, butterfly_data) in twiddles[butterfly_range].iter().zip(current_data.chunks_mut(2 * stride)) {
129            let (first, second) = butterfly_data[..(stride + stride_range_len)].split_at_mut(stride);
130            let (first_chunks, first_rem) = first[..stride_range_len].as_chunks_mut::<4>();
131            let (second_chunks, second_rem) = second.as_chunks_mut::<4>();
132            for (a, b) in first_chunks.iter_mut().zip(second_chunks.iter_mut()) {
133                butterfly(&mut a[0], &mut b[0], &twiddle);
134                butterfly(&mut a[1], &mut b[1], &twiddle);
135                butterfly(&mut a[2], &mut b[2], &twiddle);
136                butterfly(&mut a[3], &mut b[3], &twiddle);
137            }
138            for (a, b) in first_rem.iter_mut().zip(second_rem.iter_mut()) {
139                butterfly(a, b, &twiddle);
140            }
141        }
142    }
143}
144
145impl<R_main, H> CooleyTuckeyFFT<R_main, Complex64Base, H, Global> 
146    where R_main: ?Sized + RingBase,
147        H: Homomorphism<Complex64Base, R_main>
148{
149    ///
150    /// Creates an [`CooleyTuckeyFFT`] for the complex field, using the given homomorphism
151    /// to connect the ring implementation for twiddles with the main ring implementation.
152    /// 
153    /// This function is mainly provided for parity with other rings, since in the complex case
154    /// it currently does not make much sense to use a different homomorphism than the identity.
155    /// Hence, it is simpler to use [`CooleyTuckeyFFT::for_complex()`].
156    /// 
157    pub fn for_complex_with_hom(hom: H, log2_n: usize) -> Self {
158        let CC = *hom.domain().get_ring();
159        Self::new_with_pows_with_hom(hom, |i| CC.root_of_unity(i, 1 << log2_n), log2_n)
160    }
161}
162
163impl<R> CooleyTuckeyFFT<Complex64Base, Complex64Base, Identity<R>, Global> 
164    where R: RingStore<Type = Complex64Base>
165{
166    ///
167    /// Creates an [`CooleyTuckeyFFT`] for the complex field.
168    /// 
169    pub fn for_complex(ring: R, log2_n: usize) -> Self {
170        Self::for_complex_with_hom(ring.into_identity(), log2_n)
171    }
172}
173
174impl<R> CooleyTuckeyFFT<R::Type, R::Type, Identity<R>, Global> 
175    where R: RingStore,
176        R::Type: DivisibilityRing
177{
178    ///
179    /// Creates an [`CooleyTuckeyFFT`] for the given ring, using the given root of unity. 
180    /// 
181    /// Do not use this for approximate rings, as computing the powers of `root_of_unity`
182    /// will incur avoidable precision loss.
183    /// 
184    pub fn new(ring: R, root_of_unity: El<R>, log2_n: usize) -> Self {
185        Self::new_with_hom(ring.into_identity(), root_of_unity, log2_n)
186    }
187
188    ///
189    /// Creates an [`CooleyTuckeyFFT`] for the given ring, using the passed function to
190    /// provide the necessary roots of unity.
191    /// 
192    /// Concretely, `root_of_unity_pow(i)` should return `z^i`, where `z` is a `2^log2_n`-th
193    /// primitive root of unity.
194    /// 
195    pub fn new_with_pows<F>(ring: R, root_of_unity_pow: F, log2_n: usize) -> Self 
196        where F: FnMut(i64) -> El<R>
197    {
198        Self::new_with_pows_with_hom(ring.into_identity(), root_of_unity_pow, log2_n)
199    }
200
201    ///
202    /// Creates an [`CooleyTuckeyFFT`] for a prime field, assuming it has a characteristic
203    /// congruent to 1 modulo `2^log2_n`.
204    /// 
205    pub fn for_zn(ring: R, log2_n: usize) -> Option<Self>
206        where R::Type: ZnRing
207    {
208        Self::for_zn_with_hom(ring.into_identity(), log2_n)
209    }
210}
211
212impl<R_main, R_twiddle, H> CooleyTuckeyFFT<R_main, R_twiddle, H, Global> 
213    where R_main: ?Sized + RingBase,
214        R_twiddle: ?Sized + RingBase + DivisibilityRing,
215        H: Homomorphism<R_twiddle, R_main>
216{
217    ///
218    /// Creates an [`CooleyTuckeyFFT`] for the given rings, using the given root of unity.
219    /// 
220    /// Instead of a ring, this function takes a homomorphism `R -> S`. Twiddle factors that are
221    /// precomputed will be stored as elements of `R`, while the main FFT computations will be 
222    /// performed in `S`. This allows both implicit ring conversions, and using patterns like 
223    /// [`zn_64::ZnFastmul`] to precompute some data for better performance.
224    /// 
225    /// Do not use this for approximate rings, as computing the powers of `root_of_unity`
226    /// will incur avoidable precision loss.
227    /// 
228    pub fn new_with_hom(hom: H, root_of_unity: R_twiddle::Element, log2_n: usize) -> Self {
229        let ring = hom.domain();
230        let root_of_unity_pow = |i: i64| if i >= 0 {
231            ring.pow(ring.clone_el(&root_of_unity), i as usize)
232        } else {
233            ring.invert(&ring.pow(ring.clone_el(&root_of_unity), (-i) as usize)).unwrap()
234        };
235        let result = CooleyTuckeyFFT::create(&hom, root_of_unity_pow, log2_n, Global);
236        
237        return CooleyTuckeyFFT {
238            root_of_unity_list: result.root_of_unity_list,
239            inv_root_of_unity_list: result.inv_root_of_unity_list,
240            two_inv: result.two_inv,
241            n_inv: result.n_inv,
242            root_of_unity: result.root_of_unity, 
243            log2_n: result.log2_n, 
244            allocator: result.allocator,
245            hom: hom, 
246        };
247    }
248
249    ///
250    /// Creates an [`CooleyTuckeyFFT`] for the given rings, using the given function to create
251    /// the necessary powers of roots of unity.
252    /// 
253    /// Concretely, `root_of_unity_pow(i)` should return `z^i`, where `z` is a `2^log2_n`-th
254    /// primitive root of unity.
255    /// 
256    /// Instead of a ring, this function takes a homomorphism `R -> S`. Twiddle factors that are
257    /// precomputed will be stored as elements of `R`, while the main FFT computations will be 
258    /// performed in `S`. This allows both implicit ring conversions, and using patterns like 
259    /// [`zn_64::ZnFastmul`] to precompute some data for better performance.
260    /// 
261    pub fn new_with_pows_with_hom<F>(hom: H, root_of_unity_pow: F, log2_n: usize) -> Self 
262        where F: FnMut(i64) -> R_twiddle::Element
263    {
264        Self::create(hom, root_of_unity_pow, log2_n, Global)
265    }
266
267    ///
268    /// Creates an [`CooleyTuckeyFFT`] for the given prime fields, assuming they have
269    /// a characteristic congruent to 1 modulo `2^log2_n`.
270    /// 
271    /// Instead of a ring, this function takes a homomorphism `R -> S`. Twiddle factors that are
272    /// precomputed will be stored as elements of `R`, while the main FFT computations will be 
273    /// performed in `S`. This allows both implicit ring conversions, and using patterns like 
274    /// [`zn_64::ZnFastmul`] to precompute some data for better performance.
275    /// 
276    pub fn for_zn_with_hom(hom: H, log2_n: usize) -> Option<Self>
277        where R_twiddle: ZnRing
278    {
279        let root_of_unity = get_prim_root_of_unity_zn(hom.domain(), log2_n)?;
280        Some(Self::new_with_hom(hom, root_of_unity, log2_n))
281    }
282}
283
284impl<R_main, R_twiddle, H, A> PartialEq for CooleyTuckeyFFT<R_main, R_twiddle, H, A> 
285    where R_main: ?Sized + RingBase,
286        R_twiddle: ?Sized + RingBase + DivisibilityRing,
287        H: Homomorphism<R_twiddle, R_main>,
288        A: Allocator
289{
290    fn eq(&self, other: &Self) -> bool {
291        self.ring().get_ring() == other.ring().get_ring() &&
292            self.log2_n == other.log2_n &&
293            self.ring().eq_el(self.root_of_unity(self.ring()), other.root_of_unity(self.ring()))
294    }
295}
296
297impl<R_main, R_twiddle, H, A> Debug for CooleyTuckeyFFT<R_main, R_twiddle, H, A> 
298    where R_main: ?Sized + RingBase + Debug,
299        R_twiddle: ?Sized + RingBase + DivisibilityRing,
300        H: Homomorphism<R_twiddle, R_main>,
301        A: Allocator
302{
303    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
304        f.debug_struct("CooleyTuckeyFFT")
305            .field("ring", &self.ring().get_ring())
306            .field("n", &(1 << self.log2_n))
307            .field("root_of_unity", &self.ring().format(&self.root_of_unity(self.ring())))
308            .finish()
309    }
310}
311
312impl<R_main, R_twiddle, H, A> Clone for CooleyTuckeyFFT<R_main, R_twiddle, H, A> 
313    where R_main: ?Sized + RingBase,
314        R_twiddle: ?Sized + RingBase + DivisibilityRing,
315        H: Homomorphism<R_twiddle, R_main> + Clone,
316        A: Allocator + Clone
317{
318    fn clone(&self) -> Self {
319        Self {
320            two_inv: self.hom.domain().clone_el(&self.two_inv),
321            n_inv: self.hom.domain().clone_el(&self.n_inv),
322            hom: self.hom.clone(),
323            inv_root_of_unity_list: self.inv_root_of_unity_list.iter().map(|list| list.iter().map(|x| self.hom.domain().clone_el(x)).collect()).collect(),
324            root_of_unity_list: self.root_of_unity_list.iter().map(|list| list.iter().map(|x| self.hom.domain().clone_el(x)).collect()).collect(),
325            root_of_unity: self.hom.codomain().clone_el(&self.root_of_unity),
326            log2_n: self.log2_n,
327            allocator: self.allocator.clone()
328        }
329    }
330}
331
332///
333/// A helper trait that defines the Cooley-Tukey butterfly operation.
334/// It is default-implemented for all rings, but for increase FFT performance, some rings
335/// might wish to provide a specialization.
336/// 
337/// # Why not a subtrait of [`Homomorphism`]?
338/// 
339/// With the current design, indeed making this a subtrait of [`Homomorphism`] would
340/// indeed be the conceptually most fitting choice. It would allow specializing on
341/// the twiddle ring, the main ring and the inclusion. 
342/// 
343/// Unfortunately, there is a technical issue: With the current `min_specialization`, 
344/// we can only specialize on concrete type. If this is a subtrait of [`Homomorphism`], this 
345/// means we can only specialize on, say, `CanHom<ZnFastmul, Zn>`, which then does not give a
346/// specialization for `CanHom<&ZnFastmul, Zn>` - in other words, we would specialize on
347/// the [`RingStore`], and not on the [`RingBase`] as we should. Hence, we'll keep this
348/// suboptimal design until full specialization works.
349/// 
350pub trait CooleyTuckeyButterfly<S>: RingBase
351    where S: ?Sized + RingBase
352{
353    ///
354    /// Should compute `(values[i1], values[i2]) := (values[i1] + twiddle * values[i2], values[i1] - twiddle * values[i2])`.
355    /// 
356    /// It is guaranteed that the input elements are either outputs of
357    /// [`CooleyTuckeyButterfly::butterfly()`] or of [`CooleyTuckeyButterfly::prepare_for_fft()`].
358    /// 
359    /// Deprecated in favor of [`CooleyTuckeyButterfly::butterfly_new()`].
360    /// 
361    #[deprecated]
362    fn butterfly<V: VectorViewMut<Self::Element>, H: Homomorphism<S, Self>>(&self, hom: H, values: &mut V, twiddle: &S::Element, i1: usize, i2: usize);
363
364    ///
365    /// Should compute `(values[i1], values[i2]) := (values[i1] + values[i2], (values[i1] - values[i2]) * twiddle)`
366    /// 
367    /// It is guaranteed that the input elements are either outputs of
368    /// [`CooleyTuckeyButterfly::inv_butterfly()`] or of [`CooleyTuckeyButterfly::prepare_for_inv_fft()`].
369    /// 
370    /// Deprecated in favor of [`CooleyTuckeyButterfly::inv_butterfly_new()`].
371    /// 
372    #[deprecated]
373    fn inv_butterfly<V: VectorViewMut<Self::Element>, H: Homomorphism<S, Self>>(&self, hom: H, values: &mut V, twiddle: &S::Element, i1: usize, i2: usize);
374    
375    ///
376    /// Should compute `(x, y) := (x + twiddle * y, x - twiddle * y)`.
377    /// 
378    /// It is guaranteed that the input elements are either outputs of
379    /// [`CooleyTuckeyButterfly::butterfly_new()`] or of [`CooleyTuckeyButterfly::prepare_for_fft()`].
380    /// 
381    fn butterfly_new<H: Homomorphism<S, Self>>(hom: H, x: &mut Self::Element, y: &mut Self::Element, twiddle: &S::Element);
382    
383    ///
384    /// Should compute `(x, y) := (x + y, (x - y) * twiddle)`
385    /// 
386    /// It is guaranteed that the input elements are either outputs of
387    /// [`CooleyTuckeyButterfly::inv_butterfly_new()`] or of [`CooleyTuckeyButterfly::prepare_for_inv_fft()`].
388    /// 
389    fn inv_butterfly_new<H: Homomorphism<S, Self>>(hom: H, x: &mut Self::Element, y: &mut Self::Element, twiddle: &S::Element);
390
391    ///
392    /// Possibly pre-processes elements before the FFT starts. Here you can
393    /// bring ring element into a certain form, and assume during [`CooleyTuckeyButterfly::butterfly_new()`]
394    /// that the inputs are in this form.
395    /// 
396    #[inline(always)]
397    fn prepare_for_fft(&self, _value: &mut Self::Element) {}
398    
399    ///
400    /// Possibly pre-processes elements before the inverse FFT starts. Here you can
401    /// bring ring element into a certain form, and assume during [`CooleyTuckeyButterfly::inv_butterfly_new()`]
402    /// that the inputs are in this form.
403    /// 
404    #[inline(always)]
405    fn prepare_for_inv_fft(&self, _value: &mut Self::Element) {}
406}
407
408#[allow(deprecated)]
409impl<R, S> CooleyTuckeyButterfly<S> for R
410    where S: ?Sized + RingBase, R: ?Sized + RingBase
411{
412    #[inline(always)]
413    default fn butterfly<V: VectorViewMut<Self::Element>, H: Homomorphism<S, Self>>(&self, hom: H, values: &mut V, twiddle: &<S as RingBase>::Element, i1: usize, i2: usize) {
414        hom.mul_assign_ref_map(values.at_mut(i2), twiddle);
415        let new_a = self.add_ref(values.at(i1), values.at(i2));
416        let a = std::mem::replace(values.at_mut(i1), new_a);
417        self.sub_self_assign(values.at_mut(i2), a);
418    }
419
420    #[inline(always)]
421    #[allow(deprecated)]
422    default fn butterfly_new<H: Homomorphism<S, Self>>(hom: H, x: &mut Self::Element, y: &mut Self::Element, twiddle: &S::Element) {
423        let mut values = [hom.codomain().clone_el(x), hom.codomain().clone_el(y)];
424        <Self as CooleyTuckeyButterfly<S>>::butterfly(hom.codomain().get_ring(), &hom, &mut values, twiddle, 0, 1);
425        [*x, *y] = values;
426    }
427
428    #[inline(always)]
429    default fn inv_butterfly<V: VectorViewMut<Self::Element>, H: Homomorphism<S, Self>>(&self, hom: H, values: &mut V, twiddle: &<S as RingBase>::Element, i1: usize, i2: usize) {
430        let new_a = self.add_ref(values.at(i1), values.at(i2));
431        let a = std::mem::replace(values.at_mut(i1), new_a);
432        self.sub_self_assign(values.at_mut(i2), a);
433        hom.mul_assign_ref_map(values.at_mut(i2), twiddle);
434    }
435    
436    #[inline(always)]
437    #[allow(deprecated)]
438    default fn inv_butterfly_new<H: Homomorphism<S, Self>>(hom: H, x: &mut Self::Element, y: &mut Self::Element, twiddle: &S::Element) {
439        let mut values = [hom.codomain().clone_el(x), hom.codomain().clone_el(y)];
440        <Self as CooleyTuckeyButterfly<S>>::inv_butterfly(hom.codomain().get_ring(), &hom, &mut values, twiddle, 0, 1);
441        [*x, *y] = values;
442    }
443
444    #[inline(always)]
445    default fn prepare_for_fft(&self, _value: &mut Self::Element) {}
446    
447    #[inline(always)]
448    default fn prepare_for_inv_fft(&self, _value: &mut Self::Element) {}
449}
450
451impl<R_main, R_twiddle, H, A> CooleyTuckeyFFT<R_main, R_twiddle, H, A> 
452    where R_main: ?Sized + RingBase,
453        R_twiddle: ?Sized + RingBase + DivisibilityRing,
454        H: Homomorphism<R_twiddle, R_main>,
455        A: Allocator
456{
457    ///
458    /// Most general way to create a [`CooleyTuckeyFFT`].
459    /// 
460    /// This is currently the same as [`CooleyTuckeyFFT::new_with_pows_with_hom()`], except
461    /// that it additionally accepts an allocator, which is used to copy the input data in
462    /// cases where the input data layout is not optimal for the algorithm.
463    /// 
464    #[stability::unstable(feature = "enable")]
465    pub fn create<F>(hom: H, mut root_of_unity_pow: F, log2_n: usize, allocator: A) -> Self 
466        where F: FnMut(i64) -> R_twiddle::Element
467    {
468        let ring = hom.domain();
469        assert!(ring.is_commutative());
470        assert!(ring.get_ring().is_approximate() || is_prim_root_of_unity_pow2(&ring, &root_of_unity_pow(1), log2_n));
471        assert!(hom.codomain().get_ring().is_approximate() || is_prim_root_of_unity_pow2(&hom.codomain(), &hom.map(root_of_unity_pow(1)), log2_n));
472
473        let root_of_unity_list = Self::create_root_of_unity_list(|i| root_of_unity_pow(-i), log2_n);
474        let inv_root_of_unity_list = Self::create_root_of_unity_list(|i| root_of_unity_pow(i), log2_n);
475        let root_of_unity = root_of_unity_pow(1);
476        
477        let store_twiddle_ring = root_of_unity_list.len();
478        CooleyTuckeyFFT {
479            root_of_unity_list: root_of_unity_list.into_iter().take(store_twiddle_ring).collect(),
480            inv_root_of_unity_list: inv_root_of_unity_list.into_iter().take(store_twiddle_ring).collect(),
481            two_inv: hom.domain().invert(&hom.domain().int_hom().map(2)).unwrap(),
482            n_inv: hom.domain().invert(&hom.domain().int_hom().map(1 << log2_n)).unwrap(),
483            root_of_unity: hom.map(root_of_unity), 
484            hom, 
485            log2_n, 
486            allocator
487        }
488    }
489
490    ///
491    /// Replaces the ring that this object can compute FFTs over, assuming that the current
492    /// twiddle factors can be mapped into the new ring with the given homomorphism.
493    /// 
494    /// In particular, this function does not recompute twiddles, but uses a different
495    /// homomorphism to map the current twiddles into a new ring. Hence, it is extremely
496    /// cheap. 
497    /// 
498    #[stability::unstable(feature = "enable")]
499    pub fn change_ring<R_new: ?Sized + RingBase, H_new: Homomorphism<R_twiddle, R_new>>(self, new_hom: H_new) -> (CooleyTuckeyFFT<R_new, R_twiddle, H_new, A>, H) {
500        let ring = new_hom.codomain();
501        let root_of_unity = if self.log2_n == 0 {
502            new_hom.codomain().one()
503        } else {
504            new_hom.map_ref(&self.inv_root_of_unity_list[self.log2_n - 1][bitreverse(1, self.log2_n - 1)])
505        };
506        assert!(ring.is_commutative());
507        assert!(ring.get_ring().is_approximate() || is_prim_root_of_unity_pow2(&ring, &root_of_unity, self.log2_n));
508
509        return (
510            CooleyTuckeyFFT {
511                root_of_unity_list: self.root_of_unity_list,
512                inv_root_of_unity_list: self.inv_root_of_unity_list,
513                two_inv: self.two_inv,
514                n_inv: self.n_inv,
515                root_of_unity: root_of_unity, 
516                hom: new_hom, 
517                log2_n: self.log2_n, 
518                allocator: self.allocator
519            },
520            self.hom
521        );
522    }
523
524    fn create_root_of_unity_list<F>(mut root_of_unity_pow: F, log2_n: usize) -> Vec<Vec<R_twiddle::Element>>
525        where F: FnMut(i64) -> R_twiddle::Element
526    {
527        let mut twiddles: Vec<Vec<R_twiddle::Element>> = (0..log2_n).map(|_| Vec::new()).collect();
528        for log2_step in 0..log2_n {
529            let butterfly_count = 1 << log2_step;
530            for i in 0..butterfly_count {
531                twiddles[log2_step].push(root_of_unity_pow(bitreverse(i, log2_n - 1) as i64));
532            }
533        }
534        return twiddles;
535    }
536
537    ///
538    /// Returns the ring over which this object can compute FFTs.
539    /// 
540    pub fn ring<'a>(&'a self) -> &'a <H as Homomorphism<R_twiddle, R_main>>::CodomainStore {
541        self.hom.codomain()
542    }
543
544    /// 
545    /// Computes the main butterfly step, either forward or backward (without division by two).
546    /// 
547    /// The forward butterfly is
548    /// ```text
549    ///   (a, b) -> (a + twiddle * b, a - twiddle * b)
550    /// ```
551    /// The backward butterfly is
552    /// ```text
553    ///   (u, v) -> (u + v, twiddle * (u - v))
554    /// ```
555    /// 
556    /// The `#[inline(never)]` here is absolutely important for performance!
557    /// No idea why...
558    /// 
559    #[inline(never)]
560    fn butterfly_step_main<const INV: bool, const IS_PREPARED: bool>(&self, data: &mut [R_main::Element], butterfly_range: Range<usize>, stride_range: Range<usize>, log2_step: usize) {
561        let twiddles = if INV {
562            &self.inv_root_of_unity_list[log2_step]
563        } else {
564            &self.root_of_unity_list[log2_step]
565        };
566        // let start = std::time::Instant::now();
567        let butterfly = |a: &mut _, b: &mut _, twiddle: &_| {
568            if INV {
569                if !IS_PREPARED {
570                    <R_main as CooleyTuckeyButterfly<R_twiddle>>::prepare_for_inv_fft(self.ring().get_ring(), a);
571                    <R_main as CooleyTuckeyButterfly<R_twiddle>>::prepare_for_inv_fft(self.ring().get_ring(), b);
572                }
573                <R_main as CooleyTuckeyButterfly<R_twiddle>>::inv_butterfly_new(&self.hom, a, b, twiddle);
574            } else {
575                if !IS_PREPARED {
576                    <R_main as CooleyTuckeyButterfly<R_twiddle>>::prepare_for_fft(self.ring().get_ring(), a);
577                    <R_main as CooleyTuckeyButterfly<R_twiddle>>::prepare_for_fft(self.ring().get_ring(), b);
578                }
579                <R_main as CooleyTuckeyButterfly<R_twiddle>>::butterfly_new(&self.hom, a, b, twiddle);
580            }
581        };
582        butterfly_loop(self.log2_n, data, butterfly_range, stride_range, log2_step, twiddles, butterfly);
583        // let end = std::time::Instant::now();
584        // BUTTERFLY_TIMES[log2_step].fetch_add((end - start).as_micros() as usize, std::sync::atomic::Ordering::Relaxed);
585    }
586    
587    ///
588    /// The definitions are
589    /// ```text
590    ///   u = a/2 + twiddle * b/2,
591    ///   v = a/2 - twiddle * b/2
592    /// ```
593    /// 
594    #[inline(never)]
595    fn butterfly_ub_from_ab(&self, data: &mut [R_main::Element], butterfly_range: Range<usize>, stride_range: Range<usize>, log2_step: usize) {
596        butterfly_loop(self.log2_n, data, butterfly_range, stride_range, log2_step, &self.root_of_unity_list[log2_step], |a, b, twiddle| {
597            *a = self.hom.mul_ref_snd_map(
598                self.ring().add_ref_fst(a, self.hom.mul_ref_map(b, twiddle)),
599                &self.two_inv
600            );
601        });
602    }
603
604    ///
605    /// The definitions are
606    /// ```text
607    ///   u = a/2 + twiddle * b/2,
608    ///   v = a/2 - twiddle * b/2
609    /// ```
610    /// 
611    #[inline(never)]
612    fn butterfly_uv_from_ub(&self, data: &mut [R_main::Element], butterfly_range: Range<usize>, stride_range: Range<usize>, log2_step: usize) {
613        butterfly_loop(self.log2_n, data, butterfly_range, stride_range, log2_step, &self.root_of_unity_list[log2_step], |a, b, twiddle| {
614            *b = self.ring().sub_ref_fst(a, self.hom.mul_ref_map(b, twiddle));
615        });
616    }
617
618    ///
619    /// The definitions are
620    /// ```text
621    ///   u = a/2 + twiddle * b/2,
622    ///   v = a/2 - twiddle * b/2
623    /// ```
624    /// 
625    #[inline(never)]
626    fn butterfly_ab_from_ub(&self, data: &mut [R_main::Element], butterfly_range: Range<usize>, stride_range: Range<usize>, log2_step: usize) {
627        butterfly_loop(self.log2_n, data, butterfly_range, stride_range, log2_step, &self.root_of_unity_list[log2_step], |a, b, twiddle| {
628            *a = self.ring().add_ref(a, a);
629            self.ring().sub_assign(a, self.hom.mul_ref_map(b, twiddle));
630        });
631    }
632
633    ///
634    /// Returns a reference to the allocator currently used for temporary allocations by this FFT.
635    /// 
636    #[stability::unstable(feature = "enable")]
637    pub fn allocator(&self) -> &A {
638        &self.allocator
639    }
640
641    ///
642    /// Replaces the allocator used for temporary allocations by this FFT.
643    /// 
644    #[stability::unstable(feature = "enable")]
645    pub fn with_allocator<A_new: Allocator>(self, allocator: A_new) -> CooleyTuckeyFFT<R_main, R_twiddle, H, A_new> {
646        CooleyTuckeyFFT {
647            root_of_unity_list: self.root_of_unity_list,
648            inv_root_of_unity_list: self.inv_root_of_unity_list,
649            two_inv: self.two_inv,
650            n_inv: self.n_inv,
651            root_of_unity: self.root_of_unity, 
652            hom: self.hom, 
653            log2_n: self.log2_n, 
654            allocator: allocator
655        }
656    }
657
658    ///
659    /// Returns a reference to the homomorphism that is used to map the stored twiddle
660    /// factors into main ring, over which FFTs are computed.
661    /// 
662    #[stability::unstable(feature = "enable")]
663    pub fn hom(&self) -> &H {
664        &self.hom
665    }
666
667    ///
668    /// Computes the unordered, truncated FFT.
669    /// 
670    /// The truncated FFT is the standard DFT, applied to a list for which only the first
671    /// `nonzero_entries` entries are nonzero, and the (bitreversed) result truncated to
672    /// length `nonzero_entries`.
673    /// 
674    /// Therefore, this function is equivalent to the following pseudocode
675    /// ```text
676    /// data[nonzero_entries..] = 0;
677    /// unordered_fft(data);
678    /// data[nonzero_entries] = unspecified;
679    /// ```
680    /// 
681    /// It can be inverted using [`CooleyTuckey::unordered_truncated_fft_inv()`].
682    /// 
683    #[stability::unstable(feature = "enable")]
684    pub fn unordered_truncated_fft(&self, data: &mut [R_main::Element], nonzero_entries: usize) {
685        assert_eq!(self.len(), data.len());
686        assert!(nonzero_entries > self.len() / 2);
687        assert!(nonzero_entries <= self.len());
688        for i in nonzero_entries..self.len() {
689            debug_assert!(self.ring().get_ring().is_approximate() || self.ring().is_zero(&data[i]));
690        }
691
692        for i in 0..data.len() {
693            <R_main as CooleyTuckeyButterfly<R_twiddle>>::prepare_for_fft(self.ring().get_ring(), &mut data[i]);
694        }
695        for log2_step in 0..self.log2_n {
696            let stride = 1 << (self.log2_n - log2_step - 1);
697            let butterfly_count = nonzero_entries.div_ceil(2 * stride);
698            self.butterfly_step_main::<false, true>(data, 0..butterfly_count, 0..stride, log2_step);
699        }
700    }
701    
702    ///
703    /// Computes the inverse of the unordered, truncated FFT.
704    /// 
705    /// The truncated FFT is the standard DFT, applied to a list for which only the first
706    /// `nonzero_entries` entries are nonzero, and the (bitreversed) result truncated to
707    /// length `nonzero_entries`. Therefore, this function computes a list of `nonzero_entries`
708    /// many values, followed by zeros, whose DFT agrees with the input on the first `nonzero_entries`
709    /// many elements.
710    /// 
711    #[stability::unstable(feature = "enable")]
712    pub fn unordered_truncated_fft_inv(&self, data: &mut [R_main::Element], nonzero_entries: usize) {   
713        assert_eq!(self.len(), data.len());
714        assert!(nonzero_entries > self.len() / 2);
715        assert!(nonzero_entries <= self.len());
716
717        for i in 0..data.len() {
718            <R_main as CooleyTuckeyButterfly<R_twiddle>>::prepare_for_inv_fft(self.ring().get_ring(), &mut data[i]);
719        }
720        for log2_step in (0..self.log2_n).rev() {
721            let stride = 1 << (self.log2_n - log2_step - 1);
722            let current_block = nonzero_entries / (2 * stride);
723            self.butterfly_step_main::<true, true>(data, 0..current_block, 0..stride, log2_step);
724        }
725        if nonzero_entries < (1 << self.log2_n) {
726            for i in nonzero_entries..(1 << self.log2_n) {
727                data[i] = self.ring().zero();
728            }
729            for log2_step in 0..self.log2_n {
730                let stride = 1 << (self.log2_n - log2_step - 1);
731                let current_block = nonzero_entries / (2 * stride);
732                let known_area = nonzero_entries % (2 * stride);
733                if known_area >= stride {
734                    self.butterfly_uv_from_ub(data, current_block..(current_block + 1), (known_area - stride)..stride, log2_step);
735                } else {
736                    self.butterfly_ub_from_ab(data, current_block..(current_block + 1), known_area..stride, log2_step);
737                }
738            }
739            for log2_step in (0..self.log2_n).rev() {
740                let stride = 1 << (self.log2_n - log2_step - 1);
741                let current_block = nonzero_entries / (2 * stride);
742                let known_area = nonzero_entries % (2 * stride);
743                if known_area >= stride {
744                    self.butterfly_step_main::<true, false>(data, current_block..(current_block + 1), 0..stride, log2_step);
745                } else {
746                    self.butterfly_ab_from_ub(data, current_block..(current_block + 1), 0..stride, log2_step);
747                }
748            }
749        }
750        for i in 0..(1 << self.log2_n) {
751            self.hom.mul_assign_ref_map(&mut data[i], &self.n_inv);
752        }
753    }
754    
755    ///
756    /// Permutes the given list of length `n` according to `values[bitreverse(i, log2(n))] = values[i]`.
757    /// This is exactly the permutation that is implicitly applied by [`CooleyTuckeyFFT::unordered_fft()`].
758    /// 
759    pub fn bitreverse_permute_inplace<V, T>(&self, mut values: V) 
760        where V: SwappableVectorViewMut<T>
761    {
762        assert!(values.len() == 1 << self.log2_n);
763        for i in 0..(1 << self.log2_n) {
764            if bitreverse(i, self.log2_n) < i {
765                values.swap(i, bitreverse(i, self.log2_n));
766            }
767        }
768    }
769}
770
771impl<R_main, R_twiddle, H, A> FFTAlgorithm<R_main> for CooleyTuckeyFFT<R_main, R_twiddle, H, A> 
772    where R_main: ?Sized + RingBase,
773        R_twiddle: ?Sized + RingBase + DivisibilityRing,
774        H: Homomorphism<R_twiddle, R_main>,
775        A: Allocator
776{
777    fn len(&self) -> usize {
778        1 << self.log2_n
779    }
780
781    fn root_of_unity<S: Copy + RingStore<Type = R_main>>(&self, ring: S) -> &R_main::Element {
782        assert!(ring.get_ring() == self.ring().get_ring(), "unsupported ring");
783        &self.root_of_unity
784    }
785
786    fn unordered_fft_permutation(&self, i: usize) -> usize {
787        bitreverse(i, self.log2_n)
788    }
789
790    fn unordered_fft_permutation_inv(&self, i: usize) -> usize {
791        bitreverse(i, self.log2_n)
792    }
793
794    fn fft<V, S>(&self, mut values: V, ring: S)
795        where V: SwappableVectorViewMut<<R_main as RingBase>::Element>,
796            S: RingStore<Type = R_main> + Copy 
797    {
798        assert!(ring.get_ring() == self.ring().get_ring(), "unsupported ring");
799        assert_eq!(self.len(), values.len());
800        self.unordered_fft(&mut values, ring);
801        self.bitreverse_permute_inplace(&mut values);
802    }
803
804    fn inv_fft<V, S>(&self, mut values: V, ring: S)
805        where V: SwappableVectorViewMut<<R_main as RingBase>::Element>,
806            S: RingStore<Type = R_main> + Copy 
807    {
808        assert!(ring.get_ring() == self.ring().get_ring(), "unsupported ring");
809        assert_eq!(self.len(), values.len());
810        self.bitreverse_permute_inplace(&mut values);
811        self.unordered_inv_fft(&mut values, ring);
812    }
813
814    fn unordered_fft<V, S>(&self, mut values: V, ring: S)
815        where V: SwappableVectorViewMut<<R_main as RingBase>::Element>,
816            S: RingStore<Type = R_main> + Copy 
817    {
818        assert!(ring.get_ring() == self.ring().get_ring(), "unsupported ring");
819        assert_eq!(self.len(), values.len());
820        if let Some(data) = values.as_slice_mut() {
821            self.unordered_truncated_fft(data, 1 << self.log2_n);
822        } else {
823            let mut data = Vec::with_capacity_in(1 << self.log2_n, &self.allocator);
824            data.extend(values.clone_ring_els(ring).iter());
825            self.unordered_truncated_fft(&mut data, 1 << self.log2_n);
826            for (i, x) in data.into_iter().enumerate() {
827                *values.at_mut(i) = x;
828            }
829        }
830    }
831    
832    fn unordered_inv_fft<V, S>(&self, mut values: V, ring: S)
833        where V: SwappableVectorViewMut<<R_main as RingBase>::Element>,
834            S: RingStore<Type = R_main> + Copy 
835    {
836        assert!(ring.get_ring() == self.ring().get_ring(), "unsupported ring");
837        assert_eq!(self.len(), values.len());
838        if let Some(data) = values.as_slice_mut() {
839            self.unordered_truncated_fft_inv(data, 1 << self.log2_n);
840        } else {
841            let mut data = Vec::with_capacity_in(1 << self.log2_n, &self.allocator);
842            data.extend(values.clone_ring_els(ring).iter());
843            self.unordered_truncated_fft_inv(&mut data, 1 << self.log2_n);
844            for (i, x) in data.into_iter().enumerate() {
845                *values.at_mut(i) = x;
846            }
847        }
848    }
849}
850
851impl<H, A> FFTErrorEstimate for CooleyTuckeyFFT<Complex64Base, Complex64Base, H, A> 
852    where H: Homomorphism<Complex64Base, Complex64Base>,
853        A: Allocator
854{
855    fn expected_absolute_error(&self, input_bound: f64, input_error: f64) -> f64 {
856        // the butterfly performs a multiplication with a root of unity, and an addition
857        let multiply_absolute_error = input_bound * root_of_unity_error() + input_bound * f64::EPSILON;
858        let addition_absolute_error = input_bound * f64::EPSILON;
859        let butterfly_absolute_error = multiply_absolute_error + addition_absolute_error;
860        // the operator inf-norm of the FFT is its length
861        return 2. * self.len() as f64 * butterfly_absolute_error + self.len() as f64 * input_error;
862    }
863}
864
865#[cfg(test)]
866use crate::primitive_int::*;
867#[cfg(test)]
868use crate::rings::zn::zn_static::Fp;
869#[cfg(test)]
870use crate::rings::zn::zn_big;
871#[cfg(test)]
872use crate::rings::zn::zn_static;
873#[cfg(test)]
874use crate::field::*;
875#[cfg(test)]
876use crate::rings::finite::FiniteRingStore;
877
878#[test]
879fn test_bitreverse_fft_inplace_basic() {
880    let ring = Fp::<5>::RING;
881    let z = ring.int_hom().map(2);
882    let fft = CooleyTuckeyFFT::new(ring, ring.div(&1, &z), 2);
883    let mut values = [1, 0, 0, 1];
884    let expected = [2, 4, 0, 3];
885    let mut bitreverse_expected = [0; 4];
886    for i in 0..4 {
887        bitreverse_expected[i] = expected[bitreverse(i, 2)];
888    }
889
890    fft.unordered_fft(&mut values, ring);
891    assert_eq!(values, bitreverse_expected);
892}
893
894#[test]
895fn test_bitreverse_fft_inplace_advanced() {
896    let ring = Fp::<17>::RING;
897    let z = ring.int_hom().map(3);
898    let fft = CooleyTuckeyFFT::new(ring, z, 4);
899    let mut values = [1, 0, 0, 0, 1, 0, 0, 0, 4, 3, 2, 1, 4, 3, 2, 1];
900    let expected = [5, 2, 0, 11, 5, 4, 0, 6, 6, 13, 0, 1, 7, 6, 0, 1];
901    let mut bitreverse_expected = [0; 16];
902    for i in 0..16 {
903        bitreverse_expected[i] = expected[bitreverse(i, 4)];
904    }
905
906    fft.unordered_fft(&mut values, ring);
907    assert_eq!(values, bitreverse_expected);
908}
909
910#[test]
911fn test_unordered_fft_permutation() {
912    let ring = Fp::<17>::RING;
913    let fft = CooleyTuckeyFFT::for_zn(&ring, 4).unwrap();
914    let mut values = [0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
915    let mut expected = [0; 16];
916    for i in 0..16 {
917        let power_of_zeta = ring.pow(*fft.root_of_unity(&ring), 16 - fft.unordered_fft_permutation(i));
918        expected[i] = ring.add(power_of_zeta, ring.pow(power_of_zeta, 4));
919    }
920    fft.unordered_fft(&mut values, ring);
921    assert_eq!(expected, values);
922}
923
924#[test]
925fn test_bitreverse_inv_fft_inplace() {
926    let ring = Fp::<17>::RING;
927    let fft = CooleyTuckeyFFT::for_zn(&ring, 4).unwrap();
928    let values: [u64; 16] = [1, 2, 3, 2, 1, 0, 17 - 1, 17 - 2, 17 - 1, 0, 1, 2, 3, 4, 5, 6];
929    let mut work = values;
930    fft.unordered_fft(&mut work, ring);
931    fft.unordered_inv_fft(&mut work, ring);
932    assert_eq!(&work, &values);
933}
934
935#[test]
936fn test_truncated_fft() {
937    let ring = Fp::<17>::RING;
938    let fft = CooleyTuckeyFFT::new(ring, 2, 3);
939
940    let data = [2, 3, 0, 1, 1, 0, 0, 0];
941    let mut complete_fft = data;
942    fft.unordered_fft(&mut complete_fft, ring);
943    for k in 5..=8 {
944        println!("{}", k);
945        let mut truncated_fft = data;
946        fft.unordered_truncated_fft(&mut truncated_fft, k);
947        assert_eq!(&complete_fft[..k], &truncated_fft[..k]);
948
949        fft.unordered_truncated_fft_inv(&mut truncated_fft, k);
950        assert_eq!(data, truncated_fft);
951    }
952}
953
954#[test]
955fn test_for_zn() {
956    let ring = Fp::<17>::RING;
957    let fft = CooleyTuckeyFFT::for_zn(ring, 4).unwrap();
958    assert!(ring.is_neg_one(&ring.pow(fft.root_of_unity, 8)));
959
960    let ring = Fp::<97>::RING;
961    let fft = CooleyTuckeyFFT::for_zn(ring, 4).unwrap();
962    assert!(ring.is_neg_one(&ring.pow(fft.root_of_unity, 8)));
963}
964
965#[cfg(test)]
966fn run_fft_bench_round<R, S, H>(fft: &CooleyTuckeyFFT<S, R, H>, data: &Vec<S::Element>, copy: &mut Vec<S::Element>)
967    where R: ZnRing, S: ZnRing, H: Homomorphism<R, S>
968{
969    copy.clear();
970    copy.extend(data.iter().map(|x| fft.ring().clone_el(x)));
971    fft.unordered_fft(&mut copy[..], &fft.ring());
972    fft.unordered_inv_fft(&mut copy[..], &fft.ring());
973    assert_el_eq!(fft.ring(), copy[0], data[0]);
974}
975
976#[cfg(test)]
977const BENCH_SIZE_LOG2: usize = 13;
978
979#[bench]
980fn bench_fft_zn_big(bencher: &mut test::Bencher) {
981    let ring = zn_big::Zn::new(StaticRing::<i128>::RING, 1073872897);
982    let fft = CooleyTuckeyFFT::for_zn(&ring, BENCH_SIZE_LOG2).unwrap();
983    let data = (0..(1 << BENCH_SIZE_LOG2)).map(|i| ring.int_hom().map(i)).collect::<Vec<_>>();
984    let mut copy = Vec::with_capacity(1 << BENCH_SIZE_LOG2);
985    bencher.iter(|| {
986        run_fft_bench_round(&fft, &data, &mut copy)
987    });
988}
989
990#[bench]
991fn bench_fft_zn_64(bencher: &mut test::Bencher) {
992    let ring = zn_64::Zn::new(1073872897);
993    let fft = CooleyTuckeyFFT::for_zn(&ring, BENCH_SIZE_LOG2).unwrap();
994    let data = (0..(1 << BENCH_SIZE_LOG2)).map(|i| ring.int_hom().map(i)).collect::<Vec<_>>();
995    let mut copy = Vec::with_capacity(1 << BENCH_SIZE_LOG2);
996    bencher.iter(|| {
997        run_fft_bench_round(&fft, &data, &mut copy)
998    });
999}
1000
1001#[bench]
1002fn bench_fft_zn_64_fastmul(bencher: &mut test::Bencher) {
1003    let ring = zn_64::Zn::new(1073872897);
1004    let fastmul_ring = zn_64::ZnFastmul::new(ring).unwrap();
1005    let fft = CooleyTuckeyFFT::for_zn_with_hom(ring.into_can_hom(fastmul_ring).ok().unwrap(), BENCH_SIZE_LOG2).unwrap();
1006    let data = (0..(1 << BENCH_SIZE_LOG2)).map(|i| ring.int_hom().map(i)).collect::<Vec<_>>();
1007    let mut copy = Vec::with_capacity(1 << BENCH_SIZE_LOG2);
1008    bencher.iter(|| {
1009        run_fft_bench_round(&fft, &data, &mut copy)
1010    });
1011}
1012
1013#[test]
1014fn test_approximate_fft() {
1015    let CC = Complex64::RING;
1016    for log2_n in [4, 7, 11, 15] {
1017        let fft = CooleyTuckeyFFT::new_with_pows(CC, |x| CC.root_of_unity(x, 1 << log2_n), log2_n);
1018        let mut array = (0..(1 << log2_n)).map(|i|  CC.root_of_unity(i.try_into().unwrap(), 1 << log2_n)).collect::<Vec<_>>();
1019        fft.fft(&mut array, CC);
1020        let err = fft.expected_absolute_error(1., 0.);
1021        assert!(CC.is_absolute_approx_eq(array[0], CC.zero(), err));
1022        assert!(CC.is_absolute_approx_eq(array[1], CC.from_f64(fft.len() as f64), err));
1023        for i in 2..fft.len() {
1024            assert!(CC.is_absolute_approx_eq(array[i], CC.zero(), err));
1025        }
1026    }
1027}
1028
1029#[test]
1030fn test_size_1_fft() {
1031    let ring = Fp::<17>::RING;
1032    let fft = CooleyTuckeyFFT::for_zn(&ring, 0).unwrap().change_ring(ring.identity()).0;
1033    let values: [u64; 1] = [3];
1034    let mut work = values;
1035    fft.unordered_fft(&mut work, ring);
1036    assert_eq!(&work, &values);
1037    fft.unordered_inv_fft(&mut work, ring);
1038    assert_eq!(&work, &values);
1039    assert_eq!(0, fft.unordered_fft_permutation(0));
1040    assert_eq!(0, fft.unordered_fft_permutation_inv(0));
1041}
1042
1043#[cfg(any(test, feature = "generic_tests"))]
1044pub fn generic_test_cooley_tuckey_butterfly<R: RingStore, S: RingStore, I: Iterator<Item = El<R>>>(ring: R, base: S, edge_case_elements: I, test_twiddle: &El<S>)
1045    where R::Type: CanHomFrom<S::Type>,
1046        S::Type: DivisibilityRing
1047{
1048    let test_inv_twiddle = base.invert(&test_twiddle).unwrap();
1049    let elements = edge_case_elements.collect::<Vec<_>>();
1050    let hom = ring.can_hom(&base).unwrap();
1051
1052    for a in &elements {
1053        for b in &elements {
1054
1055            let [mut x, mut y] = [ring.clone_el(a), ring.clone_el(b)];
1056            <R::Type as CooleyTuckeyButterfly<S::Type>>::butterfly_new(&hom, &mut x, &mut y, &test_twiddle);
1057            assert_el_eq!(ring, ring.add_ref_fst(a, ring.mul_ref_fst(b, hom.map_ref(test_twiddle))), &x);
1058            assert_el_eq!(ring, ring.sub_ref_fst(a, ring.mul_ref_fst(b, hom.map_ref(test_twiddle))), &y);
1059
1060            <R::Type as CooleyTuckeyButterfly<S::Type>>::inv_butterfly_new(&hom, &mut x, &mut y, &test_inv_twiddle);
1061            assert_el_eq!(ring, ring.int_hom().mul_ref_fst_map(a, 2), &x);
1062            assert_el_eq!(ring, ring.int_hom().mul_ref_fst_map(b, 2), &y);
1063
1064            let [mut x, mut y] = [ring.clone_el(a), ring.clone_el(b)];
1065            <R::Type as CooleyTuckeyButterfly<S::Type>>::inv_butterfly_new(&hom, &mut x, &mut y, &test_twiddle);
1066            assert_el_eq!(ring, ring.add_ref(a, b), &x);
1067            assert_el_eq!(ring, ring.mul(ring.sub_ref(a, b), hom.map_ref(test_twiddle)), &y);
1068
1069            <R::Type as CooleyTuckeyButterfly<S::Type>>::butterfly_new(&hom, &mut x, &mut y, &test_inv_twiddle);
1070            assert_el_eq!(ring, ring.int_hom().mul_ref_fst_map(a, 2), &x);
1071            assert_el_eq!(ring, ring.int_hom().mul_ref_fst_map(b, 2), &y);
1072        }
1073    }
1074}
1075
1076#[test]
1077fn test_butterfly() {
1078    generic_test_cooley_tuckey_butterfly(zn_static::F17, zn_static::F17, zn_static::F17.elements(), &get_prim_root_of_unity_pow2(zn_static::F17, 4).unwrap());
1079}
feanor_math/algorithms/fft/cooley_tuckey.rs

feanor_math/algorithms/fft/
cooley_tuckey.rs
