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')

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.

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 .

Other Parameters

M : An 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 .

sigma : real

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)

v0 : ndarray, optional

Starting vector for iteration. Default: random

ncv : int, 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))

which : str ['LM' | 'SM' | 'LA' | 'SA' | 'BE']

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

maxiter : int, optional

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

tol : float

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

Minv : N x N matrix, array, sparse matrix, or LinearOperator

See notes in M, above.

OPinv : N x N matrix, array, sparse matrix, or LinearOperator

See notes in sigma, above.

return_eigenvectors : bool

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 :None:None:`which` variable.

For which = 'LM' or 'SA':

If :None:None:`return_eigenvectors` is True, eigenvalues are sorted by algebraic value.

If :None:None:`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 :None:None:`return_eigenvectors` is True, eigenvalues are sorted by algebraic value.

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

mode : string ['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).

Parameters

A : ndarray, 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.

k : int, 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.

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.

Returns

w : array

Array of k eigenvalues.

v : array

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

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

See Also

eigs

eigenvalues and eigenvectors for a general (nonsymmetric) matrix A

svds

singular value decomposition for a matrix A

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)

See :

Back References

The following pages refer to to this document either explicitly or contain code examples using this.

scipy.sparse.linalg._eigen.arpack.arpack.eigs scipy.sparse.linalg._eigen.arpack.arpack.eigsh

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

---

GitHub : /scipy/sparse/linalg/_eigen/arpack/arpack.py#1350
type: <class 'function'>
Commit: