← Back to branch summary

~ubuntu-branches/ubuntu/raring/scilab/raring-proposed

« back to all changes in this revision

Viewing changes to modules/cacsd/help/en_US/findBDK.xml

  • Committer: Package Import Robot
  • Author(s): Sylvestre Ledru
  • Date: 2012-08-30 14:42:38 UTC
  • mfrom: (1.4.7)
  • Revision ID: package-import@ubuntu.com-20120830144238-c1y2og7dbm7m9nig
Tags: 5.4.0-beta-3-1~exp1
* New upstream release
* Update the scirenderer dep
* Get ride of libjhdf5-java dependency

Show diffs side-by-side

added added

removed removed

Lines of Context:
modules/cacsd/help/en_US/findBDK.xml
11
11
 *
12
12
 -->
13
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" version="5.0-subset Scilab" xml:lang="en" xml:id="findBDK">
14
 
  <refnamediv>
15
 
    <refname>findBDK</refname>
16
 
    <refpurpose> Kalman gain and  B D system matrices of a discrete-time system</refpurpose>
17
 
  </refnamediv>
18
 
  <refsynopsisdiv>
19
 
    <title>Calling Sequence</title>
20
 
    <synopsis>[B,D,K] = findBDK(S,N,L,R,A,C,METH,JOB,NSMPL,TOL,PRINTW)
21
 
      [B,D,RCND] = findBDK(S,N,L,R,A,C,METH,JOB)
22
 
      [B,D,K,Q,Ry,S,RCND] = findBDK(S,N,L,R,A,C,METH,JOB,NSMPL,TOL,PRINTW)
23
 
    </synopsis>
24
 
  </refsynopsisdiv>
25
 
  <refsection>
26
 
    <title>Arguments</title>
27
 
    <variablelist>
28
 
      <varlistentry>
29
 
        <term>S</term>
30
 
        <listitem>
31
 
          <para>integer, the number of block rows in the block-Hankel matrices</para>
32
 
        </listitem>
33
 
      </varlistentry>
34
 
      <varlistentry>
35
 
        <term>N</term>
36
 
        <listitem>
37
 
          <para>integer</para>
38
 
        </listitem>
39
 
      </varlistentry>
40
 
      <varlistentry>
41
 
        <term>L</term>
42
 
        <listitem>
43
 
          <para>integer</para>
44
 
        </listitem>
45
 
      </varlistentry>
46
 
      <varlistentry>
47
 
        <term>R</term>
48
 
        <listitem>
49
 
          <para>matrix, relevant part of the  R factor of the concatenated block-Hankel matrices computed by a call to findR.</para>
50
 
        </listitem>
51
 
      </varlistentry>
52
 
      <varlistentry>
53
 
        <term>A</term>
54
 
        <listitem>
55
 
          <para>square matrix</para>
56
 
        </listitem>
57
 
      </varlistentry>
58
 
      <varlistentry>
59
 
        <term>C</term>
60
 
        <listitem>
61
 
          <para>matrix</para>
62
 
        </listitem>
63
 
      </varlistentry>
64
 
      <varlistentry>
65
 
        <term>METH</term>
66
 
        <listitem>
67
 
          <para>integer, an option for the method to use</para>
68
 
          <variablelist>
69
 
            <varlistentry>
70
 
              <term>= 1</term>
71
 
              <listitem>
72
 
                <para> MOESP method with past inputs and outputs;</para>
73
 
              </listitem>
74
 
            </varlistentry>
75
 
            <varlistentry>
76
 
              <term>= 2</term>
77
 
              <listitem>
78
 
                <para> N4SID method;</para>
79
 
              </listitem>
80
 
            </varlistentry>
81
 
          </variablelist>
82
 
          <para>
83
 
            Default:    METH = 2.
84
 
          </para>
85
 
        </listitem>
86
 
      </varlistentry>
87
 
      <varlistentry>
88
 
        <term>JOB</term>
89
 
        <listitem>
90
 
          <para>an option specifying which system matrices should be computed:</para>
91
 
          <variablelist>
92
 
            <varlistentry>
93
 
              <term>= 1</term>
94
 
              <listitem>
95
 
                <para>  compute the matrix B;</para>
96
 
              </listitem>
97
 
            </varlistentry>
98
 
            <varlistentry>
99
 
              <term>= 2</term>
100
 
              <listitem>
101
 
                <para>  compute the matrices B and D.</para>
102
 
              </listitem>
103
 
            </varlistentry>
104
 
          </variablelist>
105
 
          <para>
106
 
            Default:    JOB = 2.
107
 
          </para>
108
 
        </listitem>
109
 
      </varlistentry>
110
 
      <varlistentry>
111
 
        <term>NSMPL</term>
112
 
        <listitem>
113
 
          <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>
114
 
        </listitem>
115
 
      </varlistentry>
116
 
      <varlistentry>
117
 
        <term>TOL</term>
118
 
        <listitem>
119
 
          <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>
120
 
        </listitem>
121
 
      </varlistentry>
122
 
      <varlistentry>
123
 
        <term>PRINTW</term>
124
 
        <listitem>
125
 
          <para>integer, switch for printing the warning messages.</para>
126
 
          <variablelist>
127
 
            <varlistentry>
128
 
              <term>PRINTW</term>
129
 
              <listitem>
130
 
                <para>= 1: print warning messages;</para>
131
 
              </listitem>
132
 
            </varlistentry>
133
 
            <varlistentry>
134
 
              <term>PRINTW</term>
135
 
              <listitem>
136
 
                <para>= 0: do not print warning messages.</para>
137
 
              </listitem>
138
 
            </varlistentry>
139
 
          </variablelist>
140
 
          <para>
141
 
            Default:    PRINTW = 0.
142
 
          </para>
143
 
        </listitem>
144
 
      </varlistentry>
145
 
      <varlistentry>
146
 
        <term>SYS</term>
147
 
        <listitem>
148
 
          <para>computes a state-space realization SYS = (A,B,C,D) (an syslin object)</para>
149
 
        </listitem>
150
 
      </varlistentry>
151
 
      <varlistentry>
152
 
        <term>K</term>
153
 
        <listitem>
154
 
          <para>the Kalman predictor gain K (if NSMPL &gt; 0)</para>
155
 
        </listitem>
156
 
      </varlistentry>
157
 
      <varlistentry>
158
 
        <term>Q</term>
159
 
        <listitem>
160
 
          <para> state covariance</para>
161
 
        </listitem>
162
 
      </varlistentry>
163
 
      <varlistentry>
164
 
        <term>Ry</term>
165
 
        <listitem>
166
 
          <para>output covariance</para>
167
 
        </listitem>
168
 
      </varlistentry>
169
 
      <varlistentry>
170
 
        <term>S</term>
171
 
        <listitem>
172
 
          <para>state-output cross-covariance</para>
173
 
        </listitem>
174
 
      </varlistentry>
175
 
      <varlistentry>
176
 
        <term>RCND</term>
177
 
        <listitem>
178
 
          <para>he vector  of length 12 containing the reciprocal condition numbers of the matrices involved in rank decisions, least squares or Riccati equation solutions.</para>
179
 
        </listitem>
180
 
      </varlistentry>
181
 
    </variablelist>
182
 
  </refsection>
183
 
  <refsection>
184
 
    <title>Description</title>
185
 
    <para>
186
 
      finds the system matrices B and D and the Kalman gain of a discrete-time 
187
 
      system, given the system order, the matrices A and C, and the relevant
188
 
      part of the R factor of the concatenated block-Hankel matrices, using
189
 
      subspace identification techniques (MOESP or N4SID).
190
 
    </para>
191
 
    <itemizedlist>
192
 
      <listitem>
193
 
        <para>[B,D,K] = findBDK(S,N,L,R,A,C,METH,JOB,NSMPL,TOL,PRINTW)  computes the system matrices B (if JOB = 1), B and D (if JOB = 2), and the Kalman  predictor gain K (if NSMPL &gt; 0). The model structure is:</para>
194
 
        <programlisting role=""><![CDATA[ 
 
14
    <refnamediv>
 
15
        <refname>findBDK</refname>
 
16
        <refpurpose> Kalman gain and  B D system matrices of a discrete-time system</refpurpose>
 
17
    </refnamediv>
 
18
    <refsynopsisdiv>
 
19
        <title>Calling Sequence</title>
 
20
        <synopsis>[B,D,K] = findBDK(S,N,L,R,A,C,METH,JOB,NSMPL,TOL,PRINTW)
 
21
            [B,D,RCND] = findBDK(S,N,L,R,A,C,METH,JOB)
 
22
            [B,D,K,Q,Ry,S,RCND] = findBDK(S,N,L,R,A,C,METH,JOB,NSMPL,TOL,PRINTW)
 
23
        </synopsis>
 
24
    </refsynopsisdiv>
 
25
    <refsection>
 
26
        <title>Arguments</title>
 
27
        <variablelist>
 
28
            <varlistentry>
 
29
                <term>S</term>
 
30
                <listitem>
 
31
                    <para>integer, the number of block rows in the block-Hankel matrices</para>
 
32
                </listitem>
 
33
            </varlistentry>
 
34
            <varlistentry>
 
35
                <term>N</term>
 
36
                <listitem>
 
37
                    <para>integer</para>
 
38
                </listitem>
 
39
            </varlistentry>
 
40
            <varlistentry>
 
41
                <term>L</term>
 
42
                <listitem>
 
43
                    <para>integer</para>
 
44
                </listitem>
 
45
            </varlistentry>
 
46
            <varlistentry>
 
47
                <term>R</term>
 
48
                <listitem>
 
49
                    <para>matrix, relevant part of the  R factor of the concatenated block-Hankel matrices computed by a call to findR.</para>
 
50
                </listitem>
 
51
            </varlistentry>
 
52
            <varlistentry>
 
53
                <term>A</term>
 
54
                <listitem>
 
55
                    <para>square matrix</para>
 
56
                </listitem>
 
57
            </varlistentry>
 
58
            <varlistentry>
 
59
                <term>C</term>
 
60
                <listitem>
 
61
                    <para>matrix</para>
 
62
                </listitem>
 
63
            </varlistentry>
 
64
            <varlistentry>
 
65
                <term>METH</term>
 
66
                <listitem>
 
67
                    <para>integer, an option for the method to use</para>
 
68
                    <variablelist>
 
69
                        <varlistentry>
 
70
                            <term>= 1</term>
 
71
                            <listitem>
 
72
                                <para> MOESP method with past inputs and outputs;</para>
 
73
                            </listitem>
 
74
                        </varlistentry>
 
75
                        <varlistentry>
 
76
                            <term>= 2</term>
 
77
                            <listitem>
 
78
                                <para> N4SID method;</para>
 
79
                            </listitem>
 
80
                        </varlistentry>
 
81
                    </variablelist>
 
82
                    <para>
 
83
                        Default:    METH = 2.
 
84
                    </para>
 
85
                </listitem>
 
86
            </varlistentry>
 
87
            <varlistentry>
 
88
                <term>JOB</term>
 
89
                <listitem>
 
90
                    <para>an option specifying which system matrices should be computed:</para>
 
91
                    <variablelist>
 
92
                        <varlistentry>
 
93
                            <term>= 1</term>
 
94
                            <listitem>
 
95
                                <para>  compute the matrix B;</para>
 
96
                            </listitem>
 
97
                        </varlistentry>
 
98
                        <varlistentry>
 
99
                            <term>= 2</term>
 
100
                            <listitem>
 
101
                                <para>  compute the matrices B and D.</para>
 
102
                            </listitem>
 
103
                        </varlistentry>
 
104
                    </variablelist>
 
105
                    <para>
 
106
                        Default:    JOB = 2.
 
107
                    </para>
 
108
                </listitem>
 
109
            </varlistentry>
 
110
            <varlistentry>
 
111
                <term>NSMPL</term>
 
112
                <listitem>
 
113
                    <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>
 
114
                </listitem>
 
115
            </varlistentry>
 
116
            <varlistentry>
 
117
                <term>TOL</term>
 
118
                <listitem>
 
119
                    <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>
 
120
                </listitem>
 
121
            </varlistentry>
 
122
            <varlistentry>
 
123
                <term>PRINTW</term>
 
124
                <listitem>
 
125
                    <para>integer, switch for printing the warning messages.</para>
 
126
                    <variablelist>
 
127
                        <varlistentry>
 
128
                            <term>PRINTW</term>
 
129
                            <listitem>
 
130
                                <para>= 1: print warning messages;</para>
 
131
                            </listitem>
 
132
                        </varlistentry>
 
133
                        <varlistentry>
 
134
                            <term>PRINTW</term>
 
135
                            <listitem>
 
136
                                <para>= 0: do not print warning messages.</para>
 
137
                            </listitem>
 
138
                        </varlistentry>
 
139
                    </variablelist>
 
140
                    <para>
 
141
                        Default:    PRINTW = 0.
 
142
                    </para>
 
143
                </listitem>
 
144
            </varlistentry>
 
145
            <varlistentry>
 
146
                <term>SYS</term>
 
147
                <listitem>
 
148
                    <para>computes a state-space realization SYS = (A,B,C,D) (an syslin object)</para>
 
149
                </listitem>
 
150
            </varlistentry>
 
151
            <varlistentry>
 
152
                <term>K</term>
 
153
                <listitem>
 
154
                    <para>the Kalman predictor gain K (if NSMPL &gt; 0)</para>
 
155
                </listitem>
 
156
            </varlistentry>
 
157
            <varlistentry>
 
158
                <term>Q</term>
 
159
                <listitem>
 
160
                    <para> state covariance</para>
 
161
                </listitem>
 
162
            </varlistentry>
 
163
            <varlistentry>
 
164
                <term>Ry</term>
 
165
                <listitem>
 
166
                    <para>output covariance</para>
 
167
                </listitem>
 
168
            </varlistentry>
 
169
            <varlistentry>
 
170
                <term>S</term>
 
171
                <listitem>
 
172
                    <para>state-output cross-covariance</para>
 
173
                </listitem>
 
174
            </varlistentry>
 
175
            <varlistentry>
 
176
                <term>RCND</term>
 
177
                <listitem>
 
178
                    <para>he vector  of length 12 containing the reciprocal condition numbers of the matrices involved in rank decisions, least squares or Riccati equation solutions.</para>
 
179
                </listitem>
 
180
            </varlistentry>
 
181
        </variablelist>
 
182
    </refsection>
 
183
    <refsection>
 
184
        <title>Description</title>
 
185
        <para>
 
186
            finds the system matrices B and D and the Kalman gain of a discrete-time 
 
187
            system, given the system order, the matrices A and C, and the relevant
 
188
            part of the R factor of the concatenated block-Hankel matrices, using
 
189
            subspace identification techniques (MOESP or N4SID).
 
190
        </para>
 
191
        <itemizedlist>
 
192
            <listitem>
 
193
                <para>[B,D,K] = findBDK(S,N,L,R,A,C,METH,JOB,NSMPL,TOL,PRINTW)  computes the system matrices B (if JOB = 1), B and D (if JOB = 2), and the Kalman  predictor gain K (if NSMPL &gt; 0). The model structure is:</para>
 
194
                <programlisting role=""><![CDATA[ 
195
195
x(k+1) = Ax(k) + Bu(k) + Ke(k),   k >= 1,
196
196
y(k)   = Cx(k) + Du(k) + e(k),
197
197
 ]]></programlisting>
198
 
        <para>
199
 
          where x(k) and y(k) are vectors of length N and L, respectively.
200
 
        </para>
201
 
      </listitem>
202
 
      <listitem>
203
 
        <para>[B,D,RCND] = findBDK(S,N,L,R,A,C,METH,JOB)  also returns the vector RCND of length 4 containing the reciprocal condition numbers of the matrices involved in rank decisions.</para>
204
 
      </listitem>
205
 
      <listitem>
206
 
        <para>[B,D,K,Q,Ry,S,RCND] = findBDK(S,N,L,R,A,C,METH,JOB,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 12 containing the reciprocal condition numbers of the matrices involved in rank decisions, least squares or Riccati equation solutions.</para>
207
 
      </listitem>
208
 
    </itemizedlist>
209
 
    <para>
210
 
      Matrix R, computed by findR, should be determined with suitable arguments
211
 
      METH and JOBD.  METH = 1 and JOBD = 1 must be used in findR, for METH = 1 
212
 
      in findBDK. Using METH = 1 in FINDR and METH = 2 in findBDK is allowed.
213
 
    </para>
214
 
    <para>
215
 
      The number of output arguments may vary, but should correspond to the 
216
 
      input arguments, e.g.,
217
 
    </para>
218
 
    <programlisting role=""><![CDATA[ 
 
198
                <para>
 
199
                    where x(k) and y(k) are vectors of length N and L, respectively.
 
200
                </para>
 
201
            </listitem>
 
202
            <listitem>
 
203
                <para>[B,D,RCND] = findBDK(S,N,L,R,A,C,METH,JOB)  also returns the vector RCND of length 4 containing the reciprocal condition numbers of the matrices involved in rank decisions.</para>
 
204
            </listitem>
 
205
            <listitem>
 
206
                <para>[B,D,K,Q,Ry,S,RCND] = findBDK(S,N,L,R,A,C,METH,JOB,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 12 containing the reciprocal condition numbers of the matrices involved in rank decisions, least squares or Riccati equation solutions.</para>
 
207
            </listitem>
 
208
        </itemizedlist>
 
209
        <para>
 
210
            Matrix R, computed by findR, should be determined with suitable arguments
 
211
            METH and JOBD.  METH = 1 and JOBD = 1 must be used in findR, for METH = 1 
 
212
            in findBDK. Using METH = 1 in FINDR and METH = 2 in findBDK is allowed.
 
213
        </para>
 
214
        <para>
 
215
            The number of output arguments may vary, but should correspond to the 
 
216
            input arguments, e.g.,
 
217
        </para>
 
218
        <programlisting role=""><![CDATA[ 
219
219
         B = findBDK(S,N,L,R,A,C,METH,1)  or
220
220
     [B,D] = findBDK(S,N,L,R,A,C,METH,2)  or
221
221
[B,D,RCND] = findBDK(S,N,L,R,A,C,METH,2)  
222
222
 ]]></programlisting>
223
 
  </refsection>
224
 
  <refsection>
225
 
    <title>Examples</title>
226
 
    <programlisting role="example"><![CDATA[ 
 
223
    </refsection>
 
224
    <refsection>
 
225
        <title>Examples</title>
 
226
        <programlisting role="example"><![CDATA[ 
227
227
//generate data from a given linear system
228
228
A = [ 0.5, 0.1,-0.1, 0.2;
229
229
      0.1, 0,  -0.1,-0.1;      
251
251
Y1=flts(U,SYS1);
252
252
clf();plot2d((1:nsmp)',[Y',Y1'])
253
253
]]></programlisting>
254
 
  </refsection>
255
 
  <refsection role="see also">
256
 
    <title>See Also</title>
257
 
    <simplelist type="inline">
258
 
      <member>
259
 
        <link linkend="findABCD">findABCD</link>
260
 
      </member>
261
 
      <member>
262
 
        <link linkend="findAC">findAC</link>
263
 
      </member>
264
 
      <member>
265
 
        <link linkend="findBD">findBD</link>
266
 
      </member>
267
 
      <member>
268
 
        <link linkend="findR">findR</link>
269
 
      </member>
270
 
      <member>
271
 
        <link linkend="sorder">sorder</link>
272
 
      </member>
273
 
      <member>
274
 
        <link linkend="sident">sident</link>
275
 
      </member>
276
 
    </simplelist>
277
 
  </refsection>
 
254
    </refsection>
 
255
    <refsection role="see also">
 
256
        <title>See Also</title>
 
257
        <simplelist type="inline">
 
258
            <member>
 
259
                <link linkend="findABCD">findABCD</link>
 
260
            </member>
 
261
            <member>
 
262
                <link linkend="findAC">findAC</link>
 
263
            </member>
 
264
            <member>
 
265
                <link linkend="findBD">findBD</link>
 
266
            </member>
 
267
            <member>
 
268
                <link linkend="findR">findR</link>
 
269
            </member>
 
270
            <member>
 
271
                <link linkend="sorder">sorder</link>
 
272
            </member>
 
273
            <member>
 
274
                <link linkend="sident">sident</link>
 
275
            </member>
 
276
        </simplelist>
 
277
    </refsection>
278
278
</refentry>