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

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

References
----------
.. [1] ARPACK Software, https://github.com/opencollab/arpack-ng
.. [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 numpy as np
>>> 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)

