rocsparse_v2_spmv Interface Reference

rocsparse_v2_spmv Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_v2_spmv Interface Reference

Sparse matrix vector multiplication. More...

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_v2_spmv_ (handle, descr, alpha, mat, x, beta, y, stage, buffer_size_in_bytes, buffer, error)

Detailed Description

Sparse matrix vector multiplication.

rocsparse_v2_spmv multiplies the scalar \(\alpha\) with a sparse \(m \times n\) matrix \(op(A)\) 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. \]

Note: The sparse matrix format rocsparse_format_bell is not supported.

Performing the above operation involves two stages. The first stage is rocsparse_v2_spmv_stage_analysis. This will perform an analysis of the symbolic information of \(op(A)\). The second stage is rocsparse_v2_spmv_stage_compute, which corresponds to the actual calculation. The size of the buffer required for each stage is determined by calling the routine rocsparse_v2_spmv_buffer_size. The stage rocsparse_v2_spmv_stage_analysis only needs 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.

Note: The stage rocsparse_v2_spmv_stage_analysis is mandatory. An error will be returned if that stage was not executed before the stage rocsparse_v2_spmv_stage_compute.

rocsparse_v2_spmv supports multiple 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.

CSR/CSC Algorithms
Algorithm	Deterministic	Notes
rocsparse_spmv_alg_csr_rowsplit	Yes	This 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	[Deprecated] The old name for rocsparse_spmv_alg_csr_rowsplit.
rocsparse_spmv_alg_csr_adaptive	No	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	Like the adaptive algorithm, this generally performs well across all matrix sparsity patterns. Generally not as fast as the adaptive algorithm. However, it uses a much faster preprocessing step. Good for when only a small number of sparse vector products will be performed.
rocsparse_spmv_alg_csr_nnzsplit	No	Like the adaptive algorithm, this 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. It's 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
COO Algorithms	Deterministic	Notes
rocsparse_spmv_alg_coo	Yes	Generally not as fast as the atomic algorithm but is deterministic.
rocsparse_spmv_alg_coo_atomic	No	Generally the fastest COO algorithm.

ELL Algorithms
ELL Algorithms	Deterministic	Notes
rocsparse_spmv_alg_ell	Yes

Sliced ELL Algorithms
Sliced ELL Algorithms	Deterministic	Notes
rocsparse_spmv_alg_sell	Yes

BSR Algorithms
BSR Algorithm	Deterministic	Notes
rocsparse_spmv_alg_bsr	Yes

rocsparse_v2_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_v2_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.; All the sparse matrix formats are supported except rocsparse_format_bell.; The rocsparse_v2_spmv_stage_compute stage is non-blocking and executed asynchronously with respect to the host. It can return before the actual computation has finished. The stage rocsparse_v2_spmv_stage_analysis is blocking with respect to the host.; Only the stage rocsparse_v2_spmv_stage_compute supports execution in a hipGraph context. The rocsparse_v2_spmv_stage_analysis stage does not support hipGraph.; This routine does not support batched computation.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	descr	- SpMV descriptor.
[in]	alpha	- scalar \(\alpha\).
[in]	mat	- matrix descriptor.
[in]	x	- vector descriptor.
[in]	beta	- scalar \(\beta\).
[in,out]	y	- vector descriptor.
[in]	stage	- SpMV stage of the SpMV algorithm.
[in]	buffer_size_in_bytes	- size in bytes of the buffer, which must be greater or equal to the buffer size obtained from rocsparse_v2_spmv_buffer_size.
[in]	buffer	- temporary buffer allocated by the user.
[out]	error	- error descriptor created if the returned status is not `rocsparse_status_success`. A null pointer can be passed if an error descriptor is not required.

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_handle	the library context `handle` was not initialized.
rocsparse_status_invalid_pointer	`alpha`, `mat`, `x`, `beta`, `y`, or `buffer` pointer is invalid.
rocsparse_status_invalid_value	the value of `stage` is invalid.
rocsparse_status_not_implemented	if `alg` is not supported or if the mixed precision configuration is not supported.

Example

Member Function/Subroutine Documentation