Mercurial > octave

comparison scripts/sparse/eigs.m @ 19596:0e1f5a750d00

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
maint: Periodic merge of gui-release to default.
author John W. Eaton <jwe@octave.org>
date Tue, 20 Jan 2015 10:24:46 -0500
parents 0850b5212619 446c46af4b42
children db92e7e28e1f
comparison
equal deleted inserted replaced
19592:37d37297acf8 19596:0e1f5a750d00
38 ## @deftypefnx {Function File} {[@var{V}, @var{d}, @var{flag}] =} eigs (@var{A}, @dots{}) 38 ## @deftypefnx {Function File} {[@var{V}, @var{d}, @var{flag}] =} eigs (@var{A}, @dots{})
39 ## @deftypefnx {Function File} {[@var{V}, @var{d}, @var{flag}] =} eigs (@var{af}, @var{n}, @dots{}) 39 ## @deftypefnx {Function File} {[@var{V}, @var{d}, @var{flag}] =} eigs (@var{af}, @var{n}, @dots{})
40 ## Calculate a limited number of eigenvalues and eigenvectors of @var{A}, 40 ## Calculate a limited number of eigenvalues and eigenvectors of @var{A},
41 ## based on a selection criteria. The number of eigenvalues and eigenvectors to 41 ## based on a selection criteria. The number of eigenvalues and eigenvectors to
42 ## calculate is given by @var{k} and defaults to 6. 42 ## calculate is given by @var{k} and defaults to 6.
43 ## 43 ##
44 ## By default, @code{eigs} solve the equation 44 ## By default, @code{eigs} solve the equation
45 ## @tex 45 ## @tex
46 ## $A \nu = \lambda \nu$, 46 ## $A \nu = \lambda \nu$,
47 ## @end tex 47 ## @end tex
48 ## @ifinfo 48 ## @ifinfo
61 ## $A \nu = \lambda B \nu$. 61 ## $A \nu = \lambda B \nu$.
62 ## @end tex 62 ## @end tex
63 ## @ifinfo 63 ## @ifinfo
64 ## @code{A * v = lambda * B * v}. 64 ## @code{A * v = lambda * B * v}.
65 ## @end ifinfo 65 ## @end ifinfo
66 ## 66 ##
67 ## The argument @var{sigma} determines which eigenvalues are returned. 67 ## The argument @var{sigma} determines which eigenvalues are returned.
68 ## @var{sigma} can be either a scalar or a string. When @var{sigma} is a 68 ## @var{sigma} can be either a scalar or a string. When @var{sigma} is a
69 ## scalar, the @var{k} eigenvalues closest to @var{sigma} are returned. If 69 ## scalar, the @var{k} eigenvalues closest to @var{sigma} are returned. If
70 ## @var{sigma} is a string, it must have one of the following values. 70 ## @var{sigma} is a string, it must have one of the following values.
71 ## 71 ##
72 ## @table @asis 72 ## @table @asis
73 ## @item @qcode{"lm"} 73 ## @item @qcode{"lm"}
74 ## Largest Magnitude (default). 74 ## Largest Magnitude (default).
75 ## 75 ##
76 ## @item @qcode{"sm"} 76 ## @item @qcode{"sm"}
77 ## Smallest Magnitude. 77 ## Smallest Magnitude.
78 ## 78 ##
79 ## @item @qcode{"la"} 79 ## @item @qcode{"la"}
80 ## Largest Algebraic (valid only for real symmetric problems). 80 ## Largest Algebraic (valid only for real symmetric problems).
81 ## 81 ##
82 ## @item @qcode{"sa"} 82 ## @item @qcode{"sa"}
83 ## Smallest Algebraic (valid only for real symmetric problems). 83 ## Smallest Algebraic (valid only for real symmetric problems).
84 ## 84 ##
85 ## @item @qcode{"be"} 85 ## @item @qcode{"be"}
86 ## Both Ends, with one more from the high-end if @var{k} is odd (valid only for 86 ## Both Ends, with one more from the high-end if @var{k} is odd (valid only for
87 ## real symmetric problems). 87 ## real symmetric problems).
88 ## 88 ##
89 ## @item @qcode{"lr"} 89 ## @item @qcode{"lr"}
90 ## Largest Real part (valid only for complex or unsymmetric problems). 90 ## Largest Real part (valid only for complex or unsymmetric problems).
91 ## 91 ##
92 ## @item @qcode{"sr"} 92 ## @item @qcode{"sr"}
93 ## Smallest Real part (valid only for complex or unsymmetric problems). 93 ## Smallest Real part (valid only for complex or unsymmetric problems).
94 ## 94 ##
95 ## @item @qcode{"li"} 95 ## @item @qcode{"li"}
96 ## Largest Imaginary part (valid only for complex or unsymmetric problems). 96 ## Largest Imaginary part (valid only for complex or unsymmetric problems).
97 ## 97 ##
98 ## @item @qcode{"si"} 98 ## @item @qcode{"si"}
99 ## Smallest Imaginary part (valid only for complex or unsymmetric problems). 99 ## Smallest Imaginary part (valid only for complex or unsymmetric problems).
100 ## @end table 100 ## @end table
101 ## 101 ##
102 ## If @var{opts} is given, it is a structure defining possible options that 102 ## If @var{opts} is given, it is a structure defining possible options that
103 ## @code{eigs} should use. The fields of the @var{opts} structure are: 103 ## @code{eigs} should use. The fields of the @var{opts} structure are:
104 ## 104 ##
105 ## @table @code 105 ## @table @code
106 ## @item issym 106 ## @item issym
107 ## If @var{af} is given, then flags whether the function @var{af} defines a 107 ## If @var{af} is given, then flags whether the function @var{af} defines a
108 ## symmetric problem. It is ignored if @var{A} is given. The default is false. 108 ## symmetric problem. It is ignored if @var{A} is given. The default is false.
109 ## 109 ##
110 ## @item isreal 110 ## @item isreal
111 ## If @var{af} is given, then flags whether the function @var{af} defines a 111 ## If @var{af} is given, then flags whether the function @var{af} defines a
112 ## real problem. It is ignored if @var{A} is given. The default is true. 112 ## real problem. It is ignored if @var{A} is given. The default is true.
113 ## 113 ##
114 ## @item tol 114 ## @item tol
115 ## Defines the required convergence tolerance, calculated as 115 ## Defines the required convergence tolerance, calculated as
116 ## @code{tol * norm (A)}. The default is @code{eps}. 116 ## @code{tol * norm (A)}. The default is @code{eps}.
117 ## 117 ##
118 ## @item maxit 118 ## @item maxit
119 ## The maximum number of iterations. The default is 300. 119 ## The maximum number of iterations. The default is 300.
120 ## 120 ##
121 ## @item p 121 ## @item p
122 ## The number of Lanzcos basis vectors to use. More vectors will result in 122 ## The number of Lanzcos basis vectors to use. More vectors will result in
123 ## faster convergence, but a greater use of memory. The optimal value of 123 ## faster convergence, but a greater use of memory. The optimal value of
124 ## @code{p} is problem dependent and should be in the range @var{k} to @var{n}. 124 ## @code{p} is problem dependent and should be in the range @var{k} to @var{n}.
125 ## The default value is @code{2 * @var{k}}. 125 ## The default value is @code{2 * @var{k}}.
126 ## 126 ##
127 ## @item v0 127 ## @item v0
128 ## The starting vector for the algorithm. An initial vector close to the 128 ## The starting vector for the algorithm. An initial vector close to the
129 ## final vector will speed up convergence. The default is for @sc{arpack} 129 ## final vector will speed up convergence. The default is for @sc{arpack}
130 ## to randomly generate a starting vector. If specified, @code{v0} must be 130 ## to randomly generate a starting vector. If specified, @code{v0} must be
131 ## an @var{n}-by-1 vector where @code{@var{n} = rows (@var{A})} 131 ## an @var{n}-by-1 vector where @code{@var{n} = rows (@var{A})}
132 ## 132 ##
133 ## @item disp 133 ## @item disp
134 ## The level of diagnostic printout (0|1|2). If @code{disp} is 0 then 134 ## The level of diagnostic printout (0|1|2). If @code{disp} is 0 then
135 ## diagnostics are disabled. The default value is 0. 135 ## diagnostics are disabled. The default value is 0.
136 ## 136 ##
137 ## @item cholB 137 ## @item cholB
138 ## Flag if @code{chol (@var{B})} is passed rather than @var{B}. The default is 138 ## Flag if @code{chol (@var{B})} is passed rather than @var{B}. The default is
139 ## false. 139 ## false.
140 ## 140 ##
141 ## @item permB 141 ## @item permB
142 ## The permutation vector of the Cholesky@tie{}factorization of @var{B} if 142 ## The permutation vector of the Cholesky@tie{}factorization of @var{B} if
143 ## @code{cholB} is true. That is @code{chol (@var{B}(permB, permB))}. The 143 ## @code{cholB} is true. That is @code{chol (@var{B}(permB, permB))}. The
144 ## default is @code{1:@var{n}}. 144 ## default is @code{1:@var{n}}.
145 ## 145 ##
146 ## @end table 146 ## @end table
147 ## 147 ##
148 ## It is also possible to represent @var{A} by a function denoted @var{af}. 148 ## It is also possible to represent @var{A} by a function denoted @var{af}.
149 ## @var{af} must be followed by a scalar argument @var{n} defining the length 149 ## @var{af} must be followed by a scalar argument @var{n} defining the length
150 ## of the vector argument accepted by @var{af}. @var{af} can be 150 ## of the vector argument accepted by @var{af}. @var{af} can be
151 ## a function handle, an inline function, or a string. When @var{af} is a 151 ## a function handle, an inline function, or a string. When @var{af} is a
152 ## string it holds the name of the function to use. 152 ## string it holds the name of the function to use.
153 ## 153 ##
154 ## @var{af} is a function of the form @code{y = af (x)} 154 ## @var{af} is a function of the form @code{y = af (x)}
155 ## where the required return value of @var{af} is determined by 155 ## where the required return value of @var{af} is determined by
156 ## the value of @var{sigma}. The four possible forms are 156 ## the value of @var{sigma}. The four possible forms are
157 ## 157 ##
158 ## @table @code 158 ## @table @code
159 ## @item A * x 159 ## @item A * x
160 ## if @var{sigma} is not given or is a string other than "sm". 160 ## if @var{sigma} is not given or is a string other than "sm".
161 ## 161 ##
162 ## @item A \ x 162 ## @item A \ x
163 ## if @var{sigma} is 0 or "sm". 163 ## if @var{sigma} is 0 or "sm".
164 ## 164 ##
165 ## @item (A - sigma * I) \ x 165 ## @item (A - sigma * I) \ x
166 ## for the standard eigenvalue problem, where @code{I} is the identity matrix of 166 ## for the standard eigenvalue problem, where @code{I} is the identity matrix of
167 ## the same size as @var{A}. 167 ## the same size as @var{A}.
168 ## 168 ##
169 ## @item (A - sigma * B) \ x 169 ## @item (A - sigma * B) \ x
170 ## for the general eigenvalue problem. 170 ## for the general eigenvalue problem.
171 ## @end table 171 ## @end table
172 ## 172 ##
173 ## The return arguments of @code{eigs} depend on the number of return arguments 173 ## The return arguments of @code{eigs} depend on the number of return arguments
174 ## requested. With a single return argument, a vector @var{d} of length @var{k} 174 ## requested. With a single return argument, a vector @var{d} of length @var{k}
175 ## is returned containing the @var{k} eigenvalues that have been found. With 175 ## is returned containing the @var{k} eigenvalues that have been found. With
176 ## two return arguments, @var{V} is a @var{n}-by-@var{k} matrix whose columns 176 ## two return arguments, @var{V} is a @var{n}-by-@var{k} matrix whose columns
177 ## are the @var{k} eigenvectors corresponding to the returned eigenvalues. The 177 ## are the @var{k} eigenvectors corresponding to the returned eigenvalues. The
178 ## eigenvalues themselves are returned in @var{d} in the form of a 178 ## eigenvalues themselves are returned in @var{d} in the form of a
179 ## @var{n}-by-@var{k} matrix, where the elements on the diagonal are the 179 ## @var{n}-by-@var{k} matrix, where the elements on the diagonal are the
180 ## eigenvalues. 180 ## eigenvalues.
181 ## 181 ##
182 ## Given a third return argument @var{flag}, @code{eigs} returns the status 182 ## Given a third return argument @var{flag}, @code{eigs} returns the status
183 ## of the convergence. If @var{flag} is 0 then all eigenvalues have converged. 183 ## of the convergence. If @var{flag} is 0 then all eigenvalues have converged.
184 ## Any other value indicates a failure to converge. 184 ## Any other value indicates a failure to converge.
185 ## 185 ##
186 ## This function is based on the @sc{arpack} package, written by 186 ## This function is based on the @sc{arpack} package, written by
187 ## @nospell{R. Lehoucq, K. Maschhoff, D. Sorensen, and C. Yang}. For more 187 ## @nospell{R. Lehoucq, K. Maschhoff, D. Sorensen, and C. Yang}. For more
188 ## information see @url{http://www.caam.rice.edu/software/ARPACK/}. 188 ## information see @url{http://www.caam.rice.edu/software/ARPACK/}.
189 ## 189 ##
190 ## @seealso{eig, svds} 190 ## @seealso{eig, svds}
191 ## @end deftypefn 191 ## @end deftypefn
192 192
193 function varargout = eigs (varargin) 193 function varargout = eigs (varargin)
194 194
213 endif 213 endif
214 214
215 if (rows (a) < 9) 215 if (rows (a) < 9)
216 call_eig = true; 216 call_eig = true;
217 endif 217 endif
218 218
219 if (nargin > 1 + offset) 219 if (nargin > 1 + offset)
220 tmp = varargin{2+offset}; 220 tmp = varargin{2+offset};
221 if (isnumeric (tmp) && isscalar (tmp) && isreal (tmp) 221 if (isnumeric (tmp) && isscalar (tmp) && isreal (tmp)
222 && round (tmp) == tmp) 222 && round (tmp) == tmp)
223 k = tmp; 223 k = tmp;