betterfftw 0.1.3
High-performance, user-friendly wrapper for FFTW in Python
Requires Python: >=3.7

[![PyPI version](https://badge.fury.io/py/betterfftw.svg)](https://badge.fury.io/py/betterfftw)  
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

# BetterFFTW

BetterFFTW is a thin, high-performance wrapper around [pyFFTW](https://github.com/pyFFTW/pyFFTW) that makes it easier to use FFTW in Python with optimized default settings and automatic performance tuning.

## About

BetterFFTW provides drop‑in replacements for NumPy and SciPy FFT routines. It aims to simplify FFTW’s complex configuration by automatically choosing settings (such as threading counts, FFTW planning strategies, and plan caching) that yield faster performance in many cases. In short, BetterFFTW makes it easier to harness FFTW’s speed in Python without manually tweaking countless parameters.

That said, the library has its limitations. The performance numbers shown in benchmarks are based only on execution time and do not include the planning overhead. This means that if you are performing a transform only once or a few times, the planning phase may negate most of the speed gains. The benefits become clear only when FFT plans are reused repeatedly, which is how FFTW is designed to be used.

## Key Improvements

- **Optimized Defaults:**  
  The wrapper automatically selects the number of threads and FFTW planning strategy (starting with fast planning like FFTW_ESTIMATE and, for repeated use, upgrading to more thorough strategies such as FFTW_MEASURE). These defaults work well when the same FFT configuration is used multiple times.

- **Automatic Plan Caching and Reuse:**  
  BetterFFTW caches FFTW plans based on array shape, data type, and transform parameters. This cache reuse is key to achieving speedup on repeated transforms, but note that a one-off transform can suffer from planning overhead.

- **Fallback to NumPy:**  
  In situations where an FFTW plan is not yet amortized or where NumPy’s FFT performs better for a given configuration, BetterFFTW will automatically fall back to NumPy’s implementation to give you the best performance available under the circumstances.

- **Improved Handling of Non-Power-of-2 Sizes:**  
  BetterFFTW applies tailored strategies for non‑power‑of‑2 dimensions – a challenging area for FFT implementations – although these cases are not magic and still require plan reuse to see the benefit.

## Installation

BetterFFTW is available on PyPI and can be installed using pip:

```bash
pip install betterfftw
```

## Usage

BetterFFTW is designed to replace NumPy’s FFT routines with little to no code modification. To enable BetterFFTW’s FFT routines as the default, simply register it:

```python
import betterfftw

# Register BetterFFTW as the default FFT backend for both NumPy and SciPy
betterfftw.use_as_default()

import numpy as np
x = np.random.random(1024)
y = np.fft.fft(x)  # This now uses BetterFFTW
```

For more advanced scenarios, you can call the functions directly (e.g., `betterfftw.fft`, `betterfftw.ifft2`, etc.) to control parameters such as the number of threads or planning strategy. However, I would recommend using the pyFFTW library for this instead.

## Performance Notes

BetterFFTW can provide significant speed improvements over the default NumPy or SciPy FFT routines—especially for large, multi-dimensional arrays and when the same transform configuration is used repeatedly. Benchmarks (which do not account for FFT planning time) show impressive speedups; however, users should note:

- **Planning Overhead:**  
  The planning phase can take time, so one-off transforms may not be faster. The performance gains come from amortizing the planning cost over many FFTs.

- **Repetition is Key:**  
  BetterFFTW is most effective when you perform the same transform repeatedly, allowing the expensive planning phase to be paid off over many executions.

- **Fallbacks:**  
  In configurations where the FFTW plan is not yet amortized or isn’t optimal, BetterFFTW will revert to using NumPy’s FFT to avoid degraded performance.

## Credits

BetterFFTW builds on the work of [pyFFTW](https://github.com/pyFFTW/pyFFTW) and the [FFTW C library](http://www.fftw.org/). I am very grateful to the creators and maintainers of both these excellent projects.

## License

This project is licensed under the GPL-3.0 License. See the LICENSE file for details.

## Repository

The source code and issue tracker are hosted on GitHub:  
https://github.com/sebastian-griego/BetterFFTW