Visible to Intel only — GUID: GUID-8A15EEB5-D350-4EBC-9AEE-671669F15797
Visible to Intel only — GUID: GUID-8A15EEB5-D350-4EBC-9AEE-671669F15797
oneapi::mkl::sparse::trsm
Solves a system of linear equations with multiple right-hand sides (RHS) for a triangular sparse matrix.
Description
The oneapi::mkl::sparse::trsm routine solves the sparse triangular system
where is a sparse triangular matrix of size rows by columns and is a matrix modifier:
The dense matrices and are stored with row-major or column-major layout and have an appropriate number of rows and columns number of columns for computing sparse::trsm() operation, that is, and are of dimensions rows by columns. The matrix is input right hand side data and is the resulting output matrix.
For a given matrix decomposition into lower, diagonal, and upper parts , the triangular solve with one of oneapi::mkl::uplo::lower or oneapi::mkl::uplo::upper selected will perform the appropriate forward or backward substitution using respectively or for oneapi::mkl::diag::nonunit or, for oneapi::mkl::diag::unit, will perform the appropriate forward or backward substitution for or where is the identity matrix.
- Refer to Sparse BLAS Supported Data and Integer Types for a list of supported <DATA_TYPE> and <INT_TYPE> data and integer types, and refer to Error Handling for a detailed description of the possible exceptions thrown.
While it can make sense to pass in the same array for both RHS () and solution () in order to update the RHS in-place, we currently do not support in-place sparse::trsm() operation.
API
Syntax
Using SYCL buffers:
namespace oneapi::mkl::sparse {
void trsm (
sycl::queue &queue,
oneapi::mkl::layout layout_val,
oneapi::mkl::transpose opA,
oneapi::mkl::transpose opX,
oneapi::mkl::uplo uplo_val,
oneapi::mkl::diag diag_val,
const DATA_TYPE alpha,
oneapi::mkl::sparse::matrix_handle_t A,
sycl::buffer<DATA_TYPE, 1> &X,
const std::int64_t columns,
const std::int64_t ldx,
sycl::buffer<DATA_TYPE, 1> &Y,
const std::int64_t ldy);
}
Using USM pointers:
namespace oneapi::mkl::sparse {
sycl::event trsm(
sycl::queue &queue,
oneapi::mkl::layout layout_val,
oneapi::mkl::transpose opA,
oneapi::mkl::transpose opX,
oneapi::mkl::uplo uplo_val,
oneapi::mkl::diag diag_val,
const DATA_TYPE alpha,
oneapi::mkl::sparse::matrix_handle_t A,
const DATA_TYPE *X,
const std::int64_t columns,
const std::int64_t ldx,
DATA_TYPE *Y,
const std::int64_t ldy,
const std::vector<sycl::event> &dependencies = {});
}
Include Files
oneapi/mkl/spblas.hpp
Input Parameters
- queue
-
Specifies the SYCL command queue that will be used for SYCL kernels execution.
- layout_val
-
Specifies the storage scheme in memory for the dense matrices. Note that this layout applies to both X and Y dense matrices.
- opA
-
Specifies operation op() on the sparse input matrix, .
oneapi::mkl::transpose::nontrans
Non-transpose, .
oneapi::mkl::transpose::trans
Transpose, .
oneapi::mkl::transpose::conjtrans
Conjugate transpose, .
NOTE:Currently, the only supported case for operation is oneapi::mkl::transpose::nontrans. - opX
-
Specifies operation op() on the dense input matrix, .
oneapi::mkl::transpose::nontrans
Non-transpose, .
oneapi::mkl::transpose::trans
Transpose, .
oneapi::mkl::transpose::conjtrans
Conjugate transpose, .
NOTE:Currently, the only supported case for operation is oneapi::mkl::transpose::nontrans. - uplo_val
-
Specifies which part of the matrix is to be processed.
oneapi::mkl::uplo::lower
The lower triangular matrix part is processed.
oneapi::mkl::uplo::upper
The upper triangular matrix part is processed.
- diag_val
-
Specifies whether the diagonal used for computations is unit or based on provided matrix data.
oneapi::mkl::diag::nonunit
Diagonal elements are used as provided in the sparse matrix.
oneapi::mkl::diag::unit
The value of one is substituted for the diagonal elements in the triangular solve algorithm.
NOTE:If oneapi::mkl::diag::nonunit is selected, all diagonal values must be present in the sparse matrix sparsity profile and must not be zero valued. This is not necessary for the oneapi::mkl::diag::unit case. An exception of type onemkl::invalid_value() will be thrown in case this is violated. - alpha
-
Specifies the scalar, .
- A
-
Handle to object containing sparse matrix () and other internal data. Created using one of the oneapi::mkl::sparse::set_<sparse_matrix_type>_data routines.
NOTE:The supported cases for <sparse_matrix_type> are csr on CPU and GPU devices, and coo only on CPU device. - X
-
SYCL buffer or device-accessible USM pointer for the right hand side dense matrix. is of dimension by columns with a leading dimension stride of ldx based on the provided layout of X.
For example, if , i.e opX == oneapi::mkl::transpose::nontrans, we would have
layout=oneapi::mkl::layout::col-major
layout=oneapi::mkl::layout::row-major
nrows of
ldx
m
ncols of
columns
ldx
- columns
-
Number of columns of and matrices.
- ldx
-
Specifies the leading dimension of matrix X. Must be positive, and larger than or equal to the actual usable row (for layout_val=oneapi::mkl::layout::row_major) or column (for layout_val=oneapi::mkl::layout::col_major) dimension of X.
- ldy
-
Specifies the leading dimension of matrix Y. Must be positive, and at least columns if layout_val=oneapi::mkl::layout::row-major or at least number of rows in if layout_val=oneapi::mkl::layout::col-major.
- dependencies
-
A vector of type std::vector<sycl::event> containing the list of events that the oneapi::mkl::sparse::trsm routine depends on.
Output Parameters
- Y
-
SYCL buffer or device-accessible USM pointer for the dense matrix solution of the triangular solve. is of dimension by columns with a leading dimension stride of ldy based on the provided layout of Y.
layout=oneapi::mkl::layout::col-major
layout=oneapi::mkl::layout::row-major
nrows of
ldy
m (number of rows in and )
ncols of
columns
ldy
Return Values (USM Only)
- sycl::event
-
SYCL event that can be waited upon or added as a dependency for the completion of the trsm routine.
Examples
An example of how to use oneapi::mkl::sparse::trsm with SYCL buffers or USM can be found in the oneMKL installation directory, under:
share/doc/mkl/examples/sycl/sparse_blas/source/csr_trsm.cpp
share/doc/mkl/examples/sycl/sparse_blas/source/csr_trsm_usm.cpp