cannam@95: Next: Advanced Real-data DFTs, cannam@95: Previous: Advanced Interface, cannam@95: Up: Advanced Interface cannam@95:
fftw_plan fftw_plan_many_dft(int rank, const int *n, int howmany, cannam@95: fftw_complex *in, const int *inembed, cannam@95: int istride, int idist, cannam@95: fftw_complex *out, const int *onembed, cannam@95: int ostride, int odist, cannam@95: int sign, unsigned flags); cannam@95:cannam@95:
cannam@95: This routine plans multiple multidimensional complex DFTs, and it
cannam@95: extends the fftw_plan_dft routine (see Complex DFTs) to
cannam@95: compute howmany transforms, each having rank rank and size
cannam@95: n. In addition, the transform data need not be contiguous, but
cannam@95: it may be laid out in memory with an arbitrary stride. To account for
cannam@95: these possibilities, fftw_plan_many_dft adds the new parameters
cannam@95: howmany, {i,o}nembed,
cannam@95: {i,o}stride, and
cannam@95: {i,o}dist. The FFTW basic interface
cannam@95: (see Complex DFTs) provides routines specialized for ranks 1, 2,
cannam@95: and 3, but the advanced interface handles only the general-rank
cannam@95: case.
cannam@95:
cannam@95:
howmany is the number of transforms to compute. The resulting
cannam@95: plan computes howmany transforms, where the input of the
cannam@95: k-th transform is at location in+k*idist (in C pointer
cannam@95: arithmetic), and its output is at location out+k*odist. Plans
cannam@95: obtained in this way can often be faster than calling FFTW multiple
cannam@95: times for the individual transforms. The basic fftw_plan_dft
cannam@95: interface corresponds to howmany=1 (in which case the dist
cannam@95: parameters are ignored).
cannam@95:
cannam@95:
cannam@95:
Each of the howmany transforms has rank rank and size
cannam@95: n, as in the basic interface. In addition, the advanced
cannam@95: interface allows the input and output arrays of each transform to be
cannam@95: row-major subarrays of larger rank-rank arrays, described by
cannam@95: inembed and onembed parameters, respectively.
cannam@95: {i,o}nembed must be arrays of length rank,
cannam@95: and n should be elementwise less than or equal to
cannam@95: {i,o}nembed. Passing NULL for an
cannam@95: nembed parameter is equivalent to passing n (i.e. same
cannam@95: physical and logical dimensions, as in the basic interface.)
cannam@95:
cannam@95:
The stride parameters indicate that the j-th element of
cannam@95: the input or output arrays is located at j*istride or
cannam@95: j*ostride, respectively. (For a multi-dimensional array,
cannam@95: j is the ordinary row-major index.) When combined with the
cannam@95: k-th transform in a howmany loop, from above, this means
cannam@95: that the (j,k)-th element is at j*stride+k*dist.
cannam@95: (The basic fftw_plan_dft interface corresponds to a stride of 1.)
cannam@95:
cannam@95:
cannam@95:
For in-place transforms, the input and output stride and
cannam@95: dist parameters should be the same; otherwise, the planner may
cannam@95: return NULL.
cannam@95:
cannam@95:
Arrays n, inembed, and onembed are not used after
cannam@95: this function returns. You can safely free or reuse them.
cannam@95:
cannam@95:
Examples: cannam@95: One transform of one 5 by 6 array contiguous in memory: cannam@95:
int rank = 2;
cannam@95: int n[] = {5, 6};
cannam@95: int howmany = 1;
cannam@95: int idist = odist = 0; /* unused because howmany = 1 */
cannam@95: int istride = ostride = 1; /* array is contiguous in memory */
cannam@95: int *inembed = n, *onembed = n;
cannam@95:
cannam@95: Transform of three 5 by 6 arrays, each contiguous in memory, cannam@95: stored in memory one after another: cannam@95:
int rank = 2;
cannam@95: int n[] = {5, 6};
cannam@95: int howmany = 3;
cannam@95: int idist = odist = n[0]*n[1]; /* = 30, the distance in memory
cannam@95: between the first element
cannam@95: of the first array and the
cannam@95: first element of the second array */
cannam@95: int istride = ostride = 1; /* array is contiguous in memory */
cannam@95: int *inembed = n, *onembed = n;
cannam@95:
cannam@95: Transform each column of a 2d array with 10 rows and 3 columns: cannam@95:
int rank = 1; /* not 2: we are computing 1d transforms */
cannam@95: int n[] = {10}; /* 1d transforms of length 10 */
cannam@95: int howmany = 3;
cannam@95: int idist = odist = 1;
cannam@95: int istride = ostride = 3; /* distance between two elements in
cannam@95: the same column */
cannam@95: int *inembed = n, *onembed = n;
cannam@95:
cannam@95:
cannam@95:
cannam@95: