rustfft/algorithm/
bluesteins_algorithm.rs

1use std::sync::Arc;
2
3use num_complex::Complex;
4use num_traits::Zero;
5
6use crate::{common::FftNum, twiddles, FftDirection};
7use crate::{Direction, Fft, Length};
8
9/// Implementation of Bluestein's Algorithm
10///
11/// This algorithm computes an arbitrary-sized FFT in O(nlogn) time. It does this by converting this size-N FFT into a
12/// size-M FFT where M >= 2N - 1.
13///
14/// The choice of M is very important for the performance of Bluestein's Algorithm. The most obvious choice is the next-largest
15/// power of two -- but if there's a smaller/faster FFT size that satisfies the `>= 2N - 1` requirement, that will significantly
16/// improve this algorithm's overall performance.
17///
18/// ~~~
19/// // Computes a forward FFT of size 1201, using Bluestein's Algorithm
20/// use rustfft::algorithm::BluesteinsAlgorithm;
21/// use rustfft::{Fft, FftPlanner};
22/// use rustfft::num_complex::Complex;
23///
24/// let mut buffer = vec![Complex{ re: 0.0f32, im: 0.0f32 }; 1201];
25///
26/// // We need to find an inner FFT whose size is greater than 1201*2 - 1.
27/// // The size 2401 (7^4) satisfies this requirement, while also being relatively fast.
28/// let mut planner = FftPlanner::new();
29/// let inner_fft = planner.plan_fft_forward(2401);
30///
31/// let fft = BluesteinsAlgorithm::new(1201, inner_fft);
32/// fft.process(&mut buffer);
33/// ~~~
34///
35/// Bluesteins's Algorithm is relatively expensive compared to other FFT algorithms. Benchmarking shows that it is up to
36/// an order of magnitude slower than similar composite sizes. In the example size above of 1201, benchmarking shows
37/// that it takes 5x more time to compute than computing a FFT of size 1200 via a step of MixedRadix.
38
39pub struct BluesteinsAlgorithm<T> {
40    inner_fft: Arc<dyn Fft<T>>,
41
42    inner_fft_multiplier: Box<[Complex<T>]>,
43    twiddles: Box<[Complex<T>]>,
44
45    len: usize,
46    direction: FftDirection,
47}
48
49impl<T: FftNum> BluesteinsAlgorithm<T> {
50    /// Creates a FFT instance which will process inputs/outputs of size `len`. `inner_fft.len()` must be >= `len * 2 - 1`
51    ///
52    /// Note that this constructor is quite expensive to run; This algorithm must compute a FFT using `inner_fft` within the
53    /// constructor. This further underlines the fact that Bluesteins Algorithm is more expensive to run than other
54    /// FFT algorithms
55    ///
56    /// # Panics
57    /// Panics if `inner_fft.len() < len * 2 - 1`.
58    pub fn new(len: usize, inner_fft: Arc<dyn Fft<T>>) -> Self {
59        let inner_fft_len = inner_fft.len();
60        assert!(len * 2 - 1 <= inner_fft_len, "Bluestein's algorithm requires inner_fft.len() >= self.len() * 2 - 1. Expected >= {}, got {}", len * 2 - 1, inner_fft_len);
61
62        // when computing FFTs, we're going to run our inner multiply pairise by some precomputed data, then run an inverse inner FFT. We need to precompute that inner data here
63        let inner_fft_scale = T::one() / T::from_usize(inner_fft_len).unwrap();
64        let direction = inner_fft.fft_direction();
65
66        // Compute twiddle factors that we'll run our inner FFT on
67        let mut inner_fft_input = vec![Complex::zero(); inner_fft_len];
68        twiddles::fill_bluesteins_twiddles(
69            &mut inner_fft_input[..len],
70            direction.opposite_direction(),
71        );
72
73        // Scale the computed twiddles and copy them to the end of the array
74        inner_fft_input[0] = inner_fft_input[0] * inner_fft_scale;
75        for i in 1..len {
76            let twiddle = inner_fft_input[i] * inner_fft_scale;
77            inner_fft_input[i] = twiddle;
78            inner_fft_input[inner_fft_len - i] = twiddle;
79        }
80
81        //Compute the inner fft
82        let mut inner_fft_scratch = vec![Complex::zero(); inner_fft.get_inplace_scratch_len()];
83        inner_fft.process_with_scratch(&mut inner_fft_input, &mut inner_fft_scratch);
84
85        // also compute some more mundane twiddle factors to start and end with
86        let mut twiddles = vec![Complex::zero(); len];
87        twiddles::fill_bluesteins_twiddles(&mut twiddles, direction);
88
89        Self {
90            inner_fft: inner_fft,
91
92            inner_fft_multiplier: inner_fft_input.into_boxed_slice(),
93            twiddles: twiddles.into_boxed_slice(),
94
95            len,
96            direction,
97        }
98    }
99
100    fn perform_fft_inplace(&self, input: &mut [Complex<T>], scratch: &mut [Complex<T>]) {
101        let (inner_input, inner_scratch) = scratch.split_at_mut(self.inner_fft_multiplier.len());
102
103        // Copy the buffer into our inner FFT input. the buffer will only fill part of the FFT input, so zero fill the rest
104        for ((buffer_entry, inner_entry), twiddle) in input
105            .iter()
106            .zip(inner_input.iter_mut())
107            .zip(self.twiddles.iter())
108        {
109            *inner_entry = *buffer_entry * *twiddle;
110        }
111        for inner in (&mut inner_input[input.len()..]).iter_mut() {
112            *inner = Complex::zero();
113        }
114
115        // run our inner forward FFT
116        self.inner_fft
117            .process_with_scratch(inner_input, inner_scratch);
118
119        // Multiply our inner FFT output by our precomputed data. Then, conjugate the result to set up for an inverse FFT
120        for (inner, multiplier) in inner_input.iter_mut().zip(self.inner_fft_multiplier.iter()) {
121            *inner = (*inner * *multiplier).conj();
122        }
123
124        // inverse FFT. we're computing a forward but we're massaging it into an inverse by conjugating the inputs and outputs
125        self.inner_fft
126            .process_with_scratch(inner_input, inner_scratch);
127
128        // copy our data back to the buffer, applying twiddle factors again as we go. Also conjugate inner_input to complete the inverse FFT
129        for ((buffer_entry, inner_entry), twiddle) in input
130            .iter_mut()
131            .zip(inner_input.iter())
132            .zip(self.twiddles.iter())
133        {
134            *buffer_entry = inner_entry.conj() * twiddle;
135        }
136    }
137
138    #[inline]
139    fn perform_fft_immut(
140        &self,
141        input: &[Complex<T>],
142        output: &mut [Complex<T>],
143        scratch: &mut [Complex<T>],
144    ) {
145        let (inner_input, inner_scratch) = scratch.split_at_mut(self.inner_fft_multiplier.len());
146
147        // Copy the buffer into our inner FFT input. the buffer will only fill part of the FFT input, so zero fill the rest
148        for ((buffer_entry, inner_entry), twiddle) in input
149            .iter()
150            .zip(inner_input.iter_mut())
151            .zip(self.twiddles.iter())
152        {
153            *inner_entry = *buffer_entry * *twiddle;
154        }
155        for inner in inner_input.iter_mut().skip(input.len()) {
156            *inner = Complex::zero();
157        }
158
159        // run our inner forward FFT
160        self.inner_fft
161            .process_with_scratch(inner_input, inner_scratch);
162
163        // Multiply our inner FFT output by our precomputed data. Then, conjugate the result to set up for an inverse FFT
164        for (inner, multiplier) in inner_input.iter_mut().zip(self.inner_fft_multiplier.iter()) {
165            *inner = (*inner * *multiplier).conj();
166        }
167
168        // inverse FFT. we're computing a forward but we're massaging it into an inverse by conjugating the inputs and outputs
169        self.inner_fft
170            .process_with_scratch(inner_input, inner_scratch);
171
172        // copy our data back to the buffer, applying twiddle factors again as we go. Also conjugate inner_input to complete the inverse FFT
173        for ((buffer_entry, inner_entry), twiddle) in output
174            .iter_mut()
175            .zip(inner_input.iter())
176            .zip(self.twiddles.iter())
177        {
178            *buffer_entry = inner_entry.conj() * twiddle;
179        }
180    }
181
182    fn perform_fft_out_of_place(
183        &self,
184        input: &mut [Complex<T>],
185        output: &mut [Complex<T>],
186        scratch: &mut [Complex<T>],
187    ) {
188        self.perform_fft_immut(input, output, scratch);
189    }
190}
191boilerplate_fft!(
192    BluesteinsAlgorithm,
193    |this: &BluesteinsAlgorithm<_>| this.len, // FFT len
194    |this: &BluesteinsAlgorithm<_>| this.inner_fft_multiplier.len()
195        + this.inner_fft.get_inplace_scratch_len(), // in-place scratch len
196    |this: &BluesteinsAlgorithm<_>| this.inner_fft_multiplier.len()
197        + this.inner_fft.get_inplace_scratch_len(), // out of place scratch len
198    |this: &BluesteinsAlgorithm<_>| this.inner_fft_multiplier.len()
199        + this.inner_fft.get_inplace_scratch_len()  // immut scratch len
200);
201
202#[cfg(test)]
203mod unit_tests {
204    use super::*;
205    use crate::algorithm::Dft;
206    use crate::test_utils::check_fft_algorithm;
207    use std::sync::Arc;
208
209    #[test]
210    fn test_bluesteins_scalar() {
211        for &len in &[3, 5, 7, 11, 13] {
212            test_bluesteins_with_length(len, FftDirection::Forward);
213            test_bluesteins_with_length(len, FftDirection::Inverse);
214        }
215    }
216
217    fn test_bluesteins_with_length(len: usize, direction: FftDirection) {
218        let inner_fft = Arc::new(Dft::new(
219            (len * 2 - 1).checked_next_power_of_two().unwrap(),
220            direction,
221        ));
222        let fft = BluesteinsAlgorithm::new(len, inner_fft);
223
224        check_fft_algorithm::<f32>(&fft, len, direction);
225    }
226}
rustfft/algorithm/bluesteins_algorithm.rs

rustfft/algorithm/
bluesteins_algorithm.rs
