rocsparse_spsm Interface Reference

• hipfort_rocsparse
• rocsparse_spsm

Public Member Functions | List of all members

hipfort_rocsparse::rocsparse_spsm Interface Reference

Sparse triangular system solve with multiple right-hand sides. More...

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_spsm_ (handle, trans_a, trans_b, alpha, mata, matb, matc, compute_type, alg, stage, buffer_size, temp_buffer)

Detailed Description

Sparse triangular system solve with multiple right-hand sides.

rocsparse_spsm solves a triangular linear system of equations defined by a sparse \(m \times m\) square matrix \(op(A)\), given in CSR or COO storage format, such that

\[ op(A) \cdot C = \alpha \cdot op(B), \]

with

\[ op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == rocsparse_operation_none} \\% A^T, & \text{if trans == rocsparse_operation_transpose} \end{array} \right. \]

and

\[ op(B) = \left\{ \begin{array}{ll} B, & \text{if trans_B == rocsparse_operation_none} \\% B^T, & \text{if trans_B == rocsparse_operation_transpose} \end{array} \right. \]

and where \(C\) is the dense solution matrix and \(B\) is the dense right-hand side matrix. Both \(B\) and \(C\) can be in row or column order.

Performing the above operation requires three stages. First, rocsparse_spsm must be called with the stage rocsparse_spsm_stage_buffer_size, which will determine the size of the required temporary storage buffer. Then allocate this buffer and call rocsparse_spsm with the stage rocsparse_spsm_stage_preprocess, which will perform analysis on the sparse matrix \(op(A)\). Finally, complete the computation by calling rocsparse_spsm with the stage rocsparse_spsm_stage_compute. The buffer size, buffer allocation, and preprocess stages only need to be called once for a given sparse triangular matrix \(op(A)\), while the computation stage can be repeatedly used with different \(B\) and \(C\) matrices.

As noted above, both \(B\) and \(C\) can be in row or column order (this includes mixing the order so that \(B\) is in row order and \(C\) in column order and vice versa). Internally, however, rocSPARSE kernels solve the system assuming the matrices \(B\) and \(C\) are in row order, as this provides the best memory access. This means that if the matrix \(C\) is not in row order and/or the matrix \(B\) is not row order (or \(B^{T}\) is not column order as this is equivalent to being in row order), then internally, memory copies and/or transposing of data might be performed to get them into the correct order (possibly using extra buffer size). After the computation is completed, additional memory copies and/or transposing of data might be performed to get them back into the user arrays. For the best performance and smallest required temporary storage buffers, use row order for the matrix \(C\) and row order for the matrix \(B\) (or column order if \(B\) is being transposed).

rocsparse_spsm supports rocsparse_indextype_i32 and rocsparse_indextype_i64 index precisions for storing the row pointer and column indices arrays of the sparse matrices. rocsparse_spsm supports the following data types for \(op(A)\), \(op(B)\), \(C\), and compute types for \(\alpha\):

Uniform Precisions:

Uniform Precisions

A / B / C / compute_type
rocsparse_datatype_f32_r
rocsparse_datatype_f64_r
rocsparse_datatype_f32_c
rocsparse_datatype_f64_c

Note

The sparse matrix formats currently supported are: rocsparse_format_coo, rocsparse_format_csr, and rocsparse_format_csc.

Only the rocsparse_spsm_stage_buffer_size stage and the rocsparse_spsm_stage_compute stage are non-blocking and executed asynchronously with respect to the host. They can return before the actual computation has finished. The rocsparse_spsm_stage_preprocess stage is blocking with respect to the host.

Currently, only trans_A == rocsparse_operation_none and trans_A == rocsparse_operation_transpose is supported. Currently, only trans_B == rocsparse_operation_none and trans_B == rocsparse_operation_transpose is supported.

Only the rocsparse_spsm_stage_buffer_size stage and the rocsparse_spsm_stage_compute stage support execution in a hipGraph context. The rocsparse_spsm_stage_preprocess stage does not support hipGraph.

This routine does not support batched computation.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	trans_A	- matrix operation type for the sparse matrix \(op(A)\).
[in]	trans_B	- matrix operation type for the dense matrix \(op(B)\).
[in]	alpha	- scalar \(\alpha\).
[in]	matA	- sparse matrix descriptor.
[in]	matB	- dense matrix descriptor.
[in,out]	matC	- dense matrix descriptor.
[in]	compute_type	- floating point precision for the SpSM computation.
[in]	alg	- SpSM algorithm for the SpSM computation.
[in]	stage	- SpSM stage for the SpSM computation.
[out]	buffer_size	- number of bytes of the temporary storage buffer.
[in]	temp_buffer	- temporary storage buffer allocated by the user. When the rocsparse_spsm_stage_buffer_size stage is passed in, the required allocation size (in bytes) is written to buffer_size, and the function returns without performing the SpSM operation.

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_handle	the library context was not initialized.
rocsparse_status_invalid_pointer	alpha, matA, matB, matC, descr, or buffer_size pointer is invalid.
rocsparse_status_not_implemented	trans_A, trans_B, compute_type, stage, or alg is currently not supported.

Example

Member Function/Subroutine Documentation

◆ rocsparse_spsm_()

integer(kind(rocsparse_status_success)) function hipfort_rocsparse::rocsparse_spsm::rocsparse_spsm_	(	type(c_ptr), value	handle,
		integer(kind(rocsparse_operation_none)), value	trans_a,
		integer(kind(rocsparse_operation_none)), value	trans_b,
		type(c_ptr), value	alpha,
		type(c_ptr), value	mata,
		type(c_ptr), value	matb,
		type(c_ptr), value	matc,
		integer(kind(rocsparse_datatype_f16_r)), value	compute_type,
		integer(kind(rocsparse_spsm_alg_default)), value	alg,
		integer(kind(rocsparse_spsm_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:

• hipfort_rocsparse.F90