Debian Codegraph @

.cargo/vendor/rustfft/UpgradeGuide4to5.md

raw
1 # 4.0 to 5.0 Upgrade Guide
2 RustFFT 5.0 has several breaking changes compared to 4.0. This document will guide users through the upgrade process, explaining each breaking change and how to upgrade code to fit the new style.
3
4 Each section is ordered by how likely they are to impact you: Things at the top are likely to affect every user of RustFFT, while things at the bottom are unlikely to affect most users.
5
6 ## Renaming Structs
7 Several structs and traits in RustFFT were renamed to follow the [Rust API guidlines](https://rust-lang.github.io/api-guidelines/naming.html) regarding acronyms:
8
9 > In UpperCamelCase, acronyms and contractions of compound words count as one word: use Uuid rather than UUID, Usize rather than USize or Stdin rather than StdIn.
10
11 The following were renamed in RustFFT 5.0 to conform to this style:
12 * The `FFT` trait was renamed to `Fft`
13 * The `FFTnum` trait was renamed to `FftNum`
14 * The `FFTplanner` struct was renamed to `FftPlanner`
15 * The `DFT` struct was renamed to `Dft`
16
17 ## FFT Direction
18 In RustFFT 4.0, forward FFTs vs inverse FFTs were specified by a boolean. For example, the 4.0 `FFTplanner` constructor expects a boolean parameter for direction: If you pass `false`, the planner will plan forward FFTs. If you pass `true`, the planner will plan inverse FFTs.
19
20 In 5.0, there is a new `FftDirection` enum with `Forward` and `Inverse` variants. FFT algorithms that took a `bool` for direction now take `FftDirection` instead. For example, if you were constructing a `Radix4` instance to compute a power-of-two FFT, you will have to change the parameters to the constructor:
21
22 ```rust
23 // RustFFT 4.0
24 let fft_forward = Radix4::new(4096, false);
25 let fft_inverse = Radix4::new(4096, true);
26
27 // RustFFT 5.0
28 let fft_forward = Radix4::new(4096, FftDirection::Forward);
29 let fft_inverse = Radix4::new(4096, FftDirection::Inverse);
30 ```
31
32 A few traits and methods were renamed to support the new `FftDirection` trait:
33 * The `IsInverse` trait was renamed to `Direction`
34 * `IsInverse`'s only method, `is_inverse(&self) -> bool`, was renamed to `fft_direction(&self) -> FftDirection`
35 * The `Fft` trait inherited the `IsInverse` trait, and now inherits the `Direction` trait instead, so if you were calling `is_inverse()` on a `Fft` instance you'll have to change that to `fft_direction()` as well.
36
37 Finally, the way the `FftPlanner` handles forward vs inverse FFTs has changed. In 4.0, the `FFTplanner` took a direction in its constructor -- In 5.0, its constructor is empty, and it takes a direction in its `plan_fft` method. This means a single planner can be used to plan both forward and inverse FFTs.
38
39 The `FftPlanner` also has `plan_fft_forward` and `plan_fft_inverse` convenince methods so that you don't have to import the FftDirection enum.
40
41 ```rust
42 // RustFFT 4.0
43 let planner_forward = FFTplanner::new(false);
44 let fft_forward = planner.plan_fft(1234);
45
46 let planner_inverse = FFTplanner::new(true);
47 let fft_inverse = planner.plan_fft(1234);
48
49 // RustFFT 5.0
50 let planner = FftPlanner::new();
51
52 let fft_forward1 = planner.plan_fft(1234, FftDirection::Forward);
53 let fft_forward2 = planner.plan_fft_forward(1234);
54
55 let fft_inverse1 = planner.plan_fft(1234, FftDirection::Inverse);
56 let fft_inverse2 = planner.plan_fft_inverse(1234);
57 ```
58
59 ## Fft Trait Methods
60 In RustFFT 4.0, the `Fft` trait has two methods:
61 * `FFT::process()` took an input and output buffer, and computed a single FFT, storing the result in the output buffer.
62 * `FFT::process_multi()` took an input and output buffer, divided those buffers into chunks of size `fft.len()`, and computed a FFT on each chunk.
63
64 RustFFT 5.0 makes a few changes to this setup. First, there is no longer a distinction between "single" and "multi" FFT methods: All `Fft` trait methods compute multiple FFTs if provided a buffer whose length is a multiple of the FFT length.
65
66 Second, the `Fft` trait now has three methods. Most users will want the first method:
67 1. `Fft::process()` takes a single buffer instead of two, and computes FFTs in-place. Internally, it allocates scratch space as needed.
68 1. `Fft::process_with_scratch()` takes two buffers: A data buffer, and a scratch buffer. It computes FFTs in-place on the data buffer, using the provided scratch space as needed.
69 1. `Fft::process_outofplace_with_scratch()` takes three buffers: An input buffer, an output buffer, and a scratch buffer. It computes FFTs from the input buffer and stores the results in the output buffer, using the provided scratch space as needed.
70
71 Example for users who want to use the new in-place `process()` behavior:
72 ```rust
73 // RustFFT 4.0
74 let fft = Radix4::new(4096, false);
75
76 let mut input : Vec<Complex<f32>> = get_my_input_data();
77 let mut output = vec![Complex::zero(); fft.len()];
78 fft.process(&mut input, &mut output);
79
80 // RustFFT 5.0
81 let fft = Radix4::new(4096, FftDirection::Forward);
82
83 let mut buffer : Vec<Complex<f32>> = get_my_input_data();
84 fft.process(&mut buffer);
85 ```
86
87 Example for users who want to keep the old out-of-place `process()` behavior from RustFFT 4.0:
88 ```rust
89 // RustFFT 4.0
90 let fft = Radix4::new(4096, false);
91
92 let mut input : Vec<Complex<f32>> = get_my_input_data();
93 let mut output = vec![Complex::zero(); fft.len()];
94 fft.process(&mut input, &mut output);
95
96 // RustFFT 5.0
97 let fft = Radix4::new(4096, FftDirection::Forward);
98
99 let mut input : Vec<Complex<f32>> = get_my_input_data();
100 let mut output = vec![Complex::zero(); fft.len()];
101 let mut scratch = vec![Complex::zero(); fft.get_outofplace_scratch_len()];
102 fft.process_outofplace_with_scratch(&mut input, &mut output, &mut scratch);
103 ```
104
105 ## Rader's Algorithm Constructor
106 The constructor for `RadersAlgorithm` has changed. In RustFFT 4.0, its signature was `pub fn new(len: usize, inner_fft: Arc<dyn FFT<T>>)`, and it asserted that `len == inner_fft.len() + 1`
107
108 RustFFT 5.0 removes the `len: usize` parameter, and `RadersAlgorithm` derives its FFT length from the inner FFT length instead.
109
110 ```rust
111 // RustFFT 4.0
112 let inner_fft : Arc<dyn Fft<T>> = ...;
113 let fft = RadersAlgorithm::new(inner_fft.len() + 1, inner_fft);
114
115 // RustFFT 5.0
116 let inner_fft : Arc<dyn Fft<T>> = ...;
117 let fft = RadersAlgorithm::new(inner_fft);
118 ```
119
120 ## Deleted the `FFTButterfly` trait
121 In RustFFT 4.0, there was a trait called `FFTbutterfly`. This trait has been deleted. It had two methods which were merged into the `Fft` trait:
122 * `FFTButterfly::process_inplace` is replaced by `Fft::process_inplace` or `Fft::process_inplace_with_scratch`
123 * `FFTButterfly::process_multi_inplace` is replaced by `Fft::process_inplace_multi`
124
125 Two FFT algorithms relied on the deleted trait: `MixedRadixDoubleButterfly` and `GoodThomasAlgorithmDoubleButterfly`. They took `FFTbutterfly` trait objects in their constructor. They've been renamed to `MixedRadixSmall` and `GoodThomasAlgorithmSmall` respectively, and take `Fft` trait objects in their constructor.
126
127 ```rust
128 // RustFFT 4.0
129 let butterfly8 : Arc<dyn FFTbutterfly<T>> = Arc::new(Butterfly8::new(false));
130 let butterfly3 : Arc<dyn FFTbutterfly<T>> = Arc::new(Butterfly3::new(false));
131
132 let fft1 = MixedRadixDoubleButterfly::new(Arc::clone(&butterfly8), Arc::clone(&butterfly3));
133 let fft2 = GoodThomasAlgorithmDoubleButterfly::new(Arc::clone(&butterfly8), Arc::clone(&butterfly3));
134
135 // RustFFT 5.0
136 let butterfly8 : Arc<dyn Fft<T>> = Arc::new(Butterfly8::new(FftDirection::Forward));
137 let butterfly3 : Arc<dyn Fft<T>> = Arc::new(Butterfly3::new(FftDirection::Forward));
138
139 let fft1 = MixedRadixSmall::new(Arc::clone(&butterfly8), Arc::clone(&butterfly3));
140 let fft2 = GoodThomasAlgorithmSmall::new(Arc::clone(&butterfly8), Arc::clone(&butterfly3));
141 ```