#### 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, 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: ‘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 [R329] SSEUPD and DSEUPD functions which use the Implicitly Restarted Lanczos Method to find the eigenvalues and eigenvectors [R330].

  References

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

  [R330] | (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)