#### Previous topic

scipy.sparse.linalg.eigs

#### Next topic

scipy.sparse.linalg.lobpcg

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

  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]

  Parameters:

  A : An N x N matrix, array, sparse matrix, or LinearOperator representing

  > the operation A * x, where A is a real symmetric matrix 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.

  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]`.

  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, 2*k + 1)`

  which : str [‘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.

  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

  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)

  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.

  See also

  `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 [R16] SSEUPD and DSEUPD functions which use the Implicitly Restarted Lanczos Method to find the eigenvalues and eigenvectors [R17].

  References

  [R16] | (1, 2) ARPACK Software, http://www.caam.rice.edu/software/ARPACK/

  [R17] | (1, 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

      >>> import scipy.sparse as sparse
      >>> id = np.eye(13)
      >>> vals, vecs = sparse.linalg.eigsh(id, k=6)
      >>> vals
      array([ 1.+0.j,  1.+0.j,  1.+0.j,  1.+0.j,  1.+0.j,  1.+0.j])
      >>> vecs.shape
      (13, 6)