.. _heevd:

heevd
=====


Computes all eigenvalues and, optionally, all eigenvectors of a complex
Hermitian matrix using divide and conquer algorithm. This routine
belongs to the ``oneapi::mkl::lapack`` namespace.


.. contents::
    :local:
    :depth: 1

Description
***********

The routine computes all the eigenvalues, and optionally all the
eigenvectors, of a complex Hermitian matrix ``A``. In other words, it
can compute the spectral factorization of ``A`` as: ``A = Z*Λ*ZH``.


Here :math:`\Lambda` is a real diagonal matrix whose diagonal elements are the
eigenvalues :math:`\lambda`\ :sub:`i`, and ``Z`` is the (complex) unitary matrix whose columns are the eigenvectors ``z``\ :sub:`i`. Thus,


``A*zi = λi*zi`` for ``i = 1, 2, ..., n``.


If the eigenvectors are requested, then this routine uses a divide
and conquer algorithm to compute eigenvalues and eigenvectors.
However, if only eigenvalues are required, then it uses the
Pal-Walker-Kahan variant of the ``QL`` or ``QR`` algorithm.


API
***


Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::lapack {
     void heevd(cl::sycl::queue &queue,
     mkl::job jobz,
     mkl::uplo uplo,
     std::int64_t n,
     cl::sycl::buffer<T> &a,
     std::int64_t lda,
     cl::sycl::buffer<T> &w,
     cl::sycl::buffer<T> &scratchpad,
     std::int64_t scratchpad_size)
   }

``heevd`` supports the following precision and devices.


.. list-table::
   :header-rows: 1

   * -  T
     -  Devices Supported
   * -  ``std::complex<float>``
     -  Host, CPU, and GPU
   * -  ``std::complex<double>``
     -  Host, CPU, and GPU


Input Parameters
----------------

queue
   Device queue where calculations will be performed.


jobz
   Must be ``job::novec`` or ``job::vec``.


   If ``jobz = job::novec``, then only eigenvalues are computed.


   If ``jobz = job::vec``, then eigenvalues and eigenvectors are
   computed.


uplo
   Must be ``uplo::upper`` or ``uplo::lower``.


   If ``uplo = job::upper``, a stores the upper triangular part of
   ``A``.


   If ``uplo = job::lower``, a stores the lower triangular part of
   ``A``.


n
   The order of the matrix ``A`` (``0≤n``).


a
   Buffer holding the array containing ``A``, size (``lda,*``). The
   second dimension of a must be at least ``max(1, n)``.


lda
   The leading dimension of a. Must be at least ``max(1,n)``.


scratchpad
   Buffer holding scratchpad memory to be used by the routine for
   storing intermediate results.


scratchpad_size
   Size of scratchpad memory as a number of floating point elements
   of type ``T``. Size should not be less than the value returned by
   the
   :ref:`heevd_scratchpad_size`
   function.


Output Parameters
-----------------

a
   If ``jobz = job::vec``, then on exit this buffer is overwritten by
   the unitary matrix ``Z`` which contains the eigenvectors of ``A``.


w
   Buffer holding array of size at least n. If ``info = 0``, contains
   the eigenvalues of the matrix ``A`` in ascending order. See also
   info.


Exceptions
----------

.. tabularcolumns:: |\Y{0.3}|\Y{0.7}|

.. list-table::
   :header-rows: 1

   * - Exception
     - Description

   * -     ``mkl::lapack::exception``
     -     This exception is thrown when problems occur during    calculations. You can obtain the info code of the problem using the   info() method of the exception object:

           If   ``info = -i``, the ``i``-th parameter had an illegal   value.

           If ``info = i``, and ``jobz = job::novec``,   then the algorithm failed to converge; ``i`` indicates the number of   off-diagonal elements of an intermediate tridiagonal form which did   not converge to zero.

           If ``info = i``, and   ``jobz = job::vec``, then the algorithm failed to compute an   eigenvalue while working on the submatrix lying in rows and columns   ``info/(n+1)`` through ``mod(info,n+1)``.

           If ``info``   is equal to the value passed as scratchpad size, and detail() returns   non zero, then the passed scratchpad has an insufficient size, and   the required size should not be less than the value returned by the   detail() method of the exception object.