.. _getrs_batch-group-version:

getrs_batch (Group Version)
===========================


Solves a batch of systems of linear equations with a batch of
LU-factored square coefficient matrices, with multiple right-hand sides.
This routine belongs to the ``oneapi::mkl::lapack`` namespace.


.. contents::
    :local:
    :depth: 1

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

The routine solves for ``X``\ :sub:`i` (``iϵ{1...batch_size}``) the
following systems of linear equations:


- ``A``\ :sub:`i` \* ``X``\ :sub:`i` = ``B``\ :sub:`i` If ``trans = mkl::transpose::notrans``


- ``A``\ :sub:`i`\ :sup:`T` \* ``X``\ :sub:`i` = ``B``\ :sub:`i` If ``trans = mkl::transpose::trans``


- ``A``\ :sub:`i`\ :sup:`H` \* ``X``\ :sub:`i` = ``B``\ :sub:`i` If ``trans = mkl::transpose::conjtrans``


Before calling this routine you must call :ref:`getrf_batch-group-version` to
compute the LU factorization of ``A``\ :sub:`1`.


The total number of problems to solve, ``batch_size``, is a sum of sizes
of all of the groups of parameters as provided by``group_sizes`` array.



API
***


Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::lapack {
     cl::sycl::event getrs_batch(cl::sycl::queue &queue,
     mkl::transpose *trans,
     std::int64_t *n,
     std::int64_t *nrhs,
     T **a,
     std::int64_t *lda,
     std::int64_t **ipiv,
     T **b,
     std::int64_t *ldb,
     std::int64_t group_count,
     std::int64_t *group_sizes,
     T *scratchpad,
     std::int64_t scratchpad_size,
     const std::vector<cl::sycl::event> &events = {})
   }

Function supports the following precisions and devices.


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

   * -  T
     -  Devices supported
   * -  ``float``
     -  Host, CPU, and GPU
   * -  ``double``
     -  Host, CPU, and GPU
   * -  ``std::complex<float>``
     -  Host, CPU, and GPU
   * -  ``std::complex<double>``
     -  Host, CPU, and GPU


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

queue
   Device queue where calculations will be performed.


trans
   Array of ``group_count`` parameters trans\ :sub:`g` indicating the
   form of the equations for the group ``g``:


   If trans = mkl::transpose::nontrans, then
   ``A``\ :sub:`i`\ \*\ ``X``\ :sub:`i` = ``B``\ :sub:`i` is solved
   for ``X``\ :sub:`i`.


   If trans = mkl::transpose::trans, then
   ``A``\ :sub:`i`\ :sup:`T`\ \*\ ``X``\ :sub:`i` = ``B``\ :sub:`i`
   is solved for ``X``\ :sub:`i`.


   If trans = mkl::transpose::conjtrans, then
   ``A``\ :sub:`i`\ :sup:`H`\ \*\ ``X``\ :sub:`i` = ``B``\ :sub:`i`
   is solved for ``X``\ :sub:`i`.


n
   Array of ``group_count`` parameters ``n``\ :sub:`g` specifying the
   order of the matrices ``A``\ :sub:`i` and the number of rows in
   matrices ``B``\ :sub:`i` (0 ≤ ``n``\ :sub:`g`) belonging to group
   ``g``.


nrhs
   Array of ``group_count`` parameters nrhs\ :sub:`g` specifying the
   number of right hand sides\ ``(0≤nrhs)``\ for group ``g``.


a
   Array of ``batch_size`` pointers to factorization of the
   matrices\ ``A``\ :sub:`i`, as returned by :ref:`getrf_batch-group-version`.


lda
   Array of ``group_count`` parameters lda\ :sub:`g` specifying the
   leading dimension of ``A``\ :sub:`i` from group ``g``.


ipiv
   The ipiv array, as returned by :ref:`getrf_batch-group-version`.


b
   The array containing @ ``batch_size`` pointers to the matrices
   ``B``\ :sub:`i` whose columns are the right-hand sides for the
   systems of equations.


ldb
   Array of ``group_count`` parameters ldb\ :sub:`g` specifying the
   leading dimensions of ``B``\ :sub:`i` in the group ``g``.


group_count
   Specifies the number of groups of parameters. Must be at least 0.


group_sizes
   Array of group_count integers. Array element with index ``g``
   specifies the number of problems to solve for each of the groups
   of parameters ``g``. So the total number of problems to solve,
   ``batch_size``, is a sum of all parameter group sizes.


scratchpad
   Scratchpad memory to be used by routine for storing intermediate
   results.


scratchpad_size
   Size of scratchpad memory as a number of floating point elements
   of type T. Size should not be less then the value returned by
   :ref:`getrs_batch_scratchpad_size-group-version`.


events
   List of events to wait for before starting computation. Defaults
   to empty list.


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

b
   Overwritten by the solution matrices ``X``\ :sub:`i`.


Exceptions
----------

.. tabularcolumns:: |\Y{0.3}|\Y{0.7}|

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

   * - Exception
     - Description

   * -     ``mkl::lapack::batch_exception``
     -     This exception is thrown when problems occur during    calculations. You can obtain the info code of the problem using the   info() method of the exception object:

           If   ``info = -n``, the ``n``-th parameter had an illegal   value.

           If ``info`` equals the value passed as   scratchpad size, and detail() returns non-zero, then the passed   scratchpad is of insufficient size, and the required size should be   not less then value returned by the detail() method of the exception   object.

           If ``info`` is zero, then the diagonal   element of some of ``U``\ :sub:`i` is zero, and the solve could not   be completed. The indexes of such matrices in the batch can be   obtained with the ids() method of the exception object. You can   obtain the indexes of the first zero diagonal elements in these   ``U``\ :sub:`i` matrices using the infos() method of the exception   object.



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

Output event to wait on to ensure computation is complete.