polars-rfft

FFT as native Polars expressions. Built with Rust (RustFFT) and PyO3 for zero-copy, vectorized computation over Polars DataFrames.

Install

pip install polars-rfft

Quick start

import polars as pl
from polars_rfft import rfft

df = pl.DataFrame({"signal": [1.0, 0.0, -1.0, 0.0, 1.0, 0.0, -1.0, 0.0]})

# Forward FFT — returns struct {re, im}
df.with_columns(spectrum=rfft(pl.col("signal")).fft())

Roundtrip: FFT → IFFT

df.with_columns(
    recovered=rfft(rfft(pl.col("signal")).fft()).ifft_real()
)

Magnitude, phase, power spectrum

fft_expr = rfft(pl.col("signal")).fft()
df.with_columns(
    mag=rfft(fft_expr).magnitude(),
    phase=rfft(fft_expr).phase(),
    power=rfft(fft_expr).power_spectrum(),
)

Complex-valued input

df = pl.DataFrame({
    "z": [{"re": 1.0, "im": 0.0}, {"re": 0.0, "im": 1.0},
           {"re": -1.0, "im": 0.0}, {"re": 0.0, "im": -1.0}]
})
df.with_columns(spectrum=rfft(pl.col("z")).fft_complex())

API reference

Complex values are represented as struct columns with fields re (real) and im (imaginary).

All methods are accessed via the rfft() wrapper:

from polars_rfft import rfft

rfft(pl.col("signal")).fft()          # forward
rfft(pl.col("spectrum")).ifft()       # inverse
rfft(pl.col("spectrum")).magnitude()  # magnitude

Direct functions

For lower overhead on smaller signals, fft_direct and ifft_direct bypass the Polars expression engine and operate directly on Series:

from polars_rfft import fft_direct, ifft_direct

re, im = fft_direct(df["signal"])           # Series → (Series, Series)
re, im = ifft_direct(re, im)               # (Series, Series) → (Series, Series)

Performance

Benchmarked end-to-end against numpy on signals of varying length. Median of 7 runs after warmup.

Expression API (rfft().fft())

Direct API (fft_direct())

Bypasses Polars expression dispatch for ~0.1ms less overhead:

At small sizes (< 4K), numpy is faster due to its highly optimized C/Fortran backend. At 16K+ elements, RustFFT's radix algorithms dominate — up to 2.3x faster than numpy. The direct API eliminates ~0.1ms of Polars expression dispatch overhead, matching numpy at very small sizes.

Run it yourself:

pip install numpy
python benchmarks/bench_fft.py --sizes 1024 16384 262144 1048576

License

MIT