GNU Info

(fftw.info)Words of Wisdom

---

Prev: Multi-dimensional Array Format Up: Tutorial

---

Enter node , (file) or (file)node

Words of Wisdom
===============

   FFTW implements a method for saving plans to disk and restoring them.
In fact, what FFTW does is more general than just saving and loading
plans.  The mechanism is called "`wisdom'".  Here, we describe this
feature at a high level. Note: FFTW Reference, for a less casual (but
more complete) discussion of how to use `wisdom' in FFTW.

   Plans created with the `FFTW_MEASURE' option produce near-optimal
FFT performance, but it can take a long time to compute a plan because
FFTW must actually measure the runtime of many possible plans and select
the best one.  This is designed for the situations where so many
transforms of the same size must be computed that the start-up time is
irrelevant.  For short initialization times but slightly slower
transforms, we have provided `FFTW_ESTIMATE'.  The `wisdom' mechanism
is a way to get the best of both worlds.  There are, however, certain
caveats that the user must be aware of in using `wisdom'.  For this
reason, `wisdom' is an optional feature which is not enabled by default.

   At its simplest, `wisdom' provides a way of saving plans to disk so
that they can be reused in other program runs.  You create a plan with
the flags `FFTW_MEASURE' and `FFTW_USE_WISDOM', and then save the
`wisdom' using `fftw_export_wisdom':

          plan = fftw_create_plan(..., ... | FFTW_MEASURE | FFTW_USE_WISDOM);
          fftw_export_wisdom(...);

   The next time you run the program, you can restore the `wisdom' with
`fftw_import_wisdom', and then recreate the plan using the same flags
as before.  This time, however, the same optimal plan will be created
very quickly without measurements. (FFTW still needs some time to
compute trigonometric tables, however.)  The basic outline is:

          fftw_import_wisdom(...);
          plan = fftw_create_plan(..., ... | FFTW_USE_WISDOM);

   Wisdom is more than mere rote memorization, however.  FFTW's
`wisdom' encompasses all of the knowledge and measurements that were
used to create the plan for a given size.  Therefore, existing `wisdom'
is also applied to the creation of other plans of different sizes.

   Whenever a plan is created with the `FFTW_MEASURE' and
`FFTW_USE_WISDOM' flags, `wisdom' is generated.  Thereafter, plans for
any transform with a similar factorization will be computed more
quickly, so long as they use the `FFTW_USE_WISDOM' flag.  In fact, for
transforms with the same factors and of equal or lesser size, no
measurements at all need to be made and an optimal plan can be created
with negligible delay!

   For example, suppose that you create a plan for N = 2^16.  Then, for
any equal or smaller power of two, FFTW can create a plan (with the
same direction and flags) quickly, using the precomputed `wisdom'. Even
for larger powers of two, or sizes that are a power of two times some
other prime factors, plans will be computed more quickly than they
would otherwise (although some measurements still have to be made).

   The `wisdom' is cumulative, and is stored in a global, private data
structure managed internally by FFTW.  The storage space required is
minimal, proportional to the logarithm of the sizes the `wisdom' was
generated from.  The `wisdom' can be forgotten (and its associated
memory freed) by a call to `fftw_forget_wisdom()'; otherwise, it is
remembered until the program terminates.  It can also be exported to a
file, a string, or any other medium using `fftw_export_wisdom' and
restored during a subsequent execution of the program (or a different
program) using `fftw_import_wisdom' (these functions are described
below).

   Because `wisdom' is incorporated into FFTW at a very low level, the
same `wisdom' can be used for one-dimensional transforms,
multi-dimensional transforms, and even the parallel extensions to FFTW.
Just include `FFTW_USE_WISDOM' in the flags for whatever plans you
create (i.e., always plan wisely).

   Plans created with the `FFTW_ESTIMATE' plan can use `wisdom', but
cannot generate it;  only `FFTW_MEASURE' plans actually produce
`wisdom'.  Also, plans can only use `wisdom' generated from plans
created with the same direction and flags.  For example, a size `42'
`FFTW_BACKWARD' transform will not use `wisdom' produced by a size `42'
`FFTW_FORWARD' transform.  The only exception to this rule is that
`FFTW_ESTIMATE' plans can use `wisdom' from `FFTW_MEASURE' plans.

Caveats in Using Wisdom

What you should worry about in using wisdom

Importing and Exporting Wisdom

I/O of wisdom to disk and other media