fft_backend.hpp

Go to the documentation of this file.

#pragma once
 
// Multi-backend FFT — runtime-selectable wrapper around pulp::signal::Fft.
//
// Backends:
//   - vdsp     : Apple Accelerate.framework (always available on Apple)
//   - kissfft  : built-in radix-2 fallback (always available, header-only).
//                The public backend name stays stable even though the shipping
//                implementation is the hand-rolled radix-2 Cooley-Tukey in
//                pulp::signal::Fft, so callers do not have to track
//                implementation changes.
//   - fftw3   : libfftw3f loaded via dlopen at runtime (optional)
//   - mkl     : Intel MKL libmkl_rt loaded via dlopen at runtime (optional)
//
// Both fftw3 and mkl are loaded lazily — no link-time dependency. If the
// shared library is not installed on the runtime machine, the selector
// falls back to vDSP (on Apple) or kissfft.
//
// Backend selection precedence (highest wins):
//   1. Explicit MultiBackendFft(size, FftBackend::X) constructor
//   2. env var PULP_FFT_BACKEND={auto,vdsp,kissfft,fftw3,mkl}
//   3. compile-time default: vDSP on Apple, kissfft elsewhere
//
// Numerical equivalence: cross-backend output matches to within a small
// float tolerance (single-precision round-off accumulates with size). The
// test suite asserts max-abs-error < ~1e-3 across sizes 64..16384 for
// power-of-2 transforms.
 
#include <complex>
#include <memory>
#include <string>
 
namespace pulp::signal {
 
enum class FftBackend {
    auto_,    
    vdsp,     
    kissfft,  
    fftw3,    
    mkl,      
};

const char* fft_backend_name(FftBackend b) noexcept;

FftBackend parse_fft_backend(const char* s) noexcept;

bool fft_backend_available(FftBackend b) noexcept;

FftBackend resolve_fft_backend(FftBackend hint = FftBackend::auto_) noexcept;

class MultiBackendFft {
public:
    explicit MultiBackendFft(int size, FftBackend backend = FftBackend::auto_);
    ~MultiBackendFft();
 
    MultiBackendFft(const MultiBackendFft&) = delete;
    MultiBackendFft& operator=(const MultiBackendFft&) = delete;
    MultiBackendFft(MultiBackendFft&&) noexcept;
    MultiBackendFft& operator=(MultiBackendFft&&) noexcept;
 
    int size() const noexcept;
    FftBackend backend() const noexcept;

    void forward(std::complex<float>* data) const;

    void inverse(std::complex<float>* data) const;
 
private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};
 
} // namespace pulp::signal