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