.. _onemkl_blas_gbmv:

gbmv
====

Computes a matrix-vector product with a general band matrix.

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

The ``gbmv`` routines compute a scalar-matrix-vector product and add 
the result to a scalar-vector product, with a general band matrix. 
The operation is defined as:

.. math::

      y \leftarrow alpha*op(A)*x + beta*y

where:


-  op(``A``) is one of op(``A``) = ``A``, or op(``A``) = ``A``\ :sup:`T`, or op(``A``) = ``A``\ :sup:`H`

-  ``alpha`` and ``beta`` are scalars

-  ``A`` is ``m`` x ``n`` matrix with ``kl`` sub-diagonals and ``ku`` super-diagonals

-  ``x`` and ``y`` are vectors

``gbmv`` supports the following precisions:

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

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


gbmv (Buffer Version)
*********************

Syntax
------

.. code-block:: cpp

    namespace oneapi::mkl::blas::column_major {
        void gbmv(queue &queue, 
                  oneapi::mkl::transpose trans,
                  std::int64_t m,
                  std::int64_t n,
                  std::int64_t kl,
                  std::int64_t ku,
                  T alpha,
                  sycl::buffer<T,1> &a,
                  std::int64_t lda,
                  sycl::buffer<T,1> &x,
                  std::int64_t incx,
                  T beta,
                  sycl::buffer<T,1> &y,
                  std::int64_t incy)
    }

.. code-block:: cpp

    namespace oneapi::mkl::blas::row_major {
        void gbmv(queue &queue, 
                  oneapi::mkl::transpose trans,
                  std::int64_t m,
                  std::int64_t n,
                  std::int64_t kl,
                  std::int64_t ku,
                  T alpha,
                  sycl::buffer<T,1> &a,
                  std::int64_t lda,
                  sycl::buffer<T,1> &x,
                  std::int64_t incx,
                  T beta,
                  sycl::buffer<T,1> &y,
                  std::int64_t incy)
    }

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

queue
   The queue where the routine should be executed.

trans
   Specifies op(``A``), the transposition operation applied to matrix ``A``. See :ref:`data-types` for more details.

m
   Number of rows of matrix ``A``. Must be at least zero.

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

kl
   Number of sub-diagonals of matrix ``A``. Must be at least zero.

ku
   Number of super-diagonals of matrix ``A``. Must be at least zero.

alpha
   Scaling factor for the matrix-vector product.

a
   Buffer holding input matrix ``A``. Size of the buffer must be at least ``lda`` * ``n`` if column major layout is used, or at least ``lda`` * ``m`` if row major layout is used. See :ref:`matrix-storage` for more details.

lda
   Leading dimension of matrix ``A``. Must be at least (``kl`` + ``ku`` + 1) and positive.

x
   Buffer holding input vector ``x``. The length(``len``) of vector ``x`` is ``n`` if ``A`` is not transposed, and ``m`` if ``A`` is transposed. Size of the buffer must be at least (1 + (``len`` - 1)\*abs(``incx``)). See :ref:`matrix-storage` for more details.

incx
   Stride of vector ``x``.

beta
   Scaling factor for vector ``y``.

y
   Buffer holding input/output vector ``y``. The length(``len``) of vector ``y`` is ``m``, if ``A`` is not transposed, and ``n`` if ``A`` is transposed. Size of the buffer must be at least (1 + (``len`` - 1)\*abs(``incy``)). See :ref:`matrix-storage` for more details.

incy
   Stride of vector ``y``.

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

y
   Buffer holding updated vector ``y``.


gbmv (USM Version)
******************

Syntax
------

.. code-block:: cpp

    namespace oneapi::mkl::blas::column_major {
        sycl::event gbmv(queue &queue, 
                         oneapi::mkl::transpose trans,
                         std::int64_t m,
                         std::int64_t n,
                         std::int64_t kl,
                         std::int64_t ku,
                         T alpha,
                         const T *a,
                         std::int64_t lda,
                         const T *x,
                         std::int64_t incx,
                         T beta,
                         T *y,
                         std::int64_t incy,
                         const std::vector<sycl::event> &dependencies = {})
    }

.. code-block:: cpp

    namespace oneapi::mkl::blas::row_major {
        sycl::event gbmv(queue &queue, 
                         oneapi::mkl::transpose trans,
                         std::int64_t m,
                         std::int64_t n,
                         std::int64_t kl,
                         std::int64_t ku,
                         T alpha,
                         const T *a,
                         std::int64_t lda,
                         const T *x,
                         std::int64_t incx,
                         T beta,
                         T *y,
                         std::int64_t incy,
                         const std::vector<sycl::event> &dependencies = {})
    }

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

queue
   The queue where the routine should be executed.

trans
   Specifies op(``A``), the transposition operation applied to matrix ``A``. See :ref:`data-types` for more details.

m
   Number of rows of matrix ``A``. Must be at least zero.

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

kl
   Number of sub-diagonals of matrix ``A``. Must be at least zero.

ku
   Number of super-diagonals of matrix ``A``. Must be at least zero.

alpha
   Scaling factor for the matrix-vector product.

a
   Pointer to input matrix ``A``. Size of the array must be at least ``lda`` * ``n`` if column major layout is used, or at least ``lda`` * ``m`` if row major layout is used. See :ref:`matrix-storage` for more details.

lda
   Leading dimension of matrix ``A``. Must be at least (``kl`` + ``ku`` + 1) and positive.

x
   Pointer to input vector ``x``. The length ``len`` of vector ``x`` is ``n`` if ``A`` is not transposed, and ``m`` if ``A`` is transposed. Size of the array holding input vector ``x`` must be at least (1 + (``len`` - 1)*abs(``incx``)). See :ref:`matrix-storage` for more details.

incx
   Stride of vector ``x``.

beta
   Scaling factor for vector ``y``.

y
   Pointer to input/output vector ``y``. The length ``len`` of vector ``y`` is ``m``, if ``A`` is not transposed, and ``n`` if ``A`` is transposed. Size of the array holding input/output vector ``y`` must be at least (1 + (``len`` - 1)*abs(``incy``)) where ``len`` is this length. See :ref:`matrix-storage` for more details.

incy
   Stride of vector ``y``.

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

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

y
   Pointer to updated vector ``y``.

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

Output event to wait on to ensure computation is complete.