fftw3: Words of Wisdom-Saving Plans
3.3 Words of Wisdom--Saving Plans
=================================
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. FFTW Reference, for a less casual but
more complete discussion of how to use wisdom in FFTW.
Plans created with the 'FFTW_MEASURE', 'FFTW_PATIENT', or
'FFTW_EXHAUSTIVE' options produce near-optimal FFT performance, but may
require a long time to compute because FFTW must measure the runtime of
many possible plans and select the best one. This setup 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 slower transforms, we have provided 'FFTW_ESTIMATE'. The
'wisdom' mechanism is a way to get the best of both worlds: you compute
a good plan once, save it to disk, and later reload it as many times as
necessary. The wisdom mechanism can actually save and reload many plans
at once, not just one.
Whenever you create a plan, the FFTW planner accumulates wisdom,
which is information sufficient to reconstruct the plan. After
planning, you can save this information to disk by means of the
function:
int fftw_export_wisdom_to_filename(const char *filename);
(This function returns non-zero on success.)
The next time you run the program, you can restore the wisdom with
'fftw_import_wisdom_from_filename' (which also returns non-zero on
success), and then recreate the plan using the same flags as before.
int fftw_import_wisdom_from_filename(const char *filename);
Wisdom is automatically used for any size to which it is applicable,
as long as the planner flags are not more "patient" than those with
which the wisdom was created. For example, wisdom created with
'FFTW_MEASURE' can be used if you later plan with 'FFTW_ESTIMATE' or
'FFTW_MEASURE', but not with 'FFTW_PATIENT'.
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. If memory usage is a concern, however, the wisdom can
be forgotten and its associated memory freed by calling:
void fftw_forget_wisdom(void);
Wisdom can be exported to a file, a string, or any other medium. For
details, see Wisdom.