Get ride of the useless pubdate tag.
[scilab.git] / scilab / modules / signal_processing / help / en_US / conv.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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:lang="en_US" xml:id="conv">
3   <refnamediv>
4     <refname>conv</refname>
5     <refpurpose>discrete 1-D convolution. </refpurpose>
6   </refnamediv>
7   <refsynopsisdiv>
8     <title>Calling Sequence</title>
9     <synopsis>C = conv(A,B [,shape])</synopsis>
10   </refsynopsisdiv>
11   <refsection>
12     <title>Parameters</title>
13     <variablelist>
14       <varlistentry>
15         <term>A</term>
16         <listitem>
17           <para>
18             a real or complex vector.
19           </para>
20         </listitem>
21       </varlistentry>
22       <varlistentry>
23         <term>B</term>
24         <listitem>
25           <para>
26             a real or complex vector.
27           </para>
28         </listitem>
29       </varlistentry>
30       <varlistentry>
31         <term>shape</term>
32         <listitem>
33           <para>
34             an optional character string with possible values:
35           </para>
36           <itemizedlist>
37             <listitem>
38               <literal>"full"</literal>, <literal>conv</literal>
39               computes the full convolution. It is the
40               default value.
41             </listitem>
42             <listitem>
43               <literal>"same"</literal>, <literal>conv</literal>
44               computes the central part of the convolution of the same
45               size as <literal>A</literal>.
46             </listitem>
47             <listitem>
48               <literal>"valid"</literal>, <literal>conv</literal>
49               computes the convolution parts without the zero-padding
50               of <literal>A</literal>.
51             </listitem>
52           </itemizedlist>
53         </listitem>
54       </varlistentry>
55       <varlistentry>
56         <term>C</term>
57         <listitem>
58           <para>
59             a real or complex vector.
60           </para>
61         </listitem>
62       </varlistentry>
63     </variablelist>
64   </refsection>
65   <refsection>
66     <title>Description</title>
67     <para>
68       <literal>conv</literal> uses a straightforward formal
69       implementation of the one-dimensional convolution equation in
70       spatial form.
71     </para>
72     <para>
73       <literal>C=conv(A,B [,shape])</literal> computes the
74       one-dimensional convolution of the vectors <literal>A</literal>
75       and <literal>B</literal>:
76     </para>
77     <itemizedlist>
78       <listitem>
79         With <literal>shape=="full"</literal> the
80         dimensions of the result<literal>C</literal> are given by
81         <literal>size(A,'*')+size(B,'*')+1</literal>. The indices of the
82         center element of <literal>B</literal> are defined as
83         <literal>floor((size(B,'*')+1)/2)</literal>.
84       </listitem>
85       <listitem>
86         With <literal>shape=="same"</literal> the
87         dimensions of the result<literal>C</literal> are given by
88         <literal>size(A)</literal>. The indices of the
89         center element of <literal>B</literal> are defined as
90         <literal>floor((size(B,'*')+1)/2)</literal>.
91       </listitem>
92       <listitem>
93         With <literal>shape=="valid"</literal> the dimensions
94         of the result <literal>C</literal> are given by
95         <literal>size(A,'*')-size(B,'*')+1)</literal> if
96         <literal>and(size(A,'*')-size(B,'*'))&gt;=0</literal> else
97         <literal>C</literal> is empty . The indices of the center
98         element of <literal>B</literal> are defined as
99         <literal>1</literal>.
100       </listitem>
101     </itemizedlist>
102     <para>
103       Note that <link linkend="convol">convol</link> can be more efficient for large arrays.
104     </para>
105   </refsection>
106   <refsection>
107     <title>Examples</title>
108     <programlisting role="example"><![CDATA[
109         A=1:10;
110         B=[1 -1];
111         conv(A,B)
112     ]]></programlisting>
113   </refsection>
114   <refsection>
115     <title>See Also</title>
116     <simplelist type="inline">
117       <member>
118         <link linkend="convol">convol</link>
119       </member>
120       <member>
121         <link linkend="conv2">conv2</link>
122       </member>
123     </simplelist>
124   </refsection>
125   <refsection>
126     <title>Used Functions</title>
127     <para>
128       The conv function is based on the  <link linkend="conv2">conv2</link> builtin.
129     </para>
130   </refsection>
131   <refsection>
132     <title>History</title>
133     <revhistory>
134       <revision>
135         <revnumber>5.4.0</revnumber>
136         <revremark>Function conv introduced.</revremark>
137       </revision>
138     </revhistory>
139   </refsection>
140 </refentry>