scipy.sparse.linalg.eigsh#

scipy.sparse.linalg.eigsh(A, k=6, M=None, sigma=None, which='LM', v0=None, ncv=None, maxiter=None, tol=0, return_eigenvectors=True, Minv=None, OPinv=None, mode='normal')[source]#

Find k eigenvalues and eigenvectors of the real symmetric square matrix or complex Hermitian matrix A.

Solves A @ x[i] = w[i] * x[i], the standard eigenvalue problem for w[i] eigenvalues with corresponding eigenvectors x[i].

If M is specified, solves A @ x[i] = w[i] * M @ x[i], the generalized eigenvalue problem for w[i] eigenvalues with corresponding eigenvectors x[i].

Note that there is no specialized routine for the case when A is a complex Hermitian matrix. In this case, eigsh() will call eigs() and return the real parts of the eigenvalues thus obtained.

Parameters:

Andarray, sparse matrix or LinearOperator: A square operator representing the operation A @ x, where A is real symmetric or complex Hermitian. For buckling mode (see below) A must additionally be positive-definite.
kint, optional: The number of eigenvalues and eigenvectors desired. k must be smaller than N. It is not possible to compute all eigenvectors of a matrix.

Returns:

warray: Array of k eigenvalues.
varray: An array representing the k eigenvectors. The column v[:, i] is the eigenvector corresponding to the eigenvalue w[i].

Other Parameters:

MAn N x N matrix, array, sparse matrix, or linear operator representing

the operation M @ x for the generalized eigenvalue problem

A @ x = w * M @ x.

M must represent a real symmetric matrix if A is real, and must represent a complex Hermitian matrix if A is complex. For best results, the data type of M should be the same as that of A. Additionally:

If sigma is None, M is symmetric positive definite.

If sigma is specified, M is symmetric positive semi-definite.

In buckling mode, M is symmetric indefinite.

If sigma is None, eigsh requires an operator to compute the solution of the linear equation M @ x = b. This is done internally via a (sparse) LU decomposition for an explicit matrix M, or via an iterative solver for a general linear operator. Alternatively, the user can supply the matrix or operator Minv, which gives x = Minv @ b = M^-1 @ b.

sigmareal

Find eigenvalues near sigma using shift-invert mode. This requires an operator to compute the solution of the linear system [A - sigma * M] x = b, where M is the identity matrix if unspecified. This is computed internally via a (sparse) LU decomposition for explicit matrices A & M, or via an iterative solver if either A or M is a general linear operator. Alternatively, the user can supply the matrix or operator OPinv, which gives x = OPinv @ b = [A - sigma * M]^-1 @ b. Note that when sigma is specified, the keyword ‘which’ refers to the shifted eigenvalues w'[i] where:

if mode == ‘normal’, w'[i] = 1 / (w[i] - sigma).

if mode == ‘cayley’, w'[i] = (w[i] + sigma) / (w[i] - sigma).

if mode == ‘buckling’, w'[i] = w[i] / (w[i] - sigma).

(see further discussion in ‘mode’ below)

v0ndarray, optional

Starting vector for iteration. Default: random

ncvint, optional

The number of Lanczos vectors generated ncv must be greater than k and smaller than n; it is recommended that ncv > 2*k. Default: min(n, max(2*k + 1, 20))

whichstr [‘LM’ | ‘SM’ | ‘LA’ | ‘SA’ | ‘BE’]

If A is a complex Hermitian matrix, ‘BE’ is invalid. Which k eigenvectors and eigenvalues to find:

‘LM’ : Largest (in magnitude) eigenvalues.

‘SM’ : Smallest (in magnitude) eigenvalues.

‘LA’ : Largest (algebraic) eigenvalues.

‘SA’ : Smallest (algebraic) eigenvalues.

‘BE’ : Half (k/2) from each end of the spectrum.

When k is odd, return one more (k/2+1) from the high end. When sigma != None, ‘which’ refers to the shifted eigenvalues w'[i] (see discussion in ‘sigma’, above). ARPACK is generally better at finding large values than small values. If small eigenvalues are desired, consider using shift-invert mode for better performance.

maxiterint, optional

Maximum number of Arnoldi update iterations allowed. Default: n*10

tolfloat

Relative accuracy for eigenvalues (stopping criterion). The default value of 0 implies machine precision.

MinvN x N matrix, array, sparse matrix, or LinearOperator

See notes in M, above.

OPinvN x N matrix, array, sparse matrix, or LinearOperator

See notes in sigma, above.

return_eigenvectorsbool

Return eigenvectors (True) in addition to eigenvalues. This value determines the order in which eigenvalues are sorted. The sort order is also dependent on the which variable.

For which = ‘LM’ or ‘SA’:
If return_eigenvectors is True, eigenvalues are sorted by algebraic value.

If return_eigenvectors is False, eigenvalues are sorted by absolute value.

For which = ‘BE’ or ‘LA’:
eigenvalues are always sorted by algebraic value.

For which = ‘SM’:
If return_eigenvectors is True, eigenvalues are sorted by algebraic value.

If return_eigenvectors is False, eigenvalues are sorted by decreasing absolute value.

modestring [‘normal’ | ‘buckling’ | ‘cayley’]

Specify strategy to use for shift-invert mode. This argument applies only for real-valued A and sigma != None. For shift-invert mode, ARPACK internally solves the eigenvalue problem OP @ x'[i] = w'[i] * B @ x'[i] and transforms the resulting Ritz vectors x’[i] and Ritz values w’[i] into the desired eigenvectors and eigenvalues of the problem A @ x[i] = w[i] * M @ x[i]. The modes are as follows:

‘normal’ :
OP = [A - sigma * M]^-1 @ M, B = M, w’[i] = 1 / (w[i] - sigma)

‘buckling’ :
OP = [A - sigma * M]^-1 @ A, B = A, w’[i] = w[i] / (w[i] - sigma)

‘cayley’ :
OP = [A - sigma * M]^-1 @ [A + sigma * M], B = M, w’[i] = (w[i] + sigma) / (w[i] - sigma)

The choice of mode will affect which eigenvalues are selected by the keyword ‘which’, and can also impact the stability of convergence (see [2] for a discussion).

Raises:

ArpackNoConvergence

When the requested convergence is not obtained.

The currently converged eigenvalues and eigenvectors can be found as eigenvalues and eigenvectors attributes of the exception object.