#include <stdio.h>
#include "gromacs/math/gmxcomplex.h"
#include "gromacs/utility/real.h"

Include dependency graph for fft.h:

This graph shows which files directly or indirectly include this file:

Description

Fast Fourier Transforms.

This file provides an abstract Gromacs interface to Fourier transforms, including multi-dimensional and real-to-complex transforms.

Internally it is implemented as wrappers to external libraries such as FFTW or the Intel Math Kernel Library, but we also have a built-in version of FFTPACK in case the faster alternatives are unavailable.

We also provide our own multi-dimensional transform setups even when the underlying library does not support it directly.

Typedefs
typedef struct gmx_fft *	gmx_fft_t
	Datatype for FFT setup. More...

typedef enum gmx_fft_direction	gmx_fft_direction
	Specifier for FFT direction. More...

typedef int	gmx_fft_flag
	Specifier for FFT flags. More...

Enumerations
enum	gmx_fft_direction { GMX_FFT_FORWARD, GMX_FFT_BACKWARD, GMX_FFT_REAL_TO_COMPLEX, GMX_FFT_COMPLEX_TO_REAL }
	Specifier for FFT direction. More...

Functions
int	gmx_fft_init_1d (gmx_fft_t *fft, int nx, gmx_fft_flag flags)
	Setup a 1-dimensional complex-to-complex transform. More...

int	gmx_fft_init_many_1d (gmx_fft_t *fft, int nx, int howmany, gmx_fft_flag flags)
	Setup multiple 1-dimensional complex-to-complex transform. More...

int	gmx_fft_init_1d_real (gmx_fft_t *fft, int nx, gmx_fft_flag flags)
	Setup a 1-dimensional real-to-complex transform. More...

int	gmx_fft_init_many_1d_real (gmx_fft_t *fft, int nx, int howmany, gmx_fft_flag flags)
	Setup multiple 1-dimensional real-to-complex transform. More...

int	gmx_fft_init_2d_real (gmx_fft_t *fft, int nx, int ny, gmx_fft_flag flags)
	Setup a 2-dimensional real-to-complex transform. More...

int	gmx_fft_1d (gmx_fft_t setup, enum gmx_fft_direction dir, void in_data, void out_data)
	Perform a 1-dimensional complex-to-complex transform. More...

int	gmx_fft_many_1d (gmx_fft_t setup, enum gmx_fft_direction dir, void in_data, void out_data)
	Perform many 1-dimensional complex-to-complex transforms. More...

int	gmx_fft_1d_real (gmx_fft_t setup, enum gmx_fft_direction dir, void in_data, void out_data)
	Perform a 1-dimensional real-to-complex transform. More...

int	gmx_fft_many_1d_real (gmx_fft_t setup, enum gmx_fft_direction dir, void in_data, void out_data)
	Perform many 1-dimensional real-to-complex transforms. More...

int	gmx_fft_2d_real (gmx_fft_t setup, enum gmx_fft_direction dir, void in_data, void out_data)
	Perform a 2-dimensional real-to-complex transform. More...

void	gmx_fft_destroy (gmx_fft_t setup)
	Release an FFT setup structure. More...

void	gmx_many_fft_destroy (gmx_fft_t setup)
	Release a many FFT setup structure. More...

int	gmx_fft_transpose_2d (t_complex in_data, t_complex out_data, int nx, int ny)
	Transpose 2d complex matrix, in-place or out-of-place. More...

void	gmx_fft_cleanup ()
	Cleanup global data of FFT. More...

const char *	gmx_fft_get_version_info ()
	Return string describing the underlying FFT implementation. More...

Variables
static const int	GMX_FFT_FLAG_NONE = 0
	Macro to indicate no special flags for FFT routines. More...

static const int	GMX_FFT_FLAG_CONSERVATIVE = (1<<0)
	Flag to disable FFT optimizations based on timings, see gmx_fft_flag. More...

Typedef Documentation

typedef enum gmx_fft_direction gmx_fft_direction

Specifier for FFT direction.

The definition of the 1D forward transform from input x[] to output y[] is

$y_{k} = \sum_{j=0}^{N-1} x_{j} \exp{-i 2 \pi j k /N}$

while the corresponding backward transform is

$y_{k} = \sum_{j=0}^{N-1} x_{j} \exp{i 2 \pi j k /N}$

A forward-backward transform pair will this result in data scaled by N.

For complex-to-complex transforms you can only use one of GMX_FFT_FORWARD or GMX_FFT_BACKWARD, and for real-complex transforms you can only use GMX_FFT_REAL_TO_COMPLEX or GMX_FFT_COMPLEX_TO_REAL.

typedef int gmx_fft_flag

Specifier for FFT flags.

Some FFT libraries (FFTW, in particular) can do timings and other tricks to try and optimize the FFT for the current architecture. However, this can also lead to results that differ between consecutive runs with identical input. To avoid this, the conservative flag will attempt to disable such optimization, but there are no guarantees since we cannot control what the FFT libraries do internally.

typedef struct gmx_fft* gmx_fft_t

Datatype for FFT setup.

The gmx_fft_t type contains all the setup information, e.g. twiddle factors, necessary to perform an FFT. Internally it is mapped to whatever FFT library we are using, or the built-in FFTPACK if no fast external library is available.

Since some of the libraries (e.g. MKL) store work array data in their handles this datatype should only be used for one thread at a time, i.e. they should allocate one instance each when executing in parallel.

Enumeration Type Documentation

enum gmx_fft_direction

Specifier for FFT direction.

The definition of the 1D forward transform from input x[] to output y[] is

$y_{k} = \sum_{j=0}^{N-1} x_{j} \exp{-i 2 \pi j k /N}$

while the corresponding backward transform is

$y_{k} = \sum_{j=0}^{N-1} x_{j} \exp{i 2 \pi j k /N}$

A forward-backward transform pair will this result in data scaled by N.

For complex-to-complex transforms you can only use one of GMX_FFT_FORWARD or GMX_FFT_BACKWARD, and for real-complex transforms you can only use GMX_FFT_REAL_TO_COMPLEX or GMX_FFT_COMPLEX_TO_REAL.

Enumerator
GMX_FFT_FORWARD	Forward complex-to-complex transform.
GMX_FFT_BACKWARD	Backward complex-to-complex transform.
GMX_FFT_REAL_TO_COMPLEX	Real-to-complex valued FFT.
GMX_FFT_COMPLEX_TO_REAL	Complex-to-real valued FFT.

Function Documentation

int gmx_fft_1d	(	gmx_fft_t	setup,
		enum gmx_fft_direction	dir,
		void *	in_data,
		void *	out_data
	)

Perform a 1-dimensional complex-to-complex transform.

Performs an instance of a transform previously initiated.

Parameters

setup	Setup returned from gmx_fft_init_1d()
dir	Forward or Backward
in_data	Input grid data. This should be allocated with gmx_new() to make it 16-byte aligned for better performance.
out_data	Output grid data. This should be allocated with gmx_new() to make it 16-byte aligned for better performance. You can provide the same pointer for in_data and out_data to perform an in-place transform.

Returns: 0 on success, or an error code.

Note: Data pointers are declared as void, to avoid casting pointers depending on your grid type.

int gmx_fft_1d_real	(	gmx_fft_t	setup,
		enum gmx_fft_direction	dir,
		void *	in_data,
		void *	out_data
	)

Perform a 1-dimensional real-to-complex transform.

Performs an instance of a transform previously initiated.

Parameters

setup	Setup returned from gmx_fft_init_1d_real()
dir	Real-to-complex or complex-to-real
in_data	Input grid data. This should be allocated with gmx_new() to make it 16-byte aligned for better performance.
out_data	Output grid data. This should be allocated with gmx_new() to make it 16-byte aligned for better performance. You can provide the same pointer for in_data and out_data to perform an in-place transform.

If you are doing an in-place transform, the array must be padded up to an even integer length so n/2 complex numbers can fit. Out-of-place arrays should not be padded (although it doesn't matter in 1d).

Returns: 0 on success, or an error code.

Note: Data pointers are declared as void, to avoid casting pointers depending on transform direction.

int gmx_fft_2d_real	(	gmx_fft_t	setup,
		enum gmx_fft_direction	dir,
		void *	in_data,
		void *	out_data
	)

Perform a 2-dimensional real-to-complex transform.

Performs an instance of a transform previously initiated.

Parameters

setup	Setup returned from gmx_fft_init_1d_real()
dir	Real-to-complex or complex-to-real
in_data	Input grid data. This should be allocated with gmx_new() to make it 16-byte aligned for better performance.
out_data	Output grid data. This should be allocated with gmx_new() to make it 16-byte aligned for better performance. You can provide the same pointer for in_data and out_data to perform an in-place transform.

Returns: 0 on success, or an error code.

Note: If you are doing an in-place transform, the last dimension of the array MUST be padded up to an even integer length so n/2 complex numbers can fit. Thus, if the real grid e.g. has dimension 5*3, you must allocate it as a 5*4 array, where the last element in the second dimension is padding. The complex data will be written to the same array, but since that dimension is 5*2 it will now fill the entire array. Reverse complex-to-real in-place transformation will produce the same sort of padded array.

The padding does NOT apply to out-of-place transformation. In that case the input array will simply be 5*3 of real, while the output is 5*2 of complex.

Note: Data pointers are declared as void, to avoid casting pointers depending on transform direction.

void gmx_fft_cleanup ( )

Cleanup global data of FFT.

Any plans are invalid after this function. Should be called after all plans have been destroyed.

void gmx_fft_destroy ( gmx_fft_t setup )

Release an FFT setup structure.

Destroy setup and release all allocated memory.

Parameters

setup Setup returned from gmx_fft_init_1d(), or one of the other initializers.

const char* gmx_fft_get_version_info ( )

Return string describing the underlying FFT implementation.

Used to print out information about the used FFT library where needed.

int gmx_fft_init_1d	(	gmx_fft_t *	fft,
		int	nx,
		gmx_fft_flag	flags
	)

Setup a 1-dimensional complex-to-complex transform.

Parameters

fft	Pointer to opaque Gromacs FFT datatype
nx	Length of transform
flags	FFT options

Returns: status - 0 or a standard error message.

Note: Since some of the libraries (e.g. MKL) store work array data in their handles this datatype should only be used for one thread at a time, i.e. you should create one copy per thread when executing in parallel.

int gmx_fft_init_1d_real	(	gmx_fft_t *	fft,
		int	nx,
		gmx_fft_flag	flags
	)

Setup a 1-dimensional real-to-complex transform.

Parameters

fft	Pointer to opaque Gromacs FFT datatype
nx	Length of transform in real space
flags	FFT options

Returns: status - 0 or a standard error message.

Note: Since some of the libraries (e.g. MKL) store work array data in their handles this datatype should only be used for one thread at a time, i.e. you should create one copy per thread when executing in parallel.

int gmx_fft_init_2d_real	(	gmx_fft_t *	fft,
		int	nx,
		int	ny,
		gmx_fft_flag	flags
	)

Setup a 2-dimensional real-to-complex transform.

Parameters

fft	Pointer to opaque Gromacs FFT datatype
nx	Length of transform in first dimension
ny	Length of transform in second dimension
flags	FFT options

The normal space is assumed to be real, while the values in frequency space are complex.

Returns: status - 0 or a standard error message.

Note: Since some of the libraries (e.g. MKL) store work array data in their handles this datatype should only be used for one thread at a time, i.e. you should create one copy per thread when executing in parallel.

int gmx_fft_init_many_1d	(	gmx_fft_t *	fft,
		int	nx,
		int	howmany,
		gmx_fft_flag	flags
	)

Setup multiple 1-dimensional complex-to-complex transform.

Parameters

fft	Pointer to opaque Gromacs FFT datatype
nx	Length of transform
howmany	Howmany 1D FFT
flags	FFT options

Returns: status - 0 or a standard error message.

Note: Since some of the libraries (e.g. MKL) store work array data in their handles this datatype should only be used for one thread at a time, i.e. you should create one copy per thread when executing in parallel.

int gmx_fft_init_many_1d_real	(	gmx_fft_t *	fft,
		int	nx,
		int	howmany,
		gmx_fft_flag	flags
	)

Setup multiple 1-dimensional real-to-complex transform.

Parameters

fft	Pointer to opaque Gromacs FFT datatype
nx	Length of transform in real space
howmany	Homany 1D FFTs
flags	FFT options

Returns: status - 0 or a standard error message.

Note: Since some of the libraries (e.g. MKL) store work array data in their handles this datatype should only be used for one thread at a time, i.e. you should create one copy per thread when executing in parallel.

int gmx_fft_many_1d	(	gmx_fft_t	setup,
		enum gmx_fft_direction	dir,
		void *	in_data,
		void *	out_data
	)

Perform many 1-dimensional complex-to-complex transforms.

Performs many instances of a transform previously initiated.

Parameters

setup	Setup returned from gmx_fft_init_1d()
dir	Forward or Backward
in_data	Input grid data. This should be allocated with gmx_new() to make it 16-byte aligned for better performance.
out_data	Output grid data. This should be allocated with gmx_new() to make it 16-byte aligned for better performance. You can provide the same pointer for in_data and out_data to perform an in-place transform.

Returns: 0 on success, or an error code.

Note: Data pointers are declared as void, to avoid casting pointers depending on your grid type.

int gmx_fft_many_1d_real	(	gmx_fft_t	setup,
		enum gmx_fft_direction	dir,
		void *	in_data,
		void *	out_data
	)

Perform many 1-dimensional real-to-complex transforms.

Performs many instances of a transform previously initiated.

Parameters

setup	Setup returned from gmx_fft_init_1d_real()
dir	Real-to-complex or complex-to-real
in_data	Input grid data. This should be allocated with gmx_new() to make it 16-byte aligned for better performance.
out_data	Output grid data. This should be allocated with gmx_new() to make it 16-byte aligned for better performance. You can provide the same pointer for in_data and out_data to perform an in-place transform.

If you are doing an in-place transform, the array must be padded up to an even integer length so n/2 complex numbers can fit. Out-of-place arrays should not be padded (although it doesn't matter in 1d).

Returns: 0 on success, or an error code.

Note: Data pointers are declared as void, to avoid casting pointers depending on transform direction.

int gmx_fft_transpose_2d	(	t_complex *	in_data,
		t_complex *	out_data,
		int	nx,
		int	ny
	)

Transpose 2d complex matrix, in-place or out-of-place.

This routines works when the matrix is non-square, i.e. nx!=ny too, without allocating an entire matrix of work memory, which is important for huge FFT grids.

Parameters

in_data	Input data, to be transposed
out_data	Output, transposed data. If this is identical to in_data, an in-place transpose is performed.
nx	Number of rows before transpose
ny	Number of columns before transpose

Returns: GMX_SUCCESS, or an error code from gmx_errno.h

void gmx_many_fft_destroy ( gmx_fft_t setup )

Release a many FFT setup structure.

Destroy setup and release all allocated memory.

Parameters

setup Setup returned from gmx_fft_init_1d(), or one of the other initializers.

Variable Documentation

const int GMX_FFT_FLAG_CONSERVATIVE = (1<<0)

static

Flag to disable FFT optimizations based on timings, see gmx_fft_flag.

const int GMX_FFT_FLAG_NONE = 0

static

Macro to indicate no special flags for FFT routines.

Description

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation