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.

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 change the definition of FFTW_REAL from double to float in fftw.h and then recompile the library.

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.

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).

Arguments

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.

How to install your own memory allocator

#include <fftw.h>

void *fftw_malloc(size_t n);
void fftw_free(void *p);

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

Whenever it has to allocate and release memory, FFTW calls fftw_malloc and fftw_free (which, in turn, ordinarily call malloc and free). (FFTW needs some memory for internal use and to create data structures like plans.)

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 another function, 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.