0
# pyFFTW
1

2
A pythonic wrapper around FFTW 3, the high-performance FFT library. pyFFTW provides both complex DFT and real DFT support on arbitrary axes of arbitrary shaped and strided arrays, making it nearly feature-equivalent to numpy.fft while offering significantly better performance and additional precision support.
3

4
## Package Information
5

6
- **Package Name**: pyFFTW
7
- **Language**: Python
8
- **Installation**: `pip install pyfftw`
9
- **Version**: 0.15.0
10

11
## Core Imports
12

13
```python
14
import pyfftw
15
```
16

17
For direct access to the FFTW class and utilities:
18

19
```python
20
from pyfftw import FFTW, empty_aligned, zeros_aligned, ones_aligned
21
```
22

23
For numpy-like interfaces:
24

25
```python
26
from pyfftw.interfaces import numpy_fft
27
from pyfftw.interfaces import scipy_fft
28
```
29

30
## Basic Usage
31

32
```python
33
import pyfftw
34
import numpy as np
35

36
# Create aligned arrays for optimal performance
37
a = pyfftw.empty_aligned((128, 64), dtype='complex128')
38
b = pyfftw.empty_aligned((128, 64), dtype='complex128')
39

40
# Fill with sample data
41
a[:] = np.random.randn(128, 64) + 1j * np.random.randn(128, 64)
42

43
# Create FFTW object for 2D FFT
44
fft_object = pyfftw.FFTW(a, b, axes=(0, 1), direction='FFTW_FORWARD')
45

46
# Execute the transform
47
result = fft_object()
48

49
# Or use numpy-like interface for simpler usage
50
from pyfftw.interfaces import numpy_fft
51
result = numpy_fft.fft2(a)
52
```
53

54
## Architecture
55

56
pyFFTW is organized around several key components:
57

58
- **FFTW Class**: Core wrapper around FFTW plans, providing direct access to FFTW's performance
59
- **Builders Module**: Higher-level functions that create FFTW objects with numpy-like interfaces
60
- **Interfaces Module**: Drop-in replacements for numpy.fft, scipy.fft, and scipy.fftpack
61
- **Memory Management**: Aligned array utilities for optimal SIMD performance
62
- **Wisdom System**: Plan caching and optimization for repeated transforms
63

64
This architecture enables both high-performance direct usage and seamless integration with existing code using numpy/scipy FFT functions.
65

66
## Capabilities
67

68
### Core FFTW Interface
69

70
Direct access to FFTW functionality through the main FFTW class, providing maximum control over transform planning, execution, and memory management.
71

72
```python { .api }
73
class FFTW:
74
    def __init__(self, input_array, output_array, axes=(-1,), direction='FFTW_FORWARD', flags=('FFTW_MEASURE',), threads=1, planning_timelimit=None, normalise_idft=True, ortho=False): ...
75
    def __call__(self, input_array=None, output_array=None, normalise_idft=None, ortho=None): ...
76
    def update_arrays(self, new_input_array, new_output_array): ...
77
    def execute(self): ...
78
```
79

80
[Core FFTW Interface](./core-fftw.md)
81

82
### Memory Management and Alignment
83

84
Utilities for creating and managing aligned arrays to maximize SIMD performance, plus functions for checking alignment and converting existing arrays.
85

86
```python { .api }
87
def empty_aligned(shape, dtype='float64', order='C', n=None): ...
88
def zeros_aligned(shape, dtype='float64', order='C', n=None): ...
89
def ones_aligned(shape, dtype='float64', order='C', n=None): ...
90
def n_byte_align(array, n, dtype=None): ...
91
def byte_align(array, n=None, dtype=None): ...
92
def is_byte_aligned(array, n=None): ...
93
```
94

95
[Memory Management](./memory-management.md)
96

97
### FFT Builders
98

99
High-level functions that create FFTW objects with numpy-like signatures, supporting complex and real transforms in 1D, 2D, and N-D variants.
100

101
```python { .api }
102
def fft(a, n=None, axis=-1, overwrite_input=False, planner_effort='FFTW_ESTIMATE', threads=1): ...
103
def ifft(a, n=None, axis=-1, overwrite_input=False, planner_effort='FFTW_ESTIMATE', threads=1): ...
104
def rfft(a, n=None, axis=-1, overwrite_input=False, planner_effort='FFTW_ESTIMATE', threads=1): ...
105
def fft2(a, s=None, axes=(-2,-1), overwrite_input=False, planner_effort='FFTW_ESTIMATE', threads=1): ...
106
def fftn(a, s=None, axes=None, overwrite_input=False, planner_effort='FFTW_ESTIMATE', threads=1): ...
107
```
108

109
[FFT Builders](./fft-builders.md)
110

111
### numpy.fft Interface
112

113
Drop-in replacement for numpy.fft functions with additional optimization parameters, enabling existing code to benefit from FFTW performance with minimal changes.
114

115
```python { .api }
116
def fft(a, n=None, axis=-1, norm=None, overwrite_input=False, planner_effort='FFTW_ESTIMATE', threads=1): ...
117
def fft2(a, s=None, axes=(-2,-1), norm=None, overwrite_input=False, planner_effort='FFTW_ESTIMATE', threads=1): ...
118
def rfft(a, n=None, axis=-1, norm=None, overwrite_input=False, planner_effort='FFTW_ESTIMATE', threads=1): ...
119
def hfft(a, n=None, axis=-1, norm=None, overwrite_input=False, planner_effort='FFTW_ESTIMATE', threads=1): ...
120
```
121

122
[numpy.fft Interface](./numpy-fft-interface.md)
123

124
### scipy.fft Interface
125

126
Compatible interface for scipy.fft functions with FFTW backend, supporting the newer scipy FFT API including workers parameter and context manager compatibility.
127

128
```python { .api }
129
def fft(x, n=None, axis=-1, norm=None, overwrite_x=False, workers=None, plan=None): ...
130
def fft2(x, s=None, axes=(-2,-1), norm=None, overwrite_x=False, workers=None, plan=None): ...
131
def next_fast_len(target, real=False): ...
132
```
133

134
[scipy.fft Interface](./scipy-fft-interface.md)
135

136
### scipy.fftpack Interface (Legacy)
137

138
Drop-in replacement for scipy.fftpack functions with FFTW backend, including support for discrete cosine and sine transforms. This interface provides backward compatibility with legacy scipy.fftpack code.
139

140
```python { .api }
141
def fft(x, n=None, axis=-1, overwrite_x=False, planner_effort=None, threads=None): ...
142
def dct(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False, planner_effort=None, threads=None): ...
143
def dst(x, type=2, n=None, axis=-1, norm=None, overwrite_x=False, planner_effort=None, threads=None): ...
144
def dctn(x, type=2, shape=None, axes=None, norm=None, overwrite_x=False, planner_effort=None, threads=None): ...
145
```
146

147
[scipy.fftpack Interface](./scipy-fftpack-interface.md)
148

149
### Wisdom Management
150

151
Functions for importing, exporting, and managing FFTW wisdom to optimize transform planning across sessions and applications.
152

153
```python { .api }
154
def export_wisdom(): ...
155
def import_wisdom(wisdom): ...
156
def forget_wisdom(): ...
157
```
158

159
[Wisdom Management](./wisdom-management.md)
160

161
### Configuration and Utilities
162

163
Global configuration settings, utility functions for finding optimal transform sizes, and system information access.
164

165
```python { .api }
166
def next_fast_len(target): ...
167
# Configuration constants
168
simd_alignment: int
169
NUM_THREADS: int
170
PLANNER_EFFORT: str
171
```
172

173
[Configuration and Utilities](./configuration-utilities.md)
174

175
### Interface Performance Cache
176

177
Caching system for interface functions that stores FFTW objects to eliminate repeated planning overhead, providing significant performance improvements for repeated transforms.
178

179
```python { .api }
180
def enable(): ...
181
def disable(): ...
182
def is_enabled(): ...
183
def set_keepalive_time(keepalive_time): ...
184
```
185

186
[Interface Cache](./interfaces-cache.md)