rocsparse_scsrsm_solve Interface Reference

rocsparse_scsrsm_solve Interface Reference#

HIPFORT API Reference: hipfort_rocsparse::rocsparse_scsrsm_solve Interface Reference

Sparse triangular system solve using the CSR storage format. More...

Public Member Functions
integer(kind(rocsparse_status_success)) function	rocsparse_scsrsm_solve_ (handle, trans_a, trans_b, m, nrhs, nnz, alpha, descr, csr_val, csr_row_ptr, csr_col_ind, b, ldb, myinfo, policy, temp_buffer)

integer(kind(rocsparse_status_success)) function	rocsparse_scsrsm_solve_rank_0 (handle, trans_a, trans_b, m, nrhs, nnz, alpha, descr, csr_val, csr_row_ptr, csr_col_ind, b, ldb, myinfo, policy, temp_buffer)

integer(kind(rocsparse_status_success)) function	rocsparse_scsrsm_solve_rank_1 (handle, trans_a, trans_b, m, nrhs, nnz, alpha, descr, csr_val, csr_row_ptr, csr_col_ind, b, ldb, myinfo, policy, temp_buffer)

integer(kind(rocsparse_status_success)) function	rocsparse_scsrsm_solve_full_rank (handle, trans_a, trans_b, m, nrhs, nnz, alpha, descr, csr_val, csr_row_ptr, csr_col_ind, b, ldb, myinfo, policy, temp_buffer)

Detailed Description

Sparse triangular system solve using the CSR storage format.

rocsparse_csrsm_solve solves a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in CSR storage format, a column-oriented dense solution matrix \(X\) and the column-oriented dense right-hand side matrix \(B\) that is multiplied by \(\alpha\), such that

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

with

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

,

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

The solution is performed inplace, meaning that the matrix B is overwritten with the solution X after calling rocsparse_csrsm_solve. Given that the sparse matrix A is a square matrix, its size is \(m \times m\), regardless of whether A is transposed or not. The size of the column-oriented dense matrices B and X depends on the value of trans_B:

\[ op(B)/op(X) = \left\{ \begin{array}{ll} ldb \times nrhs, \text{ } ldb ≥ m, & \text{if trans_B == rocsparse_operation_none} \\% ldb \times m, \text{ } ldb ≥ nrhs, & \text{if trans_B == rocsparse_operation_transpose} \\% ldb \times m, \text{ } ldb ≥ nrhs, & \text{if trans_B == rocsparse_operation_conjugate_transpose} \end{array} \right. \]

rocsparse_csrsm_solve requires a user-allocated temporary buffer. Its size is returned by rocsparse_Xcsrsm_buffer_size(). The size of the required buffer is larger when trans_A equals rocsparse_operation_transpose or rocsparse_operation_conjugate_transpose and when trans_B is rocsparse_operation_none. The subsequent solve will also be faster when \(A\) is non-transposed and \(B\) is transposed (or conjugate transposed). For example, instead of solving:

\[ \begin{bmatrix} a_{00} & 0 & 0 \\% a_{10} & a_{11} & 0 \\% a_{20} & a_{21} & a_{22} \\% \end{bmatrix} \cdot \begin{bmatrix} x_{00} & x_{01} \\% x_{10} & x_{11} \\% x_{20} & x_{21} \\% \end{bmatrix} = \begin{bmatrix} b_{00} & b_{01} \\% b_{10} & b_{11} \\% b_{20} & b_{21} \\% \end{bmatrix} \]

Consider solving:

\[ \begin{bmatrix} a_{00} & 0 & 0 \\% a_{10} & a_{11} & 0 \\% a_{20} & a_{21} & a_{22} \end{bmatrix} \cdot \begin{bmatrix} x_{00} & x_{10} & x_{20} \\% x_{01} & x_{11} & x_{21} \end{bmatrix}^{T} = \begin{bmatrix} b_{00} & b_{10} & b_{20} \\% b_{01} & b_{11} & b_{21} \end{bmatrix}^{T} \]

After the temporary storage buffer has been allocated, analysis of the metadata is required. It can be obtained by rocsparse_Xcsrsm_analysis().

Solving a triangular system involves division by the diagonal elements. This means that if the sparse matrix is missing the diagonal entry (referred to as a structural zero) or the diagonal entry is zero (referred to as a numerical zero), then a division by zero would occur. rocsparse_csrsm_solve tracks the location of the first zero pivot (either numerical or structural zero). The zero pivot status can be checked by calling rocsparse_csrsm_zero_pivot (). If rocsparse_csrsm_zero_pivot () returns rocsparse_status_success, then no zero pivot was found and therefore the matrix does not have a structural or numerical zero.

The user can specify that the sparse matrix should be interpreted as having ones on the diagonal by setting the diagonal type on the descriptor descr to rocsparse_diag_type_unit using rocsparse_set_mat_diag_type. If rocsparse_diag_type == rocsparse_diag_type_unit, no zero pivot will be reported, even if \(A_{j,j} = 0\) for some \(j\).

The sparse CSR matrix passed to rocsparse_csrsm_solve does not actually have to be a triangular matrix. Instead, the triangular upper or lower part of the sparse matrix is solved based on the rocsparse_fill_mode setting on the descriptor descr. If the fill mode is set to rocsparse_fill_mode_lower, then the lower triangular matrix is solved. If the fill mode is set to rocsparse_fill_mode_upper, then the upper triangular matrix is solved.

Note: The sparse CSR matrix has to be sorted. This can be achieved by calling rocsparse_csrsort().; This function is non-blocking and executed asynchronously with respect to the host. It can return before the actual computation has finished.; Currently, only trans_A != rocsparse_operation_conjugate_transpose and trans_B != rocsparse_operation_conjugate_transpose is supported.; This routine supports execution in a hipGraph context.

Parameters

[in]	handle	- handle to the rocSPARSE library context queue.
[in]	trans_A	- matrix A operation type.
[in]	trans_B	- matrix B operation type.
[in]	m	- number of rows of the sparse CSR matrix A.
[in]	nrhs	- number of columns of the column-oriented dense matrix op(B).
[in]	nnz	- number of non-zero entries of the sparse CSR matrix A.
[in]	alpha	- scalar \(\alpha\).
[in]	descr	- descriptor of the sparse CSR matrix A.
[in]	csr_val	- array of `nnz` elements of the sparse CSR matrix A.
[in]	csr_row_ptr	- array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.
[in]	csr_col_ind	- array of `nnz` elements containing the column indices of the sparse CSR matrix A.
[in,out]	B	- column-oriented dense matrix of dimension `m` \(\times\) `nrhs` elements of the rhs matrix B.
[in]	ldb	- leading dimension of rhs matrix B.
[in]	myInfo	- structure that holds the information collected during the analysis step.
[in]	policy	- `rocsparse_solve_policy_auto`.
[in]	temp_buffer	- temporary storage buffer allocated by the user.

Return values

rocsparse_status_success	the operation completed successfully.
rocsparse_status_invalid_handle	the library context was not initialized.
rocsparse_status_invalid_size	`m`, `nrhs`, or `nnz` is invalid.
rocsparse_status_invalid_pointer	`alpha`, `descr`, `csr_val`, `csr_row_ptr`, `csr_col_ind`, `B`, `info`, or `temp_buffer` pointer is invalid.
rocsparse_status_internal_error	an internal error occurred.
rocsparse_status_not_implemented	`trans_A` == `rocsparse_operation_conjugate_transpose`, `trans_B` == `rocsparse_operation_conjugate_transpose`, or `rocsparse_matrix_type` != `rocsparse_matrix_type_general`.

Example: Consider the lower triangular \(m \times m\) matrix \(L\), stored in CSR storage format with unit diagonal. The following example solves \(L \cdot X = B\).

Member Function/Subroutine Documentation