Indent all the XML files to the same way
[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>