oneapi::mkl::sparse::trsm

oneMKL - Data Parallel C++ Developer Reference

Download PDF

ID 772045

Date 6/24/2024

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-29DD150A-DEAA-4DC8-B372-78C4C837EC3C

View Details

oneapi::mkl::sparse::trsm

Solves a system of linear equations with multiple right-hand sides (RHS) for a triangular sparse matrix.

Description
API
Examples

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.

NOTE:

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

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

oneMKL - Data Parallel C++ Developer Reference

oneapi::mkl::sparse::trsm

Description

API

Examples