0
# scipy.fftpack Interface
1

2
Drop-in replacement for scipy.fftpack functions with FFTW backend. This interface provides compatibility with the legacy scipy.fftpack module while offering FFTW's superior performance. Note that scipy.fftpack is considered legacy - new code should use scipy.fft instead.
3

4
**Warning:** scipy.fftpack is deprecated in favor of scipy.fft. This interface is provided for backward compatibility with existing code.
5

6
## Core Imports
7

8
```python
9
from pyfftw.interfaces import scipy_fftpack
10
```
11

12
Individual function imports:
13

14
```python
15
from pyfftw.interfaces.scipy_fftpack import fft, ifft, dct, dst
16
```
17

18
## Basic Usage
19

20
```python
21
from pyfftw.interfaces import scipy_fftpack
22
import numpy as np
23

24
# Create sample data
25
x = np.random.randn(128) + 1j * np.random.randn(128)
26

27
# FFT using scipy.fftpack interface with FFTW backend
28
y = scipy_fftpack.fft(x)
29

30
# Discrete Cosine Transform
31
real_data = np.random.randn(128)
32
dct_result = scipy_fftpack.dct(real_data, type=2, norm='ortho')
33

34
# Use additional FFTW parameters for optimization
35
fft_result = scipy_fftpack.fft(x, overwrite_x=True, 
36
                               planner_effort='FFTW_MEASURE', 
37
                               threads=4)
38
```
39

40
## Capabilities
41

42
### Complex FFT Functions
43

44
Standard complex FFT transforms compatible with scipy.fftpack interface.
45

46
```python { .api }
47
def fft(x, n=None, axis=-1, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
48
    """
49
    Perform an 1D FFT.
50

51
    Parameters:
52
    - x: array_like, input array
53
    - n: int, optional, length of the transform
54
    - axis: int, optional, axis over which to compute the FFT
55
    - overwrite_x: bool, optional, whether input can be overwritten
56
    - planner_effort: str, optional, FFTW planner effort ('FFTW_ESTIMATE', 'FFTW_MEASURE', 'FFTW_PATIENT', 'FFTW_EXHAUSTIVE')
57
    - threads: int, optional, number of threads to use
58
    - auto_align_input: bool, optional, automatically align input for optimal performance
59
    - auto_contiguous: bool, optional, ensure input is contiguous
60

61
    Returns:
62
    ndarray: Complex FFT result
63
    """
64

65
def ifft(x, n=None, axis=-1, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
66
    """
67
    Perform an 1D inverse FFT.
68

69
    Parameters:
70
    - x: array_like, input array
71
    - n: int, optional, length of the inverse transform
72
    - axis: int, optional, axis over which to compute the inverse FFT
73
    - overwrite_x: bool, optional, whether input can be overwritten
74
    - planner_effort: str, optional, FFTW planner effort
75
    - threads: int, optional, number of threads to use
76
    - auto_align_input: bool, optional, automatically align input
77
    - auto_contiguous: bool, optional, ensure input is contiguous
78

79
    Returns:
80
    ndarray: Complex inverse FFT result
81
    """
82

83
def fft2(x, shape=None, axes=(-2, -1), overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
84
    """
85
    Perform a 2D FFT.
86

87
    Parameters:
88
    - x: array_like, input array
89
    - shape: sequence of ints, optional, shape of the result
90
    - axes: sequence of ints, optional, axes over which to compute the FFT
91
    - overwrite_x: bool, optional, whether input can be overwritten
92
    - planner_effort: str, optional, FFTW planner effort
93
    - threads: int, optional, number of threads to use
94
    - auto_align_input: bool, optional, automatically align input
95
    - auto_contiguous: bool, optional, ensure input is contiguous
96

97
    Returns:
98
    ndarray: Complex 2D FFT result
99
    """
100

101
def ifft2(x, shape=None, axes=(-2, -1), overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
102
    """
103
    Perform a 2D inverse FFT.
104

105
    Parameters:
106
    - x: array_like, input array
107
    - shape: sequence of ints, optional, shape of the result
108
    - axes: sequence of ints, optional, axes over which to compute the inverse FFT
109
    - overwrite_x: bool, optional, whether input can be overwritten
110
    - planner_effort: str, optional, FFTW planner effort
111
    - threads: int, optional, number of threads to use
112
    - auto_align_input: bool, optional, automatically align input
113
    - auto_contiguous: bool, optional, ensure input is contiguous
114

115
    Returns:
116
    ndarray: Complex 2D inverse FFT result
117
    """
118

119
def fftn(x, shape=None, axes=None, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
120
    """
121
    Perform an N-dimensional FFT.
122

123
    Parameters:
124
    - x: array_like, input array
125
    - shape: sequence of ints, optional, shape of the result
126
    - axes: sequence of ints, optional, axes over which to compute the FFT
127
    - overwrite_x: bool, optional, whether input can be overwritten
128
    - planner_effort: str, optional, FFTW planner effort
129
    - threads: int, optional, number of threads to use
130
    - auto_align_input: bool, optional, automatically align input
131
    - auto_contiguous: bool, optional, ensure input is contiguous
132

133
    Returns:
134
    ndarray: Complex N-dimensional FFT result
135
    """
136

137
def ifftn(x, shape=None, axes=None, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
138
    """
139
    Perform an N-dimensional inverse FFT.
140

141
    Parameters:
142
    - x: array_like, input array
143
    - shape: sequence of ints, optional, shape of the result
144
    - axes: sequence of ints, optional, axes over which to compute the inverse FFT
145
    - overwrite_x: bool, optional, whether input can be overwritten
146
    - planner_effort: str, optional, FFTW planner effort
147
    - threads: int, optional, number of threads to use
148
    - auto_align_input: bool, optional, automatically align input
149
    - auto_contiguous: bool, optional, ensure input is contiguous
150

151
    Returns:
152
    ndarray: Complex N-dimensional inverse FFT result
153
    """
154
```
155

156
### Real FFT Functions
157

158
Real-to-complex and complex-to-real FFT transforms.
159

160
```python { .api }
161
def rfft(x, n=None, axis=-1, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
162
    """
163
    Perform a real-input FFT.
164

165
    Parameters:
166
    - x: array_like, real input array
167
    - n: int, optional, length of the transform
168
    - axis: int, optional, axis over which to compute the FFT
169
    - overwrite_x: bool, optional, whether input can be overwritten
170
    - planner_effort: str, optional, FFTW planner effort
171
    - threads: int, optional, number of threads to use
172
    - auto_align_input: bool, optional, automatically align input
173
    - auto_contiguous: bool, optional, ensure input is contiguous
174

175
    Returns:
176
    ndarray: Complex FFT result with conjugate symmetry
177
    """
178

179
def irfft(x, n=None, axis=-1, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
180
    """
181
    Perform an inverse real-input FFT.
182

183
    Parameters:
184
    - x: array_like, complex input array with conjugate symmetry
185
    - n: int, optional, length of the inverse transform
186
    - axis: int, optional, axis over which to compute the inverse FFT
187
    - overwrite_x: bool, optional, whether input can be overwritten
188
    - planner_effort: str, optional, FFTW planner effort
189
    - threads: int, optional, number of threads to use
190
    - auto_align_input: bool, optional, automatically align input
191
    - auto_contiguous: bool, optional, ensure input is contiguous
192

193
    Returns:
194
    ndarray: Real inverse FFT result
195
    """
196
```
197

198
### Discrete Cosine Transform (DCT)
199

200
Discrete Cosine Transform functions with multiple types and normalization options.
201

202
```python { .api }
203
def dct(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
204
    """
205
    Perform a discrete cosine transform.
206

207
    Parameters:
208
    - x: array_like, input array
209
    - type: int, optional, DCT type (1, 2, 3, or 4), default is 2
210
    - n: int, optional, length of the transform
211
    - axis: int, optional, axis over which to compute the DCT
212
    - norm: str, optional, normalization mode (None or 'ortho')
213
    - overwrite_x: bool, optional, whether input can be overwritten
214
    - planner_effort: str, optional, FFTW planner effort
215
    - threads: int, optional, number of threads to use
216
    - auto_align_input: bool, optional, automatically align input
217
    - auto_contiguous: bool, optional, ensure input is contiguous
218

219
    Returns:
220
    ndarray: DCT result
221
    """
222

223
def idct(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
224
    """
225
    Perform an inverse discrete cosine transform.
226

227
    Parameters:
228
    - x: array_like, input array
229
    - type: int, optional, DCT type (1, 2, 3, or 4), default is 2
230
    - n: int, optional, length of the inverse transform
231
    - axis: int, optional, axis over which to compute the inverse DCT
232
    - norm: str, optional, normalization mode (None or 'ortho')
233
    - overwrite_x: bool, optional, whether input can be overwritten
234
    - planner_effort: str, optional, FFTW planner effort
235
    - threads: int, optional, number of threads to use
236
    - auto_align_input: bool, optional, automatically align input
237
    - auto_contiguous: bool, optional, ensure input is contiguous
238

239
    Returns:
240
    ndarray: Inverse DCT result
241
    """
242

243
def dctn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
244
    """
245
    Perform an N-dimensional discrete cosine transform.
246

247
    Parameters:
248
    - x: array_like, input array
249
    - type: int, optional, DCT type (1, 2, 3, or 4), default is 2
250
    - shape: sequence of ints, optional, shape of the result
251
    - axes: sequence of ints, optional, axes over which to compute the DCT
252
    - norm: str, optional, normalization mode (None or 'ortho')
253
    - overwrite_x: bool, optional, whether input can be overwritten
254
    - planner_effort: str, optional, FFTW planner effort
255
    - threads: int, optional, number of threads to use
256
    - auto_align_input: bool, optional, automatically align input
257
    - auto_contiguous: bool, optional, ensure input is contiguous
258

259
    Returns:
260
    ndarray: N-dimensional DCT result
261
    """
262

263
def idctn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
264
    """
265
    Perform an N-dimensional inverse discrete cosine transform.
266

267
    Parameters:
268
    - x: array_like, input array
269
    - type: int, optional, DCT type (1, 2, 3, or 4), default is 2
270
    - shape: sequence of ints, optional, shape of the result
271
    - axes: sequence of ints, optional, axes over which to compute the inverse DCT
272
    - norm: str, optional, normalization mode (None or 'ortho')
273
    - overwrite_x: bool, optional, whether input can be overwritten
274
    - planner_effort: str, optional, FFTW planner effort
275
    - threads: int, optional, number of threads to use
276
    - auto_align_input: bool, optional, automatically align input
277
    - auto_contiguous: bool, optional, ensure input is contiguous
278

279
    Returns:
280
    ndarray: N-dimensional inverse DCT result
281
    """
282
```
283

284
### Discrete Sine Transform (DST)
285

286
Discrete Sine Transform functions with multiple types and normalization options.
287

288
```python { .api }
289
def dst(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
290
    """
291
    Perform a discrete sine transform.
292

293
    Parameters:
294
    - x: array_like, input array
295
    - type: int, optional, DST type (1, 2, 3, or 4), default is 2
296
    - n: int, optional, length of the transform
297
    - axis: int, optional, axis over which to compute the DST
298
    - norm: str, optional, normalization mode (None or 'ortho')
299
    - overwrite_x: bool, optional, whether input can be overwritten
300
    - planner_effort: str, optional, FFTW planner effort
301
    - threads: int, optional, number of threads to use
302
    - auto_align_input: bool, optional, automatically align input
303
    - auto_contiguous: bool, optional, ensure input is contiguous
304

305
    Returns:
306
    ndarray: DST result
307
    """
308

309
def idst(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
310
    """
311
    Perform an inverse discrete sine transform.
312

313
    Parameters:
314
    - x: array_like, input array
315
    - type: int, optional, DST type (1, 2, 3, or 4), default is 2
316
    - n: int, optional, length of the inverse transform
317
    - axis: int, optional, axis over which to compute the inverse DST
318
    - norm: str, optional, normalization mode (None or 'ortho')
319
    - overwrite_x: bool, optional, whether input can be overwritten
320
    - planner_effort: str, optional, FFTW planner effort
321
    - threads: int, optional, number of threads to use
322
    - auto_align_input: bool, optional, automatically align input
323
    - auto_contiguous: bool, optional, ensure input is contiguous
324

325
    Returns:
326
    ndarray: Inverse DST result
327
    """
328

329
def dstn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
330
    """
331
    Perform an N-dimensional discrete sine transform.
332

333
    Parameters:
334
    - x: array_like, input array
335
    - type: int, optional, DST type (1, 2, 3, or 4), default is 2
336
    - shape: sequence of ints, optional, shape of the result
337
    - axes: sequence of ints, optional, axes over which to compute the DST
338
    - norm: str, optional, normalization mode (None or 'ortho')
339
    - overwrite_x: bool, optional, whether input can be overwritten
340
    - planner_effort: str, optional, FFTW planner effort
341
    - threads: int, optional, number of threads to use
342
    - auto_align_input: bool, optional, automatically align input
343
    - auto_contiguous: bool, optional, ensure input is contiguous
344

345
    Returns:
346
    ndarray: N-dimensional DST result
347
    """
348

349
def idstn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False, planner_effort=None, threads=None, auto_align_input=True, auto_contiguous=True):
350
    """
351
    Perform an N-dimensional inverse discrete sine transform.
352

353
    Parameters:
354
    - x: array_like, input array
355
    - type: int, optional, DST type (1, 2, 3, or 4), default is 2
356
    - shape: sequence of ints, optional, shape of the result
357
    - axes: sequence of ints, optional, axes over which to compute the inverse DST
358
    - norm: str, optional, normalization mode (None or 'ortho')
359
    - overwrite_x: bool, optional, whether input can be overwritten
360
    - planner_effort: str, optional, FFTW planner effort
361
    - threads: int, optional, number of threads to use
362
    - auto_align_input: bool, optional, automatically align input
363
    - auto_contiguous: bool, optional, ensure input is contiguous
364

365
    Returns:
366
    ndarray: N-dimensional inverse DST result
367
    """
368
```
369

370
### Utility Functions
371

372
Additional utility functions provided by the interface.
373

374
```python { .api }
375
def next_fast_len(target):
376
    """
377
    Find the next fast size of input data to fft, for zero-padding, etc.
378

379
    Parameters:
380
    - target: int, target transform length
381

382
    Returns:
383
    int: Next fast length >= target
384
    """
385
```
386

387
## Usage Examples
388

389
### Legacy Code Migration
390

391
```python
392
# Original scipy.fftpack code
393
import scipy.fftpack as fftpack
394
result = fftpack.fft(data)
395

396
# Drop-in replacement with FFTW backend
397
from pyfftw.interfaces import scipy_fftpack as fftpack
398
result = fftpack.fft(data)  # Now uses FFTW backend
399
```
400

401
### DCT/DST Usage
402

403
```python
404
from pyfftw.interfaces import scipy_fftpack
405
import numpy as np
406

407
# Image compression example with DCT
408
image = np.random.randn(64, 64)
409
dct_coeffs = scipy_fftpack.dctn(image, type=2, norm='ortho')
410
reconstructed = scipy_fftpack.idctn(dct_coeffs, type=2, norm='ortho')
411

412
# Signal processing with DST
413
signal = np.random.randn(256)
414
dst_coeffs = scipy_fftpack.dst(signal, type=1)
415
original = scipy_fftpack.idst(dst_coeffs, type=1)
416
```
417

418
### Performance Optimization
419

420
```python
421
# Use FFTW-specific parameters for better performance
422
result = scipy_fftpack.fft(data, 
423
                          overwrite_x=True,        # Allow input modification
424
                          planner_effort='FFTW_PATIENT',  # Better planning
425
                          threads=8,               # Multi-threading
426
                          auto_align_input=True)   # Optimal alignment
427
```