* Get ride of the useless tag
[scilab.git] / scilab / modules / signal_processing / help / en_US / filters / convol.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="convol" xml:lang="en">
3     <refnamediv>
4         <refname>convol</refname>
5         <refpurpose>convolution</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Calling Sequence</title>
9         <synopsis>
10             [y]=convol(h,x)
11             [y,e1]=convol(h,x,e0)
12         </synopsis>
13     </refsynopsisdiv>
14     <refsection>
15         <title>Arguments</title>
16         <variablelist>
17             <varlistentry>
18                 <term>h</term>
19                 <listitem>
20                     <para>a vector, first input sequence ("short" one) </para>
21                 </listitem>
22             </varlistentry>
23             <varlistentry>
24                 <term>x</term>
25                 <listitem>
26                     <para>a vector, second input sequence ( "long" one)</para>
27                 </listitem>
28             </varlistentry>
29             <varlistentry>
30                 <term>e0</term>
31                 <listitem>
32                     <para>a vector,old tail to overlap add (not used in first
33                         call)
34                     </para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>y</term>
39                 <listitem>
40                     <para>a vector, the convolution. </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>e1</term>
45                 <listitem>
46                     <para>new tail to overlap add (not used in last call)</para>
47                 </listitem>
48             </varlistentry>
49         </variablelist>
50     </refsection>
51     <refsection>
52         <title>Description</title>
53         <para>
54             Calculates the convolution <literal>y= h*x</literal> of two discrete
55             sequences by using the fft. The convolution is defined as follow:
56         </para>
57         <para>
58             <inlinemediaobject>
59                 <imageobject>
60                     <imagedata>
61                         <math:math xmlns:math="http://www.w3.org/1998/Math/MathML">
62                             <math:semantics>
63                                 <math:mrow>
64                                     <math:msub>
65                                         <math:mi>y</math:mi>
66                                         <math:mi>k</math:mi>
67                                     </math:msub>
68                                     <math:mo math:stretchy="false">=</math:mo>
69                                     <math:mrow>
70                                         <math:mrow>
71                                             <math:msub>
72                                                 <math:mo math:stretchy="false">∑</math:mo>
73                                                 <math:mi>j</math:mi>
74                                             </math:msub>
75                                             <math:msub>
76                                                 <math:mi>h</math:mi>
77                                                 <math:mi>j</math:mi>
78                                             </math:msub>
79                                         </math:mrow>
80                                         <math:mo math:stretchy="false">∗</math:mo>
81                                         <math:msub>
82                                             <math:mi>x</math:mi>
83                                             <math:mrow>
84                                                 <math:mrow>
85                                                     <math:mi>k</math:mi>
86                                                     <math:mo math:stretchy="false">+</math:mo>
87                                                     <math:mn>1</math:mn>
88                                                 </math:mrow>
89                                                 <math:mo math:stretchy="false">−</math:mo>
90                                                 <math:mi>j</math:mi>
91                                             </math:mrow>
92                                         </math:msub>
93                                     </math:mrow>
94                                 </math:mrow>
95                                 <math:annotation math:encoding="StarMath 5.0">y_k=sum_j h_j*x_{k+1-j}
96                                 </math:annotation>
97                             </math:semantics>
98                         </math:math>
99                     </imagedata>
100                 </imageobject>
101             </inlinemediaobject>
102         </para>
103         <para>Overlap add method can be used.</para>
104         <para>USE OF OVERLAP ADD METHOD: For
105             <literal>x=[x1,x2,...,xNm1,xN]</literal> First call is
106             <literal>[y1,e1]=convol(h,x1);</literal> Subsequent calls :
107             <literal>[yk,ek]=convol(h,xk,ekm1)</literal>; Final call :
108             <literal>[yN]=convol(h,xN,eNm1);</literal> Finally
109             <literal>y=[y1,y2,...,yNm1,yN]</literal>.
110         </para>
111         <para>The algorithm based on the convolution definition is
112             implemented for polynomial
113             product: <literal>y=convol(h,x)</literal> is equivalent
114             to <literal>y=coeff(poly(h,'z','c')*poly(x,'z','c')</literal> but
115             much more efficient if <literal>x</literal> is a "long" array.
116         </para>
117     </refsection>
118     <refsection>
119         <title>Examples</title>
120         <programlisting role="example"><![CDATA[ 
121 x=1:3;
122 h1=[1,0,0,0,0];h2=[0,1,0,0,0];h3=[0,0,1,0,0];
123 x1=convol(h1,x),x2=convol(h2,x),x3=convol(h3,x),
124 convol(h1+h2+h3,x)
125 p1=poly(x,'x','coeff')
126 p2=poly(h1+h2+h3,'x','coeff')
127 p1*p2
128  ]]></programlisting>
129     </refsection>
130     <refsection role="see also">
131         <title>See Also</title>
132         <simplelist type="inline">
133             <member>
134                 <link linkend="corr">corr</link>
135             </member>
136             <member>
137                 <link linkend="fft">fft</link>
138             </member>
139             <member>
140                 <link linkend="pspect">pspect</link>
141             </member>
142         </simplelist>
143     </refsection>
144 </refentry>