Gromacs
2024.3
|
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 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... | |
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 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.
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 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.
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.
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. |
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.
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).
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.
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. |
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.
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 1-dimensional complex-to-complex 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 1-dimensional real-to-complex 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 2-dimensional real-to-complex 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 1-dimensional complex-to-complex 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 1-dimensional real-to-complex 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 1-dimensional complex-to-complex 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 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. |
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.
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).
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.
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 |
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.