diff --git a/source/elements/oneMath/source/domains/blas/blas-level-3-routines.rst b/source/elements/oneMath/source/domains/blas/blas-level-3-routines.rst index 28529b240f..886b589dae 100644 --- a/source/elements/oneMath/source/domains/blas/blas-level-3-routines.rst +++ b/source/elements/oneMath/source/domains/blas/blas-level-3-routines.rst @@ -24,6 +24,9 @@ BLAS Level 3 Routines - Description * - :ref:`onemath_blas_gemm` - Computes a matrix-matrix product with general matrices. + * - :ref:`onemath_blas_gemmtr` + - Computes a matrix-matrix product with general matrices, but updates + only the upper or lower triangular part of the result matrix. * - :ref:`onemath_blas_hemm` - Computes a matrix-matrix product where one input matrix is Hermitian and one is general. * - :ref:`onemath_blas_herk` @@ -47,6 +50,7 @@ BLAS Level 3 Routines :hidden: gemm + gemmtr hemm herk her2k diff --git a/source/elements/oneMath/source/domains/blas/blas-like-extensions.rst b/source/elements/oneMath/source/domains/blas/blas-like-extensions.rst index 65143cbae3..36f52b6fad 100644 --- a/source/elements/oneMath/source/domains/blas/blas-like-extensions.rst +++ b/source/elements/oneMath/source/domains/blas/blas-like-extensions.rst @@ -32,8 +32,10 @@ BLAS-like Extensions - Computes groups of matrix-matrix products with general matrices. * - :ref:`onemath_blas_trsm_batch` - Solves a triangular matrix equation for a group of matrices. - * - :ref:`onemath_blas_gemmt` - - Computes a matrix-matrix product with general matrices, but updates + * - :ref:`onemath_blas_gemmt` (deprecated) + - **gemmt has been deprecated. Use level 3** :ref:`onemath_blas_gemmtr` **instead.** + + Computes a matrix-matrix product with general matrices, but updates only the upper or lower triangular part of the result matrix. * - :ref:`onemath_blas_gemm_bias` - Computes a matrix-matrix product using general integer matrices with bias diff --git a/source/elements/oneMath/source/domains/blas/gemmt.rst b/source/elements/oneMath/source/domains/blas/gemmt.rst index e876ce7a06..2421b5b5ee 100644 --- a/source/elements/oneMath/source/domains/blas/gemmt.rst +++ b/source/elements/oneMath/source/domains/blas/gemmt.rst @@ -7,6 +7,8 @@ gemmt ===== +.. warning:: gemmt has been deprecated. Use level 3 :ref:`onemath_blas_gemmtr` instead. + Computes a matrix-matrix product with general matrices, but updates only the upper or lower triangular part of the result matrix. diff --git a/source/elements/oneMath/source/domains/blas/gemmtr.rst b/source/elements/oneMath/source/domains/blas/gemmtr.rst new file mode 100644 index 0000000000..822bbdb687 --- /dev/null +++ b/source/elements/oneMath/source/domains/blas/gemmtr.rst @@ -0,0 +1,463 @@ +.. SPDX-FileCopyrightText: 2019-2026 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemath_blas_gemmtr: + +gemmtr +====== + +Computes a matrix-matrix product with general matrices, but updates +only the upper or lower triangular part of the result matrix. + +.. _onemath_blas_gemmtr_description: + +.. rubric:: Description + +The gemmtr routines compute a scalar-matrix-matrix product and add +the result to the upper or lower part of a scalar-matrix product, +with general matrices. The operation is defined as: + +.. math:: + + C \leftarrow alpha*op(A)*op(B) + beta*C + +where: + +op(``X``) is one of op(``X``) = ``X``, or op(``X``) = ``X``\ :sup:`T`, or +op(``X``) = ``X``\ :sup:`H`, + +``alpha`` and ``beta`` are scalars + +``A``, ``B``, and ``C`` are matrices + +op(``A``) is ``n`` x ``k``, op(``B``) is ``k`` x ``n``, and +``C`` is ``n`` x ``n``. + +``gemmtr`` supports the following precisions. + + .. list-table:: + :header-rows: 1 + + * - T + * - ``float`` + * - ``double`` + * - ``std::complex`` + * - ``std::complex`` + +.. _onemath_blas_gemmtr_buffer: + +gemmtr (Buffer Version) +----------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::math::blas::column_major { + void gemmtr(sycl::queue &queue, + oneapi::math::uplo upper_lower, + oneapi::math::transpose transa, + oneapi::math::transpose transb, + std::int64_t n, + std::int64_t k, + T alpha, + sycl::buffer &a, + std::int64_t lda, + sycl::buffer &b, + std::int64_t ldb, + T beta, + sycl::buffer &c, + std::int64_t ldc) + } +.. code-block:: cpp + + namespace oneapi::math::blas::row_major { + void gemmtr(sycl::queue &queue, + oneapi::math::uplo upper_lower, + oneapi::math::transpose transa, + oneapi::math::transpose transb, + std::int64_t n, + std::int64_t k, + T alpha, + sycl::buffer &a, + std::int64_t lda, + sycl::buffer &b, + std::int64_t ldb, + T 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 ``C``\ ’s data is stored in its upper or + lower triangle. See :ref:`onemath_datatypes` for more details. + + transa + Specifies op(``A``), the transposition operation applied to + ``A``. See :ref:`onemath_datatypes` for more details. + + transb + Specifies op(``B``), the transposition operation applied to + ``B``. See :ref:`onemath_datatypes` for more details. + + n + Number of rows of op(``A``), columns of op(``B``), and + columns and rows of\ ``C``. Must be at least zero. + + k + Number of columns of op(``A``) and rows of op(``B``). Must be + at least zero. + + alpha + Scaling factor for the matrix-matrix product. + + a + Buffer holding the input matrix ``A``. + + .. list-table:: + :header-rows: 1 + + * - + - ``A`` not transposed + - ``A`` transposed + * - 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 + + * - + - ``A`` not transposed + - ``A`` transposed + * - 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 the input matrix ``B``. + + .. list-table:: + :header-rows: 1 + + * - + - ``B`` not transposed + - ``B`` transposed + * - 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 + + * - + - ``B`` not transposed + - ``B`` transposed + * - 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 + Scaling factor for matrix ``C``. + + c + Buffer holding the 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 + ``m``. + +.. container:: section + + .. rubric:: Output Parameters + + c + Output buffer, overwritten by the upper or lower triangular + part of ``alpha`` * op(``A``)*op(``B``) + ``beta`` * ``C``. + +.. container:: section + + .. rubric:: Notes + + If ``beta`` = 0, matrix ``C`` does not need to be initialized + before calling gemmtr. + +.. 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_gemmtr_usm: + +gemmtr (USM Version) +-------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::math::blas::column_major { + sycl::event gemmtr(sycl::queue &queue, + oneapi::math::uplo upper_lower, + oneapi::math::transpose transa, + oneapi::math::transpose transb, + 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 gemmtr(sycl::queue &queue, + oneapi::math::uplo upper_lower, + oneapi::math::transpose transa, + oneapi::math::transpose transb, + 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 ``C``\ ’s data is stored in its upper or + lower triangle. See + :ref:`onemath_datatypes` for + more details. + + transa + Specifies op(``A``), the transposition operation applied to + ``A``. See + :ref:`onemath_datatypes` for + more details. + + transb + Specifies op(``B``), the transposition operation applied to + ``B``. See + :ref:`onemath_datatypes` for + more details. + + n + Number of columns of op(``A``), columns of op(``B``), and + columns of\ ``C``. Must be at least zero. + + k + Number of columns of op(``A``) and rows of op(``B``). Must be + at least zero. + + alpha + Scaling factor for the matrix-matrix product. See :ref:`value_or_pointer` for more details. + + a + Pointer to input matrix ``A``. + + .. list-table:: + :header-rows: 1 + + * - + - ``A`` not transposed + - ``A`` transposed + * - 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 + + * - + - ``A`` not transposed + - ``A`` transposed + * - 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 + + * - + - ``B`` not transposed + - ``B`` transposed + * - 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 + + * - + - ``B`` not transposed + - ``B`` transposed + * - 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 + 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 + ``m``. + + 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 upper or lower + triangular part of ``alpha`` * op(``A``)*op(``B``) + ``beta`` * ``C``. + +.. container:: section + + .. rubric:: Notes + + If ``beta`` = 0, matrix ``C`` does not need to be initialized + before calling gemmtr. + +.. 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` diff --git a/source/spelling_wordlist.txt b/source/spelling_wordlist.txt index b27e011bbe..9f697f6de3 100644 --- a/source/spelling_wordlist.txt +++ b/source/spelling_wordlist.txt @@ -366,6 +366,7 @@ gebrd gelu gemm gemmt +gemmtr gemt gemv gemvOptimize