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>