[Numpy] Add linalg.eigvals/eig/eigvalsh/eigh op

* add source file

* fix cudaRunError

Author: Ubuntu

python/mxnet/ndarray/numpy/linalg.py

@@ -21,7 +21,8 @@
 from . import _op as _mx_nd_np
 from . import _internal as _npi
 
-__all__ = ['norm', 'svd', 'cholesky', 'inv', 'det', 'slogdet', 'solve', 'tensorinv', 'tensorsolve']
+__all__ = ['norm', 'svd', 'cholesky', 'inv', 'det', 'slogdet', 'solve', 'tensorinv', 'tensorsolve',
+           'eigvals', 'eig', 'eigvalsh', 'eigh']
 
 
 def norm(x, ord=None, axis=None, keepdims=False):
@@ -509,3 +510,265 @@ def tensorsolve(a, b, axes=None):
     True
     """
     return _npi.tensorsolve(a, b, axes)
+
+
+def eigvals(a):
+    r"""
+    Compute the eigenvalues of a general matrix.
+
+    Main difference between `eigvals` and `eig`: the eigenvectors aren't
+    returned.
+
+    Parameters
+    ----------
+    a : (..., M, M) ndarray
+        A real-valued matrix whose eigenvalues will be computed.
+
+    Returns
+    -------
+    w : (..., M,) ndarray
+        The eigenvalues, each repeated according to its multiplicity.
+        They are not necessarily ordered.
+
+    Raises
+    ------
+    MXNetError
+        If the eigenvalue computation does not converge.
+
+    See Also
+    --------
+    eig : eigenvalues and right eigenvectors of general arrays
+    eigh : eigenvalues and eigenvectors of a real symmetric array.
+    eigvalsh : eigenvalues of a real symmetric.
+
+    Notes
+    -----
+    Broadcasting rules apply, see the `numpy.linalg` documentation for
+    details.
+
+    This is implemented using the ``_geev`` LAPACK routines which compute
+    the eigenvalues and eigenvectors of general square arrays.
+
+    This function differs from the original `numpy.linalg.eigvals
+    <https://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.eigvals.html>`_ in
+    the following way(s):
+     - Does not support complex input and output.
+
+    Examples
+    --------
+    Illustration, using the fact that the eigenvalues of a diagonal matrix
+    are its diagonal elements, that multiplying a matrix on the left
+    by an orthogonal matrix, `Q`, and on the right by `Q.T` (the transpose
+    of `Q`), preserves the eigenvalues of the "middle" matrix.  In other words,
+    if `Q` is orthogonal, then ``Q * A * Q.T`` has the same eigenvalues as
+    ``A``:
+    >>> from numpy import linalg as LA
+    >>> x = np.random.random()
+    >>> Q = np.array([[np.cos(x), -np.sin(x)], [np.sin(x), np.cos(x)]])
+    >>> LA.norm(Q[0, :]), LA.norm(Q[1, :]), np.dot(Q[0, :],Q[1, :])
+    (1.0, 1.0, 0.0)
+
+    Now multiply a diagonal matrix by ``Q`` on one side and by ``Q.T`` on the other:
+    >>> D = np.diag((-1,1))
+    >>> LA.eigvals(D)
+    array([-1.,  1.])
+    >>> A = np.dot(Q, D)
+    >>> A = np.dot(A, Q.T)
+    >>> LA.eigvals(A)
+    array([ 1., -1.]) # random
+    """
+    return _npi.eigvals(a)
+
+
+def eigvalsh(a, UPLO='L'):
+    r"""
+    Compute the eigenvalues real symmetric matrix.
+
+    Main difference from eigh: the eigenvectors are not computed.
+
+    Parameters
+    ----------
+    a : (..., M, M) ndarray
+        A real-valued matrix whose eigenvalues are to be computed.
+    UPLO : {'L', 'U'}, optional
+        Specifies whether the calculation is done with the lower triangular
+        part of `a` ('L', default) or the upper triangular part ('U').
+        Irrespective of this value only the real parts of the diagonal will
+        be considered in the computation to preserve the notion of a Hermitian
+        matrix. It therefore follows that the imaginary part of the diagonal
+        will always be treated as zero.
+
+    Returns
+    -------
+    w : (..., M,) ndarray
+        The eigenvalues in ascending order, each repeated according to
+        its multiplicity.
+
+    Raises
+    ------
+    MXNetError
+        If the eigenvalue computation does not converge.
+
+    See Also
+    --------
+    eig : eigenvalues and right eigenvectors of general arrays
+    eigvals : eigenvalues of a non-symmetric array.
+    eigh : eigenvalues and eigenvectors of a real symmetric array.
+
+    Notes
+    -----
+    Broadcasting rules apply, see the `numpy.linalg` documentation for
+    details.
+
+    The eigenvalues are computed using LAPACK routines ``_syevd``.
+
+    This function differs from the original `numpy.linalg.eigvalsh
+    <https://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.eigvalsh.html>`_ in
+    the following way(s):
+     - Does not support complex input and output.
+
+    Examples
+    --------
+    >>> from numpy import linalg as LA
+    >>> a = np.array([[ 5.4119368 ,  8.996273  , -5.086096  ],
+                      [ 0.8866155 ,  1.7490431 , -4.6107802 ],
+                      [-0.08034172,  4.4172044 ,  1.4528792 ]])
+    >>> LA.eigvalsh(a, UPLO='L')
+    array([-2.87381886,  5.10144682,  6.38623114]) # in ascending order
+    """
+    return _npi.eigvalsh(a, UPLO)
+
+
+def eig(a):
+    r"""
+    Compute the eigenvalues and right eigenvectors of a square array.
+
+    Parameters
+    ----------
+    a : (..., M, M) ndarray
+        Matrices for which the eigenvalues and right eigenvectors will
+        be computed
+
+    Returns
+    -------
+    w : (..., M) ndarray
+        The eigenvalues, each repeated according to its multiplicity.
+        The eigenvalues are not necessarily ordered.
+    v : (..., M, M) ndarray
+        The normalized (unit "length") eigenvectors, such that the
+        column ``v[:,i]`` is the eigenvector corresponding to the
+        eigenvalue ``w[i]``.
+
+    Raises
+    ------
+    MXNetError
+        If the eigenvalue computation does not converge.
+
+    See Also
+    --------
+    eigvals : eigenvalues of a non-symmetric array.
+    eigh : eigenvalues and eigenvectors of a real symmetric array.
+    eigvalsh : eigenvalues of a real symmetric.
+
+    Notes
+    -----
+    This is implemented using the ``_geev`` LAPACK routines which compute
+    the eigenvalues and eigenvectors of general square arrays.
+
+    The number `w` is an eigenvalue of `a` if there exists a vector
+    `v` such that ``dot(a,v) = w * v``. Thus, the arrays `a`, `w`, and
+    `v` satisfy the equations ``dot(a[:,:], v[:,i]) = w[i] * v[:,i]``
+    for :math:`i \\in \\{0,...,M-1\\}`.
+
+    The array `v` of eigenvectors may not be of maximum rank, that is, some
+    of the columns may be linearly dependent, although round-off error may
+    obscure that fact. If the eigenvalues are all different, then theoretically
+    the eigenvectors are linearly independent.
+
+    This function differs from the original `numpy.linalg.eig
+    <https://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.eig.html>`_ in
+    the following way(s):
+     - Does not support complex input and output.
+
+    Examples
+    --------
+    >>> from numpy import linalg as LA
+    >>> a = np.array([[-1.9147992 ,  6.054115  , 18.046988  ],
+                      [ 0.77563655, -4.860152  ,  2.1012988 ],
+                      [ 2.6083658 ,  2.3705218 ,  0.3192524 ]])
+    >>> w, v = LA.eig(a)
+    >>> w
+    array([ 6.9683027, -7.768063 , -5.655937 ])
+    >>> v
+    array([[ 0.90617794,  0.9543622 ,  0.2492316 ],
+           [ 0.13086087, -0.04077047, -0.9325615 ],
+           [ 0.4021404 , -0.29585576,  0.26117516]])
+    """
+    return _npi.eig(a)
+
+
+def eigh(a, UPLO='L'):
+    r"""
+    Return the eigenvalues and eigenvectors real symmetric matrix.
+
+    Returns two objects, a 1-D array containing the eigenvalues of `a`, and
+    a 2-D square array or matrix (depending on the input type) of the
+    corresponding eigenvectors (in columns).
+
+    Parameters
+    ----------
+    a : (..., M, M) ndarray
+        real symmetric matrices whose eigenvalues and eigenvectors are to be computed.
+    UPLO : {'L', 'U'}, optional
+        Specifies whether the calculation is done with the lower triangular
+        part of `a` ('L', default) or the upper triangular part ('U').
+        Irrespective of this value only the real parts of the diagonal will
+        be considered in the computation to preserve the notion of a Hermitian
+        matrix. It therefore follows that the imaginary part of the diagonal
+        will always be treated as zero.
+
+    Returns
+    -------
+    w : (..., M) ndarray
+        The eigenvalues in ascending order, each repeated according to
+        its multiplicity.
+    v : {(..., M, M) ndarray, (..., M, M) matrix}
+        The column ``v[:, i]`` is the normalized eigenvector corresponding
+        to the eigenvalue ``w[i]``.  Will return a matrix object if `a` is
+        a matrix object.
+
+    Raises
+    ------
+    MXNetError
+        If the eigenvalue computation does not converge.
+
+    See Also
+    --------
+    eig : eigenvalues and right eigenvectors of general arrays
+    eigvals : eigenvalues of a non-symmetric array.
+    eigvalsh : eigenvalues of a real symmetric.
+
+    Notes
+    -----
+    The eigenvalues/eigenvectors are computed using LAPACK routines ``_syevd``.
+
+    This function differs from the original `numpy.linalg.eigh
+    <https://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.eigh.html>`_ in
+    the following way(s):
+     - Does not support complex input and output.
+
+    Examples
+    --------
+    >>> from numpy import linalg as LA
+    >>> a = np.array([[ 6.8189726 , -3.926585  ,  4.3990498 ],
+                      [-0.59656644, -1.9166266 ,  9.54532   ],
+                      [ 2.1093285 ,  0.19688708, -1.1634291 ]])
+    >>> w, v = LA.eigh(a, UPLO='L')
+    >>> w
+    array([-2.175445 , -1.4581827,  7.3725457])
+    >>> v
+    array([[ 0.1805163 , -0.16569263,  0.9695154 ],
+           [ 0.8242942 ,  0.56326365, -0.05721384],
+           [-0.53661287,  0.80949366,  0.23825769]])
+    """
+    return _npi.eigh(a, UPLO)