rocsparse_scsrmv Interface Reference

rocsparse_scsrmv Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_scsrmv Interface Reference

Sparse matrix vector multiplication using the CSR storage format. More...

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_scsrmv_ (handle, trans, m, n, nnz, alpha, descr, csr_val, csr_row_ptr, csr_col_ind, myinfo, x, beta, y)

integer(kind(rocsparse_status_success)) function	rocsparse_scsrmv_rank_0 (handle, trans, m, n, nnz, alpha, descr, csr_val, csr_row_ptr, csr_col_ind, myinfo, x, beta, y)

integer(kind(rocsparse_status_success)) function	rocsparse_scsrmv_rank_1 (handle, trans, m, n, nnz, alpha, descr, csr_val, csr_row_ptr, csr_col_ind, myinfo, x, beta, y)

Detailed Description

Sparse matrix vector multiplication using the CSR storage format.

rocsparse_csrmv multiplies the scalar \(\alpha\) with a sparse \(m \times n\) matrix, defined in CSR storage format, and 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. \]

The info parameter is optional and contains information collected by rocsparse_Xcsrmv_analysis(). If present, the information will be used to speed up the csrmv computation. If info == NULL, a general csrmv routine will be used instead. Running with analysis might result in better performance when computing the matrix vector product but will also incur a performance cost attributed to the additional analysis step. For this reason, running with analysis makes sense when computing the matrix vector product many times, therefore amortizing the analysis cost.

for(i = 0; i < m; ++i)
{
    y[i] = beta * y[i];
 
    for(j = csr_row_ptr[i]; j < csr_row_ptr[i + 1]; ++j)
    {
        y[i] = y[i] + alpha * csr_val[j] * x[csr_col_ind[j]];
    }
}

To run the above operation without analysis, call the rocsparse_csrmv routine while passing NULL for the info parameter.

With analysis, completing the sparse matrix vector multiplication involves two steps. First, create a rocsparse_mat_info object by calling rocsparse_create_mat_info and then pass this to rocsparse_Xcsrmv_analysis(), which will perform analysis on the sparsity pattern of the matrix \(op(A)\). Then complete the operation by calling rocsparse_csrmv. The creation of the info object and the call to the analysis routine only need to be performed once for a given sparsity pattern, while the computation can be performed repeatedly as long as the sparsity pattern has not changed. After all calls to rocsparse_csrmv have been made, the info object can be destroyed with a call to rocsparse_destroy_mat_info.

When running with analysis, a user might want to perform multiple sparse matrix multiplications, with each sparse matrix having a different sparsity pattern. Instead of creating and destroying multiple rocsparse_mat_info objects for each unique sparsity pattern, they can instead create the info object once and then call rocsparse_csrmv_clear and rerun the analysis in between each sparse matrix multiplication.

Note: This function is non-blocking and executed asynchronously with respect to the host. It can return before the actual computation has finished.; This routine supports execution in a hipGraph context.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	trans	- matrix operation type.
[in]	m	- number of rows of the sparse CSR matrix.
[in]	n	- number of columns of the sparse CSR matrix.
[in]	nnz	- number of non-zero entries of the sparse CSR matrix.
[in]	alpha	- scalar \(\alpha\).
[in]	descr	- descriptor of the sparse CSR matrix. Currently, only `rocsparse_matrix_type_general` is supported.
[in]	csr_val	- array of `nnz` elements of the sparse CSR matrix.
[in]	csr_row_ptr	- array of `m+1` elements that point to the start of every row of the sparse CSR matrix.
[in]	csr_col_ind	- array of `nnz` elements containing the column indices of the sparse CSR matrix.
[in]	myInfo	- information collected by rocsparse_Xcsrmv_analysis(), which can be `NULL` if no information is available.
[in]	x	- array of `n` elements ( \(op(A) == A\)) or `m` elements ( \(op(A) == A^T\) or \(op(A) == A^H\)).
[in]	beta	- scalar \(\beta\).
[in,out]	y	- array of `m` elements ( \(op(A) == A\)) or `n` elements ( \(op(A) == A^T\) or \(op(A) == A^H\)).

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_handle	the library context was not initialized.
rocsparse_status_invalid_size	`m`, `n`, or `nnz` is invalid.
rocsparse_status_invalid_pointer	`descr`, `alpha`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `x`, `beta`, or `y` pointer is invalid.
rocsparse_status_arch_mismatch	the device is not supported.
rocsparse_status_not_implemented	`rocsparse_matrix_type` != `rocsparse_matrix_type_general`.

Example: This example performs a sparse matrix vector multiplication in CSR format using additional meta data to improve performance.

Member Function/Subroutine Documentation