.. _onemkl_blas_her2:

her2
====

Computes a rank-2 update of a hermitian matrix.

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

The ``her2`` routines compute two scalar-vector-vector products and add them to a hermitian matrix. The operation is defined as:

.. math::

      A \leftarrow alpha*x*y^H + conjg(alpha)*y*x^H + A

where:

- ``alpha`` is a scalar

- ``A`` is ``n`` x ``n`` hermitian matrix

- ``x`` and ``y`` are vectors or length ``n``

``her2`` supports the following precisions:

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

      * -  T
      * -  ``std::complex<float>``
      * -  ``std::complex<double>``


her2 (Buffer Version)
*********************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       void her2(sycl::queue &queue,
                 oneapi::mkl::uplo upper_lower,
                 std::int64_t n,
                 T alpha,
                 sycl::buffer<T,1> &x,
                 std::int64_t incx,
                 sycl::buffer<T,1> &y,
                 std::int64_t incy,
                 sycl::buffer<T,1> &a,
                 std::int64_t lda)
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       void her2(sycl::queue &queue,
                 oneapi::mkl::uplo upper_lower,
                 std::int64_t n,
                 T alpha,
                 sycl::buffer<T,1> &x,
                 std::int64_t incx,
                 sycl::buffer<T,1> &y,
                 std::int64_t incy,
                 sycl::buffer<T,1> &a,
                 std::int64_t lda)
   }

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

queue
   The queue where the routine should be executed.

upper_lower
   Specifies whether matrix ``A`` is upper or lower triangular. See :ref:`data-types` for more details.

n
   Number of columns of matrix ``A``. Must be at least zero.

alpha
   Scaling factor for the matrix-vector product.

x
   Buffer holding input vector ``x``. Size of the buffer must be at
   least (1 + (``n`` - 1)*abs(``incx``)). See :ref:`matrix-storage` for more details.

incx
   Stride of vector ``x``.

y
   Buffer holding input/output vector ``y``. Size of the buffer must be
   at least (1 + (``n`` - 1)*abs(``incy``)). See :ref:`matrix-storage` for more details.

incy
   Stride of vector ``y``.

a
   Buffer holding input matrix ``A``. Size of the buffer must be at least
   ``lda`` * ``n``. See :ref:`matrix-storage` for more details.

lda
   Leading dimension of matrix ``A``. Must be at least ``n`` and positive.

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

a
   Buffer holding updated upper triangular part of the hermitian
   matrix ``A`` if ``upper_lower=upper``, or updated
   lower triangular part of the hermitian matrix ``A`` if
   ``upper_lower=lower``.

   The imaginary parts of the diagonal elements are set to zero.


her2 (USM Version)
******************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       sycl::event her2(sycl::queue &queue,
                        oneapi::mkl::uplo upper_lower,
                        std::int64_t n,
                        T alpha,
                        const T *x,
                        std::int64_t incx,
                        const T *y,
                        std::int64_t incy,
                        T *a,
                        std::int64_t lda,
                        const std::vector<sycl::event> &dependencies = {})
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       sycl::event her2(sycl::queue &queue,
                        oneapi::mkl::uplo upper_lower,
                        std::int64_t n,
                        T alpha,
                        const T *x,
                        std::int64_t incx,
                        const T *y,
                        std::int64_t incy,
                        T *a,
                        std::int64_t lda,
                        const std::vector<sycl::event> &dependencies = {})
   }

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

queue
   The queue where the routine should be executed.

upper_lower
   Specifies whether matrix ``A`` is upper or lower triangular. See :ref:`data-types` for more details.

n
   Number of columns of matrix ``A``. Must be at least zero.

alpha
   Scaling factor for the matrix-vector product.

x
   Pointer to input vector ``x``. Size of the array holding input vector
   ``x`` must be at least (1 + (``n`` - 1)*abs(``incx``)). See :ref:`matrix-storage` for more details.

incx
   Stride of vector ``x``.

y
   Pointer to input/output vector ``y``. Size of the array holding
   input/output vector ``y`` must be at least (1 + (``n`` -
   1)*abs(``incy``)). See :ref:`matrix-storage` for more details.

incy
   Stride of vector ``y``.

a
   Pointer to input matrix ``A``. Size of the array holding input matrix
   ``A`` must be at least ``lda`` * ``n``. See :ref:`matrix-storage` for more details.

lda
   Leading dimension of matrix ``A``. Must be at least ``n`` and positive.

dependencies
   List of events to wait for before starting computation, if any. If
   omitted, defaults to no dependencies.

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

a
   Pointer to updated upper triangular part of the hermitian
   matrix ``A`` if ``upper_lower=upper``, or updated
   lower triangular part of the hermitian matrix ``A`` if
   ``upper_lower=lower``.

   The imaginary parts of the diagonal elements are set to zero.

Return Values
-------------

Output event to wait on to ensure computation is complete.