module FFTW3

Fast Fourier Transforms by using ((<FFTW|URL:www.fftw.org>)) Ver.3.

Takeshi Horinouchi

© Takeshi Horinouchi / GFD Dennou Club, 2003

NO WARRANTY

Features

• Uses ((<NArray|URL:www.ruby-lang.org/en/raa-list.rhtml?name=NArray>)).

• Multi-dimensional complex FFT. (Real data are coerced to complex).

• Supports both double and single float transforms.

• Not normalized as in FFTW

Features yet to be introduced

• Sine / cosine transforms

• User choice of optimization levels (i.e., FFTW_MEASURE etc in addition to FFTW_ESTIMATE).

• Multi-threaded FFT3 support – don’t know whether it’s really feasible.

Installation

Install fftw3 (in OSX with MacPorts: sudo port install fftw3)
sudo gem install fftw3

How to use

See the following peice of code. (Install this library and copy and paste the following to the interactive shell irb).

require "fftw3"

na = NArray.float(8,6)   # float -> will be corced to complex
na[1,1]=1

# <example 1>
fc = FFTW3.fft(na)/na.length  # forward 2D FFT and normalization
nc = FFTW3.ifft(fc)       # backward 2D FFT (complex) --> 
nb = nc.real                # should be equal to na except round errors  

# <example 2>
fc = FFTW3.fft(na, 0) / na.shape[0]  # forward FFT with the first dim

# <example 3>
fc = FFTW3.fft(na, 1) / na.shape[1]  # forward FFT with the second dim

API Reference

Module methods

—fft(narray, [dim,dim,…])

Complex FFT.

The 3rd, 4th,... arguments are optional.

ARGUMENTS
* narray (NArray or NArray-compatible Array) : array to be
  transformed. If real, coerced to complex before transformation.
  If narray is single-precision and the single-precision
  version of FFTW3 is installed (before installing this module),
  this method does a single-precision transform. 
  Otherwise, a double-precision transform is used.
* optional 3rd, 4th,... arguments (Integer) : Specifies dimensions 
  to apply FFT. For example, if 0, the first dimension is
  transformed (1D FFT); If -1, the last dimension is used (1D FFT);
  If 0,2,4, the first, third, and fifth dimensions
  are transformed (3D FFT); If entirely omitted, ALL DIMENSIONS
  ARE SUBJECT TO FFT, so 3D FFT is done with a 3D array.

RETURN VALUE
* a complex NArray

NOTE
* As in FFTW, return value is NOT normalized. Thus, a consecutive
  forward and backward transform would multiply the size of
  data used for transform. You can normalize, for example,
  the forward transform FFTW.fft(narray, -1, 0, 1)
  (FFT regarding the first (dim 0) & second (dim 1) dimensions) by
  dividing with (narray.shape[0]*narray.shape[1]). Likewise,
  the result of FFTW.fft(narray, -1) (FFT for all dimensions)
  can be normalized by narray.length.

—ifft(narray, [dim,dim,…])

Complex inverse FFT