.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 .. _onemath_blas_her2k: her2k ===== Performs a Hermitian rank-2k update. .. _onemath_blas_her2k_description: .. rubric:: Description The ``her2k`` routines perform a rank-2k update of an ``n`` x ``n`` Hermitian matrix ``C`` by general matrices ``A`` and ``B``. If ``trans`` = ``transpose::nontrans``, the operation is defined as: .. math:: C \leftarrow alpha*A*B^H + conjg(alpha)*B*A^H + beta*C where ``A`` is ``n`` x ``k`` and ``B`` is ``k`` x ``n``. If ``trans`` = ``transpose::conjtrans``, the operation is defined as: .. math:: C \leftarrow alpha*B*A^H + conjg(alpha)*A*B^H + beta*C where ``A`` is ``k`` x ``n`` and ``B`` is ``n`` x ``k``. In both cases: ``alpha`` is a complex scalar and ``beta`` is a real scalar. ``C`` is a Hermitian matrix and ``A`` , ``B`` are general matrices. The inner dimension of both matrix multiplications is ``k``. ``her2k`` supports the following precisions: .. list-table:: :header-rows: 1 * - T - Treal * - ``std::complex`` - ``float`` * - ``std::complex`` - ``double`` .. _onemath_blas_her2k_buffer: her2k (Buffer Version) ---------------------- .. rubric:: Syntax .. code-block:: cpp namespace oneapi::math::blas::column_major { void her2k(sycl::queue &queue, oneapi::math::uplo upper_lower, oneapi::math::transpose trans, std::int64_t n, std::int64_t k, T alpha, sycl::buffer &a, std::int64_t lda, sycl::buffer &b, std::int64_t ldb, Treal beta, sycl::buffer &c, std::int64_t ldc) } .. code-block:: cpp namespace oneapi::math::blas::row_major { void her2k(sycl::queue &queue, oneapi::math::uplo upper_lower, oneapi::math::transpose trans, std::int64_t n, std::int64_t k, T alpha, sycl::buffer &a, std::int64_t lda, sycl::buffer &b, std::int64_t ldb, Treal beta, sycl::buffer &c, std::int64_t ldc) } .. container:: section .. rubric:: Input Parameters queue The queue where the routine should be executed. upper_lower Specifies whether ``A``'s data is stored in its upper or lower triangle. See :ref:`onemath_datatypes` for more details. trans Specifies the operation to apply, as described above. Supported operations are ``transpose::nontrans`` and ``transpose::conjtrans``. n The number of rows and columns in ``C``. The value of ``n`` must be at least zero. k The inner dimension of matrix multiplications. The value of ``k`` must be at least equal to zero. alpha Complex scaling factor for the rank-2k update. a Buffer holding input matrix ``A``. .. list-table:: :header-rows: 1 * - - ``trans`` = ``transpose::nontrans`` - ``trans`` = ``transpose::trans`` or ``transpose::conjtrans`` * - Column major - ``A`` is an ``n``-by-``k`` matrix so the array ``a`` must have size at least ``lda``\ \*\ ``k``. - ``A`` is an ``k``-by-``n`` matrix so the array ``a`` must have size at least ``lda``\ \*\ ``n`` * - Row major - ``A`` is an ``n``-by-``k`` matrix so the array ``a`` must have size at least ``lda``\ \*\ ``n``. - ``A`` is an ``k``-by-``n`` matrix so the array ``a`` must have size at least ``lda``\ \*\ ``k``. See :ref:`matrix-storage` for more details. lda The leading dimension of ``A``. It must be positive. .. list-table:: :header-rows: 1 * - - ``trans`` = ``transpose::nontrans`` - ``trans`` = ``transpose::trans`` or ``transpose::conjtrans`` * - Column major - ``lda`` must be at least ``n``. - ``lda`` must be at least ``k``. * - Row major - ``lda`` must be at least ``k``. - ``lda`` must be at least ``n``. b Buffer holding input matrix ``B``. .. list-table:: :header-rows: 1 * - - ``trans`` = ``transpose::nontrans`` - ``trans`` = ``transpose::trans`` or ``transpose::conjtrans`` * - Column major - ``B`` is an ``k``-by-``n`` matrix so the array ``b`` must have size at least ``ldb``\ \*\ ``n``. - ``B`` is an ``n``-by-``k`` matrix so the array ``b`` must have size at least ``ldb``\ \*\ ``k`` * - Row major - ``B`` is an ``k``-by-``n`` matrix so the array ``b`` must have size at least ``ldb``\ \*\ ``k``. - ``B`` is an ``n``-by-``k`` matrix so the array ``b`` must have size at least ``ldb``\ \*\ ``n``. See :ref:`matrix-storage` for more details. ldb The leading dimension of ``B``. It must be positive. .. list-table:: :header-rows: 1 * - - ``trans`` = ``transpose::nontrans`` - ``trans`` = ``transpose::trans`` or ``transpose::conjtrans`` * - Column major - ``ldb`` must be at least ``k``. - ``ldb`` must be at least ``n``. * - Row major - ``ldb`` must be at least ``n``. - ``ldb`` must be at least ``k``. beta Real scaling factor for matrix ``C``. c Buffer holding input/output matrix ``C``. Must have size at least ``ldc``\ \*\ ``n``. See :ref:`matrix-storage` for more details. ldc Leading dimension of ``C``. Must be positive and at least ``n``. .. container:: section .. rubric:: Output Parameters c Output buffer, overwritten by the updated ``C`` matrix. .. container:: section .. rubric:: Throws This routine shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here. :ref:`oneapi::math::invalid_argument` :ref:`oneapi::math::unsupported_device` :ref:`oneapi::math::host_bad_alloc` :ref:`oneapi::math::device_bad_alloc` :ref:`oneapi::math::unimplemented` .. _onemath_blas_her2k_usm: her2k (USM Version) ------------------- .. rubric:: Syntax .. code-block:: cpp namespace oneapi::math::blas::column_major { sycl::event her2k(sycl::queue &queue, oneapi::math::uplo upper_lower, oneapi::math::transpose trans, std::int64_t n, std::int64_t k, value_or_pointer alpha, const T *a, std::int64_t lda, const T *b, std::int64_t ldb, value_or_pointer beta, T *c, std::int64_t ldc, const std::vector &dependencies = {}) } .. code-block:: cpp namespace oneapi::math::blas::row_major { sycl::event her2k(sycl::queue &queue, oneapi::math::uplo upper_lower, oneapi::math::transpose trans, std::int64_t n, std::int64_t k, value_or_pointer alpha, const T *a, std::int64_t lda, const T *b, std::int64_t ldb, value_or_pointer beta, T *c, std::int64_t ldc, const std::vector &dependencies = {}) } .. container:: section .. rubric:: Input Parameters queue The queue where the routine should be executed. upper_lower Specifies whether ``A``'s data is stored in its upper or lower triangle. See :ref:`onemath_datatypes` for more details. trans Specifies the operation to apply, as described above. Supported operations are ``transpose::nontrans`` and ``transpose::conjtrans``. n The number of rows and columns in ``C``. The value of ``n`` must be at least zero. k The inner dimension of matrix multiplications. The value of ``k`` must be at least equal to zero. alpha Complex scaling factor for the rank-2k update. See :ref:`value_or_pointer` for more details. a Pointer to input matrix ``A``. .. list-table:: :header-rows: 1 * - - ``trans`` = ``transpose::nontrans`` - ``trans`` = ``transpose::trans`` or ``transpose::conjtrans`` * - Column major - ``A`` is an ``n``-by-``k`` matrix so the array ``a`` must have size at least ``lda``\ \*\ ``k``. - ``A`` is an ``k``-by-``n`` matrix so the array ``a`` must have size at least ``lda``\ \*\ ``n`` * - Row major - ``A`` is an ``n``-by-``k`` matrix so the array ``a`` must have size at least ``lda``\ \*\ ``n``. - ``A`` is an ``k``-by-``n`` matrix so the array ``a`` must have size at least ``lda``\ \*\ ``k``. See :ref:`matrix-storage` for more details. lda The leading dimension of ``A``. It must be positive. .. list-table:: :header-rows: 1 * - - ``trans`` = ``transpose::nontrans`` - ``trans`` = ``transpose::trans`` or ``transpose::conjtrans`` * - Column major - ``lda`` must be at least ``n``. - ``lda`` must be at least ``k``. * - Row major - ``lda`` must be at least ``k``. - ``lda`` must be at least ``n``. b Pointer to input matrix ``B``. .. list-table:: :header-rows: 1 * - - ``trans`` = ``transpose::nontrans`` - ``trans`` = ``transpose::trans`` or ``transpose::conjtrans`` * - Column major - ``B`` is an ``k``-by-``n`` matrix so the array ``b`` must have size at least ``ldb``\ \*\ ``n``. - ``B`` is an ``n``-by-``k`` matrix so the array ``b`` must have size at least ``ldb``\ \*\ ``k`` * - Row major - ``B`` is an ``k``-by-``n`` matrix so the array ``b`` must have size at least ``ldb``\ \*\ ``k``. - ``B`` is an ``n``-by-``k`` matrix so the array ``b`` must have size at least ``ldb``\ \*\ ``n``. See :ref:`matrix-storage` for more details. ldb The leading dimension of ``B``. It must be positive. .. list-table:: :header-rows: 1 * - - ``trans`` = ``transpose::nontrans`` - ``trans`` = ``transpose::trans`` or ``transpose::conjtrans`` * - Column major - ``ldb`` must be at least ``k``. - ``ldb`` must be at least ``n``. * - Row major - ``ldb`` must be at least ``n``. - ``ldb`` must be at least ``k``. beta Real scaling factor for matrix ``C``. See :ref:`value_or_pointer` for more details. c Pointer to input/output matrix ``C``. Must have size at least ``ldc``\ \*\ ``n``. See :ref:`matrix-storage` for more details. ldc Leading dimension of ``C``. Must be positive and at least ``n``. dependencies List of events to wait for before starting computation, if any. If omitted, defaults to no dependencies. .. container:: section .. rubric:: Output Parameters c Pointer to the output matrix, overwritten by the updated ``C`` matrix. .. container:: section .. rubric:: Return Values Output event to wait on to ensure computation is complete. .. container:: section .. rubric:: Throws This routine shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here. :ref:`oneapi::math::invalid_argument` :ref:`oneapi::math::unsupported_device` :ref:`oneapi::math::host_bad_alloc` :ref:`oneapi::math::device_bad_alloc` :ref:`oneapi::math::unimplemented` **Parent topic:** :ref:`blas-level-3-routines`