94ec88dc9bb8d876ef00a36492b58f54db9e185b
[scilab.git] / scilab / modules / arnoldi / help / en_US / eigs.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) 2012 - Scilab Enterprises - Adeline CARNIS
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: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="eigs" xml:lang="en">
14     <refnamediv>
15         <refname>eigs</refname>
16         <refpurpose>calculates largest eigenvalues and eigenvectors of matrices</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>
21             d = eigs(A [,B [,k [,sigma [,opts]]]])
22             [d, v] = eigs(A [,B [,k [,sigma [,opts]]]])
23             
24             d = eigs(Af, n [,B [,k [,sigma [,opts]]]])
25             [d, v] = eigs(Af, n [,B [,k [,sigma [,opts]]]])
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>A </term>
33                 <listitem>
34                     <para>a full or sparse, real or complex, symmetric or non-symmetric square matrix</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>Af </term>
39                 <listitem>
40                     <para>a function</para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>n </term>
45                 <listitem>
46                     <para>
47                         a scalar, defined only if <literal>A</literal> is a function
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>B</term>
53                 <listitem>
54                     <para>
55                         a sparse, real or complex, square matrix with same dimensions as
56                         <literal> A</literal>
57                     </para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>k</term>
62                 <listitem>
63                     <para>an integer, number of eigenvalues to be computed</para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>sigma</term>
68                 <listitem>
69                     <para>a real scalar or a string of length 2</para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>opts</term>
74                 <listitem>
75                     <para>a structure</para>
76                 </listitem>
77             </varlistentry>
78             <varlistentry>
79                 <term>d</term>
80                 <listitem>
81                     <para>a real or complex eigenvalues vector or diagonal matrix (eigenvalues along the diagonal)</para>
82                 </listitem>
83             </varlistentry>
84             <varlistentry>
85                 <term>v</term>
86                 <listitem>
87                     <para>
88                         real or complex eigenvector matrix
89                     </para>
90                 </listitem>
91             </varlistentry>
92         </variablelist>
93     </refsection>
94     <refsection>
95       <title>Description</title>
96       <para>
97         The purpose of the eigs function is to compute the largest eigenvalues of sparse, large matrices.
98       </para>
99       <variablelist>
100             <varlistentry>
101                 <term>d = eigs(A) or d = eigs(Af, n)</term>
102                 <listitem>
103                     <para>
104                         solves the eigenvalue problem <literal>A * v = lambda * v</literal>. This calling returns a vector <literal>d</literal> containing the six largest magnitude eigenvalues.
105                         <literal>A</literal> is either a square matrix, which can be symmetric or non-symmetric, real or complex, full or sparse.
106                     </para>
107                     <para>
108                         <literal>A</literal> should be represented by a function <literal>Af</literal>. In this instance, a scalar <literal>n</literal> designating
109                         the length of the vector argument, must be defined. It must have the following header :
110                     </para>
111                     <programlisting role="no-scilab-exec">
112                         <![CDATA[ 
113 function y = A ( x )
114  ]]>
115                     </programlisting>
116                     <para>
117                         This function <literal>Af</literal> must return one of the four following expressions :
118                         <itemizedlist>
119                             <listitem>
120                                 <term>A * x</term>
121                                 <para> if sigma is not given or is a string other than 'SM'.</para>
122                             </listitem>
123                             <listitem>
124                                 <term>A \ x</term>
125                                 <para> if sigma is 0 or 'SM'.</para>
126                             </listitem>
127                             <listitem>
128                                 <term>(A - sigma * I) \ x</term>
129                                 <para>for the standard eigenvalue problem, where I is the identity matrix.</para>
130                             </listitem>
131                             <listitem>
132                                 <term>(A - sigma * B) \ x</term>
133                                 <para> for the generalized eigenvalue problem.</para>
134                             </listitem>
135                         </itemizedlist>
136                     </para>
137                 </listitem>
138             </varlistentry>
139             <varlistentry>
140                 <term>[d, v] = eigs(A) or [d, v] = eigs(Af, n)</term>
141                 <listitem>
142                     <para>
143                         returns a diagonal matrix <literal>d</literal> containing the six largest magnitude eigenvalues on the diagonal.
144                         <literal>v</literal> is a n by six matrix whose columns are the six eigenvectors corresponding to the returned eigenvalues.
145                     </para>
146                 </listitem>
147             </varlistentry>
148             <varlistentry>
149                 <term>d = eigs(A, B)</term>
150                 <listitem>
151                     <para>
152                         solves the generalized eigenvalue problem <literal>A * v = lambda  * B * v </literal> with positive, definite matrix <literal>B</literal>.
153                     </para>
154                     <itemizedlist>
155                         <listitem>
156                             <para>
157                                 if <literal>B</literal> is not specified, <literal>B = []</literal> is used.
158                             </para>
159                         </listitem>
160                         <listitem>
161                             <para>
162                                 if <literal>B</literal> is specified, <literal>B</literal> must be the same size as A.
163                             </para>
164                         </listitem>
165                     </itemizedlist>
166                 </listitem>
167             </varlistentry>
168             <varlistentry>
169                 <term>d = eigs(A, B, k)</term>
170                 <listitem>
171                     <para>
172                         returns in vector <literal>d</literal> the <literal>k</literal> eigenvalues.
173                         If <literal>k</literal> is not specified, <literal>k = min(n, 6)</literal>, where n is the row number of A.
174                     </para>
175                 </listitem>
176             </varlistentry>
177             <varlistentry>
178                 <term>d = eigs(A, B, k, sigma)</term>
179                 <listitem>
180                     <para>
181                         returns in vector <literal>d</literal> the <literal>k</literal> eigenvalues determined by <literal>sigma</literal>.
182                         <literal>sigma</literal> can be either a real or complex including 0 scalar or string.
183                         If sigma is a string of length 2, it takes one of the following values :
184                     </para>
185                     <itemizedlist>
186                         <listitem>
187                             <para>
188                                 <literal>'LM'</literal> compute the <varname>k</varname> largest in magnitude eigenvalues (by default).
189                             </para>
190                         </listitem>
191                         <listitem>
192                             <para>
193                                 <literal>'SM'</literal> compute the <varname>k</varname> smallest in magnitude eigenvalues (same as sigma = 0).
194                             </para>
195                         </listitem>
196                         <listitem>
197                             <para>
198                                 <literal>'LA'</literal> compute the <varname>k</varname> Largest Algebraic eigenvalues, only for real symmetric problems.
199                             </para>
200                         </listitem>
201                         <listitem>
202                             <para>
203                                 <literal>'SA'</literal> compute the <varname>k</varname> Smallest Algebraic eigenvalues, only for real symmetric problems.
204                             </para>
205                         </listitem>
206                         <listitem>
207                             <para>
208                                 <literal>'BE'</literal> compute <varname>k</varname> eigenvalues, half from each end of the spectrum, only for real 
209                                 symmetric problems.
210                             </para>
211                         </listitem>
212                         <listitem>
213                             <para>
214                                 <literal>'LR'</literal> compute the <varname>k</varname> eigenvalues of Largest Real part, only for real non-symmetric or 
215                                 complex problems.
216                             </para>
217                         </listitem>
218                         <listitem>
219                             <para>
220                                 <literal>'SR'</literal> compute the <varname>k</varname> eigenvalues of Smallest Real part, only for real non-symmetric or 
221                                 complex problems.
222                             </para>
223                         </listitem>
224                         <listitem>
225                             <para>
226                                 <literal>'LI'</literal> compute the <varname>k</varname> eigenvalues of Largest Imaginary part, only for real non-symmetric 
227                                 or complex problems.
228                             </para>
229                         </listitem>
230                         <listitem>
231                             <para>
232                                 <literal>'SI'</literal> compute the <varname>k</varname> eigenvalues of Smallest Imaginary part, only for real non-symmetric 
233                                 or complex problems.
234                             </para>
235                         </listitem>
236                     </itemizedlist>
237                 </listitem>
238             </varlistentry>
239             <varlistentry>
240                 <term>d = eigs(A, B, k, sigma, opts)</term>
241                 <listitem>
242                     <para>
243                         If the <literal> opts </literal> structure is specified, different options can be used to compute the <literal>k</literal> eigenvalues :
244                     </para>
245                     <itemizedlist>
246                         <listitem>
247                             <para>
248                                 <term>tol</term>
249                                 <para>
250                                     required convergence tolerance. By default, <literal>tol = %eps</literal>.
251                                 </para>
252                             </para>
253                         </listitem>
254                         <listitem>
255                             <para>
256                                 <term>maxiter</term>
257                                 <para>
258                                     maximum number of iterations. By default, <literal>maxiter = 300</literal>.
259                                 </para>
260                             </para>
261                         </listitem>
262                         <listitem>
263                             <para>
264                                 <term>ncv</term>
265                                 <para>
266                                     number of Lanzcos basis vectors to use. The <literal>ncv</literal> value must be greater or equal than <literal>2 * k + 1 </literal> for real non-symmetric
267                                     problems. For real symmetric or complex problems, <literal>ncv</literal> must be greater or equal <literal>2 * k </literal>.
268                                 </para>
269                             </para>
270                         </listitem>
271                         <listitem>
272                             <para>
273                                 <term>resid</term>
274                                 <para>
275                                     starting vector whose contains the initial residual vector, possibly from a previous run. By default,
276                                     <literal>resid</literal> is a random initial vector.
277                                 </para>
278                             </para>
279                         </listitem>
280                         <listitem>
281                             <para>
282                                 <term>cholB</term>
283                                 <para>
284                                     if <literal>chol(B)</literal> is passed rather than <literal>B</literal>. By default, <literal>cholB</literal> is %f.
285                                 </para>
286                             </para>
287                         </listitem>
288                         <listitem>
289                             <para>
290                                 <term>isreal</term>
291                                 <para>
292                                     if <literal>Af</literal> is given, <literal>isreal</literal> can be defined. By default, <literal>isreal</literal> is %t.
293                                     This argument should not be indicated if <literal>A</literal> is a matrix.
294                                 </para>
295                             </para>
296                         </listitem>
297                         <listitem>
298                             <para>
299                                 <term>issym</term>
300                                 <para>
301                                     if <literal>Af</literal> is given, <literal>issym</literal> can be defined. By default, <literal>issym</literal> is %f.
302                                     This argument should not be indicated if <literal>A</literal> is a matrix.
303                                 </para>
304                             </para>
305                         </listitem>
306                     </itemizedlist>
307                 </listitem>
308             </varlistentry>
309         </variablelist>
310     </refsection>
311     <refsection>
312         <title>References</title>
313         <para>
314             This function is based on the ARPACK package written by R. Lehoucq, K. Maschhoff, D. Sorensen, and C. Yang.
315         </para>
316         <itemizedlist>
317             <listitem>
318                 <para>DSAUPD and DSEUPD routines for real symmetric problems,</para>
319             </listitem>
320             <listitem>
321                 <para>DNAUPD and DNEUPD routines for real non-symmetric problems.</para>
322             </listitem>
323             <listitem>
324                 <para>ZNAUPD and ZNEUPD routines for complex problems.</para>
325             </listitem>
326         </itemizedlist>
327     </refsection>
328     <refsection>
329         <title>Example for real symmetric problems</title>
330         <programlisting role="example">
331             <![CDATA[ 
332 A            = diag(10*ones(10,1));
333 A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
334 A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6*ones(9,1));
335
336 B = eye(10,10);
337 k = 8;
338 sigma = 'SM';
339 opts.cholB = %t;
340
341 d = eigs(A)
342 [d, v] = eigs(A)
343
344 d = eigs(A, B, k, sigma)
345 [d, v] = eigs(A, B, k, sigma)
346
347 d = eigs(A, B, k, sigma, opts)
348 [d, v] = eigs(A, B, k, sigma, opts)
349
350 // With sparses
351 AS = sparse(A);
352 BS = sparse(B);
353
354 d = eigs(AS)
355 [d, v] = eigs(AS)
356
357 d = eigs(AS, BS, k, sigma)
358 [d, v] = eigs(AS, BS, k, sigma)
359
360 d = eigs(AS, BS, k, sigma, opts)
361 [d, v] = eigs(AS, BS, k, sigma, opts)
362
363 // With function
364 clear opts
365 function y = fn(x)
366    y = A * x;
367 endfunction
368
369 opts.isreal = %t;
370 opts.issym = %t;
371
372 d = eigs(fn, 10, [], k, 'LM', opts)
373
374 function y = fn(x)
375    y = A \ x;
376 endfunction
377
378 d = eigs(fn, 10, [], k, 'SM', opts)
379
380 function y = fn(x)
381    y = (A - 4 * eye(10,10)) \ x;
382 endfunction
383
384 d = eigs(fn, 10, [], k, 4, opts)
385  ]]>
386         </programlisting>
387     </refsection>
388     <refsection>
389         <title>Example for real non-symmetric problems</title>
390         <programlisting role="example">
391             <![CDATA[ 
392     A            = diag(10*ones(10,1));
393     A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
394     A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1));
395
396     B = eye(10,10);
397     k = 8;
398     sigma = 'SM';
399     opts.cholB = %t;
400     
401     d = eigs(A)
402 [d, v] = eigs(A)
403     
404     d = eigs(A, B, k, sigma)
405     [d, v] = eigs(A, B, k, sigma) 
406
407     d = eigs(A, B, k, sigma, opts)
408     [d, v] = eigs(A, B, k, sigma, opts)
409
410 // With sparses
411     AS = sparse(A);
412     BS = sparse(B);
413
414 d = eigs(AS)
415 [d, v] = eigs(AS)
416     d = eigs(AS, BS, k, sigma)
417     [d, v] = eigs(AS, BS, k, sigma)
418
419     d = eigs(AS, BS, k, sigma, opts)
420     [d, v] = eigs(AS, BS, k, sigma, opts)
421     
422     // With function
423 clear opts
424 function y = fn(x)
425    y = A * x;
426 endfunction
427
428 opts.isreal = %t;
429 opts.issym = %f;
430
431 d = eigs(fn, 10, [], k, 'LM', opts)
432
433 function y = fn(x)
434    y = A \ x;
435 endfunction
436
437 d = eigs(fn, 10, [], k, 'SM', opts)
438
439 function y = fn(x)
440    y = (A - 4 * eye(10,10)) \ x;
441 endfunction
442
443 d = eigs(fn, 10, [], k, 4, opts)
444     ]]>
445         </programlisting>
446     </refsection>
447     <refsection>
448         <title>Example for complex problems</title>
449         <programlisting role="example">
450             <![CDATA[ 
451     A            = diag(10*ones(10,1) + %i * ones(10,1));
452     A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
453     A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1));
454
455     B = eye(10,10);
456     k = 8;
457     sigma = 'LM';
458     opts.cholB = %t;
459     
460     d = eigs(A)
461 [d, v] = eigs(A)
462
463     d = eigs(A, B, k, sigma)
464     [d, v] = eigs(A, B, k, sigma)
465     d = eigs(A, B, k, sigma, opts)
466     [d, v] = eigs(A, B, k, sigma, opts)
467     
468     // With sparses
469     AS = sparse(A);
470     BS = sparse(B);
471     
472     d = eigs(AS)
473 [d, v] = eigs(AS)
474
475     d = eigs(AS, BS, k, sigma)
476     [d, v] = eigs(AS, BS, k, sigma)
477
478     d = eigs(AS, BS, k, sigma, opts)
479     [d, v] = eigs(AS, BS, k, sigma, opts)
480     
481     // With function
482 clear opts
483 function y = fn(x)
484    y = A * x;
485 endfunction
486
487 opts.isreal = %f;
488 opts.issym = %f;
489
490 d = eigs(fn, 10, [], k, 'LM', opts)
491
492 function y = fn(x)
493    y = A \ x;
494 endfunction
495
496 d = eigs(fn, 10, [], k, 'SM', opts)
497
498 function y = fn(x)
499    y = (A - 4 * eye(10,10)) \ x;
500 endfunction
501
502 d = eigs(fn, 10, [], k, 4, opts)
503     ]]>
504         </programlisting>
505     </refsection>
506     <refsection role="see also">
507         <title>See Also</title>
508         <simplelist type="inline">
509             <member>
510                 <link linkend="spec">spec</link>
511             </member>
512         </simplelist>
513     </refsection>
514     <refsection>
515         <title>History</title>
516         <revhistory>
517             <revision>
518                 <revnumber>5.4.0</revnumber>
519                 <revremark>Function introduced. Deprecates dnaupd, dneupd, dsaupd, dseupd, znaupd and zneupd.</revremark>
520             </revision>
521         </revhistory>
522     </refsection>
523 </refentry>