FFTW-WISDOM(1)

💖 FFTW-WISDOM(1) — like, the manual page, but make it make sense 💖

okay bestie, so this is fftw-wisdom, and it lives in the fftw section of your man pages. it's a little command-line icon and i'm about to tell you everything it does, no gatekeeping. 🫶

✨ NAME ✨

fftw-wisdom — create wisdom (pre-optimized FFTs) 👑

🌸 SYNOPSIS 🌸

fftw-wisdom [OPTION]... [SIZE]...

🦋 DESCRIPTION 🦋

so fftw-wisdom is a utility that generates FFTW wisdom files. and what's in a wisdom file? literally saved info about how to optimally compute (Fourier) transforms of various sizes. it's the cheat sheet of FFT knowledge, periodt.

FFTW itself is a free library for computing discrete Fourier transforms — one dimension or multiple, arbitrary sizes, real and complex data, plus a bunch of related operations. more deets live at the FFTW home page: http://www.fftw.org

programs that use FFTW can be written to load wisdom from an arbitrary file, string, or other source. and honestly? a lot of FFTW-using programs probably load the system wisdom file, which lives at /etc/fftw/wisdom by default. fftw-wisdom is what you use to create that file or add to it. 🎀

the most typical usage — pre-planning a canonical set of sizes (see below) — looks like:

fftw-wisdom -v -c -o wisdom

⚠️ heads up bestie: that will take many hours. you can cap it with the -t option. then you copy the output wisdom file (as root) to /etc/fftw/ or wherever you want it to live.

normally fftw-wisdom writes the wisdom straight to standard output, but you can change that with -o, like in the example above. 💅

if the system wisdom file /etc/fftw/wisdom already exists, then fftw-wisdom reads that existing wisdom (unless you pass -n) and outputs both the old wisdom and any newly created wisdom. which means you can use it to add new transform sizes to the existing system wisdom — or to any other wisdom file, via -w. slay.

🔥 SPECIFYING SIZES 🔥

so the -c option gives you a canonical set of sizes to optimize, but that's not the only way, bestie. you can also pass zero or more non-canonical transform sizes and types yourself, via the SIZE arguments that follow the option flags. or — plot twist — you can read the sizes to optimize from standard input (whitespace-separated) by supplying a SIZE argument of -.

sizes are specified with this syntax:

<type><inplace><direction><geometry>

• <type> is either c (complex), r (real, r2c/c2r), or k (r2r, per-dimension kinds, specified in the geometry, below).
• <inplace> is either i (in place) or o (out of place).
• <direction> is either f (forward) or b (backward). the <direction> should be omitted for k transforms, where it gets specified via the geometry instead.
• <geometry> is the size and dimensionality of the transform, where different dimensions are separated by x (e.g. 16x32 for a two-dimensional 16 by 32 transform). for k transforms, the size of each dimension is followed by a "type" string, which can be one of f/b/h/e00/e01/e10/e11/o00/o01/o10/o11 for R2HC/HC2R/DHT/REDFT00/.../RODFT11, respectively, as defined in the FFTW manual.

examples, because i know you're a visual learner 🧚:

• cif12x13x14 — a three-dimensional 12 by 13 x 14 complex DFT operating in-place.
• rob65536 — a one-dimensional size-65536 out-of-place complex-to-real (backwards) transform operating on Hermitian-symmetry input.
• ki10hx20e01 — a two-dimensional 10 by 20 r2r transform where the first dimension is a DHT and the second dimension is an REDFT01 (DCT-III).

💅 OPTIONS 💅

• -h, --help — display help on the command-line options and usage.
• -V, --version — print the version number and copyright information.
• -v, --verbose — verbose output. (you can specify this multiple times, or supply a numeric argument greater than 1, to increase the verbosity level.) note that the verbose output will be mixed with the wisdom output (making it impossible to import), unless you write the wisdom to a file via the -o option.
• -c, --canonical — optimize/pre-plan a canonical set of sizes: all powers of two and ten up to 2^20 (1048576), including both real and complex, forward and backwards, in-place and out-of-place transforms. also includes two- and three-dimensional transforms of equal-size dimensions (e.g. 16x16x16).
• -t hours, --time-limit=hours — stop after a time of hours (hours) has elapsed, outputting accumulated wisdom. (the problems are planned in increasing order of size.) defaults to 0, indicating no time limit.
• -o file, --output-file=file — send wisdom output to file rather than to standard output (the default).
• -m, --measure; -e, --estimate; -x, --exhaustive — normally, fftw-wisdom creates plans in FFTW_PATIENT mode, but with these options you can instead use FFTW_MEASURE, FFTW_ESTIMATE, or FFTW_EXHAUSTIVE modes, respectively, as described in more detail by the FFTW manual.

note that wisdom is tagged with the planning patience level, and a single file can mix different levels of wisdom (e.g. you can mostly use the patient default, but plan a few sizes that you especially care about in --exhaustive mode). 💖

• -n, --no-system-wisdom — do not import the system wisdom from /etc/fftw/wisdom (which is normally read by default).
• -w file, --wisdom-file=file — import wisdom from file (in addition to the system wisdom, unless -n is specified). multiple wisdom files can be read via multiple -w options. if file is -, then read wisdom from standard input.
• -T N, --threads=N — plan with N threads. this option is only present if FFTW was configured with thread support.

😭 BUGS 😭

send bug reports to fftw@fftw.org. be nice, they're doing their best. 🙈

👑 AUTHORS 👑

written by Steven G. Johnson and Matteo Frigo.

Copyright (c) 2003, 2007-14 Matteo Frigo
Copyright (c) 2003, 2007-14 Massachusetts Institute of Technology

🌈 SEE ALSO 🌈

• fftw-wisdom-to-conf(1)

and that's the whole page, bestie. this little manual has been living in the fftw collection since February, 2003 — iconic behavior honestly, still relevant, still slaying. go generate some wisdom. 🎀✨💜