.. _potrs-usm-version:

potrs (USM Version)
===================

Solves a system of linear equations with a Cholesky-factored symmetric
(Hermitian) positive-definite coefficient matrix. This routine belongs
to the ``oneapi::mkl::lapack`` namespace.


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

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

The routine solves for ``X`` the system of linear equations
``A``\ \*\ ``X`` = ``B`` with a symmetric positive-definite or, for
complex data, Hermitian positive-definite matrix A, given the
Cholesky factorization of ``A``:


.. list-table::
   :header-rows: 0

   * -  ``A`` = ``U``\ :sup:`T`\ \*\ ``U`` for real data, ``A`` =    ``U``\ :sup:`H`\ \*\ ``U`` for complex data
     -  if uplo=\ ``mkl::uplo::upper``
   * -  ``A`` = ``L``\ \*\ ``L``\ :sup:`T` for real data, ``A`` =    ``L``\ \*\ ``L``\ :sup:`H` for complex data
     -  if uplo=\ ``mkl::uplo::lower``




where ``L`` is a lower triangular matrix and ``U`` is upper
triangular. The system is solved with multiple right-hand sides
stored in the columns of the matrix ``B``.


Before calling this routine, you must call :ref:`potrf-usm-version` to
compute the Cholesky factorization of A.


API
***


Syntax
------

.. code-block:: cpp

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

``potrs`` (USM version) 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.


uplo
   Indicates how the input matrix has been factored:


   If uplo=\ ``mkl::uplo::upper``, the upper triangle ``U`` of ``A``
   is stored, where ``A`` = ``U``\ :sup:`T`\ \*\ ``U`` for real data,
   ``A`` = ``U``\ :sup:`H`\ \*\ ``U`` for complex data.


   If uplo=\ ``mkl::uplo::lower``, the upper triangle ``L`` of ``A``
   is stored, where ``A`` = ``L``\ \*\ ``L``\ :sup:`T` for real data,
   ``A`` = ``L``\ \*\ ``L``\ :sup:`H` for complex data.


n
   The order of matrix ``A`` (0≤n).


nrhs
   The number of right-hand sides (0≤nrhs).


a
   Pointer to factorization of the matrix ``A``, as returned by
   :ref:`potrf-usm-version`. The
   second dimension of a must be at least max(1, n).


lda
   The leading dimension of a.


b
   Pointer to the data of matrix ``B`` whose columns are the
   right-hand sides for the systems of equations. The second
   dimension of b must be at least max(1,nrhs).


ldb
   The leading dimension of b.


scratchpad
   Pointer to scratchpad memory to be used by the 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 than the value returned by
   the
   :ref:`potrs_scratchpad_size`
   function.


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


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

b
   The memory pointed to by pointer b is overwritten by the solution
   matrix ``X``.


Exceptions
----------

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

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

   * - Exception
     - Description

   * -     ``mkl::lapack::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 = -i``, the ``i``-th parameter had an illegal value.

           If ``info = i``, the ``i``-th diagonal element of the Cholesky factor is zero, and the solve could not be completed.

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


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

Output event to wait on to ensure computation is complete.