* Bug 13762 fixed [doc]: ifft 1/n normalization missed in TeX 58/21558/6
Samuel GOUGEON [Tue, 28 Jul 2020 19:40:10 +0000 (21:40 +0200)]
  http://bugzilla.scilab.org/13762
  Overhauled fft page (PDF): http://bugzilla.scilab.org/attachment.cgi?id=5164
  +
  * Synopsis unfolded & clarified
  * "selection" argument explicitly renamed "directions"
  * "option" argument
     - explicitly renamed "symmetry"
 - completely described in Arguments, instead of shared in Arguments & Description
  * Very nested lists replaced with <refsect3>
  * LaTeX: alt=".." added for text-rendering.
  * Some code indentation fixed.

Change-Id: Ib04e5ab1a8f7977b64f6885ac90df4d967780607

scilab/CHANGES.md
scilab/modules/helptools/etc/images_md5.txt
scilab/modules/helptools/images/_LaTeX_fft.xml_1.png
scilab/modules/helptools/images/_LaTeX_fft.xml_2.png
scilab/modules/signal_processing/help/en_US/transforms/fft.xml
scilab/modules/signal_processing/help/fr_FR/transforms/fft.xml
scilab/modules/signal_processing/help/ja_JP/transforms/fft.xml
scilab/modules/signal_processing/help/ru_RU/transforms/fft.xml [new file with mode: 0644]

index b1c808c..f44c730 100644 (file)
@@ -200,7 +200,7 @@ Feature changes and additions
 Help pages:
 -----------
 
-* overhauled / rewritten: `bitget`, `edit`, `factorial`, `vectorfind`, `datafit`
+* overhauled / rewritten: `bitget`, `edit`, `factorial`, `fft`, `vectorfind`, `datafit`
 * fixed / improved:  `bench_run` `M_SWITCH`, `comet`, `comet3d`
 * Rewritten: `weekday`
 * Translations added:
@@ -283,6 +283,7 @@ Bug Fixes
 * [#12719](https://bugzilla.scilab.org/12719): `A(%s)` gave the same result as `A($)`.
 * [#12889](https://bugzilla.scilab.org/12889): In the help browser, add a menu allowing to select the language of help pages, regardless of the language of the session.
 * [#13593](https://bugzilla.scilab.org/13593): `csvRead()` did not take the `range` into account when `header` is provided. `[]` could not be used as default `range`.
+* [#13762](https://bugzilla.scilab.org/13762): In the `fft` page, the formula for the inverse FFT missed the 1/n normalization factor.
 * [#14873](https://bugzilla.scilab.org/14873): `setfield` page: The output and the 6.0 history were documented only on the en_US version. The input was wrongly restricted to matrices, while any Scilab object is acceptable. The specific role of `setfield` for mlists was not really described nor illustrated. The example did not include any call to setfield.
 * [#15280](https://bugzilla.scilab.org/15280): `gsort` was unable to sort any hypermatrix along dimensions > "r"|"c".
 * [#15839](https://bugzilla.scilab.org/15839): `gsort`: the only sparse possible input were real or complex vectors, and only with the `g` method.
index 4b63ac4..f0931e7 100644 (file)
@@ -299,8 +299,8 @@ _LaTeX_erfc.xml_1.png=be98f7db5bd298ff2c38bce2e7bb90dd
 _LaTeX_erfcx.xml_1.png=3e69185b6882d8edc7e54d751156dc18
 _LaTeX_erfcx.xml_2.png=5feafbda8ba8a657c647a355fb122b49
 _LaTeX_erfi.xml_1.png=98b6a64c2482c6be60499c854c70a678
-_LaTeX_fft.xml_1.png=7db5478ba8fb1495b82cd5cbcc0635b8
-_LaTeX_fft.xml_2.png=4319fcfbe1beceb023b5361c01cee5ef
+_LaTeX_fft.xml_1.png=b16d8d250dade64a45e1e557c4673442
+_LaTeX_fft.xml_2.png=fa418662faf728120edcfff2a838bc8e
 _LaTeX_filter.xml_1.png=f5eab130f2e7fd10b80a402952421a05
 _LaTeX_floor.xml_ru_RU_1.png=1d5ba78bbbafd3226f371146bc348363
 _LaTeX_grand.xml_1.png=dd59088e24bed7a6af5a6ccd16e58616
index dab2773..725aa13 100644 (file)
Binary files a/scilab/modules/helptools/images/_LaTeX_fft.xml_1.png and b/scilab/modules/helptools/images/_LaTeX_fft.xml_1.png differ
index 5890510..3377141 100644 (file)
Binary files a/scilab/modules/helptools/images/_LaTeX_fft.xml_2.png and b/scilab/modules/helptools/images/_LaTeX_fft.xml_2.png differ
index a7ea4f5..f3b3fbd 100644 (file)
@@ -3,8 +3,8 @@
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 1997   - INRIA
  * Copyright (C) 2012 - Serge Steer - INRIA
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:svg="http://www.w3.org/2000/svg"
-          xmlns:mml="http://www.w3.org/1998/Math/MathML"
-          xmlns:db="http://docbook.org/ns/docbook"
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
           xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="fft">
     <refnamediv>
         <refname>fft</refname>
-        <refpurpose>fast Fourier transform.</refpurpose>
+        <refpurpose>Direct or inverse Fast Fourier Transform of a vector, matrix, or hypermatrix</refpurpose>
     </refnamediv>
     <refnamediv xml:id="ifft">
         <refname>ifft</refname>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>X=fft(A [,sign] [,option])
-            X=fft(A,sign,selection  [,option])
-            X=fft(A,sign,dims,incr [,option] )
+        <synopsis>
+            X = fft(A)
+            X = fft(A, sign)
+            X = fft(A, sign, directions)
+            X = fft(A, sign, dims, incr)
+            X = fft(.., symmetry)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>A</term>
+                <term>A, X</term>
                 <listitem>
-                    <para>a real or complex vector or real or complex array
-                        (vector, matrix or N-D array).
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>X</term>
-                <listitem>
-                    a real or complex array with same shape as <literal>A</literal>.
+                    vectors, matrices or ND-arrays of real or complex numbers, of same sizes.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>sign</term>
                 <listitem>
-                    an integer. with possible values <literal>1</literal> or
-                    <literal>-1</literal>. Select direct or inverse
-                    transform. The default value is <literal>-1</literal>
-                    (direct transform).
+                    -1 or 1 : sign of the ±2iπ factor in the exponential term of the
+                    transform formula, setting the direct or inverse transform. The default
+                    value is <literal>-1</literal> = Direct transform.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>option</term>
+                <term>directions</term>
                 <listitem>
-                    a character string. with possible values
-                    <literal>"symmetric"</literal> or
-                    <literal>"nonsymmetric"</literal>. Indicates if
-                    <literal>A</literal> is symmetric or not. If this argument
-                    is omitted the algorithm automatically determines if
-                    <literal>A</literal> is symmetric or not. See the
-                    Description part for details.
+                    vector containing indices of <varname>A</varname> dimensions (in [1, ndims(A)])
+                    along which the (multidirectional) FFT must be computed.
+                    Default directions=1:ndims(A): The "cumulated" FFT is computed for all directions.
+                    See the Description section.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>selection</term>
+                <term>symmetry</term>
                 <listitem>
-                    a vector containing index on <literal>A</literal> array
-                    dimensions.  See the Description part for details.
+                    optional character string, helping fft() to choose the best algorithm:
+                    <itemizedlist>
+                        <listitem>
+                            <emphasis role="bold">"symmetric"</emphasis>: forces to consider
+                            <varname>A</varname> or all its "slices" as conjugate symmetric.
+                            This is useful when an exact symmetry of <varname>A</varname>
+                            or its "slices" is possibly altered only by round-off errors.
+                            <para/>
+                            A ND-array <literal>B</literal> of sizes <literal>[s1,s2,..,sN]</literal>
+                            is conjugate symmetric for the FFT if and only if
+                            <literal>B==conj(B([1 s1:-1:2],[1 s2:-1:2],...,[1 sN:-1:2]))</literal>.
+                            In such a case, the result <literal>X</literal> is real, and an
+                            efficient specific algorithm can be used to compute it.
+                            <para/>
+                        </listitem>
+                        <listitem>
+                            <emphasis role="bold">"nonsymmetric"</emphasis>: Then fft() does
+                            not take care of any symmetry.
+                            <para/>
+                        </listitem>
+                        <listitem>
+                            not specified: Then an automatic determination of symmetry is performed.
+                            <para/>
+                        </listitem>
+                    </itemizedlist>
                 </listitem>
+                <para/>
             </varlistentry>
             <varlistentry>
                 <term>dims</term>
                 <listitem>
-                    a vector of positive numbers with integer values, or a
-                    vector of positive integers.  See the Description part for details.
-                    <para>
-                        Each element must be a divisor
-                        of the total number of elements of <literal>A</literal>.
-                    </para>
-                    <para>
-                        The product of the elements must be less than the total
-                        number of elements of <literal>A</literal>.
-                    </para>
+                    vector of positive integers. Old syntax.
+                    Each element must be a divisor of length(A).
+                    The product of the elements must be strictly smaller than length(A).
+                    See the Description section for details.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>incr</term>
                 <listitem>
-                    a vector of positive numbers with integer values, or a
-                    vector of positive integers.  See the Description part for
-                    details.
-                    <para>
-                        <literal>incr</literal> must have the same number of
-                        elements than <literal>dims</literal>.
-                    </para>
-                    <para>
-                        Each element must be a divisor of the total number of
-                        elements of <literal>A</literal>.
-                    </para>
-                    <para>
-                        The <literal>incr</literal> elements must be in strictly
-                        increasing order.
-                    </para>
+                    vector of positive strictly increasing integers, as long as
+                    <varname>dims</varname>. Old syntax. Each element must be a divisor of length(A).
+                    See the Description section for details.
+                    <para/>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
     <refsection>
-        <title>Description</title> This function realizes direct or
-        inverse 1-D or N-D Discrete Fourier Transforms.
-        <variablelist>
-            <varlistentry>
-                <term>Short syntax </term>
-                <listitem>
-                    <variablelist>
-                        <varlistentry>
-                            <term>direct</term>
-                            <listitem>
-                                <literal>X=fft(A,-1 [,option])</literal> or
-                                <literal>X=fft(A [,option])</literal> gives a direct
-                                transform.
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>single variate</term>
-                                        <listitem>
-                                            <para>
-                                                If <literal>A</literal> is a vector a
-                                                single variate direct FFT is computed that
-                                                is:
-                                            </para>
-                                            <para>
-                                                <latex>
-                                                    $x(k) = \sum_{m=1}^n
-                                                    {a(m) \exp\left(-2 i\pi\frac{(m-1)}{n} (k-1)\right)}$
-                                                </latex>
-                                            </para>
-                                            <para>
-                                                (the <literal>-1</literal> argument refers
-                                                to the sign of the exponent..., NOT to
-                                                "inverse"),
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-
-                                    <varlistentry>
-                                        <term>multivariate</term>
-                                        <listitem>
-                                            <para>
-                                                If <literal>A</literal> is a matrix or
-                                                a multidimensional array a multivariate direct
-                                                FFT is performed.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>inverse</term>
-                            <listitem>
-                                <para>
-                                    <literal>X=fft(A,1)</literal> or
-                                    <literal>X=ifft(A)</literal>performs the inverse
-                                    normalized transform, such
-                                    that<literal>A==ifft(fft(A))</literal>.
-                                </para>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>single variate</term>
-                                        <listitem>
-                                            If <literal>A</literal> is a vector a single
-                                            variate inverse FFT is computed
-                                            <para>
-                                                <latex>
-                                                    $x(k) = \sum_{m=1}^n
-                                                    {a(m) \exp\left(+2 i\pi\frac{(m-1)}{n} (k-1)\right)}$
-                                                </latex>
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>multivariate</term>
-                                        <listitem>
-                                            <para>
-                                                If <literal>a</literal> is a matrix or or
-                                                a multidimensional array a multivariate inverse
-                                                FFT is performed.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>Long syntax for FFT along specified dimensions</term>
-                <listitem>
-                    <itemizedlist>
-                        <listitem>
-                            <para>
-                                <literal>X=fft(A,sign,selection [,option])</literal>
-                                allows to perform efficiently all direct or inverse
-                                fft of the "slices" of <literal>A</literal> along
-                                selected dimensions.
-                            </para>
-                            <para>
-                                For example, if <literal>A</literal> is a 3-D array
-                                <literal>X=fft(A,-1,2)</literal> is equivalent to:
-                            </para>
-                            <programlisting role=""><![CDATA[
-for i1=1:size(A,1)
-  for i3=1:size(A,3)
-    X(i1,:,i3)=fft(A(i1,:,i3),-1);
-  end
-end
-              ]]></programlisting>
-                            <para>
-                                and <literal>X=fft(A,-1,[1 3])</literal> is equivalent to:
-                            </para>
-                            <programlisting role=""><![CDATA[
-for i2=1:size(A,2)
-  X(:,i2,:)=fft(A(:,i2,:),-1);
-end
-              ]]></programlisting>
-                        </listitem>
+        <title>Description</title>
+        This function computes the direct or inverse 1D, 2D, or.. ND Discrete Fourier Transform
+        of an array or ND-array of numbers, along one or several directions inside this one.
+        <para/>
+        <refsect3>
+            <title>Short syntax</title>
+            <para>
+                <emphasis role="bold">Direct transform</emphasis>:
+            </para>
+            <para>
+                <literal>X = fft(A [,symmetry])</literal> or
+                <literal>X = fft(A, -1 [,symmetry])</literal> gives a direct transform.
+                <variablelist>
+                    <varlistentry>
+                        <term>single variate</term>
                         <listitem>
-                            <para>
-                                <literal>X=fft(A,sign,dims,incr [,option])</literal> is
-                                a previous syntax that also allows to perform all direct or
-                                inverse fft of the slices of <literal>A</literal> along
-                                selected dimensions.
-                            </para>
-                            <para>
-                                For example, if <literal>A</literal> is an array with
-                                <literal>n1*n2*n3</literal> elements
-                                <literal>X=fft(A,-1,n1,1)</literal> is equivalent to
-                                <literal>X=fft(matrix(A,[n1,n2,n3]),-1,1)</literal>.
-                                and <literal>X=fft(A,-1,[n1 n3],[1 n1*n2])</literal>
-                                is equivalent to
-                                <literal>X=fft(matrix(A,[n1,n2,n3]),-1,[1,3])</literal>.
-                            </para>
+                            <varname>a=A</varname> is a vector: a single variate direct
+                            FFT is computed, that is:
+                            <para/>
+                            <latex alt="x(k)=∑_m=1…n a(m).exp(-2iπ.(k-1)(m-1)/n)">
+                                x(k) = \sum_{m=1}^n
+                                {a(m) \exp\left(-2 i\pi\frac{(m-1)}{n} (k-1)\right)}
+                            </latex>
+                            <para/>
                         </listitem>
-                    </itemizedlist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>Using option argument</term> This argument can be used
-                to inform the fft algorithm about the symmetry of
-                <literal>A</literal> or of all its "slices".  An N-D array
-                <literal>B</literal> with dimensions <literal>n1</literal>,
-                ..., <literal>np</literal> is conjugate symmetric for the fft
-                if and only if <literal>B==conj(B([1 n1:-1:2],[1
-                    n2:-1:2],...,[1 np:-1:2]))
-                </literal>
-                .In such a case the
-                result <literal>X</literal> is real and an efficient specific
-                algorithm can be used.
-                <listitem>
-                    <itemizedlist>
+                    </varlistentry>
+                    <varlistentry>
+                        <term>multivariate</term>
                         <listitem>
-                            <term>"symmetric"</term> that value causes fft to treat
-                            <literal>A</literal> or all its "slices" conjugate
-                            symmetric. This option is useful to avoid automatic
-                            determination of symmetry or if <literal>A</literal> or
-                            all its "slices" are not exactly symmetric because of
-                            round-off errors.
+                            <varname>A</varname> is a matrix or a multidimensional
+                            array: A multivariate direct FFT is performed.
+                            <para/>
                         </listitem>
+                    </varlistentry>
+                </variablelist>
+            </para>
+            <para>
+                <emphasis role="bold">Inverse normalized transform</emphasis>:
+            </para>
+            <para>
+                <literal>X = fft(A,+1)</literal> or <literal>X = ifft(A)</literal> performs the
+                inverse normalized transform, such that <literal>A==ifft(fft(A))</literal>.
+                <variablelist>
+                    <varlistentry>
+                        <term>single variate</term>
                         <listitem>
-                            <term>"nonsymmetric"</term> that value causes fft not to
-                            take care of symmetry. This option is useful to avoid
-                            automatic determination of symmetry.
+                            <varname>a=A</varname> is a vector: <literal>X = fft(a, +1)</literal>
+                            or <literal>X = ifft(a)</literal> perform a single variate inverse
+                            FFT, computed as
+                            <para/>
+                            <latex alt="x(k)=(1/n).∑_m=1…n a(m).exp(+2iπ.(k-1)(m-1)/n)">
+                                $x(k) = \frac{1}{n}\sum_{m=1}^n
+                                {a(m) \exp\left(+2 i\pi\frac{(m-1)}{n} (k-1)\right)}$
+                            </latex>
+                            <para/>
                         </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                        <term>multivariate</term>
                         <listitem>
-                            <term>unspecified</term> If the option is omitted the
-                            fft algorithm automatically checks for exact symmetry.
+                            <varname>A</varname> is a matrix or a multidimensional
+                            array: A multivariate inverse FFT is performed.
+                            <para/>
                         </listitem>
-
-                    </itemizedlist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>Optimizing fft</term>
-                <listitem>
-                    <para>
-                        Remark: fftw function automatically stores his last
-                        parameters in memory to re-use it in a second time. This
-                        improves greatly the time computation when consecutives
-                        calls (with same parameters) are performed.
-                    </para>
-                    <para>
-                        It is possible to go further in fft optimization using
-                        <link linkend="get_fftw_wisdom">get_fftw_wisdom</link>, <link
-             linkend="set_fftw_wisdom">set_fftw_wisdom</link> functions.
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Algorithms</title>
-        <para>
-            This function uses the  <ulink url="http://www.fftw.org/">fftw3</ulink> library.
-        </para>
+                    </varlistentry>
+                </variablelist>
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Long syntax : Multidimensionnal directional FFT</title>
+            <para>
+                <emphasis role="bold">X = fft(A, sign, directions [, symmetry])</emphasis>
+                performs efficiently all direct or inverse FFT of all "slices" of
+                <varname>A</varname> along selected <varname>directions</varname>.
+            </para>
+            <para>
+                For example, if <varname>A</varname> is a 3D array,
+                <literal>X = fft(A,-1,2)</literal> is equivalent to:
+                <programlisting role="no-scilab-exec"><![CDATA[
+for i1 = 1:size(A,1)
+    for i3 = 1:size(A,3)
+        X(i1,:,i3) = fft(A(i1,:,i3), -1);
+    end
+end
+             ]]></programlisting>
+            </para>
+            <para>
+                and <literal>X = fft(A,-1,[1 3])</literal> is equivalent to:
+                <programlisting role="no-scilab-exec"><![CDATA[
+for i2 = 1:size(A,2)
+    X(:,i2,:) = fft(A(:,i2,:), -1);
+end
+             ]]></programlisting>
+            </para>
+            <para>
+                <emphasis role="bold">X = fft(A, sign, dims, incr [, symmetry])</emphasis> is
+                an old syntax that also allows to perform all direct or inverse FFT of the
+                slices of <varname>A</varname> along selected <varname>directions</varname>.
+                With this syntax, <varname>A</varname> is considered
+                as serialized into a vector, and its actual sizes are ignored.
+                The slices are selected by providing <varname>A</varname> sizes and
+                increments of the serialized index, related to dimensions.
+            </para>
+            <para>
+                For example, if <varname>A</varname> is an array with
+                <literal>n1*n2*n3</literal> elements,
+                <literal>X = fft(A,-1, n1, 1)</literal> is equivalent to
+                <literal>X = fft(matrix(A,[n1,n2,n3]), -1, 1)</literal> ;
+                and <literal>X = fft(A,-1, [n1 n3], [1 n1*n2])</literal>
+                is equivalent to
+                <literal>X = fft(matrix(A,[n1,n2,n3]), -1, [1,3])</literal>.
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Optimizing fft</title>
+            <para>
+                <emphasis role="bold">Remark</emphasis>:
+                The fft() function automatically stores its last internal parameters in
+                memory to re-use them in a second time. This improves greatly the time computation
+                when consecutive calls (with same parameters) are performed.
+            </para>
+            <para>
+                It is possible to go further in fft() optimization using the
+                <link linkend="get_fftw_wisdom">get_fftw_wisdom</link> and
+                <link linkend="set_fftw_wisdom">set_fftw_wisdom</link> functions.
+            </para>
+            <para>
+                <emphasis role="bold">Algorithms</emphasis>:
+                fft() uses the  <ulink url="http://www.fftw.org/">fftw3</ulink> library.
+            </para>
+            <para>
+                <emphasis role="bold">Bibliography</emphasis>:
+                Matteo Frigo and Steven G. Johnson, "FFTW Documentation"
+                <ulink url="http://www.fftw.org/#documentation">http://www.fftw.org/#documentation</ulink>
+            </para>
+        </refsect3>
     </refsection>
     <refsection>
         <title>Examples</title>
-        <para>1-D fft</para>
+        <para>1D FFT (of a vector):</para>
         <programlisting role="example"><![CDATA[
 //Frequency components of a signal
 //----------------------------------
 // build a noised signal sampled at 1000hz  containing  pure frequencies
 // at 50 and 70 Hz
-sample_rate=1000;
+sample_rate = 1000;
 t = 0:1/sample_rate:0.6;
-N=size(t,'*'); //number of samples
-s=sin(2*%pi*50*t)+sin(2*%pi*70*t+%pi/4)+grand(1,N,'nor',0,1);
+N = size(t,'*'); //number of samples
+s = sin(2*%pi*50*t) + sin(2*%pi*70*t+%pi/4) + grand(1,N,'nor',0,1);
 
 y=fft(s);
 
-//s is real so the fft response is conjugate symmetric and we retain only the first N/2 points
-f=sample_rate*(0:(N/2))/N; //associated frequency vector
-n=size(f,'*')
+// s is real so the fft response is conjugate symmetric and we retain only the first N/2 points
+f = sample_rate*(0:(N/2))/N; //associated frequency vector
+n = size(f,'*')
 clf()
-plot(f,abs(y(1:n)))
+plot(f, abs(y(1:n)))
      ]]></programlisting>
-        <para>2-D fft</para>
+        <para>2D FFT (of a matrix):</para>
         <programlisting role="example"><![CDATA[
-----------------------------------
 A = zeros(256,256);
 A(5:24,13:17) = 1;
 X = fftshift(fft(A));
-set(gcf(),"color_map",jetcolormap(128));
-clf;grayplot(0:255,0:255,abs(X)')
+set(gcf(), "color_map",jetcolormap(128));
+clf; grayplot(0:255, 0:255, abs(X)')
      ]]></programlisting>
-        <para>multiple fft</para>
+        <para>N-Dimensional FFT (of a ND array):</para>
         <programlisting role="example"><![CDATA[
-//simple case, 3 1-D fft at a time
-N=2048;
-t=linspace(0,10,2048);
-A=[2*sin(2*%pi*3*t)+ sin(2*%pi*3.5*t)
-  10*sin(2*%pi*8*t)
-   sin(2*%pi*0.5*t)+4*sin(2*%pi*0.8*t)];
-X=fft(A,-1,2);
+// simple case, 3 1-D fft at a time
+N = 2048;
+t = linspace(0,10,2048);
+A = [2*sin(2*%pi*3*t) + sin(2*%pi*3.5*t)
+     10*sin(2*%pi*8*t)
+     sin(2*%pi*0.5*t) + 4*sin(2*%pi*0.8*t)];
+X = fft(A,-1,2);
 
-fs=1/(t(2)-t(1));
-f=fs*(0:(N/2))/N; //associated frequency vector
-clf;plot(f(1:100)',abs(X(:,1:100))')
+fs = 1/(t(2)-t(1));
+f = fs*(0:(N/2))/N; // associated frequency vector
+clf; plot(f(1:100)',abs(X(:,1:100))')
 legend(["3 and 3.5 Hz","8 Hz","0.5 and 0.8 Hz"],"in_upper_left")
 
 // 45  3-D fft at a time
-Dims=[5 4 9 5 6];
-A=matrix(rand(1,prod(Dims)),Dims);
+Dims = [5 4 9 5 6];
+A = matrix(rand(1, prod(Dims)), Dims);
 
-y=fft(A,-1,[2 4 5]);
+y = fft(A,-1,[2 4 5]);
 
-//equivalent (but less efficient code)
-y1=zeros(A);
-for i1=1:Dims(1)
-  for i3=1:Dims(3)
-    ind=list(i1,:,i3,:,:);
-    y1(ind(:))=fft(A(ind(:)),-1);
+// equivalent (but less efficient code)
+y1 = zeros(A);
+for i1 = 1:Dims(1)
+    for i3 = 1:Dims(3)
+        ind = list(i1,:,i3,:,:);
+        y1(ind(:)) = fft(A(ind(:)),-1);
   end
 end
-   ]]></programlisting>
+     ]]></programlisting>
         <programlisting role="example"><![CDATA[
-//Using explicit formula for  1-D discrete Fourier transform
-//------------------------------------------------
-function xf=DFT(x,flag);
-  n=size(x,'*');
-  //Compute the n by n Fourier matrix
-  if flag==1 then,//backward transformation
-    am=exp(2*%pi*%i*(0:n-1)'*(0:n-1)/n);
-  else //forward transformation
-    am=exp(-2*%pi*%i*(0:n-1)'*(0:n-1)/n);
-  end
-  xf=am*matrix(x,n,1);//dft
-  xf=matrix(xf,size(x));//reshape
-  if flag==1 then,xf=xf/n;end
+// Using explicit formula for  1-D discrete Fourier transform
+// ----------------------------------------------------------
+function xf = DFT(x, Sign);
+    n = size(x,'*');
+    // Compute the n by n Fourier matrix
+    am = exp(Sign * 2*%pi*%i * (0:n-1)'*(0:n-1)/n);
+    xf = am * matrix(x,n,1);  // dft
+    xf = matrix(xf,size(x));  // reshape
+    if Sign == 1 then
+        xf = xf/n;
+    end
 endfunction
 
-//Comparison with the fast Fourier algorithm
-a=rand(1,1000);
+// Comparison with the fast Fourier algorithm
+a = rand(1,1000);
 norm(DFT(a,1) - fft(a,1))
 norm(DFT(a,-1) - fft(a,-1))
 
-timer();DFT(a,-1);timer()
-timer();fft(a,-1);timer()
+tic(); DFT(a,-1); toc()
+tic(); fft(a,-1); toc()
      ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -421,10 +356,4 @@ timer();fft(a,-1);timer()
             </member>
         </simplelist>
     </refsection>
-    <refsection>
-        <title>Bibliography</title>
-        <para>
-            Matteo Frigo and Steven G. Johnson, "FFTW Documentation" <ulink url="http://www.fftw.org/#documentation">http://www.fftw.org/#documentation</ulink>
-        </para>
-    </refsection>
 </refentry>
index 114e630..17fb528 100644 (file)
@@ -3,8 +3,8 @@
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 1997   - INRIA
  * Copyright (C) 2012 - Serge Steer - INRIA
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:svg="http://www.w3.org/2000/svg"
-          xmlns:mml="http://www.w3.org/1998/Math/MathML"
-          xmlns:db="http://docbook.org/ns/docbook"
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
           xmlns:scilab="http://www.scilab.org" xml:lang="fr" xml:id="fft">
     <refnamediv>
         <refname>fft</refname>
-        <refpurpose>Transformée de Fourier discrète rapide.</refpurpose>
+        <refpurpose>Transformée de Fourier discrète directe ou inverse uni-, bi-, ou N-dimensionnelle</refpurpose>
     </refnamediv>
     <refnamediv xml:id="ifft">
         <refname>ifft</refname>
-        <refpurpose>Transformée de Fourier discrète rapide inverse.</refpurpose>
+        <refpurpose>Transformée de Fourier inverse discrète.</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Séquence d'appel</title>
-        <synopsis>X=fft(A [,sign] [,option])
-            X=fft(A,sign,selection  [,option])
-            X=fft(A,sign,dims,incr [,option] )
+        <synopsis>
+            X = fft(A)
+            X = fft(A, sign)
+            X = fft(A, sign, directions)
+            X = fft(A, sign, dims, incr)
+            X = fft(.., symmetry)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>A</term>
-                <listitem>
-                    <para>un tableau de nombres réels ou complexes (vecteur,
-                        matrice, ou tableau N-dimensionnel).
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>X</term>
+                <term>A, X</term>
                 <listitem>
-                    <para>un tableau de nombres réels ou complexes ayant les
-                        mêmes dimensions que <literal>A</literal>.
-                    </para>
+                    vecteurs,  matrices, ou tableaux N-dimensionnels de nombres réels ou complexes,
+                    de tailles identiques.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>sign</term>
                 <listitem>
-                    un entier. qui peut prendre les valeurs <literal>1</literal>
-                    ou <literal>-1</literal>. Détermine le sens de la
-                    transformation. La valeur par défaut est
-                    <literal>-1</literal> (transformée directe).
+                    -1 ou 1 = signe du facteur ±2iπ dans le terme exponentiel calculant la
+                    transformée, et fixant le sens de celle-ci. Par défaut = -1 = transformée directe.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>option</term>
+                <term>directions</term>
                 <listitem>
-                    une chaîne de caratères. qui peut prendre les valeurs
-                    <literal>"symmetric"</literal> ou
-                    <literal>"nonsymmetric"</literal>. Permet d'indiquer à
-                    l'algorithme si <literal>A</literal> est symmétrique ou
-                    non. Si cet argument est omis l'algorithme determine
-                    automatiquement si <literal>A</literal> est symmétrique ou
-                    non. Voir la partie "Description" pour plus de détails.
+                    vecteur contenant les numéros des dimensions <varname>A</varname>
+                    (dans [1, ndims(A)]) selon lesquelles la FFT (multidirectionnelle) doit être
+                    calculée. Par défaut, directions=1:ndims(A) : la FFT "cumulée" est calculée
+                    pour toutes les directions.
+                    Voir la partie "Description" pour plus de détails.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>selection</term>
+                <term>symmetry</term>
                 <listitem>
-                    un vecteur contenant des index sur les dimensions de
-                    <literal>A</literal>.  Voir la partie "Description" pour plus
-                    de détails.
+                    mot-texte optionnel, aidant fft() à choisir le meilleur algorithme :
+                    <itemizedlist>
+                        <listitem>
+                            <emphasis role="bold">"symmetric"</emphasis>: force fft() à considérer
+                            <varname>A</varname> ou toutes ses  "tranches" comme symétriques
+                            conjuguées. Cela est utile lorsqu'une symétrie exacte attendue a été
+                            altérée par des erreurs d'arrondis provenant d'opérations antérieures
+                            effectuées sur <varname>A</varname>.
+                            <para/>
+                            Un hypertableau numérique N-Dimensionnel <literal>B</literal> de tailles
+                            <literal>[s1,s2,..,sN]</literal>
+                            est conjugué symétrique pur la FFT si et seulement si
+                            <literal>B==conj(B([1 s1:-1:2],[1 s2:-1:2],...,[1 sN:-1:2]))</literal>.
+                            Dans ce cas, le résultat <literal>X</literal> est réel. Un algorithme
+                            efficace spécifique peut alors être utilisé pour le calculer.
+                            <para/>
+                        </listitem>
+                        <listitem>
+                            <emphasis role="bold">"nonsymmetric"</emphasis>: force fft() à ignorer
+                            toute propriété de symétrie.
+                            <para/>
+                        </listitem>
+                        <listitem>
+                            option non fournie : fft() détermine alors automatiquement les propriétés
+                            de symétrie de <varname>A</varname>.
+                            <para/>
+                        </listitem>
+                    </itemizedlist>
                 </listitem>
+                <para/>
             </varlistentry>
             <varlistentry>
                 <term>dims</term>
                 <listitem>
-                    <para>
-                        un vecteur de nombres positifs à valeurs entières, ou un
-                        vecteur d'entiers positifs.  Voir la partie "Description"
-                        pour plus de détails.
-                    </para>
-                    <para>
-                        Chaque élément doit être un diviseur du nombre total
-                        d'éléments de <literal>A</literal>.
-                    </para>
-                    <para>
-                        Le produit des éléments de <literal>dims</literal> doit
-                        être strictement inférieur au nombre total d'éléments de
-                        <literal>A</literal>.
-                    </para>
-
+                    vecteur d'entiers positifs. Chaque élément doit être un diviseur de length(A).
+                    Le produit des éléments de <varname>dims</varname> doit être strictement
+                    inférieur à length(A). Ancienne syntaxe. Voir la partie "Description".
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>incr</term>
                 <listitem>
-                    <para>
-                        un vecteur de nombres positifs à valeurs entières, ou un
-                        vecteur d'entiers positifs.  Voir la partie "Description"
-                        pour plus de détails.
-                    </para>
-                    <para>
-                        Le nombre d'éléments de <literal>incr</literal> doit être
-                        égal au nombre d'éléments de <literal>dims</literal>.
-                    </para>
-                    <para>
-                        Chaque élément doit être un diviseur du nombre total
-                        d'éléments de <literal>A</literal>.
-                    </para>
-                    <para>
-                        Les éléments de <literal>incr</literal> doivent être en
-                        ordre strictement croissant.
-                    </para>
+                    vecteur d'entiers positifs strictement croissants, de taille identique à
+                    celle de <varname>dims</varname>. Chaque élément doit être un diviseur
+                    de length(A). Ancienne syntaxe. Voir la partie "Description".
+                    <para/>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
     <refsection>
-        <title>Description</title> Cette fonction calcule la transformée
-        de Fourier discrete directe ou inverse, mono ou multi
-        dimensionnelle
-        <variablelist>
-            <varlistentry>
-                <term>Syntaxe courte</term>
-                <listitem>
-                    <variablelist>
-                        <varlistentry>
-                            <term>direct</term>
-                            <listitem>
-                                <literal>X=fft(A,-1 [,option])</literal> ou
-                                <literal>X=fft(A [,option])</literal> calcule la
-                                transformée de Fourier discrète directe
-                                de <literal>A</literal>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>monovariable</term>
-                                        <listitem>
-                                            <para>
-                                                Si <literal>A</literal> est un vecteur
-                                                <literal>x=fft(a,-1)</literal> ou
-                                                <literal>x=fft(a)</literal> calcule une
-                                                transformée monovariable, c'est à dire:
-                                            </para>
-                                            <para>
-                                                <latex>
-                                                    $x(k) = \sum_{m=1}^n
-                                                    {a(m) \exp\left(-2 i\pi\frac{(m-1)}{n} (k-1)\right)}$
-                                                </latex>
-                                            </para>
-
-                                            <para>
-                                                A noter: (l'argument <literal>-1</literal>
-                                                argument de la fonction
-                                                <literal>fft</literal> représente le signe
-                                                de l'exposant de l'exponentielle.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-
-                                    <varlistentry>
-                                        <term>multivariable</term>
-                                        <listitem>
-                                            <para>
-                                                Si <literal>A</literal> est une matrice, ou un
-                                                tableau multi-diemnsionnel,
-                                                <literal>X=fft(A,-1)</literal> ou
-                                                <literal>X=fft(A)</literal> calcule la
-                                                transformée de Fourier discrète directe
-                                                multivariable de <literal>A</literal>.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>inverse</term>
-                            <listitem>
-                                <para>
-                                    <literal>X=fft(A,1)</literal> or
-                                    <literal>X=ifft(A)</literal> calcule la
-                                    transformée inverse normalisée, telle que
-                                    <literal>A==ifft(fft(A))</literal>.
-                                </para>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>mono-variable</term>
-
-                                        <listitem>
-                                            <para>
-                                                Si <literal>A</literal> est un vecteur
-                                                <literal>X=fft(A,+1)</literal> ou
-                                                <literal>X=ifft(A)</literal> calcule une
-                                                transformée monovariable inverse, c'est à
-                                                dire:
-                                            </para>
-                                            <para>
-                                                <latex>
-                                                    $x(k) = \sum_{m=1}^n
-                                                    {a(m) \exp\left(+2 i\pi\frac{(m-1)}{n} (k-1)\right)}$
-                                                </latex>
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>multi variable</term>
-                                        <listitem>
-                                            <para>
-                                                <literal>X=fft(A,+1)</literal> ou
-                                                <literal>X=ifft(A)</literal> calcule la
-                                                transformée de Fourier discrète inverse
-                                                multivariable de <literal>A</literal>
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-
-            <varlistentry>
-                <term>Syntaxe longue pour la FFT mutidimensionnelle</term>
-                <listitem>
-                    <itemizedlist>
+        <title>Description</title>
+        Cette fonction calcule la transformée de Fourier discrète directe ou inverse d'un tableau
+        ou d'un hypertableau de nombres, selon une ou plusieurs directions au sein de celui-ci.
+        <para/>
+        <refsect3>
+            <title>Syntaxe courte</title>
+            <para>
+                <emphasis role="bold">Transformée directe</emphasis> :
+            </para>
+            <para>
+                <literal>X = fft(A,-1 [, symmetry])</literal> ou
+                <literal>X = fft(A [, symmetry])</literal> calcule la transformée de Fourier discrète
+                directe de <varname>A</varname>.
+                <variablelist>
+                    <varlistentry>
+                        <term>monovariable</term>
                         <listitem>
-                            <para>
-                                <literal>X=fft(A,sign,selection [,option])</literal>
-                                permet de calculer efficacement les transformées directes
-                                ou inverses de toutes les "tranches" de
-                                <literal>A</literal> correspondant à la selection de
-                                dimensions.
-                            </para>
-                            <para>
-                                Par exemple si, <literal>A</literal> est un tableau 3-D,
-                                <literal>X=fft(A,-1,2)</literal> est équivalent à:
-                            </para>
-                            <programlisting role=""><![CDATA[
-              for i1=1:size(A,1)
-              for i3=1:size(A,3)
-              X(i1,:,i3)=fft(A(i1,:,i3),-1);
-              end
-              end
-              ]]></programlisting>
-                            <para>
-                                et <literal>X=fft(A,-1,[1 3])</literal> est équivalent à:
-                            </para>
-                            <programlisting role=""><![CDATA[
-              for i2=1:size(A,2)
-              X(:,i2,:)=fft(A(:,i2,:),-1);
-              end
-              ]]></programlisting>
+                            <varname>a=A</varname> est un vecteur : <literal>x=fft(a,-1)</literal> ou
+                            <literal>x = fft(a)</literal> calcule une transformée monovariable,
+                            c'est à dire:
+                            <para/>
+                            <latex alt="x(k)=∑_m=1…n a(m).exp(-2iπ.(k-1)(m-1)/n)">
+                                x(k) = \sum_{m=1}^n
+                                {a(m) \exp\left(-2 i\pi\frac{(m-1)}{n} (k-1)\right)}
+                            </latex>
+                            <para/>
                         </listitem>
-
+                    </varlistentry>
+                    <varlistentry>
+                        <term>multivariable</term>
                         <listitem>
-                            <para>
-                                <literal>X=fft(A,sign,dims,incr [,option])</literal>
-                                est une syntaxe ancienne qui permet aussi de
-                                calculer efficacement les transformées directes ou
-                                inverses de toutes les "tranches" de
-                                <literal>A</literal> La sélection des "tranches" se
-                                faisant par la donnée des dimensions et des incréments
-                                associés à chacune des dimensions. Avec cette syntaxe
-                                les dimensions effectives de <literal>A</literal> ne
-                                sont pas prises en compte.
-                            </para>
-                            <para>
-                                Par example si <literal>A</literal> est un tableau ayant
-                                <literal>n1*n2*n3</literal> éléments
-                                <literal>X=fft(A,-1,n1,1)</literal> est équivalent à
-                                <literal>X=fft(matrix(A,[n1,n2,n3]),-1,1)</literal>.
-                                et <literal>X=fft(A,-1,[n1 n3],[1 n1*n2])</literal>
-                                est équivalent à
-                                <literal>X=fft(matrix(A,[n1,n2,n3]),-1,[1,3])</literal>.
-                            </para>
-                        </listitem>
-                    </itemizedlist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>utilisation de l'argument option</term> Cet argument
-                peut être utilisé pour informer l'algorithme de fft au sujet
-                de la symétrie de <literal>A</literal> ou de toutes ses
-                "tranches". Un tableau multi-dimensionnel <literal>B</literal>
-                qui a pour dimensions <literal>n1</literal>, ...,
-                <literal>np</literal> est symétrique conjugué pour la fft si
-                et seulement si <literal>B==conj(B([1 n1:-1:2],[1
-                    n2:-1:2],...,[1 np:-1:2]))
-                </literal>
-                .Dans un tel cas le
-                résultat de la fft est réel et un algorithme spécifique
-                peut-être utilisé pour amélioer l'éfficacité et réduire le
-                coût mémoire.
-                <listitem>
-                    <itemizedlist>
-                        <listitem>
-                            <term>"symmetric"</term> Cette valeur indique à
-                            l'algorithme de considérer que <literal>A</literal> ou
-                            toutes ses "tranches" est symétrique conjugué. Cette
-                            option est utile pour éviter le surcoùt de la
-                            détermination automatique de la symétrie et pour gérer
-                            les cas où <literal>A</literal> n'est pas exactement
-                            symmétrique du fait par exemple d'erreurs d'arrondis.
+                            <varname>A</varname> est une matrice, ou un hypertableau N-dimensionnel :
+                            <literal>X = fft(A,-1)</literal> ou <literal>X = fft(A)</literal>
+                            calcule la transformée de Fourier discrète multivariable directe
+                            de <varname>A</varname>.
+                            <para/>
                         </listitem>
+                    </varlistentry>
+                </variablelist>
+            </para>
+            <para>
+                <emphasis role="bold">Transformée inverse normalisée</emphasis> :
+            </para>
+            <para>
+                <literal>X = fft(A, 1)</literal> ou <literal>X = ifft(A)</literal> calcule la
+                transformée inverse normalisée, telle que <literal>A==ifft(fft(A))</literal>.
+                <variablelist>
+                    <varlistentry>
+                        <term>monovariable</term>
                         <listitem>
-                            <term>"nonsymmetric"</term> Cette valeur force
-                            l'algorithme à ne pas prendre en compte une éventuelle
-                            symétrie.
+                            <varname>a=A</varname> est un vecteur : <literal>X = fft(a, +1)</literal>
+                            ou <literal>X = ifft(A)</literal> calcule la transformée monovariable
+                            inverse, c'est à dire :
+                            <para/>
+                            <latex alt="x(k)=(1/n).∑_m=1…n a(m).exp(+2iπ.(k-1)(m-1)/n)">
+                                $x(k) = \frac{1}{n}\sum_{m=1}^n
+                                {a(m) \exp\left(+2 i\pi\frac{(m-1)}{n} (k-1)\right)}$
+                            </latex>
+                            <para/>
                         </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                        <term>multivariable</term>
                         <listitem>
-                            <term>non spécifié</term> Si l'argument
-                            <literal>option</literal> est omis l'algorithme va
-                            réaliser automatiquement un test de symmétrie exacte.
+                            <varname>A</varname> est une matrice ou un hypertableau N-dimensionnel :
+                            <literal>X = fft(A, +1)</literal> ou <literal>X = ifft(A)</literal>
+                            calcule la transformée de Fourier multivariable discrète inverse
+                            de <varname>A</varname>.
+                            <para/>
                         </listitem>
-
-                    </itemizedlist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>Optimisation de l'efficacité de la fft</term>
-                <listitem>
-                    <para>
-                        Remarque: la fonction <literal>fft</literal> sauve
-                        automatiquement des paramêtres en mémoire
-                        (<literal>wisdom</literal>) pour accélérer les calculs de
-                        fft suivants correspondants aux mêmes dimensions et mêmes
-                        options.
-                    </para>
-                    <para>
-                        Les fonctions <link
-             linkend="get_fftw_wisdom">get_fftw_wisdom</link>, <link
-             linkend="set_fftw_wisdom">set_fftw_wisdom</link>
-                        permettent de récupérer et recharger ces paramètres pour
-                        amélioer l'efficacité de calcul de fft lorsque l'on
-                        alterne plusieurs types de fft.
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
+                    </varlistentry>
+                </variablelist>
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Syntaxe longue : FFT directionnelle mutidimensionnelle</title>
+            <para>
+                <emphasis role="bold">X = fft(A, sign, directions [, symmetry])</emphasis>
+                calcule efficacement les transformées directes ou inverses de toutes les
+                "rangées" de <varname>A</varname>, selon les <varname>directions</varname>
+                spécifiées.
+            </para>
+            <para>
+                Par exemple, si <varname>A</varname> est un tableau 3D,
+                <literal>X = fft(A,-1, 2)</literal> est équivalent à
+                <programlisting role="no-scilab-exec"><![CDATA[
+for i1 = 1:size(A,1)
+    for i3 = 1:size(A,3)
+        X(i1,:,i3) = fft(A(i1,:,i3), -1);
+    end
+end
+            ]]></programlisting>
+            </para>
+            <para>
+                et <literal>X = fft(A, -1, [1 3])</literal> est équivalent à
+                <programlisting role="no-scilab-exec"><![CDATA[
+for i2 = 1:size(A,2)
+    X(:,i2,:) = fft(A(:,i2,:), -1);
+end
+            ]]></programlisting>
+            </para>
+            <para>
+                <emphasis role="bold">X = fft(A, sign, dims, incr [, symmetry])</emphasis>
+                est une syntaxe ancienne qui permet aussi de
+                calculer efficacement les transformées directes ou inverses de "rangées" choisies
+                de <varname>A</varname>.
+                Avec cette syntaxe, <varname>A</varname> est vue comme sérialisée en un vecteur,
+                et ses tailles effectives ne sont pas prises en compte.
+                La sélection des "rangées" se fait par la donnée des tailles et des incréments
+                de l'indice sérialisé associés à chacune des dimensions.
+            </para>
+            <para>
+                Par exemple, si <varname>A</varname> est un hypertableau ayant
+                <literal>n1*n2*n3</literal> éléments,
+                <literal>X = fft(A,-1, n1, 1)</literal> est équivalent à
+                <literal>X = fft(matrix(A,[n1,n2,n3]), -1, 1)</literal> ;
+                et <literal>X = fft(A, -1, [n1 n3], [1 n1*n2])</literal>
+                est équivalent à
+                <literal>X = fft(matrix(A,[n1,n2,n3]), -1, [1,3])</literal>.
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Optimisation algorithmique de fft()</title>
+            <para>
+                <emphasis role="bold">Remarque</emphasis> :
+                la fonction <literal>fft</literal> enregistre automatiquement des
+                paramêtres de calcul internes en mémoire (<literal>wisdom</literal>),
+                pour accélérer les calculs de FFT suivants correspondant aux mêmes directions
+                avec les mêmes options.
+            </para>
+            <para>
+                Les fonctions <link linkend="get_fftw_wisdom">get_fftw_wisdom</link> et
+                <link  linkend="set_fftw_wisdom">set_fftw_wisdom</link>
+                permettent de récupérer et de recharger ces paramètres, afin d'améliorer
+                l'efficacité de calcul de FFT lorsqu'on alterne plusieurs types de FFT.
+            </para>
+            <para>
+                <emphasis role="bold">Algorithmes</emphasis> :
+                fft() est basée sur la bibliothèque externe
+                <ulink url="http://www.fftw.org/">fftw3</ulink>.
+            </para>
+            <para>
+                <emphasis role="bold">Bibliographie</emphasis> :
+                Matteo Frigo and Steven G. Johnson, "FFTW Documentation"
+                <ulink url="http://www.fftw.org/#documentation">http://www.fftw.org/#documentation</ulink>
+            </para>
+        </refsect3>
     </refsection>
     <refsection>
-        <title>Algorithmes</title>
+        <title>Exemples</title>
         <para>
-            Cette fonction est basée sur la bibliothèque <ulink
-        url="http://www.fftw.org/">fftw3</ulink>.
+            FFT uni-dimensionnelle (sur un vecteur) :
         </para>
-
-    </refsection>
-
-    <refsection>
-        <title>Examples</title>
-        <para>1-D fft</para>
         <programlisting role="example"><![CDATA[
 //Composantes fréquentielles d'un signal
 //----------------------------------
 // Construction d'un signal bruité échantilloné à 1000hz
-//        contenant deux fréquences pures à  50 et 70 Hz.
-sample_rate=1000;
+//   contenant deux fréquences pures à  50 et 70 Hz.
+sample_rate = 1000;
 t = 0:1/sample_rate:0.6;
-N=size(t,'*'); //nombre d'échantillons
-s=sin(2*%pi*50*t)+sin(2*%pi*70*t+%pi/4)+grand(1,N,'nor',0,1);
+N = size(t,'*'); // nombre d'échantillons
+s = sin(2*%pi*50*t) + sin(2*%pi*70*t+%pi/4) + grand(1,N,'nor',0,1);
 
-y=fft(s);
-//y est symétrique, on ne garde que  N/2 points
-f=sample_rate*(0:(N/2))/N; //vecteur de fréquences associé
-n=size(f,'*')
+y = fft(s);
+// y est symétrique, on ne garde que  N/2 points
+f = sample_rate*(0:(N/2))/N;  // vecteur de fréquences associé
+n = size(f,'*')
 clf()
-plot(f,abs(y(1:n)))
+plot(f, abs(y(1:n)))
     ]]></programlisting>
 
-        <para>2-D fft</para>
+        <para>FFT bi-dimensionnelle (sur une matrice)</para>
         <programlisting role="example"><![CDATA[
-//----------------------------------
 A = zeros(256,256);
 A(5:24,13:17) = 1;
 X = fftshift(fft(A));
-set(gcf(),"color_map",jetcolormap(128));
-clf;grayplot(0:255,0:255,abs(X)')
+set(gcf(), "color_map",jetcolormap(128));
+clf; grayplot(0:255, 0:255, abs(X)')
      ]]></programlisting>
-        <para>mupliple fft</para>
+        <para>FFT ND-dimensionnelle ("hyper-FFT")</para>
         <programlisting role="example"><![CDATA[
-//simple case, 3 1-D fft at a time
-N=2048;
-t=linspace(0,10,2048);
-A=[2*sin(2*%pi*3*t)+ sin(2*%pi*3.5*t)
-  10*sin(2*%pi*8*t)
-   sin(2*%pi*0.5*t)+4*sin(2*%pi*0.8*t)];
-X=fft(A,-1,2);
+// simple case, 3 1-D fft at a time
+N = 2048;
+t = linspace(0,10,2048);
+A = [2*sin(2*%pi*3*t) + sin(2*%pi*3.5*t)
+     10*sin(2*%pi*8*t)
+     sin(2*%pi*0.5*t) + 4*sin(2*%pi*0.8*t)];
+X = fft(A,-1,2);
 
-fs=1/(t(2)-t(1));
-f=fs*(0:(N/2))/N; //associated frequency vector
-clf;plot(f(1:100)',abs(X(:,1:100))')
+fs = 1/(t(2)-t(1));
+f = fs*(0:(N/2))/N; // associated frequency vector
+clf; plot(f(1:100)', abs(X(:,1:100))')
 legend(["3 and 3.5 Hz","8 Hz","0.5 and 0.8 Hz"],"in_upper_left")
 
 // 45  3-D fft at a time
-Dims=[5 4 9 5 6];
-A=matrix(rand(1,prod(Dims)),Dims);
+Dims = [5 4 9 5 6];
+A = matrix(rand(1,prod(Dims)), Dims);
 
-y=fft(A,-1,[2 4 5]);
+y = fft(A, -1, [2 4 5]);
 
-//equivalent (but less efficient code)
-y1=zeros(A);
-for i1=1:Dims(1)
-  for i3=1:Dims(3)
-    ind=list(i1,:,i3,:,:);
-    y1(ind(:))=fft(A(ind(:)),-1);
+// Code équivalent (mais moins efficace)
+y1 = zeros(A);
+for i1 = 1:Dims(1)
+  for i3 = 1:Dims(3)
+    ind = list(i1,:,i3,:,:);
+    y1(ind(:)) = fft(A(ind(:)), -1);
   end
 end
    ]]></programlisting>
 
         <programlisting role="example"><![CDATA[
-//Définition directe de la transformée de Fourier discrete
-//--------------------------------------------------------
-function xf=DFT(x,flag);
-  n=size(x,'*');
-  //Calcul de la matrice de Fourier (n by n !)
-  if flag==1 then,//transformation inverse
-    am=exp(2*%pi*%i*(0:n-1)'*(0:n-1)/n);
-  else //transformation directe
-    am=exp(-2*%pi*%i*(0:n-1)'*(0:n-1)/n);
-  end
-  xf=am*matrix(x,n,1);//dft
-  xf=matrix(xf,size(x));//mise en formz
-  if flag==1 then,xf=xf/n;end
+// Définition directe de la transformée de Fourier discrete
+// --------------------------------------------------------
+function xf = DFT(x, Sign);
+    n = size(x,'*');
+    // Calcul de la matrice de Fourier (n by n !)
+    am = exp(Sign*2*%pi*%i*(0:n-1)'*(0:n-1)/n);
+    xf = am*matrix(x,n,1);   // dft
+    xf = matrix(xf, size(x)); // mise en forme
+    if Sign==1 then
+        xf = xf/n
+    end
 endfunction
 
-//Comparaison avec l'algorithme de la transformée rapide:
-a=rand(1,1000);
+// Comparaison avec l'algorithme de la transformée rapide:
+a = rand(1,1000);
 norm(DFT(a,1) - fft(a,1))
 norm(DFT(a,-1) - fft(a,-1))
 
-timer();DFT(a,-1);timer()
-timer();fft(a,-1);timer()
+tic(); DFT(a,-1); toc()
+tic(); fft(a,-1); toc()
    ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -467,11 +373,4 @@ timer();fft(a,-1);timer()
             </member>
         </simplelist>
     </refsection>
-    <refsection>
-        <title>Bibliographie</title>
-        <para>
-            Matteo Frigo and Steven G. Johnson, "FFTW Documentation" <ulink
-    url="http://www.fftw.org/#documentation">http://www.fftw.org/#documentation</ulink>
-        </para>
-    </refsection>
 </refentry>
index a0fa841..250170b 100644 (file)
@@ -1,6 +1,22 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="ja" xml:id="fft">
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 1997   - INRIA
+ * Copyright (C) 2012 - Serge Steer - INRIA
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:lang="ja" xml:id="fft">
     <refnamediv>
         <refname>fft</refname>
         <refpurpose>高速フーリエ変換</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>呼び出し手順</title>
-        <synopsis>X=fft(A [,sign] [,option])
-            X=fft(A,sign,selection  [,option])
-            X=fft(A,sign,dims,incr [,option] )
+        <synopsis>
+            X = fft(A)
+            X = fft(A, sign)
+            X = fft(A, sign, directions)
+            X = fft(A, sign, dims, incr)
+            X = fft(.., symmetry)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
             <varlistentry>
                 <term>A</term>
                 <listitem>
-                    <para>
-                        実数または複素数ベクトル,
-                        実数または複素数配列(ベクトル, 行列またはN-D配列).
-                    </para>
+                    実数または複素数ベクトル,
+                    実数または複素数配列(ベクトル, 行列またはN-D配列).
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>X</term>
                 <listitem>
-                    <para>
-                        <literal>A</literal>と同じ形状の実数または複素数配列
-                    </para>
+                    <varname>A</varname>と同じ形状の実数または複素数配列
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>sign</term>
                 <listitem>
-                    an integer. with possible values <literal>1</literal> or
-                    <literal>-1</literal>. Select direct or inverse
-                    transform. The default value is <literal>-1</literal>
-                    (direct transform).
+                    -1 or 1 : sign of the ±2iπ factor in the exponential term inside the
+                    transform formula, setting the direct or inverse transform. The default
+                    value is <literal>-1</literal> = Direct transform.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>option</term>
+                <term>directions</term>
                 <listitem>
-                    文字列. 指定可能な値は
-                    <literal>"symmetric"</literal> または
-                    <literal>"nonsymmetric"</literal>です.
-                    <literal>A</literal>が対称かどうかを示します.
-                    この引数が省略された場合,アルゴリズムは
-                    <literal>A</literal>が対称かどうかを自動的に定義します.
-                    詳細は説明のパートを参照ください.
+                    a vector containing indices of <varname>A</varname> dimensions (in [1, ndims(A)])
+                    along which the (multidirectional) FFT must be computed.
+                    Default directions=1:ndims(A): The "cumulated" FFT is computed for all directions.
+                    See the Description section.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>selection</term>
+                <term>symmetry</term>
                 <listitem>
-                    <literal>A</literal> 配列の次元の添字を有するベクトル.
-                    詳細は説明のパートを参照ください.
+                    optional character string, helping fft() to choose the best algorithm:
+                    <itemizedlist>
+                        <listitem>
+                            <emphasis role="bold">"symmetric"</emphasis>: forces to consider
+                            <varname>A</varname> or all its "slices" as conjugate symmetric.
+                            This is useful when an exact symmetry of <varname>A</varname>
+                            or its "slices" is possibly altered only by round-off errors.
+                            <para/>
+                            A N-D array <literal>B</literal> of sizes <literal>[s1,s2,..,sN]</literal>
+                            is conjugate symmetric for the FFT if and only if
+                            <literal>B==conj(B([1 s1:-1:2],[1 s2:-1:2],...,[1 sN:-1:2]))</literal>.
+                            In such a case, the result <literal>X</literal> is real, and an
+                            efficient specific algorithm can be used to compute it.
+                            <para/>
+                        </listitem>
+                        <listitem>
+                            <emphasis role="bold">"nonsymmetric"</emphasis>: Then fft() does
+                            not take care of any symmetry.
+                            <para/>
+                        </listitem>
+                        <listitem>
+                            not specified: Then an automatic determination of symmetry is performed.
+                            <para/>
+                        </listitem>
+                    </itemizedlist>
                 </listitem>
+                <para/>
             </varlistentry>
             <varlistentry>
                 <term>dims</term>
                 <listitem>
                     整数値を有する正の数のベクトルまたは正の整数値のベクトル.
                     詳細は説明のパートを参照ください.
-                    <para>
-                        各要素は<literal>A</literal>の要素の総数の約数とする
-                        必要があります.
-                    </para>
-                    <para>
-                        要素の積は<literal>A</literal>の全要素数より
-                        少ない必要があります.
-                    </para>
+                    各要素は<varname>A</varname>の要素の総数の約数とする
+                    必要があります.
+                    要素の積は<varname>A</varname>の全要素数より
+                    少ない必要があります.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <listitem>
                     整数値を有する正の数のベクトルまたは正の整数値のベクトル.
                     詳細は説明のパートを参照ください.
-                    <para>
-                        <literal>incr</literal> は,
-                        <literal>dims</literal>と同じ要素数とする必要があります.
-                    </para>
-                    <para>
-                        各要素は
-                        <literal>A</literal>の全要素数の約数とする必要があります.
-                    </para>
-                    <para>
-                        <literal>incr</literal>要素は厳密に昇順とする必要があります.
-                    </para>
+                    <literal>incr</literal> は,
+                    <literal>dims</literal>と同じ要素数とする必要があります.
+                    各要素は <varname>A</varname>の全要素数の約数とする必要があります.
+                    <literal>incr</literal>要素は厳密に昇順とする必要があります.
+                    <para/>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
     <refsection>
         <title>説明</title>
-        この関数は直接または逆の1次元またはN次元離散フーリエ変換を
-        行います.
-        <variablelist>
-            <varlistentry>
-                <term>短縮構文 </term>
-                <listitem>
-                    <variablelist>
-                        <varlistentry>
-                            <term>直接</term>
-                            <listitem>
-                                <literal>X=fft(A,-1 [,option])</literal> または
-                                <literal>X=fft(A [,option])</literal>
-                                は直接変換を出力します.
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>単一変量</term>
-                                        <listitem>
-                                            <para>
-                                                <literal>A</literal> が単一変量のベクトルの場合,
-                                                次のように直接FFTが計算されます:
-                                            </para>
-                                            <para>
-                                                <latex>
-                                                    $x(k) = \sum_{m=1}^n
-                                                    {a(m) \exp\left(-2 i\pi\frac{(m-1)}{n} (k-1)\right)}$
-                                                </latex>
-                                            </para>
-                                            <para>
-                                                (引数<literal>-1</literal>は指数の符号を示しており,
-                                                "逆"ではありません),
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>多変量</term>
-                                        <listitem>
-                                            <para>
-                                                <literal>A</literal>が行列または多次元配列の場合,
-                                                多変量直接FFTが行われます.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>逆</term>
-                            <listitem>
-                                <para>
-                                    <literal>X=fft(A,1)</literal>または
-                                    <literal>X=ifft(A)</literal> は,
-                                    <literal>A==ifft(fft(A))</literal>のような
-                                    正規化された逆変換を実行します.
-                                </para>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>単一変量</term>
-                                        <listitem>
-                                            <literal>A</literal> がベクトルの場合,
-                                            単一変量逆FFTが実行されます.
-                                            <para>
-                                                <latex>
-                                                    $x(k) = \sum_{m=1}^n
-                                                    {a(m) \exp\left(+2 i\pi\frac{(m-1)}{n} (k-1)\right)}$
-                                                </latex>
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>多変量</term>
-                                        <listitem>
-                                            <para>
-                                                <literal>A</literal>が行列または多次元配列の場合,
-                                                多変量逆FFTが実行されます.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>多次元FFTの長い構文</term>
-                <listitem>
-                    <itemizedlist>
+        この関数は直接または逆の1次元またはN次元離散フーリエ変換を 行います.
+        <para/>
+        <refsect3>
+            <title>短縮構文</title>
+            <para>
+                <emphasis role="bold">直接</emphasis>
+            </para>
+            <para>
+                <literal>X = fft(A, -1 [,symmetry])</literal> または
+                <literal>X = fft(A [,symmetry])</literal> は直接変換を出力します.
+                <variablelist>
+                    <varlistentry>
+                        <term>単一変量</term>
                         <listitem>
-                            <para>
-                                <literal>X=fft(A,sign,selection [,option])</literal>
-                                により,選択した次元方向の<literal>A</literal>の
-                                "スライス"の直接または逆fftを効率的に実行することができます.
-                            </para>
-                            <para>
-                                例えば,<literal>A</literal> が3次元配列の場合,
-                                <literal>X=fft(A,-1,2)</literal>は以下と等価です:
-                            </para>
-                            <programlisting role=""><![CDATA[
-for i1=1:size(A,1)
-  for i3=1:size(A,3)
-    X(i1,:,i3)=fft(A(i1,:,i3),-1);
-  end
-end
-              ]]></programlisting>
-                            <para>
-                                <literal>X=fft(A,-1,[1 3])</literal>は以下と等価です:
-                            </para>
-                            <programlisting role=""><![CDATA[
-for i2=1:size(A,2)
-  X(:,i2,:)=fft(A(:,i2,:),-1);
-end
-              ]]></programlisting>
+                            <varname>a=A</varname> が単一変量のベクトルの場合,
+                            次のように直接FFTが計算されます:
+                            <para/>
+                            <latex alt="x(k)=∑_m=1…n a(m).exp(-2iπ.(k-1)(m-1)/n)">
+                                x(k) = \sum_{m=1}^n
+                                {a(m) \exp\left(-2 i\pi\frac{(m-1)}{n} (k-1)\right)}
+                            </latex>
+                            <para/>
                         </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                        <term>多変量</term>
                         <listitem>
-                            <para>
-                                前記の構文,
-                                <literal>X=fft(A,sign,dims,incr [,option])</literal> は,
-                                指定した次元方向に <literal>A</literal>のスライスの
-                                直接または逆fftを行うことも可能です.
-                            </para>
-                            <para>
-                                例えば, <literal>A</literal> が
-                                <literal>n1*n2*n3</literal> 個の要素を有する配列の場合,
-                                <literal>X=fft(A,-1,n1,1)</literal> は
-                                <literal>X=fft(matrix(A,[n1,n2,n3]),-1,1)</literal>
-                                と等価です.
-                                また、<literal>X=fft(A,-1,[n1 n3],[1 n1*n2])</literal>
-                                は
-                                <literal>X=fft(matrix(A,[n1,n2,n3]),-1,[1,3])</literal>
-                                と等価です.
-                            </para>
-                        </listitem>
-                    </itemizedlist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>option引数の使用法</term>
-                この引数は<literal>A</literal>またはその"スライス"全体
-                の対称性に関してfftアルゴリズムに情報を提供するために使用できます.
-                次元<literal>n1</literal>, ..., <literal>np</literal>の
-                N次元配列<literal>B</literal> は,
-                <literal>B==conj(B([1 n1:-1:2],[1
-                    n2:-1:2],...,[1 np:-1:2]))
-                </literal>
-                の場合に限り,fftが共役対称です.
-                このような場合,
-                結果<literal>X</literal>は実数で,効率的な専用のアルゴリズムを
-                使用できます.
-                <listitem>
-                    <itemizedlist>
-                        <listitem>
-                            <term>"symmetric"</term> は,
-                            <literal>A</literal>またはその全"スライス"を
-                            共役対称として扱うfftを実行する値です.
-                            このオプションは,
-                            <literal>A</literal> またはその全"スライス" が
-                            丸め誤差の影響で厳密に対称ではない場合に,
-                            自動的な対称性の定義を回避したい場合に有用です.
+                            <varname>A</varname>が行列または多次元配列の場合,
+                            多変量直接FFTが行われます.
+                            <para/>
                         </listitem>
+                    </varlistentry>
+                </variablelist>
+            </para>
+            <para>
+                <emphasis role="bold">逆</emphasis>
+            </para>
+            <para>
+                <literal>X = fft(A, 1)</literal>または <literal>X=ifft(A)</literal> は,
+                <literal>A == ifft(fft(A))</literal>のような 正規化された逆変換を実行します.
+                <variablelist>
+                    <varlistentry>
+                        <term>単一変量</term>
                         <listitem>
-                            <term>"nonsymmetric"</term> は対称性を考慮せずに
-                            fftを実行する値です.
-                            このオプションは自動的な対称性の定義を
-                            回避したい場合に有用です.
+                            <varname>a=A</varname> がベクトルの場合,
+                            単一変量逆FFTが実行されます
+                            <para/>
+                            <latex alt="x(k)=(1/n).∑_m=1…n a(m).exp(+2iπ.(k-1)(m-1)/n)">
+                                $x(k) = \frac{1}{n}\sum_{m=1}^n
+                                {a(m) \exp\left(+2 i\pi\frac{(m-1)}{n} (k-1)\right)}$
+                            </latex>
+                            <para/>
                         </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                        <term>多変量</term>
                         <listitem>
-                            <term>unspecified</term>
-                            このオプションが省略された場合,fftアルゴリズムは
-                            自動的に正しい対称性を確認します.
+                            <varname>A</varname>が行列または多次元配列の場合,
+                            多変量逆FFTが実行されます.
+                            <para/>
                         </listitem>
-                    </itemizedlist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>fftの最適化</term>
-                <listitem>
-                    <para>
-                        注意: fftw 関数は自動的に直近のパラメータをメモリに保存し,
-                        2回目に再利用します.
-                        これにより,(同じパラメータで)連続的なコールを行った場合に
-                        著しく計算時間が改善します.
-                    </para>
-                    <para>
-                        <link linkend="get_fftw_wisdom">get_fftw_wisdom</link>,
-                        <link linkend="set_fftw_wisdom">set_fftw_wisdom</link>関数により
-                        更にfftを最適化することができます.
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>アルゴリズム</title>
-        <para>
-            この関数は,<ulink url="http://www.fftw.org/">fftw3</ulink> ライブラリを
-            使用しています.
-        </para>
+                    </varlistentry>
+                </variablelist>
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>多次元FFTの長い構文</title>
+            <para>
+                <emphasis role="bold">X = fft(A, sign, directions [, symmetry])</emphasis>
+                により,選択した次元方向の<varname>A</varname>の
+                "スライス"の直接または逆fftを効率的に実行することができます.
+            </para>
+            <para>
+                例えば,<varname>A</varname> が3次元配列の場合,
+                <literal>X=fft(A,-1,2)</literal>は以下と等価です:
+                <programlisting role="no-scilab-exec"><![CDATA[
+for i1 = 1:size(A,1)
+    for i3 = 1:size(A,3)
+        X(i1,:,i3) = fft(A(i1,:,i3), -1);
+    end
+end
+            ]]></programlisting>
+            </para>
+            <para>
+                <literal>X = fft(A, -1, [1 3])</literal>は以下と等価です:
+                <programlisting role="no-scilab-exec"><![CDATA[
+for i2 = 1:size(A,2)
+    X(:,i2,:) = fft(A(:,i2,:), -1);
+end
+            ]]></programlisting>
+            </para>
+            <para>
+                前記の構文,
+                <emphasis role="bold">X = fft(A, sign, dims, incr [, symmetry])</emphasis> は,
+                指定した次元方向に <varname>A</varname>のスライスの
+                直接または逆fftを行うことも可能です.
+            </para>
+            <para>
+                例えば, <varname>A</varname> が
+                <literal>n1*n2*n3</literal> 個の要素を有する配列の場合,
+                <literal>X = fft(A,-1,n1,1)</literal> は
+                <literal>X = fft(matrix(A, [n1,n2,n3]), -1, 1)</literal>
+                と等価です.
+                また、<literal>X = fft(A, -1, [n1 n3], [1 n1*n2])</literal>
+                は
+                <literal>X = fft(matrix(A, [n1,n2,n3]), -1, [1,3])</literal>
+                と等価です.
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>fftの最適化</title>
+            <para>
+                <emphasis role="bold">注意</emphasis>:
+                fftw 関数は自動的に直近のパラメータをメモリに保存し,
+                2回目に再利用します.
+                これにより,(同じパラメータで)連続的なコールを行った場合に
+                著しく計算時間が改善します.
+            </para>
+            <para>
+                <link linkend="get_fftw_wisdom">get_fftw_wisdom</link>,
+                <link linkend="set_fftw_wisdom">set_fftw_wisdom</link>関数により
+                更にfftを最適化することができます.
+            </para>
+            <para>
+                <emphasis role="bold">アルゴリズム</emphasis>:
+                この関数は,<ulink url="http://www.fftw.org/">fftw3</ulink> ライブラリを
+                使用しています.
+            </para>
+            <para>
+                <emphasis role="bold">参考文献</emphasis>:
+                Matteo Frigo and Steven G. Johnson, "FFTW Documentation"
+                <ulink url="http://www.fftw.org/#documentation">http://www.fftw.org/#documentation</ulink>
+            </para>
+        </refsect3>
     </refsection>
+
     <refsection>
         <title>例</title>
-        <para>1次元fft</para>
+        <para>1次元FFT</para>
         <programlisting role="example"><![CDATA[
-//Frequency components of a signal
-//----------------------------------
+// Frequency components of a signal
+// --------------------------------
 // build a noised signal sampled at 1000hz  containing  pure frequencies
 // at 50 and 70 Hz
-sample_rate=1000;
+sample_rate = 1000;
 t = 0:1/sample_rate:0.6;
-N=size(t,'*'); //number of samples
-s=sin(2*%pi*50*t)+sin(2*%pi*70*t+%pi/4)+grand(1,N,'nor',0,1);
+N = size(t,'*'); // number of samples
+s = sin(2*%pi*50*t) + sin(2*%pi*70*t+%pi/4) + grand(1,N,'nor',0,1);
 
-y=fft(s);
+y = fft(s);
 
-//s is real so the fft response is conjugate symmetric and we retain only the first N/2 points
-f=sample_rate*(0:(N/2))/N; //associated frequency vector
-n=size(f,'*')
+// s is real so the fft response is conjugate symmetric and we retain only the first N/2 points
+f = sample_rate*(0:(N/2))/N;  // associated frequency vector
+n = size(f,'*')
 clf()
-plot(f,abs(y(1:n)))
+plot(f, abs(y(1:n)))
      ]]></programlisting>
-        <para>2次元fft</para>
+        <para>2次元FFT</para>
         <programlisting role="example"><![CDATA[
 //----------------------------------
 A = zeros(256,256);
 A(5:24,13:17) = 1;
 X = fftshift(fft(A));
-set(gcf(),"color_map",jetcolormap(128));
+set(gcf(), "color_map",jetcolormap(128));
 clf;grayplot(0:255,0:255,abs(X)')
      ]]></programlisting>
-        <para>mupliple fft</para>
+        <para>N-Dimensional FFT:</para>
         <programlisting role="example"><![CDATA[
-//simple case, 3 1-D fft at a time
-N=2048;
-t=linspace(0,10,2048);
-A=[2*sin(2*%pi*3*t)+ sin(2*%pi*3.5*t)
-  10*sin(2*%pi*8*t)
-   sin(2*%pi*0.5*t)+4*sin(2*%pi*0.8*t)];
-X=fft(A,-1,2);
+// simple case, 3 1-D fft at a time
+N = 2048;
+t = linspace(0,10,2048);
+A = [2*sin(2*%pi*3*t)+ sin(2*%pi*3.5*t)
+     10*sin(2*%pi*8*t)
+     sin(2*%pi*0.5*t) + 4*sin(2*%pi*0.8*t)];
+X = fft(A,-1,2);
 
-fs=1/(t(2)-t(1));
-f=fs*(0:(N/2))/N; //associated frequency vector
-clf;plot(f(1:100)',abs(X(:,1:100))')
+fs = 1/(t(2)-t(1));
+f = fs*(0:(N/2))/N; // associated frequency vector
+clf; plot(f(1:100)', abs(X(:,1:100))')
 legend(["3 and 3.5 Hz","8 Hz","0.5 and 0.8 Hz"],"in_upper_left")
 
 // 45  3-D fft at a time
-Dims=[5 4 9 5 6];
-A=matrix(rand(1,prod(Dims)),Dims);
+Dims = [5 4 9 5 6];
+A = matrix(rand(1,prod(Dims)),Dims);
 
-y=fft(A,-1,[2 4 5]);
+y = fft(A,-1,[2 4 5]);
 
-//equivalent (but less efficient code)
-y1=zeros(A);
-for i1=1:Dims(1)
-  for i3=1:Dims(3)
-    ind=list(i1,:,i3,:,:);
-    y1(ind(:))=fft(A(ind(:)),-1);
+// equivalent (but less efficient code)
+y1 = zeros(A);
+for i1 = 1:Dims(1)
+    for i3 = 1:Dims(3)
+        ind = list(i1,:,i3,:,:);
+        y1(ind(:)) = fft(A(ind(:)), -1);
   end
 end
    ]]></programlisting>
         <programlisting role="example"><![CDATA[
-//Using explicit formula for  1-D discrete Fourier transform
-//------------------------------------------------
-function xf=DFT(x,flag);
-  n=size(x,'*');
-  //Compute the n by n Fourier matrix
-  if flag==1 then,//backward transformation
-    am=exp(2*%pi*%i*(0:n-1)'*(0:n-1)/n);
-  else //forward transformation
-    am=exp(-2*%pi*%i*(0:n-1)'*(0:n-1)/n);
-  end
-  xf=am*matrix(x,n,1);//dft
-  xf=matrix(xf,size(x));//reshape
-  if flag==1 then,xf=xf/n;end
+// Using explicit formula for  1-D discrete Fourier transform
+// ----------------------------------------------------------
+function xf = DFT(x, Sign);
+    n = size(x,'*');
+    // Compute the n by n Fourier matrix
+    am = exp(Sign*2*%pi*%i*(0:n-1)'*(0:n-1)/n);
+    xf = am*matrix(x,n,1);//dft
+    xf = matrix(xf ,size(x)); // reshape
+    if Sign==1 then
+        xf = xf/n;
+    end
 endfunction
 
-//Comparison with the fast Fourier algorithm
-a=rand(1,1000);
+// Comparison with the fast Fourier algorithm
+a = rand(1,1000);
 norm(DFT(a,1) - fft(a,1))
 norm(DFT(a,-1) - fft(a,-1))
 
-timer();DFT(a,-1);timer()
-timer();fft(a,-1);timer()
+tic(); DFT(a,-1); toc()
+tic(); fft(a,-1); toc()
      ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -404,10 +370,4 @@ timer();fft(a,-1);timer()
             </member>
         </simplelist>
     </refsection>
-    <refsection>
-        <title>参考文献</title>
-        <para>
-            Matteo Frigo and Steven G. Johnson, "FFTW Documentation" <ulink url="http://www.fftw.org/#documentation">http://www.fftw.org/#documentation</ulink>
-        </para>
-    </refsection>
 </refentry>
diff --git a/scilab/modules/signal_processing/help/ru_RU/transforms/fft.xml b/scilab/modules/signal_processing/help/ru_RU/transforms/fft.xml
new file mode 100644 (file)
index 0000000..1e41ece
--- /dev/null
@@ -0,0 +1,381 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 1997   - INRIA
+ * Copyright (C) 2012 - Serge Steer - INRIA
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:lang="ru" xml:id="fft">
+    <refnamediv>
+        <refname>fft</refname>
+        <refpurpose>
+            прямое или обратное Быстрое Преобразование Фурье вектора, матрицы или гиперматрицы
+        </refpurpose>
+    </refnamediv>
+    <refnamediv xml:id="ifft">
+        <refname>ifft</refname>
+        <refpurpose>обратное быстрое преобразование Фурье</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Синтаксис</title>
+        <synopsis>
+            X = fft(A)
+            X = fft(A, sign)
+            X = fft(A, sign, directions)
+            X = fft(A, sign, dims, incr)
+            X = fft(.., symmetry)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Аргументы</title>
+        <variablelist>
+            <varlistentry>
+                <term>A, X</term>
+                <listitem>
+                    векторы, матрицы или многомерные массивы вещественных или
+                    комплексных чисел одинаковых размеров.
+                    <para/>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>sign</term>
+                <listitem>
+                    -1 или 1 : знак множителя <literal>±2iπ</literal> в экспоненциальном
+                    члене формулы преобразования, устанавливающий прямое или обратное
+                    преобразование. По умолчанию значение равно <literal>-1</literal>,
+                    соответствующее прямому преобразованию.
+                    <para/>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>directions</term>
+                <listitem>
+                    вектор, содержащий индексы размерности <varname>A</varname>
+                    (в <literal>[1, ndims(A)]</literal>) вдоль которой необходимо
+                    вычислить БПФ (многомерный). По умолчанию направления
+                    <varname>directions</varname> соответствуют
+                    <literal>1:ndims(A)</literal>: "кумулятивный" БПФ вычисляется
+                    для всех направлений. См. раздел "Описание".
+                    <para/>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>symmetry</term>
+                <listitem>
+                    необязательная символьная строка, помогающая функции
+                    <literal>fft()</literal> выбрать наилучший алгоритм:
+                    <itemizedlist>
+                        <listitem>
+                            <emphasis role="bold">"symmetric"</emphasis>: заставляет
+                            рассматривать <varname>A</varname> или все её "слои" как
+                            симметрично сопряжённую. Это полезно, когда точная симметрия
+                            <varname>A</varname> или её "слоёв" возможно чередуется только
+                            из-за ошибок округления.
+                            <para/>
+                            Многомерный массив <varname>B</varname> размерами
+                            <literal>[s1,s2,..,sN]</literal> сопряжённо симметричный
+                            для БПФ, если и только если
+                            <literal>B==conj(B([1 s1:-1:2],[1 s2:-1:2],...,[1 sN:-1:2]))</literal>.
+                            В этом случае результат <varname>X</varname> является
+                            вещественным и может использоваться эффективный специфический
+                            алгоритм для его вычисления.
+                            <para/>
+                        </listitem>
+                        <listitem>
+                            <emphasis role="bold">"nonsymmetric"</emphasis>: Тогда
+                            <literal>fft()</literal> не обращает внимание ни на
+                            какую симметрию.
+                            <para/>
+                        </listitem>
+                        <listitem>
+                            не указано: тогда выполняется автоматическое определение симметрии.
+                            <para/>
+                        </listitem>
+                    </itemizedlist>
+                </listitem>
+                <para/>
+            </varlistentry>
+            <varlistentry>
+                <term>dims</term>
+                <listitem>
+                    вектор положительных целых чисел. Старый синтаксис.
+                    Каждый элемент должен быть делителем <literal>length(A)</literal>.
+                    Произведение элементов должно быть строго меньше
+                    <literal>length(A)</literal>. См. подробности в разделе "Описание".
+                    <para/>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>incr</term>
+                <listitem>
+                    вектор положительных строго возрастающих целых чисел, такой же
+                    длины, что и <varname>dims</varname>. Старый синтаксис.
+                    Каждый элемент должен быть делителем <literal>length(A)</literal>.
+                    См. подробности в разделе "Описание".
+                    <para/>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Описание</title>
+        <para>
+            Эта функция вычисляет прямое или обратное одно-, дву- или многомерное
+            дискретное преобразование Фурье массива или многомерного массива чисел
+            вдоль одного или нескольких направлений внутри этого массива.
+        </para>
+        <para/>
+        <refsect3>
+            <title>Краткий синтаксис</title>
+            <para>
+                <emphasis role="bold">Прямое преобразование</emphasis>:
+            </para>
+            <para>
+                <literal>X = fft(A [,symmetry])</literal> или
+                <literal>X = fft(A, -1 [,symmetry])</literal> выполняет прямое
+                преобразование.
+                <variablelist>
+                    <varlistentry>
+                        <term>одномерное</term>
+                        <listitem>
+                            <varname>a=A</varname> является вектором: вычисляется
+                            одномерное прямое БПФ, так что:
+                            <para/>
+                            <latex alt="x(k)=∑_m=1…n a(m).exp(-2iπ.(k-1)(m-1)/n)">
+                                x(k) = \sum_{m=1}^n
+                                {a(m) \exp\left(-2 i\pi\frac{(m-1)}{n} (k-1)\right)}
+                            </latex>
+                            <para/>
+                        </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                        <term>многомерное</term>
+                        <listitem>
+                            <varname>A</varname> является матрицей или многомерным
+                            массивом: выполняется многомерное прямое БПФ.
+                            <para/>
+                        </listitem>
+                    </varlistentry>
+                </variablelist>
+            </para>
+            <para>
+                <emphasis role="bold">Обратное нормированное преобразование</emphasis>:
+            </para>
+            <para>
+                <literal>X = fft(A,+1)</literal> или <literal>X = ifft(A)</literal>
+                выполняет обратное нормированное преобразование, такое, что
+                <literal>A==ifft(fft(A))</literal>.
+                <variablelist>
+                    <varlistentry>
+                        <term>одномерное</term>
+                        <listitem>
+                            <literal>a=A</literal> является вектором:
+                            <literal>X = fft(a, +1)</literal> или <literal>X = ifft(a)</literal>
+                            выполняют одномерное обратное БПФ, вычисляемое как:
+                            <para/>
+                            <latex alt="x(k)=(1/n).∑_m=1…n a(m).exp(+2iπ.(k-1)(m-1)/n)">
+                                $x(k) = \frac{1}{n}\sum_{m=1}^n
+                                {a(m) \exp\left(+2 i\pi\frac{(m-1)}{n} (k-1)\right)}$
+                            </latex>
+                            <para/>
+                        </listitem>
+                    </varlistentry>
+                    <varlistentry>
+                        <term>многомерное</term>
+                        <listitem>
+                            <varname>A</varname> является матрицей или многомерным массивом:
+                            выполняется многомерное обратное БПФ.
+                            <para/>
+                        </listitem>
+                    </varlistentry>
+                </variablelist>
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Длинный синтаксис: многомерное прямое БПФ</title>
+            <para>
+                <emphasis role="bold">X = fft(A, sign, directions [, symmetry])</emphasis>
+                выполняет эффективно все прямые или обратные БПФ по всем "слоям"
+                <varname>A</varname> вдоль выбранных направлений <varname>directions</varname>.
+            </para>
+            <para>
+                Например, если <varname>A</varname> является трёхмерным массивом, то
+                <literal>X = fft(A,-1,2)</literal> эквивалентно:
+                <programlisting role="no-scilab-exec"><![CDATA[
+for i1 = 1:size(A,1)
+    for i3 = 1:size(A,3)
+        X(i1,:,i3) = fft(A(i1,:,i3), -1);
+    end
+end
+             ]]></programlisting>
+            </para>
+            <para>
+                и <literal>X = fft(A,-1,[1 3])</literal> эквивалентно:
+                <programlisting role="no-scilab-exec"><![CDATA[
+for i2 = 1:size(A,2)
+    X(:,i2,:) = fft(A(:,i2,:), -1);
+end
+             ]]></programlisting>
+            </para>
+            <para>
+                <emphasis role="bold">X = fft(A, sign, dims, incr [, symmetry])</emphasis>
+                является старым синтаксисом, который также позволяет выполнять все
+                прямые или обратные БПФ слоёв <varname>A</varname> вдоль выбранных
+                направлений <varname>directions</varname>. С этим синтаксисом
+                <varname>A</varname> рассматривается как сериализованная в вектор, и
+                её фактические размеры игнорируются. Слои выбираются указанием
+                размеров <varname>A</varname> и инкрементов сериализованного индекса,
+                относящегося к размерам.
+            </para>
+            <para>
+                Например, если <varname>A</varname> является массивом с
+                <literal>n1*n2*n3</literal> элементов,
+                <literal>X = fft(A,-1, n1, 1)</literal> эквивалентно
+                <literal>X = fft(matrix(A,[n1,n2,n3]), -1, 1)</literal> ;
+                а <literal>X = fft(A,-1, [n1 n3], [1 n1*n2])</literal>
+                эквивалентно
+                <literal>X = fft(matrix(A,[n1,n2,n3]), -1, [1,3])</literal>.
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Оптимизация fft</title>
+            <para>
+                <emphasis role="bold">Примечание</emphasis>:
+                Функция <literal>fft()</literal> автоматически сохраняет свои последние
+                внутренние параметры в памяти для повторного их использования во
+                второй раз. Это значительно улучшает время вычисления, когда
+                выполняются последовательные вызовы (с одинаковыми параметрами).
+            </para>
+            <para>
+                Можно пойти дальше в оптимизации <literal>fft()</literal>, используя
+                функции
+                <link linkend="get_fftw_wisdom">get_fftw_wisdom</link> и
+                <link linkend="set_fftw_wisdom">set_fftw_wisdom</link>.
+            </para>
+            <para>
+                <emphasis role="bold">Алгоритмы</emphasis>:
+                <literal>fft()</literal> использует библиотеку
+                <ulink url="http://www.fftw.org/">fftw3</ulink>.
+            </para>
+            <para>
+                <emphasis role="bold">Библиография</emphasis>:
+                Matteo Frigo and Steven G. Johnson, "FFTW Documentation"
+                <ulink url="http://www.fftw.org/#documentation">http://www.fftw.org/#documentation</ulink>
+            </para>
+        </refsect3>
+    </refsection>
+    <refsection>
+        <title>Примеры</title>
+        <para>Одномерное БПФ (вектора):</para>
+        <programlisting role="example"><![CDATA[
+// Частотные составляющие сигнала
+//-------------------------------
+// построение зашумлённого сигнала оцифрованного с частотой 1000 Гц, содержащего чистые
+// гармоники на 50 и 70 Гц
+sample_rate = 1000;
+t = 0:1/sample_rate:0.6;
+N = size(t,'*'); //количество отсчётов
+s = sin(2*%pi*50*t) + sin(2*%pi*70*t+%pi/4) + grand(1,N,'nor',0,1);
+
+y=fft(s);
+
+// s является вещественным и результат БПФ является сопряжённо симметричным и мы
+// оставляем только первые N/2 точек
+f = sample_rate*(0:(N/2))/N; //вектор связанных частот
+n = size(f,'*')
+clf()
+plot(f, abs(y(1:n)))
+     ]]></programlisting>
+        <para>2D FFT (of a matrix):</para>
+        <programlisting role="example"><![CDATA[
+A = zeros(256,256);
+A(5:24,13:17) = 1;
+X = fftshift(fft(A));
+set(gcf(), "color_map",jetcolormap(128));
+clf; grayplot(0:255, 0:255, abs(X)')
+     ]]></programlisting>
+        <para>N-мерный БПФ (многомерного массива):</para>
+        <programlisting role="example"><![CDATA[
+// простой случай, 3 одномерных БПФ во времени
+N = 2048;
+t = linspace(0,10,2048);
+A = [2*sin(2*%pi*3*t) + sin(2*%pi*3.5*t)
+     10*sin(2*%pi*8*t)
+     sin(2*%pi*0.5*t) + 4*sin(2*%pi*0.8*t)];
+X = fft(A,-1,2);
+
+fs = 1/(t(2)-t(1));
+f = fs*(0:(N/2))/N; // вектор связанных частот
+clf; plot(f(1:100)',abs(X(:,1:100))')
+legend(["3 и 3,5 Гц","8 Гц","0,5 и 0,8 Гц"],"in_upper_left")
+
+// 45 трёхмерных БПФ во времени
+Dims = [5 4 9 5 6];
+A = matrix(rand(1, prod(Dims)), Dims);
+
+y = fft(A,-1,[2 4 5]);
+
+// эквивалентный (но менее эффективный) код
+y1 = zeros(A);
+for i1 = 1:Dims(1)
+    for i3 = 1:Dims(3)
+        ind = list(i1,:,i3,:,:);
+        y1(ind(:)) = fft(A(ind(:)),-1);
+  end
+end
+     ]]></programlisting>
+        <programlisting role="example"><![CDATA[
+// Использование явной формулы одномерного дискретного преобразования Фурье
+// ------------------------------------------------------------------------
+function xf = DFT(x, Sign);
+    n = size(x,'*');
+    // вычисление матрицы Фурье размером n на n
+    am = exp(Sign * 2*%pi*%i * (0:n-1)'*(0:n-1)/n);
+    xf = am * matrix(x,n,1);  // ДПФ
+    xf = matrix(xf,size(x));  // изменение размерности
+    if Sign == 1 then
+        xf = xf/n;
+    end
+endfunction
+
+// Сравнение с алгоритмом БПФ
+a = rand(1,1000);
+norm(DFT(a,1) - fft(a,1))
+norm(DFT(a,-1) - fft(a,-1))
+
+tic(); DFT(a,-1); toc()
+tic(); fft(a,-1); toc()
+     ]]></programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>Смотрите также</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="corr">corr</link>
+            </member>
+            <member>
+                <link linkend="fftw_flags">fftw_flags</link>
+            </member>
+            <member>
+                <link linkend="get_fftw_wisdom">get_fftw_wisdom</link>
+            </member>
+            <member>
+                <link linkend="set_fftw_wisdom">set_fftw_wisdom</link>
+            </member>
+            <member>
+                <link linkend="fftw_forget_wisdom">fftw_forget_wisdom</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>