0
# FFT Builders
1
2
High-level functions that create FFTW objects with numpy-like signatures, supporting complex and real transforms in 1D, 2D, and N-D variants. These functions provide a convenient middle ground between the direct FFTW interface and the drop-in replacement interfaces.
3
4
## Capabilities
5
6
### 1D Transform Builders
7
8
Functions that create FFTW objects for 1D transforms.
9
10
```python { .api }
11
def fft(
12
a,
13
n=None,
14
axis=-1,
15
overwrite_input=False,
16
planner_effort='FFTW_ESTIMATE',
17
threads=1,
18
auto_align_input=True,
19
auto_contiguous=True,
20
avoid_copy=False,
21
norm=None
22
):
23
"""
24
Return an FFTW object for 1D complex-to-complex FFT.
25
26
Parameters:
27
- a: Input array
28
- n: Length of transform (default: a.shape[axis])
29
- axis: Axis over which to compute FFT (default: -1)
30
- overwrite_input: Whether to overwrite input (default: False)
31
- planner_effort: FFTW planner effort (default: 'FFTW_ESTIMATE')
32
- threads: Number of threads (default: 1)
33
- auto_align_input: Auto-align input for SIMD (default: True)
34
- auto_contiguous: Make input contiguous (default: True)
35
- avoid_copy: Avoid copying when possible (default: False)
36
- norm: Normalization mode (default: None)
37
38
Returns:
39
- FFTW object that performs the transform
40
"""
41
42
def ifft(
43
a,
44
n=None,
45
axis=-1,
46
overwrite_input=False,
47
planner_effort='FFTW_ESTIMATE',
48
threads=1,
49
auto_align_input=True,
50
auto_contiguous=True,
51
avoid_copy=False,
52
norm=None
53
):
54
"""
55
Return an FFTW object for 1D inverse complex-to-complex FFT.
56
57
Parameters: Same as fft()
58
59
Returns:
60
- FFTW object that performs the inverse transform
61
"""
62
63
def rfft(
64
a,
65
n=None,
66
axis=-1,
67
overwrite_input=False,
68
planner_effort='FFTW_ESTIMATE',
69
threads=1,
70
auto_align_input=True,
71
auto_contiguous=True,
72
avoid_copy=False,
73
norm=None
74
):
75
"""
76
Return an FFTW object for 1D real-to-complex FFT.
77
78
Parameters: Same as fft()
79
80
Returns:
81
- FFTW object that performs real-to-complex transform
82
"""
83
84
def irfft(
85
a,
86
n=None,
87
axis=-1,
88
overwrite_input=False,
89
planner_effort='FFTW_ESTIMATE',
90
threads=1,
91
auto_align_input=True,
92
auto_contiguous=True,
93
avoid_copy=False,
94
norm=None
95
):
96
"""
97
Return an FFTW object for 1D complex-to-real FFT.
98
99
Parameters: Same as fft()
100
101
Returns:
102
- FFTW object that performs complex-to-real transform
103
"""
104
```
105
106
### 2D Transform Builders
107
108
Functions that create FFTW objects for 2D transforms.
109
110
```python { .api }
111
def fft2(
112
a,
113
s=None,
114
axes=(-2, -1),
115
overwrite_input=False,
116
planner_effort='FFTW_ESTIMATE',
117
threads=1,
118
auto_align_input=True,
119
auto_contiguous=True,
120
avoid_copy=False,
121
norm=None
122
):
123
"""
124
Return an FFTW object for 2D complex-to-complex FFT.
125
126
Parameters:
127
- a: Input array
128
- s: Shape of transform (default: a.shape[axes])
129
- axes: Axes over which to compute FFT (default: (-2, -1))
130
- Other parameters: Same as fft()
131
132
Returns:
133
- FFTW object that performs 2D transform
134
"""
135
136
def ifft2(
137
a,
138
s=None,
139
axes=(-2, -1),
140
overwrite_input=False,
141
planner_effort='FFTW_ESTIMATE',
142
threads=1,
143
auto_align_input=True,
144
auto_contiguous=True,
145
avoid_copy=False,
146
norm=None
147
):
148
"""
149
Return an FFTW object for 2D inverse complex-to-complex FFT.
150
151
Parameters: Same as fft2()
152
153
Returns:
154
- FFTW object that performs 2D inverse transform
155
"""
156
157
def rfft2(
158
a,
159
s=None,
160
axes=(-2, -1),
161
overwrite_input=False,
162
planner_effort='FFTW_ESTIMATE',
163
threads=1,
164
auto_align_input=True,
165
auto_contiguous=True,
166
avoid_copy=False,
167
norm=None
168
):
169
"""
170
Return an FFTW object for 2D real-to-complex FFT.
171
172
Parameters: Same as fft2()
173
174
Returns:
175
- FFTW object that performs 2D real-to-complex transform
176
"""
177
178
def irfft2(
179
a,
180
s=None,
181
axes=(-2, -1),
182
overwrite_input=False,
183
planner_effort='FFTW_ESTIMATE',
184
threads=1,
185
auto_align_input=True,
186
auto_contiguous=True,
187
avoid_copy=False,
188
norm=None
189
):
190
"""
191
Return an FFTW object for 2D complex-to-real FFT.
192
193
Parameters: Same as fft2()
194
195
Returns:
196
- FFTW object that performs 2D complex-to-real transform
197
"""
198
```
199
200
### N-D Transform Builders
201
202
Functions that create FFTW objects for N-dimensional transforms.
203
204
```python { .api }
205
def fftn(
206
a,
207
s=None,
208
axes=None,
209
overwrite_input=False,
210
planner_effort='FFTW_ESTIMATE',
211
threads=1,
212
auto_align_input=True,
213
auto_contiguous=True,
214
avoid_copy=False,
215
norm=None
216
):
217
"""
218
Return an FFTW object for N-D complex-to-complex FFT.
219
220
Parameters:
221
- a: Input array
222
- s: Shape of transform (default: a.shape[axes])
223
- axes: Axes over which to compute FFT (default: all axes)
224
- Other parameters: Same as fft()
225
226
Returns:
227
- FFTW object that performs N-D transform
228
"""
229
230
def ifftn(
231
a,
232
s=None,
233
axes=None,
234
overwrite_input=False,
235
planner_effort='FFTW_ESTIMATE',
236
threads=1,
237
auto_align_input=True,
238
auto_contiguous=True,
239
avoid_copy=False,
240
norm=None
241
):
242
"""
243
Return an FFTW object for N-D inverse complex-to-complex FFT.
244
245
Parameters: Same as fftn()
246
247
Returns:
248
- FFTW object that performs N-D inverse transform
249
"""
250
251
def rfftn(
252
a,
253
s=None,
254
axes=None,
255
overwrite_input=False,
256
planner_effort='FFTW_ESTIMATE',
257
threads=1,
258
auto_align_input=True,
259
auto_contiguous=True,
260
avoid_copy=False,
261
norm=None
262
):
263
"""
264
Return an FFTW object for N-D real-to-complex FFT.
265
266
Parameters: Same as fftn()
267
268
Returns:
269
- FFTW object that performs N-D real-to-complex transform
270
"""
271
272
def irfftn(
273
a,
274
s=None,
275
axes=None,
276
overwrite_input=False,
277
planner_effort='FFTW_ESTIMATE',
278
threads=1,
279
auto_align_input=True,
280
auto_contiguous=True,
281
avoid_copy=False,
282
norm=None
283
):
284
"""
285
Return an FFTW object for N-D complex-to-real FFT.
286
287
Parameters: Same as fftn()
288
289
Returns:
290
- FFTW object that performs N-D complex-to-real transform
291
"""
292
```
293
294
### Discrete Cosine/Sine Transform Builders
295
296
Functions for creating discrete cosine and sine transform objects.
297
298
```python { .api }
299
def dct(
300
a,
301
n=None,
302
axis=-1,
303
overwrite_input=False,
304
planner_effort='FFTW_ESTIMATE',
305
threads=1,
306
auto_align_input=True,
307
auto_contiguous=True,
308
avoid_copy=False,
309
norm=None,
310
type=2
311
):
312
"""
313
Return an FFTW object for discrete cosine transform.
314
315
Parameters:
316
- type: DCT type (1, 2, 3, or 4)
317
- Other parameters: Same as fft()
318
319
Returns:
320
- FFTW object that performs DCT
321
"""
322
323
def dst(
324
a,
325
n=None,
326
axis=-1,
327
overwrite_input=False,
328
planner_effort='FFTW_ESTIMATE',
329
threads=1,
330
auto_align_input=True,
331
auto_contiguous=True,
332
avoid_copy=False,
333
norm=None,
334
type=2
335
):
336
"""
337
Return an FFTW object for discrete sine transform.
338
339
Parameters:
340
- type: DST type (1, 2, 3, or 4)
341
- Other parameters: Same as fft()
342
343
Returns:
344
- FFTW object that performs DST
345
"""
346
```
347
348
## Usage Examples
349
350
### Basic 1D Transform
351
352
```python
353
import numpy as np
354
import pyfftw.builders as builders
355
356
# Create input data
357
a = np.random.randn(1024) + 1j * np.random.randn(1024)
358
359
# Create FFTW object
360
fft_obj = builders.fft(a, planner_effort='FFTW_MEASURE', threads=4)
361
362
# Execute transform multiple times
363
for i in range(10):
364
# Update input data
365
a[:] = np.random.randn(1024) + 1j * np.random.randn(1024)
366
367
# Execute (reuses existing plan)
368
result = fft_obj(a)
369
```
370
371
### 2D Real-to-Complex Transform
372
373
```python
374
import numpy as np
375
import pyfftw.builders as builders
376
377
# Create real input data
378
real_data = np.random.randn(512, 256)
379
380
# Create FFTW object for 2D real FFT
381
rfft2_obj = builders.rfft2(
382
real_data,
383
planner_effort='FFTW_PATIENT',
384
threads=2,
385
auto_align_input=True
386
)
387
388
# Execute transform
389
result = rfft2_obj()
390
print(f"Input shape: {real_data.shape}")
391
print(f"Output shape: {result.shape}") # (512, 129) - note the reduced last dimension
392
```
393
394
### N-D Transform with Custom Axes
395
396
```python
397
import numpy as np
398
import pyfftw.builders as builders
399
400
# Create 4D data
401
data = np.random.randn(64, 32, 128, 256) + 1j * np.random.randn(64, 32, 128, 256)
402
403
# Transform only the last two dimensions
404
fftn_obj = builders.fftn(
405
data,
406
axes=(-2, -1),
407
planner_effort='FFTW_MEASURE',
408
threads=4
409
)
410
411
result = fftn_obj()
412
print(f"Transformed axes: {(-2, -1)}")
413
print(f"Result shape: {result.shape}") # Same as input shape
414
```
415
416
### Discrete Cosine Transform
417
418
```python
419
import numpy as np
420
import pyfftw.builders as builders
421
422
# Create real data
423
data = np.random.randn(1024)
424
425
# Create DCT-II object (most common type)
426
dct_obj = builders.dct(data, type=2, planner_effort='FFTW_MEASURE')
427
428
# Execute DCT
429
result = dct_obj()
430
431
# Create inverse DCT (DCT-III)
432
idct_obj = builders.dct(result, type=3, planner_effort='FFTW_MEASURE')
433
reconstructed = idct_obj() / len(data) # Normalize for perfect reconstruction
434
435
print(f"Reconstruction error: {np.max(np.abs(data - reconstructed))}")
436
```
437
438
### Performance Optimization
439
440
```python
441
import numpy as np
442
import pyfftw.builders as builders
443
import time
444
445
# Create large dataset
446
N = 1024 * 1024
447
data = np.random.randn(N) + 1j * np.random.randn(N)
448
449
# Compare different planning efforts
450
efforts = ['FFTW_ESTIMATE', 'FFTW_MEASURE', 'FFTW_PATIENT']
451
results = {}
452
453
for effort in efforts:
454
# Time planning
455
start = time.time()
456
fft_obj = builders.fft(data, planner_effort=effort, threads=4)
457
plan_time = time.time() - start
458
459
# Time execution
460
start = time.time()
461
for _ in range(100):
462
result = fft_obj()
463
exec_time = time.time() - start
464
465
results[effort] = {'plan': plan_time, 'exec': exec_time}
466
print(f"{effort}: Plan {plan_time:.3f}s, Execute {exec_time:.3f}s")
467
```