<?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: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="findABCD">
    <refnamediv>
        <refname>findABCD</refname>
        <refpurpose>discrete-time system subspace identification</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
             SYS        = findABCD(S, N, L, R, METH)
            [SYS, RCND] = findABCD(S, N, L, R, METH)
            [SYS, K] = findABCD(S,N,L,R,METH,NSMPL,TOL,PRINTW)
            [SYS, K, Q, Ry, S, RCND] = findABCD(S, N, L, R, METH, NSMPL, TOL, PRINTW)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>S</term>
                <listitem>
                    <para>integer, the number of block rows in the block-Hankel matrices</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>N</term>
                <listitem>
                    <para>integer, the system order</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>L</term>
                <listitem>
                    <para>integer, the number of output</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>R</term>
                <listitem>
                    <para>matrix, relevant part of the  R factor of the concatenated block-Hankel matrices computed by a call to findr.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>METH</term>
                <listitem>
                    <para>integer, an option for the method to use</para>
                    <variablelist>
                        <varlistentry>
                            <term>= 1</term>
                            <listitem>
                                <para> MOESP method with past inputs and outputs;</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>= 2</term>
                            <listitem>
                                <para> N4SID method;</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>= 3</term>
                            <listitem>
                                <para> combined method: A and C via MOESP, B and D via N4SID.</para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                    <para>
                        Default:    METH = 3.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>NSMPL</term>
                <listitem>
                    <para>integer, the total number of samples used for calculating the covariance matrices and the Kalman predictor gain. This parameter is not needed if the covariance matrices and/or the Kalman predictor gain matrix are not desired. If NSMPL = 0, then K, Q, Ry, and S are not computed. Default:    NSMPL = 0.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>TOL</term>
                <listitem>
                    <para>the tolerance used for estimating the rank of matrices.  If  TOL &gt; 0,  then the given value of  TOL  is used as a lower bound for the reciprocal condition number. Default: prod(size(matrix))*epsilon_machine where epsilon_machine is the relative machine precision.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>PRINTW</term>
                <listitem>
                    <para>integer, switch for printing the warning messages.</para>
                    <variablelist>
                        <varlistentry>
                            <term>PRINTW</term>
                            <listitem>
                                <para>= 1: print warning messages;</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>PRINTW</term>
                            <listitem>
                                <para>= 0: do not print warning messages.</para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                    <para>
                        Default:    PRINTW = 0.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>SYS</term>
                <listitem>
                    <para>computes a state-space realization SYS = (A,B,C,D) (an syslin object)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>K</term>
                <listitem>
                    <para>the Kalman predictor gain K (if NSMPL &gt; 0)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Q</term>
                <listitem>
                    <para> state covariance</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Ry</term>
                <listitem>
                    <para>output covariance</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>S</term>
                <listitem>
                    <para>state-output cross-covariance</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>RCND</term>
                <listitem>
                    <para>vector, reciprocal condition numbers of the matrices involved in rank decisions, least squares or Riccati equation solutions</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Finds the system matrices and the Kalman gain of a discrete-time
            system, given the system order and the relevant part of the
            R factor of the concatenated block-Hankel matrices, using subspace
            identification techniques (MOESP and/or N4SID).
        </para>
        <itemizedlist>
            <listitem>
                <para>[SYS,K] = findABCD(S,N,L,R,METH,NSMPL,TOL,PRINTW)  computes a state- space realization SYS = (A,B,C,D) (an ss object), and the Kalman predictor gain K (if NSMPL &gt; 0). The model structure is:</para>
                <programlisting role=""><![CDATA[
x(k+1) = Ax(k) + Bu(k) + Ke(k),   k >= 1,
y(k)   = Cx(k) + Du(k) + e(k),
 ]]></programlisting>
                <para>
                    where x(k) and y(k) are vectors of length N and L, respectively.
                </para>
            </listitem>
            <listitem>
                <para>[SYS,K,Q,Ry,S,RCND] = findABCD(S,N,L,R,METH,NSMPL,TOL,PRINTW)  also returns the state, output, and state-output (cross-)covariance matrices Q, Ry, and S (used for computing the Kalman gain), as well as the vector RCND of length lr containing the reciprocal condition numbers of the matrices involved in rank decisions, least squares or Riccati equation solutions, where</para>
            </listitem>
        </itemizedlist>
        <programlisting role=""><![CDATA[
lr = 4,  if Kalman gain matrix K is not required, and
lr = 12, if Kalman gain matrix K is required.
 ]]></programlisting>
        <para>
            Matrix R, computed by findR, should be determined with suitable arguments
            METH and JOBD.  METH = 1 and JOBD = 1 must be used in findR, for METH = 1
            in findABCD;  METH = 1 must be used in findR, for METH = 3 in findABCD.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
//generate data from a given linear system
A = [ 0.5, 0.1,-0.1, 0.2;
      0.1, 0,  -0.1,-0.1;
     -0.4,-0.6,-0.7,-0.1;
      0.8, 0,  -0.6,-0.6];
B = [0.8;0.1;1;-1];
C = [1 2 -1 0];
SYS=syslin(0.1,A,B,C);
nsmp=100;
U=prbs_a(nsmp,nsmp/5);
Y=(flts(U,SYS)+0.3*rand(1,nsmp,'normal'));

// Compute R
S=15;
[R,N1,SVAL] = findR(S,Y',U');
N=3;
SYS1 = findABCD(S,N,1,R) ;SYS1.dt=0.1;

SYS1.X0 = inistate(SYS1,Y',U');

Y1=flts(U,SYS1);
clf();plot2d((1:nsmp)',[Y',Y1'])
]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="findAC">findAC</link>
            </member>
            <member>
                <link linkend="findBD">findBD</link>
            </member>
            <member>
                <link linkend="findBDK">findBDK</link>
            </member>
            <member>
                <link linkend="findR">findR</link>
            </member>
            <member>
                <link linkend="sorder">sorder</link>
            </member>
            <member>
                <link linkend="sident">sident</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
