fftw.jl

This unit implements a convenient interface to FFTW.jl and AbstractFFTs.jl. It is not part of the main FourierAnalysis API, since all its functions manage basic FFTW plans for FFT and iFFT computations using default settings. However, the use of this unit is important if massive FFT computations are to be performed.

In order to use effectively FFTW, see window length in FFTW.

The following are constants used by FFTW as flags in creating FFT plans. See here for details.

plan_estimate        = UInt32(64)      # (1 << 6)   very small search
plan_measure         = UInt32(0)       #            small search
plan_patient         = UInt32(32)      # (1 << 5)   large search
plan_exhaustive      = UInt32(8)       # (1 << 3)   very large search
plan_conserve_memory = UInt32(4)       # (1 << 2)
plan_wisdom_only     = UInt32(2097152) # (1 << 21)
plan_unaligned       = UInt32(2)       # (1 << 1)
plan_preserve_input  = UInt32(16)      # (1 << 4)

FourierAnalysis.Planner — Type

FFTW plans to be used by all functions in Fourier Analysis are incapsulated in this structure. This is the only operator object created by this package, all others being data objects.

Spectral and cross-spectral computations (frequency domain objects) need only a forward plan (real FFT), while objects based on the analytic signal (time-frequency domain objects) need both a forward (.p) and a backward (.ip) plan (complex iFFT).

Argument flags must be one of the constants here above. Basic usage of the flags involves a trade-off between the time needed to compute the planner and the efficacy for computing the FFTs. The following flags are sorted in ascending order of time needed to be computed and efficacy: plan_estimate, plan_measure, plan_patient, plan_exhaustive. By default FourierAnalysis adopts plan_estimate, which allows the quickest search, but the least optimal choice. Other flags may be worth if several FFT computations are to be done with the same setting. See here for details.

Argument timelimit is the maximum time (in seconds) allowed to FFTW for optimizing the plans. Setting this to -1.0 amounts to imposing no time limits.

FFTW plans are computed for a given window length wl and data type type.

Planners objects may be passed as an argument to constructors of FDobjects and TFobjects by using one of the Planner constuctor here below.

Constructors

Planner(flags :: UInt32,
    timelimit :: Union{Int, Float64},
           wl :: Int,
         type :: Type,
           bw :: Bool = false)

Use this to create a Planner object, passing as argument a FFTW flags constant and timelimit, the window length wl and the type of the input data type, which must be real, e.g., Float64.

If bw is false (default), a dummy backward plan is created, otherwise a backward plan is created for the complex data type corresponding to type (e.g., if type is Float64, it will created for ComplexF64 data.)

For example, suppose 𝐗 is a vector of many matrices of multivariate time-series sampled at 128 samples per second and that we want to compute the spectra for all of them using a 256-point FFT. We first create a plan by

p=Planner(plan_exhaustive, 10.0, 256, eltype(𝐗[1]))

Then we invoke the Spectra function passing the plan as argument:

𝐒=spectra(𝐗, sr, t; planner=p)

A shorter construction syntax is available when only the forward plan is needed and the type of the data is Float64:

Planner(flags :: UInt32,
    timelimit :: Union{Int, Float64},
           wl :: Int)

For example, the line above could have been written more shortly as

p=Planner(plan_exhaustive, 10.0, 256)

source