Add examples for armax, armax1 & initstate
[scilab.git] / scilab / modules / cacsd / help / en_US / inistate.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - 
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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="inistate">
14     <refnamediv>
15         <refname>inistate</refname>
16         <refpurpose>Estimates the initial state of a discrete-time system</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>X0 = inistate(SYS,Y,U,TOL,PRINTW)
21             X0 = inistate(A,B,C,Y,U);
22             X0 = inistate(A,C,Y);
23             
24             [x0,V,rcnd] = inistate(SYS,Y,U,TOL,PRINTW)
25         </synopsis>
26     </refsynopsisdiv>
27     <refsection>
28         <title>Arguments</title>
29         <variablelist>
30             <varlistentry>
31                 <term>SYS</term>
32                 <listitem>
33                     <para>given system, syslin(dt,A,B,C,D)</para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>Y</term>
38                 <listitem>
39                     <para>the output of the system</para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>U</term>
44                 <listitem>
45                     <para>the input of the system</para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>TOL</term>
50                 <listitem>
51                     <para>TOL is 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.</para>
52                     <para>
53                         Default:    prod(size(matrix))*epsilon_machine where epsilon_machine is the relative machine precision. 
54                     </para>
55                 </listitem>
56             </varlistentry>
57             <varlistentry>
58                 <term>PRINTW</term>
59                 <listitem>
60                     <para>PRINTW is a switch for printing the warning messages.</para>
61                     <variablelist>
62                         <varlistentry>
63                             <term>=  </term>
64                             <listitem>
65                                 <para>1: print warning messages;</para>
66                             </listitem>
67                         </varlistentry>
68                         <varlistentry>
69                             <term>=  </term>
70                             <listitem>
71                                 <para>0: do not print warning messages.</para>
72                             </listitem>
73                         </varlistentry>
74                     </variablelist>
75                     <para>
76                         Default:    PRINTW = 0.
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>X0</term>
82                 <listitem>
83                     <para>the estimated initial state vector</para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>V</term>
88                 <listitem>
89                     <para>orthogonal matrix which reduces the system state matrix A to  a real Schur form</para>
90                 </listitem>
91             </varlistentry>
92             <varlistentry>
93                 <term>rcnd</term>
94                 <listitem>
95                     <para>estimate of the reciprocal condition number of the coefficient matrix of the least squares problem solved.</para>
96                 </listitem>
97             </varlistentry>
98         </variablelist>
99     </refsection>
100     <refsection>
101         <title>Description</title>
102         <para>
103             inistate  Estimates the initial state of a discrete-time system, given the 
104             (estimated) system matrices, and a set of input/output data.
105         </para>
106         <para>
107             X0 = inistate(SYS,Y,U,TOL,PRINTW)  estimates the initial state X0 of 
108             the discrete-time system SYS = (A,B,C,D), using the output data Y
109             and the input data U. The model structure is :
110         </para>
111         <programlisting role=""><![CDATA[ 
112 x(k+1) = Ax(k) + Bu(k),   k >= 1,
113 y(k)   = Cx(k) + Du(k),
114  ]]></programlisting>
115         <para>
116             The vectors y(k) and u(k) are transposes of the k-th rows of Y and U,
117             respectively.
118         </para>
119         <para>
120             Instead of the first input parameter SYS (an syslin object), equivalent
121             information may be specified using matrix parameters, for instance,
122             X0 = inistate(A,B,C,Y,U);   or   X0 = inistate(A,C,Y);
123         </para>
124         <para>
125             [x0,V,rcnd] = inistate(SYS,Y,U,TOL,PRINTW) returns, besides x0, 
126             the orthogonal matrix V which reduces the system state matrix A to 
127             a real Schur form, as well as an estimate of the reciprocal condition
128             number of the coefficient matrix of the least squares problem solved.
129         </para>
130     </refsection>
131     <refsection>
132         <title>Examples</title>
133         <programlisting role="example"><![CDATA[ 
134 //generate data from a given linear system
135 A = [ 0.5, 0.1,-0.1, 0.2;
136       0.1, 0,  -0.1,-0.1;      
137      -0.4,-0.6,-0.7,-0.1;  
138       0.8, 0,  -0.6,-0.6];      
139 B = [0.8;0.1;1;-1];
140 C = [1 2 -1 0];
141 SYS=syslin(0.1,A,B,C);
142 nsmp=100;
143 U=prbs_a(nsmp,nsmp/5);
144 Y=(flts(U,SYS)+0.3*rand(1,nsmp,'normal'));
145
146 // Compute R
147 S=15;
148 [R,N1,SVAL] = findR(S,Y',U');
149 N=3;
150 SYS1 = findABCD(S,N,1,R) ;
151 SYS1.dt=0.1;
152
153 inistate(SYS1,Y',U')
154
155 ]]></programlisting>
156     </refsection>
157     <refsection role="see also">
158         <title>See Also</title>
159         <simplelist type="inline">
160             <member>
161                 <link linkend="findBD">findBD</link>
162             </member>
163             <member>
164                 <link linkend="findx0BD">findx0BD</link>
165             </member>
166         </simplelist>
167     </refsection>
168 </refentry>