# 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  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.

`eigs`

eigenvalues and eigenvectors for a general (nonsymmetric) matrix A

`svds`

singular value decomposition for a matrix A

Notes

This function is a wrapper to the ARPACK  SSEUPD and DSEUPD functions which use the Implicitly Restarted Lanczos Method to find the eigenvalues and eigenvectors .

References

1

ARPACK Software, http://www.caam.rice.edu/software/ARPACK/

2

R. B. Lehoucq, D. C. Sorensen, and C. Yang, ARPACK USERS GUIDE: Solution of Large Scale Eigenvalue Problems by Implicitly Restarted Arnoldi Methods. SIAM, Philadelphia, PA, 1998.

Examples

```>>> from scipy.sparse.linalg import eigsh
>>> identity = np.eye(13)
>>> eigenvalues, eigenvectors = eigsh(identity, k=6)
>>> eigenvalues
array([1., 1., 1., 1., 1., 1.])
>>> eigenvectors.shape
(13, 6)
```