GNU Info

(fftw.info)fftw_create_plan

---

Next: Discussion on Specific Plans Prev: One-dimensional Transforms Reference Up: One-dimensional Transforms Reference

---

Enter node , (file) or (file)node

Plan Creation for One-dimensional Transforms
--------------------------------------------

     #include <fftw.h>
     
     fftw_plan fftw_create_plan(int n, fftw_direction dir,
                                int flags);
     
     fftw_plan fftw_create_plan_specific(int n, fftw_direction dir,
                                         int flags,
                                         fftw_complex *in, int istride,
                                         fftw_complex *out, int ostride);

   The function `fftw_create_plan' creates a plan, which is a data
structure containing all the information that `fftw' needs in order to
compute the 1D Fourier transform. You can create as many plans as you
need, but only one plan for a given array size is required (a plan can
be reused many times).

   `fftw_create_plan' returns a valid plan, or `NULL' if, for some
reason, the plan can't be created.  In the default installation, this
cannot happen, but it is possible to configure FFTW in such a way that
some input sizes are forbidden, and FFTW cannot create a plan.

   The `fftw_create_plan_specific' variant takes as additional
arguments specific input/output arrays and their strides.  For the last
four arguments, you should pass the arrays and strides that you will
eventually be passing to `fftw'.  The resulting plans will be optimized
for those arrays and strides, although they may be used on other arrays
as well.  Note: the contents of the in and out arrays are *destroyed*
by the specific planner (the initial contents are ignored, so the
arrays need not have been initialized).

Arguments
.........

   * `n' is the size of the transform.  It can be  any positive integer.

        - FFTW is best at handling sizes of the form 2^a 3^b 5^c 7^d
          11^e 13^f, where e+f is either 0 or 1, and the other
          exponents are arbitrary.  Other sizes are computed by means
          of a slow, general-purpose routine (which nevertheless retains
          O(n lg n) performance, even for prime sizes).  (It is
          possible to customize FFTW for different array sizes.  Note:
          Installation and Customization, for more information.)
          Transforms whose sizes are powers of 2 are especially fast.

   * `dir' is the sign of the exponent in the formula that defines the
     Fourier transform.  It can be -1 or +1.  The aliases
     `FFTW_FORWARD' and `FFTW_BACKWARD' are provided, where
     `FFTW_FORWARD' stands for -1.

   * `flags' is a boolean OR (`|') of zero or more of the following:
        - `FFTW_MEASURE': this flag tells FFTW to find the optimal plan
          by actually *computing* several FFTs and measuring their
          execution time.  Depending on the installation, this can take
          some time. (1)

        - `FFTW_ESTIMATE': do not run any FFT and provide a "reasonable"
          plan (for a RISC processor with many registers).  If neither
          `FFTW_ESTIMATE' nor `FFTW_MEASURE' is provided, the default is
          `FFTW_ESTIMATE'.

        - `FFTW_OUT_OF_PLACE': produce a plan assuming that the input
          and output arrays will be distinct (this is the default).

        - `FFTW_IN_PLACE': produce a plan assuming that you want the
          output in the input array.  The algorithm used is not
          necessarily in place: FFTW is able to compute true in-place
          transforms only for small values of `n'.  If FFTW is not able
          to compute the transform in-place, it will allocate a
          temporary array (unless you provide one yourself), compute
          the transform out of place, and copy the result back.
          *Warning: This option changes the meaning of some parameters
          of `fftw'* (*note Computing the One-dimensional Transform:
          fftw.).

          The in-place option is mainly provided for people who want to
          write their own in-place multi-dimensional Fourier transform,
          using FFTW as a base.  For example, consider a
          three-dimensional `n * n * n' transform.  An out-of-place
          algorithm will need another array (which may be huge).
          However, FFTW can compute the in-place transform along each
          dimension using only a temporary array of size `n'.
          Moreover, if FFTW happens to be able to compute the transform
          truly in-place, no temporary array and no copying are needed.
          As distributed, FFTW `knows' how to compute in-place
          transforms of size 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13,
          14, 15, 16, 32 and 64.

          The default mode of operation is `FFTW_OUT_OF_PLACE'.

        - `FFTW_USE_WISDOM': use any `wisdom' that is available to help
          in the creation of the plan. (Note: Words of Wisdom.)  This
          can greatly speed the creation of plans, especially with the
          `FFTW_MEASURE' option. `FFTW_ESTIMATE' plans can also take
          advantage of `wisdom' to produce a more optimal plan (based
          on past measurements) than the estimation heuristic would
          normally generate. When the `FFTW_MEASURE' option is used,
          new `wisdom' will also be generated if the current transform
          size is not completely understood by existing `wisdom'.

   * `in', `out', `istride', `ostride' (only for
     `fftw_create_plan_specific'): see corresponding arguments in the
     description of `fftw'.  (Note: Computing the One-dimensional
     Transform.)  In particular, the `out' and `ostride'
     parameters have the same special meaning for `FFTW_IN_PLACE'
     transforms as they have for `fftw'.

   ---------- Footnotes ----------

   (1) The basic problem is the resolution of the clock: FFTW needs to
run for a certain time for the clock to be reliable.