Update documentation

_sources/building_the_project_with_dpcpp.rst

@@ -104,6 +104,9 @@ The most important supported build options are:
    * - ENABLE_CURAND_BACKEND
      - True, False
      - False     
+   * - ENABLE_CUSPARSE_BACKEND
+     - True, False
+     - False     
    * - ENABLE_NETLIB_BACKEND
      - True, False
      - False     
@@ -183,8 +186,8 @@ Building for CUDA
 ^^^^^^^^^^^^^^^^^
 
 The CUDA backends can be enabled with ``ENABLE_CUBLAS_BACKEND``,
-``ENABLE_CUFFT_BACKEND``, ``ENABLE_CURAND_BACKEND``, and
-``ENABLE_CUSOLVER_BACKEND``.
+``ENABLE_CUFFT_BACKEND``, ``ENABLE_CURAND_BACKEND``,
+``ENABLE_CUSOLVER_BACKEND``, and ``ENABLE_CUSPARSE_BACKEND``.
 
 No additional parameters are required for using CUDA libraries. In most cases,
 the CUDA libraries should be found automatically by CMake.
@@ -371,6 +374,7 @@ disabled using the Ninja build system:
       -DENABLE_CUBLAS_BACKEND=True \
       -DENABLE_CUSOLVER_BACKEND=True \
       -DENABLE_CURAND_BACKEND=True \
+      -DENABLE_CUSPARSE_BACKEND=True \
       -DBUILD_FUNCTIONAL_TESTS=False
 
 ``$ONEMKL_DIR`` points at the oneMKL source directly. The x86 CPU (``MKLCPU``)

_sources/domains/sparse_linear_algebra.rst

@@ -20,21 +20,150 @@ Currently known limitations:
 - ``oneapi::mkl::sparse::set_csr_data`` and
   ``oneapi::mkl::sparse::set_coo_data`` functions cannot be used on a handle
   that has already been used for an operation or its optimize function. Doing so
-  will throw an ``oneapi::mkl::unimplemented`` exception.
+  will throw a ``oneapi::mkl::unimplemented`` exception.
 - Using ``spsv`` with the ``oneapi::mkl::sparse::spsv_alg::no_optimize_alg`` and
   a sparse matrix that does not have the
-  ``oneapi::mkl::sparse::matrix_property::sorted`` property will throw an
+  ``oneapi::mkl::sparse::matrix_property::sorted`` property will throw a
   ``oneapi::mkl::unimplemented`` exception.
 - Using ``spmm`` on Intel GPU with a sparse matrix that is
   ``oneapi::mkl::transpose::conjtrans`` and has the
-  ``oneapi::mkl::sparse::matrix_property::symmetric`` property will throw an
+  ``oneapi::mkl::sparse::matrix_property::symmetric`` property will throw a
   ``oneapi::mkl::unimplemented`` exception.
 - Using ``spmv`` with a sparse matrix that is
   ``oneapi::mkl::transpose::conjtrans`` with a ``type_view``
-  ``matrix_descr::symmetric`` or ``matrix_descr::hermitian`` will throw an
+  ``matrix_descr::symmetric`` or ``matrix_descr::hermitian`` will throw a
   ``oneapi::mkl::unimplemented`` exception.
 - Using ``spsv`` on Intel GPU with a sparse matrix that is
-  ``oneapi::mkl::transpose::conjtrans`` and will throw an
+  ``oneapi::mkl::transpose::conjtrans`` and will throw a
   ``oneapi::mkl::unimplemented`` exception.
 - Scalar parameters ``alpha`` and ``beta`` should be host pointers to prevent
   synchronizations and copies to the host.
+
+
+cuSPARSE backend
+----------------
+
+Currently known limitations:
+
+- The COO format requires the indices to be sorted by row. See the `cuSPARSE
+  documentation
+  <https://docs.nvidia.com/cuda/cusparse/index.html#coordinate-coo>`_. Sparse
+  operations using matrices with the COO format without the property
+  ``matrix_property::sorted_by_rows`` or ``matrix_property::sorted`` will throw
+  a ``oneapi::mkl::unimplemented`` exception.
+- Using ``spmm`` with the algorithm ``spmm_alg::csr_alg3`` and an ``opA`` other
+  than ``transpose::nontrans`` or an ``opB`` ``transpose::conjtrans`` will throw
+  a ``oneapi::mkl::unimplemented`` exception.
+- Using ``spmm`` with the algorithm ``spmm_alg::csr_alg3``,
+  ``opB=transpose::trans`` and real fp64 precision will throw a
+  ``oneapi::mkl::unimplemented`` exception. This configuration can fail as of
+  CUDA 12.6.2, see the related issue
+  `here<https://forums.developer.nvidia.com/t/cusparse-spmm-sample-failing-with-misaligned-address/311022>`_.
+- Using ``spmv`` with a ``type_view`` other than ``matrix_descr::general`` will
+  throw a ``oneapi::mkl::unimplemented`` exception.
+- Using ``spsv`` with the algorithm ``spsv_alg::no_optimize_alg`` may still
+  perform some mandatory preprocessing.
+- oneMKL Interface does not provide a way to use non-default algorithms without
+  calling preprocess functions such as ``cusparseSpMM_preprocess`` or
+  ``cusparseSpMV_preprocess``. Feel free to create an issue if this is needed.
+
+
+Operation algorithms mapping
+----------------------------
+
+The following tables describe how a oneMKL SYCL Interface algorithm maps to the
+backend's algorithms. Refer to the backend's documentation for a more detailed
+explanation of the algorithms.
+
+Backends with no equivalent algorithms will fallback to the backend's default
+behavior.
+
+
+spmm
+^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 30 45
+
+   * - ``spmm_alg`` value
+     - MKLCPU/MKLGPU
+     - cuSPARSE
+   * - ``default_alg``
+     - none
+     - ``CUSPARSE_SPMM_ALG_DEFAULT``
+   * - ``no_optimize_alg``
+     - none
+     - ``CUSPARSE_SPMM_ALG_DEFAULT``
+   * - ``coo_alg1``
+     - none
+     - ``CUSPARSE_SPMM_COO_ALG1``
+   * - ``coo_alg2``
+     - none
+     - ``CUSPARSE_SPMM_COO_ALG2``
+   * - ``coo_alg3``
+     - none
+     - ``CUSPARSE_SPMM_COO_ALG3``
+   * - ``coo_alg4``
+     - none
+     - ``CUSPARSE_SPMM_COO_ALG4``
+   * - ``csr_alg1``
+     - none
+     - ``CUSPARSE_SPMM_CSR_ALG1``
+   * - ``csr_alg2``
+     - none
+     - ``CUSPARSE_SPMM_CSR_ALG2``
+   * - ``csr_alg3``
+     - none
+     - ``CUSPARSE_SPMM_CSR_ALG3``
+
+
+spmv
+^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 30 45
+
+   * - ``spmv_alg`` value
+     - MKLCPU/MKLGPU
+     - cuSPARSE
+   * - ``default_alg``
+     - none
+     - ``CUSPARSE_SPMV_ALG_DEFAULT``
+   * - ``no_optimize_alg``
+     - none
+     - ``CUSPARSE_SPMV_ALG_DEFAULT``
+   * - ``coo_alg1``
+     - none
+     - ``CUSPARSE_SPMV_COO_ALG1``
+   * - ``coo_alg2``
+     - none
+     - ``CUSPARSE_SPMV_COO_ALG2``
+   * - ``csr_alg1``
+     - none
+     - ``CUSPARSE_SPMV_CSR_ALG1``
+   * - ``csr_alg2``
+     - none
+     - ``CUSPARSE_SPMV_CSR_ALG2``
+   * - ``csr_alg3``
+     - none
+     - ``CUSPARSE_SPMV_ALG_DEFAULT``
+
+
+spsv
+^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 30 45
+
+   * - ``spsv_alg`` value
+     - MKLCPU/MKLGPU
+     - cuSPARSE
+   * - ``default_alg``
+     - none
+     - ``CUSPARSE_SPSV_ALG_DEFAULT``
+   * - ``no_optimize_alg``
+     - none
+     - ``CUSPARSE_SPSV_ALG_DEFAULT``

building_the_project_with_dpcpp.html

@@ -648,47 +648,51 @@ <h2> Contents </h2>
 <td><p>True, False</p></td>
 <td><p>False</p></td>
 </tr>
-<tr class="row-even"><td><p>ENABLE_NETLIB_BACKEND</p></td>
+<tr class="row-even"><td><p>ENABLE_CUSPARSE_BACKEND</p></td>
 <td><p>True, False</p></td>
 <td><p>False</p></td>
 </tr>
-<tr class="row-odd"><td><p>ENABLE_ROCBLAS_BACKEND</p></td>
+<tr class="row-odd"><td><p>ENABLE_NETLIB_BACKEND</p></td>
 <td><p>True, False</p></td>
 <td><p>False</p></td>
 </tr>
-<tr class="row-even"><td><p>ENABLE_ROCFFT_BACKEND</p></td>
+<tr class="row-even"><td><p>ENABLE_ROCBLAS_BACKEND</p></td>
 <td><p>True, False</p></td>
 <td><p>False</p></td>
 </tr>
-<tr class="row-odd"><td><p>ENABLE_ROCSOLVER_BACKEND</p></td>
+<tr class="row-odd"><td><p>ENABLE_ROCFFT_BACKEND</p></td>
 <td><p>True, False</p></td>
 <td><p>False</p></td>
 </tr>
-<tr class="row-even"><td><p>ENABLE_ROCRAND_BACKEND</p></td>
+<tr class="row-even"><td><p>ENABLE_ROCSOLVER_BACKEND</p></td>
 <td><p>True, False</p></td>
 <td><p>False</p></td>
 </tr>
-<tr class="row-odd"><td><p>ENABLE_MKLCPU_THREAD_TBB</p></td>
+<tr class="row-odd"><td><p>ENABLE_ROCRAND_BACKEND</p></td>
+<td><p>True, False</p></td>
+<td><p>False</p></td>
+</tr>
+<tr class="row-even"><td><p>ENABLE_MKLCPU_THREAD_TBB</p></td>
 <td><p>True, False</p></td>
 <td><p>True</p></td>
 </tr>
-<tr class="row-even"><td><p>ENABLE_PORTBLAS_BACKEND</p></td>
+<tr class="row-odd"><td><p>ENABLE_PORTBLAS_BACKEND</p></td>
 <td><p>True, False</p></td>
 <td><p>False</p></td>
 </tr>
-<tr class="row-odd"><td><p>ENABLE_PORTFFT_BACKEND</p></td>
+<tr class="row-even"><td><p>ENABLE_PORTFFT_BACKEND</p></td>
 <td><p>True, False</p></td>
 <td><p>False</p></td>
 </tr>
-<tr class="row-even"><td><p>BUILD_FUNCTIONAL_TESTS</p></td>
+<tr class="row-odd"><td><p>BUILD_FUNCTIONAL_TESTS</p></td>
 <td><p>True, False</p></td>
 <td><p>True</p></td>
 </tr>
-<tr class="row-odd"><td><p>BUILD_EXAMPLES</p></td>
+<tr class="row-even"><td><p>BUILD_EXAMPLES</p></td>
 <td><p>True, False</p></td>
 <td><p>True</p></td>
 </tr>
-<tr class="row-even"><td><p>TARGET_DOMAINS (list)</p></td>
+<tr class="row-odd"><td><p>TARGET_DOMAINS (list)</p></td>
 <td><p>blas, lapack, rng, dft, sparse_blas</p></td>
 <td><p>All domains</p></td>
 </tr>
@@ -726,8 +730,8 @@ <h2>Backends<a class="headerlink" href="#backends" title="Link to this heading">
 <section id="building-for-cuda">
 <span id="build-for-cuda-dpcpp"></span><h3>Building for CUDA<a class="headerlink" href="#building-for-cuda" title="Link to this heading">#</a></h3>
 <p>The CUDA backends can be enabled with <code class="docutils literal notranslate"><span class="pre">ENABLE_CUBLAS_BACKEND</span></code>,
-<code class="docutils literal notranslate"><span class="pre">ENABLE_CUFFT_BACKEND</span></code>, <code class="docutils literal notranslate"><span class="pre">ENABLE_CURAND_BACKEND</span></code>, and
-<code class="docutils literal notranslate"><span class="pre">ENABLE_CUSOLVER_BACKEND</span></code>.</p>
+<code class="docutils literal notranslate"><span class="pre">ENABLE_CUFFT_BACKEND</span></code>, <code class="docutils literal notranslate"><span class="pre">ENABLE_CURAND_BACKEND</span></code>,
+<code class="docutils literal notranslate"><span class="pre">ENABLE_CUSOLVER_BACKEND</span></code>, and <code class="docutils literal notranslate"><span class="pre">ENABLE_CUSPARSE_BACKEND</span></code>.</p>
 <p>No additional parameters are required for using CUDA libraries. In most cases,
 the CUDA libraries should be found automatically by CMake.</p>
 </section>
@@ -893,6 +897,7 @@ <h2>Backends<a class="headerlink" href="#backends" title="Link to this heading">
 <span class="w">    </span>-DENABLE_CUBLAS_BACKEND<span class="o">=</span>True<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>-DENABLE_CUSOLVER_BACKEND<span class="o">=</span>True<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>-DENABLE_CURAND_BACKEND<span class="o">=</span>True<span class="w"> </span><span class="se">\</span>
+<span class="w">    </span>-DENABLE_CUSPARSE_BACKEND<span class="o">=</span>True<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>-DBUILD_FUNCTIONAL_TESTS<span class="o">=</span>False
 </pre></div>
 </div>