rocsparse_sptrsm Interface Reference

rocsparse_sptrsm Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_sptrsm Interface Reference

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

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_sptrsm_ (handle, sptrsm_descr, a, x, y, sptrsm_stage, buffer_size_in_bytes, buffer, p_error)

Detailed Description

Sparse triangular system solve with multiple right-hand sides.

rocsparse_sptrsm 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 Y = \alpha \cdot op(X), \]

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(X) = \left\{ \begin{array}{ll} X, & \text{if trans_B == rocsparse_operation_none} \\% X^T, & \text{if trans_B == rocsparse_operation_transpose} \end{array} \right. \]

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

Performing the above operation requires two stages, the stage rocsparse_sptrsm_stage_analysis and the stage rocsparse_sptrsm_stage_compute. The stage rocsparse_sptrsm_stage_analysis is required to perform the stage rocsparse_sptrsm_stage_compute and only needs to be called once for a given sparse matrix \(op(A)\), while the stage rocsparse_sptrsm_stage_compute can be repeatedly used with different \(X\) and \(Y\) matrices.

As noted above, both \(X\) and \(Y\) can be in row or column order (this includes mixing the order so that \(X\) is in row order and \(Y\) in column order and vice versa). Internally, however, rocSPARSE kernels solve the system assuming the matrices \(X\) and \(Y\) are in row order, as this provides the best memory access. This means that if the matrix \(Y\) is not in row order and/or the matrix \(X\) is not in row order (or \(X^{T}\) is not in 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 \(Y\) and row order for the matrix \(X\) (or column order if \(X\) is being transposed).

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

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

Note: The sparse matrix formats currently supported are: rocsparse_format_coo, rocsparse_format_csr, and rocsparse_format_csc.; Only the rocsparse_sptrsm_stage_compute stage is non-blocking and executed asynchronously with respect to the host. It can return before the actual computation has finished. The rocsparse_sptrsm_stage_analysis stage is blocking with respect to the host.; Currently, only trans_A == rocsparse_operation_none and trans_A == rocsparse_operation_transpose are supported. Currently, only trans_X == rocsparse_operation_none and trans_X == rocsparse_operation_transpose are supported.; Only the stage rocsparse_sptrsm_stage_compute supports execution in a hipGraph context. The rocsparse_sptrsm_stage_analysis stage does not support hipGraph.; This routine does not support batched execution.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	sptrsm_descr	- SpTrSM routine descriptor.
[in]	A	- sparse matrix descriptor.
[in]	X	- dense matrix descriptor.
[in,out]	Y	- dense matrix descriptor.
[in]	sptrsm_stage	- SpTrSM stage for the SpTrSM computation.
[out]	buffer_size_in_bytes	- number of bytes of the temporary storage buffer.
[in]	buffer	- temporary storage buffer allocated by the user.
[out]	p_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 was not initialized.
rocsparse_status_invalid_pointer	`A`, X, `Y`, `sptrsm_descr`, or `buffer_size` pointer is invalid.
rocsparse_status_not_implemented	the configuration of the descriptor `sptrsm_descr` is currently not supported.

Example

Member Function/Subroutine Documentation