<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 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: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="ss2ss" xml:lang="en">
    <refnamediv>
        <refname>ss2ss</refname>
        <refpurpose>state-space to state-space conversion, feedback,
            injection
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            [Sl1, right, left] = ss2ss(Sl, T)
            [Sl1, right, left] = ss2ss(Sl, T, F)
            [Sl1, right, left] = ss2ss(Sl, T, F, G)
            [Sl1, right, left] = ss2ss(Sl, T, F, G, flag)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>Sl</term>
                <listitem>
                    <para>
                        linear system (<literal>syslin</literal> list) in state-space
                        form
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>T</term>
                <listitem>
                    <para>square (non-singular) matrix</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Sl1, right, left</term>
                <listitem>
                    <para>linear systems (syslin lists) in state-space form</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>F</term>
                <listitem>
                    <para>real matrix (state feedback gain)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>G</term>
                <listitem>
                    <para>real matrix (output injection gain)</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Returns the linear system <literal>Sl1=[A1,B1,C1,D1]</literal> where
            <literal>A1=inv(T)*A*T, B1=inv(T)*B, C1=C*T, D1=D</literal>.
        </para>
        <para>
            Optional parameters <literal>F</literal> and <literal>G</literal>
            are state feedback and output injection respectively.
        </para>
        <para>
            For example, <literal>Sl1=ss2ss(Sl,T,F)</literal> returns
            <literal>Sl1</literal> with:
        </para>
        <mediaobject>
            <imageobject>
                <imagedata align="center" fileref="../../mml/ss2ss_equation1.mml"/>
            </imageobject>
        </mediaobject>
        <para>
            and <literal>right</literal> is a non singular linear system such
            that <literal>Sl1=Sl*right</literal>.
        </para>
        <para>
            <literal>Sl1*inv(right)</literal> is a factorization of
            <literal>Sl</literal>.
        </para>
        <para>
            <literal>Sl1=ss2ss(Sl,T,0*F,G)</literal> returns
            <literal>Sl1</literal> with:
        </para>
        <mediaobject>
            <imageobject>
                <imagedata align="center" fileref="../../mml/ss2ss_equation2.mml"/>
            </imageobject>
        </mediaobject>
        <para>
            and <literal>left</literal> is a non singular linear system such
            that <literal>Sl1=left*Sl</literal> (<literal>right=Id</literal> if
            <literal>F=0</literal>).
        </para>
        <para>
            When both <literal>F</literal> and <literal>G</literal> are given,
            <literal>Sl1=left*Sl*right</literal>.
        </para>
        <itemizedlist>
            <listitem>
                <para>
                    When <literal>flag</literal> is used and
                    <literal>flag=1</literal> an output injection as follows is used
                </para>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="../../mml/ss2ss_equation3.mml"/>
                    </imageobject>
                </mediaobject>
                <para>
                    and then a feedback is performed, <literal>F</literal> must be
                    of size <literal>(m+p,n)</literal>
                </para>
                <mediaobject>
                    <imageobject>
                        <imagedata align="left" fileref="../../mml/ss2ss_equation4.mml"/>
                    </imageobject>
                </mediaobject>
                <para>
                    <literal>right</literal> and <literal>left</literal> have the
                    following property:
                </para>
                <programlisting role=""><![CDATA[
Sl1 = left*blockdiag(sys,eye(p,p))*right
 ]]></programlisting>
            </listitem>
            <listitem>
                <para>
                    When <literal>flag</literal> is used and
                    <literal>flag=2</literal> a feedback (<literal>F</literal> must be of
                    size <literal>(m,n)</literal>) is performed and then the above output
                    injection is applied. <literal>right</literal> and
                    <literal>left</literal> have the following property:
                </para>
                <programlisting role=""><![CDATA[
 Sl1 = left*blockdiag(sys*right,eye(p,p)))
 ]]></programlisting>
            </listitem>
        </itemizedlist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
Sl=ssrand(2,2,5); trzeros(Sl)       // zeros are invariant:
Sl1=ss2ss(Sl,rand(5,5),rand(2,5),rand(5,2));
trzeros(Sl1), trzeros(rand(2,2)*Sl1*rand(2,2))
// output injection [ A + GC, (B+GD,-G)]
//                  [   C   , (D   , 0)]
p=1,m=2,n=2; sys=ssrand(p,m,n);

// feedback (m,n)  first and then output injection.

F1=rand(m,n);
G=rand(n,p);
[sys1,right,left]=ss2ss(sys,rand(n,n),F1,G,2);

// Sl1 equiv left*blockdiag(sys*right,eye(p,p)))

res=clean(ss2tf(sys1) - ss2tf(left*blockdiag(sys*right,eye(p,p))))

// output injection then feedback (m+p,n)
F2=rand(p,n); F=[F1;F2];
[sys2,right,left]=ss2ss(sys,rand(n,n),F,G,1);

// Sl1 equiv left*blockdiag(sys,eye(p,p))*right

res=clean(ss2tf(sys2)-ss2tf(left*blockdiag(sys,eye(p,p))*right))

// when F2= 0; sys1 and sys2 are the same
F2=0*rand(p,n);F=[F1;F2];
[sys2,right,left]=ss2ss(sys,rand(n,n),F,G,1);

res=clean(ss2tf(sys2)-ss2tf(sys1))
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="projsl">projsl</link>
            </member>
            <member>
                <link linkend="feedback">feedback</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
