.. _onemkl_blas_gemm_bias: gemm_bias ========= Computes a matrix-matrix product using general integer matrices with bias. Description *********** The ``gemm_bias`` routines compute a scalar-matrix-matrix product and add the result to a scalar-matrix product, using general integer matrices with biases/offsets. The operation is defined as: .. math:: C \leftarrow alpha*(op(A) - A\_offset)*(op(B) - B\_offset) + beta*C + C\_offset 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_offset`` is ``m`` x ``k`` matrix with every element equal to the value ``ao`` - ``B_offset`` is ``k`` x ``n`` matrix with every element equal to the value ``bo`` - ``C_offset`` is ``m`` x ``n`` matrix defined by the ``co`` buffer. See :ref:`data-types` for more details. - ``A``, ``B``, and ``C`` are matrices - op(``A``) is ``m`` x ``k``, op(``B``) is ``k`` x ``n``, and ``C`` is ``m`` x ``n`` ``gemm_bias`` supports the following precisions: .. list-table:: :header-rows: 1 * - Ts - Ta - Tb - Tc * - ``float`` - ``std::uint8_t`` - ``std::uint8_t`` - ``std::int32_t`` * - ``float`` - ``std::int8_t`` - ``std::uint8_t`` - ``std::int32_t`` * - ``float`` - ``std::uint8_t`` - ``std::int8_t`` - ``std::int32_t`` * - ``float`` - ``std::int8_t`` - ``std::int8_t`` - ``std::int32_t`` gemm_bias (Buffer Version) ************************** Syntax ------ .. code-block:: cpp namespace oneapi::mkl::blas::column_major { void gemm_bias(sycl::queue &queue, oneapi::mkl::transpose transa, oneapi::mkl::transpose transb, oneapi::mkl::offset offsetc, std::int64_t m, std::int64_t n, std::int64_t k, Ts alpha, sycl::buffer &a, std::int64_t lda, Ta ao, sycl::buffer &b, std::int64_t ldb, Tb bo, Ts beta, sycl::buffer &c, std::int64_t ldc, sycl::buffer &co) } .. code-block:: cpp namespace oneapi::mkl::blas::row_major { void gemm_bias(sycl::queue &queue, oneapi::mkl::transpose transa, oneapi::mkl::transpose transb, oneapi::mkl::offset offsetc, std::int64_t m, std::int64_t n, std::int64_t k, Ts alpha, sycl::buffer &a, std::int64_t lda, Ta ao, sycl::buffer &b, std::int64_t ldb, Tb bo, Ts beta, sycl::buffer &c, std::int64_t ldc, sycl::buffer &co) } Input Parameters ---------------- queue The queue where the routine should be executed. transa Specifies op(``A``), the transposition operation applied to matrix ``A``. See :ref:`data-types` for more details. transb Specifies op(``B``), the transposition operation applied to matrix ``B``. See :ref:`data-types` for more details. offsetc Specifies the form of ``C_offset`` used in the matrix multiplication. See :ref:`data-types` for more details. m Number of rows of matrix op(``A``) and matrix ``C``. Must be at least zero. n Number of columns of matrix op(``B``) and matrix ``C``. Must be at least zero. k Number of columns of matrix op(``A``) and rows of matrix op(``B``). Must be at least zero. alpha Scaling factor for matrix-matrix product. a Buffer holding input matrix ``A``. See :ref:`matrix-storage` for more details. .. list-table:: :header-rows: 1 * - - ``transa`` = ``transpose::nontrans`` - ``transa`` = ``transpose::trans`` or ``trans`` = ``transpose::conjtrans`` * - Column major - ``A`` is ``m`` x ``k`` matrix. Size of array ``a`` must be at least ``lda`` * ``k`` - ``A`` is ``k`` x ``m`` matrix. Size of array ``a`` must be at least ``lda`` * ``m`` * - Row major - ``A`` is ``m`` x ``k`` matrix. Size of array ``a`` must be at least ``lda`` * ``m`` - ``A`` is ``k`` x ``m`` matrix. Size of array ``a`` must be at least ``lda`` * ``k`` lda Leading dimension of matrix ``A``. Must be positive. .. list-table:: :header-rows: 1 * - - ``transa`` = ``transpose::nontrans`` - ``transa`` = ``transpose::trans`` or ``trans`` = ``transpose::conjtrans`` * - Column major - Must be at least ``m`` - Must be at least ``k`` * - Row major - Must be at least ``k`` - Must be at least ``m`` ao Specifies the scalar offset value for matrix ``A``. b Buffer holding input matrix ``B``. See :ref:`matrix-storage` for more details. .. list-table:: :header-rows: 1 * - - ``transb`` = ``transpose::nontrans`` - ``transb`` = ``transpose::trans`` or ``trans`` = ``transpose::conjtrans`` * - Column major - ``B`` is ``k`` x ``n`` matrix. Size of array ``b`` must be at least ``ldb`` * ``n`` - ``B`` is ``n`` x ``k`` matrix. Size of array ``b`` must be at least ``ldb`` * ``k`` * - Row major - ``B`` is ``k`` x ``n`` matrix. Size of array ``b`` must be at least ``ldb`` * ``k`` - ``B`` is ``n`` x ``k`` matrix. Size of array ``b`` must be at least ``ldb`` * ``n`` ldb Leading dimension of matrix ``B``. Must be positive. .. list-table:: :header-rows: 1 * - - ``transb`` = ``transpose::nontrans`` - ``transb`` = ``transpose::trans`` or ``trans`` = ``transpose::conjtrans`` * - Column major - Must be at least ``k`` - Must be at least ``n`` * - Row major - Must be at least ``n`` - Must be at least ``k`` bo Specifies the scalar offset value for matrix ``B``. beta Scaling factor for matrix ``C``. c Buffer holding input/output matrix ``C``. See :ref:`matrix-storage` for more details. .. list-table:: * - Column major - ``C`` is ``m`` x ``n`` matrix. Size of array ``c`` must be at least ``ldc`` * ``n`` * - Row major - ``C`` is ``m`` x ``n`` matrix. Size of array ``c`` must be at least ``ldc`` * ``m`` ldc Leading dimension of matrix ``C``. Must be positive. .. list-table:: * - Column major - Must be at least ``m`` * - Row major - Must be at least ``n`` co Buffer holding the offset values for matrix ``C``. If ``offset_type = offset::fix``, size of ``co`` array must be at least 1. If ``offset_type = offset::col``, size of ``co`` array must be at least ``max(1,m)``. If ``offset_type = offset::row``, size of ``co`` array must be at least ``max(1,n)``. See :ref:`data-types` for more details. Output Parameters ----------------- c Output buffer overwritten by ``alpha`` * (op(``A``) - ``A_offset``) * (op(``B``) - ``B_offset``) + ``beta`` * ``C`` + ``C_offset``. .. note:: If ``beta`` = 0, matrix ``C`` does not need to be initialized before calling ``gemm_bias``. gemm_bias (USM Version) ************************** Syntax ------ .. code-block:: cpp namespace oneapi::mkl::blas::column_major { sycl::event gemm_bias(sycl::queue &queue, oneapi::mkl::transpose transa, oneapi::mkl::transpose transb, oneapi::mkl::offset offsetc, std::int64_t m, std::int64_t n, std::int64_t k, Ts alpha, const Ta *a, std::int64_t lda, Ta ao, const Tb *b, std::int64_t ldb, Tb bo, Ts beta, Tc *c, std::int64_t ldc, const Tc *co, const std::vector &dependencies = {}) } .. code-block:: cpp namespace oneapi::mkl::blas::row_major { sycl::event gemm_bias(sycl::queue &queue, oneapi::mkl::transpose transa, oneapi::mkl::transpose transb, oneapi::mkl::offset offsetc, std::int64_t m, std::int64_t n, std::int64_t k, Ts alpha, const Ta *a, std::int64_t lda, Ta ao, const Tb *b, std::int64_t ldb, Tb bo, Ts beta, Tc *c, std::int64_t ldc, const Tc *co, const std::vector &dependencies = {}) } Input Parameters ---------------- queue The queue where the routine should be executed. transa Specifies op(``A``), the transposition operation applied to matrix ``A``. See :ref:`data-types` for more details. transb Specifies op(``B``), the transposition operation applied to matrix ``B``. See :ref:`data-types` for more details. offsetc Specifies the form of ``C_offset`` used in the matrix multiplication. See :ref:`data-types` for more details. m Number of rows of matrix op(``A``) and matrix ``C``. Must be at least zero. n Number of columns of matrix op(``B``) and matrix ``C``. Must be at least zero. k Number of columns of matrix op(``A``) and rows of matrix op(``B``). Must be at least zero. alpha Scaling factor for matrix-matrix product. a Pointer to input matrix ``A``. See :ref:`matrix-storage` for more details. .. list-table:: :header-rows: 1 * - - ``transa`` = ``transpose::nontrans`` - ``transa`` = ``transpose::trans`` or ``trans`` = ``transpose::conjtrans`` * - Column major - ``A`` is ``m`` x ``k`` matrix. Size of array ``a`` must be at least ``lda`` * ``k`` - ``A`` is ``k`` x ``m`` matrix. Size of array ``a`` must be at least ``lda`` * ``m`` * - Row major - ``A`` is ``m`` x ``k`` matrix. Size of array ``a`` must be at least ``lda`` * ``m`` - ``A`` is ``k`` x ``m`` matrix. Size of array ``a`` must be at least ``lda`` * ``k`` lda Leading dimension of matrix ``A``. Must be positive. .. list-table:: :header-rows: 1 * - - ``transa`` = ``transpose::nontrans`` - ``transa`` = ``transpose::trans`` or ``trans`` = ``transpose::conjtrans`` * - Column major - Must be at least ``m`` - Must be at least ``k`` * - Row major - Must be at least ``k`` - Must be at least ``m`` ao Specifies the scalar offset value for matrix ``A``. b Pointer to input matrix ``B``. See :ref:`matrix-storage` for more details. .. list-table:: :header-rows: 1 * - - ``transb`` = ``transpose::nontrans`` - ``transb`` = ``transpose::trans`` or ``trans`` = ``transpose::conjtrans`` * - Column major - ``B`` is ``k`` x ``n`` matrix. Size of array ``b`` must be at least ``ldb`` * ``n`` - ``B`` is ``n`` x ``k`` matrix. Size of array ``b`` must be at least ``ldb`` * ``k`` * - Row major - ``B`` is ``k`` x ``n`` matrix. Size of array ``b`` must be at least ``ldb`` * ``k`` - ``B`` is ``n`` x ``k`` matrix. Size of array ``b`` must be at least ``ldb`` * ``n`` ldb Leading dimension of matrix ``B``. Must be positive. .. list-table:: :header-rows: 1 * - - ``transb`` = ``transpose::nontrans`` - ``transb`` = ``transpose::trans`` or ``trans`` = ``transpose::conjtrans`` * - Column major - Must be at least ``k`` - Must be at least ``n`` * - Row major - Must be at least ``n`` - Must be at least ``k`` bo Specifies the scalar offset value for matrix ``B``. beta Scaling factor for matrix ``C``. c Pointer to input/output matrix ``C``. See :ref:`matrix-storage` for more details. .. list-table:: * - Column major - ``C`` is ``m`` x ``n`` matrix. Size of array ``c`` must be at least ``ldc`` * ``n`` * - Row major - ``C`` is ``m`` x ``n`` matrix. Size of array ``c`` must be at least ``ldc`` * ``m`` ldc Leading dimension of matrix ``C``. Must be positive. .. list-table:: * - Column major - Must be at least ``m`` * - Row major - Must be at least ``n`` co Pointer to array holding offset values for matrix ``C``. If ``offset_type = offset::fix``, size of ``co`` array must be at least 1. If ``offset_type = offset::col``, size of ``co`` array must be at least ``max(1,m)``. If ``offset_type = offset::row``, size of ``co`` array must be at least ``max(1,n)``. See :ref:`data-types` for more details. dependencies List of events to wait for before starting computation, if any. If omitted, defaults to no dependencies. Output Parameters ----------------- c Pointer to output matrix ``C`` overwritten by ``alpha`` * (op(``A``) - ``A_offset``) * (op(``B``) - ``B_offset``) + ``beta`` * ``C`` + ``C_offset``. .. note:: If ``beta`` = 0, matrix ``C`` does not need to be initialized before calling ``gemm_bias``. Return Values ------------- Output event to wait on to ensure computation is complete.