Gromacs
2023.2

Fast Fourier Transforms.
This file provides an abstract Gromacs interface to Fourier transforms, including multidimensional and realtocomplex transforms.
Internally it is implemented as wrappers to external libraries such as FFTW or the Intel Math Kernel Library, but we also have a builtin version of FFTPACK in case the faster alternatives are unavailable.
We also provide our own multidimensional 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 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 1dimensional complextocomplex transform. More...  
int  gmx_fft_init_many_1d (gmx_fft_t *fft, int nx, int howmany, gmx_fft_flag flags) 
Setup multiple 1dimensional complextocomplex transform. More...  
int  gmx_fft_init_1d_real (gmx_fft_t *fft, int nx, gmx_fft_flag flags) 
Setup a 1dimensional realtocomplex transform. More...  
int  gmx_fft_init_many_1d_real (gmx_fft_t *fft, int nx, int howmany, gmx_fft_flag flags) 
Setup multiple 1dimensional realtocomplex transform. More...  
int  gmx_fft_init_2d_real (gmx_fft_t *fft, int nx, int ny, gmx_fft_flag flags) 
Setup a 2dimensional realtocomplex transform. More...  
int  gmx_fft_1d (gmx_fft_t setup, enum gmx_fft_direction dir, void *in_data, void *out_data) 
Perform a 1dimensional complextocomplex transform. More...  
int  gmx_fft_many_1d (gmx_fft_t setup, enum gmx_fft_direction dir, void *in_data, void *out_data) 
Perform many 1dimensional complextocomplex transforms. More...  
int  gmx_fft_1d_real (gmx_fft_t setup, enum gmx_fft_direction dir, void *in_data, void *out_data) 
Perform a 1dimensional realtocomplex 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 1dimensional realtocomplex transforms. More...  
int  gmx_fft_2d_real (gmx_fft_t setup, enum gmx_fft_direction dir, void *in_data, void *out_data) 
Perform a 2dimensional realtocomplex 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, inplace or outofplace. More...  
void  gmx_fft_cleanup () 
Cleanup global data of FFT. 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 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 builtin 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.
enum gmx_fft_direction 
Specifier for FFT direction.
The definition of the 1D forward transform from input x[] to output y[] is
while the corresponding backward transform is
A forwardbackward transform pair will this result in data scaled by N.
For complextocomplex transforms you can only use one of GMX_FFT_FORWARD or GMX_FFT_BACKWARD, and for realcomplex transforms you can only use GMX_FFT_REAL_TO_COMPLEX or GMX_FFT_COMPLEX_TO_REAL.
int gmx_fft_1d  (  gmx_fft_t  setup, 
enum gmx_fft_direction  dir,  
void *  in_data,  
void *  out_data  
) 
Perform a 1dimensional complextocomplex transform.
Performs an instance of a transform previously initiated.
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 16byte aligned for better performance. 
out_data  Output grid data. This should be allocated with gmx_new() to make it 16byte aligned for better performance. You can provide the same pointer for in_data and out_data to perform an inplace transform. 
int gmx_fft_1d_real  (  gmx_fft_t  setup, 
enum gmx_fft_direction  dir,  
void *  in_data,  
void *  out_data  
) 
Perform a 1dimensional realtocomplex transform.
Performs an instance of a transform previously initiated.
setup  Setup returned from gmx_fft_init_1d_real() 
dir  Realtocomplex or complextoreal 
in_data  Input grid data. This should be allocated with gmx_new() to make it 16byte aligned for better performance. 
out_data  Output grid data. This should be allocated with gmx_new() to make it 16byte aligned for better performance. You can provide the same pointer for in_data and out_data to perform an inplace transform. 
If you are doing an inplace transform, the array must be padded up to an even integer length so n/2 complex numbers can fit. Outofplace arrays should not be padded (although it doesn't matter in 1d).
int gmx_fft_2d_real  (  gmx_fft_t  setup, 
enum gmx_fft_direction  dir,  
void *  in_data,  
void *  out_data  
) 
Perform a 2dimensional realtocomplex transform.
Performs an instance of a transform previously initiated.
setup  Setup returned from gmx_fft_init_1d_real() 
dir  Realtocomplex or complextoreal 
in_data  Input grid data. This should be allocated with gmx_new() to make it 16byte aligned for better performance. 
out_data  Output grid data. This should be allocated with gmx_new() to make it 16byte aligned for better performance. You can provide the same pointer for in_data and out_data to perform an inplace transform. 
The padding does NOT apply to outofplace transformation. In that case the input array will simply be 5*3 of real, while the output is 5*2 of complex.
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.
setup  Setup returned from gmx_fft_init_1d(), or one of the other initializers. 
int gmx_fft_init_1d  (  gmx_fft_t *  fft, 
int  nx,  
gmx_fft_flag  flags  
) 
Setup a 1dimensional complextocomplex transform.
fft  Pointer to opaque Gromacs FFT datatype 
nx  Length of transform 
flags  FFT options 
int gmx_fft_init_1d_real  (  gmx_fft_t *  fft, 
int  nx,  
gmx_fft_flag  flags  
) 
Setup a 1dimensional realtocomplex transform.
fft  Pointer to opaque Gromacs FFT datatype 
nx  Length of transform in real space 
flags  FFT options 
int gmx_fft_init_2d_real  (  gmx_fft_t *  fft, 
int  nx,  
int  ny,  
gmx_fft_flag  flags  
) 
Setup a 2dimensional realtocomplex transform.
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.
int gmx_fft_init_many_1d  (  gmx_fft_t *  fft, 
int  nx,  
int  howmany,  
gmx_fft_flag  flags  
) 
Setup multiple 1dimensional complextocomplex transform.
fft  Pointer to opaque Gromacs FFT datatype 
nx  Length of transform 
howmany  Howmany 1D FFT 
flags  FFT options 
int gmx_fft_init_many_1d_real  (  gmx_fft_t *  fft, 
int  nx,  
int  howmany,  
gmx_fft_flag  flags  
) 
Setup multiple 1dimensional realtocomplex transform.
fft  Pointer to opaque Gromacs FFT datatype 
nx  Length of transform in real space 
howmany  Homany 1D FFTs 
flags  FFT options 
int gmx_fft_many_1d  (  gmx_fft_t  setup, 
enum gmx_fft_direction  dir,  
void *  in_data,  
void *  out_data  
) 
Perform many 1dimensional complextocomplex transforms.
Performs many instances of a transform previously initiated.
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 16byte aligned for better performance. 
out_data  Output grid data. This should be allocated with gmx_new() to make it 16byte aligned for better performance. You can provide the same pointer for in_data and out_data to perform an inplace transform. 
int gmx_fft_many_1d_real  (  gmx_fft_t  setup, 
enum gmx_fft_direction  dir,  
void *  in_data,  
void *  out_data  
) 
Perform many 1dimensional realtocomplex transforms.
Performs many instances of a transform previously initiated.
setup  Setup returned from gmx_fft_init_1d_real() 
dir  Realtocomplex or complextoreal 
in_data  Input grid data. This should be allocated with gmx_new() to make it 16byte aligned for better performance. 
out_data  Output grid data. This should be allocated with gmx_new() to make it 16byte aligned for better performance. You can provide the same pointer for in_data and out_data to perform an inplace transform. 
If you are doing an inplace transform, the array must be padded up to an even integer length so n/2 complex numbers can fit. Outofplace arrays should not be padded (although it doesn't matter in 1d).
int gmx_fft_transpose_2d  (  t_complex *  in_data, 
t_complex *  out_data,  
int  nx,  
int  ny  
) 
Transpose 2d complex matrix, inplace or outofplace.
This routines works when the matrix is nonsquare, i.e. nx!=ny too, without allocating an entire matrix of work memory, which is important for huge FFT grids.
in_data  Input data, to be transposed 
out_data  Output, transposed data. If this is identical to in_data, an inplace transpose is performed. 
nx  Number of rows before transpose 
ny  Number of columns before transpose 
void gmx_many_fft_destroy  (  gmx_fft_t  setup  ) 
Release a many FFT setup structure.
Destroy setup and release all allocated memory.
setup  Setup returned from gmx_fft_init_1d(), or one of the other initializers. 

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

static 
Macro to indicate no special flags for FFT routines.