← Back to branch summary

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

« back to all changes in this revision

Viewing changes to modules/linear_algebra/help/en_US/eigen/schur.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/linear_algebra/help/en_US/eigen/schur.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) 2008 - 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" version="5.0-subset Scilab" xml:lang="en" xml:id="schur">
 
14
    <refnamediv>
 
15
        <refname>schur</refname>
 
16
        <refpurpose> [ordered] Schur decomposition of matrix and pencils</refpurpose>
 
17
    </refnamediv>
 
18
    <refsynopsisdiv>
 
19
        <title>Calling Sequence</title>
 
20
        <synopsis>[U,T] = schur(A)
 
21
            [U,dim [,T] ]=schur(A,flag)
 
22
            [U,dim [,T] ]=schur(A,extern1)
 
23
            
 
24
            [As,Es [,Q,Z]]=schur(A,E)
 
25
            [As,Es [,Z,dim]] = schur(A,E,flag)
 
26
            [Z,dim] = schur(A,E,flag)
 
27
            [As,Es [,Z,dim]]= schur(A,E,extern2)
 
28
            [Z,dim]= schur(A,E,extern2)
 
29
        </synopsis>
 
30
    </refsynopsisdiv>
 
31
    <refsection>
 
32
        <title>Arguments</title>
 
33
        <variablelist>
 
34
            <varlistentry>
 
35
                <term>A</term>
 
36
                <listitem>
 
37
                    <para>real or complex square matrix.</para>
 
38
                </listitem>
 
39
            </varlistentry>
 
40
            <varlistentry>
 
41
                <term>E</term>
 
42
                <listitem>
 
43
                    <para>
 
44
                        real or complex square matrix with same dimensions as <literal> A</literal>.
 
45
                    </para>
 
46
                </listitem>
 
47
            </varlistentry>
 
48
            <varlistentry>
 
49
                <term>flag</term>
 
50
                <listitem>
 
51
                    <para>
 
52
                        character string (<literal>'c'</literal> or <literal>'d'</literal>)
 
53
                    </para>
 
54
                </listitem>
 
55
            </varlistentry>
 
56
            <varlistentry>
 
57
                <term>extern1</term>
 
58
                <listitem>
 
59
                    <para>an ``external'', see below</para>
 
60
                </listitem>
 
61
            </varlistentry>
 
62
            <varlistentry>
 
63
                <term>extern2</term>
 
64
                <listitem>
 
65
                    <para>an ``external'', see below</para>
 
66
                </listitem>
 
67
            </varlistentry>
 
68
            <varlistentry>
 
69
                <term>U</term>
 
70
                <listitem>
 
71
                    <para>orthogonal or unitary square matrix</para>
 
72
                </listitem>
 
73
            </varlistentry>
 
74
            <varlistentry>
 
75
                <term>Q</term>
 
76
                <listitem>
 
77
                    <para>orthogonal or unitary square matrix</para>
 
78
                </listitem>
 
79
            </varlistentry>
 
80
            <varlistentry>
 
81
                <term>Z</term>
 
82
                <listitem>
 
83
                    <para>orthogonal or unitary square matrix</para>
 
84
                </listitem>
 
85
            </varlistentry>
 
86
            <varlistentry>
 
87
                <term>T</term>
 
88
                <listitem>
 
89
                    <para>upper triangular or quasi-triangular square matrix</para>
 
90
                </listitem>
 
91
            </varlistentry>
 
92
            <varlistentry>
 
93
                <term>As</term>
 
94
                <listitem>
 
95
                    <para>upper triangular or quasi-triangular square matrix</para>
 
96
                </listitem>
 
97
            </varlistentry>
 
98
            <varlistentry>
 
99
                <term>Es</term>
 
100
                <listitem>
 
101
                    <para>upper triangular  square matrix</para>
 
102
                </listitem>
 
103
            </varlistentry>
 
104
            <varlistentry>
 
105
                <term>dim</term>
 
106
                <listitem>
 
107
                    <para>integer</para>
 
108
                </listitem>
 
109
            </varlistentry>
 
110
        </variablelist>
 
111
    </refsection>
 
112
    <refsection>
 
113
        <title>Description</title>
 
114
        <para>
 
115
            Schur forms, ordered Schur forms of matrices and pencils
 
116
        </para>
 
117
        <variablelist>
 
118
            <varlistentry>
 
119
                <term>MATRIX SCHUR FORM</term>
 
120
                <listitem>
 
121
                    <variablelist>
 
122
                        <varlistentry>
 
123
                            <term>Usual schur form:</term>
 
124
                            <listitem>
 
125
                                <para>
 
126
                                    <literal>[U,T] = schur(A)</literal> produces a Schur matrix
 
127
                                    <literal>T</literal> and a unitary matrix <literal>U</literal> so that
 
128
                                    <literal>A = U*T*U'</literal> and <literal>U'*U =  eye(U)</literal>. By itself, schur(<literal>A</literal>) returns
 
129
                                    <literal>T</literal>. If <literal>A</literal> is complex, the Complex
 
130
                                    Schur Form is returned in matrix
 
131
                                    <literal>T</literal>. The Complex Schur Form is upper triangular with
 
132
                                    the eigenvalues of <literal>A</literal> on the diagonal. If
 
133
                                    <literal>A</literal> is real, the Real Schur Form is returned.  The Real
 
134
                                    Schur Form has the real eigenvalues on the diagonal and the
 
135
                                    complex eigenvalues in 2-by-2 blocks on the diagonal.
 
136
                                </para>
 
137
                            </listitem>
 
138
                        </varlistentry>
 
139
                        <varlistentry>
 
140
                            <term>Ordered Schur forms</term>
 
141
                            <listitem>
 
142
                                <para>
 
143
                                    <literal>[U,dim]=schur(A,'c')</literal> returns an unitary
 
144
                                    matrix <literal>U</literal> which transforms <literal>A</literal> into schur
 
145
                                    form.  In addition, the dim first columns of <literal>U</literal> make
 
146
                                    a basis of the eigenspace of <literal>A</literal> associated with
 
147
                                    eigenvalues with negative real parts (stable "continuous
 
148
                                    time" eigenspace).
 
149
                                </para>
 
150
                                <para>
 
151
                                    <literal>[U,dim]=schur(A,'d')</literal> returns an unitary
 
152
                                    matrix <literal>U</literal> which transforms <literal>A</literal> into schur
 
153
                                    form.  In addition, the <literal>dim</literal> first columns of
 
154
                                    <literal>U</literal> span a basis of the eigenspace of <literal>A</literal>
 
155
                                    associated with eigenvalues with magnitude lower than 1 (stable
 
156
                                    "discrete time" eigenspace).
 
157
                                </para>
 
158
                                <para>
 
159
                                    <literal>[U,dim]=schur(A,extern1)</literal> returns an unitary matrix
 
160
                                    <literal>U</literal> which transforms <literal>A</literal> into schur form.
 
161
                                    In addition, the <literal>dim</literal> first columns of
 
162
                                    <literal>U</literal> span a basis of the eigenspace of <literal>A</literal>
 
163
                                    associated with the eigenvalues which are selected by the
 
164
                                    external function <literal>extern1</literal> (see external for
 
165
                                    details).  This external can be described by a Scilab function
 
166
                                    or by C or Fortran procedure: 
 
167
                                </para>
 
168
                                <variablelist>
 
169
                                    <varlistentry>
 
170
                                        <term>a Scilab function</term>
 
171
                                        <listitem>
 
172
                                            <para>
 
173
                                                If <literal>extern1</literal> is described by a Scilab function, it
 
174
                                                should have the following calling sequence:
 
175
                                                <literal>s=extern1(Ev)</literal>, where <literal>Ev</literal> is an eigenvalue and
 
176
                                                <literal>s</literal> a boolean.
 
177
                                            </para>
 
178
                                        </listitem>
 
179
                                    </varlistentry>
 
180
                                    <varlistentry>
 
181
                                        <term>a C or Fortran procedure</term>
 
182
                                        <listitem>
 
183
                                            <para>
 
184
                                                If <literal>extern1</literal> is described by a C or Fortran function it
 
185
                                                should have the following calling sequence:
 
186
                                                <literal>int extern1(double *EvR, double *EvI)</literal>
 
187
                                                where <literal>EvR</literal> and <literal>EvI</literal> are  eigenvalue real and complex parts.
 
188
                                                a true or non zero returned value stands for selected eigenvalue.
 
189
                                            </para>
 
190
                                        </listitem>
 
191
                                    </varlistentry>
 
192
                                </variablelist>
 
193
                            </listitem>
 
194
                        </varlistentry>
 
195
                    </variablelist>
 
196
                </listitem>
 
197
            </varlistentry>
 
198
            <varlistentry>
 
199
                <term>PENCIL SCHUR FORMS</term>
 
200
                <listitem>
 
201
                    <variablelist>
 
202
                        <varlistentry>
 
203
                            <term>Usual Pencil Schur form</term>
 
204
                            <listitem>
 
205
                                <para>
 
206
                                    <literal>[As,Es] = schur(A,E)</literal> produces a quasi triangular
 
207
                                    <literal>As</literal> matrix and a triangular <literal>Es</literal> matrix
 
208
                                    which are the generalized Schur form of the pair <literal>A, E</literal>.
 
209
                                </para>
 
210
                                <para>
 
211
                                    <literal>[As,Es,Q,Z] = schur(A,E)</literal>
 
212
                                    returns in addition two unitary matrices
 
213
                                    <literal>Q</literal> and <literal>Z</literal> such that
 
214
                                    <literal>As=Q'*A*Z</literal> and <literal>Es=Q'*E*Z</literal>.
 
215
                                </para>
 
216
                            </listitem>
 
217
                        </varlistentry>
 
218
                        <varlistentry>
 
219
                            <term>Ordered Schur forms:</term>
 
220
                            <listitem>
 
221
                                <para>
 
222
                                    <literal>[As,Es,Z,dim] = schur(A,E,'c')</literal>
 
223
                                    returns the real generalized
 
224
                                    Schur form of the pencil <literal>s*E-A</literal>. In addition, the dim first columns 
 
225
                                    of <literal>Z</literal> span a basis of the right eigenspace  associated with 
 
226
                                    eigenvalues with negative real parts (stable "continuous
 
227
                                    time" generalized eigenspace).
 
228
                                </para>
 
229
                                <para>
 
230
                                    <literal>[As,Es,Z,dim] = schur(A,E,'d')</literal>
 
231
                                </para>
 
232
                                <para>
 
233
                                    returns the real generalized
 
234
                                    Schur form of the pencil <literal>s*E-A</literal>. In addition, the dim first columns 
 
235
                                    of <literal>Z</literal> make a basis of the right eigenspace  associated with 
 
236
                                    eigenvalues with magnitude lower than 1 (stable "discrete
 
237
                                    time" generalized eigenspace).
 
238
                                </para>
 
239
                                <para>
 
240
                                    <literal>[As,Es,Z,dim] = schur(A,E,extern2)</literal>
 
241
                                </para>
 
242
                                <para>
 
243
                                    returns the real generalized Schur form of the pencil <literal>s*E-A</literal>. 
 
244
                                    In addition, the dim first columns 
 
245
                                    of <literal>Z</literal> make a basis of the right eigenspace  associated with 
 
246
                                    eigenvalues of the pencil which are selected according to a
 
247
                                    rule which is given by the function <literal>extern2</literal>. (see external
 
248
                                    for details). This external can be described by a Scilab
 
249
                                    function or by C or Fortran procedure:      
 
250
                                </para>
 
251
                                <variablelist>
 
252
                                    <varlistentry>
 
253
                                        <term>A Scilab function</term>
 
254
                                        <listitem>
 
255
                                            <para>
 
256
                                                If <literal>extern2</literal> is described by a Scilab function, it should
 
257
                                                have the following calling sequence:
 
258
                                                <literal>s=extern2(Alpha,Beta)</literal>, where <literal>Alpha</literal> and
 
259
                                                <literal>Beta</literal> defines a generalized eigenvalue and
 
260
                                                <literal>s</literal> a boolean.
 
261
                                            </para>
 
262
                                        </listitem>
 
263
                                    </varlistentry>
 
264
                                    <varlistentry>
 
265
                                        <term>C or Fortran procedure</term>
 
266
                                        <listitem>
 
267
                                            <para>
 
268
                                                if external <literal>extern2</literal> is described by a C or a
 
269
                                                Fortran procedure, it should have the following calling
 
270
                                                sequence:
 
271
                                            </para>
 
272
                                            <para>
 
273
                                                <literal>int extern2(double *AlphaR, double *AlphaI, double *Beta)</literal>
 
274
                                            </para>
 
275
                                            <para>
 
276
                                                if <literal>A</literal> and <literal>E</literal> are real and
 
277
                                            </para>
 
278
                                            <para>
 
279
                                                <literal>int extern2(double *AlphaR, double *AlphaI, double *BetaR, double *BetaI)</literal>
 
280
                                            </para>
 
281
                                            <para>
 
282
                                                if <literal>A</literal> or <literal>E</literal> are complex.
 
283
                                                <literal>Alpha</literal>, and <literal>Beta</literal> defines the generalized eigenvalue.
 
284
                                                a true or non zero returned value stands for selected generalized eigenvalue.
 
285
                                            </para>
 
286
                                        </listitem>
 
287
                                    </varlistentry>
 
288
                                </variablelist>
 
289
                            </listitem>
 
290
                        </varlistentry>
 
291
                    </variablelist>
 
292
                </listitem>
 
293
            </varlistentry>
 
294
        </variablelist>
 
295
    </refsection>
 
296
    <refsection>
 
297
        <title>References</title>
 
298
        <para>
 
299
            Matrix schur form computations are based on the Lapack routines DGEES and ZGEES.
 
300
        </para>
 
301
        <para>
 
302
            Pencil schur form computations are based on the Lapack routines DGGES and ZGGES.
 
303
        </para>
 
304
    </refsection>
 
305
    <refsection>
 
306
        <title>Examples</title>
 
307
        <programlisting role="example"><![CDATA[ 
 
308
//SCHUR FORM OF A MATRIX
 
309
//----------------------
 
310
A=diag([-0.9,-2,2,0.9]);X=rand(A);A=inv(X)*A*X;
 
311
[U,T]=schur(A);T
 
312
 
 
313
[U,dim,T]=schur(A,'c');
 
314
T(1:dim,1:dim)      //stable cont. eigenvalues
 
315
 
 
316
function t=mytest(Ev),t=abs(Ev)<0.95,endfunction
 
317
[U,dim,T]=schur(A,mytest);
 
318
T(1:dim,1:dim)  
 
319
 
 
320
// The same function in C (a Compiler is required)
 
321
cd TMPDIR;
 
322
C=['int mytest(double *EvR, double *EvI) {' //the C code
 
323
   'if (*EvR * *EvR + *EvI * *EvI < 0.9025) return 1;'
 
324
   'else return 0; }';]
 
325
mputl(C,TMPDIR+'/mytest.c')
 
326
 
 
327
 
 
328
//build and link
 
329
lp=ilib_for_link('mytest','mytest.c',[],'c');
 
330
link(lp,'mytest','c'); 
 
331
 
 
332
//run it
 
333
[U,dim,T]=schur(A,'mytest');
 
334
//SCHUR FORM OF A PENCIL
 
335
//----------------------
 
336
F=[-1,%s, 0,   1;
 
337
    0,-1,5-%s, 0;
 
338
    0, 0,2+%s, 0;
 
339
    1, 0, 0, -2+%s];
 
340
A=coeff(F,0);E=coeff(F,1);
 
341
[As,Es,Q,Z]=schur(A,E);
 
342
Q'*F*Z //It is As+%s*Es
 
343
 
 
344
 
 
345
[As,Es,Z,dim] = schur(A,E,'c')
 
346
function t=mytest(Alpha,Beta),t=real(Alpha)<0,endfunction
 
347
[As,Es,Z,dim] = schur(A,E,mytest)
 
348
 
 
349
//the same function in Fortran (a Compiler is required)
 
350
ftn=['integer function mytestf(ar,ai,b)' //the fortran code
 
351
     'double precision ar,ai,b'
 
352
     'mytestf=0'
 
353
     'if(ar.lt.0.0d0) mytestf=1'
 
354
     'end']
 
355
mputl('      '+ftn,TMPDIR+'/mytestf.f')
 
356
 
 
357
//build and link
 
358
lp=ilib_for_link('mytestf','mytestf.f',[],'F');
 
359
link(lp,'mytestf','f'); 
 
360
 
 
361
//run it
 
362
 
 
363
[As,Es,Z,dim] = schur(A,E,'mytestf')
 
364
 ]]></programlisting>
 
365
    </refsection>
 
366
    <refsection role="see also">
 
367
        <title>See Also</title>
 
368
        <simplelist type="inline">
 
369
            <member>
 
370
                <link linkend="spec">spec</link>
 
371
            </member>
 
372
            <member>
 
373
                <link linkend="bdiag">bdiag</link>
 
374
            </member>
 
375
            <member>
 
376
                <link linkend="ricc">ricc</link>
 
377
            </member>
 
378
            <member>
 
379
                <link linkend="pbig">pbig</link>
 
380
            </member>
 
381
            <member>
 
382
                <link linkend="psmall">psmall</link>
 
383
            </member>
 
384
        </simplelist>
 
385
    </refsection>
 
386
</refentry>