oneapi::mkl::sparse::trsv

oneMKL - Data Parallel C++ Developer Reference

Download PDF

ID 772045

Date 3/22/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-4673C4B8-FC2A-42DF-8651-C1F39F7AC925

View Details

oneapi::mkl::sparse::trsv

Solves a system of linear equations for a triangular sparse matrix.

Description
API
Examples

Description

The oneapi::mkl::sparse::trsv routine solves the sparse triangular system

where is a sparse triangular matrix of size rows by columns and is a matrix modifier:

The dense vectors and must be at least of length . The vector is input right hand side data and is the resulting output vector.

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::trsv() operation.

API

Syntax

Using SYCL buffers:

namespace oneapi::mkl::sparse {
    void trsv (
        sycl::queue &queue,
        oneapi::mkl::uplo uplo_val,
        oneapi::mkl::transpose opA,
        oneapi::mkl::diag diag_val,
        const DATA_TYPE alpha,
        oneapi::mkl::sparse::matrix_handle_t A,
        sycl::buffer<DATA_TYPE, 1> &x,
        sycl::buffer<DATA_TYPE, 1> &y);

    [[deprecated("Use oneapi::mkl::sparse::trsv(queue, uplo_val, opA, diag_val, /* alpha */ 1.0, ...) instead.")]]
    void trsv (
        sycl::queue &queue,
        oneapi::mkl::uplo uplo_val,
        oneapi::mkl::transpose opA,
        oneapi::mkl::diag diag_val,
        oneapi::mkl::sparse::matrix_handle_t A,
        sycl::buffer<DATA_TYPE, 1> &x,
        sycl::buffer<DATA_TYPE, 1> &y);
}

Using USM pointers:

namespace oneapi::mkl::sparse {
    sycl::event trsv(
        sycl::queue &queue,
        oneapi::mkl::uplo uplo_val,
        oneapi::mkl::transpose opA,
        oneapi::mkl::diag diag_val,
        const DATA_TYPE alpha,
        oneapi::mkl::sparse::matrix_handle_t A,
        DATA_TYPE *x,
        DATA_TYPE *y,
        const std::vector<sycl::event> &dependencies = {});

    [[deprecated("Use oneapi::mkl::sparse::trsv(queue, uplo_val, opA, diag_val, /* alpha */ 1.0, ...) instead.")]]
    sycl::event trsv(
        sycl::queue &queue,
        oneapi::mkl::uplo uplo_val,
        oneapi::mkl::transpose opA,
        oneapi::mkl::diag diag_val,
        const DATA_TYPE alpha,
        oneapi::mkl::sparse::matrix_handle_t A,
        DATA_TYPE *x,
        DATA_TYPE *y,
        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.

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.

opA

Specifies operation op() on 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.

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 (A) 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 of size at least equal to the number of columns of input matrix if opA = oneapi::mkl::transpose::nontrans and at least the number of rows of input matrix otherwise. It is the input vector x

dependencies

A vector of type std::vector<sycl::event> containing the list of events that the oneapi::mkl::sparse::trsv routine depends on.

Output Parameters

y: SYCL buffer or device-accessible USM pointer of size at least equal to the number of rows of the input matrix if opA = oneapi::mkl::transpose::nontrans and at least the number of columns of the input matrix otherwise. The solution of the triangular solve is filled into this array.

Return Values (USM Only)

sycl::event: SYCL event that can be waited upon or added as a dependency for the completion of the trsv routine.

Examples

An example of how to use oneapi::mkl::sparse::trsv with SYCL buffers or USM can be found in the oneMKL installation directory, under:

share/doc/mkl/examples/sycl/sparse_blas/source/csr_trsv.cpp

share/doc/mkl/examples/sycl/sparse_blas/source/csr_trsv_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::trsv

Description

API

Examples