hipsparsesgtsvinterleavedbatch Interface Reference

hipsparsesgtsvinterleavedbatch Interface Reference#

HIPFORT API Reference: hipfort_hipsparse::hipsparsesgtsvinterleavedbatch Interface Reference

Interleaved batch tridiagonal solver. More...

Public Member Functions
integer(kind(hipsparse_status_success)) function	hipsparsesgtsvinterleavedbatch_ (handle, algo, m, dl, d, du, x, batchcount, pbuffer)

Detailed Description

Interleaved batch tridiagonal solver.

hipsparseXgtsvInterleavedBatch solves a batched tridiagonal linear system

\[ T^{i}*x^{i} = x^{i} \]

where for each batch \(i=0\ldots\) batchCount, \(T^{i}\) is a sparse tridiagonal matrix and \(x^{i}\) is a dense right-hand side vector. All of the tridiagonal matrices, \(T^{i}\), are packed in an interleaved fashion into three vectors: dl for the lower diagonals, d for the main diagonals, and du for the upper diagonals. See below for a description of the interleaved memory pattern.

Solving the batched tridiagonal system involves two steps. First, the user calls hipsparseSgtsvInterleavedBatch_bufferSizeExt "hipsparseXgtsvInterleavedBatch_bufferSizeExt()" to determine the size of the required temporary storage buffer. Once determined, the user allocates this buffer and passes it to hipsparseSgtsvInterleavedBatch "hipsparseXgtsvInterleavedBatch()" to perform the actual solve. The \(x^{i}\) vectors, which initially stores the right-hand side values, are overwritten with the solution after the call to hipsparseSgtsvInterleavedBatch "hipsparseXgtsvInterleavedBatch()".

The user can specify different algorithms for hipsparseXgtsvInterleavedBatch to use. Options are Thomas ( algo=0 ), LU ( algo=1 ), or QR ( algo=2 ).

Unlike the strided batch routines, which write each batch matrix one after the other in memory, the interleaved routines write the batch matrices such that each element from each matrix is written consecutively one after the other. For example, consider the following batch matrices:

\[ \begin{bmatrix} t^{0}_{00} & t^{0}_{01} & 0 \\% t^{0}_{10} & t^{0}_{11} & t^{0}_{12} \\% 0 & t^{0}_{21} & t^{0}_{22} \end{bmatrix} \begin{bmatrix} t^{1}_{00} & t^{1}_{01} & 0 \\% t^{1}_{10} & t^{1}_{11} & t^{1}_{12} \\% 0 & t^{1}_{21} & t^{1}_{22} \end{bmatrix} \begin{bmatrix} t^{2}_{00} & t^{2}_{01} & 0 \\% t^{2}_{10} & t^{2}_{11} & t^{2}_{12} \\% 0 & t^{2}_{21} & t^{2}_{22} \end{bmatrix} \]

In interleaved format, the upper, lower, and diagonal arrays would look like:

\[ \begin{align} \text{lower} &= \begin{bmatrix} 0 & 0 & 0 & t^{0}_{10} & t^{1}_{10} & t^{1}_{10} & t^{0}_{21} & t^{1}_{21} & t^{2}_{21} \end{bmatrix} \\% \text{diagonal} &= \begin{bmatrix} t^{0}_{00} & t^{1}_{00} & t^{2}_{00} & t^{0}_{11} & t^{1}_{11} & t^{2}_{11} & t^{0}_{22} & t^{1}_{22} & t^{2}_{22} \end{bmatrix} \\% \text{upper} &= \begin{bmatrix} t^{0}_{01} & t^{1}_{01} & t^{2}_{01} & t^{0}_{12} & t^{1}_{12} & t^{2}_{12} & 0 & 0 & 0 \end{bmatrix} \\% \end{align} \]

For the lower array, the first batchCount entries are zero, and for the upper array, the last batchCount entries are zero.

Note: This function is non-blocking and executed asynchronously with respect to the host. It can return before the actual computation has finished.

Parameters

[in]	handle	- handle to the hipSPARSE library context queue.
[in]	algo	- Algorithm to use when solving tridiagonal systems. Options are Thomas ( `algo=0` ), LU ( `algo=1` ), or QR ( `algo=2` ). The Thomas algorithm is the fastest but is not stable, while LU and QR are slower but are stable.
[in]	m	- size of the tridiagonal linear system.
[in,out]	dl	- lower diagonal of the tridiagonal system. The first element of the lower diagonal must be zero.
[in,out]	d	- main diagonal of the tridiagonal system.
[in,out]	du	- upper diagonal of the tridiagonal system. The last element of the upper diagonal must be zero.
[in,out]	x	- Dense array of right-hand sides with dimension `batchCount` by `m`.
[in]	batchCount	- The number of systems to solve.
[in]	pBuffer	- temporary storage buffer allocated by the user.

Return values

HIPSPARSE_STATUS_SUCCESS	the operation completed successfully.
HIPSPARSE_STATUS_INVALID_VALUE	`handle`, `m`, `batchCount`, `dl`, `d`, `du`, `x`, or `pBuffer` pointer is invalid.
HIPSPARSE_STATUS_INTERNAL_ERROR	an internal error occurred.

Member Function/Subroutine Documentation