[oneMKL][BLAS] add out-of-place TRMM and TRSM (#523)

* [oneMKL][BLAS] update TRMM spec for out-of-place operation

* [oneMKL][BLAS] update TRSM spec for out-of-place operation

* Consistent indentation

* Consistent uplo / upper_lower naming

Author: andrewtbarker

source/elements/oneMKL/source/domains/blas/trmm.rst

@@ -19,7 +19,9 @@ the matrices in the multiplication is triangular. The argument
 ``left_right`` determines if the triangular matrix, ``A``, is on the
 left of the multiplication (``left_right`` = ``side::left``) or on
 the right (``left_right`` = ``side::right``). Depending on
-``left_right``. The operation is defined as:
+``left_right``.
+
+There are two operations available, an in-place operation and an out-of-place operation. The in-place operation is defined as:
 
 .. math::
 
@@ -31,16 +33,28 @@ or
 
       B \leftarrow alpha*B*op(A)
 
+The out-of-place operation is defined as:
+
+.. math::
+
+      C \leftarrow alpha*op(A)*B + beta*C
+
+or
+
+.. math::
+
+      C \leftarrow alpha*B*op(A) + beta*C
+
 where:
 
 op(``A``) is one of op(``A``) = *A*, or op(``A``) = ``A``\ :sup:`T`,
 or op(``A``) = ``A``\ :sup:`H`,
 
-``alpha`` is a scalar,
+``alpha`` and ``beta`` are scalars,
 
-``A`` is a triangular matrix, and ``B`` is a general matrix.
+``A`` is a triangular matrix, and ``B`` and ``C`` are general matrices.
 
-Here ``B`` is ``m`` x ``n`` and ``A`` is either ``m`` x ``m`` or
+Here ``B`` and ``C`` are  ``m`` x ``n`` and ``A`` is either ``m`` x ``m`` or
 ``n`` x ``n``, depending on ``left_right``.
 
 ``trmm`` supports the following precisions.
@@ -59,12 +73,16 @@ Here ``B`` is ``m`` x ``n`` and ``A`` is either ``m`` x ``m`` or
 trmm (Buffer Version)
 ---------------------
 
+**In-place API**
+----------------
+
 .. rubric:: Syntax
 
 .. code-block:: cpp
 
    namespace oneapi::mkl::blas::column_major {
        void trmm(sycl::queue &queue,
+                 onemkl::side left_right,
                  onemkl::uplo upper_lower,
                  onemkl::transpose transa,
                  onemkl::diag unit_diag,
@@ -80,6 +98,7 @@ trmm (Buffer Version)
 
    namespace oneapi::mkl::blas::row_major {
        void trmm(sycl::queue &queue,
+                 onemkl::side left_right,
                  onemkl::uplo upper_lower,
                  onemkl::transpose transa,
                  onemkl::diag unit_diag,
@@ -103,7 +122,7 @@ trmm (Buffer Version)
       Specifies whether ``A`` is on the left side of the multiplication
       (``side::left``) or on the right side (``side::right``). See :ref:`onemkl_datatypes` for more details.
 
-   uplo
+   upper_lower
       Specifies whether the matrix ``A`` is upper or lower triangular. See :ref:`onemkl_datatypes` for more details.
 
    trans
@@ -181,19 +200,149 @@ trmm (Buffer Version)
 
 
    :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
-      
 
+**Out-of-place API**
+--------------------
+
+.. rubric:: Syntax
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::blas::column_major {
+       void trmm(sycl::queue &queue,
+                 onemkl::side left_right,
+                 onemkl::uplo upper_lower,
+                 onemkl::transpose trans,
+                 onemkl::diag unit_diag,
+                 std::int64_t m,
+                 std::int64_t n,
+                 T alpha,
+                 sycl::buffer<T,1> &a,
+                 std::int64_t lda,
+                 sycl::buffer<T,1> &b,
+                 std::int64_t ldb,
+                 T beta,
+                 sycl::buffer<T,1> &c,
+                 std::int64_t ldc)
+   }
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::blas::row_major {
+       void trmm(sycl::queue &queue,
+                 onemkl::side left_right,
+                 onemkl::uplo upper_lower,
+                 onemkl::transpose trans,
+                 onemkl::diag unit_diag,
+                 std::int64_t m,
+                 std::int64_t n,
+                 T alpha,
+                 sycl::buffer<T,1> &a,
+                 std::int64_t lda,
+                 sycl::buffer<T,1> &b,
+                 std::int64_t ldb,
+                 T beta,
+                 sycl::buffer<T,1> &c,
+                 std::int64_t ldc)
+   }
+
+
+.. container:: section
+
+   .. rubric:: Input Parameters
+
+   queue
+      The queue where the routine should be executed.
+
+   left_right
+      Specifies whether ``A`` is on the left side of the multiplication
+      (``side::left``) or on the right side (``side::right``). See :ref:`onemkl_datatypes` for more details.
+
+   upper_lower
+      Specifies whether the matrix ``A`` is upper or lower triangular. See :ref:`onemkl_datatypes` for more details.
+
+   trans
+      Specifies op(``A``), the transposition operation applied to matrix ``A``. See :ref:`onemkl_datatypes` for more details.
+
+   unit_diag
+      Specifies whether ``A`` is assumed to be unit triangular (all diagonal elements are 1). See :ref:`onemkl_datatypes` for more details.
+
+   m
+      Specifices the number of rows of ``B``. The value of ``m`` must be at least zero.
+
+   n
+      Specifies the Number of columns of ``B``. The value of ``n`` must be at least zero.
+
+   alpha
+      Scaling factor for matrix-matrix product.
+
+   a
+      Buffer holding input matrix ``A``. Must have size at least
+      ``lda``\ \*\ ``m`` if ``left_right`` = ``side::left`` or ``lda``\ \*\ ``n`` if ``left_right`` = ``side::right``. See :ref:`matrix-storage` for more details.
+
+   lda
+      Leading dimension of ``A``. Must be at least ``m`` if ``left_right`` = ``side::left`` or at least ``n`` if ``left_right`` = ``side::right``. Must be positive.
+
+   b
+      Buffer holding input matrix ``B``. Must have size at least
+      ``ldb``\ \*\ ``n`` if column major layout or at least ``ldb``\ \*\ ``m`` if row major layout is used. See :ref:`matrix-storage` for more details.
+
+   ldb
+      Leading dimension of matrix ``B``. It must be positive and at least ``m`` if column major layout or at least ``n`` if row major layout is used.
+
+   beta
+      Scaling factor for matrix ``C``.
+
+   c
+      Buffer holding input/output matrix ``C``. Size of the buffer must be at least
+      ``ldc``\ \*\ ``n`` if column major layout or at least ``ldc``\ \*\ ``m`` if row major layout is used. See :ref:`matrix-storage` for more details.
+
+   ldc
+      Leading dimension of matrix ``C``. Must be at least ``m`` if column major layout or at least ``n`` if row major layout is used. Must be positive.
+
+.. container:: section
+
+   .. rubric:: Output Parameters
+
+   c
+      Output buffer overwritten by ``alpha``\ \*\ op(``A``)\ \*\ ``B`` + ``beta``\ \*\ ``C`` if ``left_right`` = ``side::left`` or ``alpha``\ \*\ ``B``\ \*\ op(``A``) + ``beta``\ \*\ ``C`` if ``left_right`` = ``side::right``.
+
+.. 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::mkl::invalid_argument<onemkl_exception_invalid_argument>`
+       
+   
+   :ref:`oneapi::mkl::unsupported_device<onemkl_exception_unsupported_device>`
+       
+
+   :ref:`oneapi::mkl::host_bad_alloc<onemkl_exception_host_bad_alloc>`
+       
+
+   :ref:`oneapi::mkl::device_bad_alloc<onemkl_exception_device_bad_alloc>`
+       
+
+   :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
+
+        
 .. _onemkl_blas_trmm_usm:
 
 trmm (USM Version)
 ------------------
 
+**In-place API**
+----------------
+
 .. rubric:: Syntax
 
 .. code-block:: cpp
 
    namespace oneapi::mkl::blas::column_major {
        sycl::event trmm(sycl::queue &queue,
+                        onemkl::side left_right,
                         onemkl::uplo upper_lower,
                         onemkl::transpose transa,
                         onemkl::diag unit_diag,
@@ -210,6 +359,7 @@ trmm (USM Version)
 
    namespace oneapi::mkl::blas::row_major {
        sycl::event trmm(sycl::queue &queue,
+                        onemkl::side left_right,
                         onemkl::uplo upper_lower,
                         onemkl::transpose transa,
                         onemkl::diag unit_diag,
@@ -235,7 +385,7 @@ trmm (USM Version)
       multiplication (``side::left``) or on the right side
       (``side::right``). See :ref:`onemkl_datatypes` for more details.
 
-   uplo
+   upper_lower
       Specifies whether the matrix ``A`` is upper or lower
       triangular. See :ref:`onemkl_datatypes` for more details.
 
@@ -328,5 +478,136 @@ trmm (USM Version)
 
    :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
 
+**Out-of-place API**
+--------------------
+
+.. rubric:: Syntax
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::blas::column_major {
+       void trmm(sycl::queue &queue,
+                 onemkl::side left_right,
+                 onemkl::uplo upper_lower,
+                 onemkl::transpose trans,
+                 onemkl::diag unit_diag,
+                 std::int64_t m,
+                 std::int64_t n,
+                 value_or_pointer<T> alpha,
+                 const T *a,
+                 std::int64_t lda,
+                 const T *b,
+                 std::int64_t ldb,
+                 value_or_pointer<T> beta,
+                 T *c,
+                 std::int64_t ldc,
+                 const std::vector<sycl::event> &dependencies = {})
+   }
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::blas::row_major {
+       void trmm(sycl::queue &queue,
+                 onemkl::side left_right,
+                 onemkl::uplo upper_lower,
+                 onemkl::transpose trans,
+                 onemkl::diag unit_diag,
+                 std::int64_t m,
+                 std::int64_t n,
+                 value_or_pointer<T> alpha,
+                 const T *a,
+                 std::int64_t lda,
+                 const T *b,
+                 std::int64_t ldb,
+                 value_or_pointer<T> beta,
+                 T *c,
+                 std::int64_t ldc,
+                 const std::vector<sycl::event> &dependencies = {})
+   }
+
+
+.. container:: section
+
+   .. rubric:: Input Parameters
+
+   queue
+      The queue where the routine should be executed.
+
+   left_right
+      Specifies whether ``A`` is on the left side of the multiplication
+      (``side::left``) or on the right side (``side::right``). See :ref:`onemkl_datatypes` for more details.
+
+   upper_lower
+      Specifies whether the matrix ``A`` is upper or lower triangular. See :ref:`onemkl_datatypes` for more details.
+
+   trans
+      Specifies op(``A``), the transposition operation applied to matrix ``A``. See :ref:`onemkl_datatypes` for more details.
+
+   unit_diag
+      Specifies whether ``A`` is assumed to be unit triangular (all diagonal elements are 1). See :ref:`onemkl_datatypes` for more details.
+
+   m
+      Specifices the number of rows of ``B``. The value of ``m`` must be at least zero.
+
+   n
+      Specifies the Number of columns of ``B``. The value of ``n`` must be at least zero.
+
+   alpha
+      Scaling factor for matrix-matrix product. See :ref:`value_or_pointer` for more details.
+
+   a
+      Pointer to input matrix ``A``. Must have size at least
+      ``lda``\ \*\ ``m`` if ``left_right`` = ``side::left`` or ``lda``\ \*\ ``n`` if ``left_right`` = ``side::right``. See :ref:`matrix-storage` for more details.
+
+   lda
+      Leading dimension of ``A``. Must be at least ``m`` if ``left_right`` = ``side::left`` or at least ``n`` if ``left_right`` = ``side::right``. Must be positive.
+
+   b
+      Pointer to input matrix ``B``. Must have size at least
+      ``ldb``\ \*\ ``n`` if column major layout or at least ``ldb``\ \*\ ``m`` if row major layout is used. See :ref:`matrix-storage` for more details.
+
+   ldb
+      Leading dimension of matrix ``B``. It must be positive and at least ``m`` if column major layout or at least ``n`` if row major layout is used.
+
+   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`` if column major layout or at least ``ldc``\ \*\ ``m`` if row major layout is used. See :ref:`matrix-storage` for more details.
+
+   ldc
+      Leading dimension of matrix ``C``. Must be at least ``m`` if column major layout or at least ``n`` if row major layout is used. Must be positive.
+
+   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 ``alpha``\ \*\ op(``A``)\ \*\ ``B`` + ``beta``\ \*\ ``C`` if ``left_right`` = ``side::left`` or ``alpha``\ \*\ ``B``\ \*\ op(``A``) + ``beta``\ \*\ ``C`` if ``left_right`` = ``side::right``.
+
+.. 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::mkl::invalid_argument<onemkl_exception_invalid_argument>`
+       
+   
+   :ref:`oneapi::mkl::unsupported_device<onemkl_exception_unsupported_device>`
+       
+
+   :ref:`oneapi::mkl::host_bad_alloc<onemkl_exception_host_bad_alloc>`
+       
+
+   :ref:`oneapi::mkl::device_bad_alloc<onemkl_exception_device_bad_alloc>`
+       
+
+   :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
 
    **Parent topic:** :ref:`blas-level-3-routines`