4565a68fdd6ea29da0003f6fecf0c537a2e43289
[scilab.git] / scilab / modules / linear_algebra / help / en_US / eigen / spec.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.1-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:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="spec" xml:lang="en">
14     <refnamediv>
15         <refname>spec</refname>
16         <refpurpose>eigenvalues of matrices and pencils</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>evals=spec(A)
21             [R,diagevals]=spec(A)
22             
23             evals=spec(A,B)
24             [alpha,beta]=spec(A,B)
25             [alpha,beta,Z]=spec(A,B)
26             [alpha,beta,Q,Z]=spec(A,B)
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>A</term>
34                 <listitem>
35                     <para>real or complex square matrix</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>B</term>
40                 <listitem>
41                     <para>real or complex square matrix with same dimensions as
42                         <literal> A</literal>
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>evals</term>
48                 <listitem>
49                     <para>real or complex vector, the eigenvalues</para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>diagevals</term>
54                 <listitem>
55                     <para>real or complex diagonal matrix (eigenvalues along the
56                         diagonal)
57                     </para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>alpha</term>
62                 <listitem>
63                     <para>real or complex vector, al./be gives the eigenvalues</para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>beta</term>
68                 <listitem>
69                     <para>real vector, al./be gives the eigenvalues</para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>R</term>
74                 <listitem>
75                     <para>real or complex invertible square matrix, matrix right
76                         eigenvectors.
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>L</term>
82                 <listitem>
83                     <para>real or complex invertible square matrix, pencil left
84                         eigenvectors.
85                     </para>
86                 </listitem>
87             </varlistentry>
88             <varlistentry>
89                 <term>R</term>
90                 <listitem>
91                     <para>real or complex invertible square matrix, pencil right
92                         eigenvectors.
93                     </para>
94                 </listitem>
95             </varlistentry>
96         </variablelist>
97     </refsection>
98     <refsection>
99         <title>Description</title>
100         <variablelist>
101             <varlistentry>
102                 <term>evals=spec(A)</term>
103                 <listitem>
104                     <para>
105                         returns in vector <literal>evals</literal> the
106                         eigenvalues.
107                     </para>
108                 </listitem>
109             </varlistentry>
110             <varlistentry>
111                 <term>[R,diagevals] =spec(A)</term>
112                 <listitem>
113                     <para>
114                         returns in the diagonal matrix <literal>evals</literal> the
115                         eigenvalues and in <literal>R</literal> the right
116                         eigenvectors.
117                     </para>
118                 </listitem>
119             </varlistentry>
120             <varlistentry>
121                 <term>evals=spec(A,B)</term>
122                 <listitem>
123                     <para>returns the spectrum of the matrix pencil A - s B, i.e. the
124                         roots of the polynomial matrix s B - A.
125                     </para>
126                 </listitem>
127             </varlistentry>
128             <varlistentry>
129                 <term>[alpha,beta] = spec(A,B)</term>
130                 <listitem>
131                     <para>
132                         returns the spectrum of the matrix pencil <literal>A- s
133                             B
134                         </literal>
135                         ,i.e. the roots of the polynomial matrix <literal>A - s
136                             B
137                         </literal>
138                         .Generalized eigenvalues alpha and beta are so that the
139                         matrix <literal>A - alpha./beta B</literal> is a singular matrix.
140                         The eigenvalues are given by <literal>al./be</literal> and if
141                         <literal>beta(i) = 0</literal> the ith eigenvalue is at infinity.
142                         (For <literal>B = eye(A), alpha./beta</literal> is
143                         <literal>spec(A)</literal>). It is usually represented as the pair
144                         (alpha,beta), as there is a reasonable interpretation for beta=0,
145                         and even for both being zero.
146                     </para>
147                 </listitem>
148             </varlistentry>
149             <varlistentry>
150                 <term>[alpha,beta,R] = spec(A,B)</term>
151                 <listitem>
152                     <para>
153                         returns in addition the matrix <literal>R</literal> of
154                         generalized right eigenvectors of the pencil.
155                     </para>
156                 </listitem>
157             </varlistentry>
158             <varlistentry>
159                 <term>[al,be,L,R] = spec(A,B)</term>
160                 <listitem>
161                     <para>
162                         returns in addition the matrix <literal>L</literal> and
163                         <literal>R</literal> of generalized left and right eigenvectors of
164                         the pencil.
165                     </para>
166                 </listitem>
167             </varlistentry>
168             <varlistentry>
169                 <term>[al,be,Z] = spec(A,E)</term>
170                 <listitem>
171                     <para>
172                         returns the matrix <literal>Z</literal> of right
173                         generalized eigen vectors.
174                     </para>
175                 </listitem>
176             </varlistentry>
177             <varlistentry>
178                 <term>[al,be,Q,Z] = spec(A,E)</term>
179                 <listitem>
180                     <para>
181                         returns the matrices <literal>Q</literal>
182                         and <literal>Z</literal> of right and left generalized
183                         eigen vectors.
184                     </para>
185                 </listitem>
186             </varlistentry>
187         </variablelist>
188         <para>For big full / sparse matrix, you can use the Arnoldi module.</para>
189     </refsection>
190     <refsection>
191         <title>References</title>
192         <para>Matrix eigenvalues computations are based on the Lapack
193             routines
194         </para>
195         <itemizedlist>
196             <listitem>
197                 <para>DGEEV and ZGEEV when the matrix are not symmetric,</para>
198             </listitem>
199             <listitem>
200                 <para>DSYEV and ZHEEV when the matrix are symmetric.</para>
201             </listitem>
202         </itemizedlist>
203         <para>A complex symmetric matrix has conjugate offdiagonal terms and real
204             diagonal terms.
205         </para>
206         <para>Pencil eigenvalues computations are based on the Lapack routines
207             DGGEV and ZGGEV.
208         </para>
209     </refsection>
210     <refsection>
211         <title>Real and complex matrices</title>
212         <para>It must be noticed that the type of the output variables, such as
213             evals or R for example, is not necessarily the same as the type of the
214             input matrices A and B. In the following paragraph, we analyse the type of
215             the output variables in the case where one computes the eigenvalues and
216             eigenvectors of one single matrix A.
217         </para>
218         <itemizedlist>
219             <listitem>
220                 <para>Real A matrix</para>
221                 <itemizedlist>
222                     <listitem>
223                         <para>Symetric</para>
224                         <para>The eigenvalues and the eigenvectors are real.</para>
225                     </listitem>
226                     <listitem>
227                         <para>Not symmetric</para>
228                         <para>The eigenvalues and eigenvectors are complex.</para>
229                     </listitem>
230                 </itemizedlist>
231             </listitem>
232             <listitem>
233                 <para>Complex A matrix</para>
234                 <itemizedlist>
235                     <listitem>
236                         <para>Symetric</para>
237                         <para>The eigenvalues are real but the eigenvectors are
238                             complex.
239                         </para>
240                     </listitem>
241                     <listitem>
242                         <para>Not symmetric</para>
243                         <para>The eigenvalues and the eigenvectors are complex.</para>
244                     </listitem>
245                 </itemizedlist>
246             </listitem>
247         </itemizedlist>
248     </refsection>
249     <refsection>
250         <title>Examples</title>
251         <programlisting role="example"><![CDATA[ 
252 // MATRIX EIGENVALUES
253 A=diag([1,2,3]);
254 X=rand(3,3);
255 A=inv(X)*A*X;
256 spec(A)
257
258 x=poly(0,'x');
259 pol=det(x*eye()-A)
260 roots(pol)
261
262 [S,X]=bdiag(A);
263 clean(inv(X)*A*X)
264
265 // PENCIL EIGENVALUES
266 A=rand(3,3);
267 [al,be,R] = spec(A,eye(A));
268 al./be
269 clean(inv(R)*A*R)  //displaying the eigenvalues (generic matrix)
270 A=A+%i*rand(A);
271 E=rand(A);
272 roots(det(A-%s*E))   //complex case
273  ]]></programlisting>
274     </refsection>
275     <refsection role="see also">
276         <title>See Also</title>
277         <simplelist type="inline">
278             <member>
279                 <link linkend="poly">poly</link>
280             </member>
281             <member>
282                 <link linkend="det">det</link>
283             </member>
284             <member>
285                 <link linkend="schur">schur</link>
286             </member>
287             <member>
288                 <link linkend="bdiag">bdiag</link>
289             </member>
290             <member>
291                 <link linkend="colcomp">colcomp</link>
292             </member>
293             <member>
294                 <link linkend="dsaupd">dsaupd</link>
295             </member>
296             <member>
297                 <link linkend="dnaupd">dnaupd</link>
298             </member>
299         </simplelist>
300     </refsection>
301 </refentry>