* Bug #12020 fixed - Default value of ncv in eigs function was not documented.
[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. For real non-symmetric problems, the <literal>ncv</literal> value must be greater or equal than <literal>2 * k + 1 </literal> and, by default, <literal>ncv = min(max(2 * k + 1, 20), nA) </literal>. For real symmetric or complex problems, <literal>ncv</literal> must be greater or equal <literal>2 * k </literal> and, by default, <literal> ncv = min(max(2 * k, 20), nA) </literal> with <literal> nA = size(A, 2) </literal>.
267                                 </para>
268                             </para>
269                         </listitem>
270                         <listitem>
271                             <para>
272                                 <term>resid</term>
273                                 <para>
274                                     starting vector whose contains the initial residual vector, possibly from a previous run. By default,
275                                     <literal>resid</literal> is a random initial vector.
276                                 </para>
277                             </para>
278                         </listitem>
279                         <listitem>
280                             <para>
281                                 <term>cholB</term>
282                                 <para>
283                                     if <literal>chol(B)</literal> is passed rather than <literal>B</literal>. By default, <literal>cholB</literal> is %f.
284                                 </para>
285                             </para>
286                         </listitem>
287                         <listitem>
288                             <para>
289                                 <term>isreal</term>
290                                 <para>
291                                     if <literal>Af</literal> is given, <literal>isreal</literal> can be defined. By default, <literal>isreal</literal> is %t.
292                                     This argument should not be indicated if <literal>A</literal> is a matrix.
293                                 </para>
294                             </para>
295                         </listitem>
296                         <listitem>
297                             <para>
298                                 <term>issym</term>
299                                 <para>
300                                     if <literal>Af</literal> is given, <literal>issym</literal> can be defined. By default, <literal>issym</literal> is %f.
301                                     This argument should not be indicated if <literal>A</literal> is a matrix.
302                                 </para>
303                             </para>
304                         </listitem>
305                     </itemizedlist>
306                 </listitem>
307             </varlistentry>
308         </variablelist>
309     </refsection>
310     <refsection>
311         <title>References</title>
312         <para>
313             This function is based on the ARPACK package written by R. Lehoucq, K. Maschhoff, D. Sorensen, and C. Yang.
314         </para>
315         <itemizedlist>
316             <listitem>
317                 <para>DSAUPD and DSEUPD routines for real symmetric problems,</para>
318             </listitem>
319             <listitem>
320                 <para>DNAUPD and DNEUPD routines for real non-symmetric problems.</para>
321             </listitem>
322             <listitem>
323                 <para>ZNAUPD and ZNEUPD routines for complex problems.</para>
324             </listitem>
325         </itemizedlist>
326     </refsection>
327     <refsection>
328         <title>Example for real symmetric problems</title>
329         <programlisting role="example">
330             <![CDATA[ 
331 A            = diag(10*ones(10,1));
332 A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
333 A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6*ones(9,1));
334
335 B = eye(10,10);
336 k = 8;
337 sigma = 'SM';
338 opts.cholB = %t;
339
340 d = eigs(A)
341 [d, v] = eigs(A)
342
343 d = eigs(A, B, k, sigma)
344 [d, v] = eigs(A, B, k, sigma)
345
346 d = eigs(A, B, k, sigma, opts)
347 [d, v] = eigs(A, B, k, sigma, opts)
348
349 // With sparses
350 AS = sparse(A);
351 BS = sparse(B);
352
353 d = eigs(AS)
354 [d, v] = eigs(AS)
355
356 d = eigs(AS, BS, k, sigma)
357 [d, v] = eigs(AS, BS, k, sigma)
358
359 d = eigs(AS, BS, k, sigma, opts)
360 [d, v] = eigs(AS, BS, k, sigma, opts)
361
362 // With function
363 clear opts
364 function y = fn(x)
365    y = A * x;
366 endfunction
367
368 opts.isreal = %t;
369 opts.issym = %t;
370
371 d = eigs(fn, 10, [], k, 'LM', opts)
372
373 function y = fn(x)
374    y = A \ x;
375 endfunction
376
377 d = eigs(fn, 10, [], k, 'SM', opts)
378
379 function y = fn(x)
380    y = (A - 4 * eye(10,10)) \ x;
381 endfunction
382
383 d = eigs(fn, 10, [], k, 4, opts)
384  ]]>
385         </programlisting>
386     </refsection>
387     <refsection>
388         <title>Example for real non-symmetric problems</title>
389         <programlisting role="example">
390             <![CDATA[ 
391     A            = diag(10*ones(10,1));
392     A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
393     A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1));
394
395     B = eye(10,10);
396     k = 8;
397     sigma = 'SM';
398     opts.cholB = %t;
399     
400     d = eigs(A)
401 [d, v] = eigs(A)
402     
403     d = eigs(A, B, k, sigma)
404     [d, v] = eigs(A, B, k, sigma) 
405
406     d = eigs(A, B, k, sigma, opts)
407     [d, v] = eigs(A, B, k, sigma, opts)
408
409 // With sparses
410     AS = sparse(A);
411     BS = sparse(B);
412
413 d = eigs(AS)
414 [d, v] = eigs(AS)
415     d = eigs(AS, BS, k, sigma)
416     [d, v] = eigs(AS, BS, k, sigma)
417
418     d = eigs(AS, BS, k, sigma, opts)
419     [d, v] = eigs(AS, BS, k, sigma, opts)
420     
421     // With function
422 clear opts
423 function y = fn(x)
424    y = A * x;
425 endfunction
426
427 opts.isreal = %t;
428 opts.issym = %f;
429
430 d = eigs(fn, 10, [], k, 'LM', opts)
431
432 function y = fn(x)
433    y = A \ x;
434 endfunction
435
436 d = eigs(fn, 10, [], k, 'SM', opts)
437
438 function y = fn(x)
439    y = (A - 4 * eye(10,10)) \ x;
440 endfunction
441
442 d = eigs(fn, 10, [], k, 4, opts)
443     ]]>
444         </programlisting>
445     </refsection>
446     <refsection>
447         <title>Example for complex problems</title>
448         <programlisting role="example">
449             <![CDATA[ 
450     A            = diag(10*ones(10,1) + %i * ones(10,1));
451     A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
452     A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1));
453
454     B = eye(10,10);
455     k = 8;
456     sigma = 'LM';
457     opts.cholB = %t;
458     
459     d = eigs(A)
460 [d, v] = eigs(A)
461
462     d = eigs(A, B, k, sigma)
463     [d, v] = eigs(A, B, k, sigma)
464     d = eigs(A, B, k, sigma, opts)
465     [d, v] = eigs(A, B, k, sigma, opts)
466     
467     // With sparses
468     AS = sparse(A);
469     BS = sparse(B);
470     
471     d = eigs(AS)
472 [d, v] = eigs(AS)
473
474     d = eigs(AS, BS, k, sigma)
475     [d, v] = eigs(AS, BS, k, sigma)
476
477     d = eigs(AS, BS, k, sigma, opts)
478     [d, v] = eigs(AS, BS, k, sigma, opts)
479     
480     // With function
481 clear opts
482 function y = fn(x)
483    y = A * x;
484 endfunction
485
486 opts.isreal = %f;
487 opts.issym = %f;
488
489 d = eigs(fn, 10, [], k, 'LM', opts)
490
491 function y = fn(x)
492    y = A \ x;
493 endfunction
494
495 d = eigs(fn, 10, [], k, 'SM', opts)
496
497 function y = fn(x)
498    y = (A - 4 * eye(10,10)) \ x;
499 endfunction
500
501 d = eigs(fn, 10, [], k, 4, opts)
502     ]]>
503         </programlisting>
504     </refsection>
505     <refsection role="see also">
506         <title>See Also</title>
507         <simplelist type="inline">
508             <member>
509                 <link linkend="spec">spec</link>
510             </member>
511         </simplelist>
512     </refsection>
513     <refsection>
514         <title>History</title>
515         <revhistory>
516             <revision>
517                 <revnumber>5.4.0</revnumber>
518                 <revremark>Function introduced. Deprecates dnaupd, dneupd, dsaupd, dseupd, znaupd and zneupd.</revremark>
519             </revision>
520         </revhistory>
521     </refsection>
522 </refentry>