Ubuntu Manpage: fftwl-wisdom - create wisdom (pre-optimized FFTs)

Provided by: libfftw3-bin_3.3.3-7ubuntu3_amd64

NAME

       fftwl-wisdom - create wisdom (pre-optimized FFTs)

SYNOPSIS

       fftwl-wisdom [OPTION]... [SIZE]...

DESCRIPTION

fftwl-wisdom is a utility to generate FFTW wisdom files, which contain saved information
about how to optimally compute (Fourier) transforms of various sizes. FFTW is a free
library to compute discrete Fourier transforms in one or more dimensions, for arbitrary
sizes, and of both real and complex data, among other related operations. More
information on FFTW can be found at the FFTW home page: http://www.fftw.org

Programs using FFTW can be written to load wisdom from an arbitrary file, string, or other
source. Moreover, it is likely that many FFTW-using programs will load the system wisdom
file, which is stored in /etc/fftw/wisdoml by default. fftwl-wisdom can be used to create
or add to such wisdom files. In its most typical usage, the wisdom file can be created to
pre-plan a canonical set of sizes (see below) via:

fftwl-wisdom -v -c -o wisdoml

(this will take many hours, which can be limited by the -t option) and the output wisdoml
file can then be copied (as root) to /etc/fftw/ or whatever.

The fftwl-wisdom program normally writes the wisdom directly to standard output, but this
can be changed via the -o option, as in the example above.

If the system wisdom file /etc/fftw/wisdoml already exists, then fftwl-wisdom reads this
existing wisdom (unless the -n option is specified) and outputs both the old wisdom and
any newly created wisdom. In this way, it can be used to add new transform sizes to the
existing system wisdom (or other wisdom file, with the -w option).

SPECIFYING SIZES

       Although a canonical set of sizes to optimize is specified by the -c option, the user  can
       also  specify  zero  or  more non-canonical transform sizes and types to optimize, via the
       SIZE arguments following the option flags.  Alternatively, the sizes to  optimize  can  be
       read from standard input (whitespace-separated), if a SIZE argument of "-" is supplied.

       Sizes are specified by the 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 is 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).  In the case  of
       ´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.

       For  example, ´cif12x13x14´ is a three-dimensional 12 by 13 x 14 complex DFT operating in-
       place.   ´rob65536´  is  a   one-dimensional   size-65536   out-of-place   complex-to-real
       (backwards)  transform  operating  on  Hermitian-symmetry  input.  ´ki10hx20e01´ is 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, fftwl-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/wisdoml (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.

BUGS

       Send bug reports to fftw@fftw.org.

AUTHORS

       Written by Steven G. Johnson and Matteo Frigo.

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