<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2014, 2019 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
          xmlns:scilab="http://www.scilab.org" xml:id="kron" xml:lang="en">
    <refnamediv>
        <refname>kron .*.</refname>
        <refpurpose>Kronecker tensorial product. Weighted array replication</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            P = kron(A, B)
            P = A .*. B
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>A, B</term>
                <listitem>
                    <para>
                        Arrays of size (a1, a2, ..) and (b1, b2, ..), with any number of dimensions.
                        If <varname>A</varname> or <varname>B</varname> is sparse, the other one
                        can't be an hypermatrix.
                    </para>
                    <para>
                        Supported encodings and types: integer, real, complex, polynomial, rational,
                        sparse.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>P</term>
                <listitem>
                    <para>
                        Array of <varname>A</varname> and <varname>B</varname> data type,
                        and of size (a1*b1, a2*b2, ..).
                        If <varname>A</varname> or <varname>B</varname> is sparse,
                        <varname>P</varname> is sparse.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>kron(A,B)</literal> or <literal>A .*. B</literal> returns the
            Kronecker tensor product of two matrices or hypermatrices<literal>A</literal> and
            <literal>B</literal>. The resulting matrix has the following block
            form:
            <latex style="display" alt="
          [ A(1,1).B  ..  A(1,n).B ] \n
A .✶. B = |   ⋮        ⋮     ⋮      | \n
          [ A(m,1).B  ..  A(m,n).B ]">
                A \; .*.\; B = \begin{pmatrix}
                    A_{1,1}\cdot B &amp; \cdots &amp; A_{1,n}\cdot B  \\
                          \vdots   &amp;        &amp;        \vdots   \\
                    A_{m,1}\cdot B &amp; \cdots &amp; A_{m,n}\cdot B
                    \end{pmatrix}
            </latex>
        </para>
        <para>
            If <literal>A</literal> is a <literal>m x n</literal> matrix and
            <literal>B</literal> a <literal>p x q x r</literal> hypermatrix then
            <literal>A.*.B</literal> is a <literal>(m*p) x (n*q) x (1*r)</literal>
            hypermatrix.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
A = [1 3 ; 2 4]
B = [1 10 100]
kron(A, B)
A .*. B
B .*. A
    ]]></programlisting>
    <screen><![CDATA[
--> A = [1 3 ; 2 4]
 A  =
   1.   3.
   2.   4.

--> B = [1 10 100]
 B  =
   1.   10.   100.

--> kron(A, B)
 ans  =
   1.   10.   100.   3.   30.   300.
   2.   20.   200.   4.   40.   400.

--> A .*. B
 ans  =
   1.   10.   100.   3.   30.   300.
   2.   20.   200.   4.   40.   400.

--> B .*. A
 ans  =
   1.   3.   10.   30.   100.   300.
   2.   4.   20.   40.   200.   400.
]]></screen>
        <para>With sparse matrices:</para>
        <programlisting role="example"><![CDATA[
P = [-1 0 1 10] .*. sparse([0 1 2])
full(P)
    ]]></programlisting>
    <screen><![CDATA[
--> P = [-1 0 1 10] .*. sparse([0 1 2])
 P  =
(  1,  12) sparse matrix
(  1,  2)    -1.
(  1,  3)    -2.
(  1,  8)     1.
(  1,  9)     2.
(  1,  11)    10.
(  1,  12)    20.

--> full(P)
 ans  =
   0.  -1.  -2.   0.   0.   0.   0.   1.   2.   0.   10.   20.
]]></screen>
        <para>With complex numbers:</para>
        <programlisting role="example"><![CDATA[
A = [-1 1 ; -%i %i]
A .*. A
    ]]></programlisting>
    <screen><![CDATA[
--> A = [-1 1 ; -%i %i]
 A  =
  -1.     1.
  -i      i

--> A .*. A
 ans  =
   1.    -1.    -1.     1.
   i     -i     -i      i
   i     -i     -i      i
  -1.     1.     1.    -1.
]]></screen>
        <para>
            With hypermatrices:
        </para>
        <programlisting role="example"><![CDATA[
b = matrix(1:24, [4 3 2]);

// row .*. hypermat
a = 1:2, b
a.*.b

// hypermat .*. row
b,a
b .*. a

// column .*. hypermat
a = [1;2], b
a.*.b

// matrix .*. hypermat
a = [-1 -2; 2 1], b
a.*.b

// hypermat .*. hypermat
a = matrix([-1,-2, 1 2], [1 2 2]), b
a.*.b
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See Also</title>
        <simplelist type="inline">
            <member>
                <link linkend="krondivide">kron .\. ./.</link>
            </member>
            <member>
                <link linkend="star">star</link>
            </member>
            <member>
                <link linkend="prod">prod</link>
            </member>
            <member>
                <link linkend="cumprod">cumprod</link>
            </member>
            <member>
                <link linkend="repmat">repmat</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.5.1</revnumber>
                <revdescription>
                    <para>Extension to hypermatrices</para>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
