<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * 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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="spantwo">
    <refnamediv>
        <refname>spantwo</refname>
        <refpurpose>sum and intersection of subspaces</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>[Xp,dima,dimb,dim]=spantwo(A,B, [tol])</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>A, B</term>
                <listitem>
                    <para>two real or complex matrices with equal number of rows</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Xp</term>
                <listitem>
                    <para>square non-singular matrix</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>dima, dimb, dim</term>
                <listitem>
                    <para>integers, dimension of subspaces</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>tol</term>
                <listitem>
                    <para>nonnegative real number</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Given two matrices <literal>A</literal> and <literal>B</literal> with same number of rows,
            returns a square matrix <literal>Xp</literal> (non singular but not necessarily orthogonal)
            such that :
        </para>
        <programlisting role=""><![CDATA[
         [A1, 0]    (dim-dimb rows)
Xp*[A,B]=[A2,B2]    (dima+dimb-dim rows)
         [0, B3]    (dim-dima rows)
         [0 , 0]
 ]]></programlisting>
        <para>
            The  first <literal>dima</literal>  columns of <literal>inv(Xp)</literal> span range(<literal>A</literal>).
        </para>
        <para>
            Columns <literal>dim-dimb+1</literal> to <literal>dima</literal> of <literal>inv(Xp)</literal> span the
            intersection of range(A) and range(B).
        </para>
        <para>
            The <literal>dim</literal> first columns of <literal>inv(Xp)</literal> span
            range(<literal>A</literal>)+range(<literal>B</literal>).
        </para>
        <para>
            Columns <literal>dim-dimb+1</literal> to <literal>dim</literal> of <literal>inv(Xp)</literal> span
            range(<literal>B</literal>).
        </para>
        <para>
            Matrix <literal>[A1;A2]</literal> has full row rank (=rank(A)). Matrix <literal>[B2;B3]</literal> has
            full row rank (=rank(B)). Matrix <literal>[A2,B2]</literal> has full row rank (=rank(A inter B)). Matrix <literal>[A1,0;A2,B2;0,B3]</literal> has full row rank (=rank(A+B)).
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
A=[1,0,0,4;
   5,6,7,8;
   0,0,11,12;
   0,0,0,16];
B=[1,2,0,0]';C=[4,0,0,1];
Sl=ss2ss(syslin('c',A,B,C),rand(A));
[no,X]=contr(Sl('A'),Sl('B'));CO=X(:,1:no);  //Controllable part
[uo,Y]=unobs(Sl('A'),Sl('C'));UO=Y(:,1:uo);  //Unobservable part
[Xp,dimc,dimu,dim]=spantwo(CO,UO);    //Kalman decomposition
Slcan=ss2ss(Sl,inv(Xp));
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="spanplus">spanplus</link>
            </member>
            <member>
                <link linkend="spaninter">spaninter</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
