fftw_flags demo takes too long to compute
[scilab.git] / scilab / modules / fftw / help / en_US / fftw_flags.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2007 - INRIA
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
11  *
12  -->
13 <refentry xmlns="http://docbook.org/ns/docbook" 
14           xmlns:xlink="http://www.w3.org/1999/xlink" 
15           xmlns:svg="http://www.w3.org/2000/svg" 
16           xmlns:ns4="http://www.w3.org/1999/xhtml" 
17           xmlns:mml="http://www.w3.org/1998/Math/MathML" 
18           xmlns:db="http://docbook.org/ns/docbook" 
19           xmlns:scilab="http://www.scilab.org" xml:id="fftw_flags" xml:lang="en">
20     <refnamediv>
21         <refname>fftw_flags</refname>
22         <refpurpose>set method for fft planner algorithm selection
23         </refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Calling Sequence</title>
27         <synopsis>[a,[S]]=fftw_flags(flag)</synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>flag</term>
34                 <listitem>
35                     <para>
36                         a string or an integer. Specifies the planner
37                         algorithm. See below.
38                     </para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>a</term>
43                 <listitem>
44                     <para>an integer. The planner code. See below.
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>S</term>
50                 <listitem>
51                     <para>a character string. The planner name.</para>
52                 </listitem>
53             </varlistentry>
54         </variablelist>
55     </refsection>
56     <refsection>
57         <title>Description</title>
58         <para>
59             This function enables the selection of the algorithm used to
60             determine the fftw planner algorithm. The planner is used to
61             determine an efficient way to compute the fft.
62         </para>
63         <para>
64             <warning>
65                 Warning: the default value "FFTW_ESTIMATE" gives generally 
66                 quite efficient plans. Try to change it only if the fft efficiency is
67                 really important and you have a lot of similar calls to do.
68             </warning>
69         </para>
70         
71         <para>Accepted entries are :</para>
72         <itemizedlist>
73             <listitem>
74                 <para>{FFTW_ESTIMATE} or 64. Specifies that, instead of actual
75                     measurements of different algorithms, a simple heuristic is
76                     used to pick a (probably sub-optimal) plan quickly. With this
77                     flag, the input/output arrays are not overwritten during
78                     planning. It is the default value
79                 </para>
80             </listitem>
81             <listitem>
82                 <para>FFTW_MEASURE or 0. tells FFTW to find an optimized
83                     plan by actually computing several FFTs and measuring their
84                     execution time. Depending on your machine, this can take some
85                     time (often a few seconds). 
86                 </para>
87             </listitem>
88             <listitem>
89                 <para>FFTW_PATIENT or 32. It is like "FFTW_MEASURE", but
90                     considers a wider range of algorithms and often produces a
91                     “more optimal” plan (especially for large transforms), but at
92                     the expense of several times longer planning time (especially
93                     for large transforms). 
94                 </para>
95             </listitem>
96             
97             <listitem>
98                 <para>FFTW_EXHAUSTIVE or 8. It is like "FFTW_PATIENT", but
99                     considers an even wider range of algorithms, including many
100                     that we think are unlikely to be fast, to produce the most
101                     optimal plan but with a substantially increased planning
102                     time. 
103                 </para>
104             </listitem>
105         </itemizedlist>
106         
107         
108         <para>Remark : when using FFTW_MEASURE/FFTW_PATIENT/FFTW_EXHAUSTIVE you must
109             call fftw twice. (first call for initialization, second and others
110             calls for computation)
111         </para>
112     </refsection>
113     <refsection>
114         <title>Examples</title>
115         <programlisting role="example"><![CDATA[ 
116 A=rand(1, 2^9 + 2^15);
117 fftw_forget_wisdom();
118 fftw_flags("FFTW_ESTIMATE");
119 timer(); y=fft(A); timer()//first call determines the plan
120 timer(); y=fft(A); timer() //subsequent similar calls
121 fftw_flags("FFTW_MEASURE");
122 fftw_forget_wisdom();
123 timer(); y=fft(A); timer()//first call determines the plan, this takes about 5min
124 timer(); y=fft(A); timer() //subsequent similar calls
125
126  ]]></programlisting>
127     </refsection>
128     <refsection role="see also">
129         <title>See Also</title>
130         <simplelist type="inline">
131             <member>
132                 <link linkend="fft">fft</link>
133             </member>
134             <member>
135                 <link linkend="set_fftw_wisdom">set_fftw_wisdom</link>
136             </member>
137             <member>
138                 <link linkend="get_fftw_wisdom">get_fftw_wisdom</link>
139             </member>
140             <member>
141                 <link linkend="fftw_forget_wisdom">fftw_forget_wisdom</link>
142             </member>
143         </simplelist>
144     </refsection>
145 </refentry>