Mercurial > hg > sv-dependency-builds

annotate src/fftw-3.3.3/doc/html/Using-Plans.html @ 83:ae30d91d2ffe

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Replace these with versions built using an older toolset (so as to avoid ABI compatibilities when linking on Ubuntu 14.04 for packaging purposes)
author Chris Cannam
date Fri, 07 Feb 2020 11:51:13 +0000
parents 37bf6b4a2645
children
rev   line source
Chris@10 1 <html lang="en">
Chris@10 2 <head>
Chris@10 3 <title>Using Plans - FFTW 3.3.3</title>
Chris@10 4 <meta http-equiv="Content-Type" content="text/html">
Chris@10 5 <meta name="description" content="FFTW 3.3.3">
Chris@10 6 <meta name="generator" content="makeinfo 4.13">
Chris@10 7 <link title="Top" rel="start" href="index.html#Top">
Chris@10 8 <link rel="up" href="FFTW-Reference.html#FFTW-Reference" title="FFTW Reference">
Chris@10 9 <link rel="prev" href="Data-Types-and-Files.html#Data-Types-and-Files" title="Data Types and Files">
Chris@10 10 <link rel="next" href="Basic-Interface.html#Basic-Interface" title="Basic Interface">
Chris@10 11 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
Chris@10 12 <!--
Chris@10 13 This manual is for FFTW
Chris@10 14 (version 3.3.3, 25 November 2012).
Chris@10 15
Chris@10 16 Copyright (C) 2003 Matteo Frigo.
Chris@10 17
Chris@10 18 Copyright (C) 2003 Massachusetts Institute of Technology.
Chris@10 19
Chris@10 20 Permission is granted to make and distribute verbatim copies of
Chris@10 21 this manual provided the copyright notice and this permission
Chris@10 22 notice are preserved on all copies.
Chris@10 23
Chris@10 24 Permission is granted to copy and distribute modified versions of
Chris@10 25 this manual under the conditions for verbatim copying, provided
Chris@10 26 that the entire resulting derived work is distributed under the
Chris@10 27 terms of a permission notice identical to this one.
Chris@10 28
Chris@10 29 Permission is granted to copy and distribute translations of this
Chris@10 30 manual into another language, under the above conditions for
Chris@10 31 modified versions, except that this permission notice may be
Chris@10 32 stated in a translation approved by the Free Software Foundation.
Chris@10 33 -->
Chris@10 34 <meta http-equiv="Content-Style-Type" content="text/css">
Chris@10 35 <style type="text/css"><!--
Chris@10 36 pre.display { font-family:inherit }
Chris@10 37 pre.format { font-family:inherit }
Chris@10 38 pre.smalldisplay { font-family:inherit; font-size:smaller }
Chris@10 39 pre.smallformat { font-family:inherit; font-size:smaller }
Chris@10 40 pre.smallexample { font-size:smaller }
Chris@10 41 pre.smalllisp { font-size:smaller }
Chris@10 42 span.sc { font-variant:small-caps }
Chris@10 43 span.roman { font-family:serif; font-weight:normal; }
Chris@10 44 span.sansserif { font-family:sans-serif; font-weight:normal; }
Chris@10 45 --></style>
Chris@10 46 </head>
Chris@10 47 <body>
Chris@10 48 <div class="node">
Chris@10 49 <a name="Using-Plans"></a>
Chris@10 50 <p>
Chris@10 51 Next:&nbsp;<a rel="next" accesskey="n" href="Basic-Interface.html#Basic-Interface">Basic Interface</a>,
Chris@10 52 Previous:&nbsp;<a rel="previous" accesskey="p" href="Data-Types-and-Files.html#Data-Types-and-Files">Data Types and Files</a>,
Chris@10 53 Up:&nbsp;<a rel="up" accesskey="u" href="FFTW-Reference.html#FFTW-Reference">FFTW Reference</a>
Chris@10 54 <hr>
Chris@10 55 </div>
Chris@10 56
Chris@10 57 <h3 class="section">4.2 Using Plans</h3>
Chris@10 58
Chris@10 59 <p>Plans for all transform types in FFTW are stored as type
Chris@10 60 <code>fftw_plan</code> (an opaque pointer type), and are created by one of the
Chris@10 61 various planning routines described in the following sections.
Chris@10 62 <a name="index-fftw_005fplan-152"></a>An <code>fftw_plan</code> contains all information necessary to compute the
Chris@10 63 transform, including the pointers to the input and output arrays.
Chris@10 64
Chris@10 65 <pre class="example"> void fftw_execute(const fftw_plan plan);
Chris@10 66 </pre>
Chris@10 67 <p><a name="index-fftw_005fexecute-153"></a>
Chris@10 68 This executes the <code>plan</code>, to compute the corresponding transform on
Chris@10 69 the arrays for which it was planned (which must still exist). The plan
Chris@10 70 is not modified, and <code>fftw_execute</code> can be called as many times as
Chris@10 71 desired.
Chris@10 72
Chris@10 73 <p>To apply a given plan to a different array, you can use the new-array execute
Chris@10 74 interface. See <a href="New_002darray-Execute-Functions.html#New_002darray-Execute-Functions">New-array Execute Functions</a>.
Chris@10 75
Chris@10 76 <p><code>fftw_execute</code> (and equivalents) is the only function in FFTW
Chris@10 77 guaranteed to be thread-safe; see <a href="Thread-safety.html#Thread-safety">Thread safety</a>.
Chris@10 78
Chris@10 79 <p>This function:
Chris@10 80 <pre class="example"> void fftw_destroy_plan(fftw_plan plan);
Chris@10 81 </pre>
Chris@10 82 <p><a name="index-fftw_005fdestroy_005fplan-154"></a>deallocates the <code>plan</code> and all its associated data.
Chris@10 83
Chris@10 84 <p>FFTW's planner saves some other persistent data, such as the
Chris@10 85 accumulated wisdom and a list of algorithms available in the current
Chris@10 86 configuration. If you want to deallocate all of that and reset FFTW
Chris@10 87 to the pristine state it was in when you started your program, you can
Chris@10 88 call:
Chris@10 89
Chris@10 90 <pre class="example"> void fftw_cleanup(void);
Chris@10 91 </pre>
Chris@10 92 <p><a name="index-fftw_005fcleanup-155"></a>
Chris@10 93 After calling <code>fftw_cleanup</code>, all existing plans become undefined,
Chris@10 94 and you should not attempt to execute them nor to destroy them. You can
Chris@10 95 however create and execute/destroy new plans, in which case FFTW starts
Chris@10 96 accumulating wisdom information again.
Chris@10 97
Chris@10 98 <p><code>fftw_cleanup</code> does not deallocate your plans, however. To prevent
Chris@10 99 memory leaks, you must still call <code>fftw_destroy_plan</code> before
Chris@10 100 executing <code>fftw_cleanup</code>.
Chris@10 101
Chris@10 102 <p>Occasionally, it may useful to know FFTW's internal &ldquo;cost&rdquo; metric
Chris@10 103 that it uses to compare plans to one another; this cost is
Chris@10 104 proportional to an execution time of the plan, in undocumented units,
Chris@10 105 if the plan was created with the <code>FFTW_MEASURE</code> or other
Chris@10 106 timing-based options, or alternatively is a heuristic cost function
Chris@10 107 for <code>FFTW_ESTIMATE</code> plans. (The cost values of measured and
Chris@10 108 estimated plans are not comparable, being in different units. Also,
Chris@10 109 costs from different FFTW versions or the same version compiled
Chris@10 110 differently may not be in the same units. Plans created from wisdom
Chris@10 111 have a cost of 0 since no timing measurement is performed for them.
Chris@10 112 Finally, certain problems for which only one top-level algorithm was
Chris@10 113 possible may have required no measurements of the cost of the whole
Chris@10 114 plan, in which case <code>fftw_cost</code> will also return 0.) The cost
Chris@10 115 metric for a given plan is returned by:
Chris@10 116
Chris@10 117 <pre class="example"> double fftw_cost(const fftw_plan plan);
Chris@10 118 </pre>
Chris@10 119 <p><a name="index-fftw_005fcost-156"></a>
Chris@10 120 The following two routines are provided purely for academic purposes
Chris@10 121 (that is, for entertainment).
Chris@10 122
Chris@10 123 <pre class="example"> void fftw_flops(const fftw_plan plan,
Chris@10 124 double *add, double *mul, double *fma);
Chris@10 125 </pre>
Chris@10 126 <p><a name="index-fftw_005fflops-157"></a>
Chris@10 127 Given a <code>plan</code>, set <code>add</code>, <code>mul</code>, and <code>fma</code> to an
Chris@10 128 exact count of the number of floating-point additions, multiplications,
Chris@10 129 and fused multiply-add operations involved in the plan's execution. The
Chris@10 130 total number of floating-point operations (flops) is <code>add + mul +
Chris@10 131 2*fma</code>, or <code>add + mul + fma</code> if the hardware supports fused
Chris@10 132 multiply-add instructions (although the number of FMA operations is only
Chris@10 133 approximate because of compiler voodoo). (The number of operations
Chris@10 134 should be an integer, but we use <code>double</code> to avoid overflowing
Chris@10 135 <code>int</code> for large transforms; the arguments are of type <code>double</code>
Chris@10 136 even for single and long-double precision versions of FFTW.)
Chris@10 137
Chris@10 138 <pre class="example"> void fftw_fprint_plan(const fftw_plan plan, FILE *output_file);
Chris@10 139 void fftw_print_plan(const fftw_plan plan);
Chris@10 140 </pre>
Chris@10 141 <p><a name="index-fftw_005ffprint_005fplan-158"></a><a name="index-fftw_005fprint_005fplan-159"></a>
Chris@10 142 This outputs a &ldquo;nerd-readable&rdquo; representation of the <code>plan</code> to
Chris@10 143 the given file or to <code>stdout</code>, respectively.
Chris@10 144
Chris@10 145 <!-- -->
Chris@10 146 </body></html>
Chris@10 147