rocsparse_spmv Interface Reference#
Sparse matrix vector multiplication. More...
Public Member Functions | |
| integer(kind(rocsparse_status_success)) function | rocsparse_spmv_ (handle, trans, alpha, mat, x, beta, y, compute_type, alg, stage, buffer_size, temp_buffer) |
Detailed Description
Sparse matrix vector multiplication.
rocsparse_spmv multiplies the scalar \(\alpha\) with a sparse \(m \times n\) matrix \(op(A)\), defined in CSR, CSC, COO, COO (AoS), BSR, or ELL format, with the dense vector \(x\) and adds the result to the dense vector \(y\) that is multiplied by the scalar \(\beta\), such that
\[ y := \alpha \cdot op(A) \cdot x + \beta \cdot y, \]
with
\[ op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\% A^T, & \text{if trans == rocsparse_operation_transpose} \\% A^H, & \text{if trans == rocsparse_operation_conjugate_transpose} \end{array} \right. \]
Performing the above operation involves multiple steps. First, call rocsparse_spmv with the stage parameter set to rocsparse_spmv_stage_buffer_size to determine the size of the required temporary storage buffer. Then allocate this buffer and call rocsparse_spmv with the stage parameter set to rocsparse_spmv_stage_preprocess. Depending on the algorithm and sparse matrix format, this will perform analysis on the sparsity pattern of \(op(A)\). Finally, complete the operation by calling rocsparse_spmv with the stage parmeter set to rocsparse_spmv_stage_compute. The buffer size, buffer allocation, and preprocess stages only need to be called once for a given sparse matrix \(op(A)\), while the computation stage can be repeatedly used with different \(x\) and \(y\) vectors. After all calls to rocsparse_spmv are complete, the temporary buffer can be deallocated.
rocsparse_spmv supports multiple different algorithms. These algorithms have different trade-offs depending on the sparsity pattern of the matrix, whether or not the results need to be deterministic, and how many times the sparse-vector product will be performed.
| Algorithm | Deterministic | Preprocessing | Notes |
|---|---|---|---|
| rocsparse_spmv_alg_csr_rowsplit | Yes | No | Is best suited for matrices with all rows having a similar number of non-zeros. Can outperform adaptive and LRB algorithms in certain sparsity patterns. Will perform very poorly if some rows have few non-zeros and some rows have many non-zeros. |
| rocsparse_spmv_alg_csr_stream | Yes | No | [Deprecated] The old name for rocsparse_spmv_alg_csr_rowsplit. |
| rocsparse_spmv_alg_csr_adaptive | No | Yes | Generally the fastest algorithm across all matrix sparsity patterns. This includes matrices that have some rows with many non-zeros and some rows with few non-zeros. Requires lengthy preprocessing that needs to be amortized over many subsequent sparse vector products. |
| rocsparse_spmv_alg_csr_lrb | No | Yes | Like the adaptive algorithm, it generally performs well across all matrix sparsity patterns. Generally not as fast as the adaptive algorithm, however, it uses a much faster pre-processing step. Good for when only a small number of sparse vector products will be performed. |
| rocsparse_spmv_alg_csr_nnzsplit | No | Yes | Like the adaptive algorithm, it generally performs well across all matrix sparsity patterns. Generally not as fast as the adaptive algorithm but faster than the LRB algorithm. It uses a much faster preprocessing step than LRB. Good when the number of sparse vector products that will be performed is less than one hundred. If more products need to be computed, the adaptive algorithm is probably faster. |
| COO Algorithms | Deterministic | Preprocessing | Notes |
|---|---|---|---|
| rocsparse_spmv_alg_coo | Yes | Yes | Generally not as fast as the atomic algorithm but is deterministic. |
| rocsparse_spmv_alg_coo_atomic | No | No | Generally the fastest COO algorithm. |
| ELL Algorithms | Deterministic | Preprocessing | Notes |
|---|---|---|---|
| rocsparse_spmv_alg_ell | Yes | No |
| BSR Algorithm | Deterministic | Preprocessing | Notes |
|---|---|---|---|
| rocsparse_spmv_alg_bsr | Yes | No |
rocsparse_spmv supports multiple combinations of data types and compute types. The tables below indicate the currently supported different data types that can be used for the sparse matrix \(op(A)\), the dense vectors \(x\) and \(y\), and the compute type for \(\alpha\) and \(\beta\). The advantage of using different data types is to save on memory bandwidth and storage when a user application allows, while performing the actual computation in a higher precision.
- Uniform Precisions:
-
Uniform Precisions A / X / Y / compute_type rocsparse_datatype_f32_r rocsparse_datatype_f64_r rocsparse_datatype_f32_c rocsparse_datatype_f64_c
- Mixed Precisions:
-
Mixed Precisions A / X Y compute_type rocsparse_datatype_i8_r rocsparse_datatype_i32_r rocsparse_datatype_i32_r rocsparse_datatype_i8_r rocsparse_datatype_f32_r rocsparse_datatype_f32_r rocsparse_datatype_f16_r rocsparse_datatype_f32_r rocsparse_datatype_f32_r rocsparse_datatype_f16_r rocsparse_datatype_f16_r rocsparse_datatype_f32_r rocsparse_datatype_bf16_r rocsparse_datatype_f32_r rocsparse_datatype_f32_r rocsparse_datatype_bf16_r rocsparse_datatype_bf16_r rocsparse_datatype_f32_r
- Mixed-regular Real Precisions
-
Mixed-regular Real Precisions A X / Y / compute_type rocsparse_datatype_f32_r rocsparse_datatype_f64_r rocsparse_datatype_f32_c rocsparse_datatype_f64_c
- Mixed-regular Complex Precisions
-
Mixed-regular Complex Precisions A X / Y / compute_type rocsparse_datatype_f32_r rocsparse_datatype_f32_c rocsparse_datatype_f64_r rocsparse_datatype_f64_c
rocsparse_spmv supports rocsparse_indextype_i32 and rocsparse_indextype_i64 index precisions for storing the row pointer and column indices arrays of the sparse matrices.
- Note
- None of the algorithms above are deterministic when \(A\) is transposed.
-
The sparse matrix formats currently supported are:
rocsparse_format_bsr,rocsparse_format_coo,rocsparse_format_coo_aos,rocsparse_format_csr,rocsparse_format_csc, androcsparse_format_ell. -
Only the
rocsparse_spmv_stage_buffer_sizestage and therocsparse_spmv_stage_computestage are non-blocking and executed asynchronously with respect to the host. They can return before the actual computation has finished. Therocsparse_spmv_stage_preprocessstage is blocking with respect to the host. -
Only the
rocsparse_spmv_stage_buffer_sizestage and therocsparse_spmv_stage_computestage support execution in a hipGraph context. Therocsparse_spmv_stage_preprocessstage does not support hipGraph.
- Parameters
-
[in] handle - handle to the rocSPARSE library context queue. [in] trans - matrix operation type. [in] alpha - scalar \(\alpha\). [in] mat - matrix descriptor. [in] x - vector descriptor. [in] beta - scalar \(\beta\). [in,out] y - vector descriptor. [in] compute_type - floating point precision for the SpMV computation. [in] alg - SpMV algorithm for the SpMV computation. [in] stage - SpMV stage for the SpMV computation. [out] buffer_size - number of bytes of the temporary storage buffer. buffer_size is set when temp_bufferis nullptr.[in] temp_buffer - temporary storage buffer allocated by the user. When the rocsparse_spmv_stage_buffer_sizestage is passed, the required allocation size (in bytes) is written tobuffer_sizeand function returns without performing the SpMV operation.
- Return values
-
rocsparse_status_success the operation completed successfully. rocsparse_status_invalid_handle the library context handlewas not initialized.rocsparse_status_invalid_pointer alpha,mat,x,beta,y, orbuffer_sizepointer is invalid.rocsparse_status_invalid_value the value of trans,compute_type,alg, orstageis incorrect.rocsparse_status_not_implemented compute_typeoralgis currently not supported.
- Example
Member Function/Subroutine Documentation
◆ rocsparse_spmv_()
| integer(kind(rocsparse_status_success)) function hipfort_rocsparse::rocsparse_spmv::rocsparse_spmv_ | ( | type(c_ptr), value | handle, |
| integer(kind(rocsparse_operation_none)), value | trans, | ||
| type(c_ptr), value | alpha, | ||
| type(c_ptr), value | mat, | ||
| type(c_ptr), value | x, | ||
| type(c_ptr), value | beta, | ||
| type(c_ptr), value | y, | ||
| integer(kind(rocsparse_datatype_f16_r)), value | compute_type, | ||
| integer(kind(rocsparse_spmv_alg_default)), value | alg, | ||
| integer(kind(rocsparse_spmv_stage_buffer_size)), value | stage, | ||
| integer(c_size_t) | buffer_size, | ||
| type(c_ptr), value | temp_buffer | ||
| ) |
The documentation for this interface was generated from the following file: