0
# Fast Fourier Transform (FFT)
1
2
GPU-accelerated Fast Fourier Transform operations using cuFFT for high-performance frequency domain analysis. CuPy provides comprehensive FFT functionality for real and complex transforms in 1D, 2D, and N-dimensional cases with significant performance improvements over CPU implementations.
3
4
## Capabilities
5
6
### 1D Complex Transforms
7
8
Standard complex FFT operations for frequency domain analysis of 1D signals.
9
10
```python { .api }
11
def fft(a, n=None, axis=-1, norm=None):
12
"""
13
Compute 1D discrete Fourier Transform.
14
15
Parameters:
16
- a: array_like, input array
17
- n: int, optional, length of transformed axis
18
- axis: int, optional, axis over which to compute FFT
19
- norm: {None, 'ortho'}, normalization mode
20
21
Returns:
22
- ndarray: Complex-valued transformed array
23
"""
24
25
def ifft(a, n=None, axis=-1, norm=None):
26
"""
27
Compute 1D inverse discrete Fourier Transform.
28
29
Parameters:
30
- a: array_like, input array
31
- n: int, optional, length of transformed axis
32
- axis: int, optional, axis over which to compute inverse FFT
33
- norm: {None, 'ortho'}, normalization mode
34
35
Returns:
36
- ndarray: Complex-valued inverse transformed array
37
"""
38
```
39
40
### 1D Real Transforms
41
42
Optimized FFT operations for real-valued input data with reduced memory usage and improved performance.
43
44
```python { .api }
45
def rfft(a, n=None, axis=-1, norm=None):
46
"""
47
Compute 1D FFT of real input.
48
49
Parameters:
50
- a: array_like, real-valued input array
51
- n: int, optional, length of transformed axis
52
- axis: int, optional, axis over which to compute FFT
53
- norm: {None, 'ortho'}, normalization mode
54
55
Returns:
56
- ndarray: Complex-valued FFT, only positive frequency components
57
58
Notes:
59
- Output length is n//2 + 1 for real transforms
60
- Exploits Hermitian symmetry for efficiency
61
"""
62
63
def irfft(a, n=None, axis=-1, norm=None):
64
"""
65
Compute inverse of rfft.
66
67
Parameters:
68
- a: array_like, complex-valued input from rfft
69
- n: int, optional, length of output axis
70
- axis: int, optional, axis over which to compute inverse FFT
71
- norm: {None, 'ortho'}, normalization mode
72
73
Returns:
74
- ndarray: Real-valued inverse transformed array
75
"""
76
```
77
78
### 1D Hermitian Transforms
79
80
Specialized transforms for Hermitian symmetric data.
81
82
```python { .api }
83
def hfft(a, n=None, axis=-1, norm=None):
84
"""
85
Compute FFT of signal with Hermitian symmetry.
86
87
Parameters:
88
- a: array_like, complex input with Hermitian symmetry
89
- n: int, optional, length of transformed axis
90
- axis: int, optional, axis over which to compute FFT
91
- norm: {None, 'ortho'}, normalization mode
92
93
Returns:
94
- ndarray: Real-valued transformed array
95
"""
96
97
def ihfft(a, n=None, axis=-1, norm=None):
98
"""
99
Compute inverse of hfft.
100
101
Parameters:
102
- a: array_like, real-valued input
103
- n: int, optional, length of transformed axis
104
- axis: int, optional, axis over which to compute inverse FFT
105
- norm: {None, 'ortho'}, normalization mode
106
107
Returns:
108
- ndarray: Complex-valued array with Hermitian symmetry
109
"""
110
```
111
112
### 2D Transforms
113
114
Multi-dimensional FFT operations for image processing and 2D signal analysis.
115
116
```python { .api }
117
def fft2(a, s=None, axes=(-2, -1), norm=None):
118
"""
119
Compute 2D discrete Fourier Transform.
120
121
Parameters:
122
- a: array_like, input array
123
- s: sequence of ints, optional, shape of result
124
- axes: sequence of ints, optional, axes over which to compute FFT
125
- norm: {None, 'ortho'}, normalization mode
126
127
Returns:
128
- ndarray: Complex-valued 2D transformed array
129
"""
130
131
def ifft2(a, s=None, axes=(-2, -1), norm=None):
132
"""
133
Compute 2D inverse discrete Fourier Transform.
134
135
Parameters:
136
- a: array_like, input array
137
- s: sequence of ints, optional, shape of result
138
- axes: sequence of ints, optional, axes over which to compute inverse FFT
139
- norm: {None, 'ortho'}, normalization mode
140
141
Returns:
142
- ndarray: Complex-valued 2D inverse transformed array
143
"""
144
145
def rfft2(a, s=None, axes=(-2, -1), norm=None):
146
"""
147
Compute 2D FFT of real input.
148
149
Parameters:
150
- a: array_like, real-valued input array
151
- s: sequence of ints, optional, shape of result
152
- axes: sequence of ints, optional, axes over which to compute FFT
153
- norm: {None, 'ortho'}, normalization mode
154
155
Returns:
156
- ndarray: Complex-valued 2D FFT with reduced last dimension
157
"""
158
159
def irfft2(a, s=None, axes=(-2, -1), norm=None):
160
"""
161
Compute inverse of rfft2.
162
163
Parameters:
164
- a: array_like, complex-valued input from rfft2
165
- s: sequence of ints, optional, shape of result
166
- axes: sequence of ints, optional, axes over which to compute inverse FFT
167
- norm: {None, 'ortho'}, normalization mode
168
169
Returns:
170
- ndarray: Real-valued 2D inverse transformed array
171
"""
172
```
173
174
### N-Dimensional Transforms
175
176
General N-dimensional FFT operations for multi-dimensional data analysis.
177
178
```python { .api }
179
def fftn(a, s=None, axes=None, norm=None):
180
"""
181
Compute N-dimensional discrete Fourier Transform.
182
183
Parameters:
184
- a: array_like, input array
185
- s: sequence of ints, optional, shape of result
186
- axes: sequence of ints, optional, axes over which to compute FFT
187
- norm: {None, 'ortho'}, normalization mode
188
189
Returns:
190
- ndarray: Complex-valued N-D transformed array
191
"""
192
193
def ifftn(a, s=None, axes=None, norm=None):
194
"""
195
Compute N-dimensional inverse discrete Fourier Transform.
196
197
Parameters:
198
- a: array_like, input array
199
- s: sequence of ints, optional, shape of result
200
- axes: sequence of ints, optional, axes over which to compute inverse FFT
201
- norm: {None, 'ortho'}, normalization mode
202
203
Returns:
204
- ndarray: Complex-valued N-D inverse transformed array
205
"""
206
207
def rfftn(a, s=None, axes=None, norm=None):
208
"""
209
Compute N-dimensional FFT of real input.
210
211
Parameters:
212
- a: array_like, real-valued input array
213
- s: sequence of ints, optional, shape of result
214
- axes: sequence of ints, optional, axes over which to compute FFT
215
- norm: {None, 'ortho'}, normalization mode
216
217
Returns:
218
- ndarray: Complex-valued N-D FFT with reduced last transformed dimension
219
"""
220
221
def irfftn(a, s=None, axes=None, norm=None):
222
"""
223
Compute inverse of rfftn.
224
225
Parameters:
226
- a: array_like, complex-valued input from rfftn
227
- s: sequence of ints, optional, shape of result
228
- axes: sequence of ints, optional, axes over which to compute inverse FFT
229
- norm: {None, 'ortho'}, normalization mode
230
231
Returns:
232
- ndarray: Real-valued N-D inverse transformed array
233
"""
234
```
235
236
### Helper Functions
237
238
Utility functions for frequency analysis and FFT result manipulation.
239
240
```python { .api }
241
def fftfreq(n, d=1.0):
242
"""
243
Return discrete Fourier Transform sample frequencies.
244
245
Parameters:
246
- n: int, window length
247
- d: scalar, optional, sample spacing (default: 1.0)
248
249
Returns:
250
- ndarray: Array of length n containing sample frequencies
251
252
Notes:
253
- Frequencies are in cycles per unit of sample spacing
254
- For even n: [..., -2, -1, 0, 1, 2, ...]
255
- For odd n: [..., -1, 0, 1, ...]
256
"""
257
258
def rfftfreq(n, d=1.0):
259
"""
260
Return sample frequencies for real FFT.
261
262
Parameters:
263
- n: int, window length
264
- d: scalar, optional, sample spacing (default: 1.0)
265
266
Returns:
267
- ndarray: Array of length n//2 + 1 containing positive sample frequencies
268
269
Notes:
270
- Only returns positive frequency components
271
- Length is n//2 + 1 to match rfft output
272
"""
273
274
def fftshift(x, axes=None):
275
"""
276
Shift zero-frequency component to center of spectrum.
277
278
Parameters:
279
- x: array_like, input array
280
- axes: int or shape tuple, optional, axes over which to shift
281
282
Returns:
283
- ndarray: Shifted array with zero-frequency at center
284
285
Notes:
286
- Swaps left and right halves of array
287
- Useful for visualization of FFT results
288
"""
289
290
def ifftshift(x, axes=None):
291
"""
292
Inverse of fftshift.
293
294
Parameters:
295
- x: array_like, input array
296
- axes: int or shape tuple, optional, axes over which to shift
297
298
Returns:
299
- ndarray: Array shifted back to original ordering
300
301
Notes:
302
- Undoes the effect of fftshift
303
- Prepares centered spectrum for FFT processing
304
"""
305
```
306
307
### FFT Configuration
308
309
Advanced configuration options for optimal performance tuning.
310
311
```python { .api }
312
# Configuration module for FFT planning and optimization
313
import cupy.fft.config
314
315
# Example configuration usage:
316
with cupy.fft.config.set_plan_cache_size(1024):
317
# FFT operations use larger plan cache
318
result = cupy.fft.fft2(large_array)
319
320
# Plan caching for repeated operations
321
plan = cupy.fft.config.get_current_plan()
322
# Reuse plan for multiple similar operations
323
```
324
325
### Usage Examples
326
327
#### 1D Signal Processing
328
329
```python
330
import cupy as cp
331
import cupy.fft
332
import numpy as np
333
334
# Generate sample signal
335
t = cp.linspace(0, 1, 1000, endpoint=False)
336
signal = cp.sin(2 * cp.pi * 50 * t) + 0.5 * cp.sin(2 * cp.pi * 120 * t)
337
signal += 0.1 * cp.random.randn(1000) # Add noise
338
339
# Compute FFT
340
fft_result = cupy.fft.fft(signal)
341
frequencies = cupy.fft.fftfreq(len(signal), d=1/1000)
342
343
# Filter low frequencies
344
fft_result[cp.abs(frequencies) > 100] = 0
345
346
# Inverse transform
347
filtered_signal = cupy.fft.ifft(fft_result).real
348
```
349
350
#### 2D Image Processing
351
352
```python
353
import cupy as cp
354
import cupy.fft
355
356
# Load or create 2D image data
357
image = cp.random.random((512, 512))
358
359
# Compute 2D FFT
360
fft_image = cupy.fft.fft2(image)
361
362
# Shift for visualization
363
fft_shifted = cupy.fft.fftshift(fft_image)
364
365
# Apply frequency domain filter (low-pass)
366
rows, cols = image.shape
367
crow, ccol = rows // 2, cols // 2
368
mask = cp.zeros((rows, cols), dtype=bool)
369
r = 50 # Radius for low-pass filter
370
y, x = cp.ogrid[:rows, :cols]
371
mask_area = (x - ccol) ** 2 + (y - crow) ** 2 <= r ** 2
372
mask[mask_area] = True
373
374
# Apply mask and inverse transform
375
fft_shifted[~mask] = 0
376
fft_filtered = cupy.fft.ifftshift(fft_shifted)
377
filtered_image = cupy.fft.ifft2(fft_filtered).real
378
```
379
380
#### Real-valued Data Optimization
381
382
```python
383
import cupy as cp
384
import cupy.fft
385
386
# For real-valued data, use rfft for better performance
387
real_signal = cp.random.randn(10000)
388
389
# Real FFT (more efficient for real input)
390
rfft_result = cupy.fft.rfft(real_signal)
391
print(f"Real FFT shape: {rfft_result.shape}") # Length is n//2 + 1
392
393
# Corresponding frequencies
394
rfreqs = cupy.fft.rfftfreq(len(real_signal))
395
396
# Process in frequency domain
397
# ... frequency domain operations ...
398
399
# Inverse transform back to real signal
400
reconstructed = cupy.fft.irfft(rfft_result)
401
```
402
403
#### Batch Processing
404
405
```python
406
import cupy as cp
407
import cupy.fft
408
409
# Process multiple signals simultaneously
410
batch_signals = cp.random.randn(100, 1024) # 100 signals, 1024 samples each
411
412
# FFT along last axis (axis=-1 is default)
413
batch_fft = cupy.fft.fft(batch_signals, axis=-1)
414
415
# Or process along first axis
416
batch_fft_axis0 = cupy.fft.fft(batch_signals, axis=0)
417
418
# 3D batch processing
419
volume_data = cp.random.randn(32, 64, 64)
420
volume_fft = cupy.fft.fftn(volume_data) # N-D FFT
421
```
422
423
#### Performance Optimization
424
425
```python
426
import cupy as cp
427
import cupy.fft
428
429
# For repeated operations on same size data,
430
# CuPy automatically caches FFT plans for better performance
431
432
# Warm up with first operation
433
data_size = (1024, 1024)
434
test_data = cp.random.randn(*data_size)
435
_ = cupy.fft.fft2(test_data) # Plan gets cached
436
437
# Subsequent operations reuse the cached plan
438
for i in range(100):
439
new_data = cp.random.randn(*data_size)
440
result = cupy.fft.fft2(new_data) # Uses cached plan - faster!
441
442
# Configure plan cache size for memory management
443
with cupy.fft.config.set_plan_cache_size(512):
444
# Operations within this block use larger plan cache
445
large_fft = cupy.fft.fft2(cp.random.randn(2048, 2048))
446
```
447
448
## Notes
449
450
- All FFT operations are performed on GPU using cuFFT, providing significant speedup over CPU implementations
451
- Plan caching automatically optimizes repeated operations on same-sized data
452
- Real transforms (rfft, irfft) are more memory and computationally efficient for real-valued data
453
- Multi-dimensional transforms can be computed over arbitrary axes
454
- Normalization options: None (no normalization), 'ortho' (orthogonal normalization)
455
- Large FFTs may require significant GPU memory; consider batch processing for memory-constrained environments
456
- For maximum performance on repeated operations, keep data sizes consistent to benefit from plan caching