Update documentation

_sources/building_the_project_with_dpcpp.rst

@@ -121,6 +121,9 @@ The most important supported build options are:
    * - ENABLE_ROCRAND_BACKEND
      - True, False
      - False     
+   * - ENABLE_ROCSPARSE_BACKEND
+     - True, False
+     - False     
    * - ENABLE_MKLCPU_THREAD_TBB
      - True, False
      - True      
@@ -197,14 +200,14 @@ Building for ROCm
 ^^^^^^^^^^^^^^^^^
 
 The ROCm backends can be enabled with ``ENABLE_ROCBLAS_BACKEND``,
-``ENABLE_ROCFFT_BACKEND``, ``ENABLE_ROCSOLVER_BACKEND`` and
-``ENABLE_ROCRAND_BACKEND``.
+``ENABLE_ROCFFT_BACKEND``, ``ENABLE_ROCSOLVER_BACKEND``,
+``ENABLE_ROCRAND_BACKEND``, and ``ENABLE_ROCSPARSE_BACKEND``.
 
-For *RocBLAS*, *RocSOLVER* and *RocRAND*, the target device architecture must be
-set. This can be set with using the ``HIP_TARGETS`` parameter. For example, to
-enable a build for MI200 series GPUs, ``-DHIP_TARGETS=gfx90a`` should be set.
-Currently, DPC++ can only build for a single HIP target at a time. This may
-change in future versions.
+For *RocBLAS*, *RocSOLVER*, *RocRAND*, and *RocSPARSE*, the target device
+architecture must be set. This can be set with using the ``HIP_TARGETS``
+parameter. For example, to enable a build for MI200 series GPUs,
+``-DHIP_TARGETS=gfx90a`` should be set. Currently, DPC++ can only build for a
+single HIP target at a time. This may change in future versions.
 
 A few often-used architectures are listed below:
 
@@ -393,7 +396,8 @@ disabled:
       -DENABLE_MKLGPU_BACKEND=False \
       -DENABLE_ROCFFT_BACKEND=True  \
       -DENABLE_ROCBLAS_BACKEND=True \
-      -DENABLE_ROCSOLVER_BACKEND=True \
+      -DENABLE_ROCSOLVER_BACKEND=True \ 
+      -DENABLE_ROCSPARSE_BACKEND=True \ 
       -DHIP_TARGETS=gfx90a \
       -DBUILD_FUNCTIONAL_TESTS=False
 

_sources/domains/sparse_linear_algebra.rst

@@ -68,6 +68,31 @@ Currently known limitations:
   ``cusparseSpMV_preprocess``. Feel free to create an issue if this is needed.
 
 
+rocSPARSE backend
+----------------
+
+Currently known limitations:
+
+- Using ``spmv`` with a ``type_view`` other than ``matrix_descr::general`` will
+  throw a ``oneapi::math::unimplemented`` exception.
+- The COO format requires the indices to be sorted by row then by column. See
+  the `rocSPARSE COO documentation
+  <https://rocm.docs.amd.com/projects/rocSPARSE/en/latest/how-to/basics.html#coo-storage-format>`_.
+  Sparse operations using matrices with the COO format without the property
+  ``matrix_property::sorted`` will throw a ``oneapi::math::unimplemented``
+  exception.
+- The CSR format requires the column indices to be sorted within each row. See
+  the `rocSPARSE CSR documentation
+  <https://rocm.docs.amd.com/projects/rocSPARSE/en/latest/how-to/basics.html#csr-storage-format>`_.
+  Sparse operations using matrices with the CSR format without the property
+  ``matrix_property::sorted`` will throw a ``oneapi::math::unimplemented``
+  exception.
+- The same sparse matrix handle cannot be reused for multiple operations
+  ``spmm``, ``spmv``, or ``spsv``. Doing so will throw a
+  ``oneapi::math::unimplemented`` exception. See `#332
+  <https://github.com/ROCm/rocSPARSE/issues/332>`_.
+
+
 Operation algorithms mapping
 ----------------------------
 
@@ -89,33 +114,43 @@ spmm
    * - ``spmm_alg`` value
      - MKLCPU/MKLGPU
      - cuSPARSE
+     - rocSPARSE
    * - ``default_alg``
      - none
      - ``CUSPARSE_SPMM_ALG_DEFAULT``
+     - ``rocsparse_spmm_alg_default``
    * - ``no_optimize_alg``
      - none
      - ``CUSPARSE_SPMM_ALG_DEFAULT``
+     - ``rocsparse_spmm_alg_default``
    * - ``coo_alg1``
      - none
      - ``CUSPARSE_SPMM_COO_ALG1``
+     - ``rocsparse_spmm_alg_coo_segmented``
    * - ``coo_alg2``
      - none
      - ``CUSPARSE_SPMM_COO_ALG2``
+     - ``rocsparse_spmm_alg_coo_atomic``
    * - ``coo_alg3``
      - none
      - ``CUSPARSE_SPMM_COO_ALG3``
+     - ``rocsparse_spmm_alg_coo_segmented_atomic``
    * - ``coo_alg4``
      - none
      - ``CUSPARSE_SPMM_COO_ALG4``
+     - ``rocsparse_spmm_alg_default``
    * - ``csr_alg1``
      - none
      - ``CUSPARSE_SPMM_CSR_ALG1``
+     - ``rocsparse_spmm_alg_csr``
    * - ``csr_alg2``
      - none
      - ``CUSPARSE_SPMM_CSR_ALG2``
+     - ``rocsparse_spmm_alg_csr_row_split``
    * - ``csr_alg3``
      - none
      - ``CUSPARSE_SPMM_CSR_ALG3``
+     - ``rocsparse_spmm_alg_csr_merge``
 
 
 spmv
@@ -128,27 +163,35 @@ spmv
    * - ``spmv_alg`` value
      - MKLCPU/MKLGPU
      - cuSPARSE
+     - rocSPARSE
    * - ``default_alg``
      - none
      - ``CUSPARSE_SPMV_ALG_DEFAULT``
+     - ``rocsparse_spmv_alg_default``
    * - ``no_optimize_alg``
      - none
      - ``CUSPARSE_SPMV_ALG_DEFAULT``
+     - ``rocsparse_spmv_alg_default``
    * - ``coo_alg1``
      - none
      - ``CUSPARSE_SPMV_COO_ALG1``
+     - ``rocsparse_spmv_alg_coo``
    * - ``coo_alg2``
      - none
      - ``CUSPARSE_SPMV_COO_ALG2``
+     - ``rocsparse_spmv_alg_coo_atomic``
    * - ``csr_alg1``
      - none
      - ``CUSPARSE_SPMV_CSR_ALG1``
+     - ``rocsparse_spmv_alg_csr_adaptive``
    * - ``csr_alg2``
      - none
      - ``CUSPARSE_SPMV_CSR_ALG2``
+     - ``rocsparse_spmv_alg_csr_stream``
    * - ``csr_alg3``
      - none
      - ``CUSPARSE_SPMV_ALG_DEFAULT``
+     - ``rocsparse_spmv_alg_csr_lrb``
 
 
 spsv
@@ -161,9 +204,12 @@ spsv
    * - ``spsv_alg`` value
      - MKLCPU/MKLGPU
      - cuSPARSE
+     - rocSPARSE
    * - ``default_alg``
      - none
      - ``CUSPARSE_SPSV_ALG_DEFAULT``
+     - ``rocsparse_spsv_alg_default``
    * - ``no_optimize_alg``
      - none
      - ``CUSPARSE_SPSV_ALG_DEFAULT``
+     - ``rocsparse_spsv_alg_default``

building_the_project_with_dpcpp.html

@@ -510,27 +510,31 @@ <h2> Contents </h2>
 <td><p>True, False</p></td>
 <td><p>False</p></td>
 </tr>
-<tr class="row-even"><td><p>ENABLE_MKLCPU_THREAD_TBB</p></td>
+<tr class="row-even"><td><p>ENABLE_ROCSPARSE_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>
 <td><p>True, False</p></td>
 <td><p>True</p></td>
 </tr>
-<tr class="row-odd"><td><p>ENABLE_PORTBLAS_BACKEND</p></td>
+<tr class="row-even"><td><p>ENABLE_PORTBLAS_BACKEND</p></td>
 <td><p>True, False</p></td>
 <td><p>False</p></td>
 </tr>
-<tr class="row-even"><td><p>ENABLE_PORTFFT_BACKEND</p></td>
+<tr class="row-odd"><td><p>ENABLE_PORTFFT_BACKEND</p></td>
 <td><p>True, False</p></td>
 <td><p>False</p></td>
 </tr>
-<tr class="row-odd"><td><p>BUILD_FUNCTIONAL_TESTS</p></td>
+<tr class="row-even"><td><p>BUILD_FUNCTIONAL_TESTS</p></td>
 <td><p>True, False</p></td>
 <td><p>True</p></td>
 </tr>
-<tr class="row-even"><td><p>BUILD_EXAMPLES</p></td>
+<tr class="row-odd"><td><p>BUILD_EXAMPLES</p></td>
 <td><p>True, False</p></td>
 <td><p>True</p></td>
 </tr>
-<tr class="row-odd"><td><p>TARGET_DOMAINS (list)</p></td>
+<tr class="row-even"><td><p>TARGET_DOMAINS (list)</p></td>
 <td><p>blas, lapack, rng, dft, sparse_blas</p></td>
 <td><p>All domains</p></td>
 </tr>
@@ -576,13 +580,13 @@ <h2>Backends<a class="headerlink" href="#backends" title="Link to this heading">
 <section id="building-for-rocm">
 <span id="build-for-rocm-dpcpp"></span><h3>Building for ROCm<a class="headerlink" href="#building-for-rocm" title="Link to this heading">#</a></h3>
 <p>The ROCm backends can be enabled with <code class="docutils literal notranslate"><span class="pre">ENABLE_ROCBLAS_BACKEND</span></code>,
-<code class="docutils literal notranslate"><span class="pre">ENABLE_ROCFFT_BACKEND</span></code>, <code class="docutils literal notranslate"><span class="pre">ENABLE_ROCSOLVER_BACKEND</span></code> and
-<code class="docutils literal notranslate"><span class="pre">ENABLE_ROCRAND_BACKEND</span></code>.</p>
-<p>For <em>RocBLAS</em>, <em>RocSOLVER</em> and <em>RocRAND</em>, the target device architecture must be
-set. This can be set with using the <code class="docutils literal notranslate"><span class="pre">HIP_TARGETS</span></code> parameter. For example, to
-enable a build for MI200 series GPUs, <code class="docutils literal notranslate"><span class="pre">-DHIP_TARGETS=gfx90a</span></code> should be set.
-Currently, DPC++ can only build for a single HIP target at a time. This may
-change in future versions.</p>
+<code class="docutils literal notranslate"><span class="pre">ENABLE_ROCFFT_BACKEND</span></code>, <code class="docutils literal notranslate"><span class="pre">ENABLE_ROCSOLVER_BACKEND</span></code>,
+<code class="docutils literal notranslate"><span class="pre">ENABLE_ROCRAND_BACKEND</span></code>, and <code class="docutils literal notranslate"><span class="pre">ENABLE_ROCSPARSE_BACKEND</span></code>.</p>
+<p>For <em>RocBLAS</em>, <em>RocSOLVER</em>, <em>RocRAND</em>, and <em>RocSPARSE</em>, the target device
+architecture must be set. This can be set with using the <code class="docutils literal notranslate"><span class="pre">HIP_TARGETS</span></code>
+parameter. For example, to enable a build for MI200 series GPUs,
+<code class="docutils literal notranslate"><span class="pre">-DHIP_TARGETS=gfx90a</span></code> should be set. Currently, DPC++ can only build for a
+single HIP target at a time. This may change in future versions.</p>
 <p>A few often-used architectures are listed below:</p>
 <table class="table">
 <thead>
@@ -753,6 +757,7 @@ <h2>Backends<a class="headerlink" href="#backends" title="Link to this heading">
 <span class="w">    </span>-DENABLE_ROCFFT_BACKEND<span class="o">=</span>True<span class="w">  </span><span class="se">\</span>
 <span class="w">    </span>-DENABLE_ROCBLAS_BACKEND<span class="o">=</span>True<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>-DENABLE_ROCSOLVER_BACKEND<span class="o">=</span>True<span class="w"> </span><span class="se">\</span>
+<span class="w">    </span>-DENABLE_ROCSPARSE_BACKEND<span class="o">=</span>True<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>-DHIP_TARGETS<span class="o">=</span>gfx90a<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>-DBUILD_FUNCTIONAL_TESTS<span class="o">=</span>False
 </pre></div>