[LAPACK][DOCS] Add LAPACK documentation (#135)

Author: ericlars

docs/create_new_backend.rst

@@ -3,7 +3,7 @@
 
 .. _create_backend_wrappers:
 
-Integrating a Third-party Library to oneAPI Math Kernel Library (oneMKL) Interfaces
+Integrating a Third-Party Library to oneAPI Math Kernel Library (oneMKL) Interfaces
 ====================================================================================
 
 This step-by-step tutorial provides examples for enabling new third-party libraries in oneMKL.

docs/domains/dense_linear_algebra.rst

@@ -5,13 +5,15 @@ Dense Linear Algebra
 
 This section contains information about dense linear algebra routines:
 
-:ref:`matrix-storage` provides information about dense matrix and vector storage formats that are used by oneMKL :ref:`onemkl_blas`.
+:ref:`matrix-storage` provides information about dense matrix and vector storage formats that are used by oneMKL :ref:`onemkl_blas` and :ref:`onemkl_lapack`.
 
 :ref:`onemkl_blas` provides vector, matrix-vector, and matrix-matrix routines for dense matrices and vector operations.
 
+:ref:`onemkl_lapack` provides more complex dense linear algebra routines, e.g., matrix factorization, solving dense systems of linear equations, least square problems, eigenvalue and singular value problems, and performing a number of related computational tasks.
 
 .. toctree::
     :hidden:
 
     matrix-storage.rst
     blas/blas.rst
+    lapack/lapack.rst

docs/domains/lapack/gebrd.rst

@@ -0,0 +1,230 @@
+.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemkl_lapack_gebrd:
+
+gebrd
+=====
+
+Reduces a general matrix to bidiagonal form.
+
+.. container:: section
+
+    .. rubric:: Description
+
+``gebrd`` supports the following precisions.
+
+     .. list-table:: 
+        :header-rows: 1
+
+        * -  T 
+        * -  ``float`` 
+        * -  ``double`` 
+        * -  ``std::complex<float>`` 
+        * -  ``std::complex<double>`` 
+
+The routine reduces a general :math:`m \times n` matrix :math:`A` to a 
+bidiagonal matrix :math:`B` by an orthogonal (unitary) transformation.
+
+
+If :math:`m \ge n`, the reduction is given by :math:`A=QBP^H=\begin{pmatrix}B_1\\0\end{pmatrix}P^H=Q_1B_1P_H`
+
+where :math:`B_{1}` is an :math:`n \times n` upper diagonal matrix,
+:math:`Q` and :math:`P` are orthogonal or, for a complex :math:`A`, unitary
+matrices; :math:`Q_{1}` consists of the first :math:`n` columns of
+:math:`Q`.
+
+If :math:`m < n`, the reduction is given by
+
+:math:`A = QBP^H = Q\begin{pmatrix}B_1\\0\end{pmatrix}P^H = Q_1B_1P_1^H`,
+
+where :math:`B_{1}` is an :math:`m \times m` lower diagonal matrix,
+:math:`Q` and :math:`P` are orthogonal or, for a complex :math:`A`, unitary
+matrices; :math:`P_{1}` consists of the first :math:`m` columns of
+:math:`P`.
+
+The routine does not form the matrices :math:`Q` and :math:`P` explicitly,
+but represents them as products of elementary reflectors. Routines
+are provided to work with the matrices :math:`Q` and :math:`P` in this
+representation:
+
+If the matrix :math:`A` is real,
+
+-  to compute :math:`Q` and :math:`P` explicitly, call
+   :ref:`onemkl_lapack_orgbr`.
+
+If the matrix :math:`A` is complex,
+
+-  to compute :math:`Q` and :math:`P` explicitly, call
+   :ref:`onemkl_lapack_ungbr`
+
+gebrd (Buffer Version)
+----------------------
+
+.. container:: section
+
+  .. rubric:: Syntax
+
+.. code-block:: cpp
+
+    namespace oneapi::mkl::lapack {
+      void gebrd(cl::sycl::queue &queue, std::int64_t m, std::int64_t n, cl::sycl::buffer<T,1> &a, std::int64_t lda, cl::sycl::buffer<realT,1> &d, cl::sycl::buffer<realT,1> &e, cl::sycl::buffer<T,1> &tauq, cl::sycl::buffer<T,1> &taup, cl::sycl::buffer<T,1> &scratchpad, std::int64_t scratchpad_size)
+    }
+
+.. container:: section
+
+  .. rubric:: Input Parameters
+
+queue
+   The queue where the routine should be executed.
+
+m
+   The number of rows in the matrix :math:`A` (:math:`0 \le m`).
+
+n
+   The number of columns in the matrix :math:`A` (:math:`0 \le n`).
+
+a
+   The buffer :math:`a`, size (``lda,*``). The buffer ``a`` contains the
+   matrix :math:`A`. The second dimension of ``a`` must be at least
+   :math:`\max(1, m)`.
+
+lda
+   The leading dimension of :math:`a`.
+
+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 :ref:`onemkl_lapack_gebrd_scratchpad_size` function.
+
+.. container:: section
+
+    .. rubric:: Output Parameters
+
+a
+   If :math:`m \ge n`, the diagonal and first super-diagonal of a are
+   overwritten by the upper bidiagonal matrix :math:`B`. The elements
+   below the diagonal, with the buffer tauq, represent the orthogonal
+   matrix :math:`Q` as a product of elementary reflectors, and the
+   elements above the first superdiagonal, with the buffer ``taup``,
+   represent the orthogonal matrix :math:`P` as a product of elementary
+   reflectors.
+
+   If :math:`m<n`, the diagonal and first sub-diagonal of a are
+   overwritten by the lower bidiagonal matrix :math:`B`. The elements
+   below the first subdiagonal, with the buffer tauq, represent the
+   orthogonal matrix :math:`Q` as a product of elementary reflectors, and
+   the elements above the diagonal, with the buffer ``taup``, represent
+   the orthogonal matrix :math:`P` as a product of elementary reflectors.
+
+d
+   Buffer, size at least :math:`\max(1, \min(m,n))`. Contains the diagonal
+   elements of :math:`B`.
+
+e
+   Buffer, size at least :math:`\max(1, \min(m,n) - 1)`. Contains the
+   off-diagonal elements of :math:`B`.
+
+tauq
+   Buffer, size at least :math:`\max(1, \min(m, n))`. The scalar factors of
+   the elementary reflectors which represent the orthogonal or
+   unitary matrix :math:`Q`.
+
+taup
+   Buffer, size at least :math:`\max(1, \min(m, n))`. The scalar factors of
+   the elementary reflectors which represent the orthogonal or
+   unitary matrix :math:`P`.
+
+scratchpad
+   Buffer holding scratchpad memory to be used by routine for storing intermediate results.
+
+gebrd (USM Version)
+-------------------
+
+.. container:: section
+
+  .. rubric:: Syntax
+
+.. code-block:: cpp
+
+    namespace oneapi::mkl::lapack {
+      cl::sycl::event gebrd(cl::sycl::queue &queue, std::int64_t m, std::int64_t n, T *a, std::int64_t lda, RealT *d, RealT *e, T *tauq, T *taup, T *scratchpad, std::int64_t scratchpad_size, const cl::sycl::vector_class<cl::sycl::event> &events = {})
+    }
+
+.. container:: section
+
+    .. rubric:: Input Parameters
+
+queue
+   The queue where the routine should be executed.
+
+m
+   The number of rows in the matrix :math:`A` (:math:`0 \le m`).
+
+n
+   The number of columns in the matrix :math:`A` (:math:`0 \le n`).
+
+a
+   Pointer to matrix :math:`A`. The second dimension of ``a`` must be at least
+   :math:`\max(1, m)`.
+
+lda
+   The leading dimension of ``a``.
+
+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 :ref:`onemkl_lapack_gebrd_scratchpad_size` function.
+
+events
+   List of events to wait for before starting computation. Defaults to empty list.
+
+.. container:: section
+
+    .. rubric:: Output Parameters
+
+a
+   If :math:`m \ge n`, the diagonal and first super-diagonal of a are
+   overwritten by the upper bidiagonal matrix :math:`B`. The elements
+   below the diagonal, with the array tauq, represent the orthogonal
+   matrix :math:`Q` as a product of elementary reflectors, and the
+   elements above the first superdiagonal, with the array ``taup``,
+   represent the orthogonal matrix :math:`P` as a product of elementary
+   reflectors.
+
+   If :math:`m<n`, the diagonal and first sub-diagonal of a are
+   overwritten by the lower bidiagonal matrix :math:`B`. The elements
+   below the first subdiagonal, with the array tauq, represent the
+   orthogonal matrix :math:`Q` as a product of elementary reflectors, and
+   the elements above the diagonal, with the array ``taup``, represent
+   the orthogonal matrix :math:`P` as a product of elementary reflectors.
+
+d
+   Pointer to memory of size at least :math:`\max(1, \min(m,n))`. Contains the diagonal
+   elements of :math:`B`.
+
+e
+   Pointer to memory of size at least :math:`\max(1, \min(m,n) - 1)`. Contains the
+   off-diagonal elements of :math:`B`.
+
+tauq
+   Pointer to memory of size at least :math:`\max(1, \min(m, n))`. The scalar factors of
+   the elementary reflectors which represent the orthogonal or
+   unitary matrix :math:`Q`.
+
+taup
+   Pointer to memory of size at least :math:`\max(1, \min(m, n))`. The scalar factors of
+   the elementary reflectors which represent the orthogonal or
+   unitary matrix :math:`P`.
+
+scratchpad
+   Pointer to scratchpad memory to be used by routine for storing intermediate results.
+
+.. container:: section
+
+    .. rubric:: Return Values
+
+Output event to wait on to ensure computation is complete.
+
+**Parent topic:** :ref:`onemkl_lapack-singular-value-eigenvalue-routines`
+
+

docs/domains/lapack/gebrd_scratchpad_size.rst

@@ -0,0 +1,61 @@
+.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemkl_lapack_gebrd_scratchpad_size:
+
+gebrd_scratchpad_size
+=====================
+
+Computes size of scratchpad memory required for :ref:`onemkl_lapack_gebrd` function.
+
+.. rubric:: Description
+
+``gebrd_scratchpad_size`` supports the following precisions.
+
+    .. list-table:: 
+       :header-rows: 1
+
+       * -  T 
+       * -  ``float`` 
+       * -  ``double`` 
+       * -  ``std::complex<float>`` 
+       * -  ``std::complex<double>``
+
+Computes the number of elements of type ``T`` the scratchpad memory to be passed to :ref:`onemkl_lapack_gebrd` function should be able to hold.
+Calls to this routine must specify the template parameter explicitly.
+
+.. rubric:: Syntax
+
+.. code-block:: cpp
+
+    namespace oneapi::mkl::lapack {
+      template <typename T>
+      std::int64_t gebrd_scratchpad_size(cl::sycl::queue &queue, std::int64_t m, std::int64_t n, std::int64_t lda) 
+    }
+
+.. container:: section
+
+  .. rubric:: Input Parameters
+
+queue
+   Device queue where calculations by :ref:`onemkl_lapack_gebrd` function will be performed.
+
+m
+   The number of rows in the matrix :math:`A` (:math:`0 \le m`).
+
+n
+   The number of columns in the matrix :math:`A` (:math:`0 \le n`).
+
+lda
+   The leading dimension of ``a``.
+
+.. container:: section
+
+   .. rubric:: Return Value
+
+The number of elements of type ``T`` the scratchpad memory to be passed to :ref:`onemkl_lapack_gebrd` function should be able to hold.
+
+**Parent topic:** :ref:`onemkl_lapack-singular-value-eigenvalue-routines`
+
+