New-array Execute Functions

Chris@19: Chris@19: Chris@19: New-array Execute Functions - FFTW 3.3.4 Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19:

Chris@19: Chris@19: Chris@19:

Chris@19: Next: Wisdom, Chris@19: Previous: Guru Interface, Chris@19: Up: FFTW Reference Chris@19:

Chris@19:

Chris@19: Chris@19:

4.6 New-array Execute Functions

Chris@19: Chris@19:

Chris@19: Normally, one executes a plan for the arrays with which the plan was Chris@19: created, by calling fftw_execute(plan) as described in Using Plans. Chris@19: However, it is possible for sophisticated users to apply a given plan Chris@19: to a different array using the “new-array execute” functions Chris@19: detailed below, provided that the following conditions are met: Chris@19: Chris@19:

The array size, strides, etcetera are the same (since those are set by Chris@19: the plan). Chris@19: Chris@19:
The input and output arrays are the same (in-place) or different Chris@19: (out-of-place) if the plan was originally created to be in-place or Chris@19: out-of-place, respectively. Chris@19: Chris@19:
For split arrays, the separations between the real and imaginary Chris@19: parts, ii-ri and io-ro, are the same as they were for Chris@19: the input and output arrays when the plan was created. (This Chris@19: condition is automatically satisfied for interleaved arrays.) Chris@19: Chris@19:
The alignment of the new input/output arrays is the same as that Chris@19: of the input/output arrays when the plan was created, unless the plan Chris@19: was created with the FFTW_UNALIGNED flag. Chris@19: Here, the alignment is a platform-dependent quantity (for example, it is Chris@19: the address modulo 16 if SSE SIMD instructions are used, but the address Chris@19: modulo 4 for non-SIMD single-precision FFTW on the same machine). In Chris@19: general, only arrays allocated with fftw_malloc are guaranteed to Chris@19: be equally aligned (see SIMD alignment and fftw_malloc). Chris@19: Chris@19:

Chris@19: Chris@19:

The alignment issue is especially critical, because if you don't use Chris@19: fftw_malloc then you may have little control over the alignment Chris@19: of arrays in memory. For example, neither the C++ new function Chris@19: nor the Fortran allocate statement provide strong enough Chris@19: guarantees about data alignment. If you don't use fftw_malloc, Chris@19: therefore, you probably have to use FFTW_UNALIGNED (which Chris@19: disables most SIMD support). If possible, it is probably better for Chris@19: you to simply create multiple plans (creating a new plan is quick once Chris@19: one exists for a given size), or better yet re-use the same array for Chris@19: your transforms. Chris@19: Chris@19:

For rare circumstances in which you cannot control the alignment of Chris@19: allocated memory, but wish to determine where a given array is Chris@19: aligned like the original array for which a plan was created, you can Chris@19: use the fftw_alignment_of function: Chris@19:

     int fftw_alignment_of(double *p);
Chris@19:

Chris@19:

Two arrays have equivalent alignment (for the purposes of applying a Chris@19: plan) if and only if fftw_alignment_of returns the same value Chris@19: for the corresponding pointers to their data (typecast to double* Chris@19: if necessary). Chris@19: Chris@19:

If you are tempted to use the new-array execute interface because you Chris@19: want to transform a known bunch of arrays of the same size, you should Chris@19: probably go use the advanced interface instead (see Advanced Interface)). Chris@19: Chris@19:

The new-array execute functions are: Chris@19: Chris@19:

     void fftw_execute_dft(
Chris@19:           const fftw_plan p,
Chris@19:           fftw_complex *in, fftw_complex *out);
Chris@19:      
Chris@19:      void fftw_execute_split_dft(
Chris@19:           const fftw_plan p,
Chris@19:           double *ri, double *ii, double *ro, double *io);
Chris@19:      
Chris@19:      void fftw_execute_dft_r2c(
Chris@19:           const fftw_plan p,
Chris@19:           double *in, fftw_complex *out);
Chris@19:      
Chris@19:      void fftw_execute_split_dft_r2c(
Chris@19:           const fftw_plan p,
Chris@19:           double *in, double *ro, double *io);
Chris@19:      
Chris@19:      void fftw_execute_dft_c2r(
Chris@19:           const fftw_plan p,
Chris@19:           fftw_complex *in, double *out);
Chris@19:      
Chris@19:      void fftw_execute_split_dft_c2r(
Chris@19:           const fftw_plan p,
Chris@19:           double *ri, double *ii, double *out);
Chris@19:      
Chris@19:      void fftw_execute_r2r(
Chris@19:           const fftw_plan p,
Chris@19:           double *in, double *out);
Chris@19:

Chris@19:

Chris@19: These execute the plan to compute the corresponding transform on Chris@19: the input/output arrays specified by the subsequent arguments. The Chris@19: input/output array arguments have the same meanings as the ones passed Chris@19: to the guru planner routines in the preceding sections. The plan Chris@19: is not modified, and these routines can be called as many times as Chris@19: desired, or intermixed with calls to the ordinary fftw_execute. Chris@19: Chris@19:

The plan must have been created for the transform type Chris@19: corresponding to the execute function, e.g. it must be a complex-DFT Chris@19: plan for fftw_execute_dft. Any of the planner routines for that Chris@19: transform type, from the basic to the guru interface, could have been Chris@19: used to create the plan, however. Chris@19: Chris@19: Chris@19: Chris@19: