Mercurial > hg > sv-dependency-builds

annotate src/fftw-3.3.8/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 d0c2a83c1364
children
rev   line source
Chris@82 1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
Chris@82 2 <html>
Chris@82 3 <!-- This manual is for FFTW
Chris@82 4 (version 3.3.8, 24 May 2018).
Chris@82 5
Chris@82 6 Copyright (C) 2003 Matteo Frigo.
Chris@82 7
Chris@82 8 Copyright (C) 2003 Massachusetts Institute of Technology.
Chris@82 9
Chris@82 10 Permission is granted to make and distribute verbatim copies of this
Chris@82 11 manual provided the copyright notice and this permission notice are
Chris@82 12 preserved on all copies.
Chris@82 13
Chris@82 14 Permission is granted to copy and distribute modified versions of this
Chris@82 15 manual under the conditions for verbatim copying, provided that the
Chris@82 16 entire resulting derived work is distributed under the terms of a
Chris@82 17 permission notice identical to this one.
Chris@82 18
Chris@82 19 Permission is granted to copy and distribute translations of this manual
Chris@82 20 into another language, under the above conditions for modified versions,
Chris@82 21 except that this permission notice may be stated in a translation
Chris@82 22 approved by the Free Software Foundation. -->
Chris@82 23 <!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
Chris@82 24 <head>
Chris@82 25 <title>FFTW 3.3.8: Using Plans</title>
Chris@82 26
Chris@82 27 <meta name="description" content="FFTW 3.3.8: Using Plans">
Chris@82 28 <meta name="keywords" content="FFTW 3.3.8: Using Plans">
Chris@82 29 <meta name="resource-type" content="document">
Chris@82 30 <meta name="distribution" content="global">
Chris@82 31 <meta name="Generator" content="makeinfo">
Chris@82 32 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
Chris@82 33 <link href="index.html#Top" rel="start" title="Top">
Chris@82 34 <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
Chris@82 35 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
Chris@82 36 <link href="FFTW-Reference.html#FFTW-Reference" rel="up" title="FFTW Reference">
Chris@82 37 <link href="Basic-Interface.html#Basic-Interface" rel="next" title="Basic Interface">
Chris@82 38 <link href="Memory-Allocation.html#Memory-Allocation" rel="prev" title="Memory Allocation">
Chris@82 39 <style type="text/css">
Chris@82 40 <!--
Chris@82 41 a.summary-letter {text-decoration: none}
Chris@82 42 blockquote.indentedblock {margin-right: 0em}
Chris@82 43 blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
Chris@82 44 blockquote.smallquotation {font-size: smaller}
Chris@82 45 div.display {margin-left: 3.2em}
Chris@82 46 div.example {margin-left: 3.2em}
Chris@82 47 div.lisp {margin-left: 3.2em}
Chris@82 48 div.smalldisplay {margin-left: 3.2em}
Chris@82 49 div.smallexample {margin-left: 3.2em}
Chris@82 50 div.smalllisp {margin-left: 3.2em}
Chris@82 51 kbd {font-style: oblique}
Chris@82 52 pre.display {font-family: inherit}
Chris@82 53 pre.format {font-family: inherit}
Chris@82 54 pre.menu-comment {font-family: serif}
Chris@82 55 pre.menu-preformatted {font-family: serif}
Chris@82 56 pre.smalldisplay {font-family: inherit; font-size: smaller}
Chris@82 57 pre.smallexample {font-size: smaller}
Chris@82 58 pre.smallformat {font-family: inherit; font-size: smaller}
Chris@82 59 pre.smalllisp {font-size: smaller}
Chris@82 60 span.nolinebreak {white-space: nowrap}
Chris@82 61 span.roman {font-family: initial; font-weight: normal}
Chris@82 62 span.sansserif {font-family: sans-serif; font-weight: normal}
Chris@82 63 ul.no-bullet {list-style: none}
Chris@82 64 -->
Chris@82 65 </style>
Chris@82 66
Chris@82 67
Chris@82 68 </head>
Chris@82 69
Chris@82 70 <body lang="en">
Chris@82 71 <a name="Using-Plans"></a>
Chris@82 72 <div class="header">
Chris@82 73 <p>
Chris@82 74 Next: <a href="Basic-Interface.html#Basic-Interface" accesskey="n" rel="next">Basic Interface</a>, Previous: <a href="Data-Types-and-Files.html#Data-Types-and-Files" accesskey="p" rel="prev">Data Types and Files</a>, Up: <a href="FFTW-Reference.html#FFTW-Reference" accesskey="u" rel="up">FFTW Reference</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
Chris@82 75 </div>
Chris@82 76 <hr>
Chris@82 77 <a name="Using-Plans-1"></a>
Chris@82 78 <h3 class="section">4.2 Using Plans</h3>
Chris@82 79
Chris@82 80 <p>Plans for all transform types in FFTW are stored as type
Chris@82 81 <code>fftw_plan</code> (an opaque pointer type), and are created by one of the
Chris@82 82 various planning routines described in the following sections.
Chris@82 83 <a name="index-fftw_005fplan-1"></a>
Chris@82 84 An <code>fftw_plan</code> contains all information necessary to compute the
Chris@82 85 transform, including the pointers to the input and output arrays.
Chris@82 86 </p>
Chris@82 87 <div class="example">
Chris@82 88 <pre class="example">void fftw_execute(const fftw_plan plan);
Chris@82 89 </pre></div>
Chris@82 90 <a name="index-fftw_005fexecute-1"></a>
Chris@82 91
Chris@82 92 <p>This executes the <code>plan</code>, to compute the corresponding transform on
Chris@82 93 the arrays for which it was planned (which must still exist). The plan
Chris@82 94 is not modified, and <code>fftw_execute</code> can be called as many times as
Chris@82 95 desired.
Chris@82 96 </p>
Chris@82 97 <p>To apply a given plan to a different array, you can use the new-array execute
Chris@82 98 interface. See <a href="New_002darray-Execute-Functions.html#New_002darray-Execute-Functions">New-array Execute Functions</a>.
Chris@82 99 </p>
Chris@82 100 <p><code>fftw_execute</code> (and equivalents) is the only function in FFTW
Chris@82 101 guaranteed to be thread-safe; see <a href="Thread-safety.html#Thread-safety">Thread safety</a>.
Chris@82 102 </p>
Chris@82 103 <p>This function:
Chris@82 104 </p><div class="example">
Chris@82 105 <pre class="example">void fftw_destroy_plan(fftw_plan plan);
Chris@82 106 </pre></div>
Chris@82 107 <a name="index-fftw_005fdestroy_005fplan-1"></a>
Chris@82 108 <p>deallocates the <code>plan</code> and all its associated data.
Chris@82 109 </p>
Chris@82 110 <p>FFTW&rsquo;s planner saves some other persistent data, such as the
Chris@82 111 accumulated wisdom and a list of algorithms available in the current
Chris@82 112 configuration. If you want to deallocate all of that and reset FFTW
Chris@82 113 to the pristine state it was in when you started your program, you can
Chris@82 114 call:
Chris@82 115 </p>
Chris@82 116 <div class="example">
Chris@82 117 <pre class="example">void fftw_cleanup(void);
Chris@82 118 </pre></div>
Chris@82 119 <a name="index-fftw_005fcleanup"></a>
Chris@82 120
Chris@82 121 <p>After calling <code>fftw_cleanup</code>, all existing plans become undefined,
Chris@82 122 and you should not attempt to execute them nor to destroy them. You can
Chris@82 123 however create and execute/destroy new plans, in which case FFTW starts
Chris@82 124 accumulating wisdom information again.
Chris@82 125 </p>
Chris@82 126 <p><code>fftw_cleanup</code> does not deallocate your plans, however. To prevent
Chris@82 127 memory leaks, you must still call <code>fftw_destroy_plan</code> before
Chris@82 128 executing <code>fftw_cleanup</code>.
Chris@82 129 </p>
Chris@82 130 <p>Occasionally, it may useful to know FFTW&rsquo;s internal &ldquo;cost&rdquo; metric
Chris@82 131 that it uses to compare plans to one another; this cost is
Chris@82 132 proportional to an execution time of the plan, in undocumented units,
Chris@82 133 if the plan was created with the <code>FFTW_MEASURE</code> or other
Chris@82 134 timing-based options, or alternatively is a heuristic cost function
Chris@82 135 for <code>FFTW_ESTIMATE</code> plans. (The cost values of measured and
Chris@82 136 estimated plans are not comparable, being in different units. Also,
Chris@82 137 costs from different FFTW versions or the same version compiled
Chris@82 138 differently may not be in the same units. Plans created from wisdom
Chris@82 139 have a cost of 0 since no timing measurement is performed for them.
Chris@82 140 Finally, certain problems for which only one top-level algorithm was
Chris@82 141 possible may have required no measurements of the cost of the whole
Chris@82 142 plan, in which case <code>fftw_cost</code> will also return 0.) The cost
Chris@82 143 metric for a given plan is returned by:
Chris@82 144 </p>
Chris@82 145 <div class="example">
Chris@82 146 <pre class="example">double fftw_cost(const fftw_plan plan);
Chris@82 147 </pre></div>
Chris@82 148 <a name="index-fftw_005fcost"></a>
Chris@82 149
Chris@82 150 <p>The following two routines are provided purely for academic purposes
Chris@82 151 (that is, for entertainment).
Chris@82 152 </p>
Chris@82 153 <div class="example">
Chris@82 154 <pre class="example">void fftw_flops(const fftw_plan plan,
Chris@82 155 double *add, double *mul, double *fma);
Chris@82 156 </pre></div>
Chris@82 157 <a name="index-fftw_005fflops"></a>
Chris@82 158
Chris@82 159 <p>Given a <code>plan</code>, set <code>add</code>, <code>mul</code>, and <code>fma</code> to an
Chris@82 160 exact count of the number of floating-point additions, multiplications,
Chris@82 161 and fused multiply-add operations involved in the plan&rsquo;s execution. The
Chris@82 162 total number of floating-point operations (flops) is <code>add + mul +
Chris@82 163 2*fma</code>, or <code>add + mul + fma</code> if the hardware supports fused
Chris@82 164 multiply-add instructions (although the number of FMA operations is only
Chris@82 165 approximate because of compiler voodoo). (The number of operations
Chris@82 166 should be an integer, but we use <code>double</code> to avoid overflowing
Chris@82 167 <code>int</code> for large transforms; the arguments are of type <code>double</code>
Chris@82 168 even for single and long-double precision versions of FFTW.)
Chris@82 169 </p>
Chris@82 170 <div class="example">
Chris@82 171 <pre class="example">void fftw_fprint_plan(const fftw_plan plan, FILE *output_file);
Chris@82 172 void fftw_print_plan(const fftw_plan plan);
Chris@82 173 char *fftw_sprint_plan(const fftw_plan plan);
Chris@82 174 </pre></div>
Chris@82 175 <a name="index-fftw_005ffprint_005fplan"></a>
Chris@82 176 <a name="index-fftw_005fprint_005fplan"></a>
Chris@82 177
Chris@82 178 <p>This outputs a &ldquo;nerd-readable&rdquo; representation of the <code>plan</code> to
Chris@82 179 the given file, to <code>stdout</code>, or two a newly allocated
Chris@82 180 NUL-terminated string (which the caller is responsible for deallocating
Chris@82 181 with <code>free</code>), respectively.
Chris@82 182 </p>
Chris@82 183 <hr>
Chris@82 184 <div class="header">
Chris@82 185 <p>
Chris@82 186 Next: <a href="Basic-Interface.html#Basic-Interface" accesskey="n" rel="next">Basic Interface</a>, Previous: <a href="Data-Types-and-Files.html#Data-Types-and-Files" accesskey="p" rel="prev">Data Types and Files</a>, Up: <a href="FFTW-Reference.html#FFTW-Reference" accesskey="u" rel="up">FFTW Reference</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
Chris@82 187 </div>
Chris@82 188
Chris@82 189
Chris@82 190
Chris@82 191 </body>
Chris@82 192 </html>