| DEFUN_DLD (eigs, args, nargout,"-*- texinfo -*-\n\
@deftypefn {Loadable Function} {@var{d} =} eigs (@var{A})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{k})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{k}, @var{sigma})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{k}, @var{sigma}, @var{opts})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{B})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{B}, @var{k})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{B}, @var{k}, @var{sigma})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{A}, @var{B}, @var{k}, @var{sigma}, @var{opts})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{B})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{k})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{B}, @var{k})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{k}, @var{sigma})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{k}, @var{sigma}, @var{opts})\n\
@deftypefnx {Loadable Function} {@var{d} =} eigs (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma}, @var{opts})\n\
@deftypefnx {Loadable Function} {[@var{V}, @var{d}] =} eigs (@var{A}, @dots{})\n\
@deftypefnx {Loadable Function} {[@var{V}, @var{d}] =} eigs (@var{af}, @var{n}, @dots{})\n\
@deftypefnx {Loadable Function} {[@var{V}, @var{d}, @var{flag}] =} eigs (@var{A}, @dots{})\n\
@deftypefnx {Loadable Function} {[@var{V}, @var{d}, @var{flag}] =} eigs (@var{af}, @var{n}, @dots{})\n\
Calculate a limited number of eigenvalues and eigenvectors of @var{A},\n\
based on a selection criteria. The number of eigenvalues and eigenvectors to\n\
calculate is given by @var{k} and defaults to 6.\n\
\n\
By default, @code{eigs} solve the equation\n\
@tex\n\
$A \\nu = \\lambda \\nu$,\n\
@end tex\n\
@ifinfo\n\
@code{A * v = lambda * v},\n\
@end ifinfo\n\
where\n\
@tex\n\
$\\lambda$ is a scalar representing one of the eigenvalues, and $\\nu$\n\
@end tex\n\
@ifinfo\n\
@code{lambda} is a scalar representing one of the eigenvalues, and @code{v}\n\
@end ifinfo\n\
is the corresponding eigenvector. If given the positive definite matrix\n\
@var{B} then @code{eigs} solves the general eigenvalue equation\n\
@tex\n\
$A \\nu = \\lambda B \\nu$.\n\
@end tex\n\
@ifinfo\n\
@code{A * v = lambda * B * v}.\n\
@end ifinfo\n\
\n\
The argument @var{sigma} determines which eigenvalues are returned.\n\
@var{sigma} can be either a scalar or a string. When @var{sigma} is a\n\
scalar, the @var{k} eigenvalues closest to @var{sigma} are returned. If\n\
@var{sigma} is a string, it must have one of the following values.\n\
\n\
@table @asis\n\
@item 'lm'\n\
Largest Magnitude (default).\n\
\n\
@item 'sm'\n\
Smallest Magnitude.\n\
\n\
@item 'la'\n\
Largest Algebraic (valid only for real symmetric problems).\n\
\n\
@item 'sa'\n\
Smallest Algebraic (valid only for real symmetric problems).\n\
\n\
@item 'be'\n\
Both Ends, with one more from the high-end if @var{k} is odd (valid only for\n\
real symmetric problems).\n\
\n\
@item 'lr'\n\
Largest Real part (valid only for complex or unsymmetric problems).\n\
\n\
@item 'sr'\n\
Smallest Real part (valid only for complex or unsymmetric problems).\n\
\n\
@item 'li'\n\
Largest Imaginary part (valid only for complex or unsymmetric problems).\n\
\n\
@item 'si'\n\
Smallest Imaginary part (valid only for complex or unsymmetric problems).\n\
@end table\n\
\n\
If @var{opts} is given, it is a structure defining possible options that\n\
@code{eigs} should use. The fields of the @var{opts} structure are:\n\
\n\
@table @code\n\
@item issym\n\
If @var{af} is given, then flags whether the function @var{af} defines a\n\
symmetric problem. It is ignored if @var{A} is given. The default is false.\n\
\n\
@item isreal\n\
If @var{af} is given, then flags whether the function @var{af} defines a\n\
real problem. It is ignored if @var{A} is given. The default is true.\n\
\n\
@item tol\n\
Defines the required convergence tolerance, calculated as\n\
@code{tol * norm (A)}. The default is @code{eps}.\n\
\n\
@item maxit\n\
The maximum number of iterations. The default is 300.\n\
\n\
@item p\n\
The number of Lanzcos basis vectors to use. More vectors will result in\n\
faster convergence, but a greater use of memory. The optimal value of\n\
@code{p} is problem dependent and should be in the range @var{k} to @var{n}.\n\
The default value is @code{2 * @var{k}}.\n\
\n\
@item v0\n\
The starting vector for the algorithm. An initial vector close to the\n\
final vector will speed up convergence. The default is for @sc{arpack}\n\
to randomly generate a starting vector. If specified, @code{v0} must be\n\
an @var{n}-by-1 vector where @code{@var{n} = rows (@var{A})}\n\
\n\
@item disp\n\
The level of diagnostic printout (0|1|2). If @code{disp} is 0 then\n\
diagnostics are disabled. The default value is 0.\n\
\n\
@item cholB\n\
Flag if @code{chol (@var{B})} is passed rather than @var{B}. The default is\n\
false.\n\
\n\
@item permB\n\
The permutation vector of the Cholesky@tie{}factorization of @var{B} if\n\
@code{cholB} is true. That is @code{chol (@var{B}(permB, permB))}. The\n\
default is @code{1:@var{n}}.\n\
\n\
@end table\n\
It is also possible to represent @var{A} by a function denoted @var{af}.\n\
@var{af} must be followed by a scalar argument @var{n} defining the length\n\
of the vector argument accepted by @var{af}. @var{af} can be \n\
a function handle, an inline function, or a string. When @var{af} is a\n\
string it holds the name of the function to use.\n\
\n\
@var{af} is a function of the form @code{y = af (x)}\n\
where the required return value of @var{af} is determined by\n\
the value of @var{sigma}. The four possible forms are\n\
\n\
@table @code\n\
@item A * x\n\
if @var{sigma} is not given or is a string other than 'sm'.\n\
\n\
@item A \\ x\n\
if @var{sigma} is 0 or 'sm'.\n\
\n\
@item (A - sigma * I) \\ x\n\
for the standard eigenvalue problem, where @code{I} is the identity matrix of\n\
the same size as @var{A}.\n\
\n\
@item (A - sigma * B) \\ x\n\
for the general eigenvalue problem.\n\
@end table\n\
\n\
The return arguments of @code{eigs} depend on the number of return arguments\n\
requested. With a single return argument, a vector @var{d} of length @var{k}\n\
is returned containing the @var{k} eigenvalues that have been found. With\n\
two return arguments, @var{V} is a @var{n}-by-@var{k} matrix whose columns\n\
are the @var{k} eigenvectors corresponding to the returned eigenvalues. The\n\
eigenvalues themselves are returned in @var{d} in the form of a\n\
@var{n}-by-@var{k} matrix, where the elements on the diagonal are the\n\
eigenvalues.\n\
\n\
Given a third return argument @var{flag}, @code{eigs} returns the status\n\
of the convergence. If @var{flag} is 0 then all eigenvalues have converged.\n\
Any other value indicates a failure to converge.\n\
\n\
This function is based on the @sc{arpack} package, written by R. Lehoucq,\n\
K. Maschhoff, D. Sorensen, and C. Yang. For more information see\n\
@url{http://www.caam.rice.edu/software/ARPACK/}.\n\
\n\
@seealso{eig, svds}\n\
@end deftypefn") |