.. _getrf:

getrf
=====


Computes the LU factorization of a general m-by-n matrix. This routine
belongs to the ``oneapi::mkl::lapack`` namespace.


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

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

The routine computes the ``LU`` factorization of a general
``m``-by-``n`` matrix ``A`` as

.. code-block::

   A = P*L*U,


where ``P`` is a permutation matrix, ``L`` is lower triangular with
unit diagonal elements (lower trapezoidal if ``m > n``) and ``U`` is
upper triangular (upper trapezoidal if ``m < n``). The routine uses
partial pivoting, with row interchanges.


API
***


Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::lapack {
     void getrf(cl::sycl::queue &queue,
     std::int64_t m,
     std::int64_t n,
     cl::sycl::buffer<T> &a,
     std::int64_t lda,
     std::int64_t *ipiv,
     cl::sycl::buffer<T> &scratchpad,
     std::int64_t scratchpad_size)
   }

``getrf`` 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
----------------

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

   * -     queue
     -     Device queue where calculations will be    performed.
   * -     m
     -      The number of rows in the matrix ``A`` (``0≤m``).
   * -     n
     -      The number of columns in ``A``\ (``0≤n``).
   * -     a
     -     Buffer holding array holding input matrix ``A``. The    second dimension of a must be at least ``max(1, n)``.
   * -     lda
     -     The leading dimension of a.
   * -     scratchpad
     -     Buffer holding 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:`getrf_scratchpad_size` function.


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

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

   * -     a
     -     Overwritten by ``L`` and ``U``. The unit diagonal    elements of ``L`` are not stored.
   * -     ipiv
     -     Array, size at least ``max(1,min(m, n))``. Contains the    pivot indices; for ``1 ≤i≤min(m, n)``,row ``i`` was interchanged with   row ``ipiv(i)``.
   * -     info
     -     Buffer containing error information.      If    ``info=0``, execution is successful.      If ``info=-i``,   the ``i``-th parameter had an illegal value.      If   ``info=i``, ``uii`` is 0. The factorization has been completed, but   ``U`` is exactly singular. Division by 0 will occur if you use the   factor ``U`` for solving a system of linear equations.


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``, ``uii`` is 0. The   factorization has been completed, but ``U`` is exactly singular.   Division by 0 will occur if you use the factor ``U`` for solving a   system of linear equations.

           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.