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. See 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.