<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 *
 * Copyright (C) 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="krondivide" xml:lang="en">
    <refnamediv>
        <refname>kron .\. ./.</refname>
        <refpurpose>Kronecker left and right divisions</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            X = A .\. B       // while B = A .*. X
            X = B ./. A       // while B = X .*. A
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>X</term>
                <listitem>
                    Array of decimal or complex numbers, of size (x1,x2,..).
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>A</term>
                <listitem>
                    Array of decimal or complex numbers, of size (a1,a2,..), with any number
                    of dimensions.
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>B</term>
                <listitem>
                    Array of decimal or complex numbers, of size (a1*x1, a2*x2,..), with any number
                    of dimensions.
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <emphasis role="bold">B ./. A</emphasis> computes and provides the array
            <varname>X</varname> such that <literal>B = X .*. A</literal>.
        </para>
        <para>
            <emphasis role="bold">A .\. B</emphasis> computes and provides the array
            <varname>X</varname> such that <literal>B = A .*. X</literal>.
        </para>
        <para>
            In both cases, each <varname>X</varname> coefficient is constrained by length(A)
            proportional equations. The divisions are so performed in a least-square way
            minimizing <literal>norm(A.*.X - B, 2)</literal> or <literal>norm(X.*.A - B, 2)</literal>.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>
            Simple example with low and crossed dimensions:
        </para>
        <programlisting role="example"><![CDATA[
A = 0:3
B = [1 10 100]'
P = A .*. B
 ]]></programlisting>
    <screen><![CDATA[
--> A = 0:3
 A  =
   0.   1.   2.   3.

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

--> P = A .*. B
 P  =
   0.   1.     2.     3.
   0.   10.    20.    30.
   0.   100.   200.   300.

--> P ./. B
 ans  =
   0.   1.   2.   3.

--> A .\. P
 ans  =
   1.
   10.
   100.
]]></screen>
        <para>
            Still with some low dimensions, and with noisy data:
        </para>
        <programlisting role="example"><![CDATA[
A = 1:3
B = 0:4
P = A .*. B
P ./. B
A .\. P

// Let's add some additive noise, and process noisy data:
P = P + grand(P, "unf", -0.3, 0.3)
P ./. B
A .\. P
 ]]></programlisting>
    <screen><![CDATA[
--> A = 1:3
 A  =
   1.   2.   3.

--> B = 0:4
 B  =
   0.   1.   2.   3.   4.

--> P = A .*. B
 P  =
   0.  1.  2.  3.  4.  0.  2.  4.  6.  8.  0.  3.  6.  9.  12.

--> P ./. B
 ans  =
   1.   2.   3.

--> A .\. P
 ans  =
   0.   1.   2.   3.   4.


--> // Let's add some additive noise, and process noisy data:
--> P = P + grand(P, "unf", -0.3, 0.3)
 P  =
         column 1 to 8
  -0.2793324   1.0981633   1.9632466   2.775538   3.9289351  -0.1738746   2.1593101   3.7307299

         column 9 to 15
   6.1771199   7.7218648  -0.1878764   2.9452387   5.9938586   8.9747935   11.967352

--> P ./. B
 ans  =
   0.9689004   1.9679863   2.9908914

--> A .\. P
 ans  =
  -0.0850508   1.0180357   1.9575916   3.0038685   3.9481943
]]></screen>
        <para>
            With hypermatrices:
        </para>
        <programlisting role="example"><![CDATA[
M = [-9.4  -7.    8.6  -2.3
      0.1  -3.   -0.4  -0.7
     -6.9  -5.3   3.6  -6.6 ];
H = cat(3,-2,3)
P = M .*. H
P ./. H
M .\. P
 ]]></programlisting>
    <screen><![CDATA[
 M  =
  -9.4  -7.    8.6  -2.3
   0.1  -3.   -0.4  -0.7
  -6.9  -5.3   3.6  -6.6

--> H = cat(3,-2,3)
 H  =
(:,:,1)
  -2.
(:,:,2)
   3.

--> P = M .*. H
 P  =
(:,:,1)
   18.8   14.   -17.2   4.6
  -0.2    6.     0.8    1.4
   13.8   10.6  -7.2    13.2

(:,:,2)
  -28.2  -21.    25.8  -6.9
   0.3   -9.    -1.2   -2.1
  -20.7  -15.9   10.8  -19.8

--> P ./. H
 ans  =
  -9.4  -7.    8.6  -2.3
   0.1  -3.   -0.4  -0.7
  -6.9  -5.3   3.6  -6.6

--> M .\. P
 ans  =
(:,:,1)
  -2.

(:,:,2)
   3.
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>See Also</title>
        <simplelist type="inline">
            <member>
                <link linkend="kron">kron</link>
            </member>
            <member>
                <link linkend="slash">slash</link>
            </member>
            <member>
                <link linkend="backslash">backslash</link>
            </member>
            <member>
                <link linkend="star">star</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.1.0</revnumber>
                <revdescription>
                    <para>.\. and ./. actually implemented, for decimal and complex numbers.</para>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>

</refentry>
