License Header change: Removed the LICENSE_END before beta
[scilab.git] / scilab / modules / cacsd / help / en_US / findR.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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <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="findR">
17     <refnamediv>
18         <refname>findR</refname>
19         <refpurpose>Preprocessor for estimating the matrices of a linear time-invariant dynamical system</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Calling Sequence</title>
23         <synopsis>[R,N [,SVAL,RCND]] = findR(S,Y,U,METH,ALG,JOBD,TOL,PRINTW)
24             [R,N] = findR(S,Y)
25         </synopsis>
26     </refsynopsisdiv>
27     <refsection>
28         <title>Arguments</title>
29         <variablelist>
30             <varlistentry>
31                 <term>S</term>
32                 <listitem>
33                     <para>the number of block rows in the block-Hankel matrices.</para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>Y</term>
38                 <listitem>
39                     <para/>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>U</term>
44                 <listitem>
45                     <para/>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>METH</term>
50                 <listitem>
51                     <para>an option for the method to use:</para>
52                     <variablelist>
53                         <varlistentry>
54                             <term>1</term>
55                             <listitem>
56                                 <para> MOESP method with past inputs and outputs;</para>
57                             </listitem>
58                         </varlistentry>
59                         <varlistentry>
60                             <term>2</term>
61                             <listitem>
62                                 <para> N4SI15     0     1     1  1000D method.</para>
63                             </listitem>
64                         </varlistentry>
65                     </variablelist>
66                     <para>
67                         Default:    METH = 1.
68                     </para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>ALG</term>
73                 <listitem>
74                     <para>an option for the algorithm to compute the triangular factor of the concatenated block-Hankel matrices built from the input-output data:</para>
75                     <variablelist>
76                         <varlistentry>
77                             <term>1</term>
78                             <listitem>
79                                 <para>  Cholesky algorithm on the correlation matrix;</para>
80                             </listitem>
81                         </varlistentry>
82                         <varlistentry>
83                             <term>2</term>
84                             <listitem>
85                                 <para>  fast QR algorithm;</para>
86                             </listitem>
87                         </varlistentry>
88                         <varlistentry>
89                             <term>3</term>
90                             <listitem>
91                                 <para>  standard QR algorithm.</para>
92                             </listitem>
93                         </varlistentry>
94                     </variablelist>
95                     <para>
96                         Default:    ALG = 1.
97                     </para>
98                 </listitem>
99             </varlistentry>
100             <varlistentry>
101                 <term>JOBD</term>
102                 <listitem>
103                     <para>an option to specify if the matrices B and D should later be computed using the MOESP approach:</para>
104                     <variablelist>
105                         <varlistentry>
106                             <term>=  </term>
107                             <listitem>
108                                 <para>1 :  the matrices B and D should later be computed using the MOESP approach;</para>
109                             </listitem>
110                         </varlistentry>
111                         <varlistentry>
112                             <term>=  </term>
113                             <listitem>
114                                 <para>2 :  the matrices B and D should not be computed using the MOESP approach.</para>
115                             </listitem>
116                         </varlistentry>
117                     </variablelist>
118                     <para>
119                         Default: JOBD = 2. This parameter is not relevant for METH = 2.
120                     </para>
121                 </listitem>
122             </varlistentry>
123             <varlistentry>
124                 <term>TOL</term>
125                 <listitem>
126                     <para>a vector of length 2 containing tolerances:</para>
127                     <variablelist>
128                         <varlistentry>
129                             <term>TOL</term>
130                             <listitem>
131                                 <para>(1) is the tolerance for estimating the rank of matrices. If  TOL(1) &gt; 0,  the given value of  TOL(1)  is used as a lower bound for the reciprocal condition number.</para>
132                                 <para>
133                                     Default:    TOL(1) = prod(size(matrix))*epsilon_machine where epsilon_machine is the relative machine precision.
134                                 </para>
135                             </listitem>
136                         </varlistentry>
137                         <varlistentry>
138                             <term>TOL</term>
139                             <listitem>
140                                 <para>(2) is the tolerance for estimating the system order. If  TOL(2) &gt;= 0,  the estimate is indicated by the index of the last singular value greater than or equal to  TOL(2).  (Singular values less than  TOL(2) are considered as zero.)</para>
141                                 <para>
142                                     When  TOL(2) = 0,  then  S*epsilon_machine*sval(1)  is used instead TOL(2),  where  sval(1)  is the maximal singular value. When  TOL(2) &lt; 0,  the estimate is indicated by the index of the singular value that has the largest logarithmic gap to its successor. Default:    TOL(2) = -1.
143                                 </para>
144                             </listitem>
145                         </varlistentry>
146                     </variablelist>
147                 </listitem>
148             </varlistentry>
149             <varlistentry>
150                 <term>PRINTW</term>
151                 <listitem>
152                     <para>a switch for printing the warning messages.</para>
153                     <variablelist>
154                         <varlistentry>
155                             <term>=  </term>
156                             <listitem>
157                                 <para>1: print warning messages;</para>
158                             </listitem>
159                         </varlistentry>
160                         <varlistentry>
161                             <term>=  </term>
162                             <listitem>
163                                 <para>0: do not print warning messages.</para>
164                             </listitem>
165                         </varlistentry>
166                     </variablelist>
167                     <para>
168                         Default:    PRINTW = 0.
169                     </para>
170                 </listitem>
171             </varlistentry>
172             <varlistentry>
173                 <term>R</term>
174                 <listitem>
175                     <para/>
176                 </listitem>
177             </varlistentry>
178             <varlistentry>
179                 <term>N</term>
180                 <listitem>
181                     <para>the order of the discrete-time realization</para>
182                 </listitem>
183             </varlistentry>
184             <varlistentry>
185                 <term>SVAL</term>
186                 <listitem>
187                     <para>singular values SVAL, used for estimating the order.</para>
188                 </listitem>
189             </varlistentry>
190             <varlistentry>
191                 <term>RCND</term>
192                 <listitem>
193                     <para>vector of length 2 containing the reciprocal condition numbers of the matrices involved in rank decisions or least squares solutions.</para>
194                 </listitem>
195             </varlistentry>
196         </variablelist>
197     </refsection>
198     <refsection>
199         <title>Description</title>
200         <para>
201             findR   Preprocesses the input-output data for estimating the matrices 
202             of a linear time-invariant dynamical system, using Cholesky or
203             (fast) QR factorization and subspace identification techniques 
204             (MOESP or N4SID), and estimates the system order.
205         </para>
206         <para>
207             [R,N] = findR(S,Y,U,METH,ALG,JOBD,TOL,PRINTW)  returns the processed
208             upper triangular factor  R  of the concatenated block-Hankel matrices 
209             built from the input-output data, and the order  N  of a discrete-time
210             realization. The model structure is:
211         </para>
212         <programlisting role=""><![CDATA[ 
213 x(k+1) = Ax(k) + Bu(k) + w(k),   k >= 1,
214 y(k)   = Cx(k) + Du(k) + e(k).
215  ]]></programlisting>
216         <para>
217             The vectors y(k) and u(k) are transposes of the k-th rows of Y and U,
218             respectively.
219         </para>
220         <para>
221             [R,N,SVAL,RCND] = findR(S,Y,U,METH,ALG,JOBD,TOL,PRINTW)  also returns
222             the singular values SVAL, used for estimating the order, as well as,
223             if meth = 2, the vector RCND of length 2 containing the reciprocal
224             condition numbers of the matrices involved in rank decisions or least
225             squares solutions.
226         </para>
227         <para>
228             [R,N] = findR(S,Y)  assumes U = [] and default values for the
229             remaining input arguments.
230         </para>
231     </refsection>
232     <refsection>
233         <title>Examples</title>
234         <programlisting role="example"><![CDATA[ 
235 //generate data from a given linear system
236 A = [ 0.5, 0.1,-0.1, 0.2;
237       0.1, 0,  -0.1,-0.1;      
238      -0.4,-0.6,-0.7,-0.1;  
239       0.8, 0,  -0.6,-0.6];      
240 B = [0.8;0.1;1;-1];
241 C = [1 2 -1 0];
242 SYS=syslin(0.1,A,B,C);
243 U=(ones(1,1000)+rand(1,1000,'normal')); 
244 Y=(flts(U,SYS)+0.5*rand(1,1000,'normal'));
245 // Compute R
246
247 [R,N,SVAL] = findR(15,Y',U');
248 SVAL
249 N
250  ]]></programlisting>
251     </refsection>
252     <refsection role="see also">
253         <title>See Also</title>
254         <simplelist type="inline">
255             <member>
256                 <link linkend="findABCD">findABCD</link>
257             </member>
258             <member>
259                 <link linkend="findAC">findAC</link>
260             </member>
261             <member>
262                 <link linkend="findBD">findBD</link>
263             </member>
264             <member>
265                 <link linkend="findBDK">findBDK</link>
266             </member>
267             <member>
268                 <link linkend="sorder">sorder</link>
269             </member>
270             <member>
271                 <link linkend="sident">sident</link>
272             </member>
273         </simplelist>
274     </refsection>
275 </refentry>