← Back to branch summary

~ubuntu-branches/ubuntu/raring/scilab/raring-proposed

« back to all changes in this revision

Viewing changes to modules/signal_processing/help/en_US/fft.xml

  • Committer: Package Import Robot
  • Author(s): Sylvestre Ledru
  • Date: 2012-08-30 14:42:38 UTC
  • mfrom: (1.4.7)
  • Revision ID: package-import@ubuntu.com-20120830144238-c1y2og7dbm7m9nig
Tags: 5.4.0-beta-3-1~exp1
* New upstream release
* Update the scirenderer dep
* Get ride of libjhdf5-java dependency

Show diffs side-by-side

added added

removed removed

Lines of Context:
modules/signal_processing/help/en_US/fft.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) 1997   - INRIA
5
 
 * Copyright (C) 2012 - Serge Steer - INRIA
6
 
 * 
7
 
 * This file must be used under the terms of the CeCILL.
8
 
 * This source file is licensed as described in the file COPYING, which
9
 
 * you should have received as part of this distribution.  The terms
10
 
 * are also available at    
11
 
 * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12
 
 *
13
 
 -->
14
 
<refentry xmlns="http://docbook.org/ns/docbook" 
15
 
          xmlns:xlink="http://www.w3.org/1999/xlink" 
16
 
          xmlns:svg="http://www.w3.org/2000/svg" 
17
 
          xmlns:mml="http://www.w3.org/1998/Math/MathML" 
18
 
          xmlns:db="http://docbook.org/ns/docbook" 
19
 
          version="5.0-subset Scilab" xml:lang="en" xml:id="fft">
20
 
  <refnamediv>
21
 
    <refname>fft</refname>
22
 
    <refpurpose>fast Fourier transform.</refpurpose>
23
 
  </refnamediv>
24
 
  <refnamediv xml:id="ifft">
25
 
    <refname>ifft</refname>
26
 
    <refpurpose>fast Fourier transform.</refpurpose>
27
 
  </refnamediv>
28
 
  <refsynopsisdiv>
29
 
    <title>Calling Sequence</title>
30
 
    <synopsis>X=fft(A [,sign] [,option])
31
 
      X=fft(A,sign,selection  [,option])
32
 
      X=fft(A,sign,dims,incr [,option] )
33
 
    </synopsis>
34
 
  </refsynopsisdiv>
35
 
  <refsection>
36
 
    <title>Arguments</title>
37
 
    <variablelist>
38
 
      <varlistentry>
39
 
        <term>A</term>
40
 
        <listitem>
41
 
          <para>a real or complex vector or real or complex array
42
 
            (vector, matrix or N-D array.
43
 
          </para>
44
 
        </listitem>
45
 
      </varlistentry>
46
 
      <varlistentry>
47
 
        <term>X</term>
48
 
        <listitem>
49
 
          a real or complex array with same shape as <literal>A</literal>.
50
 
        </listitem>
51
 
      </varlistentry>
52
 
      <varlistentry>
53
 
        <term>sign</term>
54
 
        <listitem>
55
 
          an integer. with possible values <literal>1</literal> or
56
 
          <literal>-1</literal>. Select direct or inverse
57
 
          transform. The default value is <literal>-1</literal>
58
 
          (direct transform).
59
 
        </listitem>
60
 
      </varlistentry>
61
 
      <varlistentry>
62
 
        <term>option</term>
63
 
        <listitem>
64
 
          a character string. with possible values
65
 
          <literal>"symmetric"</literal> or
66
 
          <literal>"nonsymmetric"</literal>. Indicates if
67
 
          <literal>A</literal> is symmetric or not. If this argument
68
 
          is omitted the algorithm automatically determines if
69
 
          <literal>A</literal> is symmetric or not. See the
70
 
          Description part for details.
71
 
        </listitem>
72
 
      </varlistentry>
73
 
      <varlistentry>
74
 
        <term>selection</term>
75
 
        <listitem>
76
 
          a vector containing index on <literal>A</literal> array
77
 
          dimensions.  See the Description part for details.
78
 
        </listitem>
79
 
      </varlistentry>
80
 
      
81
 
      <varlistentry>
82
 
        <term>dims</term>
83
 
        <listitem>
84
 
          a vector of positive numbers with integer values, or a
85
 
          vector of positive integers.  See the Description part for details.
86
 
          <para>
87
 
            Each element must be a divisor
88
 
            of the total number of elements of <literal>A</literal>. 
89
 
          </para>
90
 
          <para>
91
 
            The product of the elements must be less than the total
92
 
            number of elements of <literal>A</literal>.
93
 
          </para>
94
 
        </listitem>
95
 
      </varlistentry>
96
 
      <varlistentry>
97
 
        <term>incr</term>
98
 
        <listitem>
99
 
          a vector of positive numbers with integer values, or a
100
 
          vector of positive integers.  See the Description part for
101
 
          details.
102
 
          <para>
103
 
            <literal>incr</literal> must have the same number of
104
 
            elements than <literal>dims</literal>.
105
 
          </para>
106
 
          <para>
107
 
            Each element must be a divisor of the total number of
108
 
            elements of <literal>A</literal>.
109
 
          </para>
110
 
          <para>
111
 
            The <literal>incr</literal> elements must be in strictly
112
 
            increasing order.
113
 
          </para>
114
 
        </listitem>
115
 
      </varlistentry>
116
 
    </variablelist>
117
 
  </refsection>
118
 
  <refsection>
119
 
    <title>Description</title> This function realizes direct or
120
 
    inverse 1-D or N-D Discrete Fourier Transforms.
121
 
    <variablelist>
122
 
      <varlistentry>
123
 
        <term>Short syntax </term>
124
 
        <listitem>
125
 
          <variablelist>
126
 
            <varlistentry>
127
 
              <term>direct</term>
128
 
              <listitem>
129
 
                <literal>X=fft(A,-1 [,option])</literal> or
130
 
                <literal>X=fft(A [,option])</literal> gives a direct
131
 
                transform.
132
 
                <variablelist>
133
 
                  <varlistentry>
134
 
                    <term>single variate</term>
135
 
                    <listitem>
136
 
                      <para>
137
 
                        If <literal>A</literal> is a vector a
138
 
                        single variate direct FFT is computed that
139
 
                        is:
140
 
                      </para>
141
 
                      <para>
142
 
                        <latex>
143
 
                          $x(k) = \sum_{m=1}^n {a(m)*e^{-\frac{2i*\pi}{n}
144
 
                          (m-1) (k-1)}$
145
 
                        </latex>
146
 
                      </para>
147
 
                      <para>
148
 
                        (the <literal>-1</literal> argument refers
149
 
                        to the sign of the exponent..., NOT to
150
 
                        "inverse"),
151
 
                      </para>
152
 
                    </listitem>
153
 
                  </varlistentry>
154
 
                  
155
 
                  <varlistentry>
156
 
                    <term>multivariate</term>
157
 
                    <listitem>
158
 
                      <para>
159
 
                        If <literal>A</literal> is a matrix or
160
 
                        a multidimensional array a multivariate direct
161
 
                        FFT is performed.
162
 
                      </para>
163
 
                    </listitem>
164
 
                  </varlistentry>
165
 
                </variablelist>
166
 
                
167
 
              </listitem>
168
 
            </varlistentry>
169
 
            <varlistentry>
170
 
              <term>inverse</term>
171
 
              <listitem>
172
 
                <para>
173
 
                  <literal>X=fft(A,1)</literal> or
174
 
                  <literal>X=ifft(A)</literal>performs the inverse
175
 
                  normalized transform, such
176
 
                  that<literal>A==ifft(fft(A))</literal>. 
177
 
                </para>
178
 
                <variablelist>
179
 
                  <varlistentry>
180
 
                    <term>single variate</term>
181
 
                    <listitem>
182
 
                      If <literal>A</literal> is a vector a single
183
 
                      variate inverse FFT is computed
184
 
                      <para>
185
 
                        <latex>
186
 
                          $x(k) = \sum_{m=1}^n
187
 
                          {a(m)*e^{+\frac{2i*\pi}{n} (m-1) (k-1)}$
188
 
                        </latex>
189
 
                      </para>
190
 
                    </listitem>
191
 
                  </varlistentry>
192
 
                  <varlistentry>
193
 
                    <term>multivariate</term>
194
 
                    <listitem>
195
 
                      <para>
196
 
                        If <literal>a</literal> is a matrix or or
197
 
                        a multidimensional array a multivariate inverse
198
 
                        FFT is performed.
199
 
                      </para>
200
 
                    </listitem>
201
 
                  </varlistentry>
202
 
                </variablelist>
203
 
              </listitem>
204
 
            </varlistentry>
205
 
          </variablelist>
206
 
        </listitem>
207
 
      </varlistentry>
208
 
      
209
 
      <varlistentry>
210
 
        <term>Long syntax for FFT along specified dimensions</term>
211
 
        <listitem>
212
 
          <itemizedlist>
213
 
            <listitem>
214
 
              <para>
215
 
                <literal>X=fft(A,sign,selection [,option])</literal>
216
 
                allows to perform efficiently all direct or inverse
217
 
                fft of the "slices" of <literal>A</literal> along
218
 
                selected dimensions.
219
 
              </para>
220
 
              <para>
221
 
                For example, if <literal>A</literal> is a 3-D array
222
 
                <literal>X=fft(A,-1,2)</literal> is equivalent to:
223
 
              </para>
224
 
              <programlisting role=""><![CDATA[ 
225
 
for i1=1:size(A,1),
226
 
  for i3=1:size(A,3),
227
 
    X(i1,:,i3)=fft(A(i1,:,i3),-1);
228
 
  end
229
 
end
230
 
              ]]></programlisting>
231
 
              <para>
232
 
                and <literal>X=fft(A,-1,[1 3])</literal> is equivalent to:
233
 
              </para>
234
 
              <programlisting role=""><![CDATA[ 
235
 
for i2=1:size(A,2),
236
 
  X(:,i2,:)=fft(A(:,i2,:),-1);
237
 
end
238
 
              ]]></programlisting>
239
 
            </listitem>
240
 
            <listitem>
241
 
              <para>
242
 
                <literal>X=fft(A,sign,dims,incr [,option])</literal> is
243
 
                a previous syntax that also allows to perform all direct or
244
 
                inverse fft of the slices of <literal>A</literal> along
245
 
                selected dimensions.
246
 
              </para>
247
 
              <para>
248
 
                For example, if <literal>A</literal> is an array with
249
 
                <literal>n1*n2*n3</literal> elements
250
 
                <literal>X=fft(A,-1,n1,1)</literal> is equivalent to
251
 
                <literal>X=fft(matrix(A,[n1,n2,n3]),-1,1)</literal>.
252
 
                and <literal>X=fft(A,-1,[n1 n3],[1 n1*n2])</literal>
253
 
                is equivalent to
254
 
                <literal>X=fft(matrix(A,[n1,n2,n3]),-1,[1,3])</literal>.
255
 
              </para>
256
 
            </listitem>
257
 
          </itemizedlist>
258
 
        </listitem>
259
 
      </varlistentry>
260
 
      <varlistentry>
261
 
        <term>Using option argument</term> This argument can be used
262
 
        to inform the fft algorithm about the symmetry of
263
 
        <literal>A</literal> or of all its "slices".  An N-D array
264
 
        <literal>B</literal> with dimensions <literal>n1</literal>,
265
 
        ..., <literal>np</literal> is conjugate symmetric for the fft
266
 
        if and only if <literal>B==conj(B([1 n1:-1:2],[1
267
 
          n2:-1:2],...,[1 np:-1:2])) 
268
 
        </literal>
269
 
        .In such a case the
270
 
        result <literal>X</literal> is real and an efficient specific
271
 
        algorithm can be used.
272
 
        <listitem>
273
 
          <itemizedlist>
274
 
            <listitem>
275
 
              <term>"symmetric"</term> that value causes fft to treat
276
 
              <literal>A</literal> or all its "slices" conjugate
277
 
              symmetric. This option is useful to avoid automatic
278
 
              determination of symmetry or if <literal>A</literal> or
279
 
              all its "slices" are not exactly symmetric because of
280
 
              round-off errors.
281
 
            </listitem>
282
 
            <listitem>
283
 
              <term>"nonsymmetric"</term> that value causes fft not to
284
 
              take care of symmetry. This option is useful to avoid
285
 
              automatic determination of symmetry.
286
 
            </listitem>
287
 
            <listitem>
288
 
              <term>unspecified</term> If the option is omitted the
289
 
              fft algorithm automatically checks for exact symmetry.
290
 
            </listitem>
291
 
            
292
 
          </itemizedlist>
293
 
        </listitem>
294
 
      </varlistentry>
295
 
      <varlistentry>
296
 
        <term>Optimizing fft</term>
297
 
        <listitem>
298
 
          <para>
299
 
            Remark: fftw function automatically stores his last
300
 
            parameters in memory to re-use it in a second time. This
301
 
            improves greatly the time computation when consecutives
302
 
            calls (with same parameters) are performed.
303
 
          </para>
304
 
          <para> 
305
 
            It is possible to go further in fft optimization using
306
 
            <link linkend="get_fftw_wisdom">get_fftw_wisdom</link>, <link
307
 
             linkend="set_fftw_wisdom">set_fftw_wisdom</link> functions.
308
 
          </para>
309
 
        </listitem>
310
 
      </varlistentry>
311
 
    </variablelist>
312
 
  </refsection>
313
 
  <refsection>
314
 
    <title>Algorithms</title>
315
 
    <para>
316
 
      This function uses the  <ulink url="http://www.fftw.org/">fftw3</ulink> library.
317
 
    </para>
318
 
  </refsection>
319
 
  <refsection>
320
 
    <title>Examples</title>
321
 
    <para>1-D fft</para>
322
 
    <programlisting role="example"><![CDATA[ 
323
 
//Frequency components of a signal
324
 
//----------------------------------
325
 
// build a noised signal sampled at 1000hz  containing to pure frequencies 
326
 
// at 50 and 70 Hz
327
 
sample_rate=1000;
328
 
t = 0:1/sample_rate:0.6;
329
 
N=size(t,'*'); //number of samples
330
 
s=sin(2*%pi*50*t)+sin(2*%pi*70*t+%pi/4)+grand(1,N,'nor',0,1);
331
 
  
332
 
y=fft(s);
333
 
 
334
 
//s is real so the fft response is conjugate symmetric and we retain only the first N/2 points
335
 
f=sample_rate*(0:(N/2))/N; //associated frequency vector
336
 
n=size(f,'*')
337
 
clf()
338
 
plot(f,abs(y(1:n)))
339
 
     ]]></programlisting>
340
 
    <para>2-D fft</para>
341
 
    <programlisting role="example"><![CDATA[ 
342
 
----------------------------------
343
 
A = zeros(256,256);
344
 
A(5:24,13:17) = 1;
345
 
X = fftshift(fft(A));
346
 
set(gcf(),"color_map",jetcolormap(128));
347
 
clf;grayplot(0:255,0:255,abs(X)')
348
 
     ]]></programlisting>
349
 
    <para>mupliple fft</para>
350
 
    <programlisting role="example"><![CDATA[ 
351
 
//simple case, 3 1-D fft at a time
352
 
N=2048;
353
 
t=linspace(0,10,2048);
354
 
A=[2*sin(2*%pi*3*t)+ sin(2*%pi*3.5*t)
355
 
  10*sin(2*%pi*8*t)
356
 
   sin(2*%pi*0.5*t)+4*sin(2*%pi*0.8*t)];
357
 
X=fft(A,-1,2);
358
 
 
359
 
fs=1/(t(2)-t(1));
360
 
f=fs*(0:(N/2))/N; //associated frequency vector
361
 
clf;plot(f(1:100)',abs(X(:,1:100))')
362
 
legend(["3 and 3.5 Hz","8 Hz","0.5 and 0.8 Hz"],"in_upper_left")
363
 
 
364
 
// 45  3-D fft at a time
365
 
Dims=[5 4 9 5 6];
366
 
A=matrix(rand(1,prod(Dims)),Dims);
367
 
 
368
 
y=fft(A,-1,[2 4 5]);
369
 
 
370
 
//equivalent (but less efficient code)
371
 
y1=zeros(A);
372
 
for i1=1:Dims(1) 
373
 
  for i3=1:Dims(3)
374
 
    ind=list(i1,:,i3,:,:);
375
 
    y1(ind(:))=fft(A(ind(:)),-1);
376
 
  end
377
 
end
378
 
   ]]></programlisting>
379
 
    
380
 
    <programlisting role="example"><![CDATA[ 
381
 
//Using explicit formula for  1-D discrete Fourier transform
382
 
//------------------------------------------------
383
 
function xf=DFT(x,flag);
384
 
  n=size(x,'*');
385
 
  //Compute the n by n Fourier matrix
386
 
  if flag==1 then,//backward transformation
387
 
    am=exp(2*%pi*%i*(0:n-1)'*(0:n-1)/n);
388
 
  else //forward transformation
389
 
    am=exp(-2*%pi*%i*(0:n-1)'*(0:n-1)/n);
390
 
  end
391
 
  xf=am*matrix(x,n,1);//dft
392
 
  xf=matrix(xf,size(x));//reshape
393
 
  if flag==1 then,xf=xf/n;end
394
 
endfunction
395
 
 
396
 
//Comparison with the fast Fourier algorithm
397
 
a=rand(1,1000);
398
 
norm(DFT(a,1) - fft(a,1))
399
 
norm(DFT(a,-1) - fft(a,-1)) 
400
 
 
401
 
timer();DFT(a,-1);timer()
402
 
timer();fft(a,-1);timer()
403
 
     ]]></programlisting>
404
 
  </refsection>
405
 
  <refsection role="see also">
406
 
    <title>See Also</title>
407
 
    <simplelist type="inline">
408
 
      <member>
409
 
        <link linkend="corr">corr</link>
410
 
      </member>
411
 
      <member>
412
 
        <link linkend="fftw_flags">fftw_flags</link>
413
 
      </member>
414
 
      <member>
415
 
        <link linkend="get_fftw_wisdom">get_fftw_wisdom</link>
416
 
      </member>
417
 
      <member>
418
 
        <link linkend="set_fftw_wisdom">set_fftw_wisdom</link>
419
 
      </member>
420
 
      <member>
421
 
        <link linkend="fftw_forget_wisdom">fftw_forget_wisdom</link>
422
 
      </member>
423
 
    </simplelist>
424
 
  </refsection>
425
 
  <refsection>
426
 
    <title>Bibliography</title>
427
 
    <para>
428
 
      Matteo Frigo and Steven G. Johnson, "FFTW Documentation" <ulink url="http://www.fftw.org/#documentation">http://www.fftw.org/#documentation</ulink>
429
 
    </para>
430
 
  </refsection>
431
 
</refentry>