Julia API

The names listed here are public. FFTL exports the names FFTW.jl exports: the DFT and DCT functions with their plan_ and in-place forms, and AbstractFFTs.jl's helpers (fftshift, fftfreq, …). All other names are used with the prefix, FFTL.r2r, FFTL.REDFT10 and so on. The exported functions are FFTL's own; the generic functions of AbstractFFTs.jl reach them through the methods described on AbstractFFTs.

Complex transforms

FFTL.fft Function

fft(x, region = 1:ndims(x))

Forward DFT of x along region (all dimensions by default), unnormalised. Equal to plan_fft(x, region) * x.

source

FFTL.bfft Function

bfft(x, region = 1:ndims(x))

Backward DFT along region, unnormalised: applying bfft to fft(x) multiplies x by the number of transformed elements.

source

FFTL.ifft Function

ifft(x, region = 1:ndims(x))

Normalised inverse DFT along region: ifft(fft(x)) ≈ x.

source

FFTL.plan_fft Function

plan_fft(x::AbstractArray, region = 1:ndims(x); threads, num_threads, flags, timelimit)
plan_bfft(x, region = 1:ndims(x); …), plan_ifft(x, region = 1:ndims(x); …)

Plans for the forward, unnormalised backward and normalised inverse DFT along the dimensions region of arrays like x. Float32 and Float64 (real or complex) use the SIMD kernels, and transforms large enough to profit run on up to threads threads (default: the value of FFTL.set_num_threads, else Threads.nthreads(); num_threads is a synonym). flags and timelimit are accepted for FFTW.jl compatibility and have no effect: FFTL does not measure while planning. Other floating-point types (BigFloat, Double64, Float128, …) are transformed in their own precision by a generic, single-threaded path; Float16, integers and other numbers are converted to ComplexF64.

source

FFTL.plan_fft! Function

plan_fft!(x, region = 1:ndims(x); …), plan_bfft!, plan_ifft!
fft!(x, region = 1:ndims(x)), bfft!, ifft!

In-place forms: the plans overwrite the array they are applied to with p * x, and fft!, bfft! and ifft! overwrite x. Keywords as for plan_fft.

source

FFTL.InplacePlan Type

InplacePlan(p)

A plan that applies p in place: q * x overwrites x and returns it, as FFTW.jl's in-place plans do. Returned by plan_fft!, plan_bfft!, plan_ifft!, plan_dct! and plan_idct!.

source

plan_bfft and plan_ifft are documented with plan_fft; fft!, bfft!, ifft!, plan_bfft! and plan_ifft! with plan_fft!.

Real transforms

FFTL.rfft Function

rfft(x, region = 1:ndims(x))

Forward DFT of real x, returning the half spectrum along the first dimension of region (size(x, d) ÷ 2 + 1 values there).

source

FFTL.brfft Function

brfft(X, d, region = 1:ndims(X))

Unnormalised inverse of the half spectrum X to a real array of length d along the first dimension of region.

source

FFTL.irfft Function

irfft(X, d, region = 1:ndims(X))

Normalised inverse of the half spectrum X to a real array of length d along the first dimension of region: irfft(rfft(x), length(x)) ≈ x.

source

FFTL.plan_rfft Function

plan_rfft(x::AbstractArray{<:Real}, region = 1:ndims(x); threads, num_threads, flags, timelimit)
plan_brfft(X::AbstractArray{<:Complex}, d, region = 1:ndims(X); …)
plan_irfft(X::AbstractArray{<:Complex}, d, region = 1:ndims(X); …)

Real-input forward DFT (half spectrum along the first dimension of region), its unnormalised inverse to real arrays with length d along that dimension, and the normalised inverse. Keywords as for plan_fft.

source

plan_brfft and plan_irfft are documented with plan_rfft.

Real-to-real transforms

FFTL.dct Function

dct(x, region = 1:ndims(x)), idct(x, region = 1:ndims(x))

Orthonormal DCT-II and its inverse (DCT-III) along region.

source

FFTL.plan_dct Function

plan_dct(x, region = 1:ndims(x); …), plan_idct(x, region = 1:ndims(x); …)
plan_dct!(x, region = 1:ndims(x); …), plan_idct!(x, region = 1:ndims(x); …)
dct!(x, region = 1:ndims(x)), idct!(x, region = 1:ndims(x))

Plans of the orthonormal DCT-II and its inverse (the scaling of dct), and their in-place forms. Keywords as for plan_fft.

source

FFTL.plan_r2r Function

plan_r2r(x::AbstractArray{<:Real}, kinds, region = 1:ndims(x); threads, num_threads, flags, timelimit)
r2r(x, kinds, region = 1:ndims(x))

Unnormalised real-to-real transforms; kinds is one R2RKind (REDFT00 … RODFT11, DHT, R2HC, HC2R) for all dimensions of region or one per dimension. Keywords as for plan_fft.

source

FFTL.R2RKind Type

R2RKind

The real-to-real kinds: REDFT00 … REDFT11 (DCT-I … DCT-IV), RODFT00 … RODFT11 (DST-I … DST-IV), DHT (Hartley), R2HC and HC2R (halfcomplex). The formulas are in the documentation (Cosine, sine and Hartley transforms).

source

idct is documented with dct; plan_idct, plan_dct!, plan_idct!, dct! and idct! with plan_dct; r2r with plan_r2r.

The kinds, as constants: REDFT00 (DCT-I), REDFT10 (DCT-II), REDFT01 (DCT-III), REDFT11 (DCT-IV), RODFT00 (DST-I), RODFT10 (DST-II), RODFT01 (DST-III), RODFT11 (DST-IV), DHT (Hartley), R2HC and HC2R (halfcomplex). Their formulas are on Cosine, sine and Hartley transforms.

Passes

Batched one-dimensional transforms of strided arrays, the operations NFFT.jl builds on.

FFTL.plan_pass Function

plan_pass(v::StridedArray{<:Complex}, d; sign = -1, threads = 1, nonzero = nothing, needed = nothing)

Plan for the batched 1D DFT along dimension d of arrays with the size and strides of v (sign = -1 forward, +1 unnormalised backward). Apply with mul!(w, p, v) (w with the same size and strides, w === v in place) or apply!(p, v). With threads > 1 the lines are split among threads, and a single long line (d = 1) uses the four-step algorithm; callers that thread over many arrays themselves keep the default 1.

nonzero (ranges of indices along d, e.g. (1:a, b:n)) declares that each line is zero outside these ranges; needed that only these outputs of each line are used (the others may hold anything afterwards). The first resp. last stage then skips the zero inputs resp. the unneeded outputs.

source

FFTL.plan_r2r_pass Function

plan_r2r_pass(v::StridedArray{<:Real}, d, kind; threads = 1)

Plan for the real-to-real transform kind (REDFT00 … RODFT11, DHT, R2HC, HC2R; unnormalised) along dimension d of all lines of arrays with the size and strides of v. Apply in place with apply!(p, v) or into an array of the same layout with mul!(w, p, v).

source

FFTL.apply! Function

apply!(p::PassPlan, v)

The transform of p applied to v in place.

source

Run-time plans

Plans whose radix sequences and sizes are data, for programs compiled with juliac --trim; see Compiling ahead of time.

FFTL.RPlan Type

RPlan{T}(sz, region, σ; threads = Threads.nthreads())

DFT plan with run-time kernels for complex arrays of size sz (any number of dimensions) along the dimensions region, sign σ (-1 forward, +1 unnormalised backward). Applied like any FFTL plan (p * x, mul!(y, p, x), inv(p)); execute!(p, py, px) takes pointers.

source

FFTL.execute! Function

execute!(p::RPlan{T}, py::Ptr{Complex{T}}, px::Ptr{Complex{T}})

Apply p to the array at px (column major, size p.sz) and write the result to py; py may equal px. The caller keeps both arrays alive.

source

FFTL.RRFFTPlan Type

RRFFTPlan{T}(sz, region, σ; threads = Threads.nthreads())

r2c (σ = -1) or unnormalised c2r (σ = +1) plan for real arrays of size sz along region: real along the first dimension of the region (half spectrum of n ÷ 2 + 1 values there), complex along the others. Applied with execute_r2c!(p, py, px) or execute_c2r!(p, py, px) (pointers; out of place, c2r leaves its input unchanged). In place (py and px the same address) the real array is padded to 2(n ÷ 2 + 1) values along that dimension, so that it fills the memory of the half spectrum (FFTW's in-place layout); the padding is ignored by r2c and undefined after c2r.

source

FFTL.RR2RPlan Type

RR2RPlan{T}(sz, kinds, region; threads = Threads.nthreads())

Real-to-real plan with run-time kernels for arrays of size sz, one R2RKind per dimension of region (unnormalised, as plan_r2r). Applied with execute_r2r!(p, py, px); py may equal px.

source

execute_r2c!, execute_c2r! and execute_r2r! are documented with the plans they apply.

GPU

Available after using KernelAbstractions and a GPU package.

FFTL.plan_ka Function

plan_ka(backend, T, dims, σ; region = 1:length(dims), gmax = 64, radices = nothing)

DFT plan (σ = -1 forward, +1 unnormalised backward) for arrays of size dims with element type Complex{T} on a KernelAbstractions backend (Metal, CUDA, ROCm, oneAPI, CPU), along the dimensions region. Requires using KernelAbstractions; with a GPU package loaded, FFTL.plan_fft(x) etc. return these plans for GPU arrays. Apply with p * x or mul!(y, p, x) (y !== x); kernels are queued on the backend without synchronization.

source

FFTL.plan_ka_rfft Function

plan_ka_rfft(backend, T, dims; region = 1:length(dims))
plan_ka_brfft(backend, T, dims; region = 1:length(dims))
plan_ka_r2r(backend, T, dims, kinds; region = 1:length(dims))

Real-input forward DFT (half spectrum along region[1]), its unnormalised inverse (dims is the size of the real array in both) and real-to-real transforms (one R2RKind per dimension) on a KernelAbstractions backend. Requires using KernelAbstractions; with a GPU package loaded, FFTL.plan_rfft, plan_brfft, plan_irfft and plan_r2r return these plans for GPU arrays.

source

plan_ka_brfft and plan_ka_r2r are documented with plan_ka_rfft.

Cache and configuration

FFTL.set_num_threads Function

FFTL.set_num_threads(n)

Default number of threads for the plans made afterwards (threads keyword not given), as FFTW.set_num_threads. Without a call, plans use Threads.nthreads().

source

FFTL.ESTIMATE Constant

FFTL.ESTIMATE, FFTL.MEASURE, FFTL.PATIENT, FFTL.EXHAUSTIVE

Values for the flags keyword of the plan functions, accepted for FFTW.jl compatibility. They have no effect: an FFTL plan does not depend on measurements made while planning.

source

FFTL.clear_cache! Function

clear_cache!()

Drop the twiddle and filter tables that FFTL keeps for reuse by later plans.

source

FFTL.cpu_caches Function

FFTL.cpu_caches()

Cache sizes the CPU plans are sized from: L1 data and L2 per core, last-level cache per core cluster, in bytes, and where they come from (:queried, :default, :user).

source

FFTL.set_cpu_caches! Function

FFTL.set_cpu_caches!(; l1, l2, llc)

Override the cache sizes (bytes) that plans are sized from, e.g. when the query at load time fails or a machine reports misleading values. Affects plans made afterwards. FFTL.set_cpu_caches!() restores the queried values.

source

FFTL.PRECOMPILE_WORKLOAD Constant

FFTL.PRECOMPILE_WORKLOAD

The precompile workload selected when FFTL was built: "lean" (default), "broad" or "none". It comes from the precompile_workload preference:

using Preferences, FFTL
Preferences.set_preferences!(FFTL, "precompile_workload" => "broad"; force = true)

The next load recompiles FFTL with the selected workload.

source

FFTL.REG_BYTES Constant

FFTL.REG_BYTES

Width in bytes of the widest vector the CPU kernels use: 64 with AVX-512, 32 with AVX2, 16 otherwise. The simd_bytes preference lowers it (for comparisons, or CPUs that reduce the clock for 512-bit instructions); the next load recompiles FFTL:

using Preferences, FFTL
Preferences.set_preferences!(FFTL, "simd_bytes" => 32; force = true)

source

Plan types

Each plan is an AbstractFFTs.Plan. The types are listed for reference; their fields are not part of the interface.

type	returned by
FFTLPlan	plan_fft, plan_bfft, plan_ifft (wrapped in ScaledPlan)
RFFTLPlan	plan_rfft
BRFFTLPlan	plan_brfft, plan_irfft (wrapped in ScaledPlan)
R2RPlan	plan_r2r
OrthoDCTPlan	plan_dct, plan_idct
InplacePlan	plan_fft!, plan_bfft!, plan_ifft!, plan_dct!, plan_idct!
PassPlan	plan_pass
R2RPassPlan	plan_r2r_pass
GPlan, GRPlan, GR2RPlan	the same functions for BigFloat and other number types

The plans of the generic and the GPU paths follow the same protocol; see AbstractFFTs.