89baff46f452bd5cbce2952f99ba1657db4f6848
[scilab.git] / scilab / modules / elementary_functions / help / en_US / matrixoperations / kron.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2014, 2019 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org" xml:id="kron" xml:lang="en">
20     <refnamediv>
21         <refname>kron .*.</refname>
22         <refpurpose>Kronecker tensorial product. Weighted array replication</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             P = kron(A, B)
28             P = A .*. B
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>A, B</term>
36                 <listitem>
37                     <para>
38                         Arrays of size (a1, a2, ..) and (b1, b2, ..), with any number of dimensions.
39                         If <varname>A</varname> or <varname>B</varname> is sparse, the other one
40                         can't be an hypermatrix.
41                     </para>
42                     <para>
43                         Supported encodings and types: integer, real, complex, polynomial, rational,
44                         sparse.
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>P</term>
50                 <listitem>
51                     <para>
52                         Array of <varname>A</varname> and <varname>B</varname> data type,
53                         and of size (a1*b1, a2*b2, ..).
54                         If <varname>A</varname> or <varname>B</varname> is sparse,
55                         <varname>P</varname> is sparse.
56                     </para>
57                 </listitem>
58             </varlistentry>
59         </variablelist>
60     </refsection>
61     <refsection>
62         <title>Description</title>
63         <para>
64             <literal>kron(A,B)</literal> or <literal>A .*. B</literal> returns the
65             Kronecker tensor product of two matrices or hypermatrices<literal>A</literal> and
66             <literal>B</literal>. The resulting matrix has the following block
67             form:
68             <latex style="display" alt="
69           [ A(1,1).B  ..  A(1,n).B ] \n
70 A .✶. B = |   ⋮        ⋮     ⋮      | \n
71           [ A(m,1).B  ..  A(m,n).B ]">
72                 A \; .*.\; B = \begin{pmatrix}
73                     A_{1,1}\cdot B &amp; \cdots &amp; A_{1,n}\cdot B  \\
74                           \vdots   &amp;        &amp;        \vdots   \\
75                     A_{m,1}\cdot B &amp; \cdots &amp; A_{m,n}\cdot B
76                     \end{pmatrix}
77             </latex>
78         </para>
79         <para>
80             If <literal>A</literal> is a <literal>m x n</literal> matrix and
81             <literal>B</literal> a <literal>p x q x r</literal> hypermatrix then
82             <literal>A.*.B</literal> is a <literal>(m*p) x (n*q) x (1*r)</literal>
83             hypermatrix.
84         </para>
85     </refsection>
86     <refsection>
87         <title>Examples</title>
88         <programlisting role="example"><![CDATA[
89 A = [1 3 ; 2 4]
90 B = [1 10 100]
91 kron(A, B)
92 A .*. B
93 B .*. A
94     ]]></programlisting>
95     <screen><![CDATA[
96 --> A = [1 3 ; 2 4]
97  A  =
98    1.   3.
99    2.   4.
100
101 --> B = [1 10 100]
102  B  =
103    1.   10.   100.
104
105 --> kron(A, B)
106  ans  =
107    1.   10.   100.   3.   30.   300.
108    2.   20.   200.   4.   40.   400.
109
110 --> A .*. B
111  ans  =
112    1.   10.   100.   3.   30.   300.
113    2.   20.   200.   4.   40.   400.
114
115 --> B .*. A
116  ans  =
117    1.   3.   10.   30.   100.   300.
118    2.   4.   20.   40.   200.   400.
119 ]]></screen>
120         <para>With sparse matrices:</para>
121         <programlisting role="example"><![CDATA[
122 P = [-1 0 1 10] .*. sparse([0 1 2])
123 full(P)
124     ]]></programlisting>
125     <screen><![CDATA[
126 --> P = [-1 0 1 10] .*. sparse([0 1 2])
127  P  =
128 (  1,  12) sparse matrix
129 (  1,  2)    -1.
130 (  1,  3)    -2.
131 (  1,  8)     1.
132 (  1,  9)     2.
133 (  1,  11)    10.
134 (  1,  12)    20.
135
136 --> full(P)
137  ans  =
138    0.  -1.  -2.   0.   0.   0.   0.   1.   2.   0.   10.   20.
139 ]]></screen>
140         <para>With complex numbers:</para>
141         <programlisting role="example"><![CDATA[
142 A = [-1 1 ; -%i %i]
143 A .*. A
144     ]]></programlisting>
145     <screen><![CDATA[
146 --> A = [-1 1 ; -%i %i]
147  A  =
148   -1.     1.
149   -i      i
150
151 --> A .*. A
152  ans  =
153    1.    -1.    -1.     1.
154    i     -i     -i      i
155    i     -i     -i      i
156   -1.     1.     1.    -1.
157 ]]></screen>
158         <para>
159             With hypermatrices:
160         </para>
161         <programlisting role="example"><![CDATA[
162 b = matrix(1:24, [4 3 2]);
163
164 // row .*. hypermat
165 a = 1:2, b
166 a.*.b
167
168 // hypermat .*. row
169 b,a
170 b .*. a
171
172 // column .*. hypermat
173 a = [1;2], b
174 a.*.b
175
176 // matrix .*. hypermat
177 a = [-1 -2; 2 1], b
178 a.*.b
179
180 // hypermat .*. hypermat
181 a = matrix([-1,-2, 1 2], [1 2 2]), b
182 a.*.b
183  ]]></programlisting>
184     </refsection>
185     <refsection role="see also">
186         <title>See Also</title>
187         <simplelist type="inline">
188             <member>
189                 <link linkend="krondivide">kron .\. ./.</link>
190             </member>
191             <member>
192                 <link linkend="star">star</link>
193             </member>
194             <member>
195                 <link linkend="prod">prod</link>
196             </member>
197             <member>
198                 <link linkend="cumprod">cumprod</link>
199             </member>
200             <member>
201                 <link linkend="repmat">repmat</link>
202             </member>
203         </simplelist>
204     </refsection>
205     <refsection>
206         <title>History</title>
207         <revhistory>
208             <revision>
209                 <revnumber>5.5.1</revnumber>
210                 <revdescription>
211                     <para>Extension to hypermatrices</para>
212                 </revdescription>
213             </revision>
214         </revhistory>
215     </refsection>
216 </refentry>