Go to the first, previous, next, last section, table of contents.

FFTW Reference

This chapter provides a complete reference for all FFTW functions. Programs using FFTW should be linked with -lfftw -lm on Unix systems, or with the FFTW and standard math libraries in general.

Complex Numbers

By including <fftw.h>, you will have access to the following definitions:

typedef double FFTW_REAL;

typedef struct {
     FFTW_REAL re, im;
} FFTW_COMPLEX;

#define c_re(c)  ((c).re)
#define c_im(c)  ((c).im)

All FFTW operations are performed on the FFTW_COMPLEX data type. The two macros c_re and c_im retrieve, respectively, the real and imaginary parts of a complex number.

Users who wish to work in single precision rather than double precision merely need to #define the symbol FFTW_ENABLE_FLOAT in fftw.h and then recompile the library. On Unix systems, one can instead use configure --enable-float (See section Installation, for more information).

Plan Creation for One-dimensional Transforms

#include <fftw.h>

fftw_plan fftw_create_plan(int n, fftw_direction dir,
                           int flags);

The function fftw_create_plan creates a plan, which is a data structure containing all the information that fftw needs in order to compute the 1D Fourier Transform. You can create as many plans as you need, but only one plan for a given array size is required (a plan can be reused many times).

fftw_create_plan returns a valid plan, or NULL if, for some reason, the plan can't be created. In the default installation, this can't happen, but it is possible to configure FFTW in such a way that some input sizes are forbidden, and FFTW cannot create a plan.

See also fftw_create_plan_specific, below.

Arguments

Plan Creation for Multi-dimensional Transforms

#include <fftw.h>

fftwnd_plan fftwnd_create_plan(int rank, const int *n,
                               fftw_direction dir, int flags);

fftwnd_plan fftw2d_create_plan(int nx, int ny,
                               fftw_direction dir, int flags);

fftwnd_plan fftw3d_create_plan(int nx, int ny, int nz,
                               fftw_direction dir, int flags);

The function fftwnd_create_plan creates a plan, which is a data structure containing all the information that fftwnd needs in order to compute a multi-dimensional Fourier Transform. You can create as many plans as you need, but only one plan for a given array size is required (a plan can be reused many times). The functions fftw2d_create_plan and fftw3d_create_plan are optional, alternative interfaces to fftwnd_create_plan for two and three dimensions, respectively.

fftwnd_create_plan returns a valid plan, or NULL if, for some reason, the plan can't be created. This can happen if memory runs out or if the arguments are invalid in some way (e.g. if rank < 0).

See also fftwnd_create_plan_specific, below, for an even better way to create multi-dimensional plans.

Arguments

Creating plans based on specific arrays

#include <fftw.h>

fftw_plan fftw_create_plan_specific(int n, fftw_direction dir,
                                    int flags,
                                    FFTW_COMPLEX *in, int istride,
                                    FFTW_COMPLEX *out, int ostride);
fftwnd_plan fftwnd_create_plan_specific(int rank, const int *n,
                                        fftw_direction dir,
                                        int flags,
                                        FFTW_COMPLEX *in, int istride,
                                        FFTW_COMPLEX *out, int ostride);
fftwnd_plan fftw2d_create_plan_specific(int nx, int ny,
                                        fftw_direction dir,
                                        int flags,
                                        FFTW_COMPLEX *in, int istride,
                                        FFTW_COMPLEX *out, int ostride);
fftwnd_plan fftw3d_create_plan_specific(int nx, int ny, int nz,
                                        fftw_direction dir, int flags,
                                        FFTW_COMPLEX *in, int istride,
                                        FFTW_COMPLEX *out, int ostride);

These functions are identical to the corresponding functions without the `_specific', except that they take as additional arguments specific input/output arrays and their strides.

For the last four arguments, you should pass the arrays and strides that you will eventually be passing to fftw or fftwnd. The resulting plans will be optimized for those arrays and strides, although they may be used on other arrays as well. Note: the contents of the in and out arrays are destroyed by the specific planners (the initial contents are ignored, so the arrays need not have been initialized).

We recommend the use of the specific planners, even in cases where you will be transforming arrays different from those passed to the specific planners, as they confer the following advantages:

Note that, for FFTW_IN_PLACE transforms, the out and ostride parameters are interpreted just as they are for fftw or fftwnd.

Computing the one-dimensional transform

#include <fftw.h>

void fftw(fftw_plan plan, int howmany,
          FFTW_COMPLEX *in, int istride, int idist,
          FFTW_COMPLEX *out, int ostride, int odist);

The function fftw computes the one-dimensional Fourier Transform, using a plan created by fftw_create_plan (See section Plan Creation for One-dimensional Transforms.)

Arguments

To simply transform a single, contiguous input array to a contiguous output array, pass 1 for howmany, istride, idist, ostride, and odist.

Computing the multi-dimensional transform

#include <fftw.h>

void fftwnd(fftwnd_plan plan, int howmany,
            FFTW_COMPLEX *in, int istride, int idist,
            FFTW_COMPLEX *out, int ostride, int odist);

The function fftwnd computes the multi-dimensional Fourier Transform, using a plan created by fftwnd_create_plan (See section Plan Creation for Multi-dimensional Transforms.) (Note that the plan determines the rank and dimensions of the array to be transformed.)

Arguments

To simply transform a single, contiguous input array to a contiguous output array, pass 1 for howmany, istride, idist, ostride, and odist.

Destroying a one-dimensional plan

#include <fftw.h>

void fftw_destroy_plan(fftw_plan plan);

The function fftw_destroy_plan frees the plan plan and releases all the memory associated with it. After destruction, a plan is no longer valid.

Destroying a multi-dimensional plan

#include <fftw.h>

void fftwnd_destroy_plan(fftwnd_plan plan);

The function fftwnd_destroy_plan frees the plan plan and releases all the memory associated with it. After destruction, a plan is no longer valid.

Counting the number of operations

#include <fftw.h>

typedef struct {
     int fp_additions, fp_multiplications;
     int vars, memory_accesses;
} fftw_op_count;

void fftw_count_plan_ops(fftw_plan p, fftw_op_count *ops);
void fftwnd_count_plan_ops(fftwnd_plan p, fftw_op_count *ops);

FFTW can compute a count of the number of operations it requires in order to perform an FFT with a given plan. The fftw_count_plan_ops and fftwnd_count_plan_ops functions, given a plan, fill in the ops data structure with the operation counts.

The fftw_op_count data structure, defined above, contains the total number of floating-point additions and multiplications, the maximum number of stack variables "live" at any point, and the total number of reads or writes to arrays.

It should be noted that all of these counts may be rendered inaccurate by a sufficiently aggressive compiler. The vars count is especially unreliable. We don't think that operation counts are especially important, in any case; they certainly aren't a good predictor of performance on most machines.

How to install your own memory allocator

#include <fftw.h>

void *(*fftw_malloc_hook) (size_t n);
void (*fftw_free_hook) (void *p);

Whenever it has to allocate and release memory, FFTW ordinarily calls malloc and free. If malloc fails, FFTW prints an error message and exits. This behavior may be undesirable in some applications. Also, special memory-handling functions may be necessary in certain environments. Consequently, FFTW provides means by which you can install your own memory allocator and take whatever error-correcting action you find appropriate. The variables fftw_malloc_hook and fftw_free_hook are pointers to functions, and they are normally NULL. If you set those variables to point to other functions, then FFTW will use your routines instead of malloc and free. fftw_malloc_hook must point to a malloc-like function, and fftw_free_hook must point to a free-like function.

Exporting wisdom

#include <fftw.h>

void fftw_export_wisdom(void (*emitter)(char c, void *), void *data);
void fftw_export_wisdom_to_file(FILE *output_file);
char *fftw_export_wisdom_to_string(void);

These functions allow you to export all currently accumulated wisdom in a form from which it can be later imported and restored, even during a separate run of the program. (See section Words of Wisdom.) The current store of wisdom is not affected by calling any of these routines.

fftw_export_wisdom exports the wisdom to any output medium, as specified by the callback function emitter. emitter is a putc-like function that writes the character c to some output; its second parameter is the data pointer passed to fftw_export_wisdom. For convenience, the following two "wrapper" routines are provided:

fftw_export_wisdom_to_file writes the wisdom to the current position in output_file, which should be open with write permission. Upon exit, the file remains open and is positioned at the end of the wisdom data.

fftw_export_wisdom_to_string returns a pointer to a NULL-terminated string holding the wisdom data. This string is dynamically allocated, and it is the responsibility of the caller to deallocate it with fftw_free when it is no longer needed.

All of these routines export the wisdom in the same format, which we will not document here except to say that it is LISP-like ASCII text that is insensitive to white space.

Importing wisdom

#include <fftw.h>

fftw_status fftw_import_wisdom(int (*get_input)(void *), void *data);
fftw_status fftw_import_wisdom_from_file(FILE *input_file);
fftw_status fftw_import_wisdom_from_string(const char *input_string);

These functions import wisdom into a program from data stored by the fftw_export_wisdom functions above. (See section Words of Wisdom.) The imported wisdom supplements rather than replaces any wisdom already accumulated by the running program (except when there is conflicting wisdom, in which case the existing wisdom is replaced).

fftw_import_wisdom imports wisdom from any input medium, as specified by the callback function get_input. get_input is a getc-like function that returns the next character in the input; its parameter is the data pointer passed to fftw_import_wisdom. If the end of the input data is reached (which should never happen for valid data), it may return either NULL (ASCII 0) or EOF (as defined in <stdio.h>). For convenience, the following two "wrapper" routines are provided:

fftw_import_wisdom_from_file reads wisdom from the current position in input_file, which should be open with read permission. Upon exit, the file remains open and is positioned at the end of the wisdom data.

fftw_import_wisdom_from_string reads wisdom from the NULL-terminated string input_string.

The return value of these routines is FFTW_SUCCESS if the wisdom was read successfully, and FFTW_FAILURE otherwise. Note that, in all of these functions, any data in the input stream past the end of the wisdom data is simply ignored (it is not even read if the wisdom data is well-formed).

Forgetting wisdom

#include <fftw.h>

void fftw_forget_wisdom(void);

Calling fftw_forget_wisdom causes all accumulated wisdom to be discarded and its associated memory to be freed. (New wisdom can still be gathered subsequently, however.)


Go to the first, previous, next, last section, table of contents.