Chris@82: .\" 
Chris@82: .\" Copyright (c) 2003, 2007-14 Matteo Frigo
Chris@82: .\" Copyright (c) 2003, 2007-14 Massachusetts Institute of Technology
Chris@82: .\" 
Chris@82: .\" This program is free software; you can redistribute it and/or modify
Chris@82: .\" it under the terms of the GNU General Public License as published by
Chris@82: .\" the Free Software Foundation; either version 2 of the License, or
Chris@82: .\" (at your option) any later version.
Chris@82: .\" 
Chris@82: .\" This program is distributed in the hope that it will be useful,
Chris@82: .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
Chris@82: .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
Chris@82: .\" GNU General Public License for more details.
Chris@82: .\" 
Chris@82: .\" You should have received a copy of the GNU General Public License
Chris@82: .\" along with this program; if not, write to the Free Software
Chris@82: .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
Chris@82: .\"
Chris@82: .TH FFTW-WISDOM 1 "February, 2003" "fftw" "fftw"
Chris@82: .SH NAME
Chris@82: fftwf\-wisdom \- create wisdom (pre-optimized FFTs)
Chris@82: .SH SYNOPSIS
Chris@82: .B fftwf\-wisdom
Chris@82: [\fIOPTION\fR]... [\fISIZE\fR]...
Chris@82: .SH DESCRIPTION
Chris@82: .PP
Chris@82: .\" Add any additional description here
Chris@82: .I fftwf\-wisdom
Chris@82: is a utility to generate FFTW
Chris@82: .B wisdom
Chris@82: files, which contain saved information about how to optimally compute
Chris@82: (Fourier) transforms of various sizes.  FFTW is a free library to
Chris@82: compute discrete Fourier transforms in one or more dimensions, for
Chris@82: arbitrary sizes, and of both real and complex data, among other
Chris@82: related operations.  More information on FFTW can be found at the FFTW
Chris@82: home page:
Chris@82: .I http://www.fftw.org
Chris@82: 
Chris@82: Programs using FFTW can be written to load wisdom from an arbitrary file,
Chris@82: string, or other source.  Moreover, it is likely that many FFTW-using
Chris@82: programs will load the \fBsystem wisdom\fR file, which is stored in
Chris@82: .I /etc/fftw/wisdomf
Chris@82: by default.
Chris@82: .I fftwf\-wisdom
Chris@82: can be used to create or add to such wisdom files.  In its most
Chris@82: typical usage, the wisdom file can be created to pre-plan a canonical
Chris@82: set of sizes (see below) via:
Chris@82: 
Chris@82: .ce
Chris@82: fftwf\-wisdom \-v \-c \-o wisdomf
Chris@82: 
Chris@82: (this will take many hours, which can be limited by the 
Chris@82: .B \-t
Chris@82: option) and the output
Chris@82: .I wisdomf
Chris@82: file can then be copied (as root) to
Chris@82: .I /etc/fftw/
Chris@82: or whatever.
Chris@82: 
Chris@82: The
Chris@82: .I fftwf\-wisdom
Chris@82: program normally writes the wisdom directly to standard output, but this
Chris@82: can be changed via the
Chris@82: .B \-o
Chris@82: option, as in the example above.
Chris@82: 
Chris@82: If the system wisdom file
Chris@82: .I /etc/fftw/wisdomf
Chris@82: already exists, then
Chris@82: .I fftwf\-wisdom
Chris@82: reads this existing wisdom (unless the
Chris@82: .B \-n
Chris@82: option is specified) and outputs both the old wisdom and any
Chris@82: newly created wisdom.  In this way, it can be used to add new transform
Chris@82: sizes to the existing system wisdom (or other wisdom file, with the 
Chris@82: .B \-w
Chris@82: option).
Chris@82: .SH SPECIFYING SIZES
Chris@82: Although a canonical set of sizes to optimize is specified by the 
Chris@82: .B \-c
Chris@82: option, the user can also specify zero or more non-canonical transform
Chris@82: sizes and types to optimize, via the 
Chris@82: .I SIZE
Chris@82: arguments following the option flags.  Alternatively, the sizes to
Chris@82: optimize can be read from standard input (whitespace-separated), if a
Chris@82: .I SIZE
Chris@82: argument of "\-" is supplied.
Chris@82: 
Chris@82: Sizes are specified by the syntax:
Chris@82: 
Chris@82: .ce
Chris@82: <\fItype\fR><\fIinplace\fR><\fIdirection\fR><\fIgeometry\fR>
Chris@82: 
Chris@82: <\fItype\fR> is either \'c\' (complex), \'r\' (real, r2c/c2r), or
Chris@82: \'k\' (r2r, per-dimension kinds, specified in the geometry, below).
Chris@82: 
Chris@82: <\fIinplace\fR> is either \'i\' (in place) or \'o\' (out of place).
Chris@82: 
Chris@82: <\fIdirection\fR> is either \'f\' (forward) or \'b\' (backward).  The
Chris@82: <\fIdirection\fR> should be omitted for \'k\' transforms, where it is
Chris@82: specified via the geometry instead.
Chris@82: 
Chris@82: <\fIgeometry\fR> is the size and dimensionality of the transform,
Chris@82: where different dimensions are separated by \'x\' (e.g. \'16x32\' for
Chris@82: a two-dimensional 16 by 32 transform).  In the case of \'k\'
Chris@82: transforms, the size of each dimension is followed by a "type" string,
Chris@82: which can be one of f/b/h/e00/e01/e10/e11/o00/o01/o10/o11 for
Chris@82: R2HC/HC2R/DHT/REDFT00/.../RODFT11, respectively, as defined in the
Chris@82: FFTW manual.
Chris@82: 
Chris@82: For example, \'cif12x13x14\' is a three-dimensional 12 by 13 x 14
Chris@82: complex DFT operating in-place.  \'rob65536\' is a one-dimensional
Chris@82: size-65536 out-of-place complex-to-real (backwards) transform
Chris@82: operating on Hermitian-symmetry input.  \'ki10hx20e01\' is a
Chris@82: two-dimensional 10 by 20 r2r transform where the first dimension is a
Chris@82: DHT and the second dimension is an REDFT01 (DCT-III).
Chris@82: 
Chris@82: .SH OPTIONS
Chris@82: .TP
Chris@82: \fB\-h\fR, \fB\-\-help\fR
Chris@82: Display help on the command-line options and usage.
Chris@82: .TP
Chris@82: \fB\-V\fR, \fB\-\-version\fR
Chris@82: Print the version number and copyright information.
Chris@82: .TP
Chris@82: \fB\-v\fR, \fB\-\-verbose\fR
Chris@82: Verbose output.  (You can specify this multiple times, or supply a numeric
Chris@82: argument greater than 1, to increase the verbosity level.)  Note that the
Chris@82: verbose output will be mixed with the wisdom output (making it impossible
Chris@82: to import), unless you write the wisdom to a file via the 
Chris@82: .B \-o
Chris@82: option.
Chris@82: .TP
Chris@82: \fB\-c\fR, \fB\-\-canonical\fR
Chris@82: Optimize/pre-plan a canonical set of sizes: all powers of two and ten
Chris@82: up to 2^20 (1048576), including both real and complex, forward and
Chris@82: backwards, in-place and out-of-place transforms.  Also includes two-
Chris@82: and three-dimensional transforms of equal-size dimensions
Chris@82: (e.g. 16x16x16).
Chris@82: .TP
Chris@82: \fB\-t\fR \fIhours\fR, \fB\-\-time\-limit\fR=\fIhours\fR
Chris@82: Stop after a time of
Chris@82: .I hours
Chris@82: (hours) has elapsed, outputting accumulated wisdom.  (The problems are planned
Chris@82: in increasing order of size.)  Defaults to 0, indicating no time limit.
Chris@82: .TP
Chris@82: \fB\-o\fR \fIfile\fR, \fB\-\-output-file\fR=\fIfile\fR
Chris@82: Send wisdom output to
Chris@82: .I file
Chris@82: rather than to standard output (the default).
Chris@82: .TP
Chris@82: \fB\-m\fR, \fB\-\-measure\fR; \fB\-e\fR, \fB\-\-estimate\fR; \fB\-x\fR, \fB\-\-exhaustive\fR
Chris@82: Normally, 
Chris@82: .I fftwf\-wisdom
Chris@82: creates plans in FFTW_PATIENT mode, but with these options you can instead
Chris@82: use FFTW_MEASURE, FFTW_ESTIMATE, or FFTW_EXHAUSTIVE modes, respectively,
Chris@82: as described in more detail by the FFTW manual.
Chris@82: 
Chris@82: Note that wisdom is tagged with the planning patience level, and a
Chris@82: single file can mix different levels of wisdom (e.g. you can mostly
Chris@82: use the patient default, but plan a few sizes that you especially care
Chris@82: about in
Chris@82: .B \-\-exhaustive
Chris@82: mode).
Chris@82: .TP
Chris@82: \fB\-n\fR, \fB\-\-no\-system\-wisdom\fR
Chris@82: Do not import the system wisdom from
Chris@82: .I /etc/fftw/wisdomf
Chris@82: (which is normally read by default).
Chris@82: .TP
Chris@82: \fB\-w\fR \fIfile\fR, \fB\-\-wisdom\-file\fR=\fIfile\fR
Chris@82: Import wisdom from
Chris@82: .I file
Chris@82: (in addition to the system wisdom, unless 
Chris@82: .B \-n
Chris@82: is specified).  Multiple wisdom files can be read via multiple
Chris@82: .B \-w
Chris@82: options.  If
Chris@82: .I file
Chris@82: is "\-", then read wisdom from standard input.
Chris@82: .TP
Chris@82: \fB\-T\fR \fIN\fR, \fB\--threads\fR=\fIN\fR
Chris@82: Plan with
Chris@82: .I N
Chris@82: threads.  This option is only present if FFTW was configured with
Chris@82: thread support.
Chris@82: .SH BUGS
Chris@82: Send bug reports to fftw@fftw.org.
Chris@82: .SH AUTHORS
Chris@82: Written by Steven G. Johnson and Matteo Frigo.
Chris@82: 
Chris@82: Copyright (c) 2003, 2007-14 Matteo Frigo
Chris@82: .br
Chris@82: Copyright (c) 2003, 2007-14 Massachusetts Institute of Technology
Chris@82: .SH "SEE ALSO"
Chris@82: fftw-wisdom-to-conf(1)