signal_processing: fix typos in fft documentation
[scilab.git] / scilab / modules / signal_processing / help / fr_FR / transforms / 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.1-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           xmlns:scilab="http://www.scilab.org" xml:lang="fr" xml:id="fft">
20     <refnamediv>
21         <refname>fft</refname>
22         <refpurpose>Transformée de Fourier discrète rapide.</refpurpose>
23     </refnamediv>
24     <refnamediv xml:id="ifft">
25         <refname>ifft</refname>
26         <refpurpose>Transformée de Fourier discrète rapide inverse.</refpurpose>
27     </refnamediv>
28     <refsynopsisdiv>
29         <title>Séquence d'appel</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>un tableau de nombres réels ou complexes (vecteur,
42                         matrice, ou tableau N-dimensionnel).
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>X</term>
48                 <listitem>
49                     <para>un tableau de nombres réels ou complexes ayant les
50                         mêmes dimensions que <literal>A</literal>.
51                     </para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>sign</term>
56                 <listitem>
57                     un entier. qui peut prendre les valeurs <literal>1</literal>
58                     ou <literal>-1</literal>. Détermine le sens de la
59                     transformation. La valeur par défaut est
60                     <literal>-1</literal> (transformée directe).
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>option</term>
65                 <listitem>
66                     une chaîne de caratères. qui peut prendre les valeurs
67                     <literal>"symmetric"</literal> ou
68                     <literal>"nonsymmetric"</literal>. Permet d'indiquer à
69                     l'algorithme si <literal>A</literal> est symmétrique ou
70                     non. Si cet argument est omis l'algorithme determine
71                     automatiquement si <literal>A</literal> est symmétrique ou
72                     non. Voir la partie "Description" pour plus de détails.
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>selection</term>
77                 <listitem>
78                     un vecteur contenant des index sur les dimensions de
79                     <literal>A</literal>.  Voir la partie "Description" pour plus
80                     de détails.
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>dims</term>
85                 <listitem>
86                     <para>
87                         un vecteur de nombres positifs à valeurs entières, ou un
88                         vecteur d'entiers positifs.  Voir la partie "Description"
89                         pour plus de détails.
90                     </para>
91                     <para>
92                         Chaque élément doit être un diviseur du nombre total
93                         d'éléments de <literal>A</literal>.
94                     </para>
95                     <para>
96                         Le produit des éléments de <literal>dims</literal> doit
97                         être strictement inférieur au nombre total d'éléments de
98                         <literal>A</literal>.
99                     </para>
100                     
101                 </listitem>
102             </varlistentry>
103             <varlistentry>
104                 <term>incr</term>
105                 <listitem>
106                     <para>
107                         un vecteur de nombres positifs à valeurs entières, ou un
108                         vecteur d'entiers positifs.  Voir la partie "Description"
109                         pour plus de détails.
110                     </para>
111                     <para>
112                         Le nombre d'éléments de <literal>incr</literal> doit être
113                         égal au nombre d'éléments de <literal>dims</literal>.
114                     </para>
115                     <para>
116                         Chaque élément doit être un diviseur du nombre total
117                         d'éléments de <literal>A</literal>.
118                     </para>
119                     <para>
120                         Les éléments de <literal>incr</literal> doivent être en
121                         ordre strictement croissant.
122                     </para>
123                 </listitem>
124             </varlistentry>
125         </variablelist>
126     </refsection>
127     <refsection>
128         <title>Description</title> Cette fonction calcule la transformée
129         de Fourier discrete directe ou inverse, mono ou multi
130         dimensionnelle
131         <variablelist>
132             <varlistentry>
133                 <term>Syntaxe courte</term>
134                 <listitem>
135                     <variablelist>
136                         <varlistentry>
137                             <term>direct</term>
138                             <listitem>
139                                 <literal>X=fft(A,-1 [,option])</literal> ou
140                                 <literal>X=fft(A [,option])</literal> calcule la
141                                 transformée de Fourier discrète directe
142                                 de <literal>A</literal>
143                                 <variablelist>
144                                     <varlistentry>
145                                         <term>monovariable</term>
146                                         <listitem>
147                                             <para>
148                                                 Si <literal>A</literal> est un vecteur
149                                                 <literal>x=fft(a,-1)</literal> ou
150                                                 <literal>x=fft(a)</literal> calcule une
151                                                 transformée monovariable, c'est à dire:
152                                             </para>
153                                             <para>
154                                                 <latex>
155                                                     $x(k) = \sum_{m=1}^n {a(m)*e^{-\frac{2i*\pi}{n}(m-1) (k-1)}$
156                                                 </latex>
157                                             </para>
158                                             
159                                             <para>
160                                                 A noter: (l'argument <literal>-1</literal>
161                                                 argument de la fonction
162                                                 <literal>fft</literal> représente le signe
163                                                 de l'exposant de l'exponentielle.
164                                             </para>
165                                         </listitem>
166                                     </varlistentry>
167                                     
168                                     <varlistentry>
169                                         <term>multivariable</term>
170                                         <listitem>
171                                             <para>
172                                                 Si <literal>A</literal> est une matrice, ou un
173                                                 tableau multi-diemnsionnel,
174                                                 <literal>X=fft(A,-1)</literal> ou
175                                                 <literal>X=fft(A)</literal> calcule la
176                                                 transformée de Fourier discrète directe
177                                                 multivariable de <literal>A</literal>.
178                                             </para>
179                                         </listitem>
180                                     </varlistentry>
181                                 </variablelist>
182                                 
183                             </listitem>
184                         </varlistentry>
185                         <varlistentry>
186                             <term>inverse</term>
187                             <listitem>
188                                 <para>
189                                     <literal>X=fft(A,1)</literal> or
190                                     <literal>X=ifft(A)</literal> calcule la
191                                     transformée inverse normalisée, telle que
192                                     <literal>A==ifft(fft(A))</literal>.
193                                 </para>
194                                 <variablelist>
195                                     <varlistentry>
196                                         <listitem>
197                                             <term>mono-variable</term>
198                                             <para>
199                                                 Si <literal>A</literal> est un vecteur
200                                                 <literal>X=fft(A,+1)</literal> ou
201                                                 <literal>X=ifft(A)</literal> calcule une
202                                                 transformée monovariable inverse, c'est à
203                                                 dire:
204                                             </para>
205                                             <para>
206                                                 <latex>
207                                                     $x(k) = \sum_{m=1}^n
208                                                     {a(m)*e^{+\frac{2i*\pi}{n} (m-1) (k-1)}$
209                                                 </latex>
210                                             </para>
211                                         </listitem>
212                                     </varlistentry>
213                                     <varlistentry>
214                                         <term>multi variable</term>
215                                         <listitem>
216                                             <para>
217                                                 <literal>X=fft(A,+1)</literal> ou
218                                                 <literal>X=ifft(A)</literal> calcule la
219                                                 transformée de Fourier discrète inverse
220                                                 multivariable de <literal>A</literal>
221                                             </para>
222                                         </listitem>
223                                     </varlistentry>
224                                 </variablelist>
225                             </listitem>
226                         </varlistentry>
227                     </variablelist>
228                 </listitem>
229             </varlistentry>
230             
231             <varlistentry>
232                 <term>Syntaxe longue pour la FFT mutidimensionnelle</term>
233                 <listitem>
234                     <itemizedlist>
235                         <listitem>
236                             <para>
237                                 <literal>X=fft(A,sign,selection [,option])</literal>
238                                 permet de calculer efficacement les transformées directes
239                                 ou inverses de toutes les "tranches" de
240                                 <literal>A</literal> correspondant à la selection de
241                                 dimensions.
242                             </para>
243                             <para>
244                                 Par exemple si, <literal>A</literal> est un tableau 3-D,
245                                 <literal>X=fft(A,-1,2)</literal> est équivalent à:
246                             </para>
247                             <programlisting role=""><![CDATA[ 
248               for i1=1:size(A,1)
249               for i3=1:size(A,3)
250               X(i1,:,i3)=fft(A(i1,:,i3),-1);
251               end
252               end
253               ]]></programlisting>
254                             <para>
255                                 et <literal>X=fft(A,-1,[1 3])</literal> est équivalent à:
256                             </para>
257                             <programlisting role=""><![CDATA[ 
258               for i2=1:size(A,2)
259               X(:,i2,:)=fft(A(:,i2,:),-1);
260               end
261               ]]></programlisting>
262                         </listitem>
263                         
264                         <listitem>
265                             <para>
266                                 <literal>X=fft(A,sign,dims,incr [,option])</literal>
267                                 est une syntaxe ancienne qui permet aussi de
268                                 calculer efficacement les transformées directes ou
269                                 inverses de toutes les "tranches" de
270                                 <literal>A</literal> La sélection des "tranches" se
271                                 faisant par la donnée des dimensions et des incréments
272                                 associés à chacune des dimensions. Avec cette syntaxe
273                                 les dimensions effectives de <literal>A</literal> ne
274                                 sont pas prises en compte.
275                             </para>
276                             <para>
277                                 Par example si <literal>A</literal> est un tableau ayant
278                                 <literal>n1*n2*n3</literal> éléments
279                                 <literal>X=fft(A,-1,n1,1)</literal> est équivalent à
280                                 <literal>X=fft(matrix(A,[n1,n2,n3]),-1,1)</literal>.
281                                 et <literal>X=fft(A,-1,[n1 n3],[1 n1*n2])</literal>
282                                 est équivalent à
283                                 <literal>X=fft(matrix(A,[n1,n2,n3]),-1,[1,3])</literal>.
284                             </para>
285                         </listitem>
286                     </itemizedlist>
287                 </listitem>
288             </varlistentry>
289             <varlistentry>
290                 <term>utilisation de l'argument option</term> Cet argument
291                 peut être utilisé pour informer l'algorithme de fft au sujet
292                 de la symétrie de <literal>A</literal> ou de toutes ses
293                 "tranches". Un tableau multi-dimensionnel <literal>B</literal>
294                 qui a pour dimensions <literal>n1</literal>, ...,
295                 <literal>np</literal> est symétrique conjugué pour la fft si
296                 et seulement si <literal>B==conj(B([1 n1:-1:2],[1
297                     n2:-1:2],...,[1 np:-1:2])) 
298                 </literal>
299                 .Dans un tel cas le
300                 résultat de la fft est réel et un algorithme spécifique
301                 peut-être utilisé pour amélioer l'éfficacité et réduire le
302                 coût mémoire.
303                 <listitem>
304                     <itemizedlist>
305                         <listitem>
306                             <term>"symmetric"</term> Cette valeur indique à
307                             l'algorithme de considérer que <literal>A</literal> ou
308                             toutes ses "tranches" est symétrique conjugué. Cette
309                             option est utile pour éviter le surcoùt de la
310                             détermination automatique de la symétrie et pour gérer
311                             les cas où <literal>A</literal> n'est pas exactement
312                             symmétrique du fait par exemple d'erreurs d'arrondis.
313                         </listitem>
314                         <listitem>
315                             <term>"nonsymmetric"</term> Cette valeur force
316                             l'algorithme à ne pas prendre en compte une éventuelle
317                             symétrie.
318                         </listitem>
319                         <listitem>
320                             <term>non spécifié</term> Si l'argument
321                             <literal>option</literal> est omis l'algorithme va
322                             réaliser automatiquement un test de symmétrie exacte.
323                         </listitem>
324                         
325                     </itemizedlist>
326                 </listitem>
327             </varlistentry>
328             <varlistentry>
329                 <term>Optimisation de l'efficacité de la fft</term>
330                 <listitem>
331                     <para>
332                         Remarque: la fonction <literal>fft</literal> sauve
333                         automatiquement des paramêtres en mémoire
334                         (<literal>wisdom</literal>) pour accélérer les calculs de
335                         fft suivants correspondants aux mêmes dimensions et mêmes
336                         options.
337                     </para>
338                     <para> 
339                         Les fonctions <link
340              linkend="get_fftw_wisdom">get_fftw_wisdom</link>, <link
341              linkend="set_fftw_wisdom">set_fftw_wisdom</link>
342                         permettent de récupérer et recharger ces paramètres pour
343                         amélioer l'efficacité de calcul de fft lorsque l'on
344                         alterne plusieurs types de fft.
345                     </para>
346                 </listitem>
347             </varlistentry>
348         </variablelist>
349     </refsection>
350     <refsection>
351         <title>Algorithmes</title>
352         <para>
353             Cette fonction est basée sur la bibliothèque <ulink
354         url="http://www.fftw.org/">fftw3</ulink>.
355         </para>
356         
357     </refsection>
358     
359     <refsection>
360         <title>Examples</title>
361         <para>1-D fft</para>
362         <programlisting role="example"><![CDATA[ 
363 //Composantes fréquentielles d'un signal
364 //----------------------------------
365 // Construction d'un signal bruité échantilloné à 1000hz 
366 //        contenant deux fréquences pures à  50 et 70 Hz.
367 sample_rate=1000;
368 t = 0:1/sample_rate:0.6;
369 N=size(t,'*'); //nombre d'échantillons
370 s=sin(2*%pi*50*t)+sin(2*%pi*70*t+%pi/4)+grand(1,N,'nor',0,1);
371   
372 y=fft(s);
373 //y est symétrique, on ne garde que  N/2 points
374 f=sample_rate*(0:(N/2))/N; //vecteur de fréquences associé
375 n=size(f,'*')
376 clf()
377 plot(f,abs(y(1:n)))
378     ]]></programlisting>
379         
380         <para>2-D fft</para>
381         <programlisting role="example"><![CDATA[ 
382 ----------------------------------
383 A = zeros(256,256);
384 A(5:24,13:17) = 1;
385 X = fftshift(fft(A));
386 set(gcf(),"color_map",jetcolormap(128));
387 clf;grayplot(0:255,0:255,abs(X)')
388      ]]></programlisting>
389         <para>mupliple fft</para>
390         <programlisting role="example"><![CDATA[ 
391 //simple case, 3 1-D fft at a time
392 N=2048;
393 t=linspace(0,10,2048);
394 A=[2*sin(2*%pi*3*t)+ sin(2*%pi*3.5*t)
395   10*sin(2*%pi*8*t)
396    sin(2*%pi*0.5*t)+4*sin(2*%pi*0.8*t)];
397 X=fft(A,-1,2);
398
399 fs=1/(t(2)-t(1));
400 f=fs*(0:(N/2))/N; //associated frequency vector
401 clf;plot(f(1:100)',abs(X(:,1:100))')
402 legend(["3 and 3.5 Hz","8 Hz","0.5 and 0.8 Hz"],"in_upper_left")
403
404 // 45  3-D fft at a time
405 Dims=[5 4 9 5 6];
406 A=matrix(rand(1,prod(Dims)),Dims);
407
408 y=fft(A,-1,[2 4 5]);
409
410 //equivalent (but less efficient code)
411 y1=zeros(A);
412 for i1=1:Dims(1) 
413   for i3=1:Dims(3)
414     ind=list(i1,:,i3,:,:);
415     y1(ind(:))=fft(A(ind(:)),-1);
416   end
417 end
418    ]]></programlisting>
419         
420         <programlisting role="example"><![CDATA[ 
421 //Définition directe de la transformée de Fourier discrete
422 //--------------------------------------------------------
423 function xf=DFT(x,flag);
424   n=size(x,'*');
425   //Calcul de la matrice de Fourier (n by n !)
426   if flag==1 then,//transformation inverse
427     am=exp(2*%pi*%i*(0:n-1)'*(0:n-1)/n);
428   else //transformation directe
429     am=exp(-2*%pi*%i*(0:n-1)'*(0:n-1)/n);
430   end
431   xf=am*matrix(x,n,1);//dft
432   xf=matrix(xf,size(x));//mise en formz
433   if flag==1 then,xf=xf/n;end
434 endfunction
435
436 //Comparaison avec l'algorithme de la transformée rapide:
437 a=rand(1,1000);
438 norm(DFT(a,1) - fft(a,1))
439 norm(DFT(a,-1) - fft(a,-1)) 
440
441 timer();DFT(a,-1);timer()
442 timer();fft(a,-1);timer()
443    ]]></programlisting>
444     </refsection>
445     <refsection role="see also">
446         <title>Voir aussi</title>
447         <simplelist type="inline">
448             <member>
449                 <link linkend="corr">corr</link>
450             </member>
451             <member>
452                 <link linkend="fftw_flags">fftw_flags</link>
453             </member>
454             <member>
455                 <link linkend="get_fftw_wisdom">get_fftw_wisdom</link>
456             </member>
457             <member>
458                 <link linkend="set_fftw_wisdom">set_fftw_wisdom</link>
459             </member>
460             <member>
461                 <link linkend="fftw_forget_wisdom">fftw_forget_wisdom</link>
462             </member>
463         </simplelist>
464     </refsection>
465     <refsection>
466         <title>Bibliographie</title>
467         <para>
468             Matteo Frigo and Steven G. Johnson, "FFTW Documentation" <ulink
469     url="http://www.fftw.org/#documentation">http://www.fftw.org/#documentation</ulink>
470         </para>
471     </refsection>
472 </refentry>