FFTW 3.3.8: Advanced Complex DFTs

cannam@167:

fftw_plan fftw_plan_many_dft(int rank, const int *n, int howmany,
cannam@167:                              fftw_complex *in, const int *inembed,
cannam@167:                              int istride, int idist,
cannam@167:                              fftw_complex *out, const int *onembed,
cannam@167:                              int ostride, int odist,
cannam@167:                              int sign, unsigned flags);
cannam@167:

This routine plans multiple multidimensional complex DFTs, and it cannam@167: extends the fftw_plan_dft routine (see Complex DFTs) to cannam@167: compute howmany transforms, each having rank rank and size cannam@167: n. In addition, the transform data need not be contiguous, but cannam@167: it may be laid out in memory with an arbitrary stride. To account for cannam@167: these possibilities, fftw_plan_many_dft adds the new parameters cannam@167: howmany, {i,o}nembed, cannam@167: {i,o}stride, and cannam@167: {i,o}dist. The FFTW basic interface cannam@167: (see Complex DFTs) provides routines specialized for ranks 1, 2, cannam@167: and 3, but the advanced interface handles only the general-rank cannam@167: case. cannam@167:

howmany is the (nonnegative) number of transforms to compute. The resulting cannam@167: plan computes howmany transforms, where the input of the cannam@167: k-th transform is at location in+k*idist (in C pointer cannam@167: arithmetic), and its output is at location out+k*odist. Plans cannam@167: obtained in this way can often be faster than calling FFTW multiple cannam@167: times for the individual transforms. The basic fftw_plan_dft cannam@167: interface corresponds to howmany=1 (in which case the dist cannam@167: parameters are ignored). cannam@167: cannam@167: cannam@167:

Each of the howmany transforms has rank rank and size cannam@167: n, as in the basic interface. In addition, the advanced cannam@167: interface allows the input and output arrays of each transform to be cannam@167: row-major subarrays of larger rank-rank arrays, described by cannam@167: inembed and onembed parameters, respectively. cannam@167: {i,o}nembed must be arrays of length rank, cannam@167: and n should be elementwise less than or equal to cannam@167: {i,o}nembed. Passing NULL for an cannam@167: nembed parameter is equivalent to passing n (i.e. same cannam@167: physical and logical dimensions, as in the basic interface.) cannam@167:

The stride parameters indicate that the j-th element of cannam@167: the input or output arrays is located at j*istride or cannam@167: j*ostride, respectively. (For a multi-dimensional array, cannam@167: j is the ordinary row-major index.) When combined with the cannam@167: k-th transform in a howmany loop, from above, this means cannam@167: that the (j,k)-th element is at j*stride+k*dist. cannam@167: (The basic fftw_plan_dft interface corresponds to a stride of 1.) cannam@167: cannam@167:

For in-place transforms, the input and output stride and cannam@167: dist parameters should be the same; otherwise, the planner may cannam@167: return NULL. cannam@167:

Arrays n, inembed, and onembed are not used after cannam@167: this function returns. You can safely free or reuse them. cannam@167:

Examples: cannam@167: One transform of one 5 by 6 array contiguous in memory: cannam@167:

cannam@167:

   int rank = 2;
cannam@167:    int n[] = {5, 6};
cannam@167:    int howmany = 1;
cannam@167:    int idist = odist = 0; /* unused because howmany = 1 */
cannam@167:    int istride = ostride = 1; /* array is contiguous in memory */
cannam@167:    int *inembed = n, *onembed = n;
cannam@167:

Transform of three 5 by 6 arrays, each contiguous in memory, cannam@167: stored in memory one after another: cannam@167:

cannam@167:

   int rank = 2;
cannam@167:    int n[] = {5, 6};
cannam@167:    int howmany = 3;
cannam@167:    int idist = odist = n[0]*n[1]; /* = 30, the distance in memory
cannam@167:                                      between the first element
cannam@167:                                      of the first array and the
cannam@167:                                      first element of the second array */
cannam@167:    int istride = ostride = 1; /* array is contiguous in memory */
cannam@167:    int *inembed = n, *onembed = n;
cannam@167:

cannam@167:

   int rank = 1; /* not 2: we are computing 1d transforms */
cannam@167:    int n[] = {10}; /* 1d transforms of length 10 */
cannam@167:    int howmany = 3;
cannam@167:    int idist = odist = 1;
cannam@167:    int istride = ostride = 3; /* distance between two elements in 
cannam@167:                                  the same column */
cannam@167:    int *inembed = n, *onembed = n;
cannam@167:

4.4.1 Advanced Complex DFTs