mkl_fft -- a NumPy-based Python interface to Intel® oneAPI Math Kernel Library (oneMKL) Fourier Transform Functions

Introduction

mkl_fft is part of Intel® Distribution for Python* optimizations to NumPy. It offers a thin layered python interface to the Intel® oneAPI Math Kernel Library (oneMKL) Fourier Transform Functions that allows efficient access to computing a discrete Fourier transform through the fast Fourier transform (FFT) algorithm. As a result, its performance is close to the performance of native C/Intel® oneMKL. The optimizations are provided for real and complex data types in both single and double precisions for in-place and out-of-place modes of operation. For analyzing the performance use FFT benchmarks.

Thanks to Intel® oneMKL’s flexibility in its supports for arbitrarily strided input and output arrays both one-dimensional and multi-dimensional FFTs along distinct axes can be performed directly, without the need to copy the input into a contiguous array first. Furthermore, input strides can be arbitrary, including negative or zero, as long as strides remain an integer multiple of array’s item size, otherwise a copy will be made.

More details can be found in "Accelerating Scientific Python with Intel Optimizations" from Proceedings of the 16th Python in Science Conference (SciPy 2017).

Installation

mkl_fft can be installed into conda environment from Intel's channel using:

   conda install -c https://software.repos.intel.com/python/conda mkl_fft

or from conda-forge channel:

   conda install -c conda-forge mkl_fft

To install mkl_fft PyPI package please use the following command:

   python -m pip install --index-url https://software.repos.intel.com/python/pypi --extra-index-url https://pypi.org/simple mkl_fft

If command above installs NumPy package from the PyPI, please use following command to install Intel optimized NumPy wheel package from Intel PyPI Cloud:

   python -m pip install --index-url https://software.repos.intel.com/python/pypi --extra-index-url https://pypi.org/simple mkl_fft numpy==<numpy_version>

where <numpy_version> should be the latest version from https://software.repos.intel.com/python/conda/.

How to use?

mkl_fft.interfaces module

The recommended way to use mkl_fft package is through mkl_fft.interfaces module. These interfaces act as drop-in replacements for equivalent functions in NumPy and SciPy. Learn more about these interfaces here.

mkl_fft package

While using the interfaces module is the recommended way to leverage mk_fft, one can also use mkl_fft directly with the following FFT functions:

complex-to-complex (c2c) transforms:

fft(x, n=None, axis=-1, norm=None, out=None) - 1D FFT, similar to scipy.fft.fft

fft2(x, s=None, axes=(-2, -1), norm=None, out=None) - 2D FFT, similar to scipy.fft.fft2

fftn(x, s=None, axes=None, norm=None, out=None) - ND FFT, similar to scipy.fft.fftn

and similar inverse FFT (ifft*) functions.

real-to-complex (r2c) and complex-to-real (c2r) transforms:

rfft(x, n=None, axis=-1, norm=None, out=None) - r2c 1D FFT, similar to numpy.fft.rfft

rfft2(x, s=None, axes=(-2, -1), norm=None, out=None) - r2c 2D FFT, similar to numpy.fft.rfft2

rfftn(x, s=None, axes=None, norm=None, out=None) - r2c ND FFT, similar to numpy.fft.rfftn

and similar inverse c2r FFT (irfft*) functions.

The following example shows how to use mkl_fft for calculating a 1D FFT.

import numpy, mkl_fft
a = numpy.random.randn(10) + 1j*numpy.random.randn(10)

mkl_res = mkl_fft.fft(a)
np_res = numpy.fft.fft(a)
numpy.allclose(mkl_res, np_res)
# True

Patching Mechanisms

mkl_fft provides convenient patch methods to enable MKL-accelerated FFT operations in NumPy with or without modifying your code.

CLI Quickstart

Persistent patch (all Python sessions)

# Install
python -m mkl_fft --patch install

# Status (exit code: 0 = installed, 1 = not installed)
python -m mkl_fft --patch status

# Remove
python -m mkl_fft --patch uninstall

Verify current FFT backend

python -c "import numpy; print(f'numpy.fft.fft.__module__: {numpy.fft.fft.__module__}')"

One-shot patch (single command only)

# Script
python -m mkl_fft --with-numpy-patch my_script.py

# Pytest
python -m mkl_fft --with-numpy-patch -m pytest tests/

# One-liner
python -m mkl_fft --with-numpy-patch -c "import numpy; print(f\"numpy.fft.fft.__module__: {numpy.fft.fft.__module__}\")"

# Non-Python command
python -m mkl_fft --with-numpy-patch -- <command> [args...]

Programmatic Quickstart

import mkl_fft

mkl_fft.patch_numpy_fft()
print(mkl_fft.is_patched())
mkl_fft.restore_numpy_fft()

with mkl_fft.mkl_fft():
   pass

Building from source

A C compiler, Intel® oneAPI Math Kernel Library (oneMKL), and NumPy are required to build mkl_fft from source.

Executing

python -m pip install .

will pull in the required build dependencies, including mkl and numpy, and build mkl_fft.

If you already have mkl and numpy installed (from your system or a conda environment) and want to reuse them instead of pulling fresh copies into an isolated build, first install the build dependencies:

pip install meson-python cmake ninja "cython>=3.1.0" numpy mkl-devel

then build against the existing installation with:

python -m pip install --no-build-isolation --no-deps .

Optionally, install scipy to use the mkl_fft.interfaces.scipy_fft module:

pip install scipy

Contributing

See CONTRIBUTING.md for the development workflow: setting up a build environment, running the tests and lint hooks, code style, and what to include in a pull request.