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