hipsparsesbsrsm2_solve Interface Reference

hipsparsesbsrsm2_solve Interface Reference#

HIPFORT API Reference: hipfort_hipsparse::hipsparsesbsrsm2_solve Interface Reference

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

Public Member Functions
integer(kind(hipsparse_status_success)) function	hipsparsesbsrsm2_solve_ (handle, dira, transa, transx, mb, nrhs, nnzb, alpha, descra, bsrsortedvala, bsrsortedrowptra, bsrsortedcolinda, blockdim, myinfo, b, ldb, x, ldx, policy, pbuffer)

integer(kind(hipsparse_status_success)) function	hipsparsesbsrsm2_solve_rank_0 (handle, dira, transa, transx, mb, nrhs, nnzb, alpha, descra, bsrsortedvala, bsrsortedrowptra, bsrsortedcolinda, blockdim, myinfo, b, ldb, x, ldx, policy, pbuffer)

integer(kind(hipsparse_status_success)) function	hipsparsesbsrsm2_solve_rank_1 (handle, dira, transa, transx, mb, nrhs, nnzb, alpha, descra, bsrsortedvala, bsrsortedrowptra, bsrsortedcolinda, blockdim, myinfo, b, ldb, x, ldx, policy, pbuffer)

integer(kind(hipsparse_status_success)) function	hipsparsesbsrsm2_solve_full_rank (handle, dira, transa, transx, mb, nrhs, nnzb, alpha, descra, bsrsortedvala, bsrsortedrowptra, bsrsortedcolinda, blockdim, myinfo, b, ldb, x, ldx, policy, pbuffer)

Detailed Description

Sparse triangular system solve using the BSR storage format.

hipsparseXbsrsm2_solve solves a sparse triangular linear system of a sparse \(m \times m\) matrix, defined in BSR 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 transA == HIPSPARSE_OPERATION_NON_TRANSPOSE} \\% A^T, & \text{if transA == HIPSPARSE_OPERATION_TRANSPOSE} \\% A^H, & \text{if transA == HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE} \end{array} \right. \]

,

\[ op(B) = \left\{ \begin{array}{ll} B, & \text{if transX == HIPSPARSE_OPERATION_NON_TRANSPOSE} \\% B^T, & \text{if transX == HIPSPARSE_OPERATION_TRANSPOSE} \\% B^H, & \text{if transX == HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE} \end{array} \right. \]

and

\[ op(X) = \left\{ \begin{array}{ll} X, & \text{if transX == HIPSPARSE_OPERATION_NON_TRANSPOSE} \\% X^T, & \text{if transX == HIPSPARSE_OPERATION_TRANSPOSE} \\% X^H, & \text{if transX == HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE} \end{array} \right. \]

and where \(m = blockDim \times mb\).

Note that, as indicated above, the operation type of both \(op(B)\) and \(op(X)\) is specified by the transX parameter and that the operation type of \(B\) and \(X\) must match. For example, if \(op(B)=B\), then \(op(X)=X\). Likewise, if \(op(B)=B^T\), then \(op(X)=X^T\).

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 transX:

\[ op(B) = \left\{ \begin{array}{ll} ldb \times nrhs, \text{ } ldb ≥ m, & \text{if transX == HIPSPARSE_OPERATION_NON_TRANSPOSE} \\% ldb \times m, \text{ } ldb ≥ nrhs, & \text{if transX == HIPSPARSE_OPERATION_TRANSPOSE} \\% ldb \times m, \text{ } ldb ≥ nrhs, & \text{if transX == HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE} \end{array} \right. \]

and

\[ op(X) = \left\{ \begin{array}{ll} ldb \times nrhs, \text{ } ldb ≥ m, & \text{if transX == HIPSPARSE_OPERATION_NON_TRANSPOSE} \\% ldb \times m, \text{ } ldb ≥ nrhs, & \text{if transX == HIPSPARSE_OPERATION_TRANSPOSE} \\% ldb \times m, \text{ } ldb ≥ nrhs, & \text{if transX == HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE} \end{array} \right. \]

hipsparseXbsrsm2_solve requires a user-allocated temporary buffer. Its size is returned by hipsparseSbsrsm2_bufferSize "hipsparseXbsrsm2_bufferSize()". The size of the required buffer is larger when transA equals HIPSPARSE_OPERATION_TRANSPOSE or HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE and when transX is HIPSPARSE_OPERATION_NON_TRANSPOSE. The subsequent solve will also be faster when \(A\) is non-transposed and \(B\) is transposed (or conjugate transposed). For example, instead of solving:

\[ \left[ \begin{array}{c | c} \begin{array}{c c} a_{00} & a_{01} \\% a_{10} & a_{11} \end{array} & \begin{array}{c c} 0 & 0 \\% 0 & 0 \end{array} \\% \hline \begin{array}{c c} a_{20} & a_{21} \\% a_{30} & a_{31} \end{array} & \begin{array}{c c} a_{22} & a_{23} \\% a_{32} & a_{33} \end{array} \\% \end{array} \right] \cdot \begin{bmatrix} x_{00} & x_{01} \\% x_{10} & x_{11} \\% x_{20} & x_{21} \\% x_{30} & x_{31} \\% \end{bmatrix} = \begin{bmatrix} b_{00} & b_{01} \\% b_{10} & b_{11} \\% b_{20} & b_{21} \\% b_{30} & b_{31} \\% \end{bmatrix} \]

Consider solving:

\[ \left[ \begin{array}{c | c} \begin{array}{c c} a_{00} & a_{01} \\% a_{10} & a_{11} \end{array} & \begin{array}{c c} 0 & 0 \\% 0 & 0 \end{array} \\% \hline \begin{array}{c c} a_{20} & a_{21} \\% a_{30} & a_{31} \end{array} & \begin{array}{c c} a_{22} & a_{23} \\% a_{32} & a_{33} \end{array} \\% \end{array} \right] \cdot \begin{bmatrix} x_{00} & x_{10} & x_{20} & x_{30} \\% x_{01} & x_{11} & x_{21} & x_{31} \end{bmatrix}^{T} = \begin{bmatrix} b_{00} & b_{10} & b_{20} & b_{30} \\% b_{01} & b_{11} & b_{21} & b_{31} \end{bmatrix}^{T} \]

After the temporary storage buffer has been allocated, analysis meta data is required. It can be obtained by hipsparseSbsrsm2_analysis "hipsparseXbsrsm2_analysis()". The triangular solve is completed by calling hipsparseXbsrsm2_solve, and after all solves are performed, the temporary storage buffer allocated by the user can be freed.

Solving a triangular system involves inverting the diagonal blocks. This means that if the sparse matrix is missing the diagonal block (referred to as a structural zero) or the diagonal block is not invertible (referred to as a numerical zero), then a solution is not possible. hipsparseXbsrsm2_solve tracks the location of the first zero pivot (either numerical or structural zero). The zero pivot status can be checked by calling hipsparseXbsrsm2_zeroPivot (). If hipsparseXbsrsm2_zeroPivot () returns HIPSPARSE_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 identity blocks on the diagonal by setting the diagonal type on the descriptor descrA to HIPSPARSE_DIAG_TYPE_UNIT using hipsparseSetMatDiagType. If hipsparseDiagType_t == HIPSPARSE_DIAG_TYPE_UNIT, no zero pivot will be reported, even if the diagonal block \(A_{j,j}\) for some \(j\) is not invertible.

The sparse CSR matrix passed to hipsparseXbsrsm2_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 hipsparseFillMode_t set on the descriptor descrA. If the fill mode is set to HIPSPARSE_FILL_MODE_LOWER, then the lower triangular matrix is solved. If the fill mode is set to HIPSPARSE_FILL_MODE_UPPER, then the upper triangular matrix is solved.

Note: The sparse BSR matrix has to be sorted.; Operation type of B and X must match if \(op(B)=B, op(X)=X\).; This function is non-blocking and executed asynchronously with respect to the host. It can return before the actual computation has finished.; Currently, only transA != HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE and transX != HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE is supported.

Parameters

[in]	handle	- handle to the hipSPARSE library context queue.
[in]	dirA	- matrix storage of BSR blocks.
[in]	transA	- matrix \(A\) operation type.
[in]	transX	- matrix \(X\) operation type.
[in]	mb	- number of block rows of the sparse BSR matrix \(A\).
[in]	nrhs	- number of columns of the dense matrix \(op(X)\).
[in]	nnzb	- number of non-zero blocks of the sparse BSR matrix \(A\).
[in]	alpha	- scalar \(\alpha\).
[in]	descrA	- descriptor of the sparse BSR matrix \(A\).
[in]	bsrSortedValA	- array of `nnzb` blocks of the sparse BSR matrix.
[in]	bsrSortedRowPtrA	- array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.
[in]	bsrSortedColIndA	- array of `nnzb` containing the block column indices of the sparse BSR matrix.
[in]	blockDim	- block dimension of the sparse BSR matrix.
[in]	myInfo	- structure that holds the information collected during the analysis step.
[in]	B	- rhs matrix B with leading dimension `ldb`.
[in]	ldb	- leading dimension of rhs matrix \(B\).
[out]	X	- solution matrix X with leading dimension `ldx`.
[in]	ldx	- leading dimension of solution matrix \(X\).
[in]	policy	- `HIPSPARSE_SOLVE_POLICY_NO_LEVEL` or `HIPSPARSE_SOLVE_POLICY_USE_LEVEL`.
[in]	pBuffer	- temporary storage buffer allocated by the user.

Return values

HIPSPARSE_STATUS_SUCCESS	the operation completed successfully.
HIPSPARSE_STATUS_INVALID_VALUE	`handle`, `mb`, `nrhs`, `nnzb`, `blockDim`, `alpha`, `descrA`, `bsrSortedValA`, `bsrSortedRowPtrA`, `bsrSortedColIndA`, `B`, `X` `info`, or `pBuffer` is invalid.
HIPSPARSE_STATUS_INTERNAL_ERROR	an internal error occurred.
HIPSPARSE_STATUS_NOT_SUPPORTED	`transA` == `HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE`, `transX` == `HIPSPARSE_OPERATION_CONJUGATE_TRANSPOSE` or `hipsparseMatrixType_t` != `HIPSPARSE_MATRIX_TYPE_GENERAL`.

Member Function/Subroutine Documentation